Pinecone Python SDK v10: schema-declared indexes and three data-plane interfaces
Official Python SDK for the Pinecone vector database
At a glance
- What is it?
- The official Python client for Pinecone's vector database, now on its v10 line, where index creation is driven by a schema and deployment block. The interesting part is not the HTTP calls, it is that the SDK exposes three different read and write surfaces depending on how the index was created.
- Who is it for?
- Adopt it if you are already on Pinecone and your code creates indexes programmatically, because the v10 schema and deployment arguments are not a drop-in rename of the old spec and dimension arguments. Do not adopt it if you want a self-hosted or embeddable vector store; this client only talks to Pinecone's service.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 11 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What the SDK actually covers, and who is on the hook for the rest
This is a client library, not a database. It creates and manages indexes, upserts and queries records, and runs inference operations, all against Pinecone's hosted service. That scope matters because it decides who this package is for: teams that have already chosen Pinecone and need Python code to talk to it. If you are still comparing vector stores, this SDK tells you almost nothing about the trade-offs, because none of the storage, indexing or recall behaviour lives in the package. The README states that Python 3.10 or newer is required, which is a real constraint if you are pinned to an older interpreter for other reasons. The licence is Apache-2.0, so the client code itself is permissive, but the service it connects to is a separate commercial relationship and the licence says nothing about that.
A schema decides which of three interfaces your index answers on
The design choice that shapes everything else is that the index creation call determines the API surface you use later. The README describes three cases. An index created with a declared schema becomes a document index, read and written through index.documents, where each record is a JSON document with an _id plus fields you named. An index created with the deprecated top-level vector arguments answers on index.upsert and index.query. An index created with pc.indexes.create_for_model(...) embeds text server-side and answers on index.upsert_records and index.search. These are not interchangeable wrappers over one endpoint. The SDK does not normalise them, so the same client object can present a documents handle on one index and a query method on another, and picking the wrong one is a runtime error rather than a type error. That is a defensible design if you accept that the index is the unit of configuration, but it means the SDK's surface area is effectively three SDKs sharing a constructor.
The v10 break: schema and deployment replace spec and dimension
Version 10.0.0 is a breaking release, and the README is explicit that create and configure moved from spec= and dimension= to schema= and deployment=. The migration guide is linked as the field-by-field mapping, and that link is the thing to read before touching an existing codebase, because the README does not reproduce the mapping itself. In the new form, schema carries a fields mapping, and each field declares a type such as dense_vector along with its dimension and metric. Deployment declares deployment_type, cloud and region. The README also notes that pc.indexes.create blocks until the index is ready, which is convenient in scripts and less convenient in a request handler. If your provisioning code is generated, templated or spread across services, the rename is mechanical but the blast radius is not: every caller that constructs an index has to change in the same release window.
Upsert is asynchronous, and the README says so plainly
One sentence in the quickstart carries more operational weight than the rest of the example: upserts apply asynchronously, so a document may not be visible to the next search immediately. The sample then prints results from index.documents.search without any wait, which is fine for a documentation snippet and misleading as a pattern. Read-modify-write loops, deduplication checks and tests that upsert then assert on a query all inherit this behaviour. The SDK does not appear to offer a documented consistency flag in the material provided, so the practical options are to poll, to tolerate eventual visibility in the application, or to keep the write and the read on separate paths. Anyone evaluating this client for a pipeline that assumes write-then-read consistency should treat that line as the headline, not a footnote.
Getting it running: install, key, host, timeout, debug
Installation is a single command, pip install pinecone. The client takes an API key directly or reads PINECONE_API_KEY from the environment; Pinecone() with no arguments is the documented environment-variable path. A custom control plane host is set with host="https://api.pinecone.io", and request timeouts are set in seconds with timeout=30. Debug logging is switched on with the environment variable PINECONE_DEBUG, exported as PINECONE_DEBUG=1. The async client is a separate class, AsyncPinecone, used as an async context manager, where index() is a coroutine and the returned handle is itself a context manager, so the documented shape is async with AsyncPinecone(...) as pc, then index = await pc.index(name), then async with index. Note that the async example passes the same score_by list of DenseVectorQuery objects as the sync one, so query construction is shared between the two clients even though connection handling is not.
Where the documentation stops short
The README is a quickstart, not a reference, and several things a reader would want are simply not in it. The v10 field mapping lives behind a link rather than in the repository's front page. There is no stated behaviour for what happens when a document contains a key that is neither _id, a declared schema field, nor metadata, even though the quickstart mentions that every other key is either a declared field or arbitrary metadata. There is no guidance on pagination, on how large a batch upsert can be, or on what results.matches contains beyond id and score. The repository's own development notes hint at the scale of the unstated parts: the unit suite is expected to leave the working tree clean, and the live retry and throttle smoke tests in tests/integration/test_retry_smoke.py require PINECONE_API_KEY plus PINECONE_RETRY_SMOKE=1 and cost money to run. The README says those tests should be run before any release touching retry logic, HTTP transport, the AIMD adaptive-concurrency limiter, or the batch-upsert path. That list is the closest thing to a map of the SDK's genuinely complicated internals, and none of it is documented for users.
The alternative: talking to the Pinecone API without this package
The obvious alternative is calling the Pinecone HTTP API directly with httpx or requests, and the difference is not merely ergonomic. A hand-rolled client has to implement retry behaviour, throttling and the adaptive-concurrency limiter that this SDK already ships and tests, which the development notes identify as areas sensitive enough to warrant paid smoke tests before release. It also has to track the schema and deployment payload shapes through the v10 change itself. The trade is control versus maintenance: direct HTTP gives you a smaller dependency and lets you shape requests exactly, while the SDK gives you the retry and concurrency machinery plus typed query objects like DenseVectorQuery at the cost of following its release cadence. Given that v10 is a breaking release with a migration guide, that cadence is the real cost of the SDK path, and it is the reason a thin internal wrapper over raw HTTP is a reasonable choice for teams that only ever call one or two endpoints.
Maintenance cost and what to check before you commit
The release history in the material shows a major version bump to 10.0.0 in September 2026, a 9.1.0 minor in June 2026 and a 9.0.1 patch in May 2026. That is a steady cadence with at least one breaking change in the recent past, so budget for reading migration guides rather than assuming minor upgrades are free. The Apache-2.0 licence covers the client code and imposes the usual notice and attribution conditions on redistribution; it does not grant anything with respect to the hosted service, and nothing here is legal advice. Before adopting, confirm three things against the migration guide and the quickstart rather than this article: the exact schema and deployment field names for the index types you use, which of the three data-plane interfaces your existing indexes answer on, and whether your read paths can tolerate the asynchronous upsert visibility described in the README. If any of those three is unclear for your workload, the SDK is not the blocker; the index configuration is.
Editorial conclusion
Adopt it if you are already on Pinecone and your code creates indexes programmatically, because the v10 schema and deployment arguments are not a drop-in rename of the old spec and dimension arguments. Do not adopt it if you want a self-hosted or embeddable vector store; this client only talks to Pinecone's service. Before writing code, verify the v10 field-by-field mapping in the migration guide and confirm which of the three data-plane interfaces your existing indexes answer on, since that choice is made at index creation time and not at query time.
Community notes