Overview

You start with the people document, store its entities, and read their names through a query. Later pages use the same people to explain each step of that sequence.

Before you create resources, activate the core with your license token.

Example

The example follows the complete call sequence, including the release of each result.

Store people and query their names

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"}}

query_text holds this document:

edn

66 B

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

odin

565 B

database := stardust.open(database_path) or_return
defer stardust.close(&database)

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

commit := stardust.merge_patch(database, seed) or_return
defer stardust.close(&commit)

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

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

rows := stardust.run(query) or_return
defer stardust.close(&rows)

result := stardust.next(rows) or_return
defer stardust.close(&result)

Result / 51 B

{:value [{:name "Ada"} {:name "Bob"} {:name "Cy"}]}

Ownership and lifetimes

Value	Lifetime	Your action
Owned result	Until you release it	Release it when you finish with it.
Borrowed value	The lifetime that its operation states	Stop using it when that lifetime ends.
Owned document	Continues after you release the handle that produced it	Release it separately from that handle.

Each operation states its ownership rule. Use that rule to find the values that you must release.

Concurrency

Calls can overlap unless an operation requires exclusive use of its receiver. Each such operation states that requirement beside its signature.

Before you release a handle, stop the calls that can still use it.
An owned result has its own lifetime, so another call can use it after its producer finishes.

Terms

Term	Meaning
document	A tree of native values that you can read, build, or serialize.
node	One value in a document, identified within that document.
handle	A reference to a native resource with an explicit lifetime.
owned	A result whose lifetime you control and whose release you must arrange.
borrowed	A value whose lifetime depends on its stated owner.
absent	A value or field that the operation does not supply.
entity	A database object identified independently of its field values.
transaction	A committed database change that orders the recorded facts.
fact	A recorded field value associated with an entity and a transaction.
variable	A named value supplied to an expression or document operation.
clause	One part of a query or mutation document that specifies its behavior.
tick	The ABI unit for a duration or UTC instant: 100 ns. Time and units defines it.

Operations

Operation	Returns	Summary
version	version	version() returns the loaded library's ABI version.
check_version	none	check_version(found) verifies that found matches this binding's ABI version.
plugins	document	plugins() returns an owned array document describing the plugins this library can use, followed by any unavailable plugin libraries.
activate	none	activate(token) verifies a license token and licenses this process.
license	license	license() returns the process license state.

version

odin

24 B

version :: proc() -> u32

Examples

version

odin

33 B

result := i64(stardust.version())

Result / 10 B

{:value 1}

C exports: stardust_abi_version

check_version

odin

74 B

check_version :: proc(found: u32, allocator := context.allocator) -> Error

Parameters

Parameter	Type	Ownership	Default	Meaning
`found`	`u32`	Value	Required	The ABI version to compare with this binding.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Unsupported`	found differs from the ABI version of the binding

Examples

check_version

odin

88 B

found := stardust.version()
stardust.check_version(found) or_return
result := i64(found)

Result / 10 B

{:value 1}

C exports: stardust_abi_version

plugins

odin

68 B

plugins :: proc(allocator := context.allocator) -> (Document, Error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Out_Of_Memory`	native memory is exhausted

Examples

Read the compiled plugin inventory

odin

68 B

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

Result / 940 B

{:value [
   {:name            "history"
    :description     "History retention: purges entity history by each stardust/history setting"
    :version         "1"
    :willNotWorkWith ["backups"]
    :databaseHooks   true}
   {:name          "adaptive_query_planner"
    :description   "Adaptive join orders: learns from runs and stores the plans that proved better"
    :version       "1"
    :databaseHooks true}
   {:name          "objects"
    :description   "Object store: content-addressed payloads in named files and directories"
    :version       "1"
    :databaseHooks true}
   {:name          "reactors"
    :description   "Live mutations: stored mutations with live: true react to commits"
    :version       "1"
    :databaseHooks true}
   {:name          "sdk"
    :description   "SDK generation: publishes a typed package of the stored definitions while the database is open"
    :version       "1"
    :databaseHooks true}]}

C exports: stardust_plugins, stardust_result_take_document, stardust_result_error, stardust_result_release

activate

odin

72 B

activate :: proc(token: string, allocator := context.allocator) -> Error

Parameters

Parameter	Type	Ownership	Default	Meaning
`token`	`string`	Value	Required	The PASETO v4.public license token text.
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Errors

Status	When
`.Unlicensed`	the token is refused; the error names the reason
`.Invalid_Argument`	the token is empty or longer than 4096 bytes

Notes

A refused token preserves the current license. Activation is required before parsing, building resources or opening a database. Existing resources keep working after license replacement or expiry.

Examples

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                ""}}

C exports: stardust_activate, stardust_license

license

odin

72 B

license :: proc(allocator := context.allocator) -> (License_Info, Error)

Parameters

Parameter	Type	Ownership	Default	Meaning
`allocator`	`mem.Allocator`	Value	context.allocator	Allocator for copied return values and diagnostics. The caller releases them with the same allocator.

Examples

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                ""}}

C exports: stardust_license

license_info

This record contains the result of license. Text fields are copies.

Field	Type	Unit	Range	Absent	Meaning
`active`	`bool`	None	Host type range	—	The process holds a verified license.
`failure`	`string`	None	Host type range	—	Why the last activation failed; none when it succeeded or none was tried.
`support_end`	`time.Time`	UTC instant (100 ns ticks since the Unix epoch at the ABI)	Tick range	The zero time.Time	The last build date the license covers, as a UTC instant.
`expires`	`time.Time`	UTC instant (100 ns ticks since the Unix epoch at the ABI)	Tick range	The zero time.Time	The expiry checked at activation and database open, as a UTC instant. Existing resources keep working.
`build`	`time.Time`	UTC instant (100 ns ticks since the Unix epoch at the ABI)	Tick range	The zero time.Time	The build date of this library, at UTC midnight.
`refused_support_end`	`time.Time`	UTC instant (100 ns ticks since the Unix epoch at the ABI)	Tick range	The zero time.Time	The support end of the token the last activation refused as `support_ended`, as a UTC instant.
`subject`	`string`	None	Host type range	—	The OAuth sign-in identity of the license. Empty when not active.
`license_id`	`string`	None	Host type range	—	The unique license token ID. Empty when not active.
`name`	`string`	None	Host type range	—	The project name, or account display name for Community. Empty when absent.
`license`	`string`	None	Host type range	—	The ID of the purchased license, a ULID. Empty when absent.
`tier`	`string`	None	Host type range	—	The license tier: community, solo or team. Empty when absent.