Realm 查询语言

使用 Realm SDK 进行查询

如需进一步了解不同 SDK 查询域的特定方法，请参阅相应的 SDK 文档：

您还可以使用 Realm 查询语言在 Realm Studio 中浏览数据。Realm Studio 是一款用于查看、编辑和设计 Realm 文件的可视化工具。

本页中的示例

本页面中的许多示例都使用了一个待办事项列表应用的简单数据集。两种 Realm 对象类型分别是 Project 和 Item。

• Item 具有名称、受让人名称和已完成标志。其中还有一个任意的优先级数字（数值越高表示越重要）以及处理所花费的分钟数。

• Project 具有零个或多个 Items 以及一个可选配额，用于指示预计要完成的待办事项的最小数量。

请参阅 Project 和 Item 这两个类的模式，如下所示：

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;
}

表达式

过滤器由谓词中的表达式组成。表达式由以下任一内容组成：

• 当前正在评估的对象的某个属性的名称。

• 一个操作符和最多两个参数表达式。例如，在表达式 A + B 中，整个 A + B 是一个表达式，但 A 和 B 也是操作符 + 的参数表达式。

• 一个值，例如字符串 ('hello') 或数字 (5)。

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

参数化查询

创建参数化查询以将变量插入到准备好的 Realm 查询语言语句中。插值变量的语法是 $<int>，从 0开始。将位置参数作为附加参数传递给使用 Realm 查询语言的 Realm SDK 方法。

仅包含一个带有 $0 的参数。

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

包含多个参数，使用从 $0 开始的升序整数。

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

点符号

在引用对象属性时，可以使用点符号来引用该对象的子属性。您甚至可以使用点符号来引用嵌入式对象的属性和关系。

例如，请考虑针对某个对象的查询，该对象具有一个 workplace 属性，该属性引用了一个 Workplace 对象。Workplace 对象具有嵌入式对象属性 address。您可以使用链式点符号来引用该地址的 zipcode 属性：

"workplace.address.zipcode == 10019"

Nil 类型

Realm 查询语言包含用于表示空指针的 nil 类型。您可以在查询中直接引用 nil，也可以通过参数化查询引用。如果使用参数化查询，每个 SDK 都会将各自的空指针映射到 nil。

"assignee == nil"

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

比较操作符。

搜索中最直接的操作就是比较值。

"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

逻辑操作符

使用逻辑操作符创建复合谓词。

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

字符串操作符

使用这些字符串操作符比较字符串值。类似正则表达式的通配符可以让搜索变得更加灵活。

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

ObjectId 和 UUID 操作符

查询 BSON ObjectIds 和 UUID。这些数据类型通常用作主键。

要使用 ObjectId 进行查询，请使用参数化查询。请将您要查询的 ObjectId 或 UUID 作为参数传递。

"_id == $0", oidValue

您还可以将要评估的 ObjectId 的字符串表示形式放在 oid(<ObjectId String>) 中。

"_id == oid(6001c033600510df3bbfd864)"

要使用 UUID 进行查询，请将您要评估的 UUID 的字符串表示形式放在 uuid(<UUID String>) 中。

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

算术操作符

评估数值数据类型时，请在 RQL 表达式的一侧执行基本算数运算。

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

您还可以在数学运算中同时使用多个对象属性。

"progressMinutes * priority == 90"

类型操作符

使用 @type 操作符检查属性的类型。您只能将类型操作符与混合类型和字典一起使用。

根据数据类型名称的字符串表示对属性进行评估。请参阅 SDK 文档，以了解如何将 SDK 对应语言中定义的数据类型映射到 Realm 支持的数据类型。

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

字典操作符

使用这些字典操作符比较字典值。

您还可以将字典操作符与比较操作符结合使用，根据字典键和值筛选对象。 以下示例展示了将字典操作符与比较操作符结合使用的一些方法。 所有示例均查询具有名为dict的字典属性的 Realm 对象集合。

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

日期操作符

查询 Realm 中的日期类型。

通常，应当通过参数化查询将日期数据类型从您所使用 SDK 的对应语言传递到查询。

"timeCompleted < $0", someDate

您还可以通过以下两种方式指定日期：

• 作为特定日期（以 UTC 为单位）- YYYY-MM-DD@HH:mm:ss:nnnnnnnnnn (year-month-day@hours:minutes:seconds:nanoseconds), UTC。 您还可以使用T代替@来分隔日期和时间。

• 自 Unix 纪元 以来的时间（以秒为单位） -Ts:n ，其中T s表示时间开始，n 为秒数， 为纳秒数。

日期支持比较操作符。

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

聚合操作符

将聚合操作符应用于 Realm 对象的集合属性。聚合操作符遍历集合并将其归约为单个值。

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

集合操作符

通过集合操作符，可以查询对象集合中的列表属性。集合操作符通过将谓词应用于对象的给定列表属性的每个元素来过滤集合。如果谓词返回 true，则相应对象包含在输出集合中。

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

