Tarantool WIT API 0.2.0 Latest Markdown

World guest

Aggregate imports for components running inside Tarantool.

Consumers may include this world for the complete host API or import individual interfaces directly to keep their contract minimal.

Import interface tarantool:tarantool/types@0.2.0

Types

type msgpack-value

msgpack-value

Exactly one complete MessagePack value encoded as bytes.

The byte sequence must contain one value and no trailing bytes. Functions further constrain its shape where required, for example to an array or a map. Values returned by the host are copied into guest-owned memory.

type error-code

u32

Numeric Tarantool error code.

This is the original unsigned code reported by Tarantool, including codes unknown to this version of the WIT package. Consumers must preserve and accept any u32 value. Symbolic ER_* names belong to the Tarantool version that produced the error and are not part of this contract.

record box-error

Represents an error returned by Tarantool operations.

The numeric code is preserved exactly as reported by Tarantool. Consumers must handle codes they do not recognize. No closed error category is included because Tarantool's error set and classifications may evolve.

Record Fields

record space

Identifies a Tarantool space by its numeric ID.

Record Fields

record index

Identifies a Tarantool index and its parent space.

Record Fields

record log-context

Optional guest source location attached to a log message.

Record Fields

enum log-level

Defines the severity levels used in Tarantool logging.

See https://www.tarantool.io/en/doc/latest/reference/reference_capi/say/.

Enum Cases

record session

Represents a client session in Tarantool by its ID.

Record Fields

enum transaction-isolation

Isolation levels available for Tarantool transactions.

Enum Cases

enum iterator-type

Iterator types for index scans in Tarantool.

See https://www.tarantool.io/en/doc/latest/reference/reference_capi/box_index/.

Enum Cases

record sequence

Identifies a sequence that already exists in Tarantool.

The WIT interface changes sequence state but does not create schema objects. See https://www.tarantool.io/en/doc/latest/platform/ddl_dml/sequences/.

Record Fields

flags key-part-flags

Flags used to modify behavior of key parts in index definitions.

Flags members

enum collation

Built-in Tarantool collation identifiers supported by this contract.

Case ordinals correspond to the built-in IDs in Tarantool's _collation system space. User-defined collations are outside this closed enum.

Enum Cases

enum field-type

Field types supported by key definitions.

Enum Cases

record key-part

Definition of a single key part in a Tarantool index.

Record Fields

record box-tuple

Opaque host-issued handle to a Tarantool tuple.

The handle is meaningful only in the component instance that created it. Consumers must not construct or modify handle values. Each returned handle owns one reference unless documented otherwise and must be released with the public release function from the tarantool:tarantool/box-tuple interface. This is an interface function, not a method on this record.

Record Fields

record key-def

Opaque host-issued handle to a Tarantool key definition.

The handle is meaningful only in the component instance that created it. Consumers must not construct or modify handle values. Each returned handle is owned and must be released with the public release function from the tarantool:tarantool/key-def interface. This is an interface function, not a method on this record.

Record Fields

record tuple-format

Opaque host-issued handle to a Tarantool tuple format.

Each box-tuple has an associated tuple-format. The default format (see tarantool:tarantool/tuple-format::default) is used for tuples not attached to any space.

The handle is meaningful only in the component instance that created it. Consumers must not construct or modify handle values. Each returned handle owns one reference unless documented otherwise and must be released with the public release function from the tarantool:tarantool/tuple-format interface. This is an interface function, not a method on this record.

Record Fields

type tuple-field

msgpack-value

A copied tuple field encoded as one complete MessagePack value.

Import interface tarantool:tarantool/metrics@0.2.0

Functions

uptime: func

Returns the current uptime of the instance in seconds.

Corresponds to box.info.uptime.

Returns

Return values

Import interface tarantool:tarantool/msgpack@0.2.0

Types

type box-error

box-error

type msgpack-value

msgpack-value

Functions

from-json: func

Converts a JSON value to MessagePack.

The input must contain one JSON value. The output contains the equivalent value encoded as one complete MessagePack value.

Parameters

Returns

Errors

Params
Return values

to-json: func

Converts a MessagePack value to JSON.

Only values representable by the JSON data model are accepted. MessagePack extension values, binary values, and maps with non-string keys may fail. The returned JSON is not a canonical serialization.

Parameters

Returns

Errors

