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.

Clojure conversion#

Clojure uses java.time.Duration and java.time.Instant.

• A Duration converts to ticks from its seconds and nanoseconds. Sub-tick nanoseconds round toward negative infinity, so a negative duration stays negative.
• A Duration beyond the i64 tick range saturates.
• Ticks convert to a Duration or an Instant exactly.
• nil 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#

(do (sd/activate (string/trim (slurp "license.token")))
    (sd/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#

(let [input {:parent nil :kind :number :number 41 :boolean false :key "" :text ""}]
  (with-open [builder (sd/builder)]
    (sd/add builder input))
  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"}}

(with-open [patch (sd/parse seed-text :edn)]
  (sd/merge-patch db patch))

{:value {:status       "committed"
         :transaction  4
         :facts        12
         :committed_at 17923367746759674
         :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}}}

(with-open [source (sd/parse birthday-text :edn)
            mutation (sd/mutation db source)]
  (sd/run mutation))

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

database/patch_definition#

definition-text holds this document:

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

(with-open [definition (sd/parse definition-text :edn)]
  (sd/patch-definition db :queries "people/by_role" definition))

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

document/read#

input-text holds this document:

{:x 41}

(with-open [source (sd/parse input-text :edn)]
  (sd/read source (sd/root source)))

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

(with-open [source (sd/parse input-text :edn)]
  (first (sd/read-many source (sd/root source) 1)))

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

Read the process license#

(sd/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}}}

(with-open [source (sd/parse birthday-text :edn)
            mutation (sd/mutation db source)]
  (sd/run mutation))

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

mutation/run#

birthday-text holds this document:

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

(with-open [source (sd/parse birthday-text :edn)
            mutation (sd/mutation db source)]
  (sd/run mutation))

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

Open with explicit native options#

(let [options {:create? true :clear? false :pin-memory? false :page-size 0
               :lock-timeout java.time.Duration/ZERO :initial-map-bytes 0
               :commit-batch java.time.Duration/ZERO :plugins nil
               :memory-budget-bytes 0}]
  (with-open [database (sd/open database-path 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#

(let [options {:create? true :clear? false :pin-memory? false :page-size 0
               :lock-timeout (java.time.Duration/ofNanos -1) :initial-map-bytes 0
               :commit-batch java.time.Duration/ZERO :plugins nil
               :memory-budget-bytes 0}]
  (with-open [database (sd/open database-path 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:

9223372036854775807

query-text holds this document:

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

(with-open [boundary (sd/parse boundary-text :edn)
            definition (sd/parse query-text :edn)
            query (sd/query db definition)]
  (let [max-cost (java.time.Duration/ofSeconds (sd/i64 boundary (sd/root boundary)))
        options {:page-size 2 :max-cost max-cost :as-of 0}]
    (with-open [rows (sd/run query nil options)]
      options)))

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

Truncate a positive sub-tick duration#

boundary-text holds this document:

99

query-text holds this document:

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

(with-open [boundary (sd/parse boundary-text :edn)
            definition (sd/parse query-text :edn)
            query (sd/query db definition)]
  (let [max-cost (java.time.Duration/ofNanos (sd/i64 boundary (sd/root boundary)))
        options {:page-size 2 :max-cost max-cost :as-of 0}]
    (with-open [rows (sd/run query nil options)]
      options)))

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

A negative sub-tick Java duration rounds toward negative infinity#

{:page-size 0 :max-cost (java.time.Duration/ofNanos -1) :as-of 0}

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

Run with typed query options#

query-text holds this document:

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

(let [options {:page-size 2 :max-cost (java.time.Duration/ofSeconds 1) :as-of 0}]
  (with-open [definition (sd/parse query-text :edn)
              query (sd/query db definition)
              rows (sd/run query nil options)]
    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]}

(with-open [definition (sd/parse query-text :edn)
            query (sd/query db definition)
            subscription (sd/subscribe query)]
  (or (sd/next subscription (java.time.Duration/ofSeconds 5))
      (throw (java.util.concurrent.TimeoutException.))))

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