> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update documents

> Apply partial updates to documents in a namespace. Documents are selected either per ID with `documents`, or in bulk with `filter`.

- `documents`: Each update is identified by its `_id`. Any other fields set new values for those fields, and fields listed in `_remove_fields` are removed from the document. Fields that are not mentioned are left unchanged. Updates to a document that does not exist are accepted but have no effect.
- `filter`: The same patch is applied to every document matching a metadata filter expression. The patch is given by `set_fields` and/or `remove_fields`, at least one of which must be specified. Text-match operators (`$match_phrase`, `$match_all`, `$match_any`) are not supported in a filtered update; they are only supported in search. The response reports `matched_records`, the number of documents the filter matched.

`documents` and the by-filter fields (`filter`, `set_fields`, `remove_fields`) are mutually exclusive.

<RequestExample>
  ```python Python theme={null}
  # pip install --upgrade pinecone
  import os
  from pinecone import Pinecone

  pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])
  index = pc.Index(name="articles")

  NAMESPACE = "example-namespace"

  # Patch specific documents by ID
  index.documents.update(
      namespace=NAMESPACE,
      documents=[
          {"_id": "doc1", "title": "Updated title"},
          {"_id": "doc2", "_remove_fields": ["content"]},
      ],
  )

  # Apply the same patch to every document matching a metadata filter
  index.documents.update(
      namespace=NAMESPACE,
      filter={"category": {"$eq": "news"}},
      set_fields={"category": "archive"},
      remove_fields=["content"],
  )
  ```

  ```shell curl theme={null}
  PINECONE_API_KEY="YOUR_API_KEY"
  INDEX_HOST="articles-abc123.svc.us-east-1.pinecone.io"

  # EXAMPLE REQUEST 1: Patch specific documents by ID
  curl "https://$INDEX_HOST/namespaces/__default__/documents/update" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{
      "documents": [
        { "_id": "doc1", "title": "Updated title" },
        { "_id": "doc2", "_remove_fields": ["content"] }
      ]
    }'

  # EXAMPLE REQUEST 2: Update by metadata filter
  curl "https://$INDEX_HOST/namespaces/__default__/documents/update" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Pinecone-Api-Version: 2026-07" \
    -d '{
      "filter": { "category": { "$eq": "news" } },
      "set_fields": { "category": "archive" },
      "remove_fields": ["content"]
    }'
  ```
</RequestExample>


## OpenAPI

````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-07/db_data_2026-07.oas.yaml post /namespaces/{namespace}/documents/update
openapi: 3.0.3
info:
  title: Pinecone Data Plane API
  description: >-
    Pinecone is a vector database that makes it easy to search and retrieve
    billions of high-dimensional vectors.
  contact:
    name: Pinecone Support
    url: https://support.pinecone.io
    email: support@pinecone.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 2026-07
servers:
  - url: https://{index_host}
    variables:
      index_host:
        default: unknown
        description: host of the index
security:
  - ApiKeyAuth: []
tags:
  - name: Vector Operations
  - name: Bulk Operations
  - name: Namespace Operations
  - name: Document Operations
    description: >-
      Operations on documents in an index created with a document schema — one
      that declares at least one full-text-searchable string field or a
      `dense_vector` / `sparse_vector` field under a name other than the
      reserved `_values` / `_sparse_values`. Metadata fields alone do not make a
      document schema. Indexes served by the vectors API — created from
      `dimension`/`metric` on an earlier API version, or from a schema holding
      only the reserved vector fields and metadata — and indexes served by the
      records API — created with an integrated embedding model, whose schema
      holds a single `semantic_text` field — reject every document operation
      with `400` and name the API to use instead. A document index accepts only
      the document operations; the vector data operations (upsert, query, fetch,
      update, delete, list) reject it, while index stats and the namespace
      operations remain available.
externalDocs:
  description: More Pinecone.io API docs
  url: https://docs.pinecone.io/introduction
