GrpcIndex

Obtain a GrpcIndex instance via pinecone.Pinecone.index() with grpc=True, or construct one directly.

from pinecone import Pinecone

pc = Pinecone(api_key="your-api-key")

# Resolve host automatically by index name
idx = pc.index("my-index", grpc=True)

# — or — construct directly with a host URL
from pinecone.grpc import GrpcIndex
idx = GrpcIndex(host="my-index-abc123.svc.pinecone.io", api_key="your-api-key")

GrpcIndex exposes the same data-plane operations as Index but uses gRPC transport (backed by a Rust extension) and returns PineconeFuture objects from the *_async() methods.

Method groups:

class pinecone.grpc.GrpcIndex(*, host, api_key=None, api_version='2026-07', source_tag=None, secure=True, timeout=20.0, connect_timeout=1.0, retry_config=None, proxy_url=None, on_throttle=None, limiter_registry=None)[source]

Bases: object

Synchronous gRPC data plane client targeting a specific Pinecone index.

Provides the same interface as Index but routes data-plane operations through a gRPC transport (via the Rust-backed GrpcChannel) instead of HTTP/REST.

Parameters:

  • host (str) – The index-specific data plane host URL.

  • api_key (str | None) – Pinecone API key. Falls back to PINECONE_API_KEY env var.

  • api_version (str) – API version string. Defaults to the current data plane version.

  • source_tag (str | None) – Tag appended to the User-Agent string for request attribution.

  • secure (bool) – Whether to use TLS encryption. Defaults to True.

  • timeout (float) – Request timeout in seconds. Defaults to 20.0.

  • connect_timeout (float) – Connection timeout in seconds. Defaults to 1.0.

  • retry_config (RetryConfig | None) – Retry policy for transient gRPC errors. Accepts the same RetryConfig REST uses. None (default) uses the gRPC defaults: max_retries=5, backoff_factor=0.1, max_wait=60.0. retryable_status_codes is ignored on this transport — it carries HTTP statuses, while gRPC retries a fixed set of tonic::Code values (UNAVAILABLE, RESOURCE_EXHAUSTED, ABORTED).

  • proxy_url (str | None) – HTTP proxy URL. gRPC traffic is tunnelled through it with HTTP CONNECT.

  • limiter_registry (_AdaptiveLimiterRegistry | None) – SDK-internal. Registry the bulk paths consult to back off under throttling. Wired by Pinecone.index(); not intended for user configuration.

  • on_throttle (Callable[[str], None] | None)

Raises:

PineconeValueError – If no API key can be resolved or the host is invalid.

Note

Four timeout layers apply to every gRPC call, and only the first three bound a single request:

  1. Connect — connect_timeout, default 1.0s.

  2. Per attempt — timeout (or a per-call timeout=), default 20.0s. This is a deadline on one attempt, not on the call.

  3. Retry budget — retry_config.max_retries attempts after the first, with backoff between them.

  4. Whole job — for bulk methods only, total_timeout.

Layers 2 and 3 multiply. timeout=120 is not a 120s bound: with the default max_retries=5 it is up to 6 attempts × 120s plus backoff, so a worst case near 17 minutes. Lower max_retries to shrink that, or bound the whole operation with total_timeout.

Examples

from pinecone.grpc import GrpcIndex

idx = GrpcIndex(host="movie-recs-abc123.svc.pinecone.io", api_key="...")
__init__(*, host, api_key=None, api_version='2026-07', source_tag=None, secure=True, timeout=20.0, connect_timeout=1.0, retry_config=None, proxy_url=None, on_throttle=None, limiter_registry=None)[source]
Parameters:

  • host (str)

  • api_key (str | None)

  • api_version (str)

  • source_tag (str | None)

  • secure (bool)

  • timeout (float)

  • connect_timeout (float)

  • retry_config (RetryConfig | None)

  • proxy_url (str | None)

  • on_throttle (Callable[[str], None] | None)

  • limiter_registry (_AdaptiveLimiterRegistry | None)

Return type:

None

property host: str

The data plane host URL for this index.

upsert(*, vectors, namespace='', batch_size=None, max_concurrency=4, show_progress=True, timeout=None)[source]

Upsert a batch of vectors into a namespace.

If a vector with the same ID already exists in the namespace, it is overwritten.

One request is capped both on the number of vectors it carries and on its encoded size, and with wide vectors or heavy metadata the size cap is usually the one reached first. Pass batch_size to split a long sequence into requests that stay under both.

Parameters:

  • vectors (Sequence[Vector | tuple[str, Sequence[float]] | tuple[str, Sequence[float], Mapping[str, Any]] | Mapping[str, Any]]) – Sequence of vectors to upsert. Each element can be a Vector instance, a tuple of (id, values) or (id, values, metadata), or a dict with id, values, and optional sparse_values / metadata keys.

  • namespace (str) – Target namespace. Defaults to the default (empty-string) namespace.

  • batch_size (int | None) – If set, splits vectors into batches of this size and submits them in parallel. None (default) sends all vectors in a single request. Must be a positive integer when set.

  • max_concurrency (int) – Number of parallel threads used when batch_size is set. Default 4, range [1, 64]. Ignored when batch_size is None.

  • show_progress (bool) – If True and tqdm is installed, display a progress bar while submitting batches. Ignored when batch_size is None. Defaults to True.

  • timeout (float | None) – Per-call timeout in seconds. Applied per batch when batching. None uses the client-level default.

Returns:

UpsertResponse with the count of vectors upserted.

