属性注解 - Kotlin SDK

指定主键

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

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

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

主键的重要方面：

• 您只能为每个对象模式定义一个主键。

• 将某个类型的任何对象添加到 Realm 后，您无法更改该对象类型的主键字段。

• 主键值必须在 Realm 内某一对象的所有实例中保持唯一。尝试插入重复的主键值会导致错误。

• 主键值不可变。要更改某一对象的主键值，必须删除原始对象并插入具有其他主键值的新对象。

• 主键可为 null。由于主键值必须是唯一的，因此 null 只能是集合中一个对象的主键。

• Realm 自动对主键创建索引，因此您可以根据主键有效地读取和修改对象。

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

• String

• Byte

• Char

• Short

• Int

• Long

• ObjectId

• RealmUUID

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

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

• 要便于在具有不同命名约定的多个平台上工作。例如，如果 Device Sync 模式属性名称使用蛇形大小写，而项目使用驼峰大小写。

• 在不强制迁移的情况下更改Kotlin 中的类名或字段名。

• 支持不同软件包中具有相同简单名称的多个模型类。

• 要使用长度大于 Realm 执行的 57 个字符限制的类名。

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

1. 在 Kotlin 类或属性上使用 @PersistedName 注解。

2. 指定要保留到 Realm 的类或属性 name。

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

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

如果写入同步 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) 属性过滤。