C++

The ParticleDB C++ SDK is a header-only C++17 library wrapping libpq for PostgreSQL wire-protocol communication. It includes vector search, KV store, RAG, AI helpers, and a fully testable SQL builder with zero runtime dependencies.

Features

• Header-only — just add include/ to your include path
• Vector search — similarity search, index creation
• KV store — Redis-compatible key-value operations
• RAG — retrieval-augmented generation pipelines
• AI functions — embedding, generation, classification, summarization
• SQL builder — fully testable SQL generation with zero runtime dependencies

Requirements

• C++17 compiler (GCC 7+, Clang 5+, MSVC 2017+)
• libpq (PostgreSQL client library) — required only at link time for the Client class

Installation

Copy the include/particledb/ directory into your project’s include path, or use CMake:

add_subdirectory(path/to/particledb-sdk)
target_link_libraries(your_target particledb)

Quick Start

#include <particledb/particledb.hpp>

int main() {
    particledb::Config config;
    config.host = "localhost";
    config.port = 5432;

    particledb::Client client(config);
    client.connect();

    // Raw SQL
    auto result = client.query("SELECT * FROM users WHERE id = 1");

    // Vector search
    particledb::VectorOps vec(client);
    auto hits = vec.search("documents", "embedding", {0.1f, 0.2f, 0.3f}, 5);

    // KV
    particledb::KVOps kv(client);
    kv.set("session:123", "{\"user\":\"alice\"}");
    auto val = kv.get("session:123");

    client.close();
}

Compile and link:

g++ -std=c++17 -o myapp myapp.cpp $(pkg-config --cflags --libs libpq)

SQL Queries

particledb::Client client(config);
client.connect();

// Execute a query
auto result = client.query("SELECT name, price FROM products WHERE price > 50");

// Parameterized queries use libpq's PQexecParams under the hood
auto result2 = client.query(
    "SELECT name FROM products WHERE id = $1",
    {"42"}
);

Vector Search

particledb::VectorOps vec(client);

// Nearest-neighbor search
auto results = vec.search("documents", "embedding", {0.1f, 0.2f, 0.3f}, 5);

// Create an HNSW index
vec.create_index("documents", "embedding", "hnsw");

Key-Value Operations

particledb::KVOps kv(client);

// Set / Get
kv.set("user:1", "alice");
auto val = kv.get("user:1");

// Delete
kv.del("user:1");

Building Tests

The SQL builder tests have zero external dependencies (no libpq needed):

mkdir build && cd build
cmake ..
cmake --build .
ctest --output-on-failure

Next Steps

• SQL Reference — Full SQL syntax
• C SDK — Pure C client for embedded use
• PostgreSQL Wire Protocol — Protocol-level details