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:

dust

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

dust

58 B

find    [?name]
where   [[?e name ?name]]
orderBy [?name]

python

367 B

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

Result / 33 B

[{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 / 1 B

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 / 1 B

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 / 844 B

[{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 / 293 B

{active              true
 failure             none
 support_end         72580320000000000
 expires             null
 build               null
 refused_support_end null
 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 / 293 B

{active              true
 failure             none
 support_end         72580320000000000
 expires             null
 build               null
 refused_support_end null
 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.