Kotlin / Android

The ParticleDB Kotlin SDK provides SQL queries, key-value operations, vector search, and RAG over the REST API using OkHttp for HTTP and kotlinx.serialization for JSON. Requires JDK 17+.

Installation

// Gradle (Kotlin DSL)
dependencies {
    implementation("io.particledb:particledb-kotlin:0.1.0")
}

// Gradle (Groovy)
implementation 'io.particledb:particledb-kotlin:0.1.0'

Quick Start

import io.particledb.ParticleDB
import io.particledb.Config

val db = ParticleDB(Config(host = "localhost", port = 8080))

// Query
val rows = db.query("SELECT id, name FROM users WHERE id = \$1", listOf(1))
rows.forEach { println(it["name"]) }

// Execute DML
val affected = db.execute(
    "INSERT INTO users (id, name) VALUES (\$1, \$2)",
    listOf(2, "Alice")
)
println("Inserted $affected row(s)")

// Single row
val user = db.queryOne("SELECT * FROM users WHERE id = \$1", listOf(42))
println(user?.get("name"))

db.close()

Connection Configuration

val db = ParticleDB(Config(
    host = "localhost",       // Server hostname (default: "localhost")
    port = 8080,              // HTTP REST API port (default: 8080)
    user = "myuser",          // Username for auth (default: null)
    password = "secret",      // Password for auth (default: null)
    database = "mydb",        // Database name (default: null)
    timeoutSeconds = 30       // HTTP timeout in seconds (default: 30)
))

SQL Queries

// SELECT -- returns List<Map<String, Any?>>
val rows = db.query("SELECT * FROM products WHERE price > \$1", listOf(9.99))

// Full result with metadata
val result = db.queryResult("SELECT COUNT(*) AS cnt FROM users")
println("Columns: ${result.columns}, Count: ${result.rowCount}")

// INSERT / UPDATE / DELETE -- returns affected row count
val count = db.execute("UPDATE products SET price = \$1 WHERE id = \$2", listOf(19.99, 1))

// Single row lookup (returns Map or null)
val product = db.queryOne("SELECT * FROM products WHERE id = \$1", listOf(1))

Key-Value Operations

// Set / Get / Delete
db.kv.set("session:123", """{"user":"alice"}""")
db.kv.set("temp:key", "value", ttl = 3600)  // TTL in seconds

val value = db.kv.get("session:123")
db.kv.delete("session:123")

// Batch operations
db.kv.mset(mapOf("k1" to "v1", "k2" to "v2"))
val values = db.kv.mget(listOf("k1", "k2"))

// Atomic increment
val newVal = db.kv.incr("counter", 5)

// Check existence / TTL
val exists = db.kv.exists("session:123")
val ttl = db.kv.ttl("temp:key")

// List keys
val keys = db.kv.keys("session:*")

Vector Search

// Search for nearest neighbors
val results = db.vector.search(
    table = "documents",
    column = "embedding",
    queryVector = listOf(0.1, 0.2, 0.3),
    k = 5
)
results.forEach { r ->
    println("${r["row"]} -- distance: ${r["distance"]}")
}

// Search with filter
val filtered = db.vector.search(
    table = "documents",
    column = "embedding",
    queryVector = listOf(0.1, 0.2, 0.3),
    k = 10,
    filter = "category = 'science'"
)

// Insert a vector
db.vector.insert(
    table = "documents",
    data = mapOf("id" to 1, "title" to "My Doc"),
    vectorColumn = "embedding",
    vector = listOf(0.1, 0.2, 0.3)
)

// Create a vector index
db.vector.createIndex("documents", "embedding", "hnsw", mapOf("m" to 16))

RAG (Retrieval-Augmented Generation)

// Create a pipeline
db.rag.createPipeline(
    name = "qa",
    table = "documents",
    vectorCol = "embedding",
    textCol = "content",
    k = 5,
    mode = "hybrid"
)

// Query using a pipeline
val answer = db.rag.query("What is ParticleDB?", pipeline = "qa")
println(answer)

// Query without a pipeline (inline config)
val answer2 = db.rag.query(
    question = "What is ParticleDB?",
    table = "documents",
    vectorCol = "embedding",
    textCol = "content",
    k = 5
)

// Ingest a document
db.rag.ingest(
    table = "documents",
    content = "ParticleDB is a fast database.",
    embedding = listOf(0.1, 0.2, 0.3),
    metadata = mapOf("source" to "docs", "page" to 1)
)

Error Handling

try {
    db.query("SELECT * FROM nonexistent_table")
} catch (e: ParticleDBException) {
    println("Error: ${e.message}")
    println("Code: ${e.code}")
    println("HTTP Status: ${e.httpStatus}")
}

API Reference

ParticleDB

Method	Description
query(sql, params)	Execute SQL, return rows as List<Map>
queryResult(sql, params)	Execute SQL, return QueryResult with metadata
queryOne(sql, params)	Execute SQL, return first row or null
execute(sql, params)	Execute DML/DDL, return affected row count
health()	Server health check
tables()	List all tables
kv	Access KV operations
vector	Access vector search operations
rag	Access RAG operations
close()	Release resources

Next Steps

• SQL Reference — Full SQL syntax
• Java SDK — Java SDK (also works from Kotlin via JDBC)