How to beginner · 3 min read

How to upsert vectors to Pinecone

Quick answer

Use the Pinecone Python SDK v3 to upsert vectors by creating a Pinecone client, accessing an index with pc.Index, and calling index.upsert with a list of vectors. Each vector must include an ID and a vector embedding array.

PREREQUISITES

Python 3.8+
Pinecone API key
pip install pinecone-client>=3.0.0

Setup

Install the Pinecone Python SDK and set your API key as an environment variable before running the code.

Install SDK: pip install pinecone-client>=3.0.0
Set environment variable: export PINECONE_API_KEY='your_api_key' (Linux/macOS) or setx PINECONE_API_KEY "your_api_key" (Windows)

bash

pip install pinecone-client>=3.0.0

Step by step

This example demonstrates how to initialize the Pinecone client, connect to an existing index, and upsert vectors with IDs and embeddings.

python

import os
import pinecone

# Initialize Pinecone client
# Use: pc = Pinecone(api_key=os.environ['PINECONE_API_KEY'])os.environ["PINECONE_API_KEY"])

# Connect to your Pinecone index
index = pinecone.Index("example-index")

# Prepare vectors to upsert: list of tuples (id, vector, optional metadata)
vectors_to_upsert = [
    ("vec1", [0.1, 0.2, 0.3, 0.4]),
    ("vec2", [0.5, 0.6, 0.7, 0.8]),
    ("vec3", [0.9, 1.0, 1.1, 1.2])
]

# Upsert vectors
response = index.upsert(vectors=vectors_to_upsert)

print("Upsert response:", response)

output

Upsert response: {'upserted_count': 3}

Common variations

You can upsert vectors with metadata by adding a dictionary as the third element in each tuple. Also, you can use async upsert with asyncio and the Pinecone async client.

python

import os
import asyncio
import pinecone

async def async_upsert():
    # Use: pc = Pinecone(api_key=os.environ['PINECONE_API_KEY'])os.environ["PINECONE_API_KEY"])
    index = pinecone.Index("example-index")

    vectors_with_metadata = [
        ("vec1", [0.1, 0.2, 0.3, 0.4], {"category": "A"}),
        ("vec2", [0.5, 0.6, 0.7, 0.8], {"category": "B"})
    ]

    response = await index.upsert(vectors=vectors_with_metadata)
    print("Async upsert response:", response)

asyncio.run(async_upsert())

output

Async upsert response: {'upserted_count': 2}

Troubleshooting

Index not found: Ensure the index name is correct and the index exists in your Pinecone project.
API key errors: Verify your PINECONE_API_KEY environment variable is set correctly.
Vector dimension mismatch: Confirm the vector length matches the index dimension.

✅

Key Takeaways

Use the Pinecone Python SDK v3 and environment variable for API key management.
Upsert vectors as a list of tuples with ID and vector embedding, optionally with metadata.
Async upsert is supported for scalable vector insertion.
Always verify index existence and vector dimension compatibility before upserting.

Verified 2026-04

Verify ↗