MySQL :: X DevAPI 用户指南 (适用于 Python 模式下的 MySQL Shell) :: 5.3 了解文档 ID

X DevAPI 用户指南 (适用于 Python 模式下的 MySQL Shell) / 使用文档 / 了解文档 ID

5.3 了解文档 ID

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

本节介绍自动生成文档 ID 的属性和格式。

文档 ID 属性

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

重要

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

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

_id 字段必须是顺序的（始终递增）才能获得最佳的 InnoDB 插入性能（至少在单个服务器内）。 _id 值的顺序性质在服务器重启后仍然保持。

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

文档 ID 生成

本节介绍了文档 ID 的格式。

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

unique_prefix	start_timestamp	serial
4 字节	8 字节	16 字节

其中

unique_prefix 是 InnoDB 集群分配给实例的值，用于使文档 ID 在来自同一个集群的所有实例中都是唯一的。 unique_prefix 的范围为 0 到 2¹⁶-1，用十六进制编码。默认值为 0，如果它既不是由 InnoDB 集群设置的，也不是由 mysqlx_document_id_unique_prefix 系统变量设置的。
start_timestamp 是服务器实例启动时间的的时间戳，用十六进制编码。在极不可能的事件中，如果 serial 的值溢出，则 start_timestamp 递增 1，然后 serial 值从 0 重新开始。
serial 是每个实例的自动递增整数序列号值，用十六进制编码，其范围为 0 到 2⁶⁴-1。 serial 的初始值设置为 auto_increment_offset 系统变量，值的增量由 auto_increment_increment 系统变量设置。

这种文档 ID 格式确保了

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