This guide shows you how to set up a Pinecone vector database in minutes.

Before you begin

If you haven’t already, sign up for a free Pinecone account.

On the free Starter plan, you get 1 project, 5 serverless indexes in the us-east-1 region of AWS, and up to 2 GB of storage. Although the Starter plan has stricter limits than other plans, you can upgrade whenever you’re ready.

1. Install a Pinecone client

Pinecone exposes a simple REST API for interacting with its vector database. You can use the API directly, or you can use one of the official Python , Node.js, or Java clients:

pip install pinecone-client

2. Get your API key

You need an API key to make API calls to your Pinecone project. To get your key, follow these steps:

  1. Open the Pinecone console.
  2. Select your project.
  3. Go to API Keys.
  4. Copy your API key.

3. Initialize your client connection

Using your API key, initialize your client connection to Pinecone:

from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key='YOUR_API_KEY')
When using the API directly, each HTTP request must contain an Api-Key header that specifies your API key. You’ll see this in all subsequent curl examples.

4. Create a serverless index

In Pinecone, you store vector embeddings in indexes. The vectors in any index you create must share the same dimensionality and distance metric for measuring similarity.

Use the following code to create a serverless index named “docs-quickstart-index” that performs nearest-neighbor search using the Cosine distance similarity metric for vectors of 8 dimensions:

index_name = "docs-quickstart-index"

pc.create_index(
    name=index_name,
    dimension=8,
    metric="cosine",
    spec=ServerlessSpec(
        cloud='aws', 
        region='us-east-1'
    ) 
) 

5. Upsert vectors

Now that you’ve created your index, upsert sample vectors into 2 distinct namespaces.

Namespaces let you partition vectors within a single index. Although optional, they are a best practice for speeding up queries, which can be filtered by namespace, and for complying with multi-tenancy requirements.

Target the “docs-quickstart-index” index and use the upsert operation to write eight 8-dimensional vectors into 2 distinct namespaces:

index = pc.Index(index_name)

index.upsert(
    vectors=[
        {"id": "vec1", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]},
        {"id": "vec2", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]},
        {"id": "vec3", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
        {"id": "vec4", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]}
    ],
    namespace="ns1"
)

index.upsert(
    vectors=[
        {"id": "vec5", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]},
        {"id": "vec6", "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]},
        {"id": "vec7", "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]},
        {"id": "vec8", "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]}
    ],
    namespace="ns2"
)
When upserting larger amounts of data, upsert data in batches of 100-500 vectors over multiple upsert requests.

6. Check the index

Pinecone is eventually consistent, so there can be a delay before your upserted vectors are available to query. Use the describe_index_stats operation to check if the current vector count matches the number of vectors you upserted:

index.describe_index_stats()

# Returns:
# {'dimension': 8,
#  'index_fullness': 0.0,
#  'namespaces': {'ns1': {'vector_count': 4}, 'ns2': {'vector_count': 4}},
#  'total_vector_count': 8}

Query each namespace in your index for the 3 vectors that are most similar to an example 8-dimensional vector using the Cosine distance metric you specified for the index:

index.query(
    namespace="ns1",
    vector=[0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
    top_k=3,
    include_values=True
)

index.query(
    namespace="ns2",
    vector=[0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7],
    top_k=3,
    include_values=True
)

# Returns:
# {'matches': [{'id': 'vec3',
#               'score': 0.0,
#               'values': [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
#              {'id': 'vec4',
#               'score': 0.0799999237,
#               'values': [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]},
#              {'id': 'vec2',
#               'score': 0.0800000429,
#               'values': [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]}],
#  'namespace': 'ns1',
#  'usage': {'read_units': 6}}
# {'matches': [{'id': 'vec7',
#               'score': 0.0,
#               'values': [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]},
#              {'id': 'vec8',
#               'score': 0.0799999237,
#               'values': [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]},
#              {'id': 'vec6',
#               'score': 0.0799999237,
#               'values': [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]}],
#  'namespace': 'ns2',
#  'usage': {'read_units': 6}}

This is a simple example. As you put more demands on Pinecone, you’ll see it returning low-latency, accurate results at huge scales, with indexes of up to billions of vectors.

8. Clean up

When you no longer need the “docs-quickstart-index” index, use the delete_index operation to delete it:

pc.delete_index(indexName)
After you delete an index, you cannot use it again or recover it.

Next steps

Now that you have a serverless index and experience with basic Pinecone operations, check out our notebooks anbd sample applications using common AI patterns, tools, and algorithms, or start upserting your own vector embeddings.

Was this page helpful?