Quickstart

This quickstart walks you through creating a Pinecone index and building a sample application for semantic search, recommendations, or RAG.

Prefer the command line? Try the Pinecone CLI!

Install the CLI.

# Using Homebrew (https://brew.sh)
brew tap pinecone-io/tap
brew install pinecone-io/tap/pinecone

Authenticate and get started using Pinecone!
```
pc auth login
```

For more info, see the CLI quickstart.

Get set up

To get started, you’ll need a Pinecone account and API key.

1. Create a Pinecone account

If you’re new to Pinecone, sign up at app.pinecone.io and choose a plan:

Starter plan (free): Free access to most features, but you’re limited to one cloud region and need to stay under Starter plan limits.
Builder plan ($20/month): Higher quotas than Starter and predictable flat pricing with no usage overages. Ideal for small production apps. Indexes must be in the us-east-1 region of AWS.
Standard plan trial: 21 days and $300 in credits with access to Standard plan features and higher limits that let you test Pinecone at scale.

If you’re already on a Starter plan, you can upgrade to Builder at any time, or activate a Standard plan trial (one trial per organization).

After signing up, you’ll receive an API key in the console. Save this key. You’ll need it to authenticate your requests to Pinecone.

2. Get a Pinecone API key

Create a new API key in the Pinecone console, or use the widget below to generate a key. If you don’t have a Pinecone account, the widget will sign you up for the free Starter plan.

Your generated API key:

"{{YOUR_API_KEY}}"

Build with Pinecone

Choose your approach to build with Pinecone below. Each approach achieves the same result—building a sample app for semantic search—but uses different tools and workflows.

Manual
Cursor
Claude Code
n8n

Use Pinecone’s SDKs to manually create indexes, upsert data, and run queries.

1. Install an SDK

Install the SDK for your preferred language:

pip install pinecone

To get started in your browser, use the Quickstart colab notebook.

2. Create an index

This quickstart builds a semantic-search app on an index with dense vectors integrated with an embedding model hosted by Pinecone. You upsert and search with text, and Pinecone generates the vectors for you. For other ways to model and search data in Pinecone, see Index.

For keyword and phrase search over text content, use full-text search instead. It’s in public preview, with REST and Python SDK support.

If you prefer to use external embedding models, see Bring your own vectors.

# Import the Pinecone library
from pinecone import Pinecone

# Initialize a Pinecone client with your API key
pc = Pinecone(api_key="{{YOUR_API_KEY}}")

# Create an index for dense vectors with integrated embedding
index_name = "quickstart-py"
if not pc.has_index(index_name):
    pc.create_index_for_model(
        name=index_name,
        cloud="aws",
        region="us-east-1",
        embed={
            "model":"llama-text-embed-v2",
            "field_map":{"text": "chunk_text"}
        }
    )

3. Upsert text

Prepare a sample dataset of factual statements from different domains like history, physics, technology, and music. Model the data as records with an ID, text, and category.

