Query Cheatsheet¶

Quick reference for Centrali's canonical query model.

Start Here¶

• Query Records for the full guide
• Saved Queries for reusable named queries
• Text Search for search-focused patterns
• API Overview for route maps

Canonical Query Body¶

{
  "resource": "orders",
  "where": {
    "and": [
      { "data.status": { "eq": "paid" } },
      { "data.amount": { "gte": 100 } }
    ]
  },
  "text": {
    "query": "urgent"
  },
  "sort": [
    { "field": "createdAt", "direction": "desc" }
  ],
  "page": {
    "limit": 25,
    "offset": 0
  },
  "select": {
    "fields": ["id", "data.status", "data.amount"]
  },
  "include": [
    { "relation": "customerId" }
  ]
}

Operators¶

Field Paths¶

• Use data. for custom fields: data.status, data.amount
• Top-level fields do not need data.: id, createdAt, updatedAt, status
• Nested JSON paths use dotted notation: data.customer.email

GET Adapter¶

Use for simple, flat queries:

GET /data/workspace/{workspaceSlug}/api/v1/records/slug/{recordSlug}?data.status=paid&sort=-createdAt&pageSize=25

Common GET Params¶

POST Query Endpoint¶

Use for rich queries:

POST /data/workspace/{workspaceSlug}/api/v1/records/query

Use POST when you need:

• Nested and / or / not
• text
• select.fields
• include
• One query shape you can reuse in SDK code and saved queries

SDK¶

await centrali.records.query('orders', {
  where: { 'data.status': { eq: 'paid' } },
  sort: [{ field: 'createdAt', direction: 'desc' }],
  page: { limit: 25 }
});

await centrali.records.list('orders', {
  'data.status': 'paid',
  sort: '-createdAt',
  pageSize: 25
});

await centrali.records.search('orders', 'urgent', {
  where: { 'data.priority': { eq: 'high' } },
  page: { limit: 10 }
});

Compute Functions¶

const result = await api.queryRecords('orders', {
  where: {
    'data.status': { eq: 'pending' }
  },
  sort: [{ field: 'createdAt', direction: 'asc' }],
  page: { limit: 100 }
});

Result Envelope¶

{
  "data": [],
  "meta": {
    "limit": 25,
    "offset": 0,
    "hasMore": false,
    "total": 0,
    "processingTimeMs": 3,
    "mode": "filter"
  }
}

Saved Query Variables¶

Use canonical variable syntax inside saved query definitions:

{
  "query": {
    "resource": "orders",
    "where": {
      "data.status": { "eq": "${status}" }
    }
  }
}

Execute with:

{
  "variables": {
    "status": "paid"
  }
}

When to Use What¶

• Use records.list or GET routes for simple collection views
• Use records.query or POST /records/query for rich ad-hoc queries
• Use savedQueries when the same query should be named, stored, and reused
• Use records.search or a text clause when users type natural text