C# / .NET SDK

The ParticleDB C# SDK wraps Npgsql to provide typed access to ParticleDB’s SQL engine, vector search, KV store, RAG pipelines, and AI functions over the PG wire protocol.

Requirements

• .NET 6.0 or later
• A running ParticleDB instance

Installation

dotnet add package ParticleDB.Client

Quick Start

using ParticleDB.Client;

// Connect with config
var config = new ParticleDBConfig
{
    Host = "localhost",
    Port = 5432,
    User = "particledb",
    Database = "particledb"
};
await using var db = new ParticleDBClient(config);

// Or connect with a connection string
await using var db2 = new ParticleDBClient(
    "Host=localhost;Port=5432;Username=particledb;Database=particledb");

// SQL queries
var result = await db.QueryAsync("SELECT * FROM users WHERE id = $1", 42);
foreach (var row in result.Rows)
    Console.WriteLine(row["name"]);

// Single row
var user = await db.QueryOneAsync("SELECT * FROM users WHERE id = $1", 1);

// Execute (INSERT/UPDATE/DELETE)
var affected = await db.ExecuteAsync(
    "INSERT INTO users (name, age) VALUES ($1, $2)", "Alice", 30);

// Transactions
var count = await db.TransactionAsync(async tx =>
{
    await tx.ExecuteAsync("INSERT INTO users (name) VALUES ($1)", "Bob");
    var result = await tx.QueryAsync("SELECT COUNT(*) AS cnt FROM users");
    return Convert.ToInt64(result.Rows[0]["cnt"]);
});

Vector Search

// Search for nearest neighbors
var results = await db.Vector.SearchAsync(
    "documents", "embedding",
    new float[] { 0.1f, 0.2f, 0.3f },
    k: 5,
    filter: "category = 'science'");

foreach (var (row, distance) in results)
    Console.WriteLine($"{row["title"]}: {distance}");

// Create a vector index
await db.Vector.CreateIndexAsync("documents", "embedding", "hnsw");

Key-Value Store

// Set / Get
await db.KV.SetAsync("session:123", "{\"user\":\"alice\"}");
var val = await db.KV.GetAsync("session:123");

// Multiple keys
await db.KV.MSetAsync(new Dictionary<string, string>
{
    { "k1", "v1" },
    { "k2", "v2" }
});
var vals = await db.KV.MGetAsync(new[] { "k1", "k2" });

// Increment, TTL, Exists
await db.KV.IncrAsync("counter", 5);
await db.KV.ExpireAsync("session:123", 3600);
var exists = await db.KV.ExistsAsync("session:123");
var keys = await db.KV.KeysAsync("session:*");

RAG (Retrieval-Augmented Generation)

// Direct query
var answer = await db.RAG.QueryAsync(
    "What is ParticleDB?", "documents", "embedding", "content", k: 5);

// Create a named pipeline
await db.RAG.CreatePipelineAsync(
    "docs_pipeline", "documents", "embedding", "content",
    k: 5, mode: "hybrid");

AI Functions

var embedding = await db.AI.EmbedAsync("Hello world");
var text = await db.AI.GenerateAsync("Explain vector databases");
var label = await db.AI.ClassifyAsync("Great product!",
    new[] { "positive", "negative", "neutral" });
var summary = await db.AI.SummarizeAsync(longArticle);

Architecture

All SQL generation is centralized in the SqlBuilder static class, which produces raw SQL strings with no I/O dependencies. This makes the SQL layer fully unit-testable without a database connection. The VectorOps, KVOps, RAGOps, and AIOps classes are thin async wrappers that combine SqlBuilder output with ParticleDBClient query execution.

Next Steps

• SQL Reference — Full SQL syntax
• PostgreSQL Wire Protocol — Protocol-level details