Quickstart

This guide explains 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 one project and one index with enough resources for testing Pinecone and for running small applications. Although the Starter plan does not support all Pinecone features, it's easy to upgrade when you're ready.
If you'd prefer to get started in your browser, use the "Hello, Pinecone!" colab notebook.

1. Install a Pinecone client

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

pip install pinecone-client

npm install @pinecone-database/pinecone

Currently, Pinecone supports a Python client and a Node.js client. For community-supported clients and other client resources, see Libraries.

2. Get your API key

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

Open the Pinecone Console.
Go to API Keys.
Copy your API key and environment.

3. Initialize your connection

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

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

import { Pinecone } from '@pinecone-database/pinecone';

const pinecone = new Pinecone({ 
    apiKey: 'YOUR_API_KEY',
    environment: 'YOUR_ENVIRONMENT'
})

ℹ️
Note
When using the API directly, each HTTP request must contain an Api-Key header that specifies your API key, and your environment must be specified in the URL. You'll see this in all subsequent curl examples.

4. Create an index

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

Create an index named "quickstart" that performs nearest-neighbor search using the Euclidean distance metric for 8-dimensional vectors:

pinecone.create_index("quickstart", dimension=8, metric="euclidean")
pinecone.describe_index("quickstart")

await pinecone.createIndex({
    name: "quickstart",
    dimension: 8,
    metric: "euclidean",
});
await pinecone.describeIndex("quickstart");

PINECONE_API_KEY="YOUR_API_KEY"
PINECONE_ENVIRONMENT="YOUR_ENVIRONMENT"

# Create the index
curl -X POST "https://controller.$PINECONE_ENVIRONMENT.pinecone.io/databases" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart",
    "dimension": 8,
    "metric": "euclidean"
  }'

# Check index status
curl "https://controller.$PINECONE_ENVIRONMENT.pinecone.io/databases/quickstart" \
  -H "Api-Key: $PINECONE_API_KEY"

5. Insert vectors

Now that you've created your index, insert some sample vectors.

Create a client instance that targets the "quickstart" index:

index = pinecone.Index("quickstart")

const index = pinecone.index("quickstart");

# Not applicable

Use the upsert operation to write 5 8-dimensional vectors into the index:

index.upsert(
  vectors=[
    {"id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]},
    {"id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]},
    {"id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
    {"id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]},
    {"id": "E", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]}
  ]
)

await index.upsert([
  {
    "id": "A",
    "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]
  },
  {
    "id": "B",
    "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
  },
  {
    "id": "C",
    "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
  },
  {
    "id": "D",
    "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
  },
  {
    "id": "E",
    "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]
  }
]);

PINECONE_API_KEY="YOUR_API_KEY"
PINECONE_ENVIRONMENT="YOUR_ENVIRONMENT"

PINECONE_PROJECT_ID=$(
  curl "https://controller.$PINECONE_ENVIRONMENT.pinecone.io/actions/whoami" \
    -H "Api-Key: $PINECONE_API_KEY" | jq -r '.project_name'
)

curl -X POST "https://quickstart-$PINECONE_PROJECT_ID.svc.$PINECONE_ENVIRONMENT.pinecone.io/vectors/upsert" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "vectors": [
      {
        "id": "A",
        "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]
      },
      {
        "id": "B",
        "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
      },
      {
        "id": "C",
        "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
      },
      {
        "id": "D",
        "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
      },
      {
        "id": "E",
        "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]
      }
    ]
  }'

The curl command above uses the endpoint for your Pinecone index.

ℹ️
Note
When upserting larger amounts of data, upsert data in batches of 100 vectors or fewer over multiple upsert requests.

6. Run a nearest-neighbor search

Query your "quickstart" index for the 3 vectors that are most similar to an example 8-dimensional vector, using the Euclidean distance metric you specified for the index:

index.query(
  vector=[0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
  top_k=3,
  include_values=True
)
# Returns:
# {'matches': [{'id': 'C',
#               'score': 0.0,
#               'values': [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
#              {'id': 'D',
#               'score': 0.0799999237,
#               'values': [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]},
#              {'id': 'B',
#               'score': 0.0800000429,
#               'values': [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]}],
#  'namespace': ''}

const queryResponse = await index.query({
    topK: 3,
    vector: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
    includeValues: true
});
// Returns:
// {
// 	matches: [{
// 		id: "C",
// 		score: 0,
// 		values: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
// 	}, {
// 		id: "D",
// 		score: 0.0799999237,
// 		values: [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
// 	}, {
// 		id: "B",
// 		score: 0.0800000429,
// 		values: [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
// 	}],
// 	namespace: ""
// }

PINECONE_API_KEY="YOUR_API_KEY"
PINECONE_ENVIRONMENT="YOUR_ENVIRONMENT"

PINECONE_PROJECT_ID=$(
  curl "https://controller.$PINECONE_ENVIRONMENT.pinecone.io/actions/whoami" \
    -H "Api-Key: $PINECONE_API_KEY" | jq -r '.project_name'
)

curl -X POST "https://quickstart-$PINECONE_PROJECT_ID.svc.$PINECONE_ENVIRONMENT.pinecone.io/query" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
    "topK": 3,
    "includeValues": true
  }'
# Output:
# {
#   "matches":[
#     {
#       "id": "C",
#       "score": -1.76717265e-07,
#       "values": [0.3,0.3,0.3,0.3,0.3,0.3,0.3,0.3]
#     },
#     {
#       "id": "B",
#       "score": 0.080000028,
#       "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
#     },
#     {
#       "id": "D",
#       "score": 0.0800001323,
#       "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
#     }
#   ],
#   "namespace": ""
# }

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.

7. Clean up

The Starter plan allows only a single index, so once you're done with the "quickstart" index, use the delete_index operation to delete it:

pinecone.delete_index("quickstart")

await pinecone.deleteIndex("quickstart");

PINECONE_API_KEY="YOUR_API_KEY"
PINECONE_ENVIRONMENT="YOUR_ENVIRONMENT"

curl -X DELETE "https://controller.$PINECONE_ENVIRONMENT.pinecone.io/databases/quickstart" \
  -H "Api-Key: $PINECONE_API_KEY"

⚠️
Warning
After you delete an index, you cannot use it again.

Next steps

Now that you have a free Pinecone account and experience with basic Pinecone operations, check out our sample applications using common AI patterns, tools, and algorithms, or start inserting your own vector embeddings.