Navigation

MongoDB Service Read Rule

Read Rule

MongoDB Stitch applies the MongoDB Service read rules to filter documents for read and write operations. The read rules are in addition to any query predicates issued in the read and write operations.

If a rule determines that a field is readable:

  • Read and write operations can query on the field (and its embedded fields, if any).
  • Read operations can include the field (and its embedded fields, if any) in their results.

If a rule determines that a field is not readable:

  • Read and write operations cannot query on the field (or its embedded fields, if any); that is, query predicates on that field (or its embedded fields, if any) will not match any documents for read or write operations.
  • Read operations will omit the field (and its embedded fields, if any) in their results.

MongoDB Authorization

MongoDB Stitch rules do not override the read and write access (i.e. authorization) that may have been set up separately in MongoDB. That is, MongoDB Stitch rules determine whether the fields are readable or writable; not whether the client has authorization to read or write to a particular database or collection.

Default Read Rules

To view the read rule, click on the Top-Level Document in the Field Rules view.

By default, the collection has the following read rule for the top-level document:

{
  "owner_id": "%%user.id"
}

With this rule, read and write operations can access all fields in a document if the document contains an owner_id field whose value equals the user ID (%%user.id) of the client issuing the read. If the owner_id field in the document does not equal the client user id, no field in the document is readable.

Rules Syntax

You can specify rules as JSON documents. MongoDB query expression operators (with the exception of the %text and the geospatial operators) are available for rule expressions.

{
  <field1>: <value1|expression1>,
  <field2>: <value2|expression2>,
  ...
}

To access elements of an array or access fields in an embedded document, use dot notation. For list of MongoDB query operators available, see Query Selectors.

You can also preface the <field> name with an expansion (%%<keyword>):

{
  "<expansion>.<field1>":  <value1|expression1>,
  "<expansion>.<field2>":  <value2|expression2>,
  ...
}

Tip

  • When a field is referenced at the top-level of a document rule, a field name <field> without any expansion is shorthand for %%root.<field>. In a read rule, %%root refers to the document being read.

    However , if a compound rule includes nested expressions, you must explictly include the expansion for a field in the nested expressions.

  • When specifying a rule at a field level, you can use %%this to refer to the field; e.g., { "%%this": <value> }.

    • In a read rule for a document, %%this refers to the document being read.
    • In a read rule for a field, %%this refers to the field.

The following table lists some syntax examples:

Syntax Examples Description
{} An empty JSON document evaluates to true. If specified as a document rule, all documents satisfy this read rule. If specified as a field rule, the field is always readable.
{ "%%true": true } The expression always evaluates to true as the value of the expansion %%true equals the boolean true. If specified as a document rule, all documents satisfy this read rule. If specified as a field rule, the field is always readable.
{ "%%true": false } The expression always evaluates to false as the reserved expansion value %%true does not equal the boolean false. If specified as a document rule, no document satisfies this read rule. If specified as a field rule, the field is never readable.
{
  "<field1>": <value1|exp1>,
  "<field2>": <value2|exp2>,
  ...
}

or

{
   "<expansion1>.<field1>": <value1|exp1>,
   "<expansion2>.<field2>": <value2|exp2>,
   ...
}
The compound document/field rule evaluates to true if all conditions are satisfied.
{
  "%or": [
     { "<expansion>.<field1>": <value1|exp1> },
     { "<expansion>.<field2>": <value2|exp2> },
     ...
  ]
}

The compound document/field rule evaluates to true if any of the specified conditions is satisfied.

Note

You must include expansions %%<keyword> to reference fields in the nested rule expressions.

Read Rule Examples

Important

When applying rules, the rules at the highest level applies. For a rule for a field to take effect, no rules must exist at a higher level. For details, see Rules Interaction.

The rule examples below apply to read operations on the collection reports with the following documents:

