属性注解 - Kotlin SDK

在此页面上

指定主键

将属性或类映射到其他名称
忽略来自 Realm 模式的属性
索引属性
全文搜索索引

Atlas Device SDK 已弃用。有关详细信息，请参阅弃用页面。

本页介绍可用于自定义对象模型中属性行为的可用注释。有关如何定义对象模型的更多信息，请参阅定义 Realm 对象模型 - Kotlin SDK。

Kotlin SDK提供了多个属性注解，可为Realm 对象属性添加功能。另请参阅注解API参考文档。

注意

属性声明

在 Kotlin 中，值类型隐式不可为 null。您可以使用内置的 ? Kotlin 操作符将属性声明为可选（可为 null）。或者可以在属性声明中为属性指定默认值。有关示例，请参阅支持的数据类型列表。

本页上的示例引用以下 Frog 类：

class Frog : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId() // Primary key property
    @Index
    var name: String = "" // Indexed property
    @Ignore
    var age: Int = 0 // Ignored property
    @PersistedName("latin_name")
    var species: String? = null // Remapped property
    @FullText
    var physicalDescription: String? = null // Full-text search indexed property
}

指定主键

主键是 Realm 中对象的唯一标识符。同一类型的其他对象不能共享对象的主键。

要指定某个属性作为对象类型的主键，请使用 @PrimaryKey 注解：

@PrimaryKey
var _id: ObjectId = ObjectId() // Primary key property

主键的重要方面：

您只能为每个对象模式定义一个主键。
将某个类型的任何对象添加到 Realm 后，您无法更改该对象类型的主键字段。
主键值必须在 Realm 内某一对象的所有实例中保持唯一。尝试插入重复的主键值会导致错误。
主键值不可变。要更改某一对象的主键值，必须删除原始对象并插入具有其他主键值的新对象。
主键可为 null。由于主键值必须是唯一的，因此 null 只能是集合中一个对象的主键。
Realm 自动对主键创建索引，因此您可以根据主键有效地读取和修改对象。

您可以使用以下任何类型创建主键：

String
Byte
Char
Short
Int
Long
ObjectId
RealmUUID

重要

Device Sync 需要 _id 主键字段

如果您使用 Device Sync，则对象模型必须包含名为 _id 的主键字段，其类型必须为 String、Int 或 ObjectId。

有关更多信息，请参阅使用 Device Sync 对数据建模 - Kotlin SDK。

将属性或类映射到其他名称

版本 10.8.0 中的新增功能：使用 @PersistedName 重新映射类名

默认情况下，Realm 使用模型类中定义的名称来表示内部的类和字段。 Kotlin SDK 允许您将属性或类名映射到与代码中使用的名称不同的持久名称。在某些情况下，为该领域保留不同的名称很有用，包括：

要便于在具有不同命名约定的多个平台上工作。例如，如果 Device Sync 模式属性名称使用蛇形大小写，而项目使用驼峰大小写。
在不强制迁移的情况下更改Kotlin 中的类名或字段名。
支持不同软件包中具有相同简单名称的多个模型类。
要使用长度大于 Realm 执行的 57 个字符限制的类名。

要将代码中的 Kotlin 类或属性名称映射到不同名称以保留在 Realm 中，请执行以下操作：

在 Kotlin 类或属性上使用 @PersistedName 注解。
指定要保留到 Realm 的类或属性 name。

在此示例中，Frog 是整个项目代码中用于执行增删改查操作的 Kotlin 类名称，而 Frog_Entity 是用于在域中存储对象的持久名称：

@PersistedName(name = "Frog_Entity") // Remapped class name
class Frog : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var age: Int = 0
    var species: String? = null
    var owner: String? = null
}

重要

通过重映射类名进行查询

在具有重新映射的类名称的对象上查询反向关系时，您必须使用持久保存的类名称。在以上示例中，您必须查询 Frog_Entity 而不是 Frog。有关更多信息，请参阅查询反向关系。

在此示例中，species 是整个项目代码中用于执行Kotlin CRUD改查操作的属性名称，latin_name 是用于在 Realm 中存储值的持久名称：

@PersistedName("latin_name")
var species: String? = null // Remapped property

提示

按重新映射的属性名称进行查询

您可以通过代码中使用的 Kotlin 名称以及 Realm 中存储的持久名称进行查询。有关更多信息，请参阅 :ref:``

如果写入同步 Realm，则同步模式会看到使用持久类或属性名称存储的值。请注意以下事项：

迁移必须使用持久化的类或属性名称。
任何模式错误报告都使用持久化名称。

忽略来自 Realm 模式的属性

默认情况下，Realm 管理 Realm 对象模型中定义的属性。但是，您可以选择忽略不想保留在 Realm 中的属性。

要忽略某个属性并阻止其在某个域中持久化，请使用 @Ignore 注解：

@Ignore
var age: Int = 0 // Ignored property

被忽略属性的行为与被托管属性完全相同，只是前者不存储到 Realm 数据库中，不能在查询中使用，并且不会触发 Realm 通知。可在类中混用被托管属性和被忽略属性。

索引属性

索引是特殊的数据结构，它以易于遍历的形式存储一小部分 realm 数据。索引支持在 Realm 中更高效地执行查询。如果查询存在适当的索引，Realm 会使用该索引来限制必须检查的文档数量。否则，Realm 必须扫描集合中的每个文档并选择与查询匹配的文档。

索引存储按字段值排序的特定字段的值。索引条目的排序支持高效的相等匹配和基于范围的查询操作。虽然索引可以加快某些查询的速度，但它们也会导致写入速度稍慢。会带来额外的存储和内存开销。Realm 将索引存储在磁盘上，这会使您的 Realm 文件更大。每个索引条目至少有 12 个字节。

要在属性上创建索引，请在属性上使用 @Index 注释：

@Index
var name: String = "" // Indexed property

注意

默认情况下会对主键建立索引。

您可以为以下类型的字段建立索引：

String
Byte
Short
Int
Long
Boolean
RealmInstant
ObjectId
RealmUUID

您不能将标准索引与同一属性上的全文Atlas Search (FTS) 索引结合使用。要在属性上创建 FTS 索引，请参阅全文Atlas Search索引部分。

全文搜索索引

除了标准索引外，Realm 还支持对 String 属性创建 Atlas 全文搜索索引。虽然无论是否使用标准索引都可以查询字符串字段，但 FTS 索引支持搜索多个词汇和短语并排除其他。

要在属性上创建 FTS 索引，请使用 @FullText 注解：

@FullText
var physicalDescription: String? = null // Full-text search indexed property

请注意全文搜索索引的以下限制：

您只能在 String 类型的属性上创建 FTS 索引。
您不能在同一属性上组合使用 FTS 索引和标准索引。要在属性上创建标准索引，请参阅索引属性部分。

注意

全文搜索索引的字符限制

对于全文搜索 (FTS) 索引，索引中只包括 ASCII 和 Latin-1 字母数字字符（大多数西方语言）。

索引不区分变音符号和大小写。

有关查询全文索引的更多信息，请参阅按全文搜索 (FTS) 属性过滤。

后退

支持的数据类型

来年

关系