Mythosia.VectorDb.Pinecone 4.0.2

Mythosia.VectorDb.Pinecone

v4.0.2 — Updated hashing and JSON dependencies with current compatible vector contracts. See the release notes.

Pinecone vector store implementation for the Mythosia VectorDb abstraction layer.

Isolation model:

• Collection = Pinecone index (physical storage)
• Namespace = Pinecone namespace (optional, via PineconeOptions.Namespace)
• Metadata = all user-defined key-value pairs stored as Pinecone metadata fields

Installation

dotnet add package Mythosia.VectorDb.Pinecone

Quick Start

using Mythosia.VectorDb;
using Mythosia.VectorDb.Pinecone;

var options = new PineconeOptions
{
    IndexHost = "https://my-index-xxxx.svc.us-east1-gcp.pinecone.io",
    ApiKey = "YOUR_PINECONE_API_KEY",
    Namespace = "documents"  // optional — scopes all operations to this namespace
};

using var store = new PineconeStore(options);

var record = new VectorRecord("doc-1", embedding, "Hello world");
await store.UpsertAsync(record);

var results = await store.SearchAsync(queryVector, topK: 5);

PineconeStore follows the same hybrid-capable storage model as QdrantStore:

• upserts always store dense vectors and sparse BM25-derived values together
• retrieval mode is chosen at query time
  • SearchAsync for vector-only retrieval
  • HybridSearchAsync for native dense + sparse retrieval

For native hybrid search, the Pinecone index metric must be dotproduct.

Options

When AutoCreateIndex = true, the index is created with dotproduct metric automatically.

AutoCreateIndex example

var options = new PineconeOptions
{
    ApiKey          = "YOUR_PINECONE_API_KEY",
    AutoCreateIndex = true,
    IndexName       = "my-index",
    Dimension       = 1536,
    Cloud           = "aws",
    Region          = "us-east-1"
    // IndexHost is resolved automatically after the index becomes ready
};

using var store = new PineconeStore(options);
// On first use the store creates the index (dotproduct metric) and polls up to
// 2 minutes (60 × 2 s) for it to become ready before accepting requests.

Hybrid Search

var hybridResults = await store.HybridSearchAsync(queryVector, "hello world", topK: 5);

SearchAsync remains pure dense retrieval. HybridSearchAsync sends both dense and sparse query components and lets Pinecone perform server-side fusion.

Metadata Filtering

// Store with metadata for logical isolation
await store.UpsertAsync(new VectorRecord
{
    Id = "doc-1",
    Content = "Some text",
    Vector = embedding,
    Metadata = { ["tenant"] = "tenant-1", ["category"] = "science" }
});

// Filter by metadata conditions
var filter = new VectorFilter()
    .Where("tenant", "tenant-1")
    .Where("category", "science");
var results = await store.SearchAsync(queryVector, topK: 5, filter: filter);

Supported filter operators

Important: Unsupported operators produce no error but filter nothing in search queries. Use GetAsync / GetBatchAsync when these operators are required.

VectorFilter

For the full operator reference and fluent API examples (Where, WhereNot, WhereIn, WhereLike, WhereExists, Or, And, WithMinScore, etc.), see the Mythosia.VectorDb.Abstractions README.

Pinecone-specific note: Like, Exists, and NotExists are silently ignored in SearchAsync / HybridSearchAsync. They are only evaluated client-side in GetAsync / GetBatchAsync.

Metadata Layout

Each stored vector uses reserved metadata keys:

Vector Replacement

ReplaceByFilterAsync is available via the IVectorStore default interface method. It performs sequential DeleteByFilterAsync → UpsertBatchAsync. Pinecone does not support server-side transactions, so sequential execution is the best available behavior:

var filter = new VectorFilter().Where("full_path", "/docs/file.md");
await store.ReplaceByFilterAsync(filter, newRecords);

Batch Get & Count

// Fetch multiple records by ID — single HTTP call to /vectors/fetch?ids=...
var records = await store.GetBatchAsync(new[] { "id-1", "id-2", "id-3" });

// Count total vectors in the configured namespace
long count = await store.CountAsync();

// Count with metadata filter (POSTs filter to describe_index_stats)
long filtered = await store.CountAsync(
    new VectorFilter().Where("category", "finance"));

GetBatchAsync issues a single GET /vectors/fetch?ids=id1&ids=id2&... request. CountAsync calls describe_index_stats; when a metadata filter is present, it is sent in a POST body for a server-side filtered count.

Connection Verification

Call VerifyConnectionAsync to test HTTP connectivity to the Pinecone index before running queries:

var store = new PineconeStore(new PineconeOptions
{
    IndexHost = "https://my-index-xxxx.svc.us-east1-gcp.pinecone.io",
    ApiKey = "YOUR_PINECONE_API_KEY"
});

try
{
    await store.VerifyConnectionAsync();
    Console.WriteLine("Connected!");
}
catch (Exception ex)
{
    Console.WriteLine($"Connection failed: {ex.Message}");
}

Resource Disposal

PineconeStore implements IDisposable. When created via the standard constructor, it owns the internal HttpClient and disposes it on Dispose():

using var store = new PineconeStore(options);
// HttpClient disposed automatically

When injecting a pre-configured HttpClient, the caller retains ownership and is responsible for disposal:

var httpClient = new HttpClient();
httpClient.BaseAddress = new Uri("https://my-index-xxxx.svc.us-east1-gcp.pinecone.io");

var store = new PineconeStore(options, httpClient);
// store.Dispose() will NOT dispose httpClient — caller must dispose it separately

API Key Note

Set your Pinecone API key securely (for example, environment variables or secret manager). Do not hardcode secrets in source code.

RAG retrieval capability boundary

This adapter keeps its native dense+sparse hybrid path on compatible dotproduct indexes. UseHybridSearch() with legacy default settings remains usable. The adapter does not implement ITextSearchStore or IConfigurableHybridSearchStore; keyword-only requests and custom mixed RRF settings fail explicitly rather than using dummy dense vectors or ignoring weights. UseVectorSearch() remains supported. Query-mode selection does not change dense+sparse document ingestion.