Rearranged page order and updated example snippet formatting

cbullinger · cbullinger · commit c86e8695bd1e · 2024-05-30T12:48:56.000-04:00
diff --git a/examples/node/v12/__tests__/realm-query-language.test.ts b/examples/node/v12/__tests__/realm-query-language.test.ts
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.backlinks-aggregate-operators.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.backlinks-aggregate-operators.ts.rst
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.backlinks-atLinks.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.backlinks-atLinks.ts.rst
@@ -1,5 +1,5 @@
 .. code-block:: typescript
 
-   // Find items that belong to a project with a quota
-   // less than 10 (using '@links').
+   // Find items that belong to a project with a quota less than 10
+   // (using '@links.<ObjectType>.<PropertyName>').
    "@links.Project.items.quota < 10"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.backlinks-collection-operators.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.backlinks-collection-operators.ts.rst
@@ -1,8 +1,23 @@
 .. code-block:: typescript
 
-     // Find items where ANY project that references the item
-     // has a quota greater than 10.
-     "ANY @links.Project.items.quota > 10"
-     // Find items where ALL projects that reference the item
-     // have a quota less than 5.
-     "ALL @links.Project.items.quota < 5"
+       // Find items where no project that references the item
+       // has a quota greater than 10.
+       "NONE @links.Project.items.quota > 10"
+
+       // Find items where all projects that reference the item
+       // have a quota less than 5.
+       "ALL @links.Project.items.quota < 5"
+
+       // Find items that are referenced by multiple projects.
+       "projects.@count > 1"
+
+       // Find items that are not referenced by any project.
+       "@links.Project.items.@count == 0"
+
+       // Find items that belong to a project where the average item has
+       // been worked on for at least 10 minutes
+       "@links.Project.items.items.@avg.progressMinutes > 10"
+
+       // Find items that are not referenced by another
+       // object of any type (backlink count is 0).
+       "@links.@count == 0"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.backlinks-linkingObjects.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.backlinks-linkingObjects.ts.rst
@@ -1,5 +1,6 @@
 .. code-block:: typescript
 
    // Find items that belong to a project with a quota greater than 10
+   // through the Item object's `projects` property
    // (using 'LinkingObjects').
    "projects.quota > 10"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.basic-arithmetic.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.basic-arithmetic.ts.rst
@@ -1,5 +1,8 @@
 .. code-block:: typescript
 
-     // Find items with a `priority` greater than 3.
-     "2 * priority > 6" // `priority > 3`
-     "priority >= 2 * (2 - 1) + 2" // `priority >= 4`
+       // Evaluate against an item's `priority` property value:
+       "2 * priority > 6" // resolves to `priority > 3`
+       "priority >= 2 * (2 - 1) + 2" // resolves to `priority >= 4`
+
+       // Evaluate against multiple object property values:
+       "progressMinutes * priority == 90"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.comparison-operators.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.comparison-operators.ts.rst
@@ -3,9 +3,6 @@
      // Compare `priority` values against a threshold value.
      "priority > $0", 5
 
-     // Compare `progressMinutes` values against a threshold value.
-     "progressMinutes > $0", 120
-
      // Compare `assignee` values to `null` value.
      "assignee == $0", null
 
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.date-parameterized-query.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.date-parameterized-query.ts.rst
@@ -3,5 +3,6 @@
      // Find to-do items completed before today's date.
      "dateCompleted < $0", today
 
-     // Find to-do items completed this year until today.
+     // Find to-do items completed between the start of the year
+     // until today.
      "dateCompleted > $0 AND dateCompleted < $1", thisYear, today
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.deep-dot-notation.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.deep-dot-notation.ts.rst
@@ -1,3 +1,5 @@
 .. code-block:: typescript
 
+   // Find projects whose `projectLocation` property contains
+   // an embedded Address object with a specific zip code.
    "projectLocation.address.zipcode == 10019"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.dictionary-operators.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.dictionary-operators.ts.rst
@@ -1,25 +1,21 @@
 .. code-block:: typescript
 
-     // Find `comments` dictionary properties with key 'status'.
+     // Find projects whose `comments` dictionary property
+     // have a key of 'status'.
      "comments.@keys == $0", "status"
 
-     // Find `comments` dictionary properties with key 'status'
-     // and value 'On track'.
-     "comments['status'] == $0", "On track"
-     // Find `comments` dictionary properties with
-     // more than one key-value pair.
-     "comments.@count > $0", 1
+     // Find projects whose `comments` dictionary property
+     // have a 'status' key with a value that ends in 'track'.
+     "comments['status'] LIKE $0", "*track"
 
