API Reference#

db#

Author: Ashot Vardanian
Date: 12 Jun 2022

Typedefs

typedef void *ustore_database_t#

Opaque multi-modal Database handle.

Properties:

Thread safety: Safe to use across threads after open and before free.
Lifetime: Must live longer than all the transactions.

See also

ustore_database_free().

typedef uint64_t ustore_snapshot_t#

typedef void *ustore_transaction_t#

Opaque Transaction handle.

Allows ACID-ly grouping operations across different collections and even modalities. This means, that the same transaction might be:

inserting a blob of media data into a collection of images.
updating users metadata in a documents collection to reference new avatar.
introducing links between the user and other in a graph collection… and all of the operations here either succeed or fail together. DBMS will do the synchronization heavy-lifting, so you don’t have to.

See also

ustore_transaction_free().

Properties:

Thread safety: None.
Lifetime: Must be freed before the ustore_database_t is closed.
Concurrency Control: Optimistic.

typedef uint64_t ustore_collection_t#: Some unique integer identifier of a collection. A ustore_database_t database can have many of those, but never with repeating names or identifiers. Those identifiers are not guaranteed to remain the same between DBMS restarts.

typedef int64_t ustore_key_t#: The unique identifier of any value within a single collection.

typedef uint8_t ustore_byte_t#: The elementary binary piece of any value.

typedef float ustore_float_t#: Single-precisions floating-point number.

typedef char ustore_char_t#: The elementary piece of any string, like collection name.

typedef uint32_t ustore_length_t#: The length of any value in the DB.

typedef uint64_t ustore_size_t#: Pointer-sized integer type.

typedef uint8_t ustore_octet_t#: The smallest possible “bitset” type, storing eight zeros or ones.

typedef uint64_t ustore_sequence_number_t#: Monotonically increasing unique identifier that reflects the order of applied transactions.

typedef char const *ustore_error_t#: Owning error message string. If not null, must be deallocated via ustore_error_free().

typedef char const *ustore_str_view_t#: Non-owning string reference. Always provided by user and we don’t participate in its lifetime management in any way.

typedef char *ustore_str_span_t#

typedef void *ustore_arena_t#

Temporary memory handle, used mostly for read requests. It’s allocated, resized and deallocated only by UStore itself. Once done, must be deallocated with ustore_arena_free().

See also

ustore_arena_free().

typedef uint8_t *ustore_bytes_ptr_t#

typedef uint8_t const *ustore_bytes_cptr_t#

typedef void *ustore_callback_payload_t#

typedef void (*ustore_callback_t)(ustore_callback_payload_t)#

typedef struct ustore_database_init_t ustore_database_init_t#

Opens the underlying Key-Value Store.

Depending on the selected distribution can be any of:

See also

ustore_database_init().

embedded persistent transactional KVS
embedded in-memory transactional KVS
remote persistent transactional KVS
remote in-memory transactional KVS

typedef struct ustore_get_metadata_t ustore_get_metadata_t#

typedef struct ustore_snapshot_list_t ustore_snapshot_list_t#

typedef struct ustore_snapshot_create_t ustore_snapshot_create_t#

typedef struct ustore_snapshot_export_t ustore_snapshot_export_t#

typedef struct ustore_snapshot_drop_t ustore_snapshot_drop_t#

typedef struct ustore_collection_list_t ustore_collection_list_t#

Lists all named collections in the DB.

Retrieves a list of collection IDs & names in a NULL-delimited form. The default nameless collection won’t be described in any form, as its always present. This is the only collection-management operation that can be performed on a DB state snapshot, and not just on the HEAD state.

See also

ustore_collection_list().

typedef struct ustore_collection_create_t ustore_collection_create_t#

Creates a new uniquely named collection in the DB.

This function may never be called, as the default nameless collection always exists and can be addressed via ustore_collection_main_k. You can “re-create” an empty collection with a new config.

See also

ustore_collection_create().

typedef struct ustore_collection_drop_t ustore_collection_drop_t#

Removes or clears an existing collection.

Removes a collection or its contents depending on mode. The default nameless collection can’t be removed, only cleared.

See also

ustore_collection_drop().

typedef struct ustore_database_control_t ustore_database_control_t#

Free-form communication tunnel with the underlying engine.

Performs free-form queries on the DB, that may not necessarily have a stable API and a fixed format output. Generally, those requests are very expensive and shouldn’t be executed in most applications. This is the “kitchen-sink” of UStore interface, similar to fcntl & ioctl.

See also

ustore_database_control().

typedef struct ustore_transaction_init_t ustore_transaction_init_t#

Begins a new ACID transaction or resets an existing one.

See also

ustore_transaction_init().

typedef struct ustore_transaction_stage_t ustore_transaction_stage_t#

