Realm Query Language

Query with Realm SDKs

For further reading on SDK-specific methods for querying realms, see the documentation for your SDK:

You can also use Realm Query Language to browse for data in Realm Studio. Realm Studio is a visual tool to view, edit, and design Realm files.

Examples on This Page

Many of the examples in this page use a simple data set for a to-do list app. The two Realm object types are Project and Item.

• An Item has a name, assignee's name, and completed flag. There is also an arbitrary number for priority (higher is more important) and a count of minutes spent working on it.

• A Project has zero or more Items and an optional quota for minimum number of to-do items expected to be completed.

See the schema for these two classes, Project and Item, below:

public class Item extends RealmObject {
  ObjectId id = new ObjectId();
  String name;
  Boolean isComplete = false;
  String assignee;
  Integer priority = 0;
  Integer progressMinutes = 0;
  @LinkingObjects("items")
  final RealmResults<Project> projects = null;
}
public class Project extends RealmObject {
  ObjectId id = new ObjectId();
  String name;
  RealmList<Item> items;
  Integer quota = null;
}

open class Item(): RealmObject() {
  var id: ObjectId = new ObjectId()
  @FullText
  lateinit var name: String
  var isComplete: Boolean = false
  var assignee: String? = null
  var priority: Int = 0
  var progressMinutes: Int = 0
}
open class Project(): RealmObject() {
  var id: ObjectId = new ObjectId()
  lateinit var name: String
  lateinit var items: RealmList<Item>
  var quota: Int? = null
}

public class Item : RealmObject
{
    [PrimaryKey]
    [MapTo("_id")]
    public ObjectId Id { get; set; } = ObjectId.GenerateNewId();
    [MapTo("name")]
    [Indexed(IndexType.FullText)]
    public string Name { get; set; }
    [MapTo("isComplete")]
    public bool IsComplete { get; set; } = false;
    [MapTo("assignee")]
    public string Assignee { get; set; }
    [MapTo("priority")]
    public int Priority { get; set; } = 0;
    [MapTo("progressMinutes")]
    public int ProgressMinutes { get; set; } = 0;
    [MapTo("projects")]
    [Backlink(nameof(Project.Items))]
    public IQueryable<Project> Projects { get; }
}
public class Project : RealmObject
{
    [PrimaryKey]
    [MapTo("_id")]
    public ObjectId Id { get; set; } = ObjectId.GenerateNewId();
    [MapTo("name")]
    public string Name { get; set; }
    [MapTo("items")]
    public IList<Item> Items { get; }
    [MapTo("quota")]
    public int Quota { get; set; }
}

const ItemModel = {
  name: "Item",
  properties: {
    id: "objectId",
    name: {type: "string", indexed: "full-text"},
    isComplete: { type: "bool", default: false },
    assignee: "string?",
    priority: {
      type: "int",
      default: 0,
    },
    progressMinutes: {
      type: "int",
      default: 0,
    },
    projects: {
      type: "linkingObjects",
      objectType: "Project",
      property: "items",
    },
  },
  primaryKey: "id",
};
const ProjectModel = {
  name: "Project",
  properties: {
    id: "objectId",
    name: "string",
    items: "Item[]",
    quota: "int?",
  },
  primaryKey: "id",
};

const ItemModel = {
  name: "Item",
  properties: {
    id: "objectId",
    name: {type: "string", indexed: "full-text"},
    isComplete: { type: "bool", default: false },
    assignee: "string?",
    priority: {
      type: "int",
      default: 0,
    },
    progressMinutes: {
      type: "int",
      default: 0,
    },
    projects: {
      type: "linkingObjects",
      objectType: "Project",
      property: "items",
    },
  },
  primaryKey: "id",
};
const ProjectModel = {
  name: "Project",
  properties: {
    id: "objectId",
    name: "string",
    items: "Item[]",
    quota: "int?",
  },
  primaryKey: "id",
};

