Types and units

The document operations use typed values, and the database operations add time values. The tables use the type names of your selected language. Use it to find the unit, range, default, and absent value of a field.

Text uses UTF-8. This includes string values, object keys, and JSON, DUST, and EDN input and output. The document builders reject invalid UTF-8 strings and keys. TRON is binary, but its strings and keys also use UTF-8. Byte lengths count encoded bytes, rather than characters.

This matches JSON's UTF-8 requirement for interchange (RFC 8259, section 8.1).

Evaluation and database read results recursively omit object fields containing empty objects or arrays. This includes objects emptied by nested omissions. Null, empty strings, false, zero and array positions stay intact. Input documents and expanded programs preserve their contents.

Time and units defines the tick, its range and resolution, and the host conversion.
Value types defines documents, formats, node IDs, transactions, entities, instants, durations, numbers, and bytes.
Other kinds defines the remaining parameter and result kinds, such as text and counts.

Time and units

The ABI uses one time unit: the 100 ns tick, stored as an i64 count.

A duration is a signed tick count.
An instant is the tick count since the Unix epoch, 1970-01-01T00:00:00Z. It is in UTC, with no leap seconds and no time zone.
DUST durations and UTC values use the same unit, so database data and API parameters need no unit conversion.

Range

An i64 tick count holds approximately 29,227 years on each side of the Unix epoch:

Quantity	Value
Largest positive count	`2^63 - 1` = `9,223,372,036,854,775,807` ticks
Ticks per second	`10,000,000`
Largest positive duration	Approximately `922,337,203,685` seconds, or `29,227.7` Gregorian years
Instant range from the Unix epoch	Approximately 27,258 BCE to 31,197 CE

This covers all written history, including cuneiform from approximately 3400 BCE.

Note

It also covers these fictional settings:

The Butlerian Jihad: approximately 13,000 CE in The Dune Encyclopedia.
The Horus Heresy: 30,005 to 30,014 CE (005.M31 to 014.M31).

Resolution

One tick is 100 ns, or 0.0000001 s.

Note

At its peak speed, the Parker Solar Probe, the fastest human-made object, travels approximately 19 mm in one tick.

Calculation	Value
Probe's peak speed	`191.2 km/s` = `191,200 m/s`
Time interval	`1 tick` = `0.0000001 s`
Distance = speed × time	`191,200 × 0.0000001` = `0.01912 m` ≈ 19 mm

Thread wake-up jitter on common platforms is microseconds, so a smaller unit gives no useful precision. Windows also counts time in 100 ns units.

Order and time zones

Integer ticks have no floating-point rounding. ABI numbers are i64 or f64 only.
An instant in UTC ticks has no time zone or daylight-saving state. Each instant has one meaning, and integer comparison gives the time order.
The host applies time zones for presentation.
Each binding uses the duration and instant types of its language and converts at the call boundary.

Odin conversion

Odin uses time.Duration and time.Time.

A non-negative duration converts to ticks as d / 100ns. Sub-tick nanoseconds truncate toward zero.
A negative duration converts to -1 ticks, so its sign survives.
Ticks convert back as ticks * 100ns. A tick count beyond the i64 nanosecond range, approximately 292 years, saturates.
A time.Time converts through its Unix nanoseconds, with the same range. A larger instant returns invalid_argument with code time_out_of_range.
The zero time.Time shows an absent instant.

Value types

Each value type has one meaning in every language. Types below use the selected language's spelling.

Value	Type	Unit	Range	Absent
document	`Document`	None	Available memory	A null handle
format	`Source_Format`	None	JSON, DUST, EDN, TRON	Never absent
node_id	`u32`	Count	0 through 2147483646	4294967295
transaction	`i64`	Count	Signed 64-bit integer	Zero selects the latest snapshot
entity	`i64`	Count	Signed 64-bit integer	Never absent
instant	`time.Time`	100 ns ticks	Signed 64-bit ticks (host ranges differ)	Zero when no commit was written
duration	`time.Duration`	100 ns ticks	Signed 64-bit ticks (host ranges differ)	Each field defines its zero or negative sentinel
number	`Number union`	None	i64 or finite f64	Never absent
bytes	`[]u8`	Bytes	Available memory	An empty sequence

Kind	Meaning
`none`	The operation returns no value.
`version`	An ABI version number.
`text`	UTF-8 text, or binary bytes for TRON.
`integer`	A signed 64-bit integer.
`real`	A finite 64-bit floating-point number.
`count`	A count that is not negative.
`boolean`	True or false.
`name`	A string: a key, title, path, kind or pattern.
`value`	A host value. The host mapping gives its document form.
`source`	A stored definition path or an inline definition document.

Binding mechanics

Bindings may include these arguments in addition to native operation arguments:

Argument	Purpose
Allocator	Owns copied output and diagnostics.
Cancellation context	Controls cancellation.
Loaded library	Selects the native ABI library.

