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).

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

QuantityValue
Largest positive count2^63 - 1 = 9,223,372,036,854,775,807 ticks
Ticks per second10,000,000
Largest positive durationApproximately 922,337,203,685 seconds, or 29,227.7 Gregorian years
Instant range from the Unix epochApproximately 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:

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.

CalculationValue
Probe's peak speed191.2 km/s = 191,200 m/s
Time interval1 tick = 0.0000001 s
Distance = speed × time191,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.

Go conversion

Go 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 time.Duration holds approximately 292 years, and a larger tick count saturates.
  • An instant converts through time.Unix, which keeps each i64 tick count exactly.
  • 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.

ValueTypeUnitRangeAbsent
document*DocumentNoneAvailable memoryA null handle
formatFormatNoneJSON, DUST, EDN, TRONNever absent
node_idIDCount0 through 21474836464294967295
transactionint64CountSigned 64-bit integerZero selects the latest snapshot
entityint64CountSigned 64-bit integerNever absent
instanttime.Time100 ns ticksSigned 64-bit ticks (host ranges differ)Zero when no commit was written
durationtime.Duration100 ns ticksSigned 64-bit ticks (host ranges differ)Each field defines its zero or negative sentinel
numberNumeric: I64 or F64Nonei64 or finite f64Never absent
bytes[]byteBytesAvailable memoryAn empty sequence

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.

Go exposes all public types in the stardust package. Query and Mutation take native definition documents. QueryPath and MutationPath take stored definition paths. There is no public Source or Path wrapper.

KindMeaning
noneThe operation returns no value.
versionAn ABI version number.
textUTF-8 text, or binary bytes for TRON.
integerA signed 64-bit integer.
realA finite 64-bit floating-point number.
countA count that is not negative.
nameA string: a key, title, path, kind or pattern.
valueA host value. The host mapping gives its document form.
sourceA stored definition path or an inline definition document.

Binding mechanics

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

ArgumentPurpose
AllocatorOwns copied output and diagnostics.
Cancellation contextControls cancellation.
Loaded librarySelects 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.

Add a typed integer node

go262B
builder, err := stardust.NewBuilder()
if err != nil {
	return err
}
defer builder.Close()

result := stardust.NodeInput{
	Parent: stardust.NoNode,
	Kind:   stardust.Number,
	Number: stardust.I64(41),
}
if _, err := builder.Add(result); err != nil {
	return err
}
Result / 81B
{parent  null
 kind    number
 boolean false
 number  41
 key     ""
 text    ""}

database/merge_patch

patchText holds this document:

dust232B
#_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}
go176B
patch, err := stardust.Parse(patchText, stardust.DUST)
if err != nil {
	return err
}
defer patch.Close()

