This section describes what a document ID is and how to work with it.
Every document has a unique identifier called the document ID,
which can be thought of as the equivalent of a table's primary
key. The document ID value is usually automatically generated by
the server when the document is added, but can also be manually
assigned. The assigned document ID is returned in the
generatedIds
property of the
Result
(AddResult
for
Connector/J) object for the collection.add()
operation and can be accessed using the
getGeneratedIds()
method. See
Section 5.3, “Understanding Document IDs” for more
background information on document IDs.
The following example in JavaScript code shows adding a document to a collection, retrieving the added document's IDs and testing that duplicate IDs cannot be added.
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)
As shown in the example above, the document ID is stored in the
_id
field of a document. The document ID is a
VARBINARY()
with a maximum length
of 32 characters. If an _id
is provided when a
document is created, it is honored; if no _id
is provided, one is automatically assigned to the document.
The following example illustrates how the _id
value can either be provided or autogenerated. It is assumed that
the test
schema exists and is assigned to the
variable db
, that the collection
my_collection
exists and that
custom_id
is unique.
# 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])
Some documents have a natural unique key. For example, a
collection that holds a list of books is likely to include the
International Standard Book Number (ISBN) for each document that
represents a book. The ISBN is a string with a length of 13
characters, which is well within the length limit of 32 characters
for the _id
field.
// 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();
Use find()
to fetch the newly inserted book
from the collection by its document ID.
var book = myColl.find('_id = "978-1449374020"').execute();
Currently, X DevAPI does not support using any document field
other than the implicit _id
as the document
ID—there is no way to define another key to perform the same
function.