X DevAPI User Guide
This sections describes in detail how document IDs are generated
and how to interpret them. X DevAPI relies on server-based
document ID generation, which results in sequentially increasing
document IDs across all clients.
InnoDB uses the document ID as a
primary key, resulting in efficient page splits and tree
reorganizations.
This section describes the properties and format of the automatically generated document IDs.
The _id field of a document behaves in the
same way as any other fields of the document during queries,
except that its value cannot be changed once it has been
inserted to the collection. The _id field is
used as the primary key of the collection
. It is possible to override the automatic generation of
document IDs by manually including an ID in an inserted
document.
X Plugin is not aware of the data inserted into the collection, including any manual document IDs you use. When using manual document IDs, you must ensure that they do not clash with any IDs that might ever be generated automatically by the server (see Document ID Generation for details), in order to avoid any errors due to primary key duplication.
Whenever an _id field value is not present in
an inserted document, the server generates an
_id value. The generated
_id value used for a document is returned to
the client as part of the Result
(Result for Connector/J) object of the
add() operation. If you are using X DevAPI
on an InnoDB Cluster, the automatically generated
_id must be unique within the whole cluster.
By setting the
mysqlx_document_id_unique_prefix
to a unique value per cluster instance, you can ensure document
IDs are unique across all the instances.
The _id field must be sequential (always
incrementing) for optimal InnoDB insertion performance (at least
within a single server). The sequential nature of
_id values is maintained across server
restarts.
In a multi-primary Group Replication or InnoDB Cluster
environment, the generated _id values of a
table are unique across instances to avoid primary key conflicts
and minimize transaction certification.
This section describes how document IDs are formatted.
The format of automatically generated document ID is:
| unique_prefix | start_timestamp | serial |
|---|---|---|
| 4 bytes | 8 bytes | 16 bytes |
Where:
unique_prefix is a value assigned by
InnoDB Cluster to the instance, which is used to make the
document ID unique across all instances from the same
cluster. The range of unique_prefix is
from 0 to 216-1, which is hex
encoded. Default value is 0, if it is neither set by
InnoDB Cluster nor by the
mysqlx_document_id_unique_prefix
system variable.
start_timestamp is the time stamp of the
startup time of the server instance, which is hex encoded.
In the unlikely event that the value of
serial overflows, the
start_timestamp is incremented by 1 and
the serial value then restarts at 0.
serial is a per-instance automatically
incremented integer serial number value, which is hex
encoded and has a range of 0 to
264-1. The initial value of
serial is set to the
auto_increment_offset
system variable, and the increment of the value is set by
the
auto_increment_increment
system variable.
This document ID format ensures that:
The primary key value monotonically increments for inserts originating from a single server instance, although the interval between values is not uniform within a table.
When using multi-primary Group Replication or
InnoDB Cluster, inserts to the same table from different
instances do not have conflicting primary key values, as
long as the instances have the
auto_increment_offset and
the
auto_increment_increment
system variables configured properly (see descriptions of
the variables for details).