Ruby

The ParticleDB Ruby SDK provides SQL queries, key-value operations, vector search, and RAG through the HTTP REST API. Uses Ruby stdlib only (net/http, json, uri) — no external gems required.

Installation

Add to your Gemfile:

gem "particledb", path: "sdk/ruby"

Or install from the gemspec:

cd sdk/ruby
gem build particledb.gemspec
gem install particledb-0.1.0.gem

Quick Start

require "particledb"

# Connect to a local ParticleDB instance (HTTP API on port 8080)
client = ParticleDB.connect(host: "localhost", port: 8080)

# Run a query
rows = client.query("SELECT name, price FROM products WHERE price > $1", [50])
rows.each { |row| puts "#{row['name']}: #{row['price']}" }

# Execute DML
affected = client.execute(
  "INSERT INTO products (id, name, price) VALUES ($1, $2, $3)",
  [1, "Keyboard", 89.99]
)
puts "Rows affected: #{affected}"

Configuration

client = ParticleDB::Client.new(
  host:     "db.example.com",
  port:     8080,
  user:     "admin",
  password: "secret",
  database: "mydb"
)

When user and password are both provided, the client sends HTTP Basic auth headers with every request.

SQL Queries

# SELECT -- returns array of hashes
rows = client.query("SELECT * FROM users WHERE age > $1", [21])
rows.each do |row|
  puts row["name"]
end

# Full result with metadata
result = client.query_result("SELECT COUNT(*) AS total FROM users")
puts "#{result.row_count} rows in #{result.elapsed_ms}ms"

# Execute DML -- returns rows affected
affected = client.execute("DELETE FROM users WHERE id = $1", [42])

Key-Value Operations

kv = client.kv

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

# Set with TTL (seconds)
kv.set_with_ttl("session:abc", "data", 3600)

# Delete
kv.delete("user:1")

# Batch operations
kv.mset("a" => "1", "b" => "2")
results = kv.mget(["a", "b"])  # => {"a" => "1", "b" => nil}

# Atomic increment
new_val = kv.incr("counter", 5)

# Check existence
kv.exists?("user:1")  # => true / false

# TTL
kv.ttl("session:abc")  # => 3542

# List keys by pattern
kv.keys("user:*")  # => ["user:1", "user:2"]

Vector Search

vec = client.vector

# ANN search
results = vec.search("documents", "embedding", [0.1, 0.2, 0.3],
                      k: 5, columns: ["id", "title"])
results.each do |r|
  puts "#{r[:row]['title']} (distance: #{r[:distance]})"
end

# Insert a row with a vector column
vec.insert("documents",
  { "id" => 1, "title" => "My Doc" },
  "embedding", [0.1, 0.2, 0.3])

# Create an HNSW index
vec.create_index("documents", "embedding", "hnsw",
                  m: 24, ef_construction: 200)

# Search with a filter
results = vec.search("documents", "embedding", [0.1, 0.2, 0.3],
                      k: 10, filter: "category = 'science'")

RAG (Retrieval-Augmented Generation)

rag = client.rag

# Create a pipeline
rag.create_pipeline("qa",
  table: "documents", vector_col: "embedding",
  text_col: "content", k: 5, mode: "hybrid")

# Query using a named pipeline
answer = rag.query("What is ParticleDB?", pipeline: "qa")
puts answer

# Query with explicit options (no pipeline)
answer = rag.query_with_options("What is ParticleDB?",
  table: "documents", vector_col: "embedding",
  text_col: "content", k: 5)

Table Introspection

# List all tables
tables = client.tables
tables.each { |t| puts "#{t['name']}: #{t['row_count']} rows" }

# Get table schema
schema = client.table("products")
schema["columns"].each do |col|
  puts "#{col['name']} #{col['type']} (pk: #{col['primary_key']})"
end

Health Check

health = client.health
puts health["status"]   # => "ok"
puts health["version"]  # => "0.1.0"

Error Handling

begin
  client.query("SELECT * FROM nonexistent_table")
rescue ParticleDB::Error => e
  puts e.message  # => "Table 'nonexistent_table' does not exist"
  puts e.code     # => "42P01"
  puts e.status   # => 404
end

Requirements

• Ruby 2.7+
• ParticleDB server running with the HTTP API enabled (port 8080 by default)

Next Steps

• SQL Reference — Full SQL syntax
• Vector Search — Vector search SQL syntax
• HTTP API — REST API reference