Author: @Jen Hamon

Changes overview

• Deploy Pinecone’s new serverless indexes. The create_index method has been refactored to accept a PodSpec or ServerlessSpec depending on how you would like to deploy your index. Many old properties such as pod_type, replicas, etc are moved into PodSpec since they do not apply to serverless indexes. Serverless indexes are currently in public preview, so make sure to review the current limitations and test thoroughly before using in production.
• Understand cost. The quantity of read units consumed by each serverless query and fetch call are now returned with the response.
• Flexible API Keys. The v3.0.0 Python SDK is consuming the new Control Plane API hosted at https://api.pinecone.io. This new API allows for a lot more flexibility in how API keys are used in comparison to the past when a rigid 1:1 relationship was enforced between projects and environments.
• State encapsulation with classes. We’ve refactored away from global state variables set with pinecone.init into new Pinecone class instances that encapsulate their configuration state. This change enables users to interact with Pinecone using multiple API keys if they wish.
• Streamlined dependencies, smoother installs.
  • Removed many dependencies: numpy, pyyaml, loguru, requests, dnspython
  • Expanded the urllib3 support back to 1.26.x
  • Everything GRPC-related is now moved into a subpackage, pinecone.grpc, so that GRPC code is only imported when needed. For applications using REST, this will mean quicker startup and fewer dependency clashes with other packages.
• Richer responses. The list_indexes and list_collections methods now return an array with full descriptions of each resource, not merely an array of names.
• Migration to the Apache 2 open source license. We’ve moved from a proprietary EULA to a more welcoming Apache 2 license to make it easier than ever for people to incorporate the Pinecone Python SDK into their projects.
• Bug fixes:
  • Removed code that was erroneously parsing some metadata into DateTime objects.
  • Refactored urllib3 usage to stop spamming deprecation warning messages.
  • Suppressed a tqdm warning that was appearing during notebook runs.
• Tidying up / Breaking changes
  • list_indexes now returns additional data, and to continue iterating over an array of names you need to chain a call to a new helper method .names(). See here.
  • list_collections has changed very similar to list_indexes. Use .names(). See here.
  • describe_index takes the same arguments as before (the index name), but returns data in a different shape reflecting the move of some configurations under the spec key and elevation of host to the top level. See a table of changed properties here.
  • The order of positional arguments to the query method has been updated to reflect that top_k is a required parameter. If you previously relied on passing your query vector as the first positional argument, you’ll see a strange error from the API about duplicate top_k values being passed. We recommend adopting keyword arguments to fix and be resilient to any future changes, e.g. index.query(vector=vec, top_k=10)
  • query() no longer accepts multiple queries via the queries keyword argument.
  • scale_index() removed in favor of configure_index()
• Debugging tools. See what data is coming and going with a new environment variable, PINECONE_DEBUG_CURL='true'

Importing and Initialization

Some challenges with initialization in pinecone-client ≤2.2.4

In the old client, you had to call the init method to setup some configuration state as global variables before invoking any data plane or control plane methods. There were a few problems with this:

• Reliance on global state. This init pattern had a side effect of setting configuration into global variables, which limited flexibility to work with multiple API keys at once.
• Tied to a specific cloud environment from the moment of initialization. Prior to the implementation of the Pinecone Global Control Plane, each API Key and all the resources managed with that key were tied to a single environment. This meant a lot of friction for people interested in working with indexes in multiple environments.
• Latency overhead of calling /actions/whoami to fetch the projectId every time. This init call also fired off a network request to validate the API key and retrieve the associated projectId that was needed in order to construct data urls using a templated format; this step added significant latency every time someone wanted to interact with Pinecone.

# Legacy initialization
import pinecone

pinecone.init(
	api_key='XXX', 
	environment='us-east1-gcp'
)