result, err := db.MergePatch(patch, nil)
if err != nil {
	return err
}
Result / 159B
{status       committed
 transaction  4
 facts        12
 committed_at 17915443414178231
 ids          {#_ada 1
               #_bob 2
               #_cy  3}}

database/mutation

birthdayText holds this document:

dust68B
query {find  [?e]
       where [[?e name Ada]]}
patch {?e {age 37}}
go292B
source, err := stardust.Parse(birthdayText, stardust.DUST)
if err != nil {
	return err
}
defer source.Close()

mutation, err := db.Mutation(source)
if err != nil {
	return err
}
defer mutation.Close()

result, err := mutation.Run(nil, stardust.RunOptions{}, nil)
if err != nil {
	return err
}
Result / 105B
{status       committed
 transaction  5
 facts        1
 committed_at 17915443414964059
 ids          {}}

database/patch_definition

patchText holds this document:

dust123B
parameters {?role engineer}
find       [?name]
where      [[?e role ?role]
            [?e name ?name]]
orderBy    [?name]
go212B
patch, err := stardust.Parse(patchText, stardust.DUST)
if err != nil {
	return err
}
defer patch.Close()

result, err := db.PatchDefinition(stardust.Queries, "people/by_role", patch)
if err != nil {
	return err
}
Result / 105B
{status       committed
 transaction  3
 facts        0
 committed_at 17915443415276282
 ids          {}}

document/read

inputText holds this document:

dust5B
x 41
go228B
source, err := stardust.Parse(inputText, stardust.DUST)
if err != nil {
	return err
}
defer source.Close()

root, err := source.Root()
if err != nil {
	return err
}

result, err := source.Read(root)
if err != nil {
	return err
}
Result / 145B
{kind         object
 boolean      false
 parent       null
 position     0
 first_child  1
 next_sibling null
 key          ""
 text         ""}

document/read_many

inputText holds this document:

dust5B
x 41
go321B
source, err := stardust.Parse(inputText, stardust.DUST)
if err != nil {
	return err
}
defer source.Close()

root, err := source.Root()
if err != nil {
	return err
}

views := make([]stardust.NodeView, 1)
written, err := source.ReadMany(root, views)
if err != nil {
	return err
}
views = views[:written]
result := views[0]
Result / 145B
{kind         object
 boolean      false
 parent       null
 position     0
 first_child  1
 next_sibling null
 key          ""
 text         ""}

mutation/close

birthdayText holds this document:

dust68B
query {find  [?e]
       where [[?e name Ada]]}
patch {?e {age 37}}
go309B
source, err := stardust.Parse(birthdayText, stardust.DUST)
if err != nil {
	return err
}
defer source.Close()

mutation, err := db.Mutation(source)
if err != nil {
	return err
}
defer mutation.Close()

result, err := mutation.Run(nil, stardust.RunOptions{}, nil)
if err != nil {
	return err
}
mutation.Close()
Result / 105B
{status       committed
 transaction  5
 facts        1
 committed_at 17915443416384677
 ids          {}}

mutation/run

birthdayText holds this document:

dust68B
query {find  [?e]
       where [[?e name Ada]]}
patch {?e {age 37}}
go292B
source, err := stardust.Parse(birthdayText, stardust.DUST)
if err != nil {
	return err
}
defer source.Close()

mutation, err := db.Mutation(source)
if err != nil {
	return err
}
defer mutation.Close()

result, err := mutation.Run(nil, stardust.RunOptions{}, nil)
if err != nil {
	return err
}
Result / 105B
{status       committed
 transaction  5
 facts        1
 committed_at 17915443416714906
 ids          {}}

Open with explicit native options

go177B
create := true
result := stardust.Options{Create: &create, PageSize: 0}
database, err := stardust.Open(databasePath, result)
if err != nil {
	return err
}
defer database.Close()
Result / 182B
{create            true
 clear             false
 pin_memory        false
 page_size         0
 lock_timeout      0
 initial_map_bytes 0
 commit_batch      0
 plugins           null}

Wait for the database lock without a limit

go208B
create := true
result := stardust.Options{Create: &create, PageSize: 0, LockTimeout: -time.Nanosecond}
database, err := stardust.Open(databasePath, result)
if err != nil {
	return err
}
defer database.Close()
Result / 185B
{create            true
 clear             false
 pin_memory        false
 page_size         0
 lock_timeout      null
 initial_map_bytes 0
 commit_batch      0
 plugins           null}

Capture the host duration boundary

boundaryText holds this document:

dust20B
9223372036854775807

queryText holds this document:

dust58B
find    [?name]
where   [[?e name ?name]]
orderBy [?name]
go631B
definition, err := stardust.Parse(queryText, stardust.DUST)
if err != nil {
	return err
}
defer definition.Close()

query, err := db.Query(definition)
if err != nil {
	return err
}
defer query.Close()

boundary, err := stardust.Parse(boundaryText, stardust.DUST)
if err != nil {
	return err
}
defer boundary.Close()

boundaryRoot, err := boundary.Root()
if err != nil {
	return err
}
nanoseconds, err := boundary.I64(boundaryRoot)
if err != nil {
	return err
}

result := stardust.RunOptions{PageSize: 2, MaxCost: time.Duration(nanoseconds)}
rows, err := query.Run(nil, result, nil)
if err != nil {
	return err
}
defer rows.Close()
Result / 55B
{page_size 2
 max_cost  92233720368547758
 as_of     0}

Truncate a positive sub-tick duration

boundaryText holds this document:

dust3B
99

queryText holds this document:

dust58B
find    [?name]
where   [[?e name ?name]]
orderBy [?name]
go631B
definition, err := stardust.Parse(queryText, stardust.DUST)
if err != nil {
	return err
}
defer definition.Close()

query, err := db.Query(definition)
if err != nil {
	return err
}
defer query.Close()

boundary, err := stardust.Parse(boundaryText, stardust.DUST)
if err != nil {
	return err
}
defer boundary.Close()

boundaryRoot, err := boundary.Root()
if err != nil {
	return err
}
nanoseconds, err := boundary.I64(boundaryRoot)
if err != nil {
	return err
}

result := stardust.RunOptions{PageSize: 2, MaxCost: time.Duration(nanoseconds)}
rows, err := query.Run(nil, result, nil)
if err != nil {
	return err
}
defer rows.Close()
Result / 39B
{page_size 2
 max_cost  0
 as_of     0}

A negative Go duration keeps its sign at the ABI boundary

go56B
result := stardust.RunOptions{MaxCost: -time.Nanosecond}
Result / 40B
{page_size 0
 max_cost  -1
 as_of     0}

Run with typed query options

queryText holds this document:

dust58B
find    [?name]
where   [[?e name ?name]]
orderBy [?name]
go356B
definition, err := stardust.Parse(queryText, stardust.DUST)
if err != nil {
	return err
}
defer definition.Close()

query, err := db.Query(definition)
if err != nil {
	return err
}
defer query.Close()

result := stardust.RunOptions{PageSize: 2, MaxCost: time.Second}
rows, err := query.Run(nil, result, nil)
if err != nil {
	return err
}
defer rows.Close()
Result / 46B
{page_size 2
 max_cost  10000000
 as_of     0}

Read the complete initial subscription event

queryText holds this document:

dust58B
find    [?name]
where   [[?e name ?name]]
orderBy [?name]
go440B
definition, err := stardust.Parse(queryText, stardust.DUST)
if err != nil {
	return err
}
defer definition.Close()

query, err := db.Query(definition)
if err != nil {
	return err
}
defer query.Close()

subscription, err := query.Subscribe(nil, stardust.RunOptions{})
if err != nil {
	return err
}
defer subscription.Close()

result, err := subscription.Next(context.Background(), 0)
if err != nil {
	return err
}
defer result.Result.Close()
Result / 92B
{sequence    1
 superseded  0
 transaction 4
 result      [{name Ada} {name Bob} {name Cy}]}