Stages an ACID transaction for Two Phase Commits.

Regardless of result, the content is preserved to allow further logging, serialization or retries. The underlying memory can be cleaned and reused by consecutive ustore_transaction_init() call.

See also

ustore_transaction_stage().

typedef struct ustore_transaction_commit_t ustore_transaction_commit_t#

Commits an ACID transaction.

Regardless of result, the content is preserved to allow further logging, serialization or retries. The underlying memory can be cleaned and reused by consecutive ustore_transaction_init() call.

See also

ustore_transaction_commit().

Enums

enum ustore_options_t#

Values:

enumerator ustore_options_default_k#

enumerator ustore_option_write_flush_k#: Forces absolute consistency on the write operations flushing all the data to disk after each write. It’s usage may cause severe performance degradation in some implementations. Yet the users must be warned, that modern IO drivers still often can’t guarantee that everything will reach the disk.

enumerator ustore_option_transaction_dont_watch_k#: When reading from a transaction, we track the requested keys. If the requested key was updated since the read, the transaction will fail on commit or prior to that. This option disables collision detection on separate parts of transactional reads and writes.

enumerator ustore_option_dont_discard_memory_k#: On every API call, the arena is cleared for reuse. If the arguments of the function are results of another UStore call, you can use this flag to avoid discarding the memory.

enumerator ustore_option_read_shared_memory_k#: Will output data into shared memory, not the one privately to do further transformations without any copies. Is relevant for standalone distributions used with drivers supporting Apache Arrow buffers or standardized Tensor representations.

enumerator ustore_option_scan_bulk_k#: When set, the underlying engine may avoid strict keys ordering and may include irrelevant (deleted & duplicate) keys in order to maximize throughput. The purpose is not accelerating the ustore_scan(), but the following ustore_read(). Generally used for Machine Learning applications.

enum ustore_drop_mode_t#

The “mode” of collection removal.

Values:

enumerator ustore_drop_keys_vals_handle_k#: Remove the handle and all of the contents.

enumerator ustore_drop_keys_vals_k#: Remove keys and values, but keep the collection.

enumerator ustore_drop_vals_k#: Clear the values, but keep the keys.

enum ustore_metadata_t#

The “metadata support types”.

Values:

enumerator ustore_supports_transactions_k#: DataBase supports transactions.

enumerator ustore_supports_named_collections_k#: DataBase supports named collections.

enumerator ustore_supports_snapshots_k#: DataBase supports snapshots.

Functions

void ustore_database_init(ustore_database_init_t*)#

Opens the underlying Key-Value Store.

See also

ustore_database_init().

void ustore_get_metadata(ustore_get_metadata_t*)#

Retrive Metadata.

See also

ustore_metadata_t.

void ustore_snapshot_list(ustore_snapshot_list_t*)#

Lists all snapshots in the DB.

See also

ustore_snapshot_list_t.

void ustore_snapshot_create(ustore_snapshot_create_t*)#

void ustore_snapshot_export(ustore_snapshot_export_t*)#

void ustore_snapshot_drop(ustore_snapshot_drop_t*)#

void ustore_collection_list(ustore_collection_list_t*)#

Lists all named collections in the DB.

See also

ustore_collection_list_t.

void ustore_collection_create(ustore_collection_create_t*)#

Creates a new uniquely named collection in the DB.

See also

ustore_collection_create_t.

void ustore_collection_drop(ustore_collection_drop_t*)#

Removes or clears an existing collection.

See also

ustore_collection_drop_t.

void ustore_database_control(ustore_database_control_t*)#

Free-form communication tunnel with the underlying engine.

See also

ustore_database_control().

void ustore_transaction_init(ustore_transaction_init_t*)#

Begins a new ACID transaction or resets an existing one.

See also

ustore_transaction_init_t.

void ustore_transaction_stage(ustore_transaction_stage_t*)#

Stages an ACID transaction for Two Phase Commits.

See also

ustore_transaction_stage_t.

void ustore_transaction_commit(ustore_transaction_commit_t*)#

Commits an ACID transaction.

See also

ustore_transaction_commit_t.

void ustore_arena_free(ustore_arena_t)#: Deallocates reusable memory arenas. Passing NULLs is safe.

void ustore_transaction_free(ustore_transaction_t)#: Resets the transaction and deallocates the underlying memory. Passing NULLs is safe.

void ustore_database_free(ustore_database_t)#: Closes the DB and deallocates used memory. The database would still persist on disk. Passing NULLs is safe.

void ustore_error_free(ustore_error_t)#: Deallocates error messages. Passing NULLs is safe.

Variables

ustore_collection_t const ustore_collection_main_k#: The handle to the default nameless collection. It exists from start, doesn’t have to be created and can’t be fully dropped. Only ustore_drop_keys_vals_k and ustore_drop_vals_k apply to it.

