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:

TRON449 B
00054 52 4F 4Emagic TRON
0043C 616765txt "age"
00802 24000000000000 00i64 36
0110F 0A 04000000 0800 0000map leaf, size 10: @4 → @8
01B4C 726F6C65txt "role"
0208C 656E67696E6565 72txt "engineer"
0290F 0A 1B000000 2000 0000map leaf, size 10: @1B → @20
0334C 6E616D65txt "name"
0383C 416461txt "Ada"
03C0F 0A 33000000 3800 0000map leaf, size 10: @33 → @38
04607 12 00910000 1100 0000 29000000 3C00 0000map branch, size 18, depth 0 (root), slots 8, 12, 15: @11 → @29 → @3C
0585C 236C696E6Btxt "#link"
05E5C 235F616461txt "#_ada"
0640F 0A 58000000 5E00 0000map leaf, size 10: @58 → @5E
06E3C 616765txt "age"
07202 29000000000000 00i64 41
07B0F 0A 6E000000 7200 0000map leaf, size 10: @6E → @72
0856C 6D656E746F72txt "mentor"
08C0F 0A 85000000 6400 0000map leaf, size 10: @85 → @64
0964C 726F6C65txt "role"
09B8C 656E67696E6565 72txt "engineer"
0A40F 0A 96000000 9B00 0000map leaf, size 10: @96 → @9B
0AE4C 6E616D65txt "name"
0B33C 426F62txt "Bob"
0B70F 0A AE000000 B300 0000map leaf, size 10: @AE → @B3
0C107 16 00990000 7B00 0000 8C000000 A400 0000 B7000000map branch, size 22, depth 0 (root), slots 8, 11, 12, 15: @7B → @8C → @A4 → @B7
0D73C 616765txt "age"
0DB02 1D000000000000 00i64 29
0E40F 0A D7000000 DB00 0000map leaf, size 10: @D7 → @DB
0EE4C 726F6C65txt "role"
0F38C 64657369676E65 72txt "designer"
0FC0F 0A EE000000 F300 0000map leaf, size 10: @EE → @F3
1064C 6E616D65txt "name"
10B2C 4379txt "Cy"
10E0F 0A 06010000 0B01 0000map leaf, size 10: @106 → @10B
11807 12 00910000 E400 0000 FC000000 0E01 0000map branch, size 18, depth 0 (root), slots 8, 12, 15: @E4 → @FC → @10E
12A6C 617574686F72txt "author"
1315C 736D6F6B65txt "smoke"
1370F 0A 2A010000 3101 0000map leaf, size 10: @12A → @131
1416C 726561736F6Etxt "reason"
1484C 73656564txt "seed"
14D0F 0A 41010000 4801 0000map leaf, size 10: @141 → @148
15707 0E 40080000 3701 0000 4D010000map branch, size 14, depth 0 (root), slots 6, 11: @137 → @14D
1654C 235F7478txt "#_tx"
16A0F 0A 65010000 5701 0000map leaf, size 10: @165 → @157
1744C 235F6379txt "#_cy"
1790F 0A 74010000 1801 0000map leaf, size 10: @174 → @118
1835C 235F626F62txt "#_bob"
1890F 0A 83010000 C100 0000map leaf, size 10: @183 → @C1
1935C 235F616461txt "#_ada"
1990F 0A 93010000 4600 0000map leaf, size 10: @193 → @46
1A307 16 88210000 6A01 0000 79010000 8901 0000 99010000map branch, size 22, depth 0 (root), slots 3, 7, 8, 13: @16A → @179 → @189 → @199

query_text holds this document:

TRON165 B
0054 52 4F 4Emagic TRON
045C 3F6E616D65txt "?name"
0A0E 0D 00 0100 010000 00 04000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
172C 3F65txt "?e"
1A4C 6E616D65txt "name"
1F5C 3F6E616D65txt "?name"
250E 15 00 0700 030000 00 17000000 1A0000 00 1F000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @17 → @1A → @1F
3A0E 0D 00 0100 010000 00 25000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @25
475C 3F6E616D65txt "?name"
4D0E 0D 00 0100 010000 00 47000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @47
5A5C 7768657265txt "where"
600F 0A 5A000000 3A00 0000map leaf, size 10: @5A → @3A
6A4C 66696E64txt "find"
6F0F 0A 6A000000 0A00 0000map leaf, size 10: @6A → @A
797C 6F726465724279txt "orderBy"
810F 0A 79000000 4D00 0000map leaf, size 10: @79 → @4D
8B07 12 2A000000 6000 0000 6F000000 8100 0000map branch, size 18, depth 0 (root), slots 1, 3, 5: @60 → @6F → @81
python367 B
async with (await stardust.open(database_path)) as database:
    async with (await stardust.parse(seed_text, "tron")) as seed:
        (await database.merge_patch(seed))
    async with (await stardust.parse(query_text, "tron")) as definition, (await database.query(definition)) as query, \
            (await query.run()) as rows:
        result = (await rows.next())
