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

1.5 kB

stardust_db *opened = NULL;
stardust_document *seed = NULL;
stardust_document *definition = NULL;
stardust_result *seeded = NULL;
stardust_db_query *query = NULL;
stardust_db_rows *rows = NULL;
stardust_result *page = NULL;
stardust_document *result = NULL;
stardust_bytes path = {(const uint8_t *)database_path, (int64_t)strlen(database_path)};
stardust_result *opening = NULL;
uint32_t status = stardust_db_open(path, NULL, &opened, &opening);
stardust_result_release(opening);
if (status == STARDUST_OK) status = stardust_parse(seed_text, STARDUST_JSON, &seed);
if (status == STARDUST_OK) status = stardust_db_merge_patch(opened, seed, NULL, NULL, &seeded);
if (status == STARDUST_OK) status = stardust_parse(query_text, STARDUST_JSON, &definition);
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
if (status == STARDUST_OK) status = stardust_db_query_open(opened, &source, &query);
if (status == STARDUST_OK) status = stardust_db_query_run(query, NULL, NULL, NULL, &rows);
if (status == STARDUST_OK) status = stardust_db_rows_next(rows, &page);
if (status == STARDUST_OK) status = stardust_result_take_document(page, &result);
stardust_result_release(page);
stardust_db_rows_release(rows);
stardust_db_query_release(query);
stardust_document_release(definition);
stardust_result_release(seeded);
stardust_document_release(seed);
stardust_db_close(opened);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

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
stardust_abi_version	`uint32_t`	version() returns the loaded library's ABI version.
check_version	Unavailable	check_version(found) verifies that found matches this binding's ABI version.
stardust_plugins	Status. document through output	plugins() returns an owned array document describing the plugins this library can use, followed by any unavailable plugin libraries.
stardust_activate	Status. none through output	activate(token) verifies a license token and licenses this process.
stardust_license	Status. license through output	license() returns the process license state.

stardust_abi_version

36 B

uint32_t stardust_abi_version(void);

Parameters

This call has no parameters.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

Examples

version

40 B

int64_t result = stardust_abi_version();

Result / 1 B

version

128 B

uint32_t found = stardust_abi_version();
if (found != STARDUST_ABI_VERSION) return STARDUST_UNSUPPORTED;
int64_t result = found;

Result / 1 B

check_version

Compare stardust_abi_version with STARDUST_ABI_VERSION.

Also calls: stardust_abi_version

stardust_plugins

52 B

uint32_t stardust_plugins(stardust_result **output);

92 B

uint32_t stardust_result_take_document(stardust_result *result, stardust_document **output);

96 B

uint32_t stardust_result_error(const stardust_result *result, stardust_diagnostic_view *output);

54 B

void stardust_result_release(stardust_result *result);

Parameters

stardust_plugins

Parameter	Type	Ownership	Default	Meaning
`output`	`stardust_result **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_take_document

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_document **`	Owned output	Required	Receives a library-owned handle. Release it after use.

stardust_result_error

Parameter	Type	Ownership	Default	Meaning
`result`	`const stardust_result *`	Borrowed handle	Required	Keep the handle alive until the call returns.
`output`	`stardust_diagnostic_view *`	Caller-owned output	Required	Receives a record. Its pointer fields follow the record's ownership contract.

stardust_result_release

Parameter	Type	Ownership	Default	Meaning
`result`	`stardust_result *`	Consumed handle	NULL	Ends ownership. Do not use the handle after this call.

Errors

Status	When
`STARDUST_OUT_OF_MEMORY`	native memory is exhausted
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

Examples

Read the compiled plugin inventory

318 B

stardust_result *inventory = NULL;
stardust_document *result = NULL;
uint32_t status = stardust_plugins(&inventory);
if (status == STARDUST_OK) status = stardust_result_take_document(inventory, &result);
stardust_result_release(inventory);
if (status != STARDUST_OK) {stardust_document_release(result); return status;}

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

Also calls: stardust_result_take_document, stardust_result_error, stardust_result_release

stardust_activate

49 B

uint32_t stardust_activate(stardust_bytes token);

57 B

uint32_t stardust_license(stardust_license_view *output);

Parameters

stardust_activate

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

stardust_license

Parameter	Type	Ownership	Default	Meaning
`output`	`stardust_license_view *`	Caller-owned output	Required	Initialize its size/version header. Returned pointers borrow the source owner.

Errors

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

569 B

char token[4097];
FILE *file = fopen("license.token", "rb");
if (file == NULL) return STARDUST_INVALID_ARGUMENT;
size_t length = fread(token, 1, sizeof token, file);
fclose(file);
while (length > 0 && (token[length - 1] == '\n' || token[length - 1] == '\r')) length--;
stardust_bytes bytes = {(const uint8_t *)token, (int64_t)length};
stardust_license_view result = {.size = sizeof(stardust_license_view), .version = 1};
uint32_t status = stardust_activate(bytes);
if (status == STARDUST_OK) status = stardust_license(&result);
if (status != STARDUST_OK) return status;

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

Also calls: stardust_license

stardust_license

57 B

uint32_t stardust_license(stardust_license_view *output);

Parameters

Parameter	Type	Ownership	Default	Meaning
`output`	`stardust_license_view *`	Caller-owned output	Required	Initialize its size/version header. Returned pointers borrow the source owner.

Errors

Status	When
`STARDUST_INVALID_ARGUMENT`	a required input or output pointer is NULL, or an input owner is not ready

Examples

Read the process license

172 B

stardust_license_view result = {.size = sizeof(stardust_license_view), .version = 1};
uint32_t status = stardust_license(&result);
if (status != STARDUST_OK) return status;

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

stardust_license_view

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

Note

Supply size and version with each record. NULL options select the defaults of the call.

Field	C type	Unit	Range	Default	Meaning
`size`	`uint32_t`	Bytes	Unsigned u32	Required: sizeof(stardust_license_view)	—
`version`	`uint32_t`	None	Unsigned u32	Required: 1	—
`active`	`uint32_t`	None	Unsigned u32	The call sets it	The process holds a verified license.
`failure`	`uint32_t`	None	Unsigned u32	The call sets it	Why the last activation failed; none when it succeeded or none was tried.
`support_end_ticks`	`int64_t`	100 ns ticks	Signed i64	The call sets it	The last build date the license covers, as a UTC instant.
`expires_ticks`	`int64_t`	100 ns ticks	Signed i64	The call sets it	The expiry checked at activation and database open, as a UTC instant. Existing resources keep working.
`build_ticks`	`int64_t`	100 ns ticks	Signed i64	The call sets it	The build date of this library, at UTC midnight.
`refused_support_end_ticks`	`int64_t`	100 ns ticks	Signed i64	The call sets it	The support end of the token the last activation refused as `support_ended`, as a UTC instant.
`subject`	`stardust_bytes`	None	C type range	The call sets it	The OAuth sign-in identity of the license. Empty when not active.
`license_id`	`stardust_bytes`	None	C type range	The call sets it	The unique license token ID. Empty when not active.
`name`	`stardust_bytes`	None	C type range	The call sets it	The project name, or account display name for Community. Empty when absent.
`license`	`stardust_bytes`	None	C type range	The call sets it	The ID of the purchased license, a ULID. Empty when absent.
`tier`	`stardust_bytes`	None	C type range	The call sets it	The license tier: community, solo or team. Empty when absent.