Realm Query Language (RQL)

Parameterized vs. Serialized Queries

You can format queries in serialized or parameterized format.

• Serialized queries pass values directly in the expression.

  "progressMinutes > 1 AND assignee == 'Ali'"

• Parameterized queries pass interpolated variables as additional arguments. The syntax for interpolated variables is $<int>, starting at 0 and incrementing for each additional variable.

  // Include one parameter with `$0`
  "progressMinutes > 1 AND assignee == $0", "Ali"
  // Include multiple parameters using ascending integers,
  // starting at`$0`
  "progressMinutes > $0 AND assignee == $1", 1, "Alex"

The following table shows how a query should be formatted when serialized and parameterized for the specific data types:

Dot Notation

You can use dot notation to refer to child properties of an object, including the properties of embedded objects and relationships:

// Find projects whose `items` list property contains an item
// with a specific name
"items[0].name == 'Approve project plan'"

You can also chain these notations for nested properties. For example, each Project has a projectLocation property that refers to an Office object, which itself contains an embedded object property address. You can chain dot notations to query the deeply nested zipcode property of an embedded address:

// Find projects whose `projectLocation` property contains an
// embedded Address object with a specific zip code
"projectLocation.address.zipcode == 10019"

Nil Type

Realm Query Language includes the nil type to represent a null pointer. You can either reference nil directly in your queries or with a parameterized query. If you're using a parameterized query, each SDK maps its respective null pointer to nil.

"assignee == nil"
"assignee == $0", null // 'null' maps to SDK language's null pointer

Aggregate Operators

Use aggregate operators to traverse a collection and reduce it to a single value.

The following example uses aggregate operators to find projects whose items collection property meets certain criteria:

var priorityNum = 5;
  // Find projects with average item `priority` above 5
  "items.@avg.priority > $0", priorityNum
  // Find projects where every item has a `priority` less than 5
  "items.@max.priority < $0", priorityNum
  // Find projects where every item has `priority` greater than 5
  "items.@min.priority > $0", priorityNum
  // Find projects with more than 5 items
  "items.@count > $0", 5
  // Find projects where the sum total value of `progressMinutes`
  // across all items is greater than 100
  "items.@sum.progressMinutes > $0",
  100

Arithmetic Operators

Use arithmetic operators to perform basic arithmetic in an expression when evaluating numeric data types, including object properties.

The following example uses arithmetic operators on Item object properties containing numeric values:

// 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"

Comparison Operators

Use comparison operators to compare values of matching data types. String values are compared lexicographically.

The following example uses comparison operators to find to-do items whose property values match certain criteria:

// Compare `priority` values against a threshold value
"priority > $0", 5
// Compare `assignee` values to `null` value.
"assignee == $0", null
// Compare `priority` values against an inclusive range of values
"priority BETWEEN { $0 , $1 }", 1, 5
// Compare `progressMinutes` values against any of the listed values
"progressMinutes IN { $0, $1, $2 }", 10, 30, 60

"Expected object of type object id for property 'id' on object of type
'User', but received: 11223344556677889900aabb (Invalid value)"

Logical Operators

Use logical operators to create compound predicates.

The following example uses logical operators to combine multiple predicates:

// Find all items assigned to Ali AND marked completed
"assignee == $0 AND isComplete == $1", "Ali", true
// Find all items assigned to Alex OR to Ali
"assignee == $0 OR assignee == $1", "Alex", "Ali"

Results Operators

Use the sort, distinct, and limit operators to shape your query results collection. You can combine these operators in a single query across multiple properties. Operators are applied in the order they appear in the query.

The following example finds all incomplete items, then shapes the returned results:

// 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 values for both `name` AND `assignee` properties
"priority >= 5 DISTINCT(name, assignee)"
// Find in-progress items, then return the first 10 results
"progressMinutes > 0 && isComplete != true LIMIT(10)"

// 1. Sorts by highest priority
// 2. Returns the first item
// 3. Remove duplicate names (N/A - a single item is always 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)"

Collection Operators

A collection operator lets you query list properties within a collection of objects. Collection operators filter a collection by applying a predicate to every element of a given list property of the object. If the predicate returns true, the object is included in the output collection.

The following example uses collection operators to find projects whose items collection property meets certain criteria

// Find projects with no complete items
"NONE items.isComplete == $0", true
// 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
// Find projects with at least one item assigned to
// either Alex or Ali
"ANY items.assignee IN { $0 , $1 }", "Alex", "Ali"
// Find projects with no items assigned to either Alex or Ali
"NONE items.assignee IN { $0 , $1 }", "Alex", "Ali"

Dictionary Operators

Use dictionary operators in combination with comparison operators to filter objects based on dictionary keys and values.

The following example uses dictionary operators with comparison operators to find projects based on the comments dictionary property:

// Find projects whose `comments` dictionary property
// have a key of 'status'
"comments.@keys == $0", "status"
// Find projects whose `comments` dictionary property
// have a 'status' key with a value that ends in 'track'
"comments['status'] LIKE $0", "*track"
// Find projects whose `comments` dictionary property
// have more than one key-value pair
"comments.@count > $0", 1
// Find projects whose `comments` dictionary property contains
// only values of type 'string'
"ALL comments.@type == 'string'"
// Find projects whose `comments` dictionary property contains
// no values of type 'int'
"NONE comments.@type == 'int'"

String Operators

Use string operators or comparison operators to filter objects based on string values. SDKs evaluate string values lexicographically.

The following example uses string and comparison operators to find projects based on the project name:

// Find projects whose name starts with 'E' or 'e'
// (case-insensitive query)
"name BEGINSWITH[c] $0", "E"
// Find projects whose name contains 'ie'
// (case-sensitive query)
"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"

