PHP

The ParticleDB PHP SDK provides SQL queries, key-value operations, vector search, and RAG over the REST API. No external dependencies — uses cURL for HTTP. Requires PHP 7.4+.

Installation

Via Composer

composer require particledb/particledb-php

Manual

Copy the src/ directory into your project and register the ParticleDB\ namespace with your autoloader, or require the files directly:

require_once 'path/to/sdk/php/src/ParticleDB.php';
require_once 'path/to/sdk/php/src/KV.php';
require_once 'path/to/sdk/php/src/Vector.php';
require_once 'path/to/sdk/php/src/RAG.php';

Quick Start

use ParticleDB\ParticleDB;

$db = new ParticleDB([
    'host' => 'localhost',
    'port' => 8080,
]);

// Query
$result = $db->query('SELECT id, name FROM users WHERE id = ?', [1]);
foreach ($result['rows'] as $row) {
    echo $row['name'] . "\n";
}

// Execute DML
$affected = $db->execute('INSERT INTO users (id, name) VALUES (?, ?)', [2, 'Alice']);
echo "Inserted {$affected} row(s)\n";

// Single row
$user = $db->queryOne('SELECT * FROM users WHERE id = ?', [42]);
if ($user) {
    echo $user['name'];
}

Connection Configuration

$db = new ParticleDB([
    '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)
    'timeout'  => 30,            // HTTP timeout in seconds (default: 30)
]);

SQL Queries

// SELECT -- returns ['rows' => [...], 'row_count' => int, 'columns' => [...]]
$result = $db->query('SELECT * FROM products WHERE price > ?', [9.99]);

// INSERT / UPDATE / DELETE -- returns affected row count
$count = $db->execute('UPDATE products SET price = ? WHERE id = ?', [19.99, 1]);

// Single row lookup (returns assoc array or null)
$product = $db->queryOne('SELECT * FROM products WHERE id = ?', [1]);

Key-Value Operations

$kv = $db->kv();

// Set / Get / Delete
$kv->set('session:abc', '{"user":"alice"}');
$kv->set('temp:key', 'value', 3600);  // with 60-minute TTL
$val = $kv->get('session:abc');        // string or null
$kv->delete('session:abc');

// Batch operations
$kv->mset(['k1' => 'v1', 'k2' => 'v2']);
$values = $kv->mget(['k1', 'k2']);     // ['v1', 'v2']

// Atomic increment
$newVal = $kv->incr('counter', 5);

// Utilities
$exists = $kv->exists('session:abc');  // bool
$ttl    = $kv->ttl('temp:key');        // int seconds or null
$keys   = $kv->keys('session:*');      // string[]

Vector Search

$vec = $db->vector();

// Similarity search
$results = $vec->search('documents', 'embedding', [0.1, 0.2, 0.3], [
    'k'      => 5,
    'filter' => "category = 'science'",
]);
foreach ($results as $r) {
    echo $r['row']['title'] . ' (distance: ' . $r['distance'] . ")\n";
}

// Insert a vector row
$vec->insert('documents', ['title' => 'My Doc'], 'embedding', [0.1, 0.2, 0.3]);

// Create a vector index
$vec->createIndex('documents', 'embedding', 'hnsw', [
    'm'               => 16,
    'ef_construction'  => 200,
]);

RAG (Retrieval-Augmented Generation)

$rag = $db->rag();

// Query using a named pipeline
$answer = $rag->query('What is ParticleDB?', ['pipeline' => 'docs_pipeline']);
echo $answer;

// Query with inline table config
$answer = $rag->query('What is ParticleDB?', [
    'table'     => 'documents',
    'vectorCol' => 'embedding',
    'textCol'   => 'content',
    'k'         => 5,
]);

// Ingest a document
$rag->ingest('documents', 'ParticleDB is a fast analytical database.', [0.1, 0.2, 0.3]);

// Ingest with metadata
$rag->ingest('documents', 'ParticleDB supports vector search.', $embedding,
    'embedding', 'content', ['source' => 'docs', 'page' => 42]);

// Create a reusable pipeline
$rag->createPipeline('docs_pipeline', [
    'table'     => 'documents',
    'vectorCol' => 'embedding',
    'textCol'   => 'content',
    'k'         => 5,
    'mode'      => 'simple',
]);

Error Handling

use ParticleDB\ParticleDBException;

try {
    $db->query('SELECT * FROM nonexistent_table');
} catch (ParticleDBException $e) {
    echo 'Error: ' . $e->getMessage() . "\n";
}

Requirements

• PHP 7.4 or later
• ext-curl (cURL extension)
• ext-json (JSON extension, typically bundled)

Next Steps

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