class Item(): RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    @FullText
    var name: String = ""
    var isComplete: Boolean = false
    var assignee: String? = null
    var priority: Int = 0
    var progressMinutes: Int = 0
}
class Project(): RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var items: RealmList<Item> = realmListOf<Item>()
    var quota: Int? = null
}

part 'models.realm.dart';
@RealmModel()
class _Project {
  @MapTo("_id")
  @PrimaryKey()
  late ObjectId id;
  late String name;
  late List<_Item> items;
  int? quota;
}
@RealmModel()
class _Item {
  @MapTo("_id")
  @PrimaryKey()
  late ObjectId id;
  @Indexed(RealmIndexType.fullText)
  late String name;
  bool isComplete = false;
  String? assignee;
  int priority = 0;
  int progressMinutes = 0;
}

Expressions

Filters consist of expressions in a predicate. An expression consists of one of the following:

• The name of a property of the object currently being evaluated.

• An operator and up to two argument expression(s). For example, in the expression A + B, the entirety of A + B is an expression, but A and B are also argument expressions to the operator +.

• A value, such as a string ('hello') or a number (5).

"progressMinutes > 1 AND assignee == $0", "Ali"

Parameterized Queries

Create parameterized queries to interpolate variables into prepared Realm Query Language statements. The syntax for interpolated variables is $<int>, starting at 0. Pass the positional arguments as additional arguments to Realm SDK methods that use Realm Query Language.

Include just one parameter with $0.

"progressMinutes > 1 AND assignee == $0", "Ali"

Include multiple parameters with ascending integers starting at $0.

"progressMinutes > $0 AND assignee == $1", 1, "Alex"

Dot Notation

When referring to an object property, you can use dot notation to refer to child properties of that object. You can even refer to the properties of embedded objects and relationships with dot notation.

For example, consider a query on an object with a workplace property that refers to a Workplace object. The Workplace object has an embedded object property, address. You can chain dot notations to refer to the zipcode property of that address:

"workplace.address.zipcode == 10019"

Nil Type

Realm Query Language include 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"

// comparison to language null pointer
"assignee == $0", null

Comparison Operators

The most straightforward operation in a search is to compare values.

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

  // Find high priority to-do items by comparing the value of the ``priority``
  // property value with a threshold number, above which priority can be considered high.
  "priority > $0", 5
  // Find long-running to-do items by seeing if the progressMinutes property is at or above a certain value.
  "progressMinutes > $0", 120
  // Find unassigned to-do items by finding items where the assignee property is equal to null.
  "assignee == $0", null
  // Find to-do items within a certain time range by finding items 
  // where the progressMinutes property is between two numbers.
  "progressMinutes BETWEEN { $0 , $1 }", 30, 60
  // Find to-do items with a certain amount of progressMinutes from the given list.
  "progressMinutes IN { $0, $1, $2, $3, $4, $5 }", 10, 20, 30, 40, 50, 60

Logical Operators

Make compound predicates using logical operators.

"assignee == $0 AND isComplete == $1", "Ali", true

String Operators

Compare string values using these string operators. Regex-like wildcards allow more flexibility in search.

  "name BEGINSWITH[c] $0", 'e'
  "name CONTAINS $0", 'ie'

ObjectId and UUID Operators

Query BSON ObjectIds and UUIDs. These data types are often used as primary keys.

To query with ObjectIds, use a parameterized query. Pass the ObjectId or UUID you're querying against as the argument.

"_id == $0", oidValue

You can also put a string representation of the ObjectId you're evaluating in oid(<ObjectId String>).

"_id == oid(6001c033600510df3bbfd864)"

To query with UUIDs, put a string representation of the UUID you're evaluating in uuid(<UUID String>).

"id == uuid(d1b186e1-e9e0-4768-a1a7-c492519d47ee)"

Arithmetic Operators

Perform basic arithmetic in one side of a RQL expression when evaluating numeric data types.

  "2 * priority > 6"
  // Is equivalent to
  "priority >= 2 * (2 - 1) + 2"