ustore_length_t const ustore_length_missing_k#

ustore_key_t const ustore_key_unknown_k#

struct ustore_database_init_t

#include <db.h>

Opens the underlying Key-Value Store.

Depending on the selected distribution can be any of:

See also

ustore_database_init().

embedded persistent transactional KVS
embedded in-memory transactional KVS
remote persistent transactional KVS
remote in-memory transactional KVS

Public Members

ustore_str_view_t config#

Configuration parameter for the DBMS.

For embedded distributions should be a json string containing DB options.

See also

db_config.json file.

Special:

Flight API Client: grpc://0.0.0.0:38709.

ustore_database_t *db#: A pointer to the opened KVS, unless error is filled.

ustore_error_t *error#: Pointer to exported error message.

struct ustore_get_metadata_t

#include <db.h>

Unnamed Group

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_metadata_t *metadata#: Output for the metadata.

struct ustore_snapshot_list_t

#include <db.h>

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message. If not NULL, must be deallocated with ustore_error_free().

ustore_arena_t *arena#

Reusable memory handle.

See also

ustore_arena_free().

ustore_options_t options#

Listing options.

Possible values:

ustore_option_dont_discard_memory_k: Won’t reset the arena before the operation begins.

Contents

ustore_size_t *count#: Number of present snapshots.

ustore_snapshot_t **ids#: All snapshots id.

struct ustore_snapshot_create_t

#include <db.h>

Public Members

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_snapshot_t *id#: Output for the snapshot id.

struct ustore_snapshot_export_t

#include <db.h>

Public Members

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_snapshot_t id#: Snapshot id.

ustore_str_view_t path#: The specified directory path.

struct ustore_snapshot_drop_t

#include <db.h>

Public Members

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_snapshot_t id#: Existing snapshot id.

struct ustore_collection_list_t

#include <db.h>

Lists all named collections in the DB.

See also

ustore_collection_list().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message. If not NULL, must be deallocated with ustore_error_free().

ustore_transaction_t transaction#

The snapshot in which the retrieval will be conducted.

ustore_snapshot_t snapshot#

A snapshot captures a point-in-time view of the DB at the time it’s created.

ustore_arena_t *arena#

Reusable memory handle.

See also

ustore_arena_free().

ustore_options_t options#

Listing options.

Possible values:

ustore_option_dont_discard_memory_k: Won’t reset the arena before the operation begins.

Contents

ustore_size_t *count#: Number of present collections.

ustore_collection_t **ids#: Handles of all the collections in same order as names.

ustore_length_t **offsets#: Offsets of separate strings in the names tape.

ustore_char_t **names#: NULL-terminated collection names tape in same order as ids.

struct ustore_collection_create_t

#include <db.h>

Creates a new uniquely named collection in the DB.

This function may never be called, as the default nameless collection always exists and can be addressed via ustore_collection_main_k. You can “re-create” an empty collection with a new config.

See also

ustore_collection_create().

Public Members

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_str_view_t name#: Unique name for the new collection.

ustore_str_view_t config#: Optional configuration JSON string.

ustore_collection_t *id#: Output for the collection handle.

struct ustore_collection_drop_t

#include <db.h>

Removes or clears an existing collection.

Removes a collection or its contents depending on mode. The default nameless collection can’t be removed, only cleared.

See also

ustore_collection_drop().

Public Members

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_collection_t id#: Existing collection handle.

ustore_drop_mode_t mode#: Controls if values, pairs or the whole collection must be dropped.

struct ustore_database_control_t

#include <db.h>

Free-form communication tunnel with the underlying engine.

See also

ustore_database_control().

Public Members

ustore_database_t db#: Already open database instance.

ustore_arena_t *arena#: Reusable memory handle.

ustore_error_t *error#: Pointer to exported error message.

ustore_str_view_t request#: The input command as a NULL-terminated string.

ustore_str_view_t *response#: The output response as a NULL-terminated string.

struct ustore_transaction_init_t

#include <db.h>

Begins a new ACID transaction or resets an existing one.

See also

ustore_transaction_init().

Public Members

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_options_t options#

Transaction options.

Possible values:

ustore_option_dont_discard_memory_k: Won’t reset the arena before the operation begins.

ustore_transaction_t *transaction#: In-out transaction handle.

struct ustore_transaction_stage_t

#include <db.h>

Stages an ACID transaction for Two Phase Commits.

Regardless of result, the content is preserved to allow further logging, serialization or retries. The underlying memory can be cleaned and reused by consecutive ustore_transaction_init() call.

See also

ustore_transaction_stage().

Public Members

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: Initialized transaction handle.

ustore_options_t options#: Staging options.

