Compendium.Adapters.Pinecone 1.0.0-preview.0

compendium-adapter-pinecone

Pinecone adapter for the Compendium framework. Implements IVectorStore from Compendium.Abstractions.VectorStore over Pinecone's managed serverless vector database via a hand-rolled HttpClient — no vendor SDK.

Built from template-compendium-adapter-dotnet. Companion to compendium-adapter-pgvector and compendium-adapter-qdrant — same abstraction, same tenant isolation posture, same Result-pattern error handling.

What's in this package

Install

dotnet add package Compendium.Adapters.Pinecone

Quick start

Sign up for a free Pinecone account at app.pinecone.io. Free-tier serverless gives you one index in us-east-1 on AWS — enough to dogfood the round-trip.

using Compendium.Abstractions.VectorStore;
using Compendium.Abstractions.VectorStore.Models;
using Compendium.Adapters.Pinecone.DependencyInjection;
using Compendium.Adapters.Pinecone.Options;

services.AddCompendiumPinecone(o =>
{
    o.ApiKey = builder.Configuration["Pinecone:ApiKey"]!; // required
    o.Cloud  = PineconeCloud.Aws;
    o.Region = "us-east-1";
});

// IVectorStore is now resolvable from DI.
var store = services.BuildServiceProvider().GetRequiredService<IVectorStore>();
await store.EnsureCollectionAsync("documents", dimension: 1536, DistanceMetric.Cosine);
await store.UpsertAsync("documents", new[]
{
    new VectorRecord("doc-1", embedding, metadata, tenantId: "tenant-1"),
});

var matches = await store.SearchAsync(
    "documents",
    queryEmbedding,
    topK: 5,
    VectorFilter.Eq("category", "support").ForTenant("tenant-1"));

A runnable example lives under samples/01-managed-rag.

Configuration options

Bind to the Compendium:Adapters:Pinecone section, or pass an inline callback.

The two-plane architecture (read this once)

Pinecone splits its REST API into two HTTP planes:

PineconeVectorStore resolves the per-index data-plane host on first use via GET /indexes/{name} and caches it in-process. Subsequent reads / writes go straight to the data plane — one extra round-trip on cold start, zero overhead afterwards. EnsureCollectionAsync pre-seeds the cache when it succeeds, so the typical flow (ensure → upsert → search) makes exactly one control-plane call.

If you delete an index outside the adapter, the cached host becomes stale — restart the process or let the data-plane 404 propagate as VectorStore.CollectionNotFound.

Tenancy

Pinecone offers two patterns for multi-tenant isolation. The adapter exposes both via PineconeOptions.TenancyMode.

Namespace mode (default — recommended)

Each tenant id maps to a Pinecone namespace. Every data-plane call includes a namespace field on the request body. This is the cleanest isolation Pinecone offers:

• Reads and writes to one namespace are physically partitioned from another.
• Per-namespace point counts are exposed in Pinecone's stats endpoint.
• No metadata-filter cost on every query.

Use this mode when tenant cardinality is low to moderate (Pinecone recommends ≤ 10,000 namespaces per index — past that, namespace overhead starts to matter).

Metadata mode

The tenant id is stored in the record's metadata under the reserved tenant_id key. Every search emits an $eq filter on that key. Use this mode when:

• You have very high tenant cardinality (hundreds of thousands of tenants) and namespaces would blow past Pinecone's recommended limits.
• You need cross-tenant searches in addition to per-tenant searches — switching modes per-call isn't supported, but a Metadata-mode index lets you omit the filter to query the whole index.

Trade-off: queries are slower (Pinecone applies the metadata filter on the hot path), and stats don't break down per-tenant.

Both modes

• TenantIdentifier.IsValid rejects anything outside [a-zA-Z0-9_-]{1,255} before serialisation — defence-in-depth against tenant-id-driven injection. Mirrors the validator used by compendium-adapter-pgvector and compendium-adapter-qdrant.
• Tenanted deletes only touch the tenant's vectors. Cross-tenant deletes-by-id are impossible by construction.

Distance metrics

The metric is fixed at EnsureCollectionAsync time. Trying to recreate an existing index with a different dimension or metric returns VectorStore.DimensionMismatch / Pinecone.MetricMismatch.

Production checklist

• TLS — automatic. Every Pinecone endpoint is HTTPS.
• API key rotation — never check the API key into source. Rotate via your secret store (we read it via IOptions<PineconeOptions>, so any provider works). After rotation you must restart the process: the key is bound to the singleton HttpClient on first construction.
• Region selection — Pinecone serverless free-tier is us-east-1/AWS only. For paid tiers, pick a region close to your application servers; cross-region latency dominates query time for small vectors.
• Free-tier limits — one serverless index, 100K vectors / 4 GB write-units / 1M read-units per month. Plenty for prototyping, not enough for prod.
• Index name rules — Pinecone limits index names to lowercase [a-z0-9-], 1–45 chars, no leading or trailing dash. The adapter enforces the same rules and returns Pinecone.InvalidIndex on violation.
• Eventual consistency — Pinecone serverless reads are eventually consistent. Upserts may take a few seconds to be visible to queries. The sample sleeps 3 seconds before searching — adjust for your workload.
• Pooled HttpClient — the DI extension registers PineconeVectorStore via IHttpClientFactory, so HTTP connections are pooled across requests by default.
• Namespace vs metadata trade-off — start with namespace mode. Switch to metadata mode only when you've measured namespace overhead at scale.

Versioning

This package is published as Compendium.Adapters.Pinecone. Versions are driven by git tags via MinVer — see docs/RELEASE.md. The release tag is set by the orchestrator after merge to main.

Repository conventions

Build & test locally

# Unit tests — no Pinecone account required.
dotnet test --filter "FullyQualifiedName!~IntegrationTests"

# Integration tests — needs a Pinecone API key on a free-tier or higher account.
export PINECONE_API_KEY="..."
dotnet test --filter "FullyQualifiedName~IntegrationTests"

The integration suite covers idempotent ensure, namespaced upsert/search/delete round-trip, and collection-not-found behaviour against a live Pinecone serverless index. It skips cleanly when PINECONE_API_KEY is absent via the [RequiresPineconeFact] attribute.

License

MIT — Copyright © 2026 Sassy Solutions.