You can also use multiple object properties together in a mathematic operation.

"progressMinutes * priority == 90"

Type Operator

Check the type of a property using the @type operator. You can only use the type operator with mixed types and dictionaries.

Evaluate the property against a string representation of the data type name. Refer to SDK documentation on the mapping from the SDK language's data types to Realm data types.

  "mixedType.@type == 'string'"
  "mixedType.@type == 'bool'"

Dictionary Operators

Compare dictionary values using these dictionary operators.

You can also use dictionary operators in combination with comparison operators to filter objects based on dictionary keys and values. The following examples show some ways to use dictionary operators with comparison operators. All examples query a collection of Realm objects with a dictionary property named dict.

  // Evaluates if there is a dictionary key with the name 'foo'
  "ANY dict.@keys == $0", 'foo'
  // Evaluates if there is a dictionary key with key 'foo' and value 'bar
  "dict['foo'] == $0", 'bar'
  // Evaluates if there is greater than one key-value pair in the dictionary
  "dict.@count > $0", 1
  // Evaluates if dictionary has property of type 'string'
  "ANY dict.@type == 'string'"
  // Evaluates if all the dictionary's values are integers
  "ALL dict.@type == 'bool'"
  // Evaluates if dictionary does not have any values of type int
  "NONE dict.@type == 'double'"
  // ANY is implied.
  "dict.@type == 'string'"

Date Operators

Query date types in a realm.

Generally, you should use a parameterized query to pass a date data type from the SDK language you are using to a query.

"timeCompleted < $0", someDate

You can also specify dates in the following two ways:

• As a specific date (in UTC)- YYYY-MM-DD@HH:mm:ss:nnnnnnnnnn (year-month-day@hours:minutes:seconds:nanoseconds), UTC. You can also use T instead of @ to separate the date from the time.

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

Date supports comparison operators.

var date = new Date("2021-02-20@17:30:15:0");
  "timeCompleted > $0", date

Aggregate Operators

Apply an aggregate operator to a collection property of a Realm object. Aggregate operators traverse a collection and reduce it to a single value.

var priorityNum = 5;
  "items.@avg.priority > $0", priorityNum
  "items.@max.priority < $0", priorityNum
  "items.@min.priority > $0", priorityNum
  "items.@count > $0", 5
  "items.@sum.progressMinutes > $0", 100

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.

  // Projects with no complete items.
  "NONE items.isComplete == $0", true
  // Projects that contain a item with priority 10
  "ANY items.priority == $0", 10
  // Projects that only contain completed items
  "ALL items.isComplete == $0", true
  // Projects with at least one item assigned to either Alex or Ali
  "ANY items.assignee IN { $0 , $1 }", "Alex", "Ali"
  // Projects with no items assigned to either Alex or Ali
  "NONE items.assignee IN { $0 , $1 }", "Alex", "Ali"

List Comparisons

You can use comparison operators and collection operators to filter based on lists of data.

You can compare any type of valid list. This includes:

• collections of Realm objects, which let you filter against other data in the realm.

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

  "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"),
  ];
  const parameterizedQuery = realm.objects("Item").filtered("id IN $0", ids);

If you do not define a collection operator, a list expression defaults to the ANY operator.

The following table includes examples that illustrate how collection operators interact with lists and comparison operators:

Full Text Search

You can use RQL to query on properties that have a full-text search (FTS) annotation. FTS supports boolean match word searches, rather than searches for relevance. For information on enabling FTS on a property, see the FTS documentation for your SDK:

• Flutter SDK

• Kotlin SDK

• .NET SDK

• Node.js SDK

• React Native SDK

• Swift SDK does not yet support Full-Text Search.

To query these properties, use the TEXT predicate in your query.

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

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

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

In the following example, we query the Item.name property:

    // Filter for items with 'write' in the name
    "name TEXT $0", "write"
    // Find items with 'write' but not 'tests' using '-'
    "name TEXT $0", "write -tests"
    // Find items starting with 'wri-' using '*'
    "name TEXT $0", "wri*"

