← Getting started as a developer
What is a fact (datom), and how are records stored?
Checked against GilbApp d529620.
A datom is one fact about a record, a fact name with one value and two times; GilbPlatform adds datoms and never writes over one.
Deeper
Also asked:
How is data stored: tables, a graph, or facts? As facts: each record is kept as datoms, one fact each, with no table for each kind of thing. Links and relations join records into a graph. Underneath, all of it is kept in PostgreSQL, a widely used database program.
How do I read an earlier version of a record by API? Add ?as_of= and a moment to the record's address to read it as it stood then, or add /history to read every fact it has had, each with its two times and who wrote it.
A record is one piece of data with its own address, such as a person, a place, a thing or a note. GilbPlatform does not store a record as one document. It stores datoms: each datom says that one record has one fact, a fact name from GilbVeda, the shared list of terms, such as a:title, with one value. The JSON your app reads for a record is put together from its current datoms each time it is read; no copy of that document is kept.
Time comes twice. World time is when a fact was true in the world, from a start to an end. System time is when GilbPlatform wrote the fact down, and when it was later replaced. A datom carries both. Its world time starts when it is written, unless the write names another start.
GilbPlatform never writes over a fact: a change closes the old fact and adds the new one. The closing is a datom too, which records when the fact stopped. Deleting ends a record; it does not erase it. An ended record can be brought back. So GilbPlatform keeps every earlier version of a record. Programs read every datom a record has had at its address with /history added, such as https://<name>.gilb.com/vault/e/<record id>/history, each with its two times and the agent, who the write says made it: the writer, unless the write names another; and the record as it stood at an earlier moment of system time by adding ?as_of= and that moment. Reading it as it stood at an earlier moment of world time is not offered yet. The history follows your access now: a record you may no longer read shows no history either, even from a time when you could read it.
Each different value is stored once, under a hash of its content, a short fingerprint worked out from it, so a value that many records hold is kept one time. A whole record has such a hash too: a write that would leave a record exactly as it is writes nothing.
Before a datom is stored, its type and fact name pass one check of their spelling. Write types as t:<Type> and fact names as a:<name>: a bare type name, such as Note, is refused with 400 InvalidDatomError, and a full address on another host, such as https://veda.gilb.com/base/a/title, is kept as you wrote it, so the same meaning written two ways is stored as two different values. The answer on why a write was refused lists what each refusal means.
Records are joined in two ways: a fact whose value is a link to another record, such as a:partOf, or a relation, which is a record of its own, with its own address and its own datoms. Underneath, GilbPlatform stores all of it in PostgreSQL, a widely used database program; apps read and write records through GilbPlatform, not in that database.
The full reference is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapters Dev.Guide.Overview, https://appbuilder.gilb.com/base/e/06gkzpwebxv8ncqr4qd7egmt58, and Dev.Guide.Vocabulary, https://appbuilder.gilb.com/base/e/06gkzpwtj1wm58yf6zng0xdtbm. It can be read with no sign-in, as data for programs and AIs rather than as a web page.
Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11; code read at 498d29a0): docs/BASE-DEVELOPER-GUIDE.md §7.1 :7222-7241 (team notes, not linked: the five tables; base.facts valid_from/valid_to world-time, tx_from/tx_to system-time, op 1 assert / 0 retract; base.values value_hash = sha256(JCS(value)), every distinct value is stored once; compute-on-read, no projection table), §7.2 :7243-7273 (state_hash no-op 200; relationUri); src/write/canonical.ts:18-55 (DatomValue, a value may be a link {@id}; hashValue RFC 8785 + SHA-256); src/write/ingest.ts:6, :1469-1502 (whole-state hash: an unchanged state writes nothing), :2068 (valid_from = state.valid_from ?? now), :2194-2219 (a change writes a retract row with valid_to = now, then the new assert); src/routes/write.ts:20-30 (valid_from and agent in the body of PUT /base/e and POST /base/ingest; the /lws doors take no valid_from); src/lws/routes.ts:850, :1019, :1062 (agent = body.agent, the x-base-agent header, or the caller's principal); src/write/relation-end.ts:17-22 (When the write path closes a fact it writes an op = 0 row with valid_to = now); src/read/query.ts:17-41, :145-178 (?as_of is a transaction-time read; True VALID-time as-of ... is the deferred); src/routes/read.ts:476-549 (readHistory from :494: fact_id, attribute, value, valid_from, valid_to, tx_from, tx_to, op, txn_id, agent; current-access authz, identical 404), :820-844 (GET /base/e/:id/history and /base/r/:id/history); src/write/normalize.ts:1-60 (the one-spelling write door: T1-T7, A1-A8; T2/A3 an address on the platform's own host becomes t:X / a:x; T6/A6 an address on another host is kept), :264-271 (type refusal text is not a legal type notation); src/write/errors.ts:11-17 (InvalidDatomError 400); src/uri/vault-segment.ts:305-405 (vaultPathRewrite :321: the /vault spelling of a user vault is rewritten to the /base routes). Dev.Guide.Overview (A 06gkzpwebxv8ncqr4qd7egmt58, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied); Dev.Guide.Vocabulary (A 06gkzpwtj1wm58yf6zng0xdtbm, pack GilbPlatformDeveloperGuide, 2026-11-11 and; read for agreement, not copied) Overview.History ("The platform never overwrites a fact. A change closes the old fact and adds a new one. A delete ends a record ..."), Overview.Records; Vocabulary.Names, Refusals ("Today a full address is kept as you wrote it ... stored ... as two different values", verified 2026-10-15); Addresses.Record (history at the @id address). GilbVeda (public read https://veda.gilb.com/base/terms?q=, 2026-11-11): Datom, datom, bitemporal, valid time, transaction time: no term (see Concepts to mint); t:VaultRecord (One unit of data held in a Vault, with its own address). Row: Concepts.DatomFacts.