Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ondb.ai/llms.txt

Use this file to discover all available pages before exploring further.

OnDB uses collections to organize data, similar to tables in traditional databases. Indexes are required for production use.

​
Collections

Collections are logical groupings of documents: 
import { createClient } from '@ondb/sdk';

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

// Create collection with schema-based indexes
await client.createCollection({
  name: 'users',
  fields: {
    email: { type: 'string', index: true, unique: true },
    createdAt: { type: 'date', index: true }
  },
  useBaseFields: true
});

​
Why Indexes Are Required

Every collection MUST have at least one index for production use.
Without indexes:
IssueImpact
Slow queriesAll reads perform full collection scans, resulting in poor performance
Dashboard invisibleThe OnDB dashboard discovers collections through index configurations - collections without indexes will not appear
Unoptimized costsFull scans consume more resources and may cost more

​
Index Types

​
Hash Index

Best for equality lookups (e.g., WHERE email = 'user@example.com'): 
await db.createIndex({
  name: 'idx_users_email',
  collection: 'users',
  field_name: 'email',
  index_type: 'hash',
  unique_constraint: true,
  store_values: true
});

​
BTree Index

Best for range queries and sorting (e.g., WHERE createdAt > '2024-01-01'): 
await db.createIndex({
  name: 'idx_users_createdAt',
  collection: 'users',
  field_name: 'createdAt',
  index_type: 'btree'
});

​
Price Index

Special type for value-based payment models. See PriceIndex for details. 
await db.createIndex({
  name: 'idx_orders_totalPrice',
  collection: 'orders',
  field_name: 'totalPrice',
  index_type: 'price'
});

​
When to Create Indexes

1

Before storing data

Create indexes BEFORE storing any data to ensure optimal performance from the start
2

Query fields

Index all fields used in whereField() queries
3

Foreign keys

Index foreign key fields used in relations and JOINs
4

Sort fields

Index fields used for sorting

​
Complete Example

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

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

const db = client.database('my-ecommerce-app');

// Create users collection with indexes
await client.createCollection({
  name: 'users',
  fields: {
    email: { type: 'string', index: true, unique: true },
    createdAt: { type: 'date', index: true }
  },
  useBaseFields: true
});

// Or use the database manager for individual indexes
await db.createIndex({
  name: 'idx_users_email',
  collection: 'users',
  field_name: 'email',
  index_type: 'hash',
  unique_constraint: true,
  store_values: true
});

await db.createIndex({
  name: 'idx_users_createdAt',
  collection: 'users',
  field_name: 'createdAt',
  index_type: 'btree'
});

// Create order indexes

await db.createIndex({
  name: 'idx_orders_userId',
  collection: 'orders',
  field_name: 'userId',
  index_type: 'hash'
});

await db.createIndex({
  name: 'idx_orders_status',
  collection: 'orders',
  field_name: 'status',
  index_type: 'hash'
});

// PriceIndex for payment-based pricing
await db.createIndex({
  name: 'idx_orders_totalPrice',
  collection: 'orders',
  field_name: 'totalPrice',
  index_type: 'price'
});

​
Relations Between Collections

Create relations for better data organization: 
const relation = await client.createRelation({
  parent_collection: 'users',
  parent_field: 'id',
  child_collection: 'posts',
  child_field: 'author_id'
});

console.log('Relation created:', relation);
console.log('Indexes created:', relation.indexes_created);

​
Next Steps

Data Storage

Store data with payment callbacks

Querying

Query your indexed collections