-     // Find `comments` dictionary properties where ANY
-     // values are of type 'string`.
-     "ANY comments.@type == 'string'"
-     "comments.@type == 'string'" // (Equivalent - ANY is implied.)
+     // Find projects whose `comments` dictionary property
+     // have more than one key-value pair.
+     "comments.@count > $0", 1
 
-     // Find `comments` dictionary properties where ALL
-     // values are of type 'int'.
-     "ALL comments.@type == 'int'"
+     // Find projects whose `comments` dictionary property
+     // contains only values of type 'string'.
+     "ALL comments.@type == 'string'"
 
-     // Find `comments` dictionary properties where NO
-     // values are of type 'int'.
+     // Find projects whose `comments` dictionary property
+     // contains no values of type 'int'.
      "NONE comments.@type == 'int'"
-
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.dot-notation.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.dot-notation.ts.rst
@@ -0,0 +1,5 @@
+.. code-block:: typescript
+
+   // Find projects whose `items` list property contains
+   // an Item object with a specific name.
+   "items[0].name == 'Approve project plan'"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.equivalent-lists-any-operator.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.equivalent-lists-any-operator.ts.rst
@@ -0,0 +1,7 @@
+.. code-block:: typescript
+
+     "assignee == ANY { $0, $1 }", "Alex", "Ali"
+
+     "assignee == { $0, $1 }", "Alex", "Ali" // Equivalent (ANY is implied.)
+
+     "assignee NONE { 'Alex', 'Ali' }" // Equivalent to != ANY.
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.list-comparisons-collection.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.list-comparisons-collection.ts.rst
@@ -1,3 +1,5 @@
 .. code-block:: typescript
 
+   // Find an item with the specified ObjectId value
+   // in the `items` collection.
    "oid(631a072f75120729dc9223d9) IN items._id"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.list-comparisons-parameterized.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.list-comparisons-parameterized.ts.rst
@@ -5,4 +5,6 @@
      new BSON.ObjectId("631a0737c98f89f5b81cd24d"),
      new BSON.ObjectId("631a073c833a34ade21db2b2"),
    ];
+   // Find items with an ObjectId value matching any value in the
+   // parameterized list.
    const parameterizedQuery = realm.objects(Item).filtered("_id IN $0", ids);
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.list-comparisons-static.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.list-comparisons-static.ts.rst
@@ -1,3 +1,5 @@
 .. code-block:: typescript
 
+   // Find items with a priority value matching
+   // any value in the static list.
    "priority IN {0, 1, 2}"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.nil-type.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.nil-type.ts.rst
@@ -1,3 +1,6 @@
 .. code-block:: typescript
 
-   "assignee == nil"
+     "assignee == nil"
+
+     // 'null' maps to the SDK language's null pointer
+     "assignee == $0", null
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.oid-literal.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.oid-literal.ts.rst
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.oid.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.oid.ts.rst
@@ -1,3 +1,18 @@
 .. code-block:: typescript
 
-   "_id == oid(6001c033600510df3bbfd864)"
+       // Find an item whose `_id` matches the ObjectID
+       // value passed to 'oid()'.
+       "_id == oid(6001c033600510df3bbfd864)"
+
+       // Find an item whose `_id` matches the ObjectID
+       // passed as a parameterized query argument.
+       "_id == $0", oidValue
+
+       // Find an item whose `id` matches the UUID value
+       // passed to 'uuid()'.
+       "id == uuid(d1b186e1-e9e0-4768-a1a7-c492519d47ee)"
+
+
+       // Find an item whose `_id` matches the UUID
+       // passed as a parameterized query argument.
+       "id == $0", uuidValue
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.rql-fts.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.rql-fts.ts.rst
@@ -7,6 +7,6 @@
      // Find items with 'write' but not 'tests' in the name.
      "name TEXT $0", "write -tests"
 
-     // Use '*' to match any suffix characters:
-     // Find items starting with 'wri-'.
+     // Use '*' to match any characters after a prefix:
+     // Find items with a name that starts with 'wri'.
      "name TEXT $0", "wri*"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.set-operators.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.set-operators.ts.rst
@@ -3,8 +3,8 @@
      // Find projects with no complete items.
      "NONE items.isComplete == $0", true
 
-     // Find projects that contain an item with priority 10.
-     "ANY items.priority == $0", 10
+     // Find projects that contain any item with priority 10.
+     "items.priority == $0", 10 // (ANY operator is implied.)
 
      // Find projects that only contain completed items.
      "ALL items.isComplete == $0", true
@@ -13,5 +13,6 @@
      // either Alex or Ali.
      "ANY items.assignee IN { $0 , $1 }", "Alex", "Ali"
 
-     // Projects with no items assigned to either Alex or Ali.
+     // Find projects with no items assigned to either
+     // Alex or Ali.
      "NONE items.assignee IN { $0 , $1 }", "Alex", "Ali"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.sort-distinct-limit-order-matters.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.sort-distinct-limit-order-matters.ts.rst
