Definitions

The example stores a query definition and executes it with different variables. It then changes the query ordering and updates the people that the query selects.

Example

Run stored definitions by path

469B

promote, err := db.MutationPath("people/promote")
if err != nil {
	return err
}
defer promote.Close()

if _, err := promote.Run(nil, stardust.RunOptions{}, nil); err != nil {
	return err
}

query, err := db.QueryPath("people/by_role")
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}]

Definition versions

A transaction records each committed change to a stored definition.

An open definition handle identifies its stored path, so later calls can select the applicable version.
To read a specific historical version, use the as_of rules below.

Operations

Operation	Returns	Summary
Database.Definition	document	database.definition(kind, path, as_of) returns an owned authored definition document.
Database.Definitions	document	database.definitions(kind, pattern) returns an owned array document of sorted matching definition paths.
Database.PatchDefinition	commit	database.patch_definition(kind, path, patch) validates and stores a definition merge patch and returns commit information.

Database.Definition

database.definition(kind, path, as_of) returns an owned authored definition document.

Zero selects the latest definition.
A positive transaction selects its historical version.

79B

func (d *Database) Definition(kind, path string, asOf int64) (*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.

Parameters

Parameter	Type	Ownership	Default	Meaning
`kind`	`string`	Value	Required	The definition folder kind.
`path`	`string`	Value	Required	The stored definition path.
`asOf`	`int64`	Value	Absent	The committed snapshot to read. Zero selects the latest snapshot.

Errors

Status	When
`StatusNotFound`	no definition is stored at the path
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

Read a stored query definition

118B

result, err := db.Definition(stardust.Queries, "people/by_role", 0)
if err != nil {
	return err
}
defer result.Close()

Result / 128B

{find       [?name]
 orderBy    [?name]
 parameters {?role engineer}
 where      [[?e role ?role]
             [?e name ?name]]}

C exports: stardust_db_definition_get, stardust_result_take_document, stardust_result_error, stardust_result_release

Database.Definitions

database.definitions(kind, pattern) returns an owned array document of sorted matching definition paths. An absent or empty pattern lists all paths.

71B

func (d *Database) Definitions(kind, pattern string) (*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.

Parameters

Parameter	Type	Ownership	Default	Meaning
`kind`	`string`	Value	Required	The definition folder kind.
`pattern`	`string`	Value	Absent	The pattern for definition paths. An absent pattern selects all paths in the requested folder.

Errors

Status	When
`StatusInvalidArgument`	the kind or the pattern is invalid
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

database/definitions

111B

result, err := db.Definitions(stardust.Queries, "people/.*")
if err != nil {
	return err
}
defer result.Close()

Result / 16B

[people/by_role]

database/definitions

111B

result, err := db.Definitions(stardust.Queries, "people/.*")
if err != nil {
	return err
}
defer result.Close()

Result / 2B

[]

database/definitions

111B

result, err := db.Definitions(stardust.Queries, "people/.*")
if err != nil {
	return err
}
defer result.Close()

Result / 16B

[people/by_role]

database/definitions

111B

result, err := db.Definitions(stardust.Queries, "people/.*")
if err != nil {
	return err
}
defer result.Close()

Result / 2B

[]

C exports: stardust_db_definition_list, stardust_result_take_document, stardust_result_error, stardust_result_release

Database.PatchDefinition

database.patch_definition(kind, path, patch) validates and stores a definition merge patch and returns commit information.

An object merges or creates a definition.
A null value deletes the definition.

86B

func (d *Database) PatchDefinition(kind, path string, patch *Document) (Commit, error)

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

Parameters

Parameter	Type	Ownership	Default	Meaning
`kind`	`string`	Value	Required	The definition folder kind.
`path`	`string`	Value	Required	The stored definition path.
`patch`	`*Document`	Borrowed for the call	Required	The native merge patch applied to the stored definition before validation and replacement.

Errors

Status	When
`StatusInvalidDefinition`	the patched definition is invalid
`StatusClosed`	the database is closed
`StatusOutOfMemory`	native memory is exhausted

Examples

database/patch_definition

patchText holds this document:

dust

123B

parameters {?role engineer}
find       [?name]
where      [[?e role ?role]
            [?e name ?name]]
orderBy    [?name]

212B

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

result, err := db.PatchDefinition(stardust.Queries, "people/by_role", patch)
if err != nil {
	return err
}

Result / 105B

{status       committed
 transaction  3
 facts        0
 committed_at 17915443415276282
 ids          {}}

C exports: stardust_db_definition_patch, stardust_db_result_commit_info, stardust_result_error, stardust_result_release