Skip to main content
OnDB uses client.store() for all write operations and client.queryBuilder() for all read operations.

​
Append-Only Storage

OnDB uses an append-only storage model — updates append new versions instead of modifying existing records, and deletes are soft deletes. See Immutability for the full details.

​
Available Methods

MethodDescription
store()Store documents (create, update, or delete) with USDC payment
queryBuilder().execute()Query multiple documents with filters
queryBuilder().executeUnique()Find the latest version of a single document
queryBuilder().count()Count matching documents
sql()Execute SQL queries against collections

​
Quick Example

import { createClient } from '@ondb/sdk';

const client = createClient({
  endpoint: 'https://api.ondb.io',
  appId: 'my-app',
  appKey: 'your-app-key'
});

// Create
const result = await client.store(
  { collection: 'users', data: [{ email: 'alice@example.com', name: 'Alice', active: true }] },
  async (quote) => {
    const txHash = await processPayment(quote);
    return { txHash, network: quote.network, sender: walletAddress, chainType: quote.chainType, paymentMethod: 'native' };
  },
  true
);

// Read (single)
const found = await client.queryBuilder()
  .collection('users')
  .whereField('email').equals('alice@example.com')
  .executeUnique();
console.log('Found:', found?.name);

// Read (many)
const activeUsers = await client.queryBuilder()
  .collection('users')
  .whereField('active').isTrue()
  .orderBy('createdAt', 'DESC')
  .limit(10)
  .execute();

// Update (append new version with same data + changes)
if (found) {
  await client.store(
    { collection: 'users', data: [{ ...found, name: 'Alice Smith' }] },
    paymentCallback,
    true
  );
}

// Soft Delete (append record with deleted flag)
if (found) {
  await client.store(
    { collection: 'users', data: [{ ...found, deleted: true, deletedAt: new Date().toISOString() }] },
    paymentCallback,
    true
  );
}

​
Payment Proof Structure

All write operations require a payment callback: 
await client.store(
  { collection: 'users', data: [...] },
  async (quote) => {
    // quote contains: totalCost, brokerAddress, tokenSymbol, network, chainType
    const txHash = await processPayment(quote);
    return { txHash, network: quote.network, sender: walletAddress, chainType: quote.chainType, paymentMethod: 'native' };
  },
  true // waitForConfirmation
);

​
Next Steps

Create

Create new documents

Read

Find and query documents

Update

Update existing documents

Delete

Soft delete documents