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:

json

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

json

134 B

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

rust

404 B

let database = stardust::open(database_path, &stardust::Options::default())?;
let seed = stardust::parse(seed_text, Format::JSON)?;
database.merge_patch(&seed, None)?;
let definition = stardust::parse(query_text, Format::JSON)?;
let query = database.query(&definition)?;
let mut rows = query.run(None, &RunOptions::default(), None)?;
let result = rows.next_page()?;
drop((rows, query));
database.close();

Result / 82 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

rust

23 B

pub fn version() -> u32

Examples

version

rust

44 B

let result = i64::from(stardust::version());

Result / 1 B

C exports: stardust_abi_version

check_version

rust

46 B

pub fn check_version(found: u32) -> Result<()>

Parameters

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

Errors

Status	When
`Status::UNSUPPORTED`	found differs from the ABI version of the binding

Examples

check_version

rust

96 B

let found = stardust::version();
stardust::check_version(found)?;
let result = i64::from(found);

Result / 1 B

C exports: stardust_abi_version

plugins

rust

36 B

pub fn plugins() -> Result<Document>

Errors

Status	When
`Status::OUT_OF_MEMORY`	native memory is exhausted

Examples

Read the compiled plugin inventory

rust

34 B

let result = stardust::plugins()?;

Result / 948 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

rust

42 B

pub fn activate(token: &str) -> Result<()>

Parameters

Parameter	Type	Ownership	Default	Meaning
`token`	`&str`	Value	Required	The PASETO v4.public license token text.

Errors

Status	When
`Status::UNLICENSED`	the token is refused; the error names the reason
`Status::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

rust

124 B

let token = std::fs::read_to_string("license.token")?;
stardust::activate(token.trim())?;
let result = stardust::license()?;

Result / 234 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

rust

39 B

pub fn license() -> Result<LicenseInfo>

Examples

Read the process license

rust

34 B

let result = stardust::license()?;

Result / 234 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`	`String`	None	Host type range	—	Why the last activation failed; none when it succeeded or none was tried.
`support_end`	`Option<SystemTime>`	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`	`Option<SystemTime>`	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`	`Option<SystemTime>`	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`	`Option<SystemTime>`	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`	`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.