Collections — Data Storage

Overview

Collections are OrbioCloud's flexible data storage layer. Each collection has a manifest (schema definition) and stores documents as JSONB. You can optionally define a JSON Schema for validation, or store free-form data.

Create a Collection

// Requires secret key (sk)
const wines = await orbio.collections.create({
  slug: 'wines',
  name: 'Wine Collection',
  schema: {  // optional JSON Schema
    type: 'object',
    properties: {
      name: { type: 'string' },
      region: { type: 'string' },
      rating: { type: 'number' },
    },
  },
});

Slug rules: lowercase, starts with a letter, only a-z, 0-9, underscore (2-63 characters).

List Collections

const collections = await orbio.collections.list({ page: 1, limit: 20 });
// Returns: { items: [...], page, limit, total, has_more }

Create a Document

const wine = await orbio.collections.documents('wines').create({
  name: 'Chateau Margaux 2015',
  region: 'Bordeaux',
  rating: 95,
  vintage: 2015,
});
// Returns: { id, data, created_at, updated_at }

Query with Filters

// Find all wines from Bordeaux
const results = await orbio.collections.documents('wines').list({
  filter: { region: 'Bordeaux' },
  page: 1,
  limit: 50,
});

// REST equivalent:
// GET /v1/collections/wines/documents?filter={"region":"Bordeaux"}

Filtering uses PostgreSQL JSONB containment (@>). You can filter on any top-level field in the document data.

Update a Document

// Merge-patch: only specified fields are updated
const updated = await orbio.collections.documents('wines').update(wine.id, {
  rating: 96,
});

Delete a Document

await orbio.collections.documents('wines').delete(wine.id);

Manage Collections

// Get collection details
const manifest = await orbio.collections.get('wines');

// Update collection name or schema
await orbio.collections.update('wines', { name: 'Wine Cellar' });

// Delete collection (cascades to all documents)
await orbio.collections.delete('wines');

Permissions

• Read operations (list, get): publishable key (pk) or secret key (sk)

• Write operations (create, update, delete): secret key (sk) with collections:write scope