records = [
    { "_id": "rec1", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history" },
    { "_id": "rec2", "chunk_text": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science" },
    { "_id": "rec3", "chunk_text": "Albert Einstein developed the theory of relativity.", "category": "science" },
    { "_id": "rec4", "chunk_text": "The mitochondrion is often called the powerhouse of the cell.", "category": "biology" },
    { "_id": "rec5", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature" },
    { "_id": "rec6", "chunk_text": "Water boils at 100°C under standard atmospheric pressure.", "category": "physics" },
    { "_id": "rec7", "chunk_text": "The Great Wall of China was built to protect against invasions.", "category": "history" },
    { "_id": "rec8", "chunk_text": "Honey never spoils due to its low moisture content and acidity.", "category": "food science" },
    { "_id": "rec9", "chunk_text": "The speed of light in a vacuum is approximately 299,792 km/s.", "category": "physics" },
    { "_id": "rec10", "chunk_text": "Newton's laws describe the motion of objects.", "category": "physics" },
    { "_id": "rec11", "chunk_text": "The human brain has approximately 86 billion neurons.", "category": "biology" },
    { "_id": "rec12", "chunk_text": "The Amazon Rainforest is one of the most biodiverse places on Earth.", "category": "geography" },
    { "_id": "rec13", "chunk_text": "Black holes have gravitational fields so strong that not even light can escape.", "category": "astronomy" },
    { "_id": "rec14", "chunk_text": "The periodic table organizes elements based on their atomic number.", "category": "chemistry" },
    { "_id": "rec15", "chunk_text": "Leonardo da Vinci painted the Mona Lisa.", "category": "art" },
    { "_id": "rec16", "chunk_text": "The internet revolutionized communication and information sharing.", "category": "technology" },
    { "_id": "rec17", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history" },
    { "_id": "rec18", "chunk_text": "Dogs have an incredible sense of smell, much stronger than humans.", "category": "biology" },
    { "_id": "rec19", "chunk_text": "The Pacific Ocean is the largest and deepest ocean on Earth.", "category": "geography" },
    { "_id": "rec20", "chunk_text": "Chess is a strategic game that originated in India.", "category": "games" },
    { "_id": "rec21", "chunk_text": "The Statue of Liberty was a gift from France to the United States.", "category": "history" },
    { "_id": "rec22", "chunk_text": "Coffee contains caffeine, a natural stimulant.", "category": "food science" },
    { "_id": "rec23", "chunk_text": "Thomas Edison invented the practical electric light bulb.", "category": "inventions" },
    { "_id": "rec24", "chunk_text": "The moon influences ocean tides due to gravitational pull.", "category": "astronomy" },
    { "_id": "rec25", "chunk_text": "DNA carries genetic information for all living organisms.", "category": "biology" },
    { "_id": "rec26", "chunk_text": "Rome was once the center of a vast empire.", "category": "history" },
    { "_id": "rec27", "chunk_text": "The Wright brothers pioneered human flight in 1903.", "category": "inventions" },
    { "_id": "rec28", "chunk_text": "Bananas are a good source of potassium.", "category": "nutrition" },
    { "_id": "rec29", "chunk_text": "The stock market fluctuates based on supply and demand.", "category": "economics" },
    { "_id": "rec30", "chunk_text": "A compass needle points toward the magnetic north pole.", "category": "navigation" },
    { "_id": "rec31", "chunk_text": "The universe is expanding, according to the Big Bang theory.", "category": "astronomy" },
    { "_id": "rec32", "chunk_text": "Elephants have excellent memory and strong social bonds.", "category": "biology" },
    { "_id": "rec33", "chunk_text": "The violin is a string instrument commonly used in orchestras.", "category": "music" },
    { "_id": "rec34", "chunk_text": "The heart pumps blood throughout the human body.", "category": "biology" },
    { "_id": "rec35", "chunk_text": "Ice cream melts when exposed to heat.", "category": "food science" },
    { "_id": "rec36", "chunk_text": "Solar panels convert sunlight into electricity.", "category": "technology" },
    { "_id": "rec37", "chunk_text": "The French Revolution began in 1789.", "category": "history" },
    { "_id": "rec38", "chunk_text": "The Taj Mahal is a mausoleum built by Emperor Shah Jahan.", "category": "history" },
    { "_id": "rec39", "chunk_text": "Rainbows are caused by light refracting through water droplets.", "category": "physics" },
    { "_id": "rec40", "chunk_text": "Mount Everest is the tallest mountain in the world.", "category": "geography" },
    { "_id": "rec41", "chunk_text": "Octopuses are highly intelligent marine creatures.", "category": "biology" },
    { "_id": "rec42", "chunk_text": "The speed of sound is around 343 meters per second in air.", "category": "physics" },
    { "_id": "rec43", "chunk_text": "Gravity keeps planets in orbit around the sun.", "category": "astronomy" },
    { "_id": "rec44", "chunk_text": "The Mediterranean diet is considered one of the healthiest in the world.", "category": "nutrition" },
    { "_id": "rec45", "chunk_text": "A haiku is a traditional Japanese poem with a 5-7-5 syllable structure.", "category": "literature" },
    { "_id": "rec46", "chunk_text": "The human body is made up of about 60% water.", "category": "biology" },
    { "_id": "rec47", "chunk_text": "The Industrial Revolution transformed manufacturing and transportation.", "category": "history" },
    { "_id": "rec48", "chunk_text": "Vincent van Gogh painted Starry Night.", "category": "art" },
    { "_id": "rec49", "chunk_text": "Airplanes fly due to the principles of lift and aerodynamics.", "category": "physics" },
    { "_id": "rec50", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy" }
]

Upsert the sample dataset into a new namespace in your index.Because your index is integrated with an embedding model, you provide the textual statements and Pinecone converts them to dense vectors automatically.

# Target the index
dense_index = pc.Index(index_name)

# Upsert the records into a namespace
dense_index.upsert_records("example-namespace", records)

To control costs when ingesting large datasets (10,000,000+ records), use import instead of upsert.

Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to check if the current vector count matches the number of vectors you upserted (50):

# Wait for the upserted vectors to be indexed
import time
time.sleep(10)

# View stats for the index
stats = dense_index.describe_index_stats()
print(stats)

The response looks like this:

{'dimension': 1024,
 'index_fullness': 0.0,
 'metric': 'cosine',
 'namespaces': {'example-namespace': {'vector_count': 50}},
 'total_vector_count': 50,
 'vector_type': 'dense'}

4. Semantic search

Search the index for ten records that are most semantically similar to the query, “Famous historical structures and monuments”.Again, because your index is integrated with an embedding model, you provide the query as text and Pinecone converts the text to a dense vector automatically.

# Define the query
query = "Famous historical structures and monuments"

# Search the index
results = dense_index.search(
    namespace="example-namespace",
    query={
        "top_k": 10,
        "inputs": {
            'text': query
        }
    }
)

# Print the results
for hit in results['result']['hits']:
        print(f"id: {hit['_id']:<5} | score: {round(hit['_score'], 2):<5} | category: {hit['fields']['category']:<10} | text: {hit['fields']['chunk_text']:<50}")

Notice that most of the results are about historical structures and monuments. However, a few unrelated statements are included as well and are ranked high in the list, for example, a statement about Shakespeare.

id: rec17 | score: 0.24  | category: history    | text: The Pyramids of Giza are among the Seven Wonders of the Ancient World.
id: rec38 | score: 0.19  | category: history    | text: The Taj Mahal is a mausoleum built by Emperor Shah Jahan.
id: rec5  | score: 0.19  | category: literature | text: Shakespeare wrote many famous plays, including Hamlet and Macbeth.
id: rec15 | score: 0.11  | category: art        | text: Leonardo da Vinci painted the Mona Lisa.          
id: rec50 | score: 0.1   | category: energy     | text: Renewable energy sources include wind, solar, and hydroelectric power.
id: rec26 | score: 0.09  | category: history    | text: Rome was once the center of a vast empire.        
id: rec47 | score: 0.08  | category: history    | text: The Industrial Revolution transformed manufacturing and transportation.
id: rec7  | score: 0.07  | category: history    | text: The Great Wall of China was built to protect against invasions.
id: rec1  | score: 0.07  | category: history    | text: The Eiffel Tower was completed in 1889 and stands in Paris, France.
id: rec3  | score: 0.07  | category: science    | text: Albert Einstein developed the theory of relativity.

5. Rerank results

To get a more accurate ranking, search again but this time rerank the initial results based on their relevance to the query.

# Search the index and rerank results
reranked_results = dense_index.search(
    namespace="example-namespace",
    query={
        "top_k": 10,
        "inputs": {
            'text': query
        }
    },
    rerank={
        "model": "bge-reranker-v2-m3",
        "top_n": 10,
        "rank_fields": ["chunk_text"]
    }   
)

# Print the reranked results
for hit in reranked_results['result']['hits']:
    print(f"id: {hit['_id']}, score: {round(hit['_score'], 2)}, text: {hit['fields']['chunk_text']}, category: {hit['fields']['category']}")

Notice that all of the most relevant results about historical structures and monuments are now ranked highest.

id: rec1  | score: 0.11  | category: history    | text: The Eiffel Tower was completed in 1889 and stands in Paris, France.
id: rec38 | score: 0.06  | category: history    | text: The Taj Mahal is a mausoleum built by Emperor Shah Jahan.
id: rec7  | score: 0.06  | category: history    | text: The Great Wall of China was built to protect against invasions.
id: rec17 | score: 0.02  | category: history    | text: The Pyramids of Giza are among the Seven Wonders of the Ancient World.
id: rec26 | score: 0.01  | category: history    | text: Rome was once the center of a vast empire.        
id: rec15 | score: 0.01  | category: art        | text: Leonardo da Vinci painted the Mona Lisa.          
id: rec5  | score: 0.0   | category: literature | text: Shakespeare wrote many famous plays, including Hamlet and Macbeth.
id: rec47 | score: 0.0   | category: history    | text: The Industrial Revolution transformed manufacturing and transportation.
id: rec50 | score: 0.0   | category: energy     | text: Renewable energy sources include wind, solar, and hydroelectric power.
id: rec3  | score: 0.0   | category: science    | text: Albert Einstein developed the theory of relativity.

6. Improve results

Reranking results is one of the most effective ways to improve search accuracy and relevance, but there are many other techniques to consider. For example:

Filtering by metadata: When records contain additional metadata, you can limit the search to records matching a filter expression.
Full-text search: For workflows where keyword and phrase matching matter (product SKUs, email addresses, domain-specific terms), we recommend an index with a document schema with one or more string fields declared with full_text_search enabled. It uses BM25 ranking on those FTS-enabled fields and supports Lucene query syntax, plus the text match operators ($match_phrase, $match_all, $match_any). A multi-field schema can declare BM25-indexed string fields alongside a dense_vector or sparse_vector field on the same index — combine them by restricting a dense (or sparse) search with a text-match filter on the lexical field, or by running separate searches and merging the results client-side.
Hybrid search: For vector-centric workflows on the vector API that need both dense and sparse vectors in a single index. For document-centric workflows, a multi-field document schema is the recommended path.
Chunking strategies: You can chunk your content in different ways to get better results. Consider factors like the length of the content, the complexity of queries, and how results will be used in your application.

7. Clean up

When you no longer need your example index, delete it as follows:

# Delete the index
pc.delete_index(index_name)

For production indexes, consider enabling deletion protection.

Next steps

Index data

Learn more about storing data in Pinecone

Search

Explore different forms of vector search.

Optimize

Find out how to improve performance

Use Cursor to build sample apps with Pinecone. Work with an AI agent that understands Pinecone APIs and implements production-ready patterns automatically, without manually copying code snippets.To get started, click this button:

Download AGENTS.md and launch in Cursor

This opens Cursor and enters this prompt:

First, download and run this remote script: 

curl -sSL https://docs.pinecone.io/install-agent-reference | sh 

Then, help me get started with Pinecone.

To see the contents of the install script, use a web browser to visit this URL: https://docs.pinecone.io/install-agent-reference.

When you run this prompt:

Cursor executes a remote script that downloads Pinecone agent reference files, extracts them into an .agents folder, and creates an AGENTS.md file. These files provide Cursor with context it can use to help you get started with Pinecone.
Then, Cursor helps you build a sample app of your choice (quick test, semantic search, RAG, or recommendations) in the programming language of your choice.

Next steps

After building some sample apps, use the AGENTS.md file to continue building with Pinecone, planning and implementing code for your own use cases.To learn more about Pinecone, check out these resources:

Index data

Learn more about storing data in Pinecone

Search

Explore different forms of vector search.

Optimize

Find out how to improve performance

Use Claude Code to build a Pinecone application with current best practices. Instead of copying code snippets, work with an agent that understands Pinecone APIs and implements production-ready patterns automatically.

Because this quickstart relies on AI, the exact implementation may vary each time.

If you don’t have Claude Code installed, see the Claude Code quickstart.

1. Set your API key

Set the PINECONE_API_KEY environment variable before installing the plugin and activating Claude Code:

export PINECONE_API_KEY="{{YOUR_API_KEY}}"

2. Install the Pinecone plugin for Claude Code

The Pinecone plugin provides Claude Code with up-to-date Pinecone API references and best practices. Install it using one of these methods:

From your terminal, run:
```
claude plugin install pinecone
```
Or, from within Claude Code, run:
```
/plugin install pinecone
```

For more information about Pinecone’s Claude Code plugin, see the Claude Code plugin integration page or the GitHub repository.

3. Run the quickstart command

To use the plugin to work through Pinecone’s quickstart, start Claude Code and run this command:

/pinecone:quickstart

This command does the following things:

Downloads and configures an AGENTS.md file that provides Claude Code with up-to-date Pinecone API information and best practices.
Guides you through setting up Pinecone using the Pinecone CLI and Pinecone MCP server.
Generates sample code to demonstrate various Pinecone use cases (quick start, semantic search, RAG, or recommendations).

Once complete, you can use the configured AGENTS.md files, MCP server, and CLI to build your application. The plugin also includes other slash commands, such as /pinecone:query, for interactively querying your indexes.

Use n8n to create a workflow that downloads files via HTTP and lets you chat with them using Pinecone Database and OpenAI.

If you’re not interested in chunking and embedding your own data or figuring out which search method to use, use n8n with Pinecone Assistant instead.

1. Get an OpenAI API key

Create a new API key in the OpenAI console.

2. Create an index

Create an index in the Pinecone console:

Name your index n8n-dense-index
Under Configuration, check Custom settings and set Dimension to 1536.
Leave everything else as default.

3. Set up n8n

Create a new workflow

In your n8n account, create a new workflow.

Import a workflow template

Copy this workflow template URL:

https://raw.githubusercontent.com/pinecone-io/n8n-templates/refs/heads/main/database-quickstart/database-quickstart.json

Paste the URL into the workflow editor and then click Import to add the workflow.

Add credentials to the workflow

Add your Pinecone credentials:
- In the Pinecone Vector Store node, select Credential to connect with > Create new credential and paste in your Pinecone API key.
- Name the credential Pinecone so that other nodes reference it.
Add your OpenAI credentials:
- In the OpenAI Chat Model, select Credential to connect with > Create new credential and paste in your OpenAI API key.

Activate the workflow

The workflow is configured to download recent Pinecone release notes and upload them to your Pinecone index. Click Execute workflow to start the workflow.

You can add your own files to the workflow by changing the URLs in the Set file urls node.

4. Chat with your docs

Once the workflow is activated, ask it for the latest changes to Pinecone Database:

What's new in Pinecone Database?

Next steps

Use your own data:
- Change the urls in Set file urls node to use your own files.
- You may need to adjust the chunk sizes in the Recursive Character Text Splitter node or use a different chunking strategy. You want chunks that are big enough to contain meaningful information but not so big that the meaning is diluted or it can’t fit within the context window of the embedding model. See Chunking Strategies for LLM Applications for more info.
- Customize the system message of the AI Agent node to reflect what the Pinecone Vector Store Tool will be used for. Be sure to include info on what data can be retrieved using that tool.
- Customize the description of the Pinecone Vector Store Tool to reflect what data you are storing in the Pinecone index.
Use n8n, Pinecone Assistant, and OpenAI to chat with your Google Drive documents.
Get help in the Pinecone Discord community.

Get started

Index data

Search

Optimize

Manage data

Manage cost

Move to production

Admin

Operations

Using pods

Get set up

1. Create a Pinecone account

2. Get a Pinecone API key

Build with Pinecone

1. Install an SDK

2. Create an index

3. Upsert text

4. Semantic search

5. Rerank results

6. Improve results

7. Clean up

Next steps

Index data

Search

Optimize

Next steps

Index data

Search

Optimize

1. Set your API key

2. Install the Pinecone plugin for Claude Code

3. Run the quickstart command

1. Get an OpenAI API key

2. Create an index

3. Set up n8n

4. Chat with your docs

Next steps

Get started

Index data

Search

Optimize

Manage data

Manage cost

Move to production

Admin

Operations

Using pods

Documentation Index

​Get set up

​1. Create a Pinecone account

​2. Get a Pinecone API key

​Build with Pinecone

​1. Install an SDK

​2. Create an index

​3. Upsert text

​4. Semantic search

​5. Rerank results

​6. Improve results

​7. Clean up

​Next steps

Index data

Search

Optimize

​Next steps

Index data

Search

Optimize

​1. Set your API key

​2. Install the Pinecone plugin for Claude Code

​3. Run the quickstart command

​1. Get an OpenAI API key

​2. Create an index

​3. Set up n8n

​4. Chat with your docs

​Next steps

Get set up

1. Create a Pinecone account

2. Get a Pinecone API key

Build with Pinecone

1. Install an SDK

2. Create an index

3. Upsert text

4. Semantic search

5. Rerank results

6. Improve results

7. Clean up

Next steps

Next steps

1. Set your API key

2. Install the Pinecone plugin for Claude Code

3. Run the quickstart command

1. Get an OpenAI API key

2. Create an index

3. Set up n8n

4. Chat with your docs

Next steps