Release v5.4.2

This release contains a small adjustment to the query_namespaces method added in the 5.4.0. The initial implementation had a bug that meant it could not properly merge small result sets across multiple namespaces. This release adds a required keyword argument, metric to the query_namespaces method, which should enable the SDK to merge results no matter how many results are returned.

from pinecone import Pinecone

pc = Pinecone(api_key='YOUR_API_KEY')
index = pc.Index(host='your-index-host')

query_results = index.query_namespaces(
    vector=[0.1, 0.2, ...],  # The query vector, dimension should match your index
    namespaces=['ns1', 'ns2', 'ns3'],
    metric="cosine", # This is the new required keyword argument
    include_values=False,
    include_metadata=True,
    filter={},
    top_k=100,
)

What's Changed

• [Bug] query_namespaces can handle single result by @jhamon in #421

Full Changelog: v5.4.1...v5.4.2

Release v5.4.1

What's Changed

• [Chore] Allow support for pinecone-plugin-inference >=2.0.0, <4.0.0 by @austin-denoble in #419

Release v5.4.0

Query namespaces

In this release we have added a utility method to run a query across multiple namespaces, then merge the result sets into a single ranked result set with the top_k most relevant results. The query_namespaces method accepts most of the same arguments as query with the addition of a required namespaces param.

Since query_namespaces executes multiple queries in parallel, in order to get good performance it is important to set values for the pool_threads and connection_pool_maxsize properties on the index client. The pool_threads setting is the number of threads available to execute requests while connection_pool_maxsize is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus.

The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace.

from pinecone import Pinecone

pc = Pinecone(api_key="key")
index = pc.Index(
  name="index-name",
  pool_threads=50,             # <-- make sure to set these
  connection_pool_maxsize=50,  # <-- make sure to set these
)

query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
combined_results = index.query_namespaces(
    vector=query_vec,
    namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
    top_k=10,
    include_values=False,
    include_metadata=True,
    filter={"genre": { "$eq": "comedy" }},
    show_progress=False,
)

for scored_vec in combined_results.matches:
    print(scored_vec)
print(combined_results.usage)

A version of query_namespaces is also available over grpc. For grpc, there is no need to set the connection_pool_maxsize because grpc makes efficient use of open connections by default.

from pinecone.grpc import PineconeGRPC

pc = PineconeGRPC(api_key="key")
index = pc.Index(
  name="index-name",
  pool_threads=50, # <-- make sure to set this
)

query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index
combined_results = index.query_namespaces(
    vector=query_vec,
    namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
    top_k=10,
    include_values=False,
    include_metadata=True,
    filter={"genre": { "$eq": "comedy" }},
    show_progress=False,
)

for scored_vec in combined_results.matches:
    print(scored_vec)
print(combined_results.usage)

Changelog

Additions

• [feat] PineconeGrpcFuture implements concurrent.futures.Future by @jhamon in #410
• Update to pinecone-plugin-inference=2.0.0 by @ssmith-pc in #397
• Detect plugins for Index and IndexGRPC classes by @jhamon in #402
• Add query_namespaces by @jhamon in #409
• Expose connection_pool_maxsize on Index and add docstrings by @jhamon in #415
• Implement query_namespaces over grpc by @jhamon in #416
• query_namespaces performance improvements by @jhamon in #417

Chores / Fixes

• [Refactor] Extract GrpcChannelFactory from GRPCIndexBase by @jhamon in #394
• [Refactor] Extract GrpcRunner from GRPCIndexBase class by @jhamon in #395
• [Chore] Replace black with ruff linter / formatter by @jhamon in #392
• [Fix] Update build-oas script for building exceptions template changes by @ssmith-pc in #396
• [Chore] Put date into test index and collection names by @jhamon in #399
• [Chore] Automatically cleanup old resources each night by @jhamon in #400
• [Chore] Improve test flakes by @jhamon in #404

Full Changelog: v5.3.1...v5.4.0.dev5

Release v5.3.1

What's Changed

• [Fix] Add missing python-dateutil dependency by @jhamon in #391

