Insert a document (HTTP)
|
For details about additional languages, see: |
Inserts a single document into a collection.
Documents are stored in collections. They represent a single row or record of data in Hyper-Converged Database (HCD) databases. For more information, see About collections with the Data API (HTTP).
If the collection is vector-enabled, pregenerated vector embeddings can be included by using the reserved $vector field.
You can later use the $vector field to perform a vector search.
|
Ready to write code? See the examples for this method to get started. |
Result
Inserts the specified document and returns a JSON object that includes the ID of the inserted document.
The ID value depends on the ID type. For more information, see Document IDs (HTTP).
Example response:
{
"status": {
"insertedIds": [
"3f557bef-fd53-47ea-957b-effd53c7eaec"
]
}
}Signature
Use the insertOne command.
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertOne": {
"document": DOCUMENT_JSON_OBJECT
}
}'Parameters
| Name | Type | Summary |
|---|---|---|
|
|
A JSON object describing the document to insert. A document can contain user-defined and reserved fields. User-defined field names can be any non-empty sequence of Unicode characters, with the following exceptions:
Reserved fields are tied to specific functionality. Include the following reserved fields in your documents, if applicable:
For examples, see Examples. |
Examples
The following examples demonstrate how to insert a document into a collection.
Insert a document
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertOne": {
"document": {
"title": "Hidden Shadows of the Past",
"genres": ["Biography", "Graphic Novel", "Dystopian", "Drama"],
"metadata": {
"isbn": "978-1-905585-40-3",
"language": "French",
"edition": "Anniversary Edition"
},
"number_of_pages": 245
}
}
}'Insert a document with vector embeddings
Use the reserved $vector field to insert a document with pregenerated vector embeddings.
You can later use this field to perform a vector search.
All embeddings in the collection should use the same provider, model, and dimensions. Mismatched embeddings can cause inaccurate vector searches.
The $vector field is only supported for vector-enabled collections.
For more information, see Create a collection that can store vector embeddings and $vector in collections (HTTP).
You can provide the vector embeddings as an array of floats, or you can use $binary to provide the vector embeddings as a Base64-encoded string.
$binary can be more performant.
For more information about how to convert an array of floats to a Base64-encoded string, see Binary encoding of vector embeddings.
- Array of floats
-
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \ --header "Token: APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "insertOne": { "document": { "name": "Jane Doe", "$vector": [0.08, -0.62, 0.39] } } }' - $binary
-
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \ --header "Token: APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "insertOne": { "document": { "name": "Jane Doe", "$vector": {"$binary": "PaPXCr8euFI+x64U"} } } }'
Insert a document and specify the ID
You can specify the _id field directly, or you can use the objectId, uuid, uuidv6, or uuidv7 types.
Example specifying an integer:
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertOne": {
"document": {
"name": "Jane Doe",
"_id": 1
}
}
}'Example using the objectId type:
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertOne": {
"document": {
"name": "Jane Doe",
"_id": { "$objectId": "6672e1cbd7fabb4e5493916f" }
}
}
}'Insert a document with a binary field
You can insert binary data as a Base64-encoded string with $binary.
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertOne": {
"document": {
"exampleBinary": {"$binary": "PaPXCr8euFI+x64U"}
}
}
}'Insert a document with nested fields
Although you can use dot notation in a filter to find a document, you cannot use dot notation to insert a document. To specify nested fields in the inserted document, you must build a map, list, or set.
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertOne": {
"document": {
"title": "Hidden Shadows of the Past",
"genres": ["Biography", "Graphic Novel", "Dystopian", "Drama"],
"metadata": {
"isbn": "978-1-905585-40-3",
"language": "French",
"edition": "Anniversary Edition"
}
}
}
}'