{
   "_id" : 1,
   "title" : "Pies",
   "about" : { "subject" : "pies", "counts" : { "pages" : 5, "words" : 100 } },
   "classification" : "Public",
   "views" : 100
}
{
   "_id" : 2,
   "title" : "Pastries Part 1",
   "about" : { "subject" : "puff pastries", "counts" : { "pages" : 50, "words" : 5000 } },
   "classification" : "Public",
   "views" : 20
}
{
  "_id" : 3,
  "title" : "Cakes",
  "about" : { "subject" : "cupcakes", "counts" : { "pages" : 1, "words" : 200 } },
  "classification" : "Internal",
  "views" : 50
 }

The following table describes the effects of the read rule when either the rule is specified for the document or the rule is specified for the field about.counts. The summary table is followed by specific examples.

Rule Description
{}

If the rule is specified for the document, any and all fields are readable for all documents if Allow All Other Fields is enabled for the document. Otherwise, only listed fields are readable. For specific examples, see All Fields Are Readable and All Listed Fields Are Readable.

If the rule is specified for the field about.counts, the field and its embedded fields pages and words are readable for all documents. Other fields are determined by Allow All Other Fields setting. For this rule to take effect, rules cannot exist at the document level or for the about field. You can specify a separate rule for the title field, about.subject field, and the type field. For specific example, see Specific Embedded Fields Are Readable.

{ "%%root.about.subject": "pies" }

If the rule is specified for the document, any and all fields are readable for documents that match this condition if Allow All Other Fields is enabled . Otherwise, only listed fields are readable for matching documents. For a specific example, see All Fields Are Readable for Documents Matching Rule Condition.

If the rule is specified for the field about.counts, the field and its embedded fields pages and words are readable for documents that match this condition. Other fields are determined by Allow All Other Fields setting. For this rule to take effect, rules cannot exist at the document level or for the about field. You can, however, specify a separate rule for the title field. For a specific example, see Specify Different Read Rules for Fields.

All Fields Are Readable

This examples sets up MongoDB Stitch rules to ensure that all fields are available for reads.

To make all fields available for reads without condition:

  • Specify an empty JSON document {} as the read rule at document level.
  • Set Allow All Other Fields to enabled.

Given this rule, if you issue the following StitchClient read operation:

db.getCollection("reports").find( {"classification":"Public"} );

The operation returns all fields:

{
   "_id":1.0,
   "title":"Pies",
   "about":{"subject":"pies","counts":{ "pages": 5.0, "words":100.0 }},
   "classification":"Public",
   "views": 100.0
}
{

   "_id":2.0,
   "title":"Pastries Part 1",
   "about":{"subject":"puff pastries","counts":{ "pages":50.0, "words":5000.0 }},
   "classification":"Public",
   "views": 20.0
}

All Listed Fields Are Readable

This examples sets up MongoDB Stitch rules to ensure that only title, classification, and views fields are available for reads.

To make all listed fields readable and disallow unlisted fields for all documents:

  • Specify an empty JSON document {} as the read rule at document level.
  • Add the fields to which you wish to apply the rule; in this example, the title, classification, and views fields. Specify Any for the field type. Do not specify any rules for the fields.
  • Set Allow All Other Fields to disabled.

Given this rule, if you issue the following StitchClient read operation:

db.getCollection("reports").find( {"classification":"Public"} );

The operation returns only the listed fields:

{"title":"Pies","classification":"Public","views":100.0}
{"title":"Pastries Part 1","classification":"Public","views":20.0}

Alternatively, instead of specifying a rule at the document level, you can specify individual field level read rules for the title, classification, and views fields.

All Fields Are Readable for Documents Matching Rule Condition

This example sets up MongoDB Stitch rules to ensure that if views field is less than or equal to 50, all fields are readable.

To make all fields available under this condition:

  • Specify document { "views": { "%lte": 50 } } as the read rule at document level.
  • Set Allow All Other Fields to enabled.

