Go SDK

The ParticleDB Go SDK provides both a PostgreSQL wire-protocol client (backed by lib/pq or pgx) and a native gRPC client. It includes helpers for vector search, KV operations, RAG pipelines, and AI functions.

Installation

go get github.com/particledb/particledb-go

Quick Start (PG Wire)

package main

import (
    "fmt"
    "log"

    particledb "github.com/particledb/particledb-go"
    _ "github.com/lib/pq" // PostgreSQL driver
)

func main() {
    // Connect with default config (localhost:5432)
    client, err := particledb.New(particledb.DefaultConfig())
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // Run a query
    result, err := client.Query("SELECT * FROM users WHERE id = $1", 42)
    if err != nil {
        log.Fatal(err)
    }
    for _, row := range result.Rows {
        fmt.Println(row)
    }
}

Configuration

cfg := particledb.Config{
    Host:     "db.example.com",
    Port:     5433,
    User:     "admin",
    Password: "secret",
    Database: "mydb",
    PoolSize: 20,
    SSLMode:  "require",
}
client, err := particledb.New(cfg)

Or connect with a DSN string:

client, err := particledb.Connect("host=localhost port=5432 user=particledb dbname=particledb sslmode=disable")

Transactions

err := client.Transaction(func(tx *particledb.Tx) error {
    _, err := tx.Execute("INSERT INTO users (name) VALUES ($1)", "alice")
    if err != nil {
        return err // triggers rollback
    }
    _, err = tx.Execute("UPDATE counters SET val = val + 1 WHERE name = $1", "users")
    return err // nil = commit
})

Set-Membership: EXISTS / SEMI / ANTI / ASOF

// Customers who placed at least one order — WHERE EXISTS is rewritten by
// the optimizer to LEFT SEMI JOIN, so this runs in a single pass.
active, _ := client.Query(`
    SELECT id, name FROM customers c
    WHERE EXISTS (SELECT 1 FROM orders o WHERE o.customer_id = c.id)
`)

// Equivalent explicit form — same plan:
active, _ = client.Query(`
    SELECT c.id, c.name FROM customers c
    LEFT SEMI JOIN orders o ON o.customer_id = c.id
`)

// Customers with NO orders (NOT EXISTS → LEFT ANTI JOIN):
inactive, _ := client.Query(`
    SELECT c.id, c.name FROM customers c
    LEFT ANTI JOIN orders o ON o.customer_id = c.id
`)

// Time-series: pair each trade with the most recent prior price per symbol:
enriched, _ := client.Query(`
    SELECT t.symbol, t.ts, t.qty, p.price
    FROM trades t
    ASOF JOIN prices p
      MATCH_CONDITION(p.ts <= t.ts)
      ON t.symbol = p.symbol
`)

Vector Search

// ANN search
results, err := client.Vector().Search("documents", "embedding",
    []float32{0.1, 0.2, 0.3},
    &particledb.VectorSearchOptions{K: 5},
)

// Insert with vector
err = client.Vector().Insert("documents",
    map[string]interface{}{"title": "My Doc", "content": "..."},
    "embedding", []float32{0.1, 0.2, 0.3},
)

// Create HNSW index
err = client.Vector().CreateIndex("documents", "embedding", "hnsw",
    map[string]interface{}{"m": "24", "ef_construction": "200"},
)

Key-Value Operations

kv := client.KV()

// Set / Get
kv.Set("user:1", "alice")
val, _ := kv.Get("user:1") // "alice"

// Set with TTL (seconds)
kv.SetWithTTL("session:abc", "data", 3600)

// Batch operations
kv.MSet(map[string]string{"a": "1", "b": "2"})
results, _ := kv.MGet([]string{"a", "b"})

// Atomic increment
newVal, _ := kv.Incr("counter", 1)

// Check existence
exists, _ := kv.Exists("user:1")

// Delete
deleted, _ := kv.Delete("user:1")

RAG (Retrieval-Augmented Generation)

rag := client.RAG()

// Create a pipeline
rag.CreatePipeline("qa", "documents", "embedding", "content", 5, "hybrid")

// Query using pipeline
answer, _ := rag.Query("What is ParticleDB?", "qa")

// Query with explicit options
answer, _ = rag.QueryWithOptions("What is ParticleDB?",
    "documents", "embedding", "content", 5,
)

AI Functions

ai := client.AI()

// Generate embeddings
embedding, _ := ai.Embed("Hello world", "text-embedding-ada-002")

// Batch embeddings
embeddings, _ := ai.EmbedBatch([]string{"Hello", "World"}, "text-embedding-ada-002")

// Text generation
result, _ := ai.Generate("Explain quantum computing", "gpt-4")

// Classification
label, _ := ai.Classify("I love this product!", []string{"positive", "negative", "neutral"})

// Summarization
summary, _ := ai.Summarize("Long text to summarize...")

gRPC Client

The SDK includes a native gRPC client that connects to the ParticleDB gRPC endpoint (default port 26257). Against the stock server, the ParticleDB service methods (ExecuteSQL, BatchExecute, Health) are the stable path documented in this site.

Connecting

package main

import (
    "context"
    "fmt"
    "log"

    particledb "github.com/particledb/particledb-go"
)

func main() {
    client, err := particledb.NewGRPCClient("localhost", particledb.DefaultGRPCPort)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    ctx := context.Background()

    health, err := client.Health(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("status=%s version=%s\n", health.Status, health.Version)
}

ExecuteSQL

// DDL
resp, err := client.ExecuteSQL(ctx, "CREATE TABLE users (id INT PRIMARY KEY, name TEXT)")

// INSERT with parameters
resp, err = client.ExecuteSQL(ctx,
    "INSERT INTO users (id, name) VALUES ($1, $2)",
    particledb.IntValue(1),
    particledb.StringValue("alice"),
)
fmt.Println("rows affected:", resp.RowsAffected)

// SELECT
resp, err = client.ExecuteSQL(ctx, "SELECT id, name FROM users")
rows := particledb.ResultToMaps(resp)

StreamQuery

The SDK also contains QueryService helpers such as StreamQuery, but those target a broader gRPC surface than the stock server binary documented in this site. Use them only if your deployment explicitly exposes that service.

results, errCh := client.StreamQuery(ctx, "SELECT * FROM large_table")
for resp := range results {
    fmt.Println("batch:", len(resp.ResultSet.Rows), "rows")
}
if err := <-errCh; err != nil {
    log.Fatal(err)
}

BatchExecute

resp, err := client.BatchExecute(ctx, []string{
    "INSERT INTO users (id, name) VALUES (1, 'alice')",
    "INSERT INTO users (id, name) VALUES (2, 'bob')",
    "UPDATE users SET name = 'charlie' WHERE id = 1",
})
for i, result := range resp.Results {
    fmt.Printf("statement %d: affected=%d error=%q\n",
        i, result.RowsAffected, result.Error)
}

Connection Options

import "time"

client, err := particledb.NewGRPCClient("db.example.com", 26257,
    particledb.WithConnectTimeout(5 * time.Second),
    particledb.WithDialOptions(
        // add TLS, interceptors, etc.
    ),
)

Requirements

• Go 1.21+
• PG wire client: A PostgreSQL-compatible driver (e.g., github.com/lib/pq or github.com/jackc/pgx/v5/stdlib)
• gRPC client: google.golang.org/grpc (pulled in automatically via go mod tidy)

Next Steps

• SQL Reference — Full SQL syntax
• Vector Search — Vector search SQL syntax
• gRPC Connectivity — gRPC protocol details