Skip to content

Release v9.0.1

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 19 May 15:31
v9.0.1
523f5a8

Release v9.0.1

v9.0.1 is a polish release. It rolls up two weeks of fixes against backend response shapes, new client-side validation, completes the gRPC namespace API, widens public input types for ergonomic flexibility, and lands a deep pass on docstrings and migration guidance.

Highlights

  • Several methods, parameters, and fields omitted from v9.0.0 are restored. Highlights include the gRPC namespace operations (create_namespace, describe_namespace, delete_namespace, list_namespaces, list_namespaces_paginated), sparse/hybrid vector queries on Index.search / AsyncIndex.search, pc.preview.indexes.describe_backup, pc.indexes.configure(serverless_read_capacity=...), pc.assistants.create(..., environment=...), and several response fields the backend was returning but the SDK was dropping. See Filling v9.0.0 gaps.
  • Schema and read_capacity are correctly forwarded everywhere. Several v9.0.0 paths (BYOC, IntegratedSpec, ServerlessSpec, async creation, the create_index shim, configure) silently dropped these fields; all are now end-to-end correct.
  • Input types are uniformly wider. Public methods that previously required list[T] now accept any Sequence[T]; dict[str, str] and dict[str, Any] parameters now accept Mapping. Existing call sites are unaffected, but tuple, generator-backed sequences, and Mapping subclasses now type-check and work without conversion.
  • Better IDE support for Jedi-based editors. A new pinecone/__init__.pyi stub fixes type resolution in Spyder, Eric, Cython, and other editors that don't follow from … import * re-exports. mypy and Pyright/Pylance users are unaffected.
  • Docstrings, examples, and the v9 migration guide got a thorough cleanup. 50+ fixes to incorrect cross-references, outdated import paths, false claims about defaults, and broken example code.

Filling v9.0.0 gaps

A handful of methods and fields that should have shipped in v9.0.0 were inadvertently left out. They are restored in v9.0.1.

gRPC namespace operations

These methods exist on the REST Index but were missing from GrpcIndex in v9.0.0:

grpc_index = pc.index("my-index", grpc=True)

grpc_index.create_namespace("orders")
ns = grpc_index.describe_namespace("orders")
for ns in grpc_index.list_namespaces():   # auto-paginating generator
    print(ns.name)
page = grpc_index.list_namespaces_paginated(limit=50)
grpc_index.delete_namespace("orders")

Index.search / AsyncIndex.search: sparse and hybrid queries

The REST search surface accepts sparse and hybrid vector queries, but v9.0.0 only plumbed dense list[float] through Index.search / AsyncIndex.search. Sparse and hybrid inputs are now accepted as a dict alongside dense lists:

index.search(
    namespace="docs",
    query={"vector": {"values": [0.1, 0.2, ...], "indices": [3, 17, 42, ...]}},
    top_k=10,
)

Keys are validated and normalized client-side; invalid combinations (e.g. values without indices on sparse) raise ValidationError before the HTTP call.

Preview: describe_backup

pc.preview.indexes.describe_backup(...) and its async counterpart were omitted from v9.0.0 and are now present.

Preview index creation and configuration

The backend accepts these parameters on preview index create / configure, but the SDK wasn't forwarding them:

  • PreviewIndexes.create(..., source_collection=..., source_backup_id=..., cmek_id=...)
  • PreviewIndexes.configure(..., deployment=...) (pod index patching)
  • PreviewIndexModel now exposes private_host, source_collection, source_backup_id, and cmek_id on the response side

Assistants: environment parameter

pc.assistants.create(..., environment=...) — the backend accepted it; the SDK was not forwarding it.

Other restored fields and parameters

  • pc.indexes.configure(serverless_read_capacity=...) — the parameter existed on the REST surface but was not plumbed through the SDK.
  • IndexModel.private_host — surfaces private-endpoint hosts the backend was already returning.
  • ByocSpecInfo.schema — was being dropped during response decoding.

New features

Widened public input types

The public surface now accepts the broadest reasonable type at every input parameter. This is purely an extension — existing list / dict call sites continue to work — but it removes a class of "I have to convert to a list first" friction:

  • list[T] → Sequence[T] on input parameters (DX-0140), including embed, rerank, and assistant messages/roles (pc.assistants.chat, etc.)
  • dict[str, str] → Mapping[str, str] for headers and tags
  • dict[str, Any] → Mapping[str, Any] for read-only params on Index operations (DX-0141)

This also unblocks downstream type-checked callers that already had widened parameter types and were forced into cast() or list(...) conversions.

pinecone/__init__.pyi stub for Jedi-based IDEs (DX-0145)

Editors that use the Jedi static analyzer (Spyder, Eric, Cython, some older VS Code setups) don't traverse from … import * re-exports, so from pinecone import Pinecone showed no autocomplete in those environments. A new pinecone/__init__.pyi stub enumerates the public surface explicitly. mypy, Pyright, and modern Pylance users are unaffected (they already resolved through the runtime module); Jedi users now see full autocomplete and go-to-definition.

