Dart / Flutter

The ParticleDB Dart SDK provides SQL queries, key-value operations, vector search, and RAG over the REST API using the http package. Works with both Flutter and server-side Dart. Requires Dart SDK 3.0+.

Installation

Add to your pubspec.yaml:

dependencies:
  particledb: ^0.1.0

Then run:

dart pub get
# or
flutter pub get

Quick Start

import 'package:particledb/particledb.dart';

void main() async {
  final db = ParticleDB(host: 'localhost', port: 8080);

  // Query
  final rows = await db.query(
    r'SELECT id, name FROM users WHERE id = $1',
    params: [1],
  );
  for (final row in rows) {
    print(row['name']);
  }

  // Execute DML
  final affected = await db.execute(
    r'INSERT INTO users (id, name) VALUES ($1, $2)',
    params: [2, 'Alice'],
  );
  print('Inserted $affected row(s)');

  // Single row
  final user = await db.queryOne(
    r'SELECT * FROM users WHERE id = $1',
    params: [42],
  );
  if (user != null) print(user['name']);

  db.close();
}

Connection Configuration

final db = 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: const Duration(seconds: 30),     // HTTP timeout (default: 30s)
);

SQL Queries

// SELECT -- returns List<Map<String, dynamic>>
final rows = await db.query(
  r'SELECT * FROM products WHERE price > $1',
  params: [9.99],
);

// Full result with metadata
final result = await db.queryResult('SELECT COUNT(*) AS cnt FROM users');
print('Columns: ${result.columns}, Count: ${result.rowCount}');

// INSERT / UPDATE / DELETE -- returns affected row count
final count = await db.execute(
  r'UPDATE products SET price = $1 WHERE id = $2',
  params: [19.99, 1],
);

// Single row lookup (returns Map or null)
final product = await db.queryOne(
  r'SELECT * FROM products WHERE id = $1',
  params: [1],
);

Key-Value Operations

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

final value = await db.kv.get('session:123');
final deleted = await db.kv.delete('session:123');

// Batch operations
await db.kv.mset({'k1': 'v1', 'k2': 'v2'});
final values = await db.kv.mget(['k1', 'k2']);

// Atomic increment
final newVal = await db.kv.incr('counter', amount: 5);

// Check existence / TTL
final exists = await db.kv.exists('session:123');
final ttl = await db.kv.ttl('temp:key');

// List keys
final keys = await db.kv.keys('session:*');

Vector Search

// Search for nearest neighbors
final results = await db.vector.search(
  table: 'documents',
  column: 'embedding',
  queryVector: [0.1, 0.2, 0.3],
  k: 5,
);
for (final r in results) {
  print('${r.row['title']} -- distance: ${r.distance}');
}

// Search with filter
final filtered = await db.vector.search(
  table: 'documents',
  column: 'embedding',
  queryVector: [0.1, 0.2, 0.3],
  k: 10,
  filter: "category = 'science'",
);

// Insert a vector
await db.vector.insert(
  table: 'documents',
  data: {'id': 1, 'title': 'My Doc'},
  vectorColumn: 'embedding',
  vector: [0.1, 0.2, 0.3],
);

// Create a vector index
await db.vector.createIndex(
  table: 'documents',
  column: 'embedding',
  indexType: 'hnsw',
  params: {'m': 16},
);

RAG (Retrieval-Augmented Generation)

// Create a pipeline
await db.rag.createPipeline(
  name: 'qa',
  table: 'documents',
  vectorCol: 'embedding',
  textCol: 'content',
  k: 5,
  mode: 'hybrid',
);

// Query using a pipeline
final answer = await db.rag.query('What is ParticleDB?', pipeline: 'qa');
print(answer);

// Query without a pipeline (inline config)
final answer2 = await db.rag.query(
  'What is ParticleDB?',
  table: 'documents',
  vectorCol: 'embedding',
  textCol: 'content',
  k: 5,
);

// Ingest a document
await db.rag.ingest(
  table: 'documents',
  content: 'ParticleDB is a fast database.',
  embedding: [0.1, 0.2, 0.3],
  metadata: {'source': 'docs', 'page': 1},
);

Error Handling

try {
  await db.query('SELECT * FROM nonexistent_table');
} on ParticleDBException catch (e) {
  print('Error: ${e.message}');
  print('Code: ${e.code}');
  print('HTTP Status: ${e.httpStatus}');
}

Flutter Usage

The SDK works identically in Flutter. Just add the dependency and import:

import 'package:particledb/particledb.dart';

class MyWidget extends StatelessWidget {
  final db = ParticleDB(host: '10.0.2.2', port: 8080);  // Android emulator

  Future<List<Map<String, dynamic>>> loadUsers() async {
    return await db.query('SELECT * FROM users');
  }
}

For Android, ensure your AndroidManifest.xml allows cleartext HTTP traffic if not using HTTPS:

<application android:usesCleartextTraffic="true" ...>

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
• Vector Search — Vector search SQL syntax
• HTTP API — REST API reference