ustore_sequence_number_t *sequence_number#: Optional output for the transaction stage sequence number.

struct ustore_transaction_commit_t

#include <db.h>

Commits an ACID transaction.

Regardless of result, the content is preserved to allow further logging, serialization or retries. The underlying memory can be cleaned and reused by consecutive ustore_transaction_init() call.

See also

ustore_transaction_commit().

Public Members

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: Initialized transaction handle.

ustore_options_t options#: Staging options.

ustore_sequence_number_t *sequence_number#: Optional output for the transaction commit sequence number.

ustore#

Author: Ashot Vardanian
Date: 12 Jun 2022

docs#

Author: Ashot Vardanian
Date: 27 Jun 2022

Typedefs

typedef enum ustore_doc_field_type_t ustore_doc_field_type_t

Type IDs needed to describing (sub-) document contents. Most types mimic what’s present in Apache Arrow. Others, describe hierarchical documents, like JSON, BSON and MessagePack.

For Business Intelligence and Analytics mostly the ustore_doc_field_i64_k and ustore_doc_field_f64_k are used.

typedef enum ustore_doc_modification_t ustore_doc_modification_t: Kind of document modification to be applied on ustore_docs_write().

typedef struct ustore_docs_write_t ustore_docs_write_t#

Main “setter” interface for (sub-)document-level data. Generalization of ustore_write_t to structured values.

See also

ustore_docs_write(), ustore_write_t, ustore_write().

typedef struct ustore_docs_read_t ustore_docs_read_t#

Main “getter” interface for (sub-)document-level data. Generalization of ustore_read_t to structured values.

See also

ustore_docs_read(), ustore_read_t, ustore_read().

typedef struct ustore_docs_gist_t ustore_docs_gist_t#

Lists fields & paths present in wanted documents or entire collections.

See also

ustore_docs_gist().

typedef struct ustore_docs_gather_t ustore_docs_gather_t#

Gathers N*M values matching M fields from N docs in columnar form.

See also

ustore_docs_gather().

Enums

enum ustore_doc_field_type_t#

Type IDs needed to describing (sub-) document contents. Most types mimic what’s present in Apache Arrow. Others, describe hierarchical documents, like JSON, BSON and MessagePack.

For Business Intelligence and Analytics mostly the ustore_doc_field_i64_k and ustore_doc_field_f64_k are used.

Values:

enumerator ustore_doc_field_json_k#

enumerator ustore_doc_field_bson_k#

enumerator ustore_doc_field_msgpack_k#

enumerator ustore_doc_field_default_k#

enumerator ustore_doc_field_null_k#

enumerator ustore_doc_field_bool_k#

enumerator ustore_doc_field_uuid_k#

enumerator ustore_doc_field_i8_k#

enumerator ustore_doc_field_i16_k#

enumerator ustore_doc_field_i32_k#

enumerator ustore_doc_field_i64_k#

enumerator ustore_doc_field_u8_k#

enumerator ustore_doc_field_u16_k#

enumerator ustore_doc_field_u32_k#

enumerator ustore_doc_field_u64_k#

enumerator ustore_doc_field_f16_k#

enumerator ustore_doc_field_f32_k#

enumerator ustore_doc_field_f64_k#

enumerator ustore_doc_field_bin_k#

enumerator ustore_doc_field_str_k#

enum ustore_doc_modification_t#

Kind of document modification to be applied on ustore_docs_write().

Values:

enumerator ustore_doc_modify_upsert_k#

enumerator ustore_doc_modify_update_k#

enumerator ustore_doc_modify_insert_k#

enumerator ustore_doc_modify_patch_k#

enumerator ustore_doc_modify_merge_k#

Functions

void ustore_docs_write(ustore_docs_write_t*)#

Main “setter” interface for (sub-)document-level data. Generalization of ustore_write_t to structured values.

See also

ustore_docs_write_t, ustore_write_t, ustore_write().

void ustore_docs_read(ustore_docs_read_t*)#

Main “getter” interface for (sub-)document-level data. Generalization of ustore_read_t to structured values.

See also

ustore_docs_read_t, ustore_read_t, ustore_read().

void ustore_docs_gist(ustore_docs_gist_t*)#

Lists fields & paths present in wanted documents or entire collections.

See also

ustore_docs_gist_t.

void ustore_docs_gather(ustore_docs_gather_t*)#

Vectorized “gather” interface, that collects, type-checks and casts N*M values matching M fields from N docs into a columnar form.

See also

ustore_docs_gather_t.

struct ustore_docs_write_t

#include <docs.h>

Main “setter” interface for (sub-)document-level data. Generalization of ustore_write_t to structured values.

See also

ustore_docs_write(), ustore_write_t, ustore_write().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Write or Read+Write options for Read-Modify-Write operations.