TRON89 B
0054 52 4F 4Emagic TRON
044C 6E616D65txt "name"
093C 416461txt "Ada"
0D0F 0A 04000000 0900 0000map leaf, size 10: @4 → @9
174C 6E616D65txt "name"
1C3C 426F62txt "Bob"
200F 0A 17000000 1C00 0000map leaf, size 10: @17 → @1C
2A4C 6E616D65txt "name"
2F2C 4379txt "Cy"
320F 0A 2A000000 2F00 0000map leaf, size 10: @2A → @2F
3C0E 15 00 0700 030000 00 0D000000 200000 00 32000000array leaf, size 21, shift 0, bitmap 0007, count 3 (root): @D → @20 → @32

Ownership and lifetimes

ValueLifetimeYour action
Owned resultUntil you release itRelease it when you finish with it.
Borrowed valueThe lifetime that its operation statesStop using it when that lifetime ends.
Owned documentContinues after you release the handle that produced itRelease 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

TermMeaning
documentA tree of native values that you can read, build, or serialize.
nodeOne value in a document, identified within that document.
handleA reference to a native resource with an explicit lifetime.
ownedA result whose lifetime you control and whose release you must arrange.
borrowedA value whose lifetime depends on its stated owner.
absentA value or field that the operation does not supply.
entityA database object identified independently of its field values.
transactionA committed database change that orders the recorded facts.
factA recorded field value associated with an entity and a transaction.
variableA named value supplied to an expression or document operation.
clauseOne part of a query or mutation document that specifies its behavior.
tickThe ABI unit for a duration or UTC instant: 100 ns. Time and units defines it.

Operations

OperationReturnsSummary
versionversionversion() returns the loaded library's ABI version.
check_versionnonecheck_version(found) verifies that found matches this binding's ABI version.
pluginsdocumentplugins() returns an owned array document describing the plugins this library can use, followed by any unavailable plugin libraries.
activatenoneactivate(token) verifies a license token and licenses this process.
licenselicenselicense() returns the process license state.

version

python49 B
def version(*, library: str | None = None) -> int

Parameters

ParameterTypeOwnershipDefaultMeaning
librarystr | NoneValueNoneLoaded native library used by this call.

Examples

version

python35 B
result = (await stardust.version())
TRON21 B
0054 52 4F 4Emagic TRON
0402 01000000000000 00i64 1

C exports: stardust_abi_version

check_version

python37 B
def check_version(found: int) -> None

Parameters

ParameterTypeOwnershipDefaultMeaning
foundintValueRequiredThe ABI version to compare with this binding.

Errors

StatusWhen
"unsupported"found differs from the ABI version of the binding

Examples

check_version

python85 B
found = (await stardust.version())
await stardust.check_version(found)
result = found
TRON21 B
0054 52 4F 4Emagic TRON
0402 01000000000000 00i64 1

C exports: stardust_abi_version

plugins

python54 B
def plugins(*, library: str | None = None) -> Document

Parameters

ParameterTypeOwnershipDefaultMeaning
librarystr | NoneValueNoneLoaded native library used by this call.

Errors

StatusWhen
"out_of_memory"native memory is exhausted

Examples

Read the compiled plugin inventory

