Merge release-candidate/2025-10 in prepartion for v8.0 release

⚠️ **Python 3.9 is no longer supported.** The SDK now requires Python 3.10 or later. Python 3.9 reached end-of-life on October 2, 2025. Users must upgrade to Python 3.10+ to continue using the SDK.

⚠️ **Namespace parameter default behavior changed.** The SDK no longer applies default values for the `namespace` parameter in GRPC methods. When `namespace=None`, the parameter is omitted from requests, allowing the API to handle namespace defaults appropriately. This change affects `upsert_from_dataframe` methods in GRPC clients. The API is moving toward `"__default__"` as the default namespace value, and this change ensures the SDK doesn't override API defaults.

Note: The official SDK package was renamed last year from `pinecone-client` to `pinecone` beginning in version 5.1.0.  Please remove `pinecone-client` from your project dependencies and add `pinecone` instead to get  the latest updates if upgrading from earlier versions.

You can now configure dedicated read nodes for your serverless indexes, giving you more control over query performance and capacity planning. By default, serverless indexes use OnDemand read capacity, which automatically scales based on demand. With dedicated read capacity, you can allocate specific read nodes with manual scaling control.

**Create an index with dedicated read capacity:**

```python
from pinecone import (
    Pinecone,
    ServerlessSpec,
    CloudProvider,
    AwsRegion,
    Metric
)

pc = Pinecone()

pc.create_index(
    name='my-index',
    dimension=1536,
    metric=Metric.COSINE,
    spec=ServerlessSpec(
        cloud=CloudProvider.AWS,
        region=AwsRegion.US_EAST_1,
        read_capacity={
            "mode": "Dedicated",
            "dedicated": {
                "node_type": "t1",
                "scaling": "Manual",
                "manual": {
                    "shards": 2,
                    "replicas": 2
                }
            }
        }
    )
)
```

**Configure read capacity on an existing index:**

You can switch between OnDemand and Dedicated modes, or adjust the number of shards and replicas for dedicated read capacity:

```python
from pinecone import Pinecone

pc = Pinecone()

pc.configure_index(
    name='my-index',
    read_capacity={"mode": "OnDemand"}
)

pc.configure_index(
    name='my-index',
    read_capacity={
        "mode": "Dedicated",
        "dedicated": {
            "node_type": "t1",
            "scaling": "Manual",
            "manual": {
                "shards": 3,
                "replicas": 2
            }
        }
    }
)

pc.configure_index(
    name='my-index',
    read_capacity={
        "mode": "Dedicated",
        "dedicated": {
            "node_type": "t1",
            "scaling": "Manual",
            "manual": {
                "shards": 4,
                "replicas": 3
            }
        }
    }
)
```

When you change read capacity configuration, the index will transition to the new configuration. You can use `describe_index` to check the status of the transition.