See also

ustore_write_t.

Inputs

ustore_size_t tasks_count#

ustore_doc_field_type_t type#

ustore_doc_modification_t modification#

ustore_collection_t const *collections#

ustore_size_t collections_stride#

ustore_key_t const *keys#

ustore_size_t keys_stride#

ustore_str_view_t const *fields#

ustore_size_t fields_stride#

ustore_octet_t const *presences#

ustore_length_t const *offsets#

ustore_size_t offsets_stride#

ustore_length_t const *lengths#

ustore_size_t lengths_stride#

ustore_bytes_cptr_t const *values#

ustore_size_t values_stride#

ustore_str_view_t id_field#

struct ustore_docs_read_t

#include <docs.h>

Main “getter” interface for (sub-)document-level data. Generalization of ustore_read_t to structured values.

See also

ustore_docs_read(), ustore_read_t, ustore_read().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_snapshot_t snapshot#: A snapshot captures a point-in-time view of the DB at the time it’s created.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Read options.

See also

ustore_read_t.

Inputs

ustore_doc_field_type_t type#

ustore_size_t tasks_count#

ustore_collection_t const *collections#

ustore_size_t collections_stride#

ustore_key_t const *keys#

ustore_size_t keys_stride#

ustore_str_view_t const *fields#

ustore_size_t fields_stride#

Outputs

ustore_octet_t **presences#

ustore_length_t **offsets#

ustore_length_t **lengths#

ustore_bytes_ptr_t *values#

struct ustore_docs_gist_t

#include <docs.h>

Lists fields & paths present in wanted documents or entire collections.

See also

ustore_docs_gist().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_snapshot_t snapshot#: A snapshot captures a point-in-time view of the DB at the time it’s created.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Read options.

See also

ustore_read_t.

Inputs

ustore_size_t docs_count#

ustore_collection_t const *collections#

ustore_size_t collections_stride#

ustore_key_t const *keys#

ustore_size_t keys_stride#

Outputs

ustore_size_t *fields_count#

ustore_length_t **offsets#

ustore_char_t **fields#

struct ustore_docs_gather_t

#include <docs.h>

Gathers N*M values matching M fields from N docs in columnar form.

See also

ustore_docs_gather().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_snapshot_t snapshot#: A snapshot captures a point-in-time view of the DB at the time it’s created.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Read options.

See also

ustore_read_t.

Inputs

ustore_size_t docs_count#

ustore_size_t fields_count#

ustore_collection_t const *collections#

ustore_size_t collections_stride#

ustore_key_t const *keys#

ustore_size_t keys_stride#

ustore_str_view_t const *fields#

ustore_size_t fields_stride#

ustore_doc_field_type_t const *types#

ustore_size_t types_stride#

Outputs

ustore_octet_t ***columns_validities#

ustore_octet_t ***columns_conversions#

ustore_octet_t ***columns_collisions#

ustore_byte_t ***columns_scalars#

ustore_length_t ***columns_offsets#

ustore_length_t ***columns_lengths#

ustore_byte_t **joined_strings#

graph#

Author: Ashot Vardanian
Date: 27 Jun 2022

Typedefs

typedef enum ustore_vertex_role_t ustore_vertex_role_t

Every vertex can be either a source or a target in a Directed Graph.

When working with undirected graphs, this argument is irrelevant and should be set to ustore_vertex_role_any_k. With directed graphs, where source and target can belong to different collections its crucial that members of each collection are fixed to be either only sources or only edges.

typedef uint32_t ustore_vertex_degree_t#: Type to describe the number of edges a vertex connects to.

typedef struct ustore_graph_find_edges_t ustore_graph_find_edges_t#

Finds all the edges, connected to given vertices.

See also

ustore_graph_find_edges().

typedef struct ustore_graph_upsert_edges_t ustore_graph_upsert_edges_t#

Inserts edges between provided vertices.

See also

ustore_graph_upsert_edges().

typedef struct ustore_graph_remove_edges_t ustore_graph_remove_edges_t#

Removed edges between provided vertices.

See also

ustore_graph_remove_edges().

typedef struct ustore_graph_upsert_vertices_t ustore_graph_upsert_vertices_t#

Upsert vertices.

See also

ustore_graph_upsert_vertices().

typedef struct ustore_graph_remove_vertices_t ustore_graph_remove_vertices_t#

Removes vertices and all related edges from the graph.

See also

ustore_graph_remove_vertices().

Enums

enum ustore_vertex_role_t#

Every vertex can be either a source or a target in a Directed Graph.

Values:

enumerator ustore_vertex_role_unknown_k#

enumerator ustore_vertex_source_k#

enumerator ustore_vertex_target_k#

enumerator ustore_vertex_role_any_k#