Raises:

  • PineconeTypeError – If a vector element is not a recognized format.

  • PineconeValueError – If a vector element is malformed, if batch_size is not a positive integer, or if max_concurrency is outside [1, 64].

  • ApiError – If one request exceeds the server’s cap on vectors per request or on encoded request size. Lower batch_size and retry.

  • PineconeTimeoutError – If the call does not complete before timeout elapses.

Return type:

UpsertResponse

Notes

When batch_size is set, up to max_concurrency batches run at once (default 4, range 1-64), each retried independently on transient errors. Partial failures do not raise — the returned UpsertResponse carries upserted_count, failed_item_count, errors, and failed_items for inspection or retry. Pass response.failed_items back to upsert(...) to retry only the failures.

Examples

from pinecone.grpc import GrpcIndex
from pinecone.models.vectors.vector import Vector

idx = GrpcIndex(host="article-search-abc123.svc.pinecone.io", api_key="...")
response = idx.upsert(
    vectors=[
        Vector(
            id="article-101",
            values=[0.012, -0.087, 0.153, ...],  # 1536-dim
        ),
        ("article-102", [0.045, 0.021, -0.064, ...]),
        {"id": "article-103", "values": [0.091, -0.032, 0.178, ...]},
    ],
    namespace="articles-en",
)
print(response.upserted_count)
query(*, top_k, vector=None, id=None, namespace='', filter=None, include_values=False, include_metadata=False, sparse_vector=None, scan_factor=None, max_candidates=None, timeout=None)[source]

Query a namespace for the nearest neighbors of a vector.

Note

Vector operations remain available for indexes created before 2026-07, where you supply your own vectors. An index created at 2026-07 carries a document schema instead, and its reads and writes go through the document operations.

Parameters:

  • top_k (int) – Number of results to return, 1-10000.

  • vector (list[float] | None) – Dense query vector values.

  • id (str | None) – ID of a stored vector to use as the query.

  • namespace (str) – Namespace to query. Defaults to the default namespace.

  • filter (dict[str, Any] | None) – Metadata filter expression.

  • include_values (bool) – Whether to include vector values in results.

  • include_metadata (bool) – Whether to include metadata in results.

  • sparse_vector (SparseValues | dict[str, Any] | None) – Sparse query vector with indices and values.

  • scan_factor (float | None) – Recall/latency trade for dedicated read node (DRN) indexes — a multiplier on how much of the index is scanned. Above 1 scans more and favours recall; below 1 scans less and favours latency. Omit to let the server choose.

  • max_candidates (int | None) – Recall/latency trade for dedicated read node (DRN) indexes — caps how many candidates are reranked before top_k is taken. Must be at least top_k: a smaller value is rejected rather than clamped, since it could not fill the page.

  • timeout (float | None) – Per-call timeout in seconds. None uses the client-level default.

Returns:

QueryResponse with matches, namespace, and usage info.

Raises:

  • PineconeValueError – If top_k is not between 1 and 10000, id is combined with vector or sparse_vector, none of vector, id, or sparse_vector is provided, or id is not a legal vector ID.

  • ApiError – If scan_factor or max_candidates is out of range, or the index is not a dense DRN index — both knobs are rejected on on-demand indexes and on sparse indexes.

  • PineconeTimeoutError – If the call does not complete before timeout elapses.

Return type:

QueryResponse

Examples

response = idx.query(
    top_k=10,
    vector=[0.012, -0.087, 0.153, ...],  # 1536-dim embedding
)
for match in response.matches:
    print(match.id, match.score)
query_namespaces(*, vector=None, namespaces, metric, top_k=None, filter=None, include_values=False, include_metadata=False, sparse_vector=None, scan_factor=None, max_candidates=None, timeout=None)[source]

Query multiple namespaces in parallel and return merged top results.

Fans out individual query() calls across all given namespaces using a thread pool, then merges results via a heap-based aggregator that returns the overall top-k matches ranked by the specified metric.

Parameters:

  • vector (Sequence[float] | None) – Dense query vector values. Required for dense and hybrid indexes; omit for sparse-only indexes (use sparse_vector instead).

  • namespaces (Sequence[str]) – Namespaces to query (must be non-empty). Duplicates are removed while preserving order.

  • metric (str) – Distance metric — "cosine", "euclidean", or "dotproduct".

  • top_k (int | None) – Maximum number of results to return. Defaults to 10.

  • filter (Mapping[str, Any] | None) – Metadata filter expression applied to every namespace.

  • include_values (bool) – Whether to include vector values in results.

  • include_metadata (bool) – Whether to include metadata in results.

  • sparse_vector (SparseValues | Mapping[str, Any] | None) – Sparse query vector with indices and values. Required for sparse-only indexes when vector is omitted.

  • scan_factor (float | None) – Recall/latency trade for dedicated read node (DRN) indexes — a multiplier on how much of the index is scanned. Above 1 scans more and favours recall; below 1 scans less and favours latency. Applied to every namespace queried.

  • max_candidates (int | None) – Recall/latency trade for dedicated read node (DRN) indexes — caps how many candidates are reranked before top_k is taken, per namespace. Must be at least top_k.

  • timeout (float | None)

Returns:

QueryNamespacesResults with the merged top-k matches, total usage, and per-namespace usage.

Raises:

  • PineconeValueError – If namespaces is empty, if both vector and sparse_vector are absent/empty, or if metric is not a recognized value.

  • ApiError – If any individual namespace query fails.

  • PineconeConnectionError – If a network-level connection fails (DNS, refused, transport error).

  • PineconeTimeoutError – If the request does not complete before the configured timeout elapses.

Return type:

QueryNamespacesResults

Examples

