Mythosia.VectorDb.Pinecone 2.0.0

Mythosia.VectorDb.Pinecone

Pinecone vector store implementation for the Mythosia VectorDb abstraction layer.

Isolation model used by this package:

• Collection = Pinecone index (physical storage)
• Namespace = Pinecone namespace (1st-tier logical partition)
• Scope = metadata key _scope (2nd-tier logical partition)

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"
};

using var store = new PineconeStore(options);

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

var results = await store.InNamespace("documents")
    .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.InNamespace("documents")
    .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.

Scope & Metadata Filtering

await store.InNamespace("docs").InScope("tenant-1").UpsertAsync(record);

var results = await store.InNamespace("docs").InScope("tenant-1")
    .SearchAsync(queryVector, topK: 10);

var filter = new VectorFilter().Where("category", "science");
var filtered = await store.InNamespace("docs")
    .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.InNamespace("documents").ReplaceByFilterAsync(filter, newRecords);

Batch Get & Count

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

// Count total vectors in a namespace
long count = await store.InNamespace("documents").CountAsync();

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

GetBatchAsync issues a single GET /vectors/fetch?ids=id1&ids=id2&... request per namespace. 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.