In this article
- The architecture
- Prerequisites
- Step 1: Configure and run both halves
- Step 2: Parse and chunk the documents
- Step 3: Embed the chunks
- Step 4: Give chunks addressable IDs and upsert by namespace
- Step 5: Retrieve context for a question
- Step 6: Build the prompt and stream the answer
- Step 7: Delete one document from a workspace
- What to change before production
- Where to go next
This guide is adapted from Pinecone's Namespace Notes sample app in the pinecone-io/sample-apps repository (MIT licence). Code is reproduced from the app's source files; where the source and its README disagree, we follow the source and say so.
Most "chat with your PDFs" tutorials stop at one user and one pile of documents. Real products need many: each customer, team or project uploads its own files and must only ever get answers from them. Pinecone's Namespace Notes sample shows the simplest robust way to do that, one Pinecone namespace per workspace, with a complete pipeline around it: PDF parsing, paragraph-aware chunking, embeddings, batched upserts, retrieval with a relevance floor, a citation-aware system prompt, streaming chat in Next.js, and targeted document deletion.
This guide walks through that code file by file. It explains what each part does, and the decisions you will want to change before it carries production traffic.
The architecture
The sample is two processes. A Next.js client (App Router, Tailwind, the Vercel AI SDK) renders workspaces and the chat UI and owns the chat route. A Node.js and Express server handles uploads, parsing, chunking, embedding, upserting and retrieval. Keeping them apart, in Pinecone's words, lets you swap either side for a stack of your choice.
A question flows like this: the chat UI posts the conversation and the workspace's namespaceId to the Next.js route /api/chat. That route asks the server's /api/context/fetch for a system prompt containing retrieved context, then streams the model's answer back to the browser.
Prerequisites
- Node.js 20 or later. The README requires it.
- A Pinecone account and API key, and an OpenAI API key.
- A Pinecone serverless index with: vector type Dense, dimension 1536, metric cosine, cloud AWS, region us-east-1. Create it with manual or custom settings so you can set the dimension yourself. It must match the embedding model below.
Step 1: Configure and run both halves
The fastest start, per the README, is npx create-pinecone-app. To run it from the repository, install and start the client and the server in two terminals. The client needs an OpenAI key and the server's URL:
cd client && npm install
OPENAI_API_KEY="your-api-key-here"
# The URL of the server (only used for development)
SERVER_URL="http://localhost:4001"
The server needs Pinecone and OpenAI credentials. Its .env.dist:
PINECONE_API_KEY="your_pinecone_api_key_here"
PINECONE_INDEX_NAME="your_pinecone_index_name_here"
OPENAI_API_KEY="your_openai_api_key_here"
Then cd server && npm install and npm run dev in each half. Uploaded files are stored on the server's local disk by default. DigitalOcean Spaces is supported for public file hosting but optional.
Step 2: Parse and chunk the documents
documentProcessor.ts extracts text with pdf-parse, rendering each page's text items joined by spaces, and treats anything that is not a PDF as UTF-8 text:
if (fileType === "application/pdf") {
const pdfData = await pdfParse(fileData, {
pagerender: function (page: any) {
return page
.getTextContent({
normalizeWhitespace: true,
})
.then(function (textContent: { items: any[] }) {
return textContent.items
.map(function (item) {
return item.str;
})
.join(" ");
});
},
});
documentContent = pdfData.text;
The text is then split by a paragraph-aware chunker:
function chunkTextByMultiParagraphs(
text: string,
maxChunkSize = 1500,
minChunkSize = 500
): string[] {
const chunks: string[] = [];
let currentChunk = "";
let startIndex = 0;
while (startIndex < text.length) {
let endIndex = startIndex + maxChunkSize;
if (endIndex >= text.length) {
endIndex = text.length;
} else {
// Just using this to find the nearest paragraph boundary
const paragraphBoundary = text.indexOf("\n\n", endIndex);
if (paragraphBoundary !== -1) {
endIndex = paragraphBoundary;
}
}
const chunk = text.slice(startIndex, endIndex).trim();
if (chunk.length >= minChunkSize) {
chunks.push(chunk);
currentChunk = "";
} else {
currentChunk += chunk + "\n\n";
}
startIndex = endIndex + 1;
}
if (currentChunk.length >= minChunkSize) {
chunks.push(currentChunk.trim());
} else if (chunks.length > 0) {
chunks[chunks.length - 1] += "\n\n" + currentChunk.trim();
} else {
chunks.push(currentChunk.trim());
}
return chunks;
}
Three things about this function are not obvious from a first read:
maxChunkSizeis a starting point, not a cap. At 1,500 characters the chunker searches forward for the next blank line, so a chunk runs on until the paragraph ends, however long that is.- In PDFs, chunks are roughly pages. Because each page's text is joined with spaces, the only paragraph breaks are between pages. A dense page becomes one large chunk.
- The defaults are 1,500 and 500, although the function's docstring (and the README) still say 1,000 and 100. Trust the signature.
Step 3: Embed the chunks
embeddings.ts embeds every chunk of a document in one request with OpenAI's text-embedding-3-small, explicitly at 1,536 dimensions to match the index:
export async function embedChunks(chunks: string[]): Promise<any> {
// You can use any embedding model or service here.
// In this example, we use OpenAI's text-embedding-3-small model.
const openai = new OpenAI({
apiKey: config.openAiApiKey,
organization: config.openAiOrganizationId,
});
try {
const response = await openai.embeddings.create({
model: "text-embedding-3-small",
input: chunks,
encoding_format: "float",
dimensions: 1536,
});
return response.data;
} catch (error) {
console.error("Error embedding text with OpenAI:", error);
throw error;
}
}
The same function embeds user questions at query time, which is what guarantees questions and chunks live in the same vector space. Change the model here and you must change it in both places, and re-embed everything already stored.
Step 4: Give chunks addressable IDs and upsert by namespace
Each chunk's ID is the document ID plus its index, joined by a colon:
for (let i = 0; i < chunks.length; i++) {
document.chunks.push({
id: `${document.documentId}:${i}`,
values: embeddings[i].embedding,
text: chunks[i],
});
}
That convention is what makes per-document updates and deletes possible later. The chunks are then written to the workspace's namespace in batches of 200, with the chunk text and the document's URL stored as metadata:
async upsertDocument(document: Document, namespaceId: string) {
// Adjust to use namespaces if you're organizing data that way
const namespace = index.namespace(namespaceId);
const vectors: PineconeRecord<RecordMetadata>[] = document.chunks.map(
(chunk) => ({
id: chunk.id,
values: chunk.values,
metadata: {
text: chunk.text,
referenceURL: document.documentUrl,
},
})
);
// Batch the upsert operation
const batchSize = 200;
for (let i = 0; i < vectors.length; i += batchSize) {
const batch = vectors.slice(i, i + batchSize);
await namespace.upsert({ records: batch });
}
}
The README shows an older form, namespace.upsert(batch). The source uses upsert({ records: batch }), which matches the version 8 Pinecone client the app depends on. Storing the text in metadata means retrieval needs no second lookup: the matching chunk's text comes back with the match.
Step 5: Retrieve context for a question
getContext embeds the latest message, queries the workspace's namespace, filters weak matches and builds the context string:
export const getContext = async (
message: string,
namespace: string,
maxCharacters = 5000,
minScore = 0.15,
getOnlyText = true
): Promise<string | ScoredPineconeRecord[]> => {
try {
// Wrap the message in an array before passing it to embedChunks
const embeddings = await embedChunks([message]);
// Extract the embedding from the response
const embedding = embeddings[0].embedding;
const matches = await getMatchesFromEmbeddings(embedding, 15, namespace);
const qualifyingDocs = matches.filter((m) => m.score && m.score > minScore);
if (!getOnlyText) {
return qualifyingDocs;
}
// Deduplicate and get text
const documentTexts = qualifyingDocs.map((match) => {
const metadata = match.metadata as Metadata;
return `REFERENCE URL: ${metadata.referenceURL} CONTENT: ${metadata.text}`;
});
// Concatenate, then truncate by maxCharacters
const concatenatedDocs = documentTexts.join(" ");
return concatenatedDocs.length > maxCharacters
? concatenatedDocs.substring(0, maxCharacters)
: concatenatedDocs;
} catch (error) {
console.error("Failed to get context:", error);
throw error;
}
};
The query itself, in pinecone.ts, targets only the given namespace and asks for metadata back:
// Get the Pinecone index and namespace
const pineconeNamespace = pinecone.Index<Metadata>(indexName).namespace(namespace ?? "");
try {
// Query the index with the defined request
const queryResult = await pineconeNamespace.query({
vector: embeddings,
topK,
includeMetadata: true,
});
return queryResult.matches || [];
Read the numbers together. Up to 15 matches come back, those scoring 0.15 or below are dropped, and the joined text is cut at 5,000 characters. With chunks of a page or more, only the first few matches will usually survive the cut, and the last one may be truncated mid-sentence. Despite its comment, the "Deduplicate" step does not remove duplicates; it only formats each match. Each match is labelled with its REFERENCE URL, which is what lets the model cite sources.
Step 6: Build the prompt and stream the answer
createPrompt puts that context inside a system prompt between START CONTEXT BLOCK and END OF CONTEXT BLOCK markers. The prompt tells the model to answer only from the context, to say it does not know when the block is empty, not to share URLs outside the block, and to cite sources as numbered links, adding a PDF page anchor only when certain of the page. It retrieves using only the last message:
// Get the last message
const lastMessage = messages[messages.length - 1]["content"];
// Get the context from the last message
const context = await getContext(lastMessage, namespaceId);
The Next.js chat route fetches that prompt from the server and streams the answer with the Vercel AI SDK:
import { streamText, convertToModelMessages, type UIMessage } from "ai";
import { openai } from "@ai-sdk/openai";
export const runtime = "edge";
export async function POST(req: Request) {
const { messages, namespaceId }: { messages: UIMessage[]; namespaceId: string } =
await req.json();
const contextMessages = messages.map((message) => ({
role: message.role,
content: message.parts
.map((part) => (part.type === "text" ? part.text : ""))
.join(""),
}));
const response = await fetch(`${process.env.SERVER_URL}/api/context/fetch`, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
namespaceId: namespaceId,
messages: contextMessages,
}),
});
const { context } = await response.json();
if (context && context.prompt && context.prompt.length > 0) {
const systemContent = context.prompt[0].content;
const result = streamText({
system: systemContent,
temperature: 0.2,
model: openai("gpt-4-turbo"),
maxRetries: 8,
messages: await convertToModelMessages(messages),
});
return result.toUIMessageStreamResponse();
} else {
throw new Error(
"Unexpected server response structure: 'prompt' array is missing or empty."
);
}
}
The route flattens the AI SDK's message parts into plain text for the server, uses the returned system prompt, and streams the full conversation to the model at temperature 0.2. toUIMessageStreamResponse() returns the stream in the format the AI SDK's React hooks consume on the client.
Step 7: Delete one document from a workspace
Because every chunk ID starts with documentId:, deleting a document means listing IDs by prefix and deleting them, one page at a time:
const namespace = index.namespace(namespaceId);
const listResult = await namespace.listPaginated({
prefix: `${documentId}:`,
limit: limit,
paginationToken: paginationToken,
});
async deleteDocumentChunks(chunkIds: string[], namespaceId: string) {
console.log("Deleting Document Chunks");
const namespace = index.namespace(namespaceId);
await namespace.deleteMany(chunkIds);
}
The controller loops, 100 IDs per page, until no IDs or pagination token remain. Deleting a whole workspace is simpler: namespace.deleteAll() clears the namespace.
What to change before production
| In the sample | Why it matters | What to do |
|---|---|---|
Client sends namespaceId; server trusts it | Workspaces live in browser local storage, so anyone who knows or guesses a namespace ID can query that tenant's documents. The Express server has no auth middleware and calls cors() with no options, which accepts any origin | Add authentication; map users to namespaces on the server and reject the rest; restrict CORS to your own origin |
| Retrieval uses only the last message | Follow-ups like "what about the second one?" retrieve poorly | Rewrite the question with the conversation before embedding it |
listIndexes() on every query | An extra API round trip before every retrieval | Check the index once at startup |
| One embeddings request per document | Very large documents can exceed per-request input limits | Batch embedChunks calls, as the upsert already is |
| Page-sized PDF chunks, 5,000-character context cut | Few chunks fit, and the last is cut mid-text | Split pages into smaller chunks, or trim whole matches instead of characters |
runtime = "edge" and gpt-4-turbo | Vercel now recommends the Node.js runtime over Edge, and the model is several generations old | Remove the runtime line; choose a current model in one place |
Where to go next
Before tuning chunk sizes or minScore, build a test set so you can measure the change; our guide to generating synthetic RAG test sets with Ragas shows how. When pure vector search misses exact terms such as product codes or names, add keyword matching with hybrid search and reciprocal rank fusion. For Pinecone's integrated embedding, where Pinecone embeds the text for you, see our semantic search over meeting audio guide. And for the architecture decisions around all of this, read designing a production-grade RAG architecture.
Frequently asked questions
How do you isolate tenants in a Pinecone RAG app?
Give each tenant its own namespace in one index. Pinecone's Namespace Notes sample upserts every workspace's chunks into a namespace named after the workspace ID and queries only that namespace, so one workspace's documents never appear in another's results. The isolation is only as strong as the check that a user may use that namespace ID.
What Pinecone index settings does the Namespace Notes sample need?
A serverless dense index with dimension 1536 and the cosine metric, on AWS us-east-1. The dimension must match the embeddings: the sample uses OpenAI's text-embedding-3-small with dimensions set to 1536.
How do you delete one document's vectors from a Pinecone namespace?
Prefix every chunk ID with the document ID, for example documentId:0, documentId:1. To delete the document, list the namespace's IDs with that prefix using listPaginated, then pass them to deleteMany, page by page until no IDs remain.
Why does the sample retrieve 15 matches but send less to the model?
getContext queries Pinecone for the top 15 matches, drops any with a similarity score of 0.15 or below, joins the rest, and truncates the result to 5,000 characters. That bounds prompt size, but the cut can fall mid-chunk, so tune topK, chunk size and the character limit together.
Does the Pinecone Namespace Notes sample authenticate users?
No. Workspaces are kept in the browser's local storage and the client sends the namespace ID with each request, which the server trusts. Before production, add authentication and map each user to the namespaces they own on the server.
Related Guides
Build a Multi-Query RAG Retriever with Elasticsearch and LangChain
Reproduce Elasticsearch Labs' multi-query RAG pipeline: paraphrase user queries, retrieve against Elasticsearch, and feed combined context to an LLM.
Build Entity-Aware Semantic Search with Pinecone Metadata Filters
Extract named entities from text, store them as Pinecone metadata, and filter vector search so results share at least one entity with the query.
DeepSeek dsh-superagent: Router-Worker Agent Hits p95 of 15.7 Min
DeepSeek's MIT-licensed dsh-superagent routes GitHub issues into parallel, isolated coding sessions, hitting a simulated p95 of 15.7 vs 29.5 minutes for sequential handling.