Release v10.3.0

10.3.0 adds two integrated-embedding settings for document indexes, from Silas Smith (@ssmith-pc): a per-search query task and a processing location. It also fixes gRPC through authenticating proxies. Nothing is removed or renamed; the API version is still 2026-07.

Act only if you give the gRPC client a proxy_url that isn't http:// (see Behavior change), or your logs captured a PineconeConfig or Config repr with a proxy password (rotate it).

What's new

Set the query task per search: EmbedQuery.parameters (docs, 3b6923e)

• EmbedQuery(field=..., query=..., parameters: dict[str, Any] | None = None) overrides the field's read_parameters for one search.
• One field serves several query types: a gemini-embedding-2 field indexed for retrieval can also answer fact-checking queries, with no second index or re-embedding.
• Only task_type can be set today; the server validates it. pc.inference.list_models() lists the models that accept it.
• Unset, the field's read_parameters apply and the key is not sent. SparseEmbedQuery does not take it.

from pinecone import EmbedQuery, Pinecone

pc = Pinecone()
facts = pc.index("fact-checks")  # "body" embeds with gemini-embedding-2

results = facts.documents.search(
    namespace="claims-en",
    top_k=5,
    score_by=[
        EmbedQuery(
            field="body",
            query="Is the Eiffel Tower taller than 300 m?",
            parameters={"task_type": "fact_verification"},
        )
    ],
)

Choose where your text is processed: FieldEmbedConfig.processing_location (8396d55)

• FieldEmbedConfig(..., processing_location: str | None = None), such as "us", sets where the model processes your documents and queries.
• Values depend on the model and your plan; unset means the model's default.
• Set at index creation, typed or as a dict (embed={"model": ..., "processing_location": "us"}). Like the rest of embed, it cannot change later.
• pc.indexes.describe(name).schema.fields["body"].embed.processing_location reports it; 10.2.0 dropped it.
• Dense embed only; FieldSparseEmbedConfig does not take it.

from pinecone import FieldEmbedConfig, Pinecone, SchemaBuilder

pc = Pinecone()
schema = (
    SchemaBuilder()
    .add_string_field(
        "body",
        embed=FieldEmbedConfig(model="text-embedding-3-large", processing_location="us"),
    )
    .build()
)
pc.indexes.create(name="support-articles-us", schema=schema)

Search guide organized by kind of search (docs only) (Search documents, d6e79e1)

• The guide starts from the kind of search you want, semantic, sparse-vector or full-text, and names the clause for each, split by whether Pinecone embeds the query or you pass a vector. Declare a schema and upsert documents builds its two example indexes.

# Clauses available before 10.3.0; the guide maps each to a kind of search.
from pinecone import DenseVectorQuery, EmbedQuery, SparseEmbedQuery, SparseValues, SparseVectorQuery, TextQuery

# Semantic: by meaning
EmbedQuery(field="body", query="how did Rome move water")             # Pinecone embeds the text
DenseVectorQuery(field="body_vector", values=[0.012, -0.087, 0.153])  # you pass the vector

# Sparse-vector: by weighted term overlap
SparseEmbedQuery(field="body", query="roman aqueduct")
SparseVectorQuery(field="body_sparse_vector", sparse_values=SparseValues(indices=[3, 41], values=[0.6, 0.4]))

# Full-text: by the words themselves
TextQuery(fields=["title"], query="roman aqueduct")

Behavior change: gRPC accepts only http:// proxy URLs

• Affects: GrpcIndex(..., proxy_url=...) and pc.index(..., grpc=True) when proxy_url starts with https://, socks5:// or socks5h:// (10.2.0 accepted these), or has no scheme.
• Now: construction raises (pc.index raises before it looks up the host):

PineconeValueError: gRPC supports only http:// proxies; got 'https://***@proxy'; use an http:// proxy URL (traffic inside the tunnel is still TLS) or use REST (grpc=False), which also supports https:// and SOCKS proxies

• Fix, gRPC only: change the scheme to http://. If gRPC worked with your URL in 10.2.0, keep its host and port: 10.2.0 already spoke plain HTTP there.
• Fix, REST and gRPC through one https:// proxy: pc.index(..., grpc=True) reuses Pinecone(proxy_url=...) and has no per-call override. Keep https:// on Pinecone and give GrpcIndex its own http:// URL:

from pinecone import GrpcIndex, Pinecone

pc = Pinecone(proxy_url="https://user:pass@proxy.corp:443")  # REST keeps TLS to the proxy
idx = GrpcIndex(host=pc.indexes.describe("my-index").host, proxy_url="http://user:pass@proxy.corp:3128")

• Or drop grpc=True and use REST.
• Unchanged: REST (Pinecone, AsyncPinecone, pc.index(...) without grpc=True) still accepts http://, https://, socks5:// and socks5h://. Don't switch a shared Pinecone(proxy_url=...) to http:// for gRPC's sake: REST would then send its proxy credentials in plaintext too.
• Why: gRPC now sends proxy_url credentials (see Fixes), and would send them unencrypted to an https:// proxy. No earlier release sent them at all. (653d62b)

Fixes: proxies

Skip this section if you don't set proxy_url.

• gRPC sends proxy credentials. With proxy_url="http://user:pass@proxy:3128", gRPC sends Proxy-Authorization: Basic on CONNECT; before, an authenticating proxy refused the tunnel. gRPC ignores proxy_headers, so put gRPC credentials in the URL. REST proxy_headers are unchanged. (736bfb6)
• A malformed proxy_url fails at construction with a masked error. Pinecone, AsyncPinecone, Index, AsyncIndex and Admin raise PineconeValueError("Invalid proxy URL '***@proxy.corp:3128': it has no scheme; start it with http:// or https://"), naming the problem. GrpcIndex raises the gRPC error above. Before, httpx raised ValueError or httpx.InvalidURL with text that could include the password. PineconeValueError is a ValueError; except httpx.InvalidURL no longer matches. Percent-encode #, /, ? and @ in credentials (Authentication). (653d62b)
• Proxy passwords are masked in reprs. repr() of PineconeConfig and Config used to print the password in proxy_url. They now print http://***@host:port. If your logs captured one, rotate the proxy password. (d895c1d, c180469)
• PINECONE_DEBUG_CURL shell-quotes its output. A URL, header or body containing ' no longer breaks the logged curl command. (d895c1d)

Docs

• The documents guides use docs.pinecone.io's names for the kinds of search (semantic, sparse-vector, full-text), and Search documents shows how to keep semantic results to documents containing certain words with a text-match filter. From @nicoalba10. (433fe11)

Dependencies

None that reach users: runtime Python dependencies and the crates in the Rust extension match 10.2.0.

Upgrading

pip install --upgrade pinecone
# or
uv add "pinecone>=10.3,<11"

Full Changelog: v10.2.0...v10.3.0