Quickstart guide

This guide explains how to set up a Pinecone client and get a production-ready similarity search service up and running in minutes.

1. Install Pinecone (optional)

This step is optional. Do this step only if you want to use the Python client.

Use the following shell command to install Pinecone:

Copy
Copied
pip install pinecone-client

For more information on how to install Pinecone clients, including troubleshooting, see Installation.

2. Get and verify your Pinecone API key

To use Pinecone, you must have an API key. To find your API key, open the Pinecone console, click your project name, and click API Keys.

To verify that your Pinecone API key works, use the following commands:

pythoncurl
Copy
Copied
import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="us-west1-gcp")
Copy
Copied
curl -i https://controller.YOUR_ENVIRONMENT.pinecone.io/actions/whoami -H 'Api-Key: YOUR_API_KEY'

By default, YOUR_ENVIRONMENT is us-west1-gcp.

If you don't receive an error message, then your API key is valid.

3. Hello, Pinecone!

You can complete the remaining steps in three ways:

  • Use the "Hello, Pinecone!" colab notebook to write and execute Python in your browser.
  • Copy the commands below into your local installation of Python.
  • Use the cURL API commands below.

1. Initialize Pinecone

pythoncurl
Copy
Copied
import pinecone
pinecone.init(api_key="YOUR_API_KEY", environment="us-west1-gcp")
Copy
Copied
# Not applicable

2. Create an index.

The commands below create an index named "quickstart" that performs approximate nearest-neighbor search using the Euclidean distance metric for 8-dimensional vectors.

Index creation takes roughly a minute.

pythoncurl
Copy
Copied
pinecone.create_index("quickstart", dimension=8, metric="euclidean", pod_type="p1")
Copy
Copied
curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Api-Key: YOUR_API_KEY_HERE' \
  https://controller.YOUR_ENVIRONMENT.pinecone.io/databases \
  -d '{
    "name": "quickstart",
    "dimension": 8,
    "metric": "euclidean"
  }'
warning

Indexes on the Starter (free) plan are deleted after 7 days of inactivity. To prevent this, send any API request or log into the console. This will count as activity.

3. Retrieve a list of your indexes.

Once your index is created, its name appears in the index list.

Use the following commands to return a list of your indexes.

pythoncurl
Copy
Copied
pinecone.list_indexes()
# Returns:
# ['quickstart']
Copy
Copied
curl -i https://controller.YOUR_ENVIRONMENT.pinecone.io/databases \
  -H "Api-Key: YOUR_API_KEY"
# Output:
# ["quickstart"]

4. Connect to the index (Client only).

Before you can query your index using a client, you must connect to the index.

Use the following commands to connect to your index.

pythoncurl
Copy
Copied
index = pinecone.Index("quickstart")
Copy
Copied
# Not applicable

5. Insert the data.

To ingest vectors into your index, use the upsert operation. The upsert operation inserts a new vector in the index or updates the vector if a vector with the same ID is already present.

The following commands upsert 5 8-dimensional vectors into your index.

pythoncurl
Copy
Copied
# Upsert sample data (5 8-dimensional vectors)
index.upsert([
    ("A", [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]),
    ("B", [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]),
    ("C", [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]),
    ("D", [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]),
    ("E", [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5])
])
Copy
Copied
curl -i -X POST https://quickstart-YOUR_PROJECT.svc.YOUR_ENVIRONMENT.pinecone.io/vectors/upsert \
  -H 'Api-Key: YOUR_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. Get statistics about your index.

The following commands return statistics about the contents of your index.

pythoncurl
Copy
Copied
index.describe_index_stats()
# Returns:
# {'dimension': 8, 'index_fullness': 0.0, 'namespaces': {'': {'vector_count': 5}}}
Copy
Copied
curl -i https://quickstart-YOUR_PROJECT.svc.YOUR_ENVIRONMENT.pinecone.io/describe_index_stats \
  -H 'Api-Key: YOUR_API_KEY'

# Output:
# {
#   "namespaces": {
#     "": {
#       "vectorCount": 5
#     }
#   },
#   "dimension": 8
# }

7. Query the index and get similar vectors.

The following example queries the index for the three (3) vectors that are most similar to an example 8-dimensional vector using the Euclidean distance metric specified in step 2 ("Create an index.") above.

pythoncurl
Copy
Copied
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': ''}
Copy
Copied
curl -i -X POST https://quickstart-YOUR_PROJECT.svc.YOUR_ENVIRONMENT.pinecone.io/query \
  -H 'Api-Key: YOUR_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": ""
#     }

8. Delete the index.

Once you no longer need the index, use the delete_index operation to delete it.

The following commands delete the index.

pythoncurl
Copy
Copied
pinecone.delete_index("quickstart")
Copy
Copied
curl -i -X DELETE https://controller.YOUR_ENVIRONMENT.pinecone.io/databases/quickstart \
  -H 'Api-Key: YOUR_API_KEY'
warning

When the index is deleted, you cannot use it again.

Next steps

Now that you’re successfully making indexes with your API key, you can start inserting data or view more examples.