Functions

void ustore_graph_find_edges(ustore_graph_find_edges_t*)#

Finds all the edges, connected to given vertices.

See also

ustore_graph_find_edges_t.

void ustore_graph_upsert_edges(ustore_graph_upsert_edges_t*)#

Inserts edges between provided vertices.

See also

ustore_graph_upsert_edges_t.

void ustore_graph_remove_edges(ustore_graph_remove_edges_t*)#

Removed edges between provided vertices.

See also

ustore_graph_remove_edges_t.

void ustore_graph_upsert_vertices(ustore_graph_upsert_vertices_t*)#

Upsert vertices.

See also

ustore_graph_upsert_vertices_t.

void ustore_graph_remove_vertices(ustore_graph_remove_vertices_t*)#

Removes vertices and all related edges from the graph.

See also

ustore_graph_remove_vertices_t.

Variables

ustore_key_t ustore_default_edge_id_k#

ustore_vertex_degree_t ustore_vertex_degree_missing_k#

struct ustore_graph_find_edges_t

#include <graph.h>

Finds all the edges, connected to given vertices.

See also

ustore_graph_find_edges().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_snapshot_t snapshot#: A snapshot captures a point-in-time view of the DB at the time it’s created.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Read options.

See also

ustore_read_t.

Inputs

ustore_size_t tasks_count#: The roles of passed vertices within edges.

ustore_collection_t const *collections#: The roles of passed vertices within edges.

ustore_size_t collections_stride#: The roles of passed vertices within edges.

ustore_key_t const *vertices#: The roles of passed vertices within edges.

ustore_size_t vertices_stride#: The roles of passed vertices within edges.

ustore_vertex_role_t const *roles#: The roles of passed vertices within edges.

ustore_size_t roles_stride#: Step between roles.

Outputs

ustore_vertex_degree_t **degrees_per_vertex#

ustore_key_t **edges_per_vertex#

struct ustore_graph_upsert_edges_t

#include <graph.h>

Inserts edges between provided vertices.

See also

ustore_graph_upsert_edges().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Read and Write options.

See also

ustore_read_t, ustore_write_t.

Inputs

ustore_size_t tasks_count#

ustore_collection_t const *collections#

ustore_size_t collections_stride#

ustore_key_t const *edges_ids#

ustore_size_t edges_stride#

ustore_key_t const *sources_ids#

ustore_size_t sources_stride#

ustore_key_t const *targets_ids#

ustore_size_t targets_stride#

struct ustore_graph_remove_edges_t

#include <graph.h>

Removed edges between provided vertices.

See also

ustore_graph_remove_edges().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Read and Write options.

See also

ustore_read_t, ustore_write_t.

Inputs

ustore_size_t tasks_count#

ustore_collection_t const *collections#

ustore_size_t collections_stride#

ustore_key_t const *edges_ids#

ustore_size_t edges_stride#

ustore_key_t const *sources_ids#

ustore_size_t sources_stride#

ustore_key_t const *targets_ids#

ustore_size_t targets_stride#

struct ustore_graph_upsert_vertices_t

#include <graph.h>

Upsert vertices.

See also

ustore_graph_upsert_vertices().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Read and Write options.

See also

ustore_read_t, ustore_write_t.

Inputs

ustore_size_t tasks_count#

ustore_collection_t const *collections#

ustore_size_t collections_stride#

ustore_key_t const *vertices#

ustore_size_t vertices_stride#

struct ustore_graph_remove_vertices_t

#include <graph.h>

Removes vertices and all related edges from the graph.

See also

ustore_graph_remove_vertices().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Read and Write options.

See also

ustore_read_t, ustore_write_t.

Inputs

ustore_size_t tasks_count#: Needed only for Joining graphs.

ustore_collection_t const *collections#: Needed only for Joining graphs.

ustore_size_t collections_stride#: Needed only for Joining graphs.

ustore_key_t const *vertices#: Needed only for Joining graphs.

ustore_size_t vertices_stride#: Needed only for Joining graphs.

ustore_vertex_role_t const *roles#: Needed only for Joining graphs.

ustore_size_t roles_stride#: Step between roles.

media#

Author: Ashot Vardanian
Date: 27 Jun 2022

Enums

enum ustore_format_field_type_t#

Formats describing contents of collections. The low-level interface.

Many of the numerical values are set to their RFC proposal numbers. https://en.wikipedia.org/wiki/List_of_RFCs

Values:

enumerator ustore_format_field_default_k#

enumerator ustore_format_graph_k#

enumerator ustore_format_doc_k#

enumerator ustore_format_table_k#

enumerator ustore_format_msgpack_k#

enumerator ustore_format_bson_k#

enumerator ustore_format_ubjson_k#