A CI typecheck-drift gate (DX-0146) ensures the stub stays in sync with the runtime pinecone/__init__.py.

PreviewTextQuery: field renamed to fields

PreviewTextQuery.field is renamed to fields so it can accept multiple field names for multi-field text search. The v9.0.0 field= kwarg continues to work as a deprecated alias and will be removed in a future release. pc.preview is not covered by SemVer; see the v9.0.0 release notes.

Behavior changes

These are not breaking under SemVer (they reject inputs the backend was already rejecting), but a few new client-side checks may surface as ValidationError where v9.0.0 surfaced as a server-side error. If your code wraps these calls in try/except, no changes are needed — ValidationError is a subclass of PineconeException — but the error class and message will differ.

  • top_k > 10000 on GrpcIndex.query is now rejected client-side. REST had this check already.
  • top_n < 1 on pc.inference.rerank(...) is now rejected client-side.
  • limit < 1 on Index.fetch_by_metadata is now rejected client-side (AGT-0044).
  • upsert_records rejects records with an invalid _id field (non-string, empty, or containing null bytes) before the HTTP call.
  • pc.collections.create(name=...) validates the resource name client-side (length, character set).
  • Projects.create/update validates the project name (length ≤ 50, no null bytes) and refuses negative max_pods.
  • ApiKeys.create enforces the 80-character name length cap.
  • PreviewDocuments.fetch(ids=...) rejects empty ids lists.

Two PreviewDocuments parameters that were never functional were removed:

  • PreviewDocuments.fetch(..., filter=...) — the filter parameter was dropped; it had no effect on the backend.
  • PreviewDocuments.delete(..., filter=...) — same.

If you were passing filter= to either of these on v9.0.0, the call will now raise TypeError. The argument was never being sent, so removing it does not change observable behavior.

fix(grpc): Cancelled + "Timeout expired" from the gRPC backend is now raised as PineconeTimeoutError instead of bubbling as the lower-level grpc.RpcError (CI-0052). Code that caught PineconeTimeoutError already handles this; code that caught only grpc.RpcError will no longer see those specific timeouts.

Response-model fixes (msgspec struct nullability)

A number of v9.0.0 response structs had fields typed as non-optional that the backend in fact returns as null in some states, causing decode failures. These have been widened:

  • IndexModel.host — optional (null during creation / Terminating states)
  • BackupModel.tags — dict[str, Any] (was dict[str, str])
  • BackupModel.schema — real schema field (was an always-None stub)
  • BackupModel.metric — removed (never returned by the backend)
  • PodSpecInfo.replicas, .shards, .pods — optional
  • RestoreJobModel.created_at — optional
  • APIKeyModel.name — str | None; the dead description field is removed
  • StreamMessageEnd.usage — optional (handles null from streaming responses)
  • PreviewBackupModel.tags — dict[str, Any] (was dict[str, str])
  • PreviewIndexModel.host — optional
  • PreviewManagedDeployment.environment — optional
  • PreviewReadCapacityStatus.error_message — new field for failure states
  • ModelInfoSupportedParameter.min / .max — int | float | None (v9.0.0 declared float, but the backend returns ints for some parameters)
  • ByocSpecInfo.schema — newly surfaced

If you were destructuring these fields and bypassing None handling, add a guard. mypy will surface the new None possibilities under --strict.

Fixes

Indexes & schema

  • Forward schema and read_capacity through every index-creation path: integrated (pc.indexes.create_for_model), BYOC (build_byoc_body), ServerlessSpec, IntegratedSpec, the async creation path, and the create_index backcompat shim. On v9.0.0 these fields were dropped at the boundary depending on which path you called.
  • pc.indexes.configure(...): stop pre-merging tags client-side; the backend handles tag merges, and the client-side step was overwriting partial updates. Same job, fewer bugs.
  • pc.indexes.configure(...): relax validate_read_capacity to allow partial Dedicated patches (e.g. changing min_replicas without re-specifying max_replicas).
  • Auto-wrap bare schema dicts at the configure boundary so that schema={"fields": {...}} and the shorter schema={"my_field": ...} are both accepted.
  • Polling: raise IndexTerminatedError when an index enters Terminating or Disabled during a poll, instead of looping until the operator's timeout.
  • EmbedConfig: include dimension in the create request (was silently dropped).

