ablative docs

Go to

↑↓ move↵ openesc close
 Stack Notebook ablative.com.au

Write your first records

Define a collection, write two records on the main branch and read them back.

Open .md

Before you begin

Have the service running from Install and run. Every command below takes --config with the file the service was started with.

Define a collection

A collection is a named home for records. You define it once. A schema is optional, so null is fine while you are getting started.

haematite write --config service.json --branch main collection.put \
  '{"collection":"patients","schema":null}'

The command prints a request id and then a receipt. The receipt carries the version the branch is now at.

Write two records

Each write names the collection, the record id and the document.

haematite write --config service.json --branch main document.put \
  '{"collection":"patients","document_id":"p0","document":{"name":"Ada","ward":"4B","admitted":20260912}}'
haematite write --config service.json --branch main document.put \
  '{"collection":"patients","document_id":"p1","document":{"name":"Bea","ward":"3A","admitted":20260913}}'

Writing the same id again adds a new version. The earlier version stays readable at the version it was written.

Read one record back

haematite call --config service.json documents.get \
  '{"selection":{"branch":"main"},"collection":"patients","document_id":"p0"}'

Run four queries

The first stage names a collection. Later stages filter, shape or count.

haematite query --config service.json --branch main 'collection("patients")'
haematite query --config service.json --branch main 'patients(ward: "4B")'
haematite query --config service.json --branch main 'collection("patients") | { name ward }'
haematite query --config service.json --branch main 'collection("patients") | count'
  1. Every patient.
  2. Only patients in ward 4B.
  3. Only the name and ward fields of every patient.
  4. How many patients there are.

Each row prints on its own line. The whole answer is read at the branch head of the moment the first page was read.

Exit codes you will see

0
Answered or applied. The receipt or the rows are on standard output.
1
Could not prepare or connect before sending the request. Read the command's diagnostic; this is a client-command exit code, not an offline maintenance result.
2
Refused, for codes this client knows. A refusal it doesn't know exits 3, even when nothing was applied; read its receipt. Read-only calls return 2 for service refusals.
3
The outcome is not known to the client. For write only, standard error names the request id to repeat it with. Query standard error instead reports any incomplete row count.

Next step

Read Records, collections and versions, then the query language.