Params
Return values

Import interface tarantool:tarantool/database@0.2.0

Types

type space

space

type box-error

box-error

type index

index

type box-tuple

box-tuple

type msgpack-value

msgpack-value

Functions

schema-version: func

Returns the current schema version of the database.

The version changes when Tarantool modifies schema objects such as spaces or indexes.

Returns

Return values

space-by-name: func

Retrieves a space object by its name.

The returned record contains a catalog ID and does not own host state.

Parameters

Returns

Params
Return values

index-by-name: func

Retrieves an index object by name within a space.

The returned record contains catalog IDs and does not own host state.

Parameters

Returns

Params
Return values

insert: func

Inserts a new tuple into a space.

The tuple must be one complete MessagePack array: [field1, field2, ...].

Parameters

Returns

Params
Return values

update: func

Updates an existing tuple by key in the specified index.

Parameters

Returns

Params
Return values

replace: func

Replaces an existing tuple or inserts a new one.

Parameters

Returns

Params
Return values

upsert: func

Performs an UPSERT operation: update if exists, insert otherwise.

Parameters

Returns

Errors

Params
Return values

delete: func

Deletes a tuple by key from the specified index.

The key must be encoded as a MessagePack array, for example [1].

Parameters

Returns

Params
Return values

truncate: func

Removes all tuples from the space.

This operation is equivalent to SQL's TRUNCATE TABLE.

Parameters

Returns

Params
Return values

Import interface tarantool:tarantool/log@0.2.0

Types

type log-level

log-level

type log-context

log-context

Functions

write: func

Writes a message to the Tarantool log.

The interface exposes non-terminating log levels only. Formatting and level-specific convenience helpers belong in guest libraries.

Parameters

Params

Import interface tarantool:tarantool/error@0.2.0

Types

type box-error

box-error

type error-code

error-code

Functions

new: func

Creates a copied error value.

Corresponds to box.error.new{ ... }.

Parameters

Returns

Params
Return values

new-with-location: func

Creates a copied error value with a source location.

Corresponds to box.error.new{ ... }.

Parameters

Returns

Params
Return values

set: func

Sets the given error as the current "last error".

Corresponds to box.error.set(err).

Parameters

Params

last: func

Returns a copy of the last error in the current execution context.

Corresponds to box.error.last(). Returns none if no error is currently set.

Return values

clear: func

Clears the last error.

Corresponds to box.error.clear().

to-string: func

Formats a box-error value for diagnostics.

Equivalent to tostring(err) in Tarantool.

Parameters

Returns

Params
Return values

Import interface tarantool:tarantool/session@0.2.0

Types

type session

session

type box-error

box-error

type msgpack-value

msgpack-value

Functions

current: func

Returns the current session.

The record identifies the connection or execution context from which the current code runs. It does not own the session.

Returns

Return values

broadcast: func

Broadcasts a message to all watchers subscribed to the given key.

value is a Lua expression whose evaluated value is passed to box.broadcast. It is not JSON. Invalid expressions return an error; callers must not interpolate untrusted text into the expression.

Parameters

Returns

Errors

Params
Return values

iproto-send: func

Sends a raw IPROTO packet to a specific session.

The header must be one complete MessagePack map. The optional body, when present, must also be one complete MessagePack map.

Parameters

Returns

Errors

Params
Return values

Import interface tarantool:tarantool/transaction@0.2.0

Types

type box-error

box-error

type transaction-isolation

transaction-isolation

Functions

id: func

Returns the current transaction ID.

A transaction ID is a non-persistent identifier of the current transaction. Returns none if no transaction is active.

Returns

Return values

isolation: func

Returns the isolation level of the current transaction.

Returns none if there is no active transaction.

Returns

Return values

begin: func

Begins a new transaction.

Fails if the current execution context already has an active transaction.

Errors

Return values

commit: func

Commits the current transaction.

Finalizes the transaction and applies its changes.

Errors

Return values

rollback: func

Rolls back the current transaction.

Discards all changes made within the current transaction.

Errors

Return values

set-isolation: func

Sets the isolation level for the current transaction.

Call this before the first DML operation in the transaction.

Parameters

Errors

Params
Return values

make-synchronous: func

Requires synchronous replication for the current transaction.

Commit waits for the configured synchronous replication acknowledgements. This function has no effect when no transaction is active.

