An on-device database a layout owns: typed collections of records that live in the app, with no server, no broker and no network. Controls read them through the standard Sync block (method: "local") and write them through the standard Toggle expand block (method: "local"), so a Border thickness, Axis bottom or Card padding bound to the store behaves exactly as it does over MeshSocket, MQTT or HTTP — only the wire differs. Every query is plain JSON: there is no SQL, no code and no expression language in a layout.
Symbol
internaldrive
Docs
Docs complete
Fields
16 fields, each with what it does.
Fields
Field
Type
Default
What it does
typetype
choiceone of 1
—
What kind of source this is
Marks the source as an on-device store; the only value is local.
locala store kept on this phone, with its own collections and views
namespacenamespace
text
—
The store's private shelf name
Scopes every non-shared collection so two layouts' rows stay apart; defaults to the layout id, then its name.
collectionscollections
object
—
The tables you keep rows in
Declares each named collection of rows, with its fields, order, sharing and defaults.
viewsviews
object
—
Saved filtered lists
Declares named row sets over a collection or another view, which bindings read like a collection.
weekStartsOnweekStartsOn
choiceone of 2
monday
Which day the week begins
Sets the first day of the week used for week grouping and the start-of-week date token.
mondaydefaultweeks begin on Monday (ISO weeks), the default
sundayweeks begin on Sunday
labelcollections.label
text
—
A friendly collection name
Sets the name the type builder shows for this collection.
fieldscollections.fields
object
—
The columns each row has
Names each field of the collection and its type or type options; rows hold only these fields.
ordercollections.order
string[]
—
The order fields are shown
Lists the fields in the order the type builder and entry forms show them.
sharedcollections.shared
on / off
—
Let other layouts use these rows
When true the collection lives in the shared namespace so other layouts can bind the same rows.
mirrorcollections.mirror
on / off
—
Reserved for the studio
Is stored with the collection but not read by the store; it only feeds the studio change notice.
singletoncollections.singleton
on / off
—
Keep just one row
When true the collection holds exactly one row, with the id singleton, such as a counter or preferences.
defaultscollections.defaults
object
—
Starting values for the single row
Sets the singleton row's first values, shown before the first write; only valid with singleton on.
fromviews.from
text
—
What the list is built from
Names the collection or view whose rows this view reads.
whereviews.where
object
—
Which rows to keep
Filters the source rows so the view holds only matches.
orderByviews.orderBy
text
—
How the list is sorted
Sorts the view by this field, newest or largest first when it starts with a minus sign.
limitviews.limit
number1–10000step 1
—
Cap the list length
Stops the view after this many rows.
Examples
3 examples, each one a control you can paste into a layout.
Typical uses: a reading log, a habit or expense tracker, a parts inventory, a
scoreboard — anything that is the user's own data and should survive a relaunch,
a layout edit and even the layout's deletion.
Definition
A local store is one more entry in the layout's top-level Data Sources block:
Scope for every non-shared collection. Defaults to the layout id, else its name. An explicit value must match ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$; the literal shared is reserved. A layout with a second local source must give it an explicit namespace.
weekStartsOn
no
"monday" (default, ISO weeks) or "sunday". Feeds the week bucket and the {{startOfWeek}} token.
collections
yes
Map of collection name → declaration. Names match ^[a-z][A-Za-z0-9_]{0,47}$; at most 32 per source.
collections.*.fields
yes
Map of field name → type (closed set below), or → an object {type, …options} (see Field options). Names match ^[a-z][A-Za-z0-9_]{0,63}$; id, createdAt, updatedAt and _hlc are reserved; at most 64 fields.
collections.*.order
no
The fields in display order (the order the type builder shows them and an entry form asks them). Each name must be declared, once. Absent = by name.
collections.*.shared
no
true puts the collection in the device-wide shared namespace so other layouts can bind the same rows.
collections.*.mirror
no
Reserved for the studio change-notice; stored, not read by the store.
collections.*.singleton
no
true makes the collection hold exactly one row, id singleton (see Singleton collections below).
collections.*.defaults
no
Map of declared field → starting value for the singleton row. Allowed only with singleton: true; each value must be valid for its field's type, and an undeclared field is rejected.
views
no
Map of view name → {from, where?, orderBy?, limit?}. from is a collection or another view (nesting up to 8 deep, cycles rejected). View names share the collection namespace and may not collide with one. A view never has groupBy/aggregate: it is a row set, and the binding aggregates it.
A sync or action with no source resolves to the single local source, exactly
as MQTT/HTTP bindings do; name the source when a layout declares several. A
source that fails validation (bad name, unknown type, a stage naming an undeclared
field) is reported to the connection console and shown as a failed pipe; the
rest of the layout still renders.
Collections and field types
Every record carries three reserved, store-managed fields — id (a string,
1–128 chars of [A-Za-z0-9_.:-], minted by the store unless the action supplies
one), createdAt and updatedAt (ISO-8601 UTC instants) — plus the declared
fields. Every declared field is nullable; a field missing from a write is null
(unless its options give it a default or make it required).
Type
Accepted on write
Delivered as
string
JSON string
string
number
JSON number
number
integer
JSON number with no fractional part
number
bool
JSON true / false only
bool
date
ISO-8601 string, one of the two forms below
string, normalized
json
any JSON value; stored canonical (sorted keys, no whitespace)
the decoded value
Writes reject, never coerce: a number given "42" fails, a bool given
1 fails, an integer given 1.5 fails, and a write naming an undeclared or
reserved field fails as a whole (one transaction, all or nothing). The failure
is a connection-console line and a failed pipe, never an alert.
Field options
A field may be declared as an object instead of a bare type string. The object
carries the type plus any of these options; the plain form stays valid and means
"no options". Options describe the field for the type builder and entry forms,
and the store enforcesrequired, default, choices and range on every
write.
The friendly name shown for the field ("Last watered"); the key stays a field name.
required
any
An insert must give the field a non-null value (after default fills it). A set/update may not null it.
default
any
Value an insert (or upsert) writes when the field is absent. Must be valid for the type and the other options. A date field may say "now" (the write's instant).
unit
number, integer
Free text shown after the value (ml, kg, $), 1-16 characters.
range
number, integer
[min, max]; writes outside it are rejected. A rating's scale (default [1, 5]).
decimals
number, integer
Decimal places shown, 0-6.
choices
string (one), json with multiple: true (many)
The allowed values (1-100, unique). A one-choice field stores the string; a many-choice field stores an array of them.
multiple
json
With choices: the field holds several choices.
labels
bool
Two words to show for true / false (["Done", "Not yet"]).
symbol
display: rating
SF Symbol name the rating draws (star, heart, circle).
display
see below
How the field shows and is entered.
compute
number, integer
A formula over the entry's own fields, worked out on every save (see Computed fields).
display values and the types they fit: number, duration (seconds) on
number/integer; text, longText, photo on string; toggle on bool;
date, time, dateTime on date; choice on string/json (needs
choices); rating on integer; location on json (a {lat, lon, label?}
object, checked on write).
A bad option fails the source with a named error (collection log: field cups
range must be [min, max] with min <= max, … has unknown option colour,
… default does not fit the field), like any other schema problem.
Computed fields
A number or integer field may carry compute: a small formula over the
entry's own fields, worked out every time the entry is saved (insert,
upsert, set/update, a singleton set/increment, a widget or Siri write)
and stored like any other field. Every query stage can then filter, sort, group
and aggregate it, so "workout volume per week" is a plain sum:
An input is {"field": name} or a plain number; ops nest up to 4 deep. unit
is seconds, minutes, hours, days (default) or weeks. The arithmetic
inputs must be number, integer or bool fields, a since/until input a
date field. When an input is empty, a division is by zero or the result is
not finite, the computed field stores null. An integer result is rounded.
since/until are fixed at the save: they do not tick afterwards.
A computed field is never written directly: a write or increment naming it is
rejected (volume is computed from other fields; leave it out). It may not be
required, have a default, read itself, read another computed field, or read
an undeclared field; each is a named schema error (… field volume compute
reads undeclared field weigth). Adding or changing a formula re-works the
stored value of every existing row when the layout loads.
Dates
A date field is stored as text in one of two normalized forms:
Instant — YYYY-MM-DDTHH:MM:SS.SSSZ, always UTC with milliseconds. Any
ISO-8601 instant with an offset is accepted and converted.
Calendar date — YYYY-MM-DD, no zone. A "finished on" is a date, not an
instant, and never shifts a day when the phone travels.
Both forms compare and sort correctly with gt/gte/lt/lte because they
share the YYYY-MM-DD prefix. The {{today}} and {{startOf…}} tokens name
the start of a period in the device's zone; {{now}} is an instant. "Since the
start of today" is {"gte": "{{today}}"} and includes everything written today,
including an instant stored at 23:30 local time (see Tokens).
Views
A view is a named, reusable row set: { "from", "where"?, "orderBy"?, "limit"? }.
from names a collection or another view, so views stack (topShelf over
finishedThisYear over books). A binding or a select action names a view
wherever it would name a collection; the binding's own stage (including
aggregate/groupBy) is applied on top of the view's rows. Insert, update,
upsert, delete and the singleton ops target collections only, never views.
Singleton collections
A collection declared "singleton": true holds exactly one row with the
fixed id singleton: a counter, a set of preferences, a "last watered" date.
There is no row until the first write, which creates it from the collection's
defaults (fields without a default start null) and then applies the op.
Write with the set, increment, decrement and toggle ops (below);
none of them takes an id. insert, update and upsert also work but only
with the id singleton (an insert with no id gets it); any other id is
rejected. Singleton ops on a collection without singleton: true fail.
Read with an ordinary rows binding: valuePath: "first.waterings" (or just
"waterings"; a field named count is read with "count" too, see
Delivery shapes). Before the first write an unfiltered binding (no where) still
receives the defaults as first, with count: 0, so a label shows its
starting value on first launch.
Every singleton op is one write transaction and the arithmetic runs inside the
store, so rapid taps never lose an update.
Query stages
A binding's query is the object { where?, groupBy?, aggregate?, having?, orderBy?, limit? }
written directly on the Sync entry beside collection. Each stage is JSON;
field names must be declared on the collection (or be id, createdAt,
updatedAt), and values are matched by type — a mismatch is simply "no match",
never a coercion.
where
An object whose keys are field names mapping to an operator object, or the
combinators and / or holding an array of where objects. A bare value is
shorthand for eq; sibling keys are and-ed. Depth is capped at 8 and a
where may hold at most 32 leaves. {} matches every row.
Operator
Form
Meaning
eq
{"rating": 5} or {"rating": {"eq": 5}}
equals; null never matches; a value of the wrong type matches nothing
ne
{"rating": {"ne": 5}}
not equal; a null row counts as "not 5"
gtgteltlte
{"rating": {"gte": 4}}
ordered compare on numbers, strings and dates
in
{"tag": {"in": ["a", "b"]}}
any of at most 64 values; an empty list matches nothing
contains
{"title": {"contains": "dun"}}
case-sensitive substring; string fields only
exists
{"notes": {"exists": true}}
field is (or, with false, is not) null; the only operator allowed on a json field
and / or
{"or": [{"lent": true}, {"rating": {"lt": 2}}]}
combine nested where objects
aggregate
Collapses the matched rows to one value. Either the bare string
"aggregate": "count" or the object "aggregate": {"op": "sum", "field": "pages"}
(the object form is required whenever a field is needed).
Op
Field
Result
count
none
number of matched rows
sum
number/integer
total; 0 for no rows
avg
number/integer
mean; null for no rows
min / max
number/integer/date/string
smallest / largest value
distinct
any non-json field
number of distinct values; with "bucket": "day" (week/month/year) on a date field, the number of distinct buckets, e.g. days with any entry
first / last
any non-json field
that field of the first / last row under orderBy (default createdAt, then id)
span
a date field, plus an optional to date field
first..last: {from, to, count, days, open} (see below)
span.{"op": "span", "field": "started", "to": "finished"} answers "from when
to when": from is the earliest field, to the latest to (or field when a row
has no to, or when to is omitted), count the rows with a field, and days
the calendar days from from to to, counting both ends (0 for no rows). A row
with a field but an empty to is still going: to becomes today and open is
true. The binding's payload is that object plus value, the label text
("Jan 3 to Sep 20", "Jan 3 to now" when open, null for no rows), and caption
("8 months"), so a Border thickness shows the span with no valuePath; valuePathfrom / to / count / days / caption read one part. span is not a group
aggregate.
groupBy
Buckets the matched rows and (with aggregate, default count) produces one
value per bucket. Four forms:
"groupBy": "genre" — exact values of a field.
"groupBy": {"field": "finished", "bucket": "month"} — a date field by
day, week, month or year. Keys are YYYY-MM-DD (day and week, the week
keyed by its first day per weekStartsOn), YYYY-MM or YYYY. Calendar dates
bucket as written; instants bucket in the device's current zone. A null date
lands in the null bucket, listed last.
"groupBy": {"field": "pages", "width": 100} — a number/integer field into
ranges; the key is the bucket's lower edge as a number.
"groupBy": {"range": ["started", "finished"], "bucket": "day"} — a row counts
in every bucket its started..finished span touches (once per bucket, so a
ten-day book adds 1 to each of ten days, or 1 to its one month). An empty
finished means still going: the span runs to today. A row with no started is
left out; a finished before started counts the start bucket only. One row may
span at most 3660 days and all rows together 200000 row-days, or the query fails
with a limit error. Keys are the same as a date bucket.
bucket and width are exclusive; range replaces field. A grouped query
returns at most 500 groups.
fill. A date bucket or a range may add "fill" so charts and calendars show
empty buckets: "fill": true adds every missing bucket between the first and last
key; "fill": {"from": "{{startOfYear}}", "to": "{{today}}"} fills that window
and drops keys outside it (either end may be left out: it defaults to the first
or last key). from/to are dates, instants or the period tokens ({{today}},
{{now}}, {{startOfWeek}}, {{startOfMonth}}, {{startOfYear}}). A filled
bucket's value is 0 for count/sum/distinct and null for avg/min/max;
the null-date bucket is dropped. orderBy and limit apply after the fill. A fill
of more than 500 buckets is a limit error. The payload shape is unchanged.
The first is a reading-days calendar for this year, the second pages per month
with empty months as 0, the third "sessions this month" (days with any entry).
Two levels (series)."groupBy": [<primary>, "<field>"] groups by the primary
(a field, a date bucket or a width, optionally filled) and by a second declared
field, giving one chart series per value of that field: "heaviest set per week, one
line per exercise". The result is a full grid: every category crossed with every
series, an empty cell carrying 0 (count/sum/distinct) or null
(avg/min/max; the Axis bottom draws it as a gap). Series come in ascending order,
at most 12 (the first 12; the rest are left out whole); limit caps the categories and orderBy may name key only. A range
groupBy takes no series.
having filters the aggregated groups with the where operators. Its leaves
name value (the group's aggregate) or key (the group key); and/or nest as in
where. Besides the tokens, a comparison value may be {"daysAgo": N}: the local
calendar date N days before today, for a date value (a max or min of a date
field). With a series, having drops single cells: a dropped cell (and an empty
one) is null, a gap, for every aggregate. having needs a groupBy, and
does not combine with fill or a range groupBy.
Plants whose last watering is more than seven days ago; the result re-runs when the
day changes. {"groupBy": "genre", "having": {"value": {"gte": 3}}} keeps the genres
with three or more books.
orderBy and limit
orderBy is a string or array of strings: "title" ascending, "-finished"
descending. In a row query any declared field, id, createdAt or updatedAt
is orderable; in a grouped query only key and value (default key
ascending). Ordering is stable (id is always the final tiebreak) and null
sorts last. A row query with no orderBy orders by id. Two writes never share
a createdAt/updatedAt (a write in the same millisecond is stamped 1 ms
later), so "createdAt" is add order and "-updatedAt" is most-recently-changed
first; rows of one batched write share a stamp and fall back to id.
limit is an integer from 1 to 1000. It applies to the rows of a row query and
to the buckets of a grouped query.
Tokens
A string that is exactly one of these tokens is replaced before the query runs
or the write lands ("{{today}}T" is a literal). In a where, tokens become
bound values, never query text.
Token
Value
Form
{{now}}
the current moment
instant, UTC
{{today}}
start of today in the device's zone
calendar date
{{startOfWeek}}{{startOfMonth}}{{startOfYear}}
start of the current period (week per weekStartsOn)
calendar date
{{selected}}
the collection's selection cursor (see select below), or null when nothing is selected
string id
When a date field is compared (eq/ne/gt/gte/lt/lte) against
{{today}} or a {{startOf…}} token, each stored value is compared in its own
form: a calendar date against the calendar date, an instant against the local
period start as a UTC instant ({{today}} on 2026-03-15 in New York is
2026-03-15T04:00:00.000Z), so evening items never count as the next day. in
lists and non-date fields use the calendar date.
A where that compares against an empty {{selected}} matches nothing, so a
form bound to the selection goes blank on deselect. A time-zone or calendar-day
change re-evaluates every binding that used a token. In actions, {{value}} and
the control's other tokens (Toggle expand) are available beside these.
Delivery shapes
The stage decides the payload a binding receives, and the store supplies a
default valuePath so the minimal form works with every existing receiver.
Card padding (listColumns[].key reads a field; with none given the list shows the collection's first fields), Color, or a form control naming first.title
Rows are flat: the declared fields sit beside id, createdAt and updatedAt.
count is the rows delivered, total the rows in the collection or view. A
valuePath that starts with a declared field is shorthand for first.<field>,
so {"where": {"id": "{{selected}}"}, "valuePath": "title"} fills a When you press Return or Send
with the selected row's title.
A declared field wins over the payload keys: if a collection declares a field
named count, total, rows or first, the bare valuePath ("count") reads
that field off the first row, not the payload's value. The payload keys are always
reachable by a $ spelling that no field can take: $rows, $count, $total
and $first ("$count" is the row count, "$first.title" the first row's
title). Without a colliding field, "count" and "$count" mean the same thing.
The lint and the app console warn about a field that shadows a payload key.
When nothing matches, first is null and the
control keeps its last value. filter applies to the payload object as on every
other transport but is rarely useful here.
Ops
An action with method: "local" names an op, a collection and, per op, an
id, a set object of declared field → value, or a singleton field and by. Tokens are substituted into
set and id first, then values are validated exactly like a delivery (reject,
never coerce). set may not name id, createdAt or updatedAt. A bound
control refreshes as soon as the write commits.
op
Requires
Effect
insert
set
New row with a store-minted id (or the given id; a duplicate is an error).
update
id, set
Merge set into the row; a missing row is an error.
upsert
id, set
Replace the whole row (fields absent from set become null), or insert it.
delete
id
Remove the row; a missing row is a no-op with a console note. Deleting the selected row clears the cursor.
select
id (or null)
Move the collection's selection cursor; no table write. Every binding that used {{selected}} for that collection re-delivers.
set
set; singleton collection
Patch the named fields of the one row, creating it from defaults first. Fields not named keep their value.
increment
field; singleton collection
Add by (default 1) to a number or integer field. The start is the stored value, else the field's default, else 0. An integer field takes whole steps only.
decrement
field; singleton collection
Subtract by (default 1); otherwise exactly like increment.
toggle
field; singleton collection
Flip a bool field. A field that is still null with no default counts as false, so the first toggle makes it true.
by is a JSON number or an exact token such as "{{value}}" that resolves to
one (a Symbol color can send its step); anything else fails. increment,
decrement and toggle without a field, set with no fields, or a field of
the wrong type fail like any other write.
Delete is by id only: a layout cannot wipe a collection with a where. Errors
surface as a connection-console line and a failed pipe (with the reason as its
detail) until the next successful op; there is never an alert. The studio mirror
sees only {op, collection} of a local action, never the values written.
What survives
Records belong to the user, not the layout. Deleting or replacing a layout —
including every studio re-push — never drops a table; a re-imported layout with the
same namespace re-attaches to its rows. Changing a field's type in a pushed or
hand-edited layout is refused (the source shows a failed pipe) rather than silently
converting data; in the app, Edit type converts the rows instead: it shows a dry
run over the real entries ("38 of 42 entries convert…"), keeps a copy of the old field
for a lossy change, and saves a snapshot of the collection first that can be restored
for 30 days. A field's key never changes, so renaming it (its label) touches no row
and no binding. Adding a field
adds a nullable column; removing one from the declaration leaves the column in
place, hidden. The selection cursor persists across relaunch. Records, the cursor
and query results are never part of the layout document, so a .carter export,
a studio read or an invite bundle carries the schema only.
What the header shows
A local source is a Data Pipe (Local, keyed by namespace) beside any MQTT or
HTTP pipes: grey with no bindings when nothing reads it, amber loading while
the first results arrive, green with <n> records · <m> bindings while serving,
red with the sanitized reason after a schema, stage or write error. A layout with
only a local source has no socket, so the header dot takes the pipe's colour.
Limits
Limit
Value
Collections per source
32
Fields per collection
64
Rows per collection
50 000 (an insert past the cap fails)
Groups per grouped query
500 (a two-level groupBy: 500 categories × 12 series)
limit
1 … 1000
where
depth 8, 32 leaves, 64 members per in
View nesting
8 deep
id
1–128 chars of [A-Za-z0-9_.:-]
Not a stage: no computed fields, no joins across collections, no expressions,
no projections (rows always deliver every declared field). Anything
beyond this is a bridge's job.