Update Existing Documents
Update an array of documents in a given index.
Each document must contain an _id
field to identify the document to update.
Only document fields and values you want to update should be in the request.
This endpoint only works for existing documents in structured indexes right now.
Use this endpoint to update documents in a structured index by modifying the existing fields or adding
new fields to the document. You can only modify or add fields that are not tensor fields or the dependent fields of a
multimodal combination field. If the document does not exist, please check the
add_documents endpoint.
If you need to update a tensor field, a multimodal combination dependent field, or a
document in unstructured index, check the useExistingTensors
feature.
This endpoint accepts the application/json
content type.
PATCH /indexes/{index_name}/documents
Path parameters
Name | Type | Description |
---|---|---|
index_name |
String | name of the index (structured index only) |
Body
In the RestAPI and for cURL
users these parameters are in lowerCamelCase
, as presented in the following table. The
Python client uses the pythonic snake_case
equivalents.
Add documents parameters | Value Type | Default Value | Description |
---|---|---|---|
documents |
Array of objects | n/a | An array of documents. Each document is represented as a JSON object. Each document must contain a valid _id field to specify the target document. You only need to include the fields you want to update in the JSON object. You cannot update a tensor field in a structured index. |
Response
The response of the update_documens
endpoint in Marqo operates on two levels.
Firstly, a status code of 200
in the overall response indicates that the batch request has been successfully received and processed by Marqo.
The response has the following fields:
Field Name | Type | Description |
---|---|---|
errors |
Boolean | Indicates whether any errors occurred during the processing of the batch request. |
items |
Array | An array of objects, each representing the processing status of an individual document in the batch. |
processingTimeMs |
Integer | The time taken to process the batch request, in milliseconds. |
index_name |
String | The name of the index to which the documents were added. |
However, a 200
status does not necessarily imply that each individual document within the batch was processed without
issues.
For each document in the batch, there will be an associated response code that specifies the status of that particular
document's processing.
These individual response codes provide granular feedback,
allowing users to discern which documents were successfully processed, which encountered errors, and the nature of any
issues encountered.
Each item in the items
array has the following fields:
Field Name | Type | Description |
---|---|---|
_id |
String | The ID of the document that was processed. |
status |
Integer | The status code of the document processing. |
message |
String | A message that provides additional information about the processing status of the document. This field only exists when the status is not 200 . |
Here is the HTTP status code of the individual document responses (non-exhaustive list of status codes):
Status Code | Description |
---|---|
200 |
The document is updated successfully. |
400 |
Bad request. Returned for invalid input (e.g., invalid field types). Inspect message for details. |
404 |
The target document is not in the index. |
429 |
Marqo vector store receives too many requests. Please try again later. |
500 |
Internal error. |
Example
# Let's create a structured index an add a document to it
curl -X POST 'http://localhost:8882/indexes/my-first-structured-index' \
-H "Content-Type: application/json" \
-d '{
"type": "structured",
"allFields": [
{"name": "img", "type": "image_pointer"},
{"name": "title", "type": "text"},
{"name": "label", "type": "text", "features": ["filter"]}
],
"model": "open_clip/ViT-B-32/laion2b_s34b_b79k",
"tensorFields": ["img", "title"]
}'
curl -X POST 'http://localhost:8882/indexes/my-first-structured-index/documents' \
-H "Content-Type: application/json" \
-d '{
"documents":[
{
"img": "https://github.com/marqo-ai/marqo/blob/mainline/examples/ImageSearchGuide/data/image0.jpg?raw=true",
"title": "A lady taking a phote",
"label": "lady",
"_id": "1"
},
{
"img": "https://github.com/marqo-ai/marqo/blob/mainline/examples/ImageSearchGuide/data/image1.jpg?raw=true",
"title": "A plane flying in the sky",
"label": "airplane",
"_id": "2"
}
]
}'
# Now let's update the document by changing the label
curl -X PATCH 'http://localhost:8882/indexes/my-first-structured-index/documents' \
-H "Content-Type: application/json" \
-d '{
"documents":[
{
"label": "person",
"_id": "1"
},
{
"_id": "2",
"label": "plane"
}
]
}'
# Let's create a structured index an add a document to it
mq.create_index(
"my-first-structured-index",
type="structured",
all_fields=[
{"name": "img", "type": "image_pointer"},
{"name": "title", "type": "text"},
{"name": "label", "type": "text", "features": ["filter"]},
],
model="open_clip/ViT-B-32/laion2b_s34b_b79k",
tensor_fields=["img", "title"],
)
mq.index("my-first-structured-index").add_documents(
[
{
"img": "https://github.com/marqo-ai/marqo/blob/mainline/examples/ImageSearchGuide/data/image0.jpg?raw=true",
"title": "A lady taking a phote",
"label": "lady",
"_id": "1",
},
{
"img": "https://github.com/marqo-ai/marqo/blob/mainline/examples/ImageSearchGuide/data/image1.jpg?raw=true",
"title": "A plane flying in the sky",
"label": "airplane",
"_id": "2",
},
]
)
# Now let's update the document by changing the label
mq.index("my-first-structured-index").update_documents(
[{"_id": "1", "label": "person"}, {"_id": "2", "label": "plane"}]
)
For Marqo Cloud, you will need to access the endpoint of your index and replace your_endpoint
with this. To do this, visit Find Your Endpoint. You will also need your API Key. To obtain this key visit Find Your API Key.
# Let's create a structured index an add a document to it
curl -X POST 'https://api.marqo.ai/api/v2/indexes/my-first-structured-index' \
-H 'x-api-key: XXXXXXXXXXXXXXX' \
-H "Content-Type: application/json" \
-d '{
"type": "structured",
"allFields": [
{"name": "img", "type": "image_pointer"},
{"name": "title", "type": "text"},
{"name": "label", "type": "text", "features": ["filter"]}
],
"model": "open_clip/ViT-B-32/laion2b_s34b_b79k",
"tensorFields": ["img", "title"]
}'
curl -X POST your_endpoint/indexes/my-first-structured-index/documents' \
-H 'x-api-key: XXXXXXXXXXXXXXX' \
-H "Content-Type: application/json" \
-d '{
"documents":[
{
"img": "https://github.com/marqo-ai/marqo/blob/mainline/examples/ImageSearchGuide/data/image0.jpg?raw=true",
"title": "A lady taking a phote",
"label": "lady",
"_id": "1"
},
{
"img": "https://github.com/marqo-ai/marqo/blob/mainline/examples/ImageSearchGuide/data/image1.jpg?raw=true",
"title": "A plane flying in the sky",
"label": "airplane",
"_id": "2"
}
]
}'
# Now let's update the document by changing the label
curl -X PATCH 'your_endpoint/indexes/my-first-structured-index/documents' \
-H 'x-api-key: XXXXXXXXXXXXXXX' \
-H "Content-Type: application/json" \
-d '{
"documents":[
{
"label": "person",
"_id": "1"
},
{
"_id": "2",
"label": "plane"
}
]
}'
# Let's create a structured index an add a document to it
mq.create_index(
"my-first-structured-index",
type="structured",
all_fields=[
{"name": "img", "type": "image_pointer"},
{"name": "title", "type": "text"},
{"name": "label", "type": "text", "features": ["filter"]},
],
model="open_clip/ViT-B-32/laion2b_s34b_b79k",
tensor_fields=["img", "title"],
)
mq.index("my-first-structured-index").add_documents(
[
{
"img": "https://github.com/marqo-ai/marqo/blob/mainline/examples/ImageSearchGuide/data/image0.jpg?raw=true",
"title": "A lady taking a phote",
"label": "lady",
"_id": "1",
},
{
"img": "https://github.com/marqo-ai/marqo/blob/mainline/examples/ImageSearchGuide/data/image1.jpg?raw=true",
"title": "A plane flying in the sky",
"label": "airplane",
"_id": "2",
},
]
)
# Now let's update the document by changing the label
mq.index("my-first-structured-index").update_documents(
[{"_id": "1", "label": "person"}, {"_id": "2", "label": "plane"}]
)
Response 200 OK
{
'errors': false,
'index_name': 'my-first-structured-index',
'items': [
{
'_id': '1',
'status': 200
},
{
'_id': '2',
'status': 200
}
],
'processingTimeMs': 20.17
}
The update document endpoint is only available for structured indexes to update the fields of existing documents.
In the example, we updated the label of the documents with _id
fields "1"
and "2"
.
The response shows that the update was successful. These changes are reflected in the index and can be used for search and
filtering. Note that you can only update fields that are not tensor fields.
Documents
Parameter: documents
Expected value: Array of documents (default maximum length: 128). Each document is a JSON object that must
contain a valid _id
field to specify the target document. You only need to include the fields you want to update in
the JSON object.
[
{
"Title": "You updated title 1 ",
"Description": "You updated description 1 ",
"_id": "your-target-doc-id-1"
},
{
"Title": "You updated title 2 ",
"Description": "You updated description 2",
"_id": "your-target-doc-id-2"
}
]