pypi / pinecone
pinecone
What changed in pinecone 9 to 10, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-20.
34 breaking3 security1 deprecations36 new APIs and options17 behavior and defaults1 tooling39 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initpinecone 1046 changes
Breaking changes 19
Adds role-binding management; authorization uses one role, one principal, and one scope, with no other source of permissions.
Becomes an explicit runtime dependency with a minimum version of 4.0.
Streaming assistant chat no longer aborts at 30 seconds; without a per-call timeout, the read floor is 300 seconds.
Removes error_message; read error from the assistant operations API instead.
Removes percent_done; read percent_complete from the assistant operations API instead.
Becomes a coroutine, so callers must await it.
Removes dimension from BackupModel; read schema instead.
Removes metric from BackupModel; read schema instead.
Invalid values and argument combinations now raise PineconeValueError or PineconeTypeError locally before a request; these are not ApiError subclasses.
Removes the [dev] extra; use uv sync --group dev instead.
Backup schedules accept exactly daily, weekly, or monthly; cron is not supported.
No longer raises on partial failure by default; failures are collected in the response. Set on_error="raise" to restore the previous behavior.
Adds document upsert, search, fetch, list, update, delete, and batch_upsert on sync and async index clients for indexes created with a 2026-07 document schema.
The created_at property is removed from IndexModel.
Returns Paginator[IndexModel] instead of IndexList, so .names() is unavailable on this path; pc.list_indexes() is unchanged.
Removes the preview namespace and its classes and modules without a shim; graduated APIs are available on the main client.
Encodes every REST path parameter at the transport boundary to prevent caller-supplied slashes and dot segments from addressing a different endpoint.
Builds an index schema in Python; add methods return the builder and build() returns a dict suitable for pc.indexes.create(schema=...).
The async rerank path now enforces top_n >= 1.
Security 1
Masks the access token in repr() and str(), showing only its last four characters.
New APIs and options 17
Adds organization invite management to the Admin client.
Adds service-account management to the Admin client.
Adds user management to the Admin client.
Assistant chat stream chunks now carry content_filter_results.
Adds members for models available at API version 2026-07.
Adds an ApiError subclass for HTTP 412 responses.
Adds an exported typed object for per-string-field full-text search configuration, including language, stemming, stop words, and character n-grams.
Adds an exported typed object for character n-gram configuration; n-grams cannot be combined with stemming or stop words.
Adds an ApiError subclass for HTTP 402 responses.
Describes assistant operations, exposing status, percent_complete, and error so asynchronous file writes can be followed.
Lists assistant operations so asynchronous jobs can be followed.
Adds recurring backup schedule management and per-schedule run history. Frequency supports daily, weekly, or monthly; only one enabled schedule per index is allowed.
Accepts read_capacity to apply dedicated read capacity while restoring an index.
Adds dedicated read capacity configuration at index creation, configure, or restore for managed and BYOC indexes; the setting reads back from IndexModel.read_capacity.
Adds an id to StreamMessageStart.
Adds a deadline for an entire batched upsert call; when it expires, submission stops, in-flight batches finish, and unsent items are returned as failures.
Adds on_error to choose between collecting partial failures in the response or raising; failed rows are available in response.failed_items.
Behavior and default changes 3
Batched upsert defaults max_concurrency to 8, up from 4; an adaptive per-host admission gate can limit or abandon batch submission.
A plaintext gRPC data plane using http against a non-loopback, non-private host now emits one RuntimeWarning per process.
The default API version header is 2026-07 on every plane; set the header explicitly to pin an older version.
Fixes and other changes 6
Is now populated in namespace descriptions.
The grpc overload narrows the return type so index.documents type-checks under mypy and pyright.
Now reaches the transport that opens the socket, so the setting takes effect.
The SDK is tested and classified on Python 3.10 through 3.14; its Python requirement floor remains 3.10.
Now reaches the transport that opens the socket, so the setting takes effect.
Now reaches the transport that opens the socket, so the setting takes effect.
pinecone 985 changes
Breaking changes 15
The default changes from 2.0 to 0.25; the value is now the minimum delay floor in the decorrelated-jitter formula, not an exponential multiplier.
REST now counts
max_retriesas retries after the initial attempt, matching gRPC; N retries allow up to N+1 total requests.Makes name nullable and removes the unused description field.
Removes the dead description parameter because the server does not accept it.
Enforces an 80-character API key name limit.
Cancelled and Timeout expired errors from the gRPC backend are raised as PineconeTimeoutError instead of grpc.RpcError.
Rejects top_k values greater than 10000 client-side.
Rejects limit values below 1 client-side.
Polling raises IndexTerminatedError when an index enters Terminating or Disabled instead of waiting for the operator timeout.
Rejects combining type=rerank with a vector_type argument.
Rejects top_n values below 1 client-side with ValidationError.
Removes the nonfunctional filter parameter; calls passing filter now raise TypeError.
Removes the nonfunctional filter parameter; calls passing filter now raise TypeError.
Rejects empty ids lists.
Rejects records with a non-string, empty, or null-byte-containing _id before making the HTTP call.
Security 2
Validates collection resource names client-side for length and allowed characters.
Validates project name length and null bytes, and refuses negative max_pods.
Deprecations 1
The field keyword remains supported as a deprecated alias for fields and is planned for removal in a future release.
New APIs and options 19
Accepts a single
query=request body as aSearchQueryor plainMapping; passing it with direct kwargs or with the wrong type raisesTypeError.Bulk import operations are now available on
GrpcIndex, includingcancel_import.Bulk import operations are now available on
GrpcIndex, includingdescribe_import.Bulk import operations are now available on
GrpcIndex, includinglist_imports.Bulk import operations are now available on
GrpcIndex, includinglist_imports_paginated.Accepts a single
query=request body as aSearchQueryor plainMapping; passing it with direct kwargs or with the wrong type raisesTypeError.Bulk import operations are now available on
GrpcIndex, includingstart_import.Accepts a single
query=request body as aSearchQueryor plainMapping; passing it with direct kwargs or with the wrong type raisesTypeError.HTTP 429 responses now raise a dedicated
ApiErrorsubclass, exported frompinecone.errorsand the top-levelpineconenamespace.A
RateLimitExceptionalias is available for the new throttling exception.The backcompat shim now accepts messages= to match the deprecated v8 signature.
Accepts sparse and hybrid vector query dictionaries alongside dense lists, and validates and normalizes dictionary keys client-side.
Accepts sparse and hybrid vector query dictionaries alongside dense lists, and validates and normalizes dictionary keys client-side.
Exposes private endpoint hosts returned by the backend.
Uses API version v202604, corrects query parameter names and pagination-token parsing, and adds page_size.
Uses API version v202604, corrects query parameter names and pagination-token parsing, and adds page_size.
Exposes private_host, source_collection, source_backup_id, and cmek_id in preview index responses.
Adds error_message to represent read capacity failure states.
Renames field to fields to support multiple field names; field remains a deprecated alias.
Behavior and default changes 14
Bulk operations automatically reduce per-host in-flight requests under throttling and recover after successes;
max_concurrencyremains the ceiling.Namespace fan-out is capped at 10 in-flight requests instead of issuing one unbounded request per namespace.
The namespace emits DEBUG records for concurrency adjustments and an INFO record the first time a host is throttled.
The namespace emits DEBUG records for throttled retry attempts, including status, host, attempt count, and computed delay.
REST and gRPC retries now use decorrelated jitter, spreading retries across time instead of bunching them together.
Widens tags from dict[str, str] to dict[str, Any] and exposes the actual schema field.
Removes the hardcoded limit=10 default so backend-default pagination is used.
Makes host optional to handle null values during creation and Terminating states.
Header and tag inputs accept Mapping[str, str], and read-only Index operation parameters accept Mapping[str, Any].
Widens tags from dict[str, str] to dict[str, Any].
Removes the hardcoded limit=10 default so backend-default pagination is used.
The configure boundary now wraps bare schema dictionaries, accepting both fields-wrapped and short field mappings.
Public input parameters previously typed as list[T] now accept Sequence[T], including embed, rerank, and assistant messages and roles.
Allows partial Dedicated patches, such as changing min_replicas without re-specifying max_replicas.
Tooling 1
Adds an explicit public-surface stub so Jedi-based editors can resolve autocomplete and go-to-definition.
Fixes and other changes 33
Bare
list[float]queries now use the correct wire shape, so dense-vector queries work.Surfaces schema in decoded BYOC spec responses instead of dropping it.
Makes role and content optional to match streaming assistant-role chunks where values arrive on later chunks.
Exposes the usage field previously dropped during struct decoding.
Includes dimension in the index creation request instead of silently dropping it.
Populates reasoning from evaluate_alignment responses instead of returning it empty.
Adds create_namespace, describe_namespace, delete_namespace, list_namespaces, and list_namespaces_paginated to the gRPC index API.
Omits errorMode from the wire payload when error_mode is unspecified, avoiding backend rejection of null.
Widens min and max to int | float | None to match backend parameter values.
Maps the JSON field error_message into error for failed operations.
Forwards the environment parameter to the backend when creating an assistant.
Omits metadata from the request body when it is not provided, avoiding rejection by stricter backends.
Omits description from the request body when it is not provided.
Forwards serverless_read_capacity, which previously was not plumbed through the SDK.
Stops pre-merging tags client-side so partial updates are not overwritten.
With timeout=-1, returns CreateIndexFromBackupResponse directly rather than polling.
Adds the previously omitted preview backup description operation and its async counterpart.
Honors the legacy assistant control host environment variable at client construction.
Honors the legacy assistant data host environment variable at client construction.
Makes replicas, shards, and pods optional to match nullable backend responses.
Treats Terminated and Terminating as terminal assistant states so creation polling exits promptly.
Adds PreviewBooleanField to the schema union so schemas containing it are accepted.
Forwards deployment for pod index patching and completes tag and schema-field validation.
Forwards source_collection, source_backup_id, and cmek_id to the backend when creating preview indexes.
Forwards limit to the server in fetch_page instead of using a hardcoded value.
Makes host optional to match nullable backend responses.
Adds PreviewLegacyIntegerField to the schema union so schemas containing it are accepted.
Makes environment optional to match nullable backend responses.
Rejects negative max_pods before making the HTTP call.
Preserves input namespace order in results so ties break deterministically.
Makes created_at optional to match nullable backend responses.
Makes usage optional to handle null values in streaming responses.
Drops the redundant id key when _id is present to avoid backend 400 responses.