See [PR #528](#528) for details.

You can now fetch vectors using metadata filters instead of vector IDs. This is especially useful when you need to retrieve vectors based on their metadata properties.

```python
from pinecone import Pinecone

pc = Pinecone()
index = pc.Index(host="your-index-host")

response = index.fetch_by_metadata(
    filter={'genre': {'$in': ['comedy', 'drama']}, 'year': {'$eq': 2019}},
    namespace='my_namespace',
    limit=50
)
print(f"Found {len(response.vectors)} vectors")

for vec_id, vector in response.vectors.items():
    print(f"ID: {vec_id}, Metadata: {vector.metadata}")
```

**Pagination support:**

When fetching large numbers of vectors, you can use pagination tokens to retrieve results in batches:

```python
response = index.fetch_by_metadata(
    filter={'status': 'active'},
    limit=100
)

if response.pagination and response.pagination.next:
    next_response = index.fetch_by_metadata(
        filter={'status': 'active'},
        pagination_token=response.pagination.next,
        limit=100
    )
```

The update method used to require a vector id to be passed, but now you have the option to pass a metadata filter instead. This is useful for bulk metadata updates across many vectors.

There is also a dry_run option that allows you to preview the number of vectors that would be changed by the update before performing the operation.

```python
from pinecone import Pinecone

pc = Pinecone()
index = pc.Index(host="your-index-host")

response = index.update(
    set_metadata={'status': 'active'},
    filter={'genre': {'$eq': 'drama'}},
    dry_run=True
)
print(f"Would update {response.matched_records} vectors")

response = index.update(
    set_metadata={'status': 'active'},
    filter={'genre': {'$eq': 'drama'}}
)
```

A new `FilterBuilder` utility class provides a type-safe, fluent interface for constructing metadata filters. While perhaps a bit verbose, it can help prevent common errors like misspelled operator names and provides better IDE support.

When you chain `.build()` onto the `FilterBuilder` it will emit a python dictionary representing the filter. Methods that take metadata filters as arguments will continue to accept dictionaries as before.

```python
from pinecone import Pinecone, FilterBuilder

pc = Pinecone()
index = pc.Index(host="your-index-host")

filter1 = FilterBuilder().eq("genre", "drama").build()

filter2 = (FilterBuilder().eq("genre", "drama") &
           FilterBuilder().gt("year", 2020)).build()

filter3 = (FilterBuilder().eq("genre", "comedy") |
           FilterBuilder().eq("genre", "drama")).build()

filter4 = ((FilterBuilder().eq("genre", "drama") &
            FilterBuilder().gte("year", 2020)) |
           (FilterBuilder().eq("genre", "comedy") &
            FilterBuilder().lt("year", 2000))).build()

response = index.fetch_by_metadata(filter=filter2, limit=50)

index.update(
    set_metadata={'status': 'archived'},
    filter=filter3
)
```

The FilterBuilder supports all Pinecone filter operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in_`, `nin`, and `exists`. Compound expressions are build with and `&` and or `|`.

See [PR #529](#529) for `fetch_by_metadata`, [PR #544](#544) for `update()` with filter, and [PR #531](#531) for FilterBuilder.

You can now create namespaces in serverless indexes directly from the SDK:

```python
from pinecone import Pinecone

pc = Pinecone()
index = pc.Index(host="your-index-host")

namespace = index.create_namespace(name="my-namespace")
print(f"Created namespace: {namespace.name}, Vector count: {namespace.vector_count}")

namespace = index.create_namespace(
    name="my-namespace",
    schema={
        "fields": {
            "genre": {"filterable": True},
            "year": {"filterable": True}
        }
    }
)
```

**Note:** This operation is not supported for pod-based indexes.

See [PR #532](#532) for details.

For sparse indexes with integrated embedding configured to use the `pinecone-sparse-english-v0` model, you can now specify which terms must be present in search results:

```python
from pinecone import Pinecone, SearchQuery

pc = Pinecone()
index = pc.Index(host="your-index-host")

response = index.search(
    namespace="my-namespace",
    query=SearchQuery(
        inputs={"text": "Apple corporation"},
        top_k=10,
        match_terms={
            "strategy": "all",
            "terms": ["apple", "corporation"]
        }
    )
)
```

The `match_terms` parameter ensures that all specified terms must be present in the text of each search hit. Terms are normalized and tokenized before matching, and order does not matter.

See [PR #530](#530) for details.

**Update API keys, projects, and organizations:**

```python
from pinecone import Admin

admin = Admin() # Auth with PINECONE_CLIENT_ID and PINECONE_CLIENT_SECRET

api_key = admin.api_key.update(
    api_key_id='my-api-key-id',
    name='updated-api-key-name',
    roles=['ProjectEditor', 'DataPlaneEditor']
)

project = admin.project.update(
    project_id='my-project-id',
    name='updated-project-name',
    max_pods=10,
    force_encryption_with_cmek=True
)

organization = admin.organization.update(
    organization_id='my-org-id',
    name='updated-organization-name'
)
```

**Delete organizations:**

```python
from pinecone import Admin

admin = Admin()

admin.organization.delete(organization_id='my-org-id')
```

See [PR #527](#527) and [PR #543](#543) for details.

You can now configure which metadata fields are filterable when creating serverless indexes. This helps optimize performance by only indexing metadata fields that you plan to use for filtering:

```python
from pinecone import (
    Pinecone,
    ServerlessSpec,
    CloudProvider,
    AwsRegion,
    Metric
)

pc = Pinecone()

pc.create_index(
    name='my-index',
    dimension=1536,
    metric=Metric.COSINE,
    spec=ServerlessSpec(
        cloud=CloudProvider.AWS,
        region=AwsRegion.US_EAST_1,
        schema={
            "genre": {"filterable": True},
            "year": {"filterable": True},
            "rating": {"filterable": True}
        }
    )
)
```

When using schemas, only fields marked as `filterable: True` in the schema can be used in metadata filters.

See [PR #528](#528) for details.

The SDK now exposes header information from API responses. This information is available in response objects via the `_response_info` attribute and can be useful for debugging and monitoring.

```python
from pinecone import Pinecone

pc = Pinecone()
index = pc.Index(host="your-index-host")

response = index.query(
    vector=[0.1, 0.2, 0.3, ...],
    top_k=10,
    namespace='my_namespace'
)

for k, v in response._response_info.get('raw_headers').items():
    print(f"{k}: {v}")
```

See [PR #539](#539) for details.

We've replaced Python's standard library `json` module with `orjson`, a fast JSON library written in Rust. This provides significant performance improvements for both serialization and deserialization of request payloads:

- **Serialization (dumps)**: 10-23x faster depending on payload size
- **Deserialization (loads)**: 4-7x faster depending on payload size

These improvements are especially beneficial for:
- High-throughput applications making many API calls
- Applications handling large vector payloads
- Real-time applications where latency matters

No code changes are required - the API remains the same, and you'll automatically benefit from these performance improvements.

See [PR #556](#556) for details.

We've optimized gRPC response parsing by replacing `json_format.MessageToDict` with direct protobuf field access. This optimization provides approximately 2x faster response parsing for gRPC operations.

Special thanks to [@yorickvP](https://github.com/yorickvP) for surfacing the `json_format.MessageToDict` refactor opportunity. While we didn't merge the specific PR, yorick's insight led us to implement a similar optimization that significantly improves gRPC performance.

See [PR #553](#553) for details.

- **Type hints and IDE support**: Comprehensive type hints throughout the SDK improve IDE autocomplete and type checking. The SDK now uses Python 3.10+ type syntax throughout.
- **Documentation**: Updated docstrings with RST formatting and code examples for better developer experience.
- **Dependency updates**: Updated protobuf to 5.29.5 to address security vulnerabilities. Updated `pinecone-plugin-assistant` to version 3.0.1.
- **Build system**: Migrated from poetry to uv for faster dependency management.

- [@yorickvP](https://github.com/yorickvP) - Thanks for surfacing the gRPC response parsing optimization opportunity!

Author: jhamon

.durations_grpc

@@ -8,8 +8,8 @@ inputs:
 runs:
   using: 'composite'
   steps:
-    - name: Setup Poetry
-      uses: ./.github/actions/setup-poetry
+    - name: Setup uv
+      uses: ./.github/actions/setup-uv
       with:
         include_grpc: 'true'
         include_dev: 'true'
@@ -19,4 +19,4 @@ runs:
     - name: Build html documentation
       shell: bash
       run: |
-        poetry run sphinx-build -b html docs docsbuild
+        uv run sphinx-build -b html docs docsbuild

.durations_rest_asyncio

@@ -19,11 +19,11 @@ inputs:
 runs:
   using: 'composite'
   steps:
-    - name: Setup Poetry
-      uses: ./.github/actions/setup-poetry
+    - name: Setup uv
+      uses: ./.github/actions/setup-uv
     - name: Cleanup all
       shell: bash
-      run: poetry run python3 ./.github/actions/cleanup-all/cleanup-test-projects.py
+      run: uv run python3 ./.github/actions/cleanup-all/cleanup-test-projects.py
       env:
         PINECONE_API_KEY: ${{ inputs.PINECONE_API_KEY }}
         PINECONE_ADDITIONAL_HEADERS: ${{ inputs.PINECONE_ADDITIONAL_HEADERS }}

.durations_rest_sync

@@ -17,11 +17,15 @@ inputs:
   dimension:
     description: 'The dimension of the index'
     required: false
-    default: '3'
+    default: ''
   metric:
     description: 'The metric of the index'
     required: false
     default: 'cosine'
+  vector_type:
+    description: 'The type of the index'
+    required: false
+    default: 'dense'
   PINECONE_API_KEY:
     description: 'The Pinecone API key'
     required: true
@@ -36,21 +40,26 @@ outputs:
     description: 'The name of the index, including randomized suffix'
     value: ${{ steps.create-index.outputs.index_name }}
 
+  index_host:
+    description: 'The host of the index'
+    value: ${{ steps.create-index.outputs.index_host }}
+
 runs:
   using: 'composite'
   steps:
-    - name: Setup Poetry
-      uses: ./.github/actions/setup-poetry
+    - name: Setup uv
+      uses: ./.github/actions/setup-uv
 
     - name: Create index
       id: create-index
       shell: bash
-      run: poetry run python3 ./.github/actions/index-create/create.py
+      run: uv run python3 ./.github/actions/index-create/create.py
       env:
         PINECONE_API_KEY: ${{ inputs.PINECONE_API_KEY }}
         PINECONE_ADDITIONAL_HEADERS: ${{ inputs.PINECONE_ADDITIONAL_HEADERS }}
         NAME_PREFIX: ${{ inputs.name_prefix }}
         REGION: ${{ inputs.region }}
         CLOUD: ${{ inputs.cloud }}
+        VECTOR_TYPE: ${{ inputs.vector_type }}
         DIMENSION: ${{ inputs.dimension }}
         METRIC: ${{ inputs.metric }}

.github/actions/build-docs/action.yml

@@ -1,9 +1,9 @@
 import os
-import re
 import random
 import string
-from datetime import datetime
+import uuid
 from pinecone import Pinecone
+from datetime import datetime
 
 
 def read_env_var(name):
@@ -22,39 +22,9 @@ def write_gh_output(name, value):
         print(f"{name}={value}", file=fh)
 
 
-def generate_index_name(test_name: str) -> str:
-    github_actor = os.getenv("GITHUB_ACTOR", None)
-    user = os.getenv("USER", None)
-    index_owner = github_actor or user
-
-    formatted_date = datetime.now().strftime("%Y%m%d-%H%M%S%f")[:-3]
-
-    github_job = os.getenv("GITHUB_JOB", None)
-
-    if test_name.startswith("test_"):
-        test_name = test_name[5:]
-
-    # Remove trailing underscore, if any
-    if test_name.endswith("_"):
-        test_name = test_name[:-1]
-
-    name_parts = [index_owner, formatted_date, github_job, test_name]
-    index_name = "-".join([x for x in name_parts if x is not None])
-
-    # Remove invalid characters
-    replace_with_hyphen = re.compile(r"[\[\(_,\s]")
-    index_name = re.sub(replace_with_hyphen, "-", index_name)
-    replace_with_empty = re.compile(r"[\]\)\.]")
-    index_name = re.sub(replace_with_empty, "", index_name)
-
-    max_length = 45
-    index_name = index_name[:max_length]
-
-    # Trim final character if it is not alphanumeric
-    if index_name.endswith("_") or index_name.endswith("-"):
-        index_name = index_name[:-1]
-
-    return index_name.lower()
+def generate_index_name(name_prefix: str) -> str:
+    name = name_prefix.lower() + "-" + str(uuid.uuid4())
+    return name[:45]
 
 
 def get_tags():
@@ -74,15 +44,35 @@ def get_tags():
 
 def main():
     pc = Pinecone(api_key=read_env_var("PINECONE_API_KEY"))
-    index_name = generate_index_name(read_env_var("NAME_PREFIX") + random_string(20))
+    index_name = generate_index_name(read_env_var("NAME_PREFIX"))
+    dimension_var = read_env_var("DIMENSION")
+    if dimension_var is not None and dimension_var != "":
+        dimension = int(dimension_var)
+    else:
+        dimension = None
+
+    vector_type_var = read_env_var("VECTOR_TYPE")
+    if vector_type_var is not None and vector_type_var != "":
+        vector_type = vector_type_var
+    else:
+        vector_type = None
+
+    metric = read_env_var("METRIC")
+    cloud = read_env_var("CLOUD")
+    region = read_env_var("REGION")
+    tags = get_tags()
+
     pc.create_index(
         name=index_name,
-        metric=read_env_var("METRIC"),
-        dimension=int(read_env_var("DIMENSION")),
-        spec={"serverless": {"cloud": read_env_var("CLOUD"), "region": read_env_var("REGION")}},
-        tags=get_tags(),
+        metric=metric,
+        dimension=dimension,
+        vector_type=vector_type,
+        tags=tags,
+        spec={"serverless": {"cloud": cloud, "region": region}},
     )
+    description = pc.describe_index(name=index_name)
     write_gh_output("index_name", index_name)
+    write_gh_output("index_host", description.host)
 
 
 if __name__ == "__main__":

.github/actions/cleanup-all/action.yml

@@ -17,12 +17,12 @@ inputs:
 runs:
   using: 'composite'
   steps:
-    - name: Setup Poetry
-      uses: ./.github/actions/setup-poetry
+    - name: Setup uv
+      uses: ./.github/actions/setup-uv
 
     - name: Delete index
       shell: bash
-      run: poetry run python3 ./.github/actions/index-delete/delete.py
+      run: uv run python3 ./.github/actions/index-delete/delete.py
       env:
         PINECONE_API_KEY: ${{ inputs.PINECONE_API_KEY }}
         PINECONE_ADDITIONAL_HEADERS: ${{ inputs.PINECONE_ADDITIONAL_HEADERS }}

.github/actions/index-create/action.yml

@@ -40,7 +40,7 @@ runs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        python-version: '3.10'
 
     - name: Install deps
       shell: bash
@@ -50,7 +50,7 @@ runs:
     - name: Create project
       id: create-project
       shell: bash
-      run: poetry run python3 ./.github/actions/project-create/script.py
+      run: uv run python3 ./.github/actions/project-create/script.py
       env:
         API_VERSION: ${{ inputs.api_version }}
         PINECONE_SERVICE_ACCOUNT_CLIENT_ID: ${{ inputs.PINECONE_SERVICE_ACCOUNT_CLIENT_ID }}

.github/actions/index-create/create.py

@@ -28,7 +28,7 @@ runs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        python-version: '3.10'
 
     - name: Install deps
       shell: bash
@@ -45,7 +45,7 @@ runs:
     - name: Delete project
       id: delete-project
       shell: bash
-      run: poetry run python3 ./.github/actions/project-delete/delete-project.py
+      run: uv run python3 ./.github/actions/project-delete/delete-project.py
       env:
         API_VERSION: ${{ inputs.api_version }}
         PINECONE_SERVICE_ACCOUNT_CLIENT_ID: ${{ inputs.PINECONE_SERVICE_ACCOUNT_CLIENT_ID }}