Import interface tarantool:tarantool/index@0.2.0

Types

type index

index

type box-error

box-error

type box-tuple

box-tuple

type iterator-type

iterator-type

type msgpack-value

msgpack-value

resource iterator

Index iterator resource for scanning tuples.

Functions

tuple-count: func

Returns the number of tuples stored in the index.

Parameters

Returns

Errors

Params
Return values

memory-size: func

Returns the memory size of the index in bytes.

Parameters

Returns

Errors

Params
Return values

random: func

Returns a random tuple from the index.

Parameters

Returns

Errors

Params
Return values

get: func

Gets a tuple by key from the index.

The key must be one complete MessagePack array, for example [1].

Parameters

Returns

Errors

Params
Return values

min: func

Finds the minimal tuple matching the given key.

Parameters

Returns

Errors

Params
Return values

max: func

Finds the maximal tuple matching the given key.

Parameters

Returns

Errors

Params
Return values

count: func

Counts tuples matching a key and iterator mode.

Parameters

Returns

Errors

Params
Return values

[static]iterator.new: func

Allocates an iterator for the given index.

Dropping the returned resource releases its host iterator state.

Params
Return values

[method]iterator.next: func

Advance the iterator and return the next tuple.

Returns some with an owned tuple handle, or none when the iterator is exhausted. The caller must release a returned handle with the public release function from the tarantool:tarantool/box-tuple interface.

Params
Return values

Import interface tarantool:tarantool/sequence@0.2.0

Types

type sequence

sequence

type box-error

box-error

Functions

next: func

Generates the next value of the specified sequence.

This updates the state of the sequence.

Parameters

Returns

Errors

Params
Return values

current: func

Returns the current value of the specified sequence.

Unlike next, this does not increment the sequence. It returns an error if the sequence has not been advanced or set since creation or reset.

Parameters

Returns

Errors

Params
Return values

set: func

Sets the sequence to a specific value.

Parameters

Errors

Params
Return values

reset: func

Resets the sequence to its initial state.

This clears the current value. After a reset, current returns an error until next or set assigns another value.

Parameters

Errors

Params
Return values

Import interface tarantool:tarantool/key-def@0.2.0

Types

type box-error

box-error

type box-tuple

box-tuple

type key-def

key-def

type key-part

key-part

type msgpack-value

msgpack-value

Functions

new: func

Creates a new key definition from a list of parts.

Each key part selects a tuple field and defines its type, optional collation, optional path, and flags.

Parameters

Returns

Errors

Params
Return values

duplicate: func

Creates a deep copy of the given key definition.

The returned key-def is independent of the original and owns one reference.

Parameters

Returns

Errors

Params
Return values

merge: func

Merges two key definitions into one.

Fields from the right-hand side are appended when they do not duplicate fields from the left-hand side.

Parameters

Returns

Errors

Params
Return values

release: func

Releases a key definition and invalidates all aliases of its handle.

Call this once for every key definition returned by new, duplicate, or merge. Releasing a stale handle traps.

Parameters

Params

dump-parts: func

Returns a list of key parts from a given key definition.

The returned list is copied into guest-owned memory.

Parameters

Returns

Errors

Params
Return values

validate-key: func

Validates whether a given key conforms to the key definition.

Checks the number of fields and their types, allowing partial matches (e.g. prefix of the full key).

Parameters

Returns

Errors

Params
Return values

validate-full-key: func

Validates whether a key fully matches the key definition.

Differs from validate-key by requiring exact number of parts.

Parameters

Returns

Errors

Params
Return values

part-count: func

Returns the number of parts in the key definition.

Each part corresponds to one field used in index comparison or validation.

Parameters

Returns

Errors

Params
Return values

extract-key: func

Extracts a key from a given tuple based on the key definition.

The result is a MessagePack-encoded byte buffer representing the key, constructed by selecting fields from the input tuple as defined by the provided key definition.

This buffer can be decoded using a MessagePack decoder and will contain an array of fields corresponding to the key parts.

Parameters

Returns

Errors

Params
Return values

validate-tuple: func

Validates whether the tuple contains all required fields and types as specified by the key definition.

This is useful to check if a box-tuple is compatible with an index.

Parameters

Returns

A tuple that does not satisfy the definition is returned as a box-error; it is not a normal boolean result.

