В этом разделе описывается, что такое идентификатор документа и как с ним работать.

Каждый документ имеет уникальный идентификатор, называемый идентификатором документа, который можно рассматривать как аналог первичного ключа таблицы. Значение идентификатора документа обычно автоматически генерируется сервером при добавлении документа, но его также можно назначить вручную. Назначенный идентификатор документа возвращается в свойстве generatedIds объекта Result (AddResult для Connector/J) для операции collection.add() и может быть получен с помощью метода getGeneratedIds(). Более подробную информацию об идентификаторах документов см. в разделе 5.3 «Понимание идентификаторов документов».

Следующий пример кода на JavaScript демонстрирует добавление документа в коллекцию, получение идентификаторов добавленного документа и проверку невозможности добавления дублирующих идентификаторов.

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 документа. Идентификатор документа является строкой с максимальной длиной 32 символа. Если при создании документа предоставлен _id, он используется; если _id не предоставлен, он автоматически назначается документу.

Следующий пример демонстрирует, как значение _id можно предоставить или сгенерировать автоматически. Предполагается, что схема test существует и присвоена переменной db, что коллекция my_collection существует и что custom_id уникальна.

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

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

Некоторые документы имеют естественный уникальный ключ. Например, коллекция, содержащая список книг, вероятно, будет включать Международный стандартный номер книги (ISBN) для каждого документа, представляющего книгу. ISBN представляет собой строку длиной 13 символов, что находится в пределах допустимого ограничения длины 32 символа для поля _id.

// 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(), чтобы получить только что вставленную книгу из коллекции по её идентификатору документа.

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

В настоящее время X DevAPI не поддерживает использование любого поля документа, кроме неявного поля _id, в качестве идентификатора документа — нет способа определить другой ключ для выполнения той же функции.