python35 B
result = (await stardust.plugins())
TRON1.2 kB
00054 52 4F 4Emagic TRON
0047C 6261636B757073txt "backups"
00C0E 0D 00 0100 010000 00 04000000array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
0197C 76657273696F6Etxt "version"
0211C 31txt "1"
0230F 0A 19000000 2100 0000map leaf, size 10: @19 → @21
02DDC 64617461626173 65486F6F6B73txt "databaseHooks"
03B09bit true
03C0F 0A 2D000000 3B00 0000map leaf, size 10: @2D → @3B
04607 0E 00810000 2300 0000 3C000000map branch, size 14, depth 1, slots 8, 15: @23 → @3C
054FC 77696C6C4E6F74 576F726B57697468txt "willNotWorkWith"
0640F 0A 54000000 0C00 0000map leaf, size 10: @54 → @C
06E4C 6E616D65txt "name"
0737C 686973746F7279txt "history"
07B0F 0A 6E000000 7300 0000map leaf, size 10: @6E → @73
085BC 64657363726970 74696F6Etxt "description"
09114 49 486973746F72 7920726574656E74 696F6E3A20707572 67657320656E7469 747920686973746F 7279206279206561 6368207374617264 7573742F68697374 6F72792073657474 696E67txt "History retention: purge…"
0DC0F 0A 85000000 9100 0000map leaf, size 10: @85 → @91
0E607 0E 88000000 7B00 0000 DC000000map branch, size 14, depth 2, slots 3, 7: @7B → @DC
0F407 0A 02000000 E600 0000map branch, size 10, depth 1, slots 1: @E6
0FE07 12 08C00000 4600 0000 64000000 F400 0000map branch, size 18, depth 0 (root), slots 3, 14, 15: @46 → @64 → @F4
1107C 76657273696F6Etxt "version"
1181C 31txt "1"
11A0F 0A 10010000 1801 0000map leaf, size 10: @110 → @118
124DC 64617461626173 65486F6F6B73txt "databaseHooks"
13209bit true
1330F 0A 24010000 3201 0000map leaf, size 10: @124 → @132
13D07 0E 00810000 1A01 0000 33010000map branch, size 14, depth 1, slots 8, 15: @11A → @133
14B4C 6E616D65txt "name"
15014 16 616461707469 76655F7175657279 5F706C616E6E6572txt "adaptive_query_planner"
1680F 0A 4B010000 5001 0000map leaf, size 10: @14B → @150
172BC 64657363726970 74696F6Etxt "description"
Show all 85 nodes
17E14 4E 416461707469 7665206A6F696E20 6F72646572733A20 6C6561726E732066 726F6D2072756E73 20616E642073746F 7265732074686520 706C616E73207468 61742070726F7665 6420626574746572txt "Adaptive join orders: le…"
1CE0F 0A 72010000 7E01 0000map leaf, size 10: @172 → @17E
1D807 0E 88000000 6801 0000 CE010000map branch, size 14, depth 2, slots 3, 7: @168 → @1CE
1E607 0A 02000000 D801 0000map branch, size 10, depth 1, slots 1: @1D8
1F007 0E 08800000 3D01 0000 E6010000map branch, size 14, depth 0 (root), slots 3, 15: @13D → @1E6
1FE7C 76657273696F6Etxt "version"
2061C 31txt "1"
2080F 0A FE010000 0602 0000map leaf, size 10: @1FE → @206
212DC 64617461626173 65486F6F6B73txt "databaseHooks"
22009bit true
2210F 0A 12020000 2002 0000map leaf, size 10: @212 → @220
22B07 0E 00810000 0802 0000 21020000map branch, size 14, depth 1, slots 8, 15: @208 → @221
2394C 6E616D65txt "name"
23E7C 6F626A65637473txt "objects"
2460F 0A 39020000 3E02 0000map leaf, size 10: @239 → @23E
250BC 64657363726970 74696F6Etxt "description"
25C14 47 4F626A656374 2073746F72653A20 636F6E74656E742D 6164647265737365 64207061796C6F61 647320696E206E61 6D65642066696C65 7320616E64206469 726563746F726965 73txt "Object store: content-ad…"
2A50F 0A 50020000 5C02 0000map leaf, size 10: @250 → @25C
2AF07 0E 88000000 4602 0000 A5020000map branch, size 14, depth 2, slots 3, 7: @246 → @2A5
2BD07 0A 02000000 AF02 0000map branch, size 10, depth 1, slots 1: @2AF
2C707 0E 08800000 2B02 0000 BD020000map branch, size 14, depth 0 (root), slots 3, 15: @22B → @2BD
2D57C 76657273696F6Etxt "version"
2DD1C 31txt "1"
2DF0F 0A D5020000 DD02 0000map leaf, size 10: @2D5 → @2DD
2E9DC 64617461626173 65486F6F6B73txt "databaseHooks"
2F709bit true
2F80F 0A E9020000 F702 0000map leaf, size 10: @2E9 → @2F7
30207 0E 00810000 DF02 0000 F8020000map branch, size 14, depth 1, slots 8, 15: @2DF → @2F8
3104C 6E616D65txt "name"
3158C 72656163746F72 73txt "reactors"
31E0F 0A 10030000 1503 0000map leaf, size 10: @310 → @315
328BC 64657363726970 74696F6Etxt "description"
33414 41 4C697665206D 75746174696F6E73 3A2073746F726564 206D75746174696F 6E73207769746820 6C6976653A207472 7565207265616374 20746F20636F6D6D 697473txt "Live mutations: stored m…"
3770F 0A 28030000 3403 0000map leaf, size 10: @328 → @334
38107 0E 88000000 1E03 0000 77030000map branch, size 14, depth 2, slots 3, 7: @31E → @377
38F07 0A 02000000 8103 0000map branch, size 10, depth 1, slots 1: @381
39907 0E 08800000 0203 0000 8F030000map branch, size 14, depth 0 (root), slots 3, 15: @302 → @38F
3A77C 76657273696F6Etxt "version"
3AF1C 31txt "1"
3B10F 0A A7030000 AF03 0000map leaf, size 10: @3A7 → @3AF
3BBDC 64617461626173 65486F6F6B73txt "databaseHooks"
3C909bit true
3CA0F 0A BB030000 C903 0000map leaf, size 10: @3BB → @3C9
3D407 0E 00810000 B103 0000 CA030000map branch, size 14, depth 1, slots 8, 15: @3B1 → @3CA
3E24C 6E616D65txt "name"
3E73C 73646Btxt "sdk"
3EB0F 0A E2030000 E703 0000map leaf, size 10: @3E2 → @3E7
3F5BC 64657363726970 74696F6Etxt "description"
40114 5E 53444B206765 6E65726174696F6E 3A207075626C6973 6865732061207479 706564207061636B 616765206F662074 68652073746F7265 6420646566696E69 74696F6E73207768 696C652074686520 6461746162617365 206973206F70656Etxt "SDK generation: publishe…"
4610F 0A F5030000 0104 0000map leaf, size 10: @3F5 → @401
46B07 0E 88000000 EB03 0000 61040000map branch, size 14, depth 2, slots 3, 7: @3EB → @461
47907 0A 02000000 6B04 0000map branch, size 10, depth 1, slots 1: @46B
48307 0E 08800000 D403 0000 79040000map branch, size 14, depth 0 (root), slots 3, 15: @3D4 → @479
4910E 1D 00 1F00 050000 00 FE000000 F00100 00 C7020000 990300 00 83040000array leaf, size 29, shift 0, bitmap 001F, count 5 (root): @FE → @1F0 → @2C7 → @399 → @483