paths:
  /namespaces/{namespace}/documents/update:
    post:
      tags:
        - Document Operations
      summary: Update documents
      description: >-
        Apply partial updates to documents in a namespace. Documents are
        selected either per ID with `documents`, or in bulk with `filter`.


        - `documents`: Each update is identified by its `_id`. Any other fields
        set new values for those fields, and fields listed in `_remove_fields`
        are removed from the document. Fields that are not mentioned are left
        unchanged. Updates to a document that does not exist are accepted but
        have no effect.

        - `filter`: The same patch is applied to every document matching a
        metadata filter expression. The patch is given by `set_fields` and/or
        `remove_fields`, at least one of which must be specified. Text-match
        operators (`$match_phrase`, `$match_all`, `$match_any`) are not
        supported in a filtered update; they are only supported in search. The
        response reports `matched_records`, the number of documents the filter
        matched.


        `documents` and the by-filter fields (`filter`, `set_fields`,
        `remove_fields`) are mutually exclusive.
      operationId: updateDocuments
      parameters:
        - in: header
          name: X-Pinecone-Api-Version
          description: Required date-based version header
          required: true
          schema:
            default: 2026-07
            type: string
          style: simple
        - in: path
          name: namespace
          description: The namespace to update documents in.
          required: true
          schema:
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDocumentsRequest'
            examples:
              by_ids:
                summary: Patch specific documents by ID
                value:
                  documents:
                    - _id: doc-1
                      title: Updated title
                    - _id: doc-2
                      _remove_fields:
                        - content
              by_filter:
                summary: >-
                  Apply the same patch to every document matching a metadata
                  filter
                value:
                  filter:
                    category:
                      $eq: news
                  remove_fields:
                    - content
                  set_fields:
                    category: archive
        required: true
      responses:
        '202':
          description: The update request was successfully accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateDocumentsResponse'
              examples:
                by_filter:
                  summary: >-
                    A filtered update, reporting how many documents the filter
                    matched
                  value:
                    matched_records: 42
                by_ids:
                  summary: A per-ID update, which reports no count
                  value: {}
        '400':
          description: Bad request. The request body included invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'Unauthorized. Possible causes: missing or invalid API key.'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/UnauthorizedMessage'
        4XX:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        5XX:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    UpdateDocumentsRequest:
      description: >-
        The request for the `update_documents` operation. Either `documents` or
        `filter` must be specified, and they are mutually exclusive. A `filter`
        must be accompanied by a non-empty `set_fields` and/or `remove_fields`.


        An empty `set_fields` or `remove_fields` asks for no change, so it does
        not make a request by-filter: it is ignored, and a request that also has
        `documents` is still a valid per-ID update.


        A by-filter patch is checked against the index schema the same way a
        per-ID patch is: a value must match the type its field declares, a field
        cannot be both set and removed, and a required field cannot be removed.
      type: object
      properties:
        documents:
          description: >-
            The list of partial document updates to apply. Mutually exclusive
            with `filter`, and with a non-empty `set_fields` or `remove_fields`.
          type: array
          items:
            $ref: '#/components/schemas/UpdateDocumentRecord'
          minItems: 1
          maxItems: 1000
        filter:
          example:
            category:
              $eq: news
          description: >-
            A metadata filter expression selecting the documents to patch with
            `set_fields` and `remove_fields`. Must not be empty; an empty filter
            is rejected rather than matching every document. Text-match
            operators (`$match_phrase`, `$match_all`, `$match_any`) are not
            supported here, since documents are selected on metadata alone.
            Mutually exclusive with `documents`.
          type: object
          minProperties: 1
        set_fields:
          example:
            category: archive
          description: >-
            The fields to set on every document matching `filter`, and the
            values to set them to. When non-empty, only valid together with
            `filter`; an empty object asks for no change and is ignored.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DocumentFieldValue'
        remove_fields:
          example:
            - content
          description: >-
            The names of the fields to remove from every document matching
            `filter`. When non-empty, only valid together with `filter`; an
            empty list asks for no change and is ignored.
          type: array
          items:
            type: string
      anyOf:
        - title: Per-ID patches
          required:
            - documents
          not:
            anyOf:
              - required:
                  - filter
              - properties:
                  set_fields:
                    minProperties: 1
                required:
                  - set_fields
              - properties:
                  remove_fields:
                    minItems: 1
                required:
                  - remove_fields
        - title: By filter
          required:
            - filter
          anyOf:
            - properties:
                set_fields:
                  minProperties: 1
              required:
                - set_fields
            - properties:
                remove_fields:
                  minItems: 1
              required:
                - remove_fields
          not:
            required:
              - documents
    UpdateDocumentsResponse:
      description: The response for the `update_documents` operation.
      type: object
      properties:
        matched_records:
          example: 42
          description: >-
            The number of documents that matched `filter` when the update was
            accepted. Only returned for a filtered update; a per-ID update
            reports no count. The patch is applied asynchronously, so this is a
            point-in-time count rather than a guarantee of the number of
            documents ultimately patched.
          type: integer
          format: int32
    ErrorResponse:
      example:
        error:
          code: INVALID_ARGUMENT
          message: >-
            No 'ids' or 'filter' provided in the document fetch request. Provide
            at least one document ID in 'ids', or a metadata filter in 'filter'.
        status: 400
      description: >-
        The error response shape returned by the records and documents
        operations. The vector operations return `rpcStatus` instead. Requests
        rejected by the authentication and rate-limiting layer before they reach
        the service (`401`, and the `400`, `403`, and `429` it produces) return
        a plain-text body on every operation.
      type: object
      properties:
        status:
          example: 400
          description: The HTTP status code of the error.
          type: integer
        error:
          description: Detailed information about the error that occurred.
          type: object
          properties:
            code:
              example: INVALID_ARGUMENT
              description: >-
                The error code.

                Possible values: `OK`, `UNKNOWN`, `INVALID_ARGUMENT`,
                `DEADLINE_EXCEEDED`, `NOT_FOUND`, `ALREADY_EXISTS`,
                `PERMISSION_DENIED`, `UNAUTHENTICATED`, `RESOURCE_EXHAUSTED`,
                `FAILED_PRECONDITION`, `ABORTED`, `OUT_OF_RANGE`, `INTERNAL`,
                `FORBIDDEN`, `PAYMENT_REQUIRED`, `SERVICE_UNAVAILABLE`, or
                `PAYLOAD_TOO_LARGE`.
              x-enum:
                - OK
                - UNKNOWN
                - INVALID_ARGUMENT
                - DEADLINE_EXCEEDED
                - NOT_FOUND
                - ALREADY_EXISTS
                - PERMISSION_DENIED
                - UNAUTHENTICATED
                - RESOURCE_EXHAUSTED
                - FAILED_PRECONDITION
                - ABORTED
                - OUT_OF_RANGE
                - INTERNAL
                - FORBIDDEN
                - PAYMENT_REQUIRED
                - SERVICE_UNAVAILABLE
                - PAYLOAD_TOO_LARGE
              type: string
            message:
              example: >-
                No 'ids' or 'filter' provided in the document fetch request.
                Provide at least one document ID in 'ids', or a metadata filter
                in 'filter'.
              description: >-
                A human-readable description of the error, including how to
                correct the request where possible.
              type: string
          required:
            - code
            - message
      required:
        - status
        - error
    UnauthorizedMessage:
      example: Unauthorized
      description: >-
        The plain-text body of a `401` response. Authentication failures are
        rejected before the request reaches the index, so they carry the message
        `Unauthorized` rather than an error object.
      type: string
    UpdateDocumentRecord:
      example:
        _id: doc-1
        _remove_fields:
          - content
        title: Updated title
      description: >-
        A partial update to a document, identified by `_id`. Any other fields
        set new values for those fields. Fields named in `_remove_fields` are
        removed from the document.
      type: object
      properties:
        _id:
          description: The unique identifier of the document to update.
          type: string
          pattern: ^[\x01-\x7F]+$
          minLength: 1
          maxLength: 512
        _remove_fields:
          description: A list of field names to delete from the document.
          type: array
          items:
            type: string
      required:
        - _id
      additionalProperties:
        $ref: '#/components/schemas/DocumentFieldValue'
    DocumentFieldValue:
      description: >-
        The value of a single document field. Scalar fields carry the same types
        as metadata ("must be a boolean, number, string, or array of strings");
        a field declared in the index schema as `dense_vector` carries an array
        of numbers, and one declared `sparse_vector` carries sparse values.
        Which names are vector fields is a property of the index, not of this
        request.
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: array
          items:
            type: string
        - type: array
          items:
            type: number
            format: float
        - $ref: '#/components/schemas/SparseValues'
    SparseValues:
      description: >-
        Vector sparse data. Represented as a list of indices and a list of 
        corresponded values, which must be with the same length.
      type: object
      properties:
        indices:
          example:
            - 1
            - 312
            - 822
            - 14
            - 980
          description: The indices of the sparse data.
          type: array
          items:
            type: integer
            format: int64
            minimum: 0
            maximum: 4294967295
          minItems: 1
          maxItems: 2048
        values:
          example:
            - 0.1
            - 0.2
            - 0.3
            - 0.4
            - 0.5
          description: >-
            The corresponding values of the sparse data, which must be with the
            same length as the indices.
          type: array
          items:
            type: number
            format: float
          minItems: 1
          maxItems: 2048
      required:
        - indices
        - values
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: >-
        An API Key is required to call Pinecone APIs. Get yours from the
        [console](https://app.pinecone.io/).

````