Optional wrappers such as pointers, Option and Maybe keep the wrapped type's contract.

Record examples

The generator captured each result from the native library.

Activate the license embedded from a token file

odin

148 B

stardust.activate(strings.trim_space(#load("license.token", string))) or_return
result := stardust.license() or_return
defer stardust.close(&result)

Result / 396 B

{:value {:active              true
         :failure             "none"
         :support_end         72580320000000000
         :expires             nil
         :build               nil
         :refused_support_end nil
         :subject             "test"
         :license_id          "test"
         :name                ""
         :license             ""
         :tier                ""}}

Add a typed integer node

odin

217 B

input := stardust.Node_Input{parent = stardust.NO_NODE, kind = .Number, number = i64(41)}
builder := stardust.builder() or_return
defer stardust.close(&builder)

stardust.add(&builder, input) or_return
result := input

Result / 137 B

{:value {:parent  nil
         :kind    "number"
         :boolean false
         :number  41
         :key     ""
         :text    ""}}

database/merge_patch

seed_text holds this document:

edn

287 B

{:#_ada {:name "Ada"
         :role "engineer"
         :age  36}
 :#_bob {:name   "Bob"
         :role   "engineer"
         :age    41
         :mentor {:#link "#_ada"}}
 :#_cy  {:name "Cy"
         :role "designer"
         :age  29}
 :#_tx  {:author "smoke"
         :reason "seed"}}

odin

180 B

patch := stardust.parse(seed_text, .EDN) or_return
defer stardust.close(&patch)

commit := stardust.merge_patch(db, patch) or_return
defer stardust.close(&commit)

result := commit

Result / 228 B