Release v5.3.0

Public Preview: Imports

To learn more about working with imports and details about expected data formats, please see these documentation guides:

• Understanding Imports
• Import Data
• Manage Storage Integrations

This release adds methods for interacting with several new endpoints in Public Preview from the Python SDK. Before you can use these, you will need to follow the above docs to prepare your data and configure any storage integrations.

import os
import random
from pinecone import Pinecone, ServerlessSpec, ImportErrorMode

# 0. Instantiate your client instance
pc = Pinecone(api_key=os.environ['PINECONE_API_KEY'])

# 1. You must have an index whose dimension matches the size of your data
#    You may already have such an index, but for this demo we will create one.
index_name = f"import-{random.randint(0, 10000)}"

if not pc.has_index(index_name):
  pc.create_index(
      name=index_name,
      dimension=10,
      metric="cosine",
      spec=ServerlessSpec(cloud="aws", region="eu-west-1")
  )

# 2. Get a reference to the index client
index = pc.Index(name=index_name)

# 3. Start the import operation, passing a uri that describes the path to your
#    AWS S3 bucket. Each subfolder within this path will correspond to a namespace
#    where imported data will be stored.
root = 's3://dev-bulk-import-datasets-pub/10-records-dim-10/'
op = index.start_import(
    uri=root,
    error_mode=ImportErrorMode.CONTINUE, # or ABORT
    # integration_id='' # Add this if you want to use a storage integration
  )

# 4. Check the operation status
index.describe_import(id=op.id)

# 5. Cancel an import operation
index.cancel_import(id=op.id)

# 6. List all recent operations using a generator that handles pagination on your behalf
for i in index.list_imports():
  print(f"id: {i.id} status: {i.status}")

# ...or turn the generator into a simple list, fetching all results at once
operations = list(index.list_imports())
print(operations)

Release v5.2.0

Public Preview: Rerank

This release adds a method for interacting with our Rerank endpoint, now in Public Preview. Rerank is used to order results by relevance to a query.

Currently rerank supports the bge-reranker-v2-m3 model. See the rerank guide for more information on using this feature.

from pinecone import Pinecone

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

query = "Tell me about Apple's products"

results = pc.inference.rerank(
    model="bge-reranker-v2-m3",
    query=query,
    documents=[
      "Apple is a popular fruit known for its sweetness and crisp texture.",
      "Apple is known for its innovative products like the iPhone.",
      "Many people enjoy eating apples as a healthy snack.",
      "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.",
      "An apple a day keeps the doctor away, as the saying goes.",
    ],
    top_n=3,
    return_documents=True,
)

print(query)
for r in results.data:
  print(r.score, r.document.text)

Gives output along these lines

Tell me about Apple's products
0.8401279 Apple is known for its innovative products like the iPhone.
0.23318209 Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.
0.17384852 Apple is a popular fruit known for its sweetness and crisp texture.

Release v5.1.0

Package renamed from pinecone-client to pinecone

In this release, we have renamed the package from pinecone-client to pinecone. From now on you should install it using the pinecone name.

There is a plan to continue publishing code under the pinecone-client package as well so that anyone using the old name will still find out about available upgrades via their dependency management tool of choice, but we haven't automated that as part of our release process yet so there will be a slight delay in new work being released under that name.

New has_index() helper and improved output

We've added a small helper function to simplify a common need in notebooks and examples, which is checking if an index exists.

from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key='YOUR_API_KEY')

index_name = "movie-recommendations"

if not pc.has_index(index_name):
    pc.create_index(
        name=index_name,
        dimension=384,
        metric="cosine",
        spec=ServerlessSpec(cloud="aws", region="us-west-2")
    )

index = pc.Index(name=index_name)

# Now upsert vectors, run queries, etc

If you are frequently working in notebooks, you will also benefit from a nicer presentation of control plane responses.

>>> pc.describe_index(name="test-embed2")
{
    "name": "test-embed2",
    "dimension": 10,
    "metric": "cosine",
    "host": "test-embed2-dojoi3u.svc.apw5-4e34-81fa.pinecone.io",
    "spec": {
        "serverless": {
            "cloud": "aws",
            "region": "us-west-2"
        }
    },
    "status": {
        "ready": true,
        "state": "Ready"
    },
    "deletion_protection": "disabled"
}