# Dense query
results = idx.query_namespaces(
    vector=[0.012, -0.087, 0.153],  # truncated; use your actual dimension
    namespaces=["articles-en", "articles-fr", "articles-de"],
    metric="cosine",
    top_k=10,
)

# Sparse-only query (sparse index)
results = idx.query_namespaces(
    sparse_vector={"indices": [0, 1, 2], "values": [0.1, 0.2, 0.3]},
    namespaces=["docs-en", "docs-fr"],
    metric="dotproduct",
    top_k=10,
)

for match in results.matches:
    print(match.id, match.score)
fetch(*, ids, namespace='', timeout=None)[source]

Fetch vectors by their IDs from a namespace.

Parameters:

  • ids (list[str]) – List of vector IDs to fetch (must be non-empty).

  • namespace (str) – Namespace to fetch from. Defaults to the default namespace.

  • timeout (float | None) – Per-call timeout in seconds. None uses the client-level default.

Returns:

FetchResponse with a map of vector IDs to Vector objects, namespace, and usage info.

Raises:
Return type:

FetchResponse

Examples

response = idx.fetch(ids=["article-101", "article-102"])
for vid, vec in response.vectors.items():
    print(vid, vec.values)
fetch_by_metadata(*, filter, namespace='', limit=None, pagination_token=None, timeout=None)[source]

Fetch vectors matching a metadata filter expression.

Parameters:

  • filter (Mapping[str, Any]) – Metadata filter expression (required, at least one condition).

  • namespace (str) – Namespace to fetch from. Defaults to the default namespace.

  • limit (int | None) – Maximum number of vectors to return per page, 1-10000. Omit to let the server choose the page size.

  • pagination_token (str | None) – Token from a previous response to fetch the next page.

  • timeout (float | None) – Per-call timeout in seconds.

Returns:

FetchByMetadataResponse with matched vectors, namespace, usage, and pagination token for the next page (if any).

Raises:
Return type:

FetchByMetadataResponse

Examples

response = idx.fetch_by_metadata(
    filter={"category": {"$eq": "science"}},
    limit=50,
)
for vid, vec in response.vectors.items():
    print(vid, vec.metadata)
delete(*, ids=None, delete_all=False, filter=None, namespace='', timeout=None)[source]

Delete vectors from a namespace by ID, filter, or delete-all flag.

Exactly one of ids, delete_all, or filter must be specified.

A by-filter delete selects on metadata alone, so a text-match operator ($match_phrase, $match_all, $match_any) in the filter is rejected rather than ignored — evaluated there it would match everything and widen the delete to every record the rest of the filter admits. Text matching belongs in search().

A by-filter delete also reads before it writes, so a dedicated index scaled to zero replicas refuses it; add replicas first. Deleting by ID or with delete_all is unaffected.

Parameters:

  • ids (list[str] | None) – List of vector IDs to delete.

  • delete_all (bool) – If True, delete all vectors in the namespace.

  • filter (dict[str, Any] | None) – Metadata filter expression selecting vectors to delete.

  • namespace (str) – Namespace to delete from. Defaults to the default namespace.

  • timeout (float | None) – Per-call timeout in seconds. None uses the client-level default.

Returns:

None

Raises:

  • PineconeValueError – If zero or more than one deletion mode is specified, any ID is not a legal vector ID, or filter is empty.

  • ApiError – If a by-filter delete uses a text-match operator, or the index is a dedicated index scaled to zero replicas.

  • PineconeTimeoutError – If the call does not complete before timeout elapses.

Return type:

None

Examples

# Delete by IDs
idx.delete(ids=["article-101", "article-102"])

# Delete all vectors in a namespace
idx.delete(delete_all=True, namespace="articles-deprecated")

# Delete by metadata filter
idx.delete(filter={"category": {"$eq": "obsolete"}})
update(*, id=None, values=None, sparse_values=None, set_metadata=None, namespace='', filter=None, dry_run=False, timeout=None)[source]

Update vectors by ID or metadata filter.

A by-filter update selects on metadata alone, so a text-match operator ($match_phrase, $match_all, $match_any) in the filter is rejected rather than ignored — evaluated there it would match everything and widen the patch to every record the rest of the filter admits. Text matching belongs in search().

A by-filter update also reads before it writes, so a dedicated index scaled to zero replicas refuses it; add replicas first. Updating by ID is unaffected.

Parameters:

  • id (str | None) – ID of the vector to update.

  • values (list[float] | None) – New dense vector values.

  • sparse_values (SparseValues | dict[str, Any] | None) – New sparse vector.

  • set_metadata (dict[str, Any] | None) – Metadata fields to set or overwrite.

  • namespace (str) – Namespace to target. Defaults to the default namespace.

  • filter (dict[str, Any] | None) – Metadata filter expression selecting vectors to update.

  • dry_run (bool) – If True, return the count of records that would be affected without applying changes.

  • timeout (float | None) – Per-call timeout in seconds. None uses the client-level default.

Returns:

UpdateResponse with matched_records count (when available).

Raises:

  • PineconeValueError – If both or neither of id and filter are provided, if filter is combined with values or sparse_values, if filter is empty, or if id is not a legal vector ID.

  • ApiError – If a by-filter update uses a text-match operator, or the index is a dedicated index scaled to zero replicas.

  • PineconeTimeoutError – If the call does not complete before timeout elapses.

Return type:

UpdateResponse

Examples

# Update by ID
idx.update(id="article-101", values=[0.012, -0.087, 0.153, ...])

# Bulk-update metadata by filter
idx.update(
    filter={"genre": {"$eq": "drama"}},
    set_metadata={"year": 2020},
)
list_paginated(*, prefix=None, limit=None, pagination_token=None, namespace='', timeout=None)[source]

