OnchainDB 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 '@onchaindb/sdk';
const client = createClient({
endpoint: 'https://api.onchaindb.io',
appKey: 'your-app-key',
appId: 'your-app-id'
});
// Get database manager
const db = client.database('your-app-id');
// Create collection
await db.createCollection('users', {
namespace: 'users_ns',
primary_column: 'id',
sort_column: 'createdAt'
});
Why Indexes Are Required
Every collection MUST have at least one index for production use.
| Issue | Impact |
|---|
| Slow queries | All reads perform full collection scans, resulting in poor performance |
| Dashboard invisible | The OnchainDB dashboard discovers collections through index configurations - collections without indexes will not appear |
| Unoptimized costs | Full 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',
options: { unique: 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
Before storing data
Create indexes BEFORE storing any data to ensure optimal performance from the start
Query fields
Index all fields used in whereField() queries
Foreign keys
Index foreign key fields used in relations and JOINs
Sort fields
Index fields used for sorting
Complete Example
import { createClient } from '@onchaindb/sdk';
const client = createClient({
endpoint: 'https://api.onchaindb.io',
appId: 'my-ecommerce-app',
appKey: 'your-app-key'
});
const db = client.database('my-ecommerce-app');
// Create users collection with indexes
await db.createCollection('users', {
namespace: 'users',
primary_column: 'id',
sort_column: 'createdAt'
});
await db.createIndex({
name: 'idx_users_email',
collection: 'users',
field_name: 'email',
index_type: 'hash',
options: { unique: true }
});
await db.createIndex({
name: 'idx_users_createdAt',
collection: 'users',
field_name: 'createdAt',
index_type: 'btree'
});
// Create orders collection with indexes
await db.createCollection('orders', {
namespace: 'orders',
primary_column: 'id',
sort_column: 'createdAt'
});
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