What's Changed

• [Docs] Fix dataframe column name in doc strings by @jseldess in #381
• [Docs] Change "client" to "SDK" in README by @jseldess in #382
• [Chore] Adding new issue templates by @anawishnoff in #380
• [Chore] Reduce dimension in testing to simplify output by @jhamon in #384
• [Chore] Rename package from pinecone-client to pinecone by @jhamon in #383
• [Feature] Add has_index() by @rohanshah18 in #385
• [Feature] Improve output from list/describe actions on indexes and collections by @jhamon in #387

New Contributors

• @jseldess made their first contribution in #381
• @anawishnoff made their first contribution in #380
• @rohanshah18 made their first contribution in #385

Full Changelog: v5.0.1...v5.1.0

Release v5.0.1

What's Changed

• [CI] Publish doc updates after each release by @jhamon in #373
• [Fix] Fetch when vector id string contains spaces by @jhamon in #372
• [Fix] Adjusting inference plugin dependency to resolve circular dependency by @jhamon @ssmith-pc in #379 #377

Full Changelog: v5.0.0...v5.0.1

Release v5.0.0

Features

API versioning

This updated release of the Pinecone Python SDK depends on API version 2024-07. This v5 SDK release line should continue to receive fixes as long as the 2024-07 API version is in support.

Inference API

Try out Pinecone's new Inference API, currently in public preview.

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")
model = "multilingual-e5-large"

# Embed documents
text = [
    "Turkey is a classic meat to eat at American Thanksgiving.",
    "Many people enjoy the beautiful mosques in Turkey.",
]
text_embeddings = pc.inference.embed(
    model=model,
    inputs=text,
    parameters={"input_type": "passage", "truncate": "END"},
)

If you were previously using the pinecone-plugin-inference plugin package to gain access to this feature with the v4 SDK, you no longer need to install the plugin as it is being included by default.

Deletion Protection

Use deletion protection to prevent your most important indexes from accidentally being deleted. This feature is available for both serverless and pod indexes.

To enable this feature for existing indexes, use configure_index

from pinecone import Pinecone

pc = Pinecone(api_key='YOUR_API_KEY')

# Enable deletion protection
pc.configure_index(name='example-index', deletion_protection='enabled')

When deletion protection is enabled, calls to delete_index will fail until you first disable the deletion protection.

# To disable deletion protection
pc.configure_index(name='example-index', deletion_protection='disabled')

If you want to enable this feature at the time of index creation, create_index now accepts an optional keyword argument. The feature is disabled by default.

from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key='YOUR_API_KEY')
pc.create_index(
  name='example-index',
  dimension=1024,
  metric='cosine',
  deletion_protection='enabled',
  spec=ServerlessSpec(cloud='aws', region='us-west-2')
)

Fixes

• This release resolves a problem that occurred when listing or describing a collection having dimension > 2000. Closes issue #366. Thank you to @drivard for reporting this issue.
• Several dependencies (certifi, urllib3, pdoc) received minor bumps to resolve security notices. #365

Breaking changes

As part of an overall move to stop exposing generated code in the package's public interface, an obscure configuration property (openapi_config) was removed in favor of individual configuration options such as proxy_url, proxy_headers, and ssl_ca_certs. All of these properties were available in v3 and v4 releases of the SDK, with deprecation notices shown to affected users.

Full Changelog: v4.1.2...v5.0.0

Release v4.1.2

Fixes

• do not override port if defined in host by @haruska in #362

Chores

• Add Black Formatting and Linting by @gdj0nes in #355
• Bump braces from 3.0.2 to 3.0.3 in /.github/actions/bump-version by @dependabot in #358
• Drop broken README badge by @gdj0nes in #359
• Bump version for 4.1.1 release by @jhamon in #363

New Contributors

• @haruska made their first contribution in #362

Full Changelog: v4.1.1...v4.1.2