C exports: stardust_plugins, stardust_result_take_document, stardust_result_error, stardust_result_release

activate

python63 B
def activate(token: str, *, library: str | None = None) -> None

Parameters

ParameterTypeOwnershipDefaultMeaning
tokenstrValueRequiredThe PASETO v4.public license token text.
librarystr | NoneValueNoneLoaded native library used by this call.

Errors

StatusWhen
"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

python104 B
(await stardust.activate(Path("license.token").read_text().strip()))
result = (await stardust.license())
TRON332 B
00054 52 4F 4Emagic TRON
0045C 6275696C64txt "build"
00A00nil
00B0F 0A 04000000 0A00 0000map leaf, size 10: @4 → @A
0154C 74696572txt "tier"
01A0Ctxt ""
01B0F 0A 15000000 1A00 0000map leaf, size 10: @15 → @1A
02507 0E 20080000 0B00 0000 1B000000map branch, size 14, depth 1, slots 5, 11: @B → @1B
03314 13 726566757365 645F737570706F72 745F656E64txt "refused_support_end"
04800nil
0490F 0A 33000000 4800 0000map leaf, size 10: @33 → @48
053AC 6C6963656E7365 5F6964txt "license_id"
05E4C 74657374txt "test"
0630F 0A 53000000 5E00 0000map leaf, size 10: @53 → @5E
06D07 0E 08020000 4900 0000 63000000map branch, size 14, depth 1, slots 3, 9: @49 → @63
07B7C 6661696C757265txt "failure"
0834C 6E6F6E65txt "none"
0880F 0A 7B000000 8300 0000map leaf, size 10: @7B → @83
0927C 6C6963656E7365txt "license"
09A0Ctxt ""
09B0F 0A 92000000 9A00 0000map leaf, size 10: @92 → @9A
0A57C 7375626A656374txt "subject"
0AD4C 74657374txt "test"
0B20F 0A A5000000 AD00 0000map leaf, size 10: @A5 → @AD
0BCBC 737570706F7274 5F656E64txt "support_end"
0C802 00C0489F6ADB01 01i64 72580320000000000
0D10F 0A BC000000 C800 0000map leaf, size 10: @BC → @C8
0DB6C 616374697665txt "active"
0E209bit true
0E30F 0A DB000000 E200 0000map leaf, size 10: @DB → @E2
0ED4C 6E616D65txt "name"
0F20Ctxt ""
0F30F 0A ED000000 F200 0000map leaf, size 10: @ED → @F2
0FD7C 65787069726573txt "expires"
10500nil
1060F 0A FD000000 0501 0000map leaf, size 10: @FD → @105
11007 0E 06000000 F300 0000 06010000map branch, size 14, depth 1, slots 1, 2: @F3 → @106
11E07 26 219F0000 2500 0000 6D000000 8800 0000 9B000000 B200 0000 D1000000 E300 0000 10010000map branch, size 38, depth 0 (root), slots 0, 5, 8, 9, 10, 11, 12, 15: @25 → @6D → @88 → @9B → @B2 → @D1 → @E3 → @110

