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:

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

Resolution#

One tick is 100 ns, or 0.0000001 s.

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.

Python conversion#

Python uses datetime.timedelta and a timezone-aware UTC datetime. Native option and result records use these rules:

• A timedelta converts to ticks exactly from its days, seconds and microseconds.
• A timedelta beyond the i64 tick range saturates.
• Timing and commit records use microsecond resolution. Sub-microsecond ticks round toward negative infinity.
• Explicit tick conversions and typed data decoding refuse sub-microsecond ticks, so a value keeps its identity when used again.
• A datetime holds the years 1 to 9999. An instant outside this range causes invalid_argument with code time_out_of_range.
• None shows an absent instant.

Value types#

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

document#

An owned native document preserves ordered members and duplicate keys.

format#

The format selects a text codec or binary TRON.

node_id#

A node ID selects a node within its owning document.

transaction#

A transaction selects a committed database snapshot.

entity#

An entity identifies an object in a database.

instant#

An instant counts 100 ns ticks since the Unix epoch. An instant outside the host range reports time_out_of_range.

duration#

A duration counts 100 ns ticks. Conversions beyond a host duration range saturate.

number#

A number is a signed integer or finite floating-point value.

bytes#

Bytes contain a borrowed byte sequence with an explicit length.

Other kinds#

These kinds have no value type of their own. The signature of each operation gives the exact type. Parameter tables link handle and record kinds to the operation or record that defines them.

Binding mechanics#

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

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 from a token file#

(await stardust.activate(Path("license.token").read_text().strip()))
result = (await stardust.license())

{: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#

input = stardust.NodeInput(kind="number", number=41)
async with (await stardust.builder()) as builder:
    (await builder.add(input))
result = input

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

database/merge_patch#

seed_text holds this document:

{:#_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"}}

async with (await stardust.parse(seed_text, "edn")) as seed:
    result = (await db.merge_patch(seed))

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

database/mutation#

birthday_text holds this document:

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

async with (await stardust.parse(birthday_text, "edn")) as birthday, (await db.mutation(birthday)) as mutation:
    result = (await mutation.run())

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

database/patch_definition#

definition_text holds this document:

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

async with (await stardust.parse(definition_text, "edn")) as definition:
    result = (await db.patch_definition("queries", "people/by_role", definition))

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

document/read#

input_text holds this document:

{:x 41}

async with (await stardust.parse(input_text, "edn")) as input:
    result = (await input.read((await input.root())))

{: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:

{:x 41}

async with (await stardust.parse(input_text, "edn")) as input:
    views = (await input.read_many((await input.root()), 1))
result = views[0]

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

Read the process license#

result = (await stardust.license())

{: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:

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

async with (await stardust.parse(birthday_text, "edn")) as birthday, (await db.mutation(birthday)) as mutation:
    result = (await mutation.run())

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

mutation/run#

birthday_text holds this document:

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

async with (await stardust.parse(birthday_text, "edn")) as birthday, (await db.mutation(birthday)) as mutation:
    result = (await mutation.run())

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

Open with explicit native options#

options = dict(page_size=0)
async with (await stardust.open(database_path, **options)):
    result = stardust.Options(**options)

{: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#

options = dict(page_size=0, lock_timeout=timedelta(microseconds=-1))
async with (await stardust.open(database_path, **options)):
    result = stardust.Options(**options)

{: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#

boundary_text holds this document:

999999999

query_text holds this document:

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

async with (await stardust.parse(boundary_text, "edn")) as boundary:
    days = (await boundary.i64((await boundary.root())))
options = dict(page_size=2, max_cost=timedelta(days=days))
async with (await stardust.parse(query_text, "edn")) as definition, (await db.query(definition)) as query, (await query.run(**options)):
    result = stardust.RunOptions(**options)

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

Python durations have microsecond resolution#

result = stardust.RunOptions(page_size=2, max_cost=timedelta(microseconds=1))

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

Python negative durations retain their microsecond precision#

result = stardust.RunOptions(max_cost=timedelta(microseconds=-1))

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

Run with typed query options#

query_text holds this document:

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

options = dict(page_size=2, max_cost=timedelta(seconds=1))
async with (await stardust.parse(query_text, "edn")) as definition, (await db.query(definition)) as query, (await query.run(**options)):
    result = stardust.RunOptions(**options)

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

Read the complete initial subscription event#

query_text holds this document:

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

async with (await stardust.parse(query_text, "edn")) as definition, (await db.query(definition)) as query, \
        (await query.subscribe()) as subscription:
    result = await subscription.next(timedelta(seconds=5))
    if result is None:
        raise TimeoutError

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