Fetch a single page of vector IDs from a namespace.

Parameters:

  • prefix (str | None) – Return only IDs starting with this prefix.

  • limit (int | None) – Maximum number of IDs to return in this page, 1-100.

  • pagination_token (str | None) – Token from a previous response to fetch the next page.

  • namespace (str) – Namespace to list from. Defaults to the default namespace.

  • timeout (float | None) – Per-call timeout in seconds. None uses the client-level default.

Returns:

ListResponse with vector IDs, pagination info, namespace, and usage.

Raises:
Return type:

ListResponse

Examples

response = idx.list_paginated(prefix="doc1#", limit=50)
for item in response.vectors:
    print(item.id)
list(*, prefix=None, limit=None, namespace='', timeout=None)[source]

List vector IDs in a namespace, automatically following pagination.

Yields one ListResponse per page.

Parameters:

  • prefix (str | None) – Return only IDs starting with this prefix.

  • limit (int | None) – Maximum number of IDs to return per page.

  • namespace (str) – Namespace to list from. Defaults to the default namespace.

  • timeout (float | None) – Per-call timeout in seconds applied to each page request. None uses the client-level default.

Yields:

ListResponse for each page of results.

Raises:
Return type:

Iterator[ListResponse]

Examples

for page in idx.list(prefix="doc1#"):
    for item in page.vectors:
        print(item.id)
describe_index_stats(*, filter=None, timeout=None)[source]

Return statistics for this index.

Parameters:

  • filter (dict[str, Any] | None) – Metadata filter expression. Accepted for API compatibility, but a non-empty filter is rejected for every index type, so the call fails instead of returning filtered counts. Leave it unset: the statistics returned always describe the whole index.

  • timeout (float | None) – Per-call timeout in seconds. None uses the client-level default.

Returns:

DescribeIndexStatsResponse with namespace summaries, dimension, total vector count, and fullness metrics.

Raises:

  • ApiError – If a non-empty filter is provided, since it is rejected for every index type.

  • PineconeTimeoutError – If the call does not complete before timeout elapses.

Return type:

DescribeIndexStatsResponse

Examples

stats = idx.describe_index_stats()
print(stats.total_vector_count, stats.dimension)
upsert_from_dataframe(df, namespace='', batch_size=500, show_progress=True, timeout=None, *, max_concurrency=None, total_timeout=None, on_error=None)[source]

Upsert vectors from a pandas DataFrame.

Splits the DataFrame into batches of batch_size rows, submits batches in parallel, and aggregates the results into a single response.

Parameters:

  • df (pd.DataFrame) – A pandas.DataFrame with at least id and values columns. sparse_values and metadata columns are included when present and non-None.

  • namespace (str) – Target namespace. Defaults to the default namespace.

  • batch_size (int) – Number of rows per upsert batch. Defaults to 500.

  • show_progress (bool) – If True and tqdm is installed, display a progress bar. The bar advances as batches complete. If tqdm is not installed, silently falls back to no progress bar.

  • max_concurrency (int | None) – Number of batches in flight at once, range [1, 64]. None (default) uses min(32, cpu_count + 4) — pass a value to make throughput reproducible across hosts.

  • on_error (Literal['raise', 'collect'] | None) – What to do when some batches fail. "collect" returns an UpsertResponse carrying failed_item_count, errors and failed_items, so the caller can retry only what failed — the same contract the REST client has had since v9.0.0. "raise" re-raises the lowest-indexed batch failure, after all batches have settled, with the partial result attached to the exception’s response attribute. None (default) behaves as "collect" and additionally warns once per process when a partial failure occurs, since this method used to raise; pass "collect" explicitly to silence that.

  • total_timeout (float | None) – Deadline in seconds for the whole ingest, as opposed to timeout, which bounds a single attempt of a single batch. On expiry no further batches are submitted; batches already in flight are allowed to settle rather than being abandoned, since dropping them client-side would not stop the server from applying them. PineconeTimeoutError is then raised carrying the partial UpsertResponse on its response attribute, whose failed_items are the rows that were never sent. None (default) means the ingest is bounded only by the per-batch deadlines.

  • timeout (float | None) –

    Server-side deadline in seconds applied to each batch’s upsert request — not to the DataFrame as a whole. None (default) uses the client’s configured request timeout: the timeout passed to GrpcIndex (20.0s unless you override it). Each attempt of a batch is bounded by this deadline (transient errors may be retried, so a batch’s total wall-clock can exceed it). Result collection then waits for the server, so a large ingest is bounded only by these per-batch deadlines rather than failing prematurely. Raise timeout to give slow batches more time on the server.

    This is not a bound on the batch. With the default max_retries=5 a batch is up to 6 attempts × timeout, plus backoff between them — timeout=120 admits a worst case near 17 minutes for a single batch. See the four timeout layers on GrpcIndex. To shrink the multiplier, pass a retry_config with a lower max_retries when constructing the index.

Returns:

UpsertResponse with the total count of vectors upserted across all batches.

Raises:

  • RuntimeError – If pandas is not installed. It is not an SDK dependency; install it yourself with pip install pandas.

  • PineconeValueError – If df is not a pandas.DataFrame or batch_size is not a positive integer.

  • PineconeTimeoutError – If a batch exceeds timeout on the server, or if total_timeout expires before every batch is submitted. In the latter case the exception carries the partial UpsertResponse on its response attribute.

Return type:

UpsertResponse

Note