C exports: stardust_activate, stardust_license

license

python57 B
def license(*, library: str | None = None) -> LicenseInfo

Parameters

ParameterTypeOwnershipDefaultMeaning
librarystr | NoneValueNoneLoaded native library used by this call.

Examples

Read the process license

python35 B
result = (await stardust.license())
TRON332 B
00054 52 4F 4Emagic TRON
0045C 6275696C64txt "build"
00A00nil
00B0F 0A 04000000 0A00 0000map leaf, size 10: @4 → @A
0154C 74696572txt "tier"
01A0Ctxt ""
01B0F 0A 15000000 1A00 0000map leaf, size 10: @15 → @1A
02507 0E 20080000 0B00 0000 1B000000map branch, size 14, depth 1, slots 5, 11: @B → @1B
03314 13 726566757365 645F737570706F72 745F656E64txt "refused_support_end"
04800nil
0490F 0A 33000000 4800 0000map leaf, size 10: @33 → @48
053AC 6C6963656E7365 5F6964txt "license_id"
05E4C 74657374txt "test"
0630F 0A 53000000 5E00 0000map leaf, size 10: @53 → @5E
06D07 0E 08020000 4900 0000 63000000map branch, size 14, depth 1, slots 3, 9: @49 → @63
07B7C 6661696C757265txt "failure"
0834C 6E6F6E65txt "none"
0880F 0A 7B000000 8300 0000map leaf, size 10: @7B → @83
0927C 6C6963656E7365txt "license"
09A0Ctxt ""
09B0F 0A 92000000 9A00 0000map leaf, size 10: @92 → @9A
0A57C 7375626A656374txt "subject"
0AD4C 74657374txt "test"
0B20F 0A A5000000 AD00 0000map leaf, size 10: @A5 → @AD
0BCBC 737570706F7274 5F656E64txt "support_end"
0C802 00C0489F6ADB01 01i64 72580320000000000
0D10F 0A BC000000 C800 0000map leaf, size 10: @BC → @C8
0DB6C 616374697665txt "active"
0E209bit true
0E30F 0A DB000000 E200 0000map leaf, size 10: @DB → @E2
0ED4C 6E616D65txt "name"
0F20Ctxt ""
0F30F 0A ED000000 F200 0000map leaf, size 10: @ED → @F2
0FD7C 65787069726573txt "expires"
10500nil
1060F 0A FD000000 0501 0000map leaf, size 10: @FD → @105
11007 0E 06000000 F300 0000 06010000map branch, size 14, depth 1, slots 1, 2: @F3 → @106
11E07 26 219F0000 2500 0000 6D000000 8800 0000 9B000000 B200 0000 D1000000 E300 0000 10010000map branch, size 38, depth 0 (root), slots 0, 5, 8, 9, 10, 11, 12, 15: @25 → @6D → @88 → @9B → @B2 → @D1 → @E3 → @110

C exports: stardust_license

license_info

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

FieldTypeUnitRangeAbsentMeaning
activeboolNoneHost type range—The process holds a verified license.
failurestrNoneHost type range—Why the last activation failed; none when it succeeded or none was tried.
support_enddatetime | NoneUTC instant (100 ns ticks since the Unix epoch at the ABI)Tick rangeNoneThe last build date the license covers, as a UTC instant.
expiresdatetime | NoneUTC instant (100 ns ticks since the Unix epoch at the ABI)Tick rangeNoneThe expiry checked at activation and database open, as a UTC instant. Existing resources keep working.
builddatetime | NoneUTC instant (100 ns ticks since the Unix epoch at the ABI)Tick rangeNoneThe build date of this library, at UTC midnight.
refused_support_enddatetime | NoneUTC instant (100 ns ticks since the Unix epoch at the ABI)Tick rangeNoneThe support end of the token the last activation refused as support_ended, as a UTC instant.
subjectstrNoneHost type range—The OAuth sign-in identity of the license. Empty when not active.
license_idstrNoneHost type range—The unique license token ID. Empty when not active.
namestrNoneHost type range—The project name, or account display name for Community. Empty when absent.
licensestrNoneHost type range—The ID of the purchased license, a ULID. Empty when absent.
tierstrNoneHost type range—The license tier: community, solo or team. Empty when absent.