MySQL :: X DevAPI 用户指南 :: 5.3 了解文档 ID

5.3 了解文档 ID

本节详细描述了文档 ID 的生成方式以及如何解释它们。X DevAPI 依赖于基于服务器的文档 ID 生成，这会导致所有客户端的文档 ID 顺序递增。InnoDB 使用文档 ID 作为主键，从而实现高效的页面拆分和树重组。

本节描述了自动生成的文档 ID 的属性和格式。

文档 ID 属性

文档的 _id 字段在查询期间的行为与文档的任何其他字段相同，只是其值在插入到集合后无法更改。_id 字段用作集合的主键。可以通过在插入的文档中手动包含 ID 来覆盖自动生成文档 ID 的功能。

重要

X 插件不知道插入到集合中的数据，包括您使用的任何手动文档 ID。使用手动文档 ID 时，您必须确保它们不会与服务器自动生成的任何 ID 冲突（有关详细信息，请参阅文档 ID 生成），以避免因主键重复而导致任何错误。

每当插入的文档中不存在 _id 字段值时，服务器都会生成一个 _id 值。用于文档的生成的 _id 值作为 add() 操作的 Result（Connector/J 为 Result）对象的一部分返回给客户端。如果您在 InnoDB 集群上使用 X DevAPI，则自动生成的 _id 在整个集群中必须是唯一的。通过将每个集群实例的mysqlx_document_id_unique_prefix 设置为唯一值，可以确保文档 ID 在所有实例中都是唯一的。

为了获得最佳的 InnoDB 插入性能（至少在单个服务器内），_id 字段的值必须是连续的（始终递增）。_id 值的顺序性在服务器重启后保持不变。

在多主组复制或 InnoDB 集群环境中，表的生成的 _id 值在实例之间是唯一的，以避免主键冲突并最大程度地减少事务认证。

文档 ID 生成

本节介绍文档 ID 的格式。

自动生成的文档 ID 的格式为

唯一前缀	开始时间戳	序列号
4 字节	8 字节	16 字节

其中

唯一前缀 是 InnoDB 集群分配给实例的值，用于使文档 ID 在来自同一集群的所有实例中都是唯一的。唯一前缀 的范围为 0 到 2¹⁶-1，采用十六进制编码。默认值为 0，如果它既没有由 InnoDB 集群设置，也没有由mysqlx_document_id_unique_prefix 系统变量设置。
开始时间戳 是服务器实例启动时间的時間戳，采用十六进制编码。在 序列号 的值溢出的极少数情况下，开始时间戳 会增加 1，然后 序列号 值从 0 重新开始。
序列号 是一个自动递增的整数序列号值，采用十六进制编码，范围为 0 到 2⁶⁴-1。序列号 的初始值设置为auto_increment_offset 系统变量，该值的增量由auto_increment_increment 系统变量设置。

此文档 ID 格式可确保

对于源自单个服务器实例的插入，主键值单调递增，尽管值之间的间隔在表中不均匀。
使用多主组复制或 InnoDB 集群时，只要实例的auto_increment_offset 和auto_increment_increment 系统变量配置正确（有关详细信息，请参阅变量的描述），从不同实例插入到同一表的插入就不会出现主键值冲突。