python-sdk

Version 10.2.0 fixes a TLS certificate-verification flaw in the gRPC client and adds full-text match operators to the Field filter builder. It targets the same 2026-07 API as 10.1.0 and removes or renames nothing.

What to do:

• Upgrade to 10.2.0 if you use the gRPC client.
• Whichever client you use, upgrade certifi to 2026.10.19 or later.

Security

gRPC users: upgrade to 10.2.0 (RUSTSEC-2026-0382, CVE-2026-111943, 7ecd4b0)

• Affected: 9.0.0 through 10.1.0, if your code uses pc.index(..., grpc=True), PineconeGRPC, or GrpcIndex/GRPCIndex.
• Risk: the bundled rustls-webpki can accept certificates chained through emSign intermediates whose private keys are now public. An attacker with those keys and a position on your network path could impersonate your index and read your API key and data.
• Fix: 10.2.0 bundles rustls-webpki 0.103.16, which rejects those chains.

Everyone, gRPC users included: upgrade certifi (GHSA-6q48-6c7w-9gw2)

• Affected: all control-plane and data plane REST calls, which go through httpx and trust whichever certifi is installed in your environment.
• Risk: certifi releases before 2026.10.19 trust the same compromised emSign roots.
• Why upgrading pinecone isn't enough: the SDK deliberately doesn't pin certifi, so it stays compatible with the other packages in your environment.
• Action: run pip install --upgrade "certifi>=2026.10.19" (or uv add "certifi>=2026.10.19") and keep that floor in your own dependencies.
• Custom CA bundles: if you pass ssl_ca_certs or set SSL_CERT_FILE or SSL_CERT_DIR, make sure that bundle no longer trusts the emSign roots.

No action needed for tokio: the bundled tokio moves to 1.51.6 for RUSTSEC-2026-0386. The SDK never calls the affected API.

What's new

Full-text match filters for documents (docs, 9fc62f4)

Narrow document search and fetch results by the words in a text field, not only by exact values. Field gains three methods:

• match_phrase: the words, in order
• match_all: every word, in any order
• match_any: at least one of the words

Things to know:

• Fields: they work on string fields declared with full_text_search, or with embed/sparse_embed unless you set store_text=False.
• Methods: use them in the filter of documents.search and documents.fetch. The server rejects them in documents.delete and documents.update.
• Usage: as with every Field filter, pass the result's .to_dict().

from pinecone import EmbedQuery, Field, Pinecone

pc = Pinecone()
index = pc.index("articles")  # "body" is a string field declared with embed=True

# Semantic search, limited to documents whose body contains "roman aqueduct"
# and whose year metadata is 100 or later.
results = index.documents.search(
    namespace="en",
    top_k=5,
    score_by=[EmbedQuery(field="body", query="how did Rome move water")],
    filter=(Field("body").match_phrase("roman aqueduct") & Field("year").gte(100)).to_dict(),
)

Fixes

• index.create_namespace(name="__default__") still raises "reserved and cannot be created", but the message no longer claims the namespace always exists. It now explains that this holds only on an index created with dimension/metric, and that on a document index you create it by upserting documents into it. (bbe1282)

Docs

New guides for document indexes:

Version 10.1.0 lets a document index embed text for you. It targets the same 2026-07 API as 10.0.0 and removes or renames nothing.

What's new

• Pinecone can embed your text: mark a string field embed=True or sparse_embed=True. (docs, f32f4e2)

  from pinecone import EmbedQuery, Pinecone, SchemaBuilder
  
  # Reads the API key from the PINECONE_API_KEY environment variable.
  pc = Pinecone()
  
  # Declare a string field that Pinecone embeds for you.
  schema = SchemaBuilder().add_string_field("body", embed=True).build()
  pc.indexes.create(name="articles", schema=schema)
  index = pc.index("articles")
  
  # Write plain-text documents; Pinecone embeds each body.
  index.documents.upsert(
      namespace="en",
      documents=[
          {"_id": "a1", "body": "Aqueducts carried water by gravity"},
          {"_id": "a2", "body": "The Colosseum seated 50,000 people"},
          {"_id": "a3", "body": "Hypocausts heated the public baths"},
          {"_id": "a4", "body": "Roman roads were built in layers"},
      ],
  )
  
  # Search with plain text; Pinecone embeds the query too.
  results = index.documents.search(
      namespace="en",
      top_k=2,
      score_by=[
          EmbedQuery(field="body", query="how did Rome move water"),
      ],
  )
  for doc in results.matches:
      print(doc.id, doc.score)
  

  • Send at most 96 documents per upsert or update; the default batch_upsert size of 50 fits.
  • An EmbedQuery or SparseEmbedQuery must be the only clause in score_by.
  • Choose the model with FieldEmbedConfig or FieldSparseEmbedConfig; skip storing text with store_text=False.
  • Responses report embedding tokens in usage.embed_total_tokens. (6ff91fd)

