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

Use	When you want to
Language values (encode, decode, typed rows)	Write and read ordinary application data in the types of your language.
Documents	Reuse a value in several calls without converting it again, keep duplicate keys and member order exactly, or batch native work.
Parse and serialize	Read or write text or bytes at a file or network boundary. See Formats and conversion.
Builders and node reads	Construct or walk documents node by node. See Documents and Building documents.

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:

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]

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_DUST, &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_DUST, &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 / 33 B

[{name Ada} {name Bob} {name Cy}]

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

Operation	Returns	Summary
from_value	Unavailable	from_value(value) copies host values into an owned document.
to_value	Unavailable	document.to_value() copies a document into host values.

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

Value	Rule
`standard`	Every value that the language's standard JSON encoder accepts converts: encoding/json in Go, json.dumps in Python, `serde_json` in Rust, cheshire or data.json in Clojure and core:encoding/json in Odin. Decode reads back what encode writes. Refusals remain only where that encoder refuses, or where a document cannot hold the value: a non-finite number, an integer outside `i64`, an inexact decimal, instant or duration, and a cycle.
`null`	A nullable target (pointer, option, Maybe, nil slice or map, None, nil) accepts null. A non-nullable target refuses it with `wrong_kind`. Explicit null is not a missing field.
`boolean`	Only booleans: no truthiness and no number or string coercion.
`integer`	Numbers are `i64` or `f64`. A host integer of any width or signedness converts when it fits `i64`; a larger one fails with `out_of_range`, in both directions. Narrower targets are range-checked (`out_of_range`).
`real`	Finite `f64` only; NaN and infinities are refused. An integer decodes into a floating target only when exactly representable, and a real into an integer target only when finite, integral and in range. f32 narrowing refuses overflow and rounds to nearest. An exact decimal (Python Decimal, Clojure BigDecimal) is an `i64` when integral and in range, otherwise the `f64` of its shortest spelling; any other decimal fails with `inexact_number`.
`text`	Valid UTF-8, copied without normalization. Invalid UTF-8 and unpaired surrogates are refused. A string argument is a string value; it is never parsed as document text. Values that the standard JSON encoder writes as text stay text: UUIDs, dates and times that are not instants, Go TextMarshaler values, and Go and Clojure byte arrays as base64. Text that does not parse as a typed target fails with `invalid_value`.
`array`	Ordered collections, including tuples, sets and Java collections. A fixed-length target needs the exact length (`length_mismatch`). A nil slice or list encodes null; an allocated empty one encodes an empty array.
`object`	Struct, record or dataclass fields and maps. Field names follow the standard encoder's tags and embedding rules; Go also matches a key case-insensitively after an exact match, as encoding/json does. Map keys that are not strings become member keys as the standard encoder spells them (decimal integers, true, false, enum names, MarshalText text) and parse back into typed keys. Typed decode refuses a repeated key (`duplicate_field`); native documents keep both members. Unknown keys are ignored unless strict mode refuses them (`unknown_field`). A missing field keeps the language default or fails as required (`missing_field`).
`enum`	Enums use the standard encoder's form: Rust variants as serde represents them, Python Enum members as their value, Odin enums by name. Odin unions write their active variant and decode into the one variant whose shape matches (`ambiguous_variant` otherwise).
`tagged`	Native tags take priority over any JSON spelling. Links, UTC instants and durations use the native {#link id}, {#utc text} and {#dur text} objects through the Link type and standard-library instant and duration types. Rust uses #[serde(with = "stardust::Utc")] and #[serde(with = "stardust::Dur")] field adapters to select native tags without guessing from record names. Extra types are only for native values that the standard library cannot represent, such as signed Rust durations. An ordinary object is never reinterpreted as a tagged value. A time value that is not a whole number of 100 ns ticks is refused. Direct converters report `inexact_number`; Rust Serde adapter errors use the custom-hook codes `unsupported_type` on encode and `wrong_kind` on decode, with the field path.
`hooks`	Conversion methods run as the standard encoder runs them: Go Encoder and Decoder hooks first, then json.Marshaler, encoding.TextMarshaler and their decode methods; Rust Serialize and Deserialize; Odin registered converters. A failing Go JSON or text method fails with `hook_failed`; other hooks return their own error. Only Go's JSON methods exchange JSON text, through the native JSON codec.
`limits`	Recursive conversions refuse nesting beyond the depth limit with `too_deep`. Go and Python untyped decode traverse iteratively and accept deeper documents. Cyclic host values fail with cycle, or `too_deep` in Clojure. Every failure has status `invalid_argument`, a code and a value path such as people[3].age or tags["a.b"]. Failed conversions return no partial value or document.

Host mapping

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