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
• Builds on: SDK-111 (search_documents implementation, now merged)

---

Note

Medium Risk
Adds a new document-write API surface (upsert_documents) that sends user-provided JSON to the backend; behavior is mostly additive but touches data-ingestion paths and response handling.

Overview
Adds document upsert support. Introduces upsert_documents(namespace, documents) on Index and _IndexAsyncio (and their interfaces) to upsert flat JSON documents (requiring _id) via DocumentOperationsApi.

The new methods validate inputs, wrap payloads in DocumentUpsertRequest, and return UpsertResponse with extracted _response_info, falling back to len(documents) when the server omits upserted_count.

Adds unit tests covering request creation, parameter validation, API invocation wiring, async behavior, and the upserted_count fallback.

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