Guide / Controls / Reference

Local Store

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
FieldTypeDefaultWhat it does
typetypechoiceone 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
namespacenamespacetext—

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.

collectionscollectionsobject—

The tables you keep rows in

Declares each named collection of rows, with its fields, order, sharing and defaults.

viewsviewsobject—

Saved filtered lists

Declares named row sets over a collection or another view, which bindings read like a collection.

weekStartsOnweekStartsOnchoiceone of 2monday

Which day the week begins

Sets the first day of the week used for week grouping and the start-of-week date token.

  • monday defaultweeks begin on Monday (ISO weeks), the default
  • sundayweeks begin on Sunday
labelcollections.labeltext—

A friendly collection name

Sets the name the type builder shows for this collection.

fieldscollections.fieldsobject—

The columns each row has

Names each field of the collection and its type or type options; rows hold only these fields.

ordercollections.orderstring[]—

The order fields are shown

Lists the fields in the order the type builder and entry forms show them.

sharedcollections.sharedon / 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.mirroron / off—

Reserved for the studio

Is stored with the collection but not read by the store; it only feeds the studio change notice.

singletoncollections.singletonon / off—

Keep just one row

When true the collection holds exactly one row, with the id singleton, such as a counter or preferences.

defaultscollections.defaultsobject—

Starting values for the single row

Sets the singleton row's first values, shown before the first write; only valid with singleton on.

fromviews.fromtext—

What the list is built from

Names the collection or view whose rows this view reads.

whereviews.whereobject—

Which rows to keep

Filters the source rows so the view holds only matches.

orderByviews.orderBytext—

How the list is sorted

Sorts the view by this field, newest or largest first when it starts with a minus sign.

limitviews.limitnumber1–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.

A reading log source

JSON 14 lines
{
  "sources": {
    "db": {
      "type": "local",
      "namespace": "book-logger",
      "collections": {
        "books": {
          "fields": { "title": "string", "pages": "integer", "rating": "number",
                      "finished": "date", "tags": "json", "lent": "bool" }
        }
      }
    }
  }
}

A shared collection with a view

JSON 14 lines
{
  "sources": {
    "home": {
      "type": "local",
      "weekStartsOn": "sunday",
      "collections": {
        "chores": { "fields": { "name": "string", "done": "date", "who": "string" }, "shared": true }
      },
      "views": {
        "thisWeek": { "from": "chores", "where": { "done": { "gte": "{{startOfWeek}}" } }, "orderBy": "-done" }
      }
    }
  }
}

A counter in a singleton collection

One row that holds a running count and a toggle, with starting values.

JSON 14 lines
{
  "sources": {
    "db": {
      "type": "local",
      "collections": {
        "plant": {
          "singleton": true,
          "fields": { "waterings": "integer", "lastWatered": "date", "outside": "bool" },
          "defaults": { "waterings": 0, "outside": false }
        }
      }
    }
  }
}

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:

{ "sources": {
  "db": {
    "type": "local",
    "namespace": "book-logger",
    "weekStartsOn": "monday",
    "collections": {
      "books": {
        "fields": { "title": "string", "pages": "integer", "rating": "number",
                    "started": "date", "finished": "date", "notes": "string",
                    "tags": "json", "lent": "bool" }
      }
    },
    "views": {
      "finishedThisYear": { "from": "books",
                            "where": { "finished": { "gte": "{{startOfYear}}" } },
                            "orderBy": "-finished" },
      "topShelf": { "from": "finishedThisYear", "where": { "rating": { "gte": 4 } }, "limit": 20 }
    }
  }
} }
Key Required Meaning
type yes "local".
namespace no 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 enforces required, default, choices and range on every write.

{
  "fields": {
    "when":   { "type": "date", "required": true, "default": "now", "display": "dateTime" },
    "cups":   { "type": "number", "unit": "cups", "range": [0, 20], "decimals": 1, "default": 1 },
    "mood":   { "type": "string", "choices": ["Good", "Okay", "Rough"], "display": "choice" },
    "tags":   { "type": "json", "choices": ["Work", "Home"], "multiple": true },
    "stars":  { "type": "integer", "display": "rating", "range": [1, 5], "symbol": "star" },
    "done":   { "type": "bool", "labels": ["Done", "Not yet"] },
    "place":  { "type": "json", "display": "location" },
    "note":   "string"
  }
}
Option Fits Meaning
label any 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:

{
  "fields": {
    "sets":   "integer",
    "reps":   "integer",
    "weight": { "type": "number", "unit": "kg" },
    "when":   { "type": "date", "default": "now" },
    "volume": { "type": "number", "unit": "kg", "compute": { "mul": [ {"field": "sets"}, {"field": "reps"}, {"field": "weight"} ] } }
  }
}
Formula Result
{"add" \| "sub" \| "mul" \| "div": [a, b, …]} 2-8 inputs, left to right.
{"since": {"of": {"field": "planted"}, "unit": "days"}} Time from a date field to the moment of the save.
{"until": {"of": {"field": "due"}, "unit": "days"}} Time from the save to a date field.

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.

{ "collections": {
  "plant": {
    "singleton": true,
    "fields": { "waterings": "integer", "lastWatered": "date", "outside": "bool" },
    "defaults": { "waterings": 0, "outside": false }
  }
} }
  • 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"
gt gte lt lte {"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; valuePath from / 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.

[
  {"groupBy": {"range": ["started", "finished"], "bucket": "day", "fill": {"from": "{{startOfYear}}", "to": "{{today}}"}}},
  {"groupBy": {"field": "finished", "bucket": "month", "fill": true}, "aggregate": {"op": "sum", "field": "pages"}},
  {"where": {"date": {"gte": "{{startOfMonth}}"}}, "aggregate": {"op": "distinct", "field": "date", "bucket": "day"}}
]

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.

{"groupBy": [{"field": "date", "bucket": "week"}, "exercise"], "aggregate": {"op": "max", "field": "weight"}}

having

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.

{"groupBy": "plant", "aggregate": {"op": "max", "field": "when"}, "having": {"value": {"lt": {"daysAgo": 7}}}}

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.

Stage Payload Default valuePath Typical receivers
aggregate, no groupBy {"value": 3} (null for avg of nothing) value Border thickness, Unit, Unit, any scalar control; a Title appends each new value
aggregate: span {"from": "2026-01-03", "to": "2026-09-20", "count": 12, "days": 261, "open": false, "value": "Jan 3 to Sep 20", "caption": "8 months"} value Border thickness (the text), a Show trend or second label on caption / days / count
groupBy (+ aggregate, default count) {"categories": ["2026-01", "2026-02"], "series": [{"name": "count", "values": [4, 7]}], "rows": [{"key": "2026-01", "value": 4}]} whole payload Axis bottom / Start angle / Label color read categories + series; a Card padding uses valuePath: "rows"; a sparkline uses series.0.values
two-level groupBy {"categories": ["2026-09-07", "2026-09-14"], "series": [{"name": "bench", "values": [70, null]}, {"name": "squat", "values": [110, 120]}], "rows": [{"key": "2026-09-07", "series": "bench", "value": 70}]} whole payload Axis bottom (one bar group or line per series)
rows (no aggregate) {"rows": [{"id": "…", "createdAt": "…", "updatedAt": "…", "title": "Dune", "pages": 412}], "count": 1, "total": 3, "first": {…} or null} rows 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.

Binding examples

Reading, on a control's sync entry:

[
  { "method": "local", "collection": "books", "aggregate": "count" },
  { "method": "local", "collection": "books", "aggregate": { "op": "sum", "field": "pages" },
    "where": { "finished": { "gte": "{{startOfYear}}" } } },
  { "method": "local", "collection": "books", "groupBy": { "field": "finished", "bucket": "month" } },
  { "method": "local", "collection": "books", "orderBy": "-createdAt", "limit": 50 },
  { "method": "local", "collection": "books", "where": { "id": "{{selected}}" }, "valuePath": "first.title" }
]

Writing, on a control's action:

[
  { "method": "local", "op": "insert", "collection": "books",
    "set": { "title": "{{value}}", "pages": 0, "finished": "{{today}}" } },
  { "method": "local", "op": "update", "collection": "books", "id": "{{selected}}",
    "set": { "rating": "{{value}}" } },
  { "method": "local", "op": "delete", "collection": "books", "id": "{{selected}}" },
  { "method": "local", "op": "select", "collection": "books", "id": "b-42" }
]

A singleton (the plant collection above), read by a Border thickness and written by buttons and a Knob shadow:

[
  { "method": "local", "collection": "plant", "valuePath": "first.waterings" },
  { "method": "local", "op": "increment", "collection": "plant", "field": "waterings" },
  { "method": "local", "op": "decrement", "collection": "plant", "field": "waterings", "by": 2 },
  { "method": "local", "op": "set", "collection": "plant", "set": { "lastWatered": "{{today}}" } },
  { "method": "local", "op": "toggle", "collection": "plant", "field": "outside" }
]
  • Sync — the inbound binding; collection and the stage fields
  • Toggle expand — the outbound op; op, collection, id, set, field, by
  • Data Sources — where the store is declared beside MQTT and HTTP
  • Card padding — the natural receiver for rows
  • Axis bottom — the natural receiver for grouped results

Generated from ControlDocs/local-store.md. Something unclear or missing? Tell me.