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.

Example

cURLPython

# 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"}]
)

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"
  }
]