Changed in 9.2.0. Partial failures are aggregated rather than raised, matching upsert() with batch_size and the REST client. Callers that relied on the raise should pass on_error="raise". The old raise discarded the partial count, so no caller could tell what had landed; the new default reports it. Because upserts are idempotent by vector ID, re-running the whole DataFrame after a failure is also still safe.

Examples

import pandas as pd
from pinecone.grpc import GrpcIndex

idx = GrpcIndex(
    host="article-search-abc123.svc.pinecone.io",
    api_key="your-api-key",
)
df = pd.DataFrame([
    {"id": "article-101", "values": [0.012, -0.087, 0.153]},
    {"id": "article-102", "values": [0.045, 0.021, -0.064]},
])
response = idx.upsert_from_dataframe(df)
response.upserted_count

df = pd.DataFrame([
    {
        "id": "article-101",
        "values": [0.012, -0.087, 0.153],
        "metadata": {"topic": "science", "year": 2024},
    },
    {
        "id": "article-102",
        "values": [0.045, 0.021, -0.064],
        "metadata": {"topic": "technology", "year": 2024},
    },
])
response = idx.upsert_from_dataframe(
    df,
    namespace="articles-en",
    batch_size=100,
)

Give each batch a longer server-side deadline for large or slow ingests:

response = idx.upsert_from_dataframe(
    df,
    batch_size=200,
    timeout=120.0,
)
upsert_async(*, vectors, namespace='', timeout=None)[source]

Submit an upsert operation and return a PineconeFuture.

Same parameters as upsert(), including timeout (float | None) which sets a per-call timeout in seconds.

Returns:

PineconeFuture [UpsertResponse] that resolves to the upsert result.

Parameters:
Return type:

PineconeFuture[UpsertResponse]

Examples

future = index.upsert_async(
    vectors=[("doc-42", [0.012, -0.087, 0.153])],
)
result = future.result()
result.upserted_count  # 1
query_async(*, top_k, vector=None, id=None, namespace='', filter=None, include_values=False, include_metadata=False, sparse_vector=None, scan_factor=None, max_candidates=None, timeout=None)[source]

Submit a query operation and return a PineconeFuture.

Same parameters as query(), including timeout (float | None) which sets a per-call timeout in seconds.

Returns:

PineconeFuture [QueryResponse] that resolves to the query result containing scored matches.

Parameters:
Return type:

PineconeFuture[QueryResponse]

Examples

future = index.query_async(
    vector=[0.012, -0.087, 0.153],
    top_k=5,
)
result = future.result()
result.matches[0].id    # 'doc-42'
result.matches[0].score  # 0.95
fetch_async(*, ids, namespace='', timeout=None)[source]

Submit a fetch operation and return a PineconeFuture.

Same parameters as fetch(), including timeout (float | None) which sets a per-call timeout in seconds.

Returns:

PineconeFuture [FetchResponse] that resolves to the fetched vectors keyed by ID.

Parameters:
Return type:

PineconeFuture[FetchResponse]

Examples

future = index.fetch_async(ids=["doc-42", "doc-43"])
result = future.result()
result.vectors["doc-42"].values  # [0.012, -0.087, 0.153]
delete_async(*, ids=None, delete_all=False, filter=None, namespace='', timeout=None)[source]

Submit a delete operation and return a PineconeFuture.

Same parameters as delete(), including timeout (float | None) which sets a per-call timeout in seconds.

Returns:

PineconeFuture [None] that resolves when the delete operation completes.

Parameters:
Return type:

PineconeFuture[None]

Examples

future = index.delete_async(ids=["doc-42", "doc-43"])
future.result()

future = index.delete_async(delete_all=True, namespace="docs")
future.result()
update_async(*, id=None, values=None, sparse_values=None, set_metadata=None, filter=None, namespace='', dry_run=False, timeout=None)[source]

Submit an update operation and return a PineconeFuture.

Same parameters as update(), including timeout (float | None) which sets a per-call timeout in seconds.

Returns:

PineconeFuture [UpdateResponse] that resolves to the update result.

Parameters:
Return type:

PineconeFuture[UpdateResponse]

Examples

future = index.update_async(
    id="article-101", values=[0.012, -0.087, 0.153]
)
result = future.result()
query_namespaces_async(*, vector=None, namespaces, metric, top_k=None, filter=None, include_values=False, include_metadata=False, sparse_vector=None, scan_factor=None, max_candidates=None, timeout=None)[source]

Submit a query_namespaces operation and return a PineconeFuture.

Same parameters as query_namespaces(), including timeout (float | None) which sets a per-call timeout in seconds.

Returns:

PineconeFuture [QueryNamespacesResults] that resolves to the merged top-k matches across namespaces.

Parameters:
Return type:

PineconeFuture[QueryNamespacesResults]

Examples

future = idx.query_namespaces_async(
    vector=[0.012, -0.087, 0.153],  # truncated; use your actual dimension
    namespaces=["articles-en", "articles-fr", "articles-de"],
    metric="cosine",
    top_k=10,
)
results = future.result()
for match in results.matches:
    print(match.id, match.score)
upsert_records(*, records, namespace, timeout=None)[source]

Upsert records for indexes with integrated inference.

Embeddings are generated server-side from the fields you provide, so each record carries source data (e.g. text) rather than precomputed vector values.

Parameters:

  • records (list[dict[str, Any]]) – List of record dicts. Each must contain an _id or id field. Additional fields are passed through for server-side embedding.

  • namespace (str) – Target namespace (required). Unlike upsert(), namespace has no default because the records API requires an explicit namespace (must be non-empty).

  • timeout (float | None)

Returns:

UpsertRecordsResponse with the count of records submitted.

