How to Intermediate · 4 min read

How to build semantic search with Pinecone

Q: How to build semantic search with Pinecone

Build semantic search with Pinecone by generating vector embeddings of your documents using an embedding model like text-embedding-3-small from OpenAI, then indexing these vectors in a Pinecone index. Query by embedding the search text and retrieving nearest vectors with index.query().

Quick answer

Build semantic search with Pinecone by generating vector embeddings of your documents using an embedding model like text-embedding-3-small from OpenAI, then indexing these vectors in a Pinecone index. Query by embedding the search text and retrieving nearest vectors with index.query().

PREREQUISITES

Python 3.8+
OpenAI API key
Pinecone API key
pip install openai pinecone-client

Setup

Install the required Python packages and set environment variables for your OPENAI_API_KEY and PINECONE_API_KEY. Initialize the Pinecone client and create an index for vector storage.

bash

pip install openai pinecone-client

output

Collecting openai
Collecting pinecone-client
Successfully installed openai-1.x.x pinecone-client-2.x.x

Step by step

This example shows how to embed documents with OpenAI embeddings, upsert them into a Pinecone index, and perform a semantic search query.

python

import os
from openai import OpenAI
import pinecone

# Initialize clients
openai_client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
pc = pinecone.Pinecone(api_key=os.environ["PINECONE_API_KEY"])

# Create or connect to Pinecone index
index_name = "semantic-search"
if index_name not in pc.list_indexes():
    pc.create_index(index_name, dimension=1536, metric="cosine")
index = pc.Index(index_name)

# Sample documents
documents = [
    {"id": "doc1", "text": "Pinecone is a vector database for semantic search."},
    {"id": "doc2", "text": "OpenAI provides powerful embedding models."},
    {"id": "doc3", "text": "Semantic search finds relevant documents by meaning."}
]

# Generate embeddings for documents
texts = [doc["text"] for doc in documents]
response = openai_client.embeddings.create(model="text-embedding-3-small", input=texts)
vectors = [data.embedding for data in response.data]

# Upsert vectors into Pinecone
upsert_data = [(doc["id"], vector) for doc, vector in zip(documents, vectors)]
index.upsert(vectors=upsert_data)

# Query semantic search
query_text = "What is Pinecone used for?"
query_response = openai_client.embeddings.create(model="text-embedding-3-small", input=[query_text])
query_vector = query_response.data[0].embedding

# Query Pinecone index
results = index.query(vector=query_vector, top_k=2, include_metadata=False)

print("Top matches:")
for match in results.matches:
    print(f"ID: {match.id}, Score: {match.score:.4f}")

output

Top matches:
ID: doc1, Score: 0.9123
ID: doc3, Score: 0.8765

Common variations

You can use asynchronous calls with Pinecone's async client or switch to different embedding models like text-embedding-3-large. Also, you can include metadata with vectors for richer filtering during queries.

python

import asyncio
from openai import OpenAI
import pinecone

async def async_semantic_search():
    openai_client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
    pc = pinecone.Pinecone(api_key=os.environ["PINECONE_API_KEY"])
    index = pc.Index("semantic-search")

    query_text = "Explain semantic search"
    response = await openai_client.embeddings.acreate(model="text-embedding-3-large", input=[query_text])
    query_vector = response.data[0].embedding

    results = index.query(vector=query_vector, top_k=3)
    for match in results.matches:
        print(f"ID: {match.id}, Score: {match.score:.4f}")

asyncio.run(async_semantic_search())

output

ID: doc3, Score: 0.9345
ID: doc1, Score: 0.8890
ID: doc2, Score: 0.8452

Troubleshooting

If you get IndexNotFoundError, ensure your Pinecone index is created and the name matches.
Embedding dimension mismatch errors mean your Pinecone index dimension does not match the embedding model output size (1536 for text-embedding-3-small).
Check your API keys and environment variables if authentication fails.

✅

Key Takeaways

Use OpenAI embeddings to convert text into vectors for semantic search.
Create a Pinecone index with the correct vector dimension matching your embedding model.
Upsert document vectors into Pinecone and query with embedded search text for nearest neighbors.
Include metadata in Pinecone vectors for advanced filtering and richer search results.
Handle common errors by verifying index existence, dimension compatibility, and API key validity.

Verified 2026-04 · text-embedding-3-small, text-embedding-3-large

Verify ↗