@@ -0,0 +1,12 @@
+.. code-block:: typescript
+
+     // 1. Sorts by highest priority.
+     // 2. Returns the first item.
+     // 3. Remove duplicate names (N/A because a single
+     //    item is always considered distinct).
+     "assignee == null SORT(priority ASC) LIMIT(1) DISTINCT(name)"
+
+     // 1. Removes any duplicates by name.
+     // 2. Sorts by highest priority.
+     // 3. Returns the first item.
+     "assignee == null DISTINCT(name) SORT(priority ASC) LIMIT(1)"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.sort-distinct-limit.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.sort-distinct-limit.ts.rst
@@ -1,3 +1,12 @@
 .. code-block:: typescript
 
-   "assignee == 'Ali' SORT(priority DESC) DISTINCT(name) LIMIT(5)"
+     // Find incomplete items, sort by `priority`
+     // in descending order, then sort equal `priority`
+     // values by `progressMinutes` in ascending order.
+     "isComplete == false SORT(priority DESC, progressMinutes ASC)"
+
+     // Find high priority items, then remove from the results
+     // any items with duplicate `name` AND `assignee` values.
+     "priority >= 5 DISTINCT(name, assignee)"
+     // Find in-progress items, then return the first 10 results.
+     "progressMinutes > 0 && isComplete != true LIMIT(10)"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.string-operators.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.string-operators.ts.rst
@@ -1,9 +1,17 @@
 .. code-block:: typescript
 
-     // Find projects whose name starts with the letter 'e'
-     // (case-insensitive).
-     "name BEGINSWITH[c] $0", "e"
+       // Find projects whose name starts with 'E' or 'e'
+       // (case-insensitive).
+       "name BEGINSWITH[c] $0", "E"
 
-     // Find projects whose name contains the letters 'ie'
-     // (case-sensitive).
-     "name CONTAINS $0", "ie"
+       // Find projects whose name contains 'ie'
+       // (case-sensitive).
+       "name CONTAINS $0", "ie"
+
+       // Find items where the assignee name is lexicographically
+       // between 'Ali' and 'Chris' (case-sensitive).
+       "assignee BETWEEN { $0 , $1 }", "Ali", "Chris"
+       
+       // Find projects where the street address is lexicographically
+       // greater than '123 Main St' (case-sensitive).
+       "projectLocation.address.street > $0", "123 Main St"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.subquery-count.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.subquery-count.ts.rst
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.subquery.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.subquery.ts.rst
@@ -1,4 +1,8 @@
 .. code-block:: typescript
 
-   // Find projects with incomplete to-do items assigned to Alex.
-   "SUBQUERY(items, $item, $item.isComplete == false AND $item.assignee == 'Alex').@count > 0"
+     // Find projects with incomplete items with 'Demo' in the name.
+     "SUBQUERY(items, $item, $item.isComplete == false AND $item.name CONTAINS[c] 'Demo').@count > 0"
+
+     // Find projects where the number of completed items
+     // is greater than or equal to the project's `quota` property.
+     "SUBQUERY(items, $item, $item.isComplete == true).@count >= quota"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.type-operator.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.type-operator.ts.rst
@@ -1,5 +1,13 @@
 .. code-block:: typescript
 
-     "mixedType.@type == 'string'"
+     // Find projects with an `additionalInfo` property of
+     // string type.
+     "additionalInfo.@type == 'string'"
 
-     "mixedType.@type == 'bool'"
+     // Find projects with an `additionalInfo` property of
+     // `collection` type, which matches list or dictionary types.
+     "additionalInfo.@type == 'collection'"
+
+     // Find projects with an `additionalInfo` property of
+     // list type, where any list element is of type 'bool'.
+     "additionalInfo[*].@type == 'bool'"
diff --git a/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.uuid.ts.rst b/source/examples/generated/node/v12/formatted/realm-query-language.test.snippet.uuid.ts.rst
diff --git a/source/examples/generated/node/v12/formatted/rql-data-models.snippet.rql-data-models.ts.rst b/source/examples/generated/node/v12/formatted/rql-data-models.snippet.rql-data-models.ts.rst
@@ -33,6 +33,7 @@
      quota?: number;
      comments?: Realm.Dictionary<string>;
      projectLocation?: Office;
+     additionalInfo!: Realm.Mixed;
 
      static schema: ObjectSchema = {
        name: "Project",
@@ -43,6 +44,7 @@
          quota: "int?",
          comments: "string?{}",
          projectLocation: "Office?",
+         additionalInfo: "mixed",
        },
        primaryKey: "_id",
      };
diff --git a/source/sdk/crud/query-engines/realm-query-language.txt b/source/sdk/crud/query-engines/realm-query-language.txt
