feat: implement upsert_documents() method for Index and IndexAsyncio

[jhamon]

Summary

Add the upsert_documents() method to the Index and IndexAsyncio classes for upserting flat JSON documents into a namespace.

• Documents are indexed based on the configured index schema
• Each document must have an _id field
• Vector fields can be user-specified (e.g., my_vector) or use the reserved _values key
• Text fields are indexed based on schema configuration with full_text_searchable: true

Usage Example

from pinecone import Pinecone

pc = Pinecone()
index = pc.Index(host="example-index-host")

# Upsert documents with pre-computed vectors
index.upsert_documents(
    namespace="movies",
    documents=[
        {
            "_id": "movie-1",
            "title": "Return of the Pink Panther",
            "year": 1986,
            "genre": "comedy",
            "embedding": [0.1, 0.2, 0.3, ...]  # matches schema field name
        },
        {
            "_id": "movie-2",
            "title": "The Pink Panther Strikes Again",
            "year": 1976,
            "genre": "comedy",
            "embedding": [0.3, 0.4, 0.5, ...]
        }
    ]
)

Async Example

import asyncio
from pinecone import Pinecone

async def main():
    pc = Pinecone()
    async with pc.IndexAsyncio(host="example-index-host") as index:
        await index.upsert_documents(
            namespace="movies",
            documents=[
                {"_id": "movie-1", "title": "Test", "embedding": [0.1, 0.2]}
            ]
        )

asyncio.run(main())

Test Plan

• Unit tests for parameter validation (namespace required, documents required)
• Unit tests for request creation with various document formats
• Unit tests for response handling
• Unit tests for async version

Related

• Linear: SDK-112
• Depends on: SDK-111 (search_documents implementation)

---

Note

Medium Risk
Medium risk because it introduces a new public write-path hitting the document upsert API and adds fallback behavior when the server omits upserted_count, which could mask partial failures if the backend response shape differs.

Overview
Adds a new upsert_documents() method on Index and IndexAsyncio to upsert flat JSON documents into a namespace via the document operations API.

The method validates inputs (namespace required, non-empty documents), builds a DocumentUpsertRequest, and returns an UpsertResponse with extracted _response_info and upserted_count (falling back to len(documents) if the server doesn’t provide a count).

Updates the sync/async interfaces to include the new method and adds unit tests covering request creation, validation, API invocation, and the count fallback behavior.

^{Written by Cursor Bugbot for commit b9c532b. This will update automatically on new commits. Configure here.}