Insert documents (HTTP)
|
For details about additional languages, see: |
Inserts multiple documents 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 for each document.
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 documents and returns a JSON object that includes the IDs of the inserted documents.
The ID value depends on the ID type. For more information, see Document IDs (HTTP).
Example response:
{
"status": {
"insertedIds": [
"3f557bef-fd53-47ea-957b-effd53c7eaec",
101,
"132ffr343"
]
}
}Signature
Use the insertMany 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 '{
"insertMany": {
"documents": DOCUMENTS_JSON_ARRAY,
"options": {
"ordered": BOOLEAN,
}
}
}'Parameters
| Name | Type | Summary |
|---|---|---|
|
|
An array of JSON objects describing the documents 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. |
|
|
Optional.
The options for this operation. See Properties of |
| Name | Type | Summary |
|---|---|---|
|
|
Optional.
Whether the insertions must be processed sequentially.
If For an example, see Insert documents and specify insertion behavior. Default: |
Examples
The following examples demonstrate how to insert multiple documents into a collection.
Insert documents
The documents can have different structures.
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertMany": {
"documents": [
{
"name": "Jane Doe",
"age": 42
},
{
"nickname": "Bobby",
"color": "blue",
"foods": ["carrots", "chocolate"]
}
]
}
}'Insert documents with vector embeddings
Use the reserved $vector field to insert documents with pregenerated vector embeddings.
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 may also insert a mix of documents with and without the $vector field.
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 '{ "insertMany": { "documents": [ { "name": "Jane Doe", "age": 42, "$vector": [0.08, -0.62, 0.39] }, { "nickname": "Bobby", "$vector": [0.12, 0.53, 0.32] } ] } }' - $binary
-
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \ --header "Token: APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "insertMany": { "documents": [ { "name": "Jane Doe", "age": 42, "$vector": {"$binary": "PaPXCr8euFI+x64U"} }, { "nickname": "Bobby", "$vector": {"$binary": "PfXCjz8HrhQ+o9cK"} } ] } }'
Insert documents and specify the IDs
You can specify the _id field directly, or you can use the objectId, uuid, uuidv6, or uuidv7 types.
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertMany": {
"documents": [
{
"name": "Melissa",
"_id": { "$objectId": "6672e1cbd7fabb4e5493916f" }
},
{
"name": "Jess",
"_id": { "$uuid": "1ef2e42c-1fdb-6ad6-aae4-e84679831739" }
},
{
"name": "Jane",
"_id": 1
},
{
"name": "Bobby",
"_id": "b_023"
}
]
}
}'Insert documents and specify insertion behavior
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"insertMany": {
"documents": [
{
"name": "Jane Doe",
"age": 42
},
{
"nickname": "Bobby",
"color": "blue",
"foods": ["carrots", "chocolate"]
}
],
"options": {
"ordered": false
}
}
}'Insert documents 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 '{
"insertMany": {
"documents": [
{
"exampleBinary": {"$binary": "PfvnbT7peNU/Sfvn"}
}
]
}
}'Insert documents 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 '{
"insertMany": {
"documents": [
{
"title": "Hidden Shadows of the Past",
"genres": ["Biography", "Graphic Novel", "Dystopian", "Drama"],
"metadata": {
"isbn": "978-1-905585-40-3",
"language": "French",
"edition": "Anniversary Edition"
}
},
{
"title": "Bake a Dozen",
"genres": ["Biography", "Fiction"],
"metadata": {
"isbn": "342-2-875587-50-2",
"language": "English",
"edition": "Illustrated Edition"
}
}
]
}
}'