Language values and documents#

Your application keeps its own structs, records, dataclasses and maps. The typed layer copies them into native documents and copies documents back into them. The native document API stays available beside it for work that needs native fidelity or no conversion.

Choose an interface#

Example#

The example stores three people from language values, runs a query written in the selected format, and decodes each row into a value of the language. The captured result is the decoded rows, encoded again for display.

Store people and query their names (C uses native documents)#

seed_text holds this document:

query_text holds this document:

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_TRON, &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_TRON, &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;}

Standard JSON values#

Any value that the standard JSON encoder of your language accepts also converts here, and decode reads back what encode writes: encoding/json in Go, json.dumps in Python, serde_json in Rust, cheshire or data.json in Clojure and core:encoding/json in Odin. Native tags come first, so instants, durations and links become #utc, #dur and #link values instead of JSON text. Several languages accept more, such as Python sets and UUIDs, or Clojure java.time values. A value is refused only where that encoder refuses it, or where a document cannot hold it: a non-finite number, an integer outside i64, a decimal, instant or duration without an exact native form, or a cycle. The host mapping gives each type.

Ownership and errors#

Encode returns a new owned document that holds a snapshot of the value. Close it as you close any document. Decode borrows a document only for the call and returns independent values. It never closes or keeps the document. Typed row iteration borrows the rows and reads one page at a time. Close the rows yourself. Every page of one cursor reads the same store snapshot, so iteration never repeats the query.

A value-argument operation accepts a language value or a document. It passes a document through unchanged. It encodes a language value into a temporary document, calls the native operation once, and closes the temporary document on success and failure.

A conversion failure is invalid_argument with a code and a value path such as people[1].age. A failed decode returns no partly filled value.

Costs#

Encode and decode copy every value. A document that you pass directly is not copied. Type inspection belongs only to the typed layer, and each language keeps per-type plans where it inspects types at run time. No conversion writes or reads DUST, EDN or TRON text, and JSON text appears only where a Go value supplies its own MarshalJSON or UnmarshalJSON method. Those formats are optional boundaries, not an intermediate transport.

The conversion rules and the host mapping below give each type, the null and missing-field rules and the strict mode.

Operations#

from_value#

C has no host value model. Use native document builders.

Also calls: stardust_document_builder_create, stardust_document_builder_add_many, stardust_document_builder_seal, stardust_document_builder_error, stardust_document_builder_release

to_value#

C has no host value model. Use native typed reads.

Also calls: stardust_document_count, stardust_document_read_many, stardust_document_i64, stardust_document_f64

Typed operations#

C has no language-generic typed layer. Construct documents with Building documents, read them with Documents, and pass document handles to native operations. The generated bindings/c/stardust_time.h header converts native ticks and time-tag text to and from standard struct timespec values. The SDK uses these helpers for generated time fields.

Conversion rules#

Host mapping#

C has no host-value conversion. Use a document handle and the typed reads on the Documents page.