• documents.batch_upsert splits a batch the server rejects as too large, instead of failing it. (8f1f96c)

• documents.fetch takes a limit of up to 10,000 for filtered fetches. (6ea0da1)

• HTTP 413 raises PayloadTooLargeError, a subclass of ApiError. (445d520)

• Python 3.15 is supported, with prebuilt wheels. (04e7125)

Behavior changes

These are subtle changes that clarify or fix how the SDK handles error cases and invalid input. For a working integration the real-world impact should be minimal. The 10.0 to 10.1 upgrade docs shows before and after for each.

Calls that succeeded on 10.0.0

• To wait for a write, poll documents.search, not documents.fetch; only search reports is_reconciled. (recipe, 203cf92)
• Unknown keys in a dict score_by clause raise PineconeValueError; deleting them leaves results unchanged. (70a44c5)
• Some ValueErrors are now PineconeTypeError; catch PineconeError or TypeError. (481b7f9)
• Documents methods need a dict filter=; call .to_dict() on a filter-builder Condition. (01a6ef3)
• A plain-http:// i

Version 10.0.0 is the SDK for the Pinecone 2026-07 API. It runs on Python 3.10 through 3.14 and sends 2026-07 on every plane by default. The release graduates the schema-based document interface, SchemaBuilder, and the rest of the 2026-07 API out of pinecone.preview onto the main client objects. There are breaking changes: a short list of the most important changes are outlined below, and Migrating to V10 is the complete accounting.

If your workload upserts and queries an existing index, upgrading does not change what your code means. upsert, query, fetch, update, delete, list, and describe_index_stats take the same arguments and return the same shapes they did on 9.x; pc.Index("movies") and pc.index("movies") both still hand you an index, though only pc.index() narrows its return type, so reach index.documents through that one; and none of those operations is deprecated or scheduled for removal. Indexes you created before 2026-07 go on being served by them. Three things do change on that path, each covered below: a batched upsert paces itself differently, some invalid calls now raise locally instead of being refused by the server, and gRPC upsert_from_dataframe collects partial failures rather than raising on the first one.

The breaking changes are concentrated in pc.indexes.create's arguments and return model, and in the surfaces that graduated out of pinecone.preview. Flat create_index(...) with dimension=, metric=, or spec= needs no edits: it takes its 9.1.0 parameters in the 9.1.0 order, positionally or by keyword. Which family of operations serves an index follows the index itself, not the SDK version — an index created before 2026-07 is addressed through the vector operations above, and one created with a 2026-07 document schema through index.documents.

What's new

Documents API. Records are addressed as documents: a JSON object with an _id, the fields you declared in the index schema, and any metadata alongside them. Upsert, search, fetch, list, update, and delete all live on index.documents, on the sync and async clients alike, and index.documents.batch_upsert handles large loads with the same admission gate and partial-failure reporting the vector path uses. See Quickstart.

from pinecone import DenseVectorQuery, Pinecone

index = Pinecone().index("quickstart")

index.documents.upsert(
    namespace="movies",
    documents=[
        {
            "_id": "movie-001",
            "embedding": [0.1, 0.2, 0.3],
            "title": "Arrival",
        },
    ],
)

results = index.documents.search(
    namespace="movies",
    top_k=3,
    score_by=[DenseVectorQuery(field="embedding", values=[0.1, 0.2, 0.3])],
)

