Java SDK

The ParticleDB Java SDK provides both a JDBC client (PG wire protocol) and a native gRPC client. It includes helpers for vector search, KV operations, RAG pipelines, and AI functions.

Requirements

• Java 11+
• Maven 3.6+

Installation

Maven

<dependency>
    <groupId>com.particledb</groupId>
    <artifactId>particledb-java-sdk</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle

implementation 'com.particledb:particledb-java-sdk:0.1.0'

Quick Start (JDBC)

import com.particledb.*;

// Connect using Config builder
Config config = Config.builder()
    .host("localhost")
    .port(5432)
    .user("particledb")
    .password("secret")
    .database("mydb")
    .build();

try (ParticleDB db = new ParticleDB(config)) {
    // SQL queries
    QueryResult result = db.query("SELECT * FROM users WHERE id = ?", 1);
    for (Row row : result.getRows()) {
        System.out.println(row.getString("name"));
    }

    // Transactions
    db.transaction(tx -> {
        tx.execute("INSERT INTO users (name) VALUES (?)", "Alice");
        tx.execute("INSERT INTO users (name) VALUES (?)", "Bob");
        return null;
    });
}

KV Operations

try (ParticleDB db = new ParticleDB(config)) {
    db.kv().set("session:123", "{\"user\":\"alice\"}");
    String val = db.kv().get("session:123");
    db.kv().delete("session:123");
    db.kv().incr("counter", 1);
    boolean exists = db.kv().exists("counter");
}

Vector Search

try (ParticleDB db = new ParticleDB(config)) {
    // Create an index
    db.vector().createIndex("documents", "embedding", "hnsw",
        Map.of("m", 16, "ef_construction", 200));

    // Search
    float[] query = {0.1f, 0.2f, 0.3f};
    QueryResult results = db.vector().search("documents", "embedding", query, 5, null);
}

RAG Queries

try (ParticleDB db = new ParticleDB(config)) {
    String answer = db.rag().query("What is ParticleDB?",
        "documents", "embedding", "content", 5);

    db.rag().createPipeline("docs", "documents", "embedding", "content", 5, "simple");
}

AI Functions

try (ParticleDB db = new ParticleDB(config)) {
    Row embedding = db.ai().embed("Hello world", null);
    String text = db.ai().generate("Explain vector databases");
    String label = db.ai().classify("Great!", List.of("positive", "negative"));
    String summary = db.ai().summarize("Long article text...");
}

gRPC Client

The SDK includes a gRPC client (io.particledb.sdk.GrpcClient) for direct access to the ParticleDB gRPC API. Recommended for high-throughput or streaming workloads.

Execute SQL

import io.particledb.sdk.GrpcClient;
import com.particledb.v1.ExecuteSqlResponse;
import com.particledb.v1.Row;
import com.particledb.v1.Value;

try (GrpcClient client = new GrpcClient("localhost", 9090)) {
    ExecuteSqlResponse response = client.executeSQL("SELECT * FROM users");

    if (!response.getError().isEmpty()) {
        System.err.println("Error: " + response.getError());
    }

    // Iterate over rows
    for (Row row : response.getRowsList()) {
        for (Value val : row.getValuesList()) {
            switch (val.getKindCase()) {
                case INT_VALUE:    System.out.print(val.getIntValue()); break;
                case FLOAT_VALUE:  System.out.print(val.getFloatValue()); break;
                case STRING_VALUE: System.out.print(val.getStringValue()); break;
                case BOOL_VALUE:   System.out.print(val.getBoolValue()); break;
                case NULL_VALUE:   System.out.print("NULL"); break;
                default:           System.out.print(val); break;
            }
            System.out.print("\t");
        }
        System.out.println();
    }
}

Batch Execute

try (GrpcClient client = new GrpcClient("localhost", 9090)) {
    BatchExecuteResponse batch = client.batchExecute(List.of(
        "CREATE TABLE events (id INT PRIMARY KEY, name TEXT)",
        "INSERT INTO events VALUES (1, 'click')",
        "INSERT INTO events VALUES (2, 'view')",
        "SELECT * FROM events"
    ));

    for (ExecuteSqlResponse result : batch.getResultsList()) {
        System.out.println("Rows affected: " + result.getRowsAffected()
            + ", rows returned: " + result.getRowsCount());
    }
}

Streaming Query

try (GrpcClient client = new GrpcClient("localhost", 9090)) {
    Iterator<QueryResponse> stream = client.streamQuery(
        "SELECT * FROM large_table");

    while (stream.hasNext()) {
        QueryResponse chunk = stream.next();
        System.out.println("Received " + chunk.getResultSet().getRowsCount()
            + " rows");
    }
}

Health Check

try (GrpcClient client = new GrpcClient("localhost", 9090)) {
    HealthResponse health = client.health();
    System.out.println("Status: " + health.getStatus());
    System.out.println("Version: " + health.getVersion());
}

Custom Channel Configuration

import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

ManagedChannel channel = ManagedChannelBuilder.forAddress("particledb.example.com", 443)
    .useTransportSecurity()
    .maxInboundMessageSize(64 * 1024 * 1024)
    .build();

try (GrpcClient client = new GrpcClient(channel)) {
    // Use client with custom TLS, interceptors, etc.
}

Building

cd sdk/java
mvn clean compile

The protobuf-maven-plugin automatically generates Java stubs from the proto files during the compile phase.

Next Steps

• SQL Reference — Full SQL syntax
• gRPC Connectivity — gRPC protocol details
• PostgreSQL Wire Protocol — PG wire protocol details