列表比较

您可以使用比较操作符和集合操作符来根据数据列表进行过滤。

您可以比较任何类型的有效列表。这包括：

• Realm Object的集合，让您可以针对域中的其他数据进行过滤。

  "oid(631a072f75120729dc9223d9) IN items.id"

• 直接在查询中定义的列表，用于过滤静态数据。您可以使用在左大括号 ({) 和右大括号 (}) 中使用逗号分隔的字面值列表来定义静态列表。

  "priority IN {0, 1, 2}"

• 通过参数化表达式传递的原生列表对象，可允许您将应用程序数据直接传递给查询。

  const ids = [
    new BSON.ObjectId("631a072f75120729dc9223d9"),
    new BSON.ObjectId("631a0737c98f89f5b81cd24d"),
    new BSON.ObjectId("631a073c833a34ade21db2b2"),
  ];
  const parameterizedQuery = realm.objects("Item").filtered("id IN $0", ids);

如果未定义集合操作符，则列表表达式默认为 ANY 操作符。

下表中的示例展示了集合操作符如何与列表以及比较运算符搭配使用：

全文本搜索

您可以使用 RQL 查询带有全文搜索 (FTS) 注解的属性。FTS 支持布尔匹配词搜索，而不支持相关性搜索。有关在属性上启用 FTS 的信息，请参阅您的 SDK 的 FTS 文档：

• Flutter SDK

• Kotlin SDK

• .NET SDK

• Node.js SDK

• React Native SDK

• Swift SDK 尚不支持全文搜索。

要查询这些属性，请在查询中使用 TEXT 谓词。

您可以搜索整个单词或短语，或使用以下字符限制搜索结果：

• 在单词前加上 - 字符以排除该单词的结果。

• 通过在前缀末尾添加 * 字符来指定前缀。目前不支持后缀搜索。

在以下示例中，我们查询 Item.name 属性：

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

地理空间查询

您可以使用geoWithin操作符查询地理空间数据。 geoWithin操作符获取自定义嵌入式对象的coordinates属性中的纬度/经度对和地理空间形状。 该操作符检查cordinates点是否包含在地理空间形状内。

支持查询以下地理空间形状：

• GeoCircle

• GeoBox

• GeoPolygon

查询地理空间数据：

1. 创建一个对象，其属性包含嵌入式地理空间数据。

2. 定义地理空间形状以设置查询边界。

3. 使用 geoWithin RQL 操作符进行查询。

在以下查询中，我们检查嵌入式location属性的坐标是否包含在GeoCircle形状smallCircle中：

"location geoWithin $0", smallCircle

有关使用嵌入式地理空间数据定义地理空间形状和对象的更多信息，请参阅您的 SDK 的地理空间文档：

• Flutter SDK

• Kotlin SDK

• .NET SDK

• Node.js SDK

• React Native SDK

• Swift SDK

反向链接查询

反向链接是一种逆向关系链接，可用于查找引用另一个对象的对象。反向链接使用您在对象模式中定义的一对一和一对多关系，但方向相反。在模式中定义的每种关系都隐式具有相应的反向链接。

您可以使用 @links.<ObjectType>.<PropertyName> 语法访问查询中的反向链接，其中 <ObjectType> 和 <PropertyName> 是指对象类型上引用所查询对象类型的特定属性。

// Find items that belong to a project with a quota greater than 10 (@links)
"@links.Project.items.quota > 10"

您还可以定义一个linkingObjects属性，以在数据模型中显式包含反向链接。 这样，您就可以使用标准点表示法通过分配的属性名称来引用反向链接。

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

反向链接的结果被视为一个集合，并支持集合操作符。

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

您可以在反向链接集合上使用聚合操作符。

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

您可以直接在 @links 上使用 @count 操作符来查询指向对象的所有关系的计数。

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

子查询

使用 SUBQUERY() 谓词函数通过另一个查询来遍历列表属性。

子查询对于以下场景很有用：

• 在多个条件下匹配列表属性中的每个对象

• 计算与子查询匹配的对象数量

SUBQUERY() 具有以下结构：

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

• collection：要遍历的属性的名称

• variableName：要在子查询中使用的元素的变量名称

• predicate：子查询谓词。使用 variableName 指定的变量来引用当前遍历的元素。

子查询遍历给定的集合，并针对集合中的每个对象检查给定的谓词。谓词可以引用当前遍历的对象，并将变量名称传递给 SUBQUERY()。

子查询表达式解析为对象列表。Realm 仅支持对子查询结果使用 @count 聚合操作符。这样就可以计算子查询输入集合中有多少个对象与谓词匹配。

您可以像使用有效表达式中的任何其他数字一样来使用子查询结果的计数。特别是，您可以将计数与数字 0 进行比较以返回所有匹配的对象。

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

排序、去重和限制

使用另一些操作符对查询结果集合进行排序和限制。

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

灵活同步 RQL 限制

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