{:value {:status       "committed"
         :transaction  4
         :facts        12
         :committed_at 17923367874985475
         :ids          {:#_ada 1
                        :#_bob 2
                        :#_cy  3}}}

database/mutation

birthday_text holds this document:

edn

82 B

{:query {:find  [?e]
         :where [[?e "name" "Ada"]]}
 :patch {:?e {:age 37}}}

odin

262 B

source := stardust.parse(birthday_text, .EDN) or_return
defer stardust.close(&source)

mutation := stardust.mutation(db, source) or_return
defer stardust.close(&mutation)

commit := stardust.run(mutation) or_return
defer stardust.close(&commit)

result := commit

Result / 153 B

{:value {:status       "committed"
         :transaction  5
         :facts        1
         :committed_at 17923367877040951
         :ids          {}}}

database/patch_definition

definition_text holds this document:

edn

133 B

{:parameters {:?role "engineer"}
 :find       [?name]
 :where      [
   [?e "role" ?role]
   [?e "name" ?name]]
 :orderBy    [?name]}

odin

220 B

patch := stardust.parse(definition_text, .EDN) or_return
defer stardust.close(&patch)

commit := stardust.patch_definition(db, "queries", "people/by_role", patch) or_return
defer stardust.close(&commit)

result := commit

Result / 153 B

{:value {:status       "committed"
         :transaction  3
         :facts        0
         :committed_at 17923367877692345
         :ids          {}}}

document/read

input_text holds this document:

edn

7 B

{:x 41}

odin

171 B

source := stardust.parse(input_text, .EDN) or_return
defer stardust.close(&source)

root := stardust.root(source) or_return
result := stardust.read(source, root) or_return

Result / 218 B

{:value {:kind         "object"
         :boolean      false
         :parent       nil
         :position     0
         :first_child  1
         :next_sibling nil
         :key          ""
         :text         ""}}

document/read_many

input_text holds this document:

edn

7 B

{:x 41}

odin

228 B

source := stardust.parse(input_text, .EDN) or_return
defer stardust.close(&source)

root := stardust.root(source) or_return
views: [1]stardust.Node_View
_ = stardust.read_many(source, root, views[:]) or_return
result := views[0]

Result / 218 B

{:value {:kind         "object"
         :boolean      false
         :parent       nil
         :position     0
         :first_child  1
         :next_sibling nil
         :key          ""
         :text         ""}}

Read the process license

odin

68 B

result := stardust.license() or_return
defer stardust.close(&result)

Result / 396 B

{:value {:active              true
         :failure             "none"
         :support_end         72580320000000000
         :expires             nil
         :build               nil
         :refused_support_end nil
         :subject             "test"
         :license_id          "test"
         :name                ""
         :license             ""
         :tier                ""}}

mutation/close

birthday_text holds this document:

edn

82 B

{:query {:find  [?e]
         :where [[?e "name" "Ada"]]}
 :patch {:?e {:age 37}}}

odin

289 B

source := stardust.parse(birthday_text, .EDN) or_return
defer stardust.close(&source)

mutation := stardust.mutation(db, source) or_return
defer stardust.close(&mutation)

commit := stardust.run(mutation) or_return
defer stardust.close(&commit)

result := commit

stardust.close(&mutation)

Result / 153 B

{:value {:status       "committed"
         :transaction  5
         :facts        1
         :committed_at 17923367880327807
         :ids          {}}}

mutation/run

birthday_text holds this document:

edn

82 B

{:query {:find  [?e]
         :where [[?e "name" "Ada"]]}
 :patch {:?e {:age 37}}}

odin

262 B

source := stardust.parse(birthday_text, .EDN) or_return
defer stardust.close(&source)

mutation := stardust.mutation(db, source) or_return
defer stardust.close(&mutation)

commit := stardust.run(mutation) or_return
defer stardust.close(&commit)

result := commit

Result / 153 B

{:value {:status       "committed"
         :transaction  5
         :facts        1
         :committed_at 17923367881229875
         :ids          {}}}

Open with explicit native options

odin

168 B

options := stardust.Options{create = true, page_size = 0}
database := stardust.open(database_path, options) or_return
defer stardust.close(&database)

result := options

Result / 302 B

{:value {:create              true
         :clear               false
         :pin_memory          false
         :page_size           0
         :lock_timeout        0
         :initial_map_bytes   0
         :commit_batch        0
         :plugins             nil
         :memory_budget_bytes 0}}

Wait for the database lock without a limit

odin

201 B

options := stardust.Options{create = true, page_size = 0, lock_timeout = -time.Nanosecond}
database := stardust.open(database_path, options) or_return
defer stardust.close(&database)

result := options

Result / 304 B

{:value {:create              true
         :clear               false
         :pin_memory          false
         :page_size           0
         :lock_timeout        nil
         :initial_map_bytes   0
         :commit_batch        0
         :plugins             nil
         :memory_budget_bytes 0}}

Capture the host duration boundary

query_text holds this document:

edn

66 B

{:find    [?name]
 :where   [[?e "name" ?name]]
 :orderBy [?name]}

boundary_text holds this document:

edn

19 B

9223372036854775807

odin

535 B

definition := stardust.parse(query_text, .EDN) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

boundary := stardust.parse(boundary_text, .EDN) or_return
defer stardust.close(&boundary)

nanoseconds := stardust.i64(boundary, stardust.root(boundary) or_return) or_return
options := stardust.Run_Options{page_size = 2, max_cost = time.Duration(nanoseconds)}
rows := stardust.run(query, options = options) or_return
defer stardust.close(&rows)

result := options

Result / 83 B

{:value {:page_size 2
         :max_cost  92233720368547758
         :as_of     0}}

Truncate a positive sub-tick duration

query_text holds this document:

edn

66 B

{:find    [?name]
 :where   [[?e "name" ?name]]
 :orderBy [?name]}

boundary_text holds this document:

edn

2 B

odin

535 B

definition := stardust.parse(query_text, .EDN) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

boundary := stardust.parse(boundary_text, .EDN) or_return
defer stardust.close(&boundary)

nanoseconds := stardust.i64(boundary, stardust.root(boundary) or_return) or_return
options := stardust.Run_Options{page_size = 2, max_cost = time.Duration(nanoseconds)}
rows := stardust.run(query, options = options) or_return
defer stardust.close(&rows)

result := options

Result / 67 B

{:value {:page_size 2
         :max_cost  0
         :as_of     0}}

A negative Odin duration keeps its sign at the ABI boundary

odin

59 B

result := stardust.Run_Options{max_cost = -time.Nanosecond}

Result / 68 B

{:value {:page_size 0
         :max_cost  -1
         :as_of     0}}

Run with typed query options

query_text holds this document:

edn

66 B

{:find    [?name]
 :where   [[?e "name" ?name]]
 :orderBy [?name]}

odin

346 B

definition := stardust.parse(query_text, .EDN) or_return
defer stardust.close(&definition)

query := stardust.query(db, definition) or_return
defer stardust.close(&query)

options := stardust.Run_Options{page_size = 2, max_cost = time.Second}
rows := stardust.run(query, options = options) or_return
defer stardust.close(&rows)

result := options

Result / 74 B

{:value {:page_size 2
         :max_cost  10000000
         :as_of     0}}

Read the complete initial subscription event

query_text holds this document:

edn

66 B

{:find    [?name]
 :where   [[?e "name" ?name]]
 :orderBy [?name]}

odin

329 B

source := stardust.parse(query_text, .EDN) or_return
defer stardust.close(&source)

query := stardust.query(db, source) or_return
defer stardust.close(&query)

subscription := stardust.subscribe(query) or_return
defer stardust.close(&subscription)

result := stardust.next(subscription, 0) or_return
defer stardust.close(&result)

Result / 138 B

{:value {:sequence    1
         :superseded  0
         :transaction 4
         :result      [{:name "Ada"} {:name "Bob"} {:name "Cy"}]}}