Raises:

  • PineconeValueError – If namespace is not a string or is empty/whitespace, records is empty, or a record is missing an identifier field.

  • ApiError – If the API returns an error response.

  • PineconeConnectionError – If a network-level connection fails (DNS, refused, transport error).

  • PineconeTimeoutError – If the request does not complete before timeout elapses.

Return type:

UpsertRecordsResponse

Examples

pc = Pinecone(api_key="YOUR_API_KEY")
idx = pc.index("my-index", grpc=True)
response = idx.upsert_records(
    namespace="articles-en",
    records=[
        {"_id": "article-101", "text": "Vector DBs enable similarity search."},
        {"_id": "article-102", "text": "RAG combines search with LLMs."},
    ],
)
print(response.record_count)
search(*, namespace, top_k=None, inputs=None, vector=None, id=None, filter=None, fields=None, rerank=None, match_terms=None, query=None, timeout=None)[source]

Search records by text, vector, or ID with optional reranking.

Delegates to the REST endpoint because the Pinecone gRPC API does not expose a records search operation for integrated inference indexes.

Note

Use this method for indexes with integrated inference. For classic indexes where you provide your own vectors, use query().

Parameters:

  • namespace (str) – Namespace to search in (required).

  • top_k (int) – Number of results to return (must be >= 1).

  • inputs (SearchInputs | dict[str, Any] | None) – Inputs for server-side embedding (e.g. {"text": "query text"}).

  • vector (list[float] | None) – Dense query vector values.

  • id (str | None) – ID of an existing record to use as the query.

  • filter (dict[str, Any] | None) – Metadata filter expression.

  • fields (list[str] | None) – Field names to include in results. When None, the server returns all available fields.

  • rerank (RerankConfig | dict[str, Any] | None) – Reranking configuration with model (required), rank_fields (required), and optional top_n, parameters, query keys. Use RerankConfig for IDE autocompletion.

  • match_terms (dict[str, Any] | None) – Term-matching constraint for sparse search. Requires keys "strategy" (currently only "all") and "terms" (list of strings). Valid only on a text query — combined with vector or id it is rejected — and only on a sparse index whose embedding model supports it; the server names the supported model when it refuses. None disables term matching.

  • query (dict[str, Any] | None) – Legacy query body containing top_k plus one of inputs, vector, or id. Prefer passing these fields directly.

  • timeout (float | None)

Returns:

SearchRecordsResponse with hits and usage statistics.

Raises:
Return type:

SearchRecordsResponse

Examples

response = idx.search(
    namespace="articles-en",
    top_k=10,
    inputs={"text": "benefits of vector databases for search"},
)
for hit in response.result.hits:
    print(hit.id, hit.score)

Search with reranking:

response = idx.search(
    namespace="articles-en",
    top_k=10,
    inputs={"text": "benefits of vector databases"},
    rerank={
        "model": "bge-reranker-v2-m3",
        "rank_fields": ["text"],
        "top_n": 5,
    },
)
for hit in response.result.hits:
    print(hit.id, hit.score)

Note

Use inline rerank when searching and reranking in a single call. Use pc.inference.rerank() when reranking results from a different source or when you need to rerank without searching.

search_records(*, namespace, top_k=None, inputs=None, vector=None, id=None, filter=None, fields=None, rerank=None, match_terms=None, query=None, timeout=None)[source]

Alias for search(), kept for backwards compatibility.

Prefer calling search() directly.

Examples

response = idx.search_records(
    namespace="articles-en",
    top_k=10,
    inputs={"text": "benefits of vector databases for search"},
)
Parameters:
Return type:

SearchRecordsResponse

list_namespaces_paginated(*, prefix=None, limit=None, pagination_token=None, timeout=None)[source]

Fetch a single page of namespace descriptions.

Parameters:

  • prefix (str | None) – Return only namespaces whose names start with this prefix. Must be ASCII, must not contain the NUL character, and must be at most 512 characters. The empty prefix matches every namespace.

  • limit (int | None) – Maximum number of namespaces to return in this page, 1-100.

  • pagination_token (str | None) – Token from a previous response to fetch the next page.

  • timeout (float | None) – Per-call timeout in seconds.

Returns:

ListNamespacesResponse with namespace descriptions, pagination info, and total count. Each description carries size_bytes.

Raises:

  • PineconeValueError – If prefix or limit violates the rules above. Raised locally, before the request is sent, with the same message the REST and asyncio clients raise.

  • PineconeTimeoutError – If the request does not complete before timeout elapses.

Return type:

ListNamespacesResponse

Examples

page = idx.list_namespaces_paginated(prefix="prod-", limit=50)
for ns in page.namespaces:
    print(ns.name, ns.record_count, ns.size_bytes)
list_namespaces(*, prefix=None, limit=None, timeout=None)[source]

List namespaces, automatically following pagination.

Yields one ListNamespacesResponse per page. The generator automatically follows pagination tokens until all pages have been retrieved.

Parameters:

  • prefix (str | None) – Return only namespaces whose names start with this prefix. Must be ASCII, must not contain the NUL character, and must be at most 512 characters. The empty prefix matches every namespace.

  • limit (int | None) – Maximum number of namespaces to return per page, 1-100.

  • timeout (float | None) – Per-call timeout in seconds.

Yields:

ListNamespacesResponse for each page of results. Each NamespaceDescription carries size_bytes.

Raises:

  • PineconeValueError – If prefix or limit violates the rules above. Raised on the first iteration, before the request is sent.

  • PineconeTimeoutError – If a page request does not complete before timeout elapses.

Return type:

Iterator[ListNamespacesResponse]

Examples

for page in idx.list_namespaces(prefix="prod-"):
    for ns in page.namespaces:
        print(ns.name, ns.record_count, ns.size_bytes)
create_namespace(*, name, schema=None, timeout=None)[source]

Create a named namespace in the index.

Parameters:

  • name (str) – Name for the new namespace. Must be ASCII, must not contain the NUL character, and must be 1-512 characters long. __default__ is reserved and cannot be created: it names the namespace requests address when they omit a namespace, so it always exists.

  • schema (dict[str, Any] | None) – Optional metadata-index configuration, {"fields": {<field>: {"filterable": True}}}. Omitting it does not mean “index everything”: the namespace inherits the index’s own metadata-index configuration, so an index that restricts which fields are indexed passes that restriction on. Supply schema to override the inherited configuration for this namespace, indexing exactly the fields listed. filterable is required on each field and must be True — to leave a field unindexed, omit it from fields.

  • timeout (float | None) – Per-call timeout in seconds.

Returns:

NamespaceDescription with the namespace name, record count, schema, indexed fields, and size_bytes.

Raises:

  • PineconeValueError – If name violates the rules above, or schema is malformed. Raised locally, before the request is sent, with the same message the REST and asyncio clients raise.

  • PineconeTimeoutError – If the request does not complete before timeout elapses.

Return type:

NamespaceDescription

Examples

ns = idx.create_namespace(name="movies-en")
print(ns.name, ns.record_count, ns.size_bytes)
describe_namespace(*, name=None, timeout=None, **kwargs)[source]

Describe a namespace by name.

This operation is rate limited per index, independently of the other namespace operations. Prefer list_namespaces() when describing more than one namespace: it returns the same information for every namespace in a single request and is not subject to that limit.

Parameters:

  • name (str) – Name of the namespace to describe. Must be ASCII, must not contain the NUL character, and must be 1-512 characters long. __default__ is accepted and describes the namespace requests address when they omit one.

  • timeout (float | None) – Per-call timeout in seconds.

  • kwargs (str)

Returns:

NamespaceDescription with the namespace name, record count, schema, indexed fields, and size_bytes.

Raises:

  • PineconeValueError – If name violates the rules above. Raised locally, before the request is sent, with the same message the REST and asyncio clients raise.

  • TypeError – If unexpected keyword arguments are passed.

  • PineconeTimeoutError – If the request does not complete before timeout elapses.

Return type:

NamespaceDescription

Examples

ns = idx.describe_namespace(name="movies-en")
print(ns.name, ns.record_count, ns.size_bytes)
delete_namespace(*, name=None, timeout=None, **kwargs)[source]

Delete a namespace by name, removing all its vectors.

Parameters:

  • name (str) – Name of the namespace to delete. Must be ASCII, must not contain the NUL character, and must be 1-512 characters long.

  • timeout (float | None) – Per-call timeout in seconds.

  • kwargs (str)

Returns:

None — a successful delete returns no payload.

Raises:

  • PineconeValueError – If name violates the rules above. Raised locally, before the request is sent, with the same message the REST and asyncio clients raise.

  • TypeError – If unexpected keyword arguments are passed.

  • PineconeTimeoutError – If the request does not complete before timeout elapses.

Return type:

None

Examples

idx.delete_namespace(name="movies-en")
start_import(uri, *, error_mode=None, integration_id=None)[source]

Start a bulk import operation from an external data source.

Initiates an asynchronous bulk import of vectors from cloud storage into the index. The import runs server-side; use describe_import() to poll for progress and completion.

Note

The import URI must point to a directory of Parquet files in cloud storage. Each Parquet file must follow the Pinecone-required schema. See Pinecone import docs for the required Parquet schema and supported storage formats.

Parameters:

  • uri (str) – Directory prefix holding the Parquet files, not a single file. Three forms are accepted: s3:// for Amazon S3, gs:// for Google Cloud Storage, and an https:// URL naming an Azure Blob Storage container. s3:// additionally requires that the index itself be hosted on AWS.

  • error_mode (str | None) – How to handle a record the import cannot read. "continue" skips it and imports the rest; "abort" ends the whole import at the first such record. Case-insensitive. Defaults to "abort" when omitted, so an unreadable record fails the import unless you opt into skipping.

  • integration_id (str | None) – Optional integration ID for the import.

Returns:

StartImportResponse with the ID of the created import operation.

Raises:

  • PineconeValueError – If error_mode is supplied but not "continue" or "abort".

  • ApiError – If uri is empty or longer than the server accepts, uses an unsupported scheme, is an s3:// URI on an index not hosted on AWS, or names an S3 directory bucket, which imports do not support, or if the API otherwise returns an error response.

  • PineconeConnectionError – If a network-level connection fails (DNS, refused, transport error).

  • PineconeTimeoutError – If the request does not complete before the configured timeout elapses.

Return type:

StartImportResponse

Examples

# Start an import and poll until complete
import time
response = idx.start_import(uri="s3://my-bucket/vectors/")
import_id = response.id

# Poll until the import finishes
import_op = idx.describe_import(import_id)
while import_op.status not in ("Completed", "Failed", "Cancelled"):
    time.sleep(10)
    import_op = idx.describe_import(import_id)
print(f"Status: {import_op.status}, records imported: {import_op.records_imported}")

# Skip unreadable records instead of failing the import
response = idx.start_import(
    uri="s3://my-bucket/vectors/",
    error_mode="continue",
)

See also

  • upsert() — for upserting vectors directly in small batches (single request per call).

  • upsert_records() — for indexes with integrated inference (text in, server-side embedding).

  • upsert_from_dataframe() — for loading vectors from a pandas DataFrame with automatic batching.