Type Operator

Check the data type of a mixed type or dictionary property using the @type operator. Evaluate the property against a string representation of the data type name using string comparison operators. For information on how each SDK language's data types map to database-specific data types, refer to Define Property Types.

The following example uses the @type operator to find projects whose mixed data type additionalInfo property type matches specific criteria:

// Find projects with an `additionalInfo` property of string type
"additionalInfo.@type == 'string'"
// 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'"

Date Queries

Use comparison operators to query date types.

Specify dates in the following formats:

• As a date in UTC, with the date and time separated by @ or T: YYYY-MM-DD@HH:mm:ss:nnnnnnnnnn (year-month-day@hours:minutes:seconds:nanoseconds), UTC.

• As a time in seconds since the Unix epoch: Ts:n (T designates the start of the time, s is the number of seconds, and n is the number of nanoseconds).

var lastYear = new Date(1577883184000); // Unix timestamp in ms
var thisYear = new Date("2021-01-01@17:30:15:0"); // DateTime in UTC
var today = new Date("April 01, 2021 03:24:00"); // Alternate DateTime format

The following example uses a parameterized query to find items based on a new dateCreated property that populates when an item is marked as complete:

// Find to-do items completed before today's date
"dateCompleted < $0", today
// Find to-do items completed between start of the year to today
"dateCompleted > $0 AND dateCompleted < $1", thisYear, today

Full Text Search (FTS) Queries

Perform boolean match word searches to query on properties that have a full-text search (FTS) annotation. For information on enabling FTS on a property, refer to Enable Full-Text Search on a Property.

Query strings are converted to tokens by a tokenizer using the following rules:

• Tokens can only consist of characters from ASCII and the Latin-1 supplement western languages). All other characters are considered whitespace.

• Strings split by a hyphen (-) are split into two tokens. For example, full-text splits into full and text.

• Tokens are diacritics insensitive and case insensitive.

You can search for entire words or phrases, or limit your results with the following wildcard characters:

• Exclude results for a word by placing the - character in front of the word.

• Specify prefixes by placing the * wildcard at the end of a prefix. Suffix searching is not currently supported.

The following example uses the TEXT operator to find items based on their FTS-enabled name property:

// Find items with 'write' in the name.
"name TEXT $0", "write"
// Use '-' to exclude:
// Find items with 'write' but not 'tests' in the name
"name TEXT $0", "write -tests"
// Use '*' to match any characters after a prefix:
// Find items with a name that starts with 'wri'
"name TEXT $0", "wri*"

Geospatial Queries

Use the geoWithin operator to query geospatial data. For more information on defining geospatial data, refer to Define a Geospatial Object.

A geospatial query consists of:

• An object with a property containing the embedded geospatial data.

• A defined geospatial shape to set the boundary for the query:

  • GeoCircle

  • GeoBox

  • GeoPolygon

The query evaluates true if the coordinates of the embedded property are within the boundaries of the geospatial shape.

The following example compares the coordinates of the embedded location property against the boundaries of the GeoCircle shape named smallCircle:

"location geoWithin $0", smallCircle

Inverse Relationship Queries (Backlinks)

You can query an object's inverse relationship to another object through its backlink. Backlinks use the to-one and to-many relationships defined in your object schemas but reverse the direction. Every relationship that you define in your schema implicitly has a corresponding backlink.

You can access an inverse relationship:

• Using the @links.<ObjectType>.<PropertyName> syntax, where <ObjectType> and <PropertyName> refer to a specific property on an object type that references the queried object type.

  // Find items that belong to a project with a quota less than 10
  // (using '@links.<ObjectType>.<PropertyName>')
  "@links.Project.items.quota < 10"

• Using the linkingObjects property to explicitly include the backlink in your data model. This lets you reference the backlink through an assigned property name using dot notation.

  // 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"

The result is treated like a collection and supports collection operators and aggregate operators.

The following examples find items based on the projects they belong to through the @links operator or the projects property:

// 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"

List Comparison Queries

Use comparison operators and collection operators to filter based on lists of data. You can compare any type of valid list, including:

• Collections of objects, which let you filter against other data in the database.

  // Find an item with the specified ObjectId value
  // in the`items` collection
  "oid(631a072f75120729dc9223d9) IN items._id"

• Lists defined directly in the query, which let you filter against static data. You define static lists as a comma-separated list of literal values enclosed in opening ({) and closing (}) braces.

  // Find items with a priority value matching any value
  // in the static list
  "priority IN {0, 1, 2}"

• Native list objects passed in a parameterized expression, which let you pass application data directly to your queries.

  const ids = [
    new BSON.ObjectId("631a072f75120729dc9223d9"),
    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);

"assignee == ANY { $0, $1 }", "Alex", "Ali"
"assignee == { $0, $1 }", "Alex", "Ali" // Equivalent (ANY is implied)

The following table demonstrates how collection operators interact with lists and comparison operators:

List Subqueries

Use the SUBQUERY() predicate function to iterate through list properties with an additional query. Subqueries are useful when you need to match objects in a list property based on multiple conditions.

Subqueries use the following syntax:

SUBQUERY(<collection>, $<variableName>, <predicate>).@count

The following example uses subquery filters to find projects based on the items collection property using the $item variable name:

// 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"

ObjectId and UUID Queries

Use comparison operators to compare BSON ObjectIds and UUIDs for equality. These data types are often used as primary keys.

You can use pass ObjectId and UUID values either as parameterized query arguments or to the oid() or uuid() predicate functions, respectively.

The following examples use equality comparison operators to find items based on their _id property:

// 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