本节介绍文档 ID 是什么以及如何使用它。

每个文档都有一个称为文档 ID 的唯一标识符，可以将其视为表主键的等效项。文档 ID 值通常在添加文档时由服务器自动生成，但也可以手动分配。分配的文档 ID 在 collection.add() 操作的 Result（Connector/J 中为 AddResult）对象的 generatedIds 属性中返回，并且可以使用 getGeneratedIds() 方法访问。有关文档 ID 的更多背景信息，请参阅第 5.3 节，“了解文档 ID”。

以下 JavaScript 代码示例显示了将文档添加到集合、检索添加的文档的 ID 以及测试是否可以添加重复 ID。

mysql-js > var result = mycollection.add({test:'demo01'}).execute()
mysql-js > print(result.generatedIds)
[
    "00006075f6810000000000000006"
]
mysql-js > var result = mycollection.add({test:'demo02'}).add({test:'demo03'}).execute()
mysql-js > print(result.generatedIds)
[
    "00006075f6810000000000000007",
    "00006075f6810000000000000008"
]

mysql-js > mycollection.find()
{
    "_id": "00006075f6810000000000000006",
    "test": "demo01"
}
{
    "_id": "00006075f6810000000000000007",
    "test": "demo02"
}
{
    "_id": "00006075f6810000000000000008",
    "test": "demo03"
}
3 documents in set (0.0102 sec)
mysql-js > var result = mycollection.add({_id:'00006075f6810000000000000008', test:'demo04'}).execute()
Document contains a field value that is not unique but required to be (MySQL Error 5116)

如上例所示，文档 ID 存储在文档的 _id 字段中。文档 ID 是一个最大长度为 32 个字符的 VARBINARY()。如果在创建文档时提供了 _id，则会采用该值；如果没有提供 _id，则会自动为文档分配一个。

以下示例说明了如何提供或自动生成 _id 值。假设 test 模式存在并分配给变量 db，集合 my_collection 存在，并且 custom_id 是唯一的。

# If the _id is provided, it will be honored
result = myColl.add( { '_id': 'custom_id', 'a' : 1 } ).execute()
document = myColl.find('a = 1').execute().fetch_one()
print("User Provided Id: %s" % document._id)

# If the _id is not provided, one will be automatically assigned
result = myColl.add( { 'b': 2 } ).execute()
print("Autogenerated Id: %s" % result.get_generated_ids()[0])

某些文档具有自然的唯一键。例如，包含书籍列表的集合可能会为表示书籍的每个文档包含国际标准书号 (ISBN)。ISBN 是一个长度为 13 个字符的字符串，完全在 _id 字段的 32 个字符的长度限制内。

// using a book's unique ISBN as the object ID
myColl.add( {
_id: "978-1449374020",
title: "MySQL Cookbook: Solutions for Database Developers and Administrators"
}).execute();

使用 find() 按其文档 ID 从集合中获取新插入的书籍。

var book = myColl.find('_id = "978-1449374020"').execute();

目前，X DevAPI 不支持使用除隐式 _id 以外的任何文档字段作为文档 ID - 无法定义另一个键来执行相同的功能。