describe_import(id)[source]

Describe a bulk import operation by ID.

Parameters:

id (str | int) – Import operation ID. Integers are converted to strings silently.

Returns:

ImportModel with the import operation details.

Raises:
Return type:

ImportModel

Examples

import_op = idx.describe_import("import-123")
print(import_op.status, import_op.percent_complete)
cancel_import(id)[source]

Cancel a running bulk import operation by ID.

Parameters:

id (str | int) – ID of the import to cancel, as returned by start_import(). Integers are converted to strings silently.

Returns:

None — a successful cancellation returns no payload.

Raises:
Return type:

None

Examples

idx.cancel_import("import-123")
list_imports(*, limit=None, pagination_token=None)[source]

List bulk import operations, automatically following pagination.

Yields individual ImportModel objects, fetching additional pages transparently until all results have been returned. Prefer list_imports_paginated() to control pagination yourself.

Parameters:

  • limit (int | None) – Maximum number of imports per page. Omit to let the server choose the page size.

  • pagination_token (str | None) – Token to resume pagination from a previous call.

Yields:

ImportModel for each import operation.

Raises:
Return type:

Iterator[ImportModel]

Examples

for imp in idx.list_imports():
    print(imp.id, imp.status)
list_imports_paginated(*, limit=None, pagination_token=None)[source]

Fetch a single page of bulk import operations.

Returns an ImportList for one page. The caller is responsible for managing the pagination token. Prefer list_imports() to have pagination handled automatically.

Parameters:

  • limit (int | None) – Maximum number of imports to return in this page.

  • pagination_token (str | None) – Token from a previous response to fetch the next page.

Returns:

ImportList for the requested page, iterable over its ImportModel entries. Its pagination.next field holds the token for the next page, or None once there are no more.

Raises:
Return type:

ImportList

Examples

page = idx.list_imports_paginated(limit=10)
for imp in page:
    print(imp.id, imp.status)

next_token = page.pagination.next if page.pagination else None
close()[source]

Close the connection to the index and release background resources.

Waits for any in-flight *_async submissions to finish, then shuts down the worker pools used for batch upserts and closes the network connection. Call this when you are done issuing requests through this client and are not using it as a context manager.

Examples

idx = pc.index("my-index", grpc=True)
idx.upsert(vectors=[...])
idx.close()
Return type:

None

__enter__()[source]

Enter a context manager block, returning this client unchanged.

Examples

with pc.index("my-index", grpc=True) as idx:
    idx.upsert(vectors=[...])
Return type:

GrpcIndex

__exit__(*args)[source]

Exit the context manager block, calling close().

Parameters:

args (Any)

Return type:

None

PineconeFuture

*_async() methods on GrpcIndex return a PineconeFuture which is fully compatible with concurrent.futures.as_completed() and concurrent.futures.wait().

class pinecone.grpc.future.PineconeFuture(underlying)[source]

Bases: Future[_T]

Future returned by GrpcIndex.*_async() methods.

Wraps a concurrent.futures.Future and is fully compatible with concurrent.futures.as_completed() and concurrent.futures.wait().

The default result() timeout is 5 seconds. When the timeout elapses, PineconeTimeoutError is raised with the message "deadline exceeded".

Examples

from pinecone.grpc import GrpcIndex
idx = GrpcIndex(host="article-search-abc123.svc.pinecone.io", api_key="your-api-key")
future = idx.upsert_async(vectors=[("article-101", [0.012, -0.087, 0.153, ...])])
result = future.result()  # blocks up to 5 seconds
result.upserted_count
# 1

from concurrent.futures import as_completed
futures = [
    idx.upsert_async(vectors=[("article-101", [0.012, -0.087, 0.153, ...])]),
    idx.upsert_async(vectors=[("article-102", [0.045, 0.021, -0.064, ...])]),
]
for future in as_completed(futures):
    print(future.result().upserted_count)
Parameters:

underlying (Future[_T])

__init__(underlying)[source]

Initializes the future. Should not be called by clients.

Parameters:

underlying (Future[_T])

Return type:

None

add_done_callback(fn)[source]

Attach a callable to be called when the future finishes.

The callable will be called with the future as its only argument.

Parameters:

fn (Callable[[...], Any])

Return type:

None

cancel()[source]

Attempt to cancel the underlying call.

Returns True if the call was successfully cancelled, False if the call has already completed or is running.

Return type:

bool

cancelled()[source]

Return True if the call was successfully cancelled.

Return type:

bool

done()[source]

Return True if the call has completed or was cancelled.

Return type:

bool

exception(timeout=5.0)[source]

Return the exception raised by the call, or None.

Parameters:

timeout (float | None) – Maximum seconds to wait. Defaults to 5.0.

Raises:

PineconeTimeoutError – If timeout seconds elapse.

Return type:

BaseException | None

result(timeout=5.0)[source]

Return the result of the call that the future represents.

Parameters:

timeout (float | None) – Maximum seconds to wait. Defaults to 5.0. Pass None to block indefinitely.

Returns:

The result value set by the underlying future.

Raises:

PineconeTimeoutError – If timeout seconds elapse before the result is available.

Return type:

_T

Examples

future = idx.upsert_async(vectors=[("article-101", [0.012, -0.087, 0.153, ...])])
result = future.result()
result.upserted_count  # 1

future = idx.upsert_async(vectors=large_batch)
result = future.result(timeout=30.0)

result = future.result(timeout=None)
running()[source]

Return True if the call is currently being executed.

Return type:

bool