Params
Return values

Import interface tarantool:tarantool/tuple-format@0.2.0

Types

type key-def

key-def

type box-error

box-error

type tuple-format

tuple-format

Functions

default: func

Returns the default tuple format.

This format is used to create tuples not bound to any specific space.

Returns

Return values

new: func

Creates a new tuple format based on a list of key definitions.

Key definitions supply field types, paths, collations, and nullability constraints.

Parameters

Returns

Errors

Params
Return values

retain: func

Increments the reference counter of the tuple format.

Call this to acquire one additional ownership reference for the same handle. Copying the handle alone does not acquire a reference.

Parameters

Params

release: func

Decrements the reference counter of the tuple format.

Must be called once for every owned reference. The final release invalidates all aliases of the handle. Releasing a stale handle traps.

Parameters

Params

Import interface tarantool:tarantool/box-tuple@0.2.0

Types

type box-error

box-error

type box-tuple

box-tuple

type tuple-field

tuple-field

type tuple-format

tuple-format

type key-def

key-def

type msgpack-value

msgpack-value

resource iterator

Stateful traversal over the top-level fields of one tuple.

Functions

new: func

Creates a new tuple from MessagePack data using the default tuple format.

The data must be a MessagePack-encoded array (for example, [1, "abc", {"x": 42}]).

Parameters

Returns

Errors

Params
Return values

retain: func

Increases the reference count of the tuple.

Call this to acquire one additional ownership reference for the same handle. Copying the handle alone does not acquire a reference.

Parameters

Params

release: func

Decreases the reference count of the tuple.

If the count reaches zero, the handle and all of its aliases become stale. Releasing a stale handle traps.

Parameters

Params

field-count: func

Returns the number of fields in the tuple (i.e., array size).

Parameters

Returns

Params
Return values

byte-size: func

Returns the byte size of the internal MessagePack data.

Useful for buffer allocations.

Parameters

Returns

Params
Return values

to-bytes: func

Serializes the tuple to a MessagePack byte array.

This data can be passed to the public to-json function from the tarantool:tarantool/msgpack interface or to another MessagePack decoder.

Parameters

Returns

Errors

Params
Return values

format: func

Returns the format object associated with the tuple.

Parameters

Returns

Params
Return values

field: func

Returns the field at the specified index (zero-based).

The returned value contains one complete copied MessagePack value.

Parameters

Returns

Errors

Params
Return values

field-by-path: func

Returns a copied field selected by a JSON path expression.

Parameters

Returns

Errors

Params
Return values

update: func

Updates fields in a tuple using the given update expression.

The expression must be a MessagePack array of operation arrays, for example [["=", 1, "new_value"]]. Operation field indexes are zero-based. The original tuple is unchanged.

Parameters

Returns

Errors

Params
Return values

upsert: func

Applies update operations while ignoring client-operation errors.

Valid operations are applied to a copy of the tuple. Invalid operations, such as a type mismatch or missing field, are skipped and may be logged by Tarantool. System failures still return box-error. Despite its name, this function does not insert a tuple into a space. The original tuple is unchanged.

Parameters

Returns

Errors

Params
Return values

validate: func

Validates a tuple against the given format.

Checks field types and nullability constraints.

Parameters

Returns

A tuple that does not conform is returned as a box-error; it is not a normal boolean result.

Errors

Params
Return values

compare: func

Compares two tuples using a given key definition.

The comparison is lexicographical by key fields.

Parameters

Returns

Params
Return values

compare-with-key: func

Compares a tuple with a key using the given key definition.

Parameters

Returns

Errors

Params
Return values

[static]iterator.new: func

Creates a new iterator over the fields of a tuple.

This allows sequential or random access to MessagePack fields within the tuple.

Parameters

Returns

Errors

Params
Return values

[method]iterator.position: func

Returns the current iterator position (index of the next field).

Returns

Params
Return values

[method]iterator.rewind: func

Rewinds the iterator to the beginning of the tuple.

After this call, the next field will be the first.

Params

[method]iterator.seek: func

Seeks to and returns a field at the given tuple index.

After a successful call, position points to the following field, so the next call to next continues after the returned value.

Parameters

Returns

Errors

Params
Return values

[method]iterator.next: func

Returns the next field in the tuple.

Returns none if there are no more fields.

Returns

Errors

Params
Return values