Given this rule, if you issue the following StitchClient read operation:

db.getCollection("reports").find( {"classification":"Public"} )

The operation returns all fields for which the views field is less than or equal to 50 and the classification field is equal to "Public".

{
   "_id":2.0,
   "title":"Pastries Part 1",
   "classification":"Public",
   "views":20.0,
   "about":{"subject":"puff pastries","counts":{"pages":50.0,"words":5000.0}}
}

Specific Embedded Fields Are Readable

This example sets up MongoDB Stitch rules to make only about.counts and its embedded fields readable. The about field itself and its other embedded fields are not readable.

To be able to read specific fields in documents,

  • Ensure that no read rule exists at the document level.

  • Set Allow All Other Fields to disabled.

  • Specify the fields to which you wish to apply the rule. If the field is an embedded document, set the Field Type to Object. For this example, add the field about and its embedded fields:

    Field Field Type Read Rule
    about Object Do not specify a rule.
    about.subject Any Do not specify a rule.
    about.counts Object {}
  • In the about.counts document, set Allow All Other Fields to enabled. Do not specify a rule. Alternatively, you can explicitly add about.counts.pages and about.counts.words in the about.counts document. For more information, see Fields Specification.

Given this rule at the about.counts, if you issue the following StitchClient read operation:

db.getCollection("reports").find({})

The operation returns only the about.count and its embedded fields for all documents:

{"about":{"counts":{"words":100.0,"pages":5.0}}}
{"about":{"counts":{"words":5000.0,"pages":50.0}}}}
{"about":{"counts":{"words":200.0,"pages":1.0}}}

Because about and about.subject do not have read rules, a query predicate that includes these fields will not match any documents. For example, although a document exists with "about.subject": "pies", because the field is not readable, following operation will not return any results:

db.getCollection("reports").find( { "about.subject": "pies" } );

Specify Different Read Rules for Fields

This examples sets up MongoDB Stitch rules such that:

  • title field is readable if about.subject is "pies"
  • about.counts and all its embedded fields are readable if about.subject is "pies"
  • about.subject is readable for any document.

To set up the rules:

  • Ensure that no read rule exists at the document level.

  • Set Allow All Other Fields to disabled.

  • Specify the fields to which you wish to apply the rule. In this example, add the following fields.

    Field Field Type Read Rule
    title Any {"%%root.about.subject":"pies"}
    about Object Do not specify a rule.
    about.subject Any {}
    about.counts Object {"%%root.about.subject":"pies"}
  • In the about.counts document, set Allow All Other Fields to enabled. Do not specify a rule. Alternatively, you can explicitly add about.counts.pages and about.counts.words in the about.counts document. For more information, see Fields Specification.

Given the specified rules, if you issue the following StitchClient read operation:

db.getCollection("reports").find( {} )

The operation returns the following:

{"about":{"subject":"pies","counts":{"words":100.0,"pages":5.0}},"title":"Pies"}
{"about":{"subject":"puff pastries"}}
{"about":{"subject":"cupcakes"}}

All Fields Except for the Listed Field is Readable

This example sets up MongoDB Stitch rules to make the about field and its embedded fields unreadable.

To be able to read specific fields in documents,

  • Ensure that no read rule exists at the document level.

  • Set Allow All Other Fields to enabled at the document level, and specify {} for the read rule.

  • Specify the fields to which you wish to apply this rule. If the field is an embedded document or a field in the embedded document, you must add all the fields in that embedded document, even if you are not specifying rules for all. In this example, add:

    In this example, add:

    Field Field Type Read Rule
    about Object { "%%true": false }

Given the specified rules, if you issue the following StitchClient read operation:

db.getCollection("reports").find( { "classification": "Public" } )

The operation returns the following:

{"_id":1.0,"title":"Pies","classification":"Public","views":100.0}
{"_id":2.0,"title":"Pastries Part 1","classification":"Public","views":20.0}