enumerator ustore_field_json_k#

enumerator ustore_format_cbor_k#

enumerator ustore_format_json_patch_k#

enumerator ustore_format_json_merge_patch_k#

enumerator ustore_format_csv_k#

enumerator ustore_format_arrow_k#

enumerator ustore_format_parquet_k#

enumerator ustore_format_text_k#

enumerator ustore_format_text_xml_k#

enumerator ustore_format_text_html_k#

enumerator ustore_format_img_jpeg200_k#

enumerator ustore_format_img_jpeg_k#

enumerator ustore_format_img_png_k#

enumerator ustore_format_img_gif_k#

enumerator ustore_format_img_webp_k#

paths#

Author: Ashot Vardanian
Date: 23 Sep 2022

Typedefs

typedef struct ustore_paths_write_t ustore_paths_write_t#

Maps string paths to binary values. Generalization of ustore_write_t to variable-length key.

See also

ustore_paths_write(), ustore_write_t, ustore_write().

typedef struct ustore_paths_read_t ustore_paths_read_t#

Retrieves binary values given string paths. Generalization of ustore_read_t to variable-length key.

See also

ustore_paths_read(), ustore_read_t, ustore_read().

typedef struct ustore_paths_match_t ustore_paths_match_t#

Vectorized “Prefix” and RegEx “Pattern Matching” for paths.

If a “pattern” contains RegEx special symbols, than it is treated as a RegEx pattern: ., +, *, ?, ^, $, (, ), [, ], {, }, |, . Otherwise, it is treated as a prefix for search.

See also

ustore_paths_match().

Functions

void ustore_paths_write(ustore_paths_write_t*)#

Maps string paths to binary values. Generalization of ustore_write_t to variable-length key.

See also

ustore_paths_write_t, ustore_write_t, ustore_write().

void ustore_paths_read(ustore_paths_read_t*)#

Retrieves binary values given string paths. Generalization of ustore_read_t to variable-length key.

See also

ustore_paths_read_t, ustore_read_t, ustore_read().

void ustore_paths_match(ustore_paths_match_t*)#

Vectorized “Prefix” and RegEx “Pattern Matching” for paths.

See also

ustore_paths_match_t.

struct ustore_paths_write_t

#include <paths.h>

Maps string paths to binary values. Generalization of ustore_write_t to variable-length key.

See also

ustore_paths_write(), ustore_write_t, ustore_write().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Read and Write options for Read-Modify-Write logic.

See also

ustore_read_t, ustore_write_t.

Inputs

ustore_size_t tasks_count#

ustore_char_t path_separator#

ustore_collection_t const *collections#

ustore_size_t collections_stride#

Variable Length Keys

ustore_str_view_t const *paths#

ustore_size_t paths_stride#

ustore_length_t const *paths_offsets#

ustore_size_t paths_offsets_stride#

ustore_length_t const *paths_lengths#

ustore_size_t paths_lengths_stride#

Variable Length Values

ustore_octet_t const *values_presences#

ustore_length_t const *values_offsets#

ustore_size_t values_offsets_stride#

ustore_length_t const *values_lengths#

ustore_size_t values_lengths_stride#

ustore_bytes_cptr_t const *values_bytes#

ustore_size_t values_bytes_stride#

struct ustore_paths_read_t

#include <paths.h>

Retrieves binary values given string paths. Generalization of ustore_read_t to variable-length key.

See also

ustore_paths_read(), ustore_read_t, ustore_read().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_snapshot_t snapshot#: The snapshot captures a view of the database at the time it’s created.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Read options.

See also

ustore_read_t.

Inputs

ustore_size_t tasks_count#

ustore_char_t path_separator#

ustore_collection_t const *collections#

ustore_size_t collections_stride#

Variable Length Keys

ustore_str_view_t const *paths#

ustore_size_t paths_stride#

ustore_length_t const *paths_offsets#

ustore_size_t paths_offsets_stride#

ustore_length_t const *paths_lengths#

ustore_size_t paths_lengths_stride#

Outputs

ustore_octet_t **presences#

ustore_length_t **offsets#

ustore_length_t **lengths#

ustore_byte_t **values#

struct ustore_paths_match_t

#include <paths.h>

Vectorized “Prefix” and RegEx “Pattern Matching” for paths.

If a “pattern” contains RegEx special symbols, than it is treated as a RegEx pattern: ., +, *, ?, ^, $, (, ), [, ], {, }, |, . Otherwise, it is treated as a prefix for search.

See also

ustore_paths_match().

Context

ustore_database_t db#: Already open database instance.

ustore_error_t *error#: Pointer to exported error message.

ustore_transaction_t transaction#: The transaction in which the operation will be watched.

ustore_arena_t *arena#: Reusable memory handle.