Geospatial Queries

You can query against geospatial data using the geoWithin operator. The geoWithin operator takes the latitude/longitude pair in a custom embedded object's coordinates property and a geospatial shape. The operator checks whether the cordinates point is contained within the geospatial shape.

The following geospatial shapes are supported for querying:

• GeoCircle

• GeoBox

• GeoPolygon

To query geospatial data:

1. Create an object with a property containing the embedded geospatial data.

2. Define the geospatial shape to set the boundary for the query.

3. Query using the geoWithin RQL operator.

In the following query, we are checking that the coordinates of the embeddeded location property are contained within the GeoCircle shape, smallCircle:

"location geoWithin $0", smallCircle

For more information on defining geospatial shapes and objects with embedded geospatial data, see the geospatial documentation for your SDK:

• Flutter SDK

• Kotlin SDK

• .NET SDK

• Node.js SDK

• React Native SDK

• Swift SDK

Backlink Queries

A backlink is an inverse relationship link that lets you look up objects that reference another object. 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 backlinks in queries 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 greater than 10 (@links)
"@links.Project.items.quota > 10"

You can also define a linkingObjects property to explicitly include the backlink in your data model. This lets you reference the backlink through an assigned property name using standard dot notation.

// Find items that belong to a project with a quota greater than 10 (LinkingObjects)
"projects.quota > 10"

The result of a backlink is treated like a collection and supports collection operators.

  // Find items where any project that references the item has a quota greater than 0
  "ANY @links.Project.items.quota > 0"
  // Find items where all projects that reference the item have a quota greater than 0
  "ALL @links.Project.items.quota > 0"

You can use aggregate operators on the backlink collection.

  // 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 5 minutes
  "@links.Project.items.items.@avg.progressMinutes > 10"

You can query the count of all relationships that point to an object by using the @count operator directly on @links.

// Find items that are not referenced by another object of any type
"@links.@count == 0"

Subqueries

Iterate through list properties with another query using the SUBQUERY() predicate function.

Subqueries are useful for the following scenarios:

• Matching each object in a list property on multiple conditions

• Counting the number of objects that match a subquery

SUBQUERY() has the following structure:

SUBQUERY(<collection>, <variableName>, <predicate>)

• collection: The name of the property to iterate through

• variableName: A variable name of the element to use in the subquery

• predicate: The subquery predicate. Use the variable specified by variableName to refer to the currently-iterated element.

A subquery iterates through the given collection and checks the given predicate against each object in the collection. The predicate can refer to the current iterated object with the variable name passed to SUBQUERY().

A subquery expression resolves to a list of objects. Realm only supports the @count aggregate operator on the result of a subquery. This allows you to count how many objects in the subquery input collection matched the predicate.

You can use the count of the subquery result as you would any other number in a valid expression. In particular, you can compare the count with the number 0 to return all matching objects.

  // Returns projects with items that have not been completed
  // by a user named Alex.
  "SUBQUERY(items, $item, $item.isComplete == false AND $item.assignee == 'Alex').@count > 0"
  // Returns the projects where the number of completed items is
  // greater than or equal to the value of a project's `quota` property.
  "SUBQUERY(items, $item, $item.isComplete == true).@count >= quota"

Sort, Distinct & Limit

Sort and limit the results collection of your query using additional operators.

"assignee == 'Ali' SORT(priority DESC) DISTINCT(name) LIMIT(5)"

Flexible Sync RQL Limitations

// Query a constant list for a queryable field value
"priority IN { 1, 2, 3 }"

// Query an array-valued queryable field for a constant value
"'comedy' IN genres"

// Invalid Flexible Sync query. Do not do this!
"{'comedy', 'horror', 'suspense'} IN genres"
// Another invalid Flexible Sync query. Do not do this!
"ANY {'comedy', 'horror', 'suspense'} != ANY genres"