# LlamaIndex on Pinecone: the wiring that actually works
## Setup
```
from pinecone import Pinecone
from llama_index.vector_stores.pinecone import PineconeVectorStore
from llama_index.core import StorageContext, VectorStoreIndex
pc = Pinecone()
pinecone_index = pc.Index("quickstart")
vector_store = PineconeVectorStore(
pinecone_index=pinecone_index,
namespace="docs-v1",
)
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)
```
## The pieces and their jobs
1. `Pinecone()` authenticates (env key) and `pc.Index(name)` targets the data plane. The index must already exist with the right dimension.
2. `PineconeVectorStore` adapts that index to LlamaIndex. `namespace` scopes all reads and writes; omit it and you land in the default (empty-string) namespace.
3. `StorageContext` is what `VectorStoreIndex.from_documents` consumes. Skipping the storage context and passing the vector store directly is the most common wiring mistake.
## Traps for agents
1. **Passing the client instead of the index.** `PineconeVectorStore(pinecone_index=pc)` fails; it wants `pc.Index(name)`, the index handle.
2. **Embedding mismatch.** LlamaIndex's default embedding model must output the index's dimension. Set `Settings.embed_model` explicitly and check one embedding's length before ingesting thousands of documents.
3. **Namespace drift.** Ingest with `namespace="docs-v1"` and query with a store built without it, and you search an empty namespace. Keep one constant for the namespace across ingest and query code.
4. **gRPC vs REST.** Some LlamaIndex examples construct `PineconeGRPC`. The REST client is the default and avoids the grpc extra unless you need its throughput.