Assistants

  • pc.assistants.create(...): omit metadata from the request body when not provided. v9.0.0 sent metadata: null, which a stricter backend rejected.
  • pc.assistants.list_page / list_files_page: upgrade to API version v202604, fix query-parameter names and pagination-token parsing, add page_size.
  • Upload-file: send the metadata field as multipart form data (was being sent as a query param, which silently dropped the value).
  • ChatCompletionMessage: role and content are now optional (matches the streaming assistant-role chunk shape where these arrive on a later chunk).
  • ChatCompletionStreamChunk: expose the usage field, which had been dropped during struct decoding.
  • EntailmentResult.reasoning: populate from the evaluate_alignment response (was always empty on v9.0.0).
  • OperationModel.error: map from the JSON field error_message (was empty for failed operations).
  • Honor PINECONE_PLUGIN_ASSISTANT_CONTROL_HOST / PINECONE_PLUGIN_ASSISTANT_DATA_HOST env vars at client construction (legacy plugin compatibility).
  • Add Terminated and Terminating as terminal states in _poll_until_ready, so creation polling exits promptly when an assistant transitions to a terminal failure state.

Search & query

  • Index.search / AsyncIndex.search: validate and normalize sparse/hybrid vector dict keys; wrap dense vector queries in {"values": ...} for backend serde compatibility.
  • query_namespaces: preserve input namespace order in the result so ties break deterministically.
  • upsert_records: drop the redundant id key when _id is present (the backend treats either, but sending both caused a 400).

Backups & restore

  • pc.backups.create(...): omit description from the request body when not provided.
  • pc.indexes.create_from_backup(timeout=-1): return CreateIndexFromBackupResponse directly instead of attempting to poll with a negative timeout.
  • Remove the hardcoded limit=10 default on Backups.list / RestoreJobs.list so backend-default pagination is used.

Preview

  • PreviewIndexes.create and configure: full tag validation (was incomplete on v9.0.0).
  • PreviewIndexes.configure: validate schema fields are semantic_text only.
  • PreviewIndexes.list_backups: forward limit to the server in fetch_page (was hardcoded).
  • PreviewBooleanField and PreviewLegacyIntegerField are now in the schema union; v9.0.0 rejected schemas containing them.

Admin

  • Projects.create / update: client-side name length and null-byte validation.
  • Projects.update: reject negative max_pods before the HTTP call.
  • ApiKeys.create: enforce the 80-character name length cap.
  • ApiKeys.create: remove the dead description parameter (server doesn't accept it).

Inference

  • rerank(...): validate top_n >= 1 before the HTTP call.
  • list_models(...): reject type=rerank combined with a vector_type argument.
  • ModelInfoSupportedParameter.min/max typing widened to int | float | None.

Imports / records

  • import_data(...): omit errorMode from the wire payload when error_mode is not specified (was sending null, which the backend rejected).

Backcompat shims

  • Forward schema and read_capacity through async index-creation shims so that v8-style positional calls continue to behave correctly.
  • Extend the AssistantModel.context shim to accept a messages= argument (matches the deprecated v8 signature).

Documentation

A broad pass over docstrings, RST formatting, and the v9 migration guide. Highlights:

  • v9 migration guide refined for response models and HTTP transport
  • Migration table corrected to show canonical pc.index() rather than the deprecated shim
  • All 19 async + 19 sync backcompat shim docstrings marked :meta private: so they no longer clutter generated docs
  • Pinecone.index, Pinecone.config, Pinecone.close, Pinecone.assistant, Pinecone.backups, Pinecone.collections, Pinecone.assistants: complete Args, Returns, Raises, and Examples sections where missing
  • 408 added to the retryable status codes list in error-handling docs
  • upsert_from_dataframe max_concurrency claim corrected in performance guide
  • gRPC limitations doc: corrected false claim about the grpc extra
  • Sphinx build: nitpick_ignore for _AssistantNamespaceProxy; build remains warnings-as-errors clean
  • Numerous example fixes — invalid kwargs (query=, spec_embed=, field=), unsafe .get() calls, deprecated import paths, false immutability claims

The Sphinx docs build remains green with -W (warnings-as-errors).

Internal

  • Integration tests are now parallelized with pytest-xdist (-n 6 --dist=loadfile); the release-readiness job's timeout was raised from 60 → 90 min as a margin.
  • A static abi3audit pass runs on every wheel produced by the cross-platform matrix; catches stable-ABI violations before publish (the multi-Python smoke job is the runtime complement).
  • Release-readiness: isolate abi3audit and auditwheel in their own venvs so they no longer leak into the verify Python's pip check.
  • Dev-publish smoke now drops the source pinecone/ tree before running so the installed wheel is actually exercised.
  • dev-version resolution now uses the artifacts API directly rather than walking workflow runs (avoids missing the most recent real publish when intermediate runs are no-op skips).
  • Many integration test fixtures were converted from function-scope to module-scope to share index creation across tests; the data-plane suite is significantly faster as a result.

Reporting issues

If something worked on v9.0.0 and doesn't on v9.0.1, please open an issue at https://github.com/pinecone-io/python-sdk/issues with the same details requested in the v9.0.0 notes (versions, minimal repro, expected vs actual). Compatibility regressions are prioritized.

Full Changelog: v9.0.0...v9.0.1

Assets 10
Loading