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

python

365 B

async with (await stardust.open(database_path)) as database:
    async with (await stardust.parse(seed_text, "edn")) as seed:
        (await database.merge_patch(seed))
    async with (await stardust.parse(query_text, "edn")) as definition, (await database.query(definition)) as query, \
            (await query.run()) as rows:
        result = (await rows.next())

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

python

49 B

def version(*, library: str | None = None) -> int

Parameters

Parameter	Type	Ownership	Default	Meaning
`library`	`str \| None`	Value	None	Loaded native library used by this call.

Examples

version

python

35 B

result = (await stardust.version())

Result / 10 B

{:value 1}

C exports: stardust_abi_version

check_version

python

37 B

def check_version(found: int) -> None

Parameters

Parameter	Type	Ownership	Default	Meaning
`found`	`int`	Value	Required	The ABI version to compare with this binding.

Errors

Status	When
`"unsupported"`	found differs from the ABI version of the binding

Examples

check_version

python

85 B

found = (await stardust.version())
await stardust.check_version(found)
result = found

Result / 10 B

{:value 1}

C exports: stardust_abi_version

plugins

python

54 B

def plugins(*, library: str | None = None) -> Document

Parameters

Parameter	Type	Ownership	Default	Meaning
`library`	`str \| None`	Value	None	Loaded native library used by this call.

Errors

Status	When
`"out_of_memory"`	native memory is exhausted

Examples

Read the compiled plugin inventory

python

35 B

result = (await stardust.plugins())

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

python

63 B

def activate(token: str, *, library: str | None = None) -> None

Parameters

Parameter	Type	Ownership	Default	Meaning
`token`	`str`	Value	Required	The PASETO v4.public license token text.
`library`	`str \| None`	Value	None	Loaded native library used by this call.

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

python

104 B

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

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

python

57 B

def license(*, library: str | None = None) -> LicenseInfo

Parameters

Parameter	Type	Ownership	Default	Meaning
`library`	`str \| None`	Value	None	Loaded native library used by this call.

Examples

Read the process license

python

35 B

result = (await stardust.license())

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`	`str`	None	Host type range	—	Why the last activation failed; none when it succeeded or none was tried.
`support_end`	`datetime \| None`	UTC instant (100 ns ticks since the Unix epoch at the ABI)	Tick range	None	The last build date the license covers, as a UTC instant.
`expires`	`datetime \| None`	UTC instant (100 ns ticks since the Unix epoch at the ABI)	Tick range	None	The expiry checked at activation and database open, as a UTC instant. Existing resources keep working.
`build`	`datetime \| None`	UTC instant (100 ns ticks since the Unix epoch at the ABI)	Tick range	None	The build date of this library, at UTC midnight.
`refused_support_end`	`datetime \| None`	UTC instant (100 ns ticks since the Unix epoch at the ABI)	Tick range	None	The support end of the token the last activation refused as `support_ended`, as a UTC instant.
`subject`	`str`	None	Host type range	—	The OAuth sign-in identity of the license. Empty when not active.
`license_id`	`str`	None	Host type range	—	The unique license token ID. Empty when not active.
`name`	`str`	None	Host type range	—	The project name, or account display name for Community. Empty when absent.
`license`	`str`	None	Host type range	—	The ID of the purchased license, a ULID. Empty when absent.
`tier`	`str`	None	Host type range	—	The license tier: community, solo or team. Empty when absent.