SchemaBuilder. An index's fields are declared as a schema, and SchemaBuilder builds that schema in Python instead of by hand-assembling nested dicts. Every add_* method returns the builder, and build() returns a plain {"fields": {...}} dict you hand straight to pc.indexes.create(schema=...). See Schema Builder.

from pinecone import Pinecone, SchemaBuilder

schema = (
    SchemaBuilder()
    .add_dense_vector_field("embedding", dimension=1024, metric="cosine")
    .add_string_field("title", full_text_search={"language": "en"})
    .build()
)

pc = Pinecone()
pc.indexes.create(
    name="product-search",
    schema=schema,
    deployment={
        "deployment_type": "managed",
        "cloud": "aws",
        "region": "us-east-1",
    },
)

Full-text search configuration. String fields carry their own full-text search config: language, stemming, stop words, and character n-grams for substring and autocomplete matching, set per field at index creation.

Release v9.1.0

v9.1.0 is the retry-resilience release. It overhauls how the SDK behaves under throttling: decorrelated jitter on every transport, plus automatic per-host concurrency back-off that shrinks in-flight bulk requests during a 429 storm and recovers as pressure eases. A new RateLimitError lets callers catch throttling distinctly, and a dedicated retries guide documents the full model. Secondary changes round out GrpcIndex parity with the REST clients and restore the v8 search(query={...}) request shape.

Highlights

• Decorrelated jitter on every transport. REST (sync and async) and gRPC now use AWS-style decorrelated jitter for retry backoff, so many clients throttled at the same moment no longer retry in lockstep.
• Automatic concurrency back-off under throttling. Bulk operations self-tune downward when the backend rate-limits a host and recover as throttling subsides — an AIMD control loop, per host, with no new knobs to configure.
• Bounded multi-namespace fan-out. AsyncIndex.query_namespaces no longer fires one unbounded request per namespace — a common cause of self-inflicted 429 storms. It's now capped at 10 in-flight.
• RateLimitError for HTTP 429. Rate-limit responses raise a dedicated pinecone.errors.RateLimitError, so you can catch throttling distinctly from other server errors.
• New retries guide at docs/guides/retries.md — defaults, jitter math, the adaptive-concurrency ceiling, and the limits of in-process retries under multi-process / serverless deployment.
• GrpcIndex parity with the REST clients. query_namespaces, query_namespaces_async, fetch_by_metadata, and the full bulk-import API now exist on GrpcIndex, so switching to grpc=True for throughput no longer loses functionality.
• Community contribution — search(query={...}) syntax from v8 has been restored. Thanks to @pragnyanramtha, the single-argument request-body form that v9.0.x rejected works again on Index, AsyncIndex, and GrpcIndex.

Retry & resilience

Decorrelated jitter

REST and gRPC retries now use decorrelated jitter — each delay is drawn from a window that grows with the previous delay, capped at max_wait. This replaces the previous fixed full-jitter backoff and spreads retries from many clients across time instead of bunching them at the same instant. See the retries guide for the exact formula and defaults.

Automatic concurrency back-off

Bulk operations now self-tune their concurrency under throttling. When the backend rate-limits a host (HTTP 429/503, or gRPC RESOURCE_EXHAUSTED), the SDK reduces the number of in-flight requests it allows to that host, then recovers after a streak of successes — the same AIMD (additive-increase / multiplicative-decrease) approach used by TCP congestion control. It's per host, automatic, and requires no configuration; max_concurrency remains the ceiling the SDK tunes beneath.

RateLimitError

HTTP 429 responses now raise RateLimitError, a subclass of ApiError, so throttling can be caught distinctly from other server errors:

from pinecone.errors import RateLimitError

try:
    pc.indexes.describe("my-index")
except RateLimitError:
    # back off and retry, or surface to your orchestrator
    ...

Exported from pinecone.errors and the top-level pinecone namespace; a RateLimitException alias matches the existing exception-naming pattern.

Observability

The retry and concurrency layers emit namespaced log records with consistent key=value fields, so you can diagnose throttling from logs without adding instrumentation:

• pinecone._internal.http_client — DEBUG on each throttled retry attempt (status, host, attempt N/total, computed delay).
• pinecone._internal.adaptive — DEBUG on each concurrency adjustment; INFO the first time a host is throttled, with an actionable