ustore_options_t options#

Read options.

See also

ustore_read_t.

Inputs

ustore_size_t tasks_count#

ustore_char_t path_separator#

ustore_collection_t const *collections#

ustore_size_t collections_stride#

ustore_length_t const *match_counts_limits#

ustore_size_t match_counts_limits_stride#

Variable Length Patterns to Match in Paths

ustore_str_view_t const *patterns#

ustore_size_t patterns_stride#

ustore_length_t const *patterns_offsets#

ustore_size_t patterns_offsets_stride#

ustore_length_t const *patterns_lengths#

ustore_size_t patterns_lengths_stride#

Previous Matches Used for Pagination

ustore_str_view_t const *previous#

ustore_size_t previous_stride#

ustore_length_t const *previous_offsets#

ustore_size_t previous_offsets_stride#

ustore_length_t const *previous_lengths#

ustore_size_t previous_lengths_stride#

Outputs

ustore_length_t **match_counts#

ustore_length_t **paths_offsets#

ustore_char_t **paths_strings#

arrow#

Author: Ashot Vardanian
Date: 08 Jun 2022

Defines

ARROW_C_DATA_INTERFACE#

ARROW_FLAG_DICTIONARY_ORDERED#

ARROW_FLAG_NULLABLE#

ARROW_FLAG_MAP_KEYS_SORTED#

ARROW_C_STREAM_INTERFACE#

Typedefs

typedef struct ArrowSchema ArrowSchema#

typedef struct ArrowArray ArrowArray#

typedef struct ArrowArrayStream ArrowArrayStream#

Functions

static char const *ustore_doc_field_type_to_arrow_format(ustore_doc_field_type_t const field_type)#: Converts ustore_doc_field_type_t to a “format” string supported by Apache Arrow.

static void release_malloced_schema(struct ArrowSchema *schema)#

static void release_malloced_array(struct ArrowArray *array)#

static void ustore_to_arrow_schema(ustore_size_t const docs_count, ustore_size_t const fields_count, struct ArrowSchema *schema, struct ArrowArray *array, ustore_error_t *error)#: Defines the structure of the continuous arrow::RecordBatch represented in C as a combination of ArrowSchema and ArrowArray.

static void ustore_to_arrow_column(ustore_size_t const docs_count, ustore_str_view_t const field_name, ustore_doc_field_type_t const field_type, ustore_octet_t const *column_validities, ustore_length_t const *column_offsets, void const *column_contents, struct ArrowSchema *schema, struct ArrowArray *array, ustore_error_t *error)#: Fill a column in a continuous arrow::RecordBatch, pre-structured by the ustore_to_arrow_schema() call. Supports scalar and string entries. For lists use ustore_to_arrow_list().

static void ustore_to_arrow_list(ustore_size_t const docs_count, ustore_str_view_t const field_name, ustore_doc_field_type_t const field_type, ustore_octet_t const *column_validities, ustore_length_t const *column_offsets, void const *column_contents, struct ArrowSchema *schema, struct ArrowArray *array, ustore_error_t *error)#: Fill a column in a continuous arrow::RecordBatch, pre-structured by the ustore_to_arrow_schema() call. Supports lists of scalars. For regular scalars or strings use ustore_to_arrow_column().

static void ustore_to_arrow_stream(ustore_database_t const, ustore_transaction_t const, ustore_size_t const, ustore_size_t const, ustore_key_t const, ustore_key_t const, ustore_collection_t const*, ustore_size_t const, ustore_str_view_t const*, ustore_size_t const, ustore_doc_field_type_t const*, ustore_size_t const, struct ArrowArrayStream*, ustore_arena_t*)#: Placeholder for future streaming exports.

static bool check_presence(ustore_octet_t const *begin, size_t idx)#

struct ArrowSchema

#include <arrow.h>

Public Members

const char *format#

const char *name#

const char *metadata#

int64_t flags#

int64_t n_children#

struct ArrowSchema **children#

struct ArrowSchema *dictionary#

void (*release)(struct ArrowSchema*)#

void *private_data#

struct ArrowArray

#include <arrow.h>

Public Members

int64_t length#

int64_t null_count#

int64_t offset#

int64_t n_buffers#

int64_t n_children#

void const **buffers#

struct ArrowArray **children#

struct ArrowArray *dictionary#

void (*release)(struct ArrowArray*)#

void *private_data#

struct ArrowArrayStream

#include <arrow.h>

Public Members

int (*get_schema)(struct ArrowArrayStream*, struct ArrowSchema *out)#

int (*get_next)(struct ArrowArrayStream*, struct ArrowArray *out)#

char const *(*get_last_error)(struct ArrowArrayStream*)#

void (*release)(struct ArrowArrayStream*)#

void *private_data#