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.

Example

The example follows the complete call sequence, including the release of each result.

Store people and query their names

seedText holds this document:

dust

232B

#_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}

queryText holds this document:

dust

58B

find    [?name]
where   [[?e name ?name]]
orderBy [?name]

678B

opened, err := stardust.Open(databasePath, stardust.Options{})
if err != nil {
	return err
}
defer opened.Close()

seed, err := stardust.Parse(seedText, stardust.DUST)
if err != nil {
	return err
}
defer seed.Close()

if _, err := opened.MergePatch(seed, nil); err != nil {
	return err
}

definition, err := stardust.Parse(queryText, stardust.DUST)
if err != nil {
	return err
}
defer definition.Close()

query, err := opened.Query(definition)
if err != nil {
	return err
}
defer query.Close()

rows, err := query.Run(nil, stardust.RunOptions{}, nil)
if err != nil {
	return err
}
defer rows.Close()

result, err := rows.Next()
if err != nil {
	return err
}
defer result.Close()

Result / 33B

[{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

Each operation states which calls can overlap it.

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.
CheckVersion	none	check_version(found) verifies that found matches this binding's ABI version.
Plugins	document	plugins() returns an owned array document describing the plugins included in this library build.

Version

version() returns the loaded library's ABI version.

21B

func Version() uint32

Concurrency: Other calls can overlap this call, except the release of a handle that this call uses.

Examples

version

28B

result := stardust.Version()

Result / 1B

C exports: stardust_abi_version

CheckVersion

check_version(found) verifies that found matches this binding's ABI version.

37B

func CheckVersion(found uint32) error

Concurrency: Other calls can overlap this call, except the release of a handle that this call uses.

Parameters

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

Errors

Status	When
`StatusUnsupported`	found differs from the ABI version of the binding

Examples

check_version

96B

result := stardust.Version()
if err := stardust.CheckVersion(result); err != nil {
	return err
}

Result / 1B

C exports: stardust_abi_version

Plugins

plugins() returns an owned array document describing the plugins included in this library build.

33B

func Plugins() (*Document, error)

Concurrency: Other calls can overlap this call, except the release of a handle that this call uses.
Ownership: The caller owns the returned handle and releases it.

Errors

Status	When
`StatusOutOfMemory`	native memory is exhausted

Examples

Read the compiled plugin inventory

84B

result, err := stardust.Plugins()
if err != nil {
	return err
}
defer result.Close()

Result / 241B

[{name            reactors
  description     Live mutations: stored mutations with live: true react to commits
  version         '1'
  requires        []
  definitionTypes []
  hooks           []
  indexProviders  []
  databaseHooks   true}]

C exports: stardust_plugins, stardust_result_take_document, stardust_result_error, stardust_result_release