TileDB C API Reference

Types

typedef struct tiledb_array_t tiledb_array_t

An array object.

typedef struct tiledb_config_t tiledb_config_t

A config object.

typedef struct tiledb_config_iter_t tiledb_config_iter_t

A config iterator.

typedef struct tiledb_ctx_t tiledb_ctx_t

A TileDB context.

typedef struct tiledb_error_t tiledb_error_t

A TileDB error.

typedef struct tiledb_attribute_t tiledb_attribute_t

A TileDB attribute.

typedef struct tiledb_array_schema_t tiledb_array_schema_t

A TileDB array schema.

typedef struct tiledb_dimension_t tiledb_dimension_t

A TileDB dimension.

typedef struct tiledb_domain_t tiledb_domain_t

A TileDB domain.

typedef struct tiledb_query_t tiledb_query_t

A TileDB query.

typedef struct tiledb_kv_t tiledb_kv_t

A key-value store object.

typedef struct tiledb_kv_schema_t tiledb_kv_schema_t

A key-value store schema.

typedef struct tiledb_kv_item_t tiledb_kv_item_t

A key-value item.

typedef struct tiledb_kv_iter_t tiledb_kv_iter_t

A key-value store iterator.

typedef struct tiledb_vfs_t tiledb_vfs_t

A virtual filesystem object.

typedef struct tiledb_vfs_fh_t tiledb_vfs_fh_t

A virtual filesystem file handle.

Return Codes

TILEDB_OK

Success

TILEDB_ERR

General error

TILEDB_OOM

Out of memory

Constants

TILEDB_COORDS

A special name indicating the coordinates attribute.

TILEDB_VAR_NUM

A special value indicating a variable number of elements.

TILEDB_MAX_PATH

The maximum path length on the current platform.

TILEDB_OFFSET_SIZE

The size (in bytes) of an offset (used in variable-sized attributes).

const char* tiledb_coords()

Returns a special name indicating the coordinates attribute.

unsigned int tiledb_var_num()

Returns a special value indicating a variable number of elements.

unsigned int tiledb_max_path()

Returns the maximum path length on the current platform.

uint64_t tiledb_datatype_size(tiledb_datatype_t type)

Returns the input datatype size.

uint64_t tiledb_offset_size()

Returns the size (in bytes) of an offset (used in variable-sized attributes).

Enumerations

enum tiledb_object_t

TileDB object type.

Values:

TILEDB_INVALID = 1

Invalid object

TILEDB_GROUP

Group object

TILEDB_ARRAY

Array object

TILEDB_KEY_VALUE

Key-value object TileDB VFS mode

enum tiledb_query_type_t

TileDB query type.

Values:

TILEDB_READ

Read query

TILEDB_WRITE

Write query

enum tiledb_query_status_t

Query status.

Values:

TILEDB_FAILED = -1

Query failed

TILEDB_COMPLETED = 0

Query completed (all data has been read)

TILEDB_INPROGRESS = 1

Query is in progress

TILEDB_INCOMPLETE = 2

Query completed (but not all data has been read)

TILEDB_UNINITIALIZED = 3

Query not initialized.

enum tiledb_filesystem_t

Filesystem type.

Values:

TILEDB_HDFS

HDFS filesystem

TILEDB_S3

S3 filesystem

enum tiledb_datatype_t

TileDB datatype.

Values:

TILEDB_INT32

32-bit signed integer

TILEDB_INT64

64-bit signed integer

TILEDB_FLOAT32

32-bit floating point value

TILEDB_FLOAT64

64-bit floating point value

TILEDB_CHAR

Character

TILEDB_INT8

8-bit signed integer

TILEDB_UINT8

8-bit unsigned integer

TILEDB_INT16

16-bit signed integer

TILEDB_UINT16

16-bit unsigned integer

TILEDB_UINT32

32-bit unsigned integer

TILEDB_UINT64

64-bit unsigned integer

TILEDB_STRING_ASCII

ASCII string

TILEDB_STRING_UTF8

UTF-8 string

TILEDB_STRING_UTF16

UTF-16 string

TILEDB_STRING_UTF32

UTF-32 string

TILEDB_STRING_UCS2

UCS2 string

TILEDB_STRING_UCS4

UCS4 string

TILEDB_ANY

This can be any datatype. Must store (type tag, value) pairs.

enum tiledb_array_type_t

Array type.

Values:

TILEDB_DENSE

Dense array

TILEDB_SPARSE

Sparse array

enum tiledb_layout_t

Tile or cell layout.

Values:

TILEDB_ROW_MAJOR

Row-major layout

TILEDB_COL_MAJOR

Column-major layout

TILEDB_GLOBAL_ORDER

Global-order layout

TILEDB_UNORDERED

Unordered layout

enum tiledb_compressor_t

Compression type.

Values:

TILEDB_NO_COMPRESSION

No compressor

TILEDB_GZIP

Gzip compressor

TILEDB_ZSTD

Zstandard compressor

TILEDB_LZ4

LZ4 compressor

TILEDB_BLOSC_LZ

Blosc compressor using LZ

TILEDB_BLOSC_LZ4

Blosc compressor using LZ4

TILEDB_BLOSC_LZ4HC

Blosc compressor using LZ4HC

TILEDB_BLOSC_SNAPPY

Blosc compressor using Snappy

TILEDB_BLOSC_ZLIB

Blosc compressor using zlib

TILEDB_BLOSC_ZSTD

Blosc compressor using Zstandard

TILEDB_RLE

Run-length encoding compressor

TILEDB_BZIP2

Bzip2 compressor

TILEDB_DOUBLE_DELTA

Double-delta compressor

enum tiledb_walk_order_t

Walk traversal order.

Values:

TILEDB_PREORDER

Pre-order traversal

TILEDB_POSTORDER

Post-order traversal

enum tiledb_vfs_mode_t

VFS mode.

Values:

TILEDB_VFS_READ

TileDB VFS mode Read mode

TILEDB_VFS_WRITE

Write mode

TILEDB_VFS_APPEND

Append mode

Context

int tiledb_ctx_alloc(tiledb_config_t * config, tiledb_ctx_t ** ctx)

Creates a TileDB context, which contains the TileDB storage manager that manages everything in the TileDB library.

Examples:

Without config (i.e., use default configuration):

tiledb_ctx_t* ctx;
tiledb_ctx_alloc(NULL, &ctx);

With some config:

tiledb_ctx_t* ctx;
tiledb_ctx_alloc(config, &ctx);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • config: The configuration parameters (NULL means default).
  • ctx: The TileDB context to be created.

void tiledb_ctx_free(tiledb_ctx_t ** ctx)

Destroys the TileDB context, freeing all associated memory and resources.

Example:

tiledb_ctx_t* ctx;
tiledb_ctx_alloc(NULL, &ctx);
tiledb_ctx_free(&ctx);

Parameters
  • ctx: The TileDB context to be freed.

int tiledb_ctx_get_config(tiledb_ctx_t * ctx, tiledb_config_t ** config)

Retrieves the config from a TileDB context.

Example:

tiledb_config_t* config;
tiledb_ctx_get_config(ctx, &config);
// Make sure to free the retrieved config

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • config: The config to be retrieved.

int tiledb_ctx_get_last_error(tiledb_ctx_t * ctx, tiledb_error_t ** err)

Retrieves the last TileDB error associated with a TileDB context.

Example:

tiledb_error_t* error;
tiledb_ctx_get_last_error(ctx, &error);
// Make sure to free the retrieved error, checking first if it is NULL

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • err: The last error, or NULL if no error has been raised.

int tiledb_ctx_is_supported_fs(tiledb_ctx_t * ctx, tiledb_filesystem_t fs, int * is_supported)

Checks if a given storage filesystem backend is supported.

Example:

int is_supported;
tiledb_ctx_is_supported_fs(ctx, TILEDB_HDFS, &is_supported);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • fs: The filesystem to be checked.
  • is_supported: Sets it to 1 if the filesystem is supported, and 0 otherwise.

int tiledb_ctx_cancel_tasks(tiledb_ctx_t * ctx)

Cancels all background or async tasks associated with the given context.

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.

Config

int tiledb_config_alloc(tiledb_config_t ** config, tiledb_error_t ** error)

Creates a TileDB config.

Example:

tiledb_config_t* config;
tiledb_error_t* error = NULL;
tiledb_config_alloc(&config, &error);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • config: The config to be created.
  • error: Error object returned upon error (NULL if there is no error).

void tiledb_config_free(tiledb_config_t ** config)

Frees a TileDB config.

Example:

tiledb_config_t* config;
tiledb_error_t* error = NULL;
tiledb_config_alloc(&config, &error);
tiledb_config_free(&config);

Parameters
  • config: The config to be freed.

int tiledb_config_set(tiledb_config_t * config, const char * param, const char * value, tiledb_error_t ** error)

Sets a config parameter.

Parameters

  • sm.dedup_coords If true, cells with duplicate coordinates will be removed during sparse array writes. Note that ties during deduplication are arbitrary. Default: false
  • sm.check_coord_dups This is applicable only if sm.dedup_coords is false. If true, an error will be thrown if there are cells with duplicate coordinates during sparse array writes. If false and there are duplicates, the duplicates will be written without errors, but the TileDB behavior could be unpredictable. Default: true
  • sm.tile_cache_size The tile cache size in bytes. Any uint64_t value is acceptable. Default: 10,000,000
  • sm.array_schema_cache_size The array schema cache size in bytes. Any uint64_t value is acceptable. Default: 10,000,000
  • sm.fragment_metadata_cache_size The fragment metadata cache size in bytes. Any uint64_t value is acceptable.
  • sm.enable_signal_handlers Whether or not TileDB will install signal handlers. Default: true
  • sm.num_async_threads The number of threads allocated for async queries. Default: 1
  • sm.num_tbb_threads The number of threads allocated for the TBB thread pool (if TBB is enabled). Note: this is a whole-program setting. Usually this should not be modified from the default. See also the documentation for TBB’s task_scheduler_init class.Default: TBB automatic
  • vfs.num_threads The number of threads allocated for VFS operations (any backend), per VFS instance. Default: number of cores
  • vfs.min_parallel_size The minimum number of bytes in a parallel VFS operation (except parallel S3 writes, which are controlled by vfs.s3.multipart_part_size.) Default: 10MB
  • vfs.file.max_parallel_ops The maximum number of parallel operations on objects with URIs. Default: vfs.num_threads
  • vfs.s3.region The S3 region, if S3 is enabled. Default: us-east-1
  • vfs.s3.scheme The S3 scheme (http or https), if S3 is enabled. Default: https
  • vfs.s3.endpoint_override The S3 endpoint, if S3 is enabled. Default: “”
  • vfs.s3.use_virtual_addressing The S3 use of virtual addressing (true or false), if S3 is enabled. Default: true
  • vfs.s3.max_parallel_ops The maximum number of S3 backend parallel operations. Default: vfs.num_threads
  • vfs.s3.multipart_part_size The part size (in bytes) used in S3 multipart writes. Any uint64_t value is acceptable. Note: vfs.s3.multipart_part_size * vfs.s3.max_parallel_ops bytes will be buffered before issuing multipart uploads in parallel. Default: 5MB
  • vfs.s3.connect_timeout_ms The connection timeout in ms. Any long value is acceptable. Default: 3000
  • vfs.s3.connect_max_tries The maximum tries for a connection. Any long value is acceptable. Default: 5
  • vfs.s3.connect_scale_factor The scale factor for exponential backofff when connecting to S3. Any long value is acceptable. Default: 25
  • vfs.s3.request_timeout_ms The request timeout in ms. Any long value is acceptable. Default: 3000
  • vfs.s3.proxy_host The proxy host. Default: “”
  • vfs.s3.proxy_port The proxy port. Default: 0
  • vfs.s3.proxy_scheme The proxy scheme. Default: “https”
  • vfs.s3.proxy_username The proxy username. Note: this parameter is not serialized by tiledb_config_save_to_file. Default: “”
  • vfs.s3.proxy_password The proxy password. Note: this parameter is not serialized by tiledb_config_save_to_file. Default: “”
  • vfs.hdfs.name_node" Name node for HDFS. Default: “”
  • vfs.hdfs.username HDFS username. Default: “”
  • vfs.hdfs.kerb_ticket_cache_path HDFS kerb ticket cache path. Default: “”

Example:

tiledb_error_t* error = NULL;
tiledb_config_set(config, "sm.tile_cache_size", "1000000", &error);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • config: The config object.
  • param: The parameter to be set.
  • value: The value of the parameter to be set.
  • error: Error object returned upon error (NULL if there is no error).

int tiledb_config_get(tiledb_config_t * config, const char * param, const char ** value, tiledb_error_t ** error)

Gets a config parameter.

Example:

const char* value;
tiledb_error_t* error = NULL;
tiledb_config_get(config, "sm.tile_cache_size", &value, &error);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • config: The config object.
  • param: The parameter to be set.
  • value: A pointer to the value of the parameter to be retrieved (NULL if it does not exist).
  • error: Error object returned upon error (NULL if there is no error).

int tiledb_config_load_from_file(tiledb_config_t * config, const char * filename, tiledb_error_t ** error)

Loads config parameters from a (local) text file.

Example:

tiledb_error_t* error = NULL;
tiledb_config_load_from_file(config, "tiledb.conf", &error);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • config: The config object.
  • filename: The name of the file.
  • error: Error object returned upon error (NULL if there is no error).

int tiledb_config_unset(tiledb_config_t * config, const char * param, tiledb_error_t ** error)

Unsets a config parameter. This will set the config parameter to its default value.

Example:

tiledb_error_t* error = NULL;
tiledb_config_unset(config, "sm.tile_cache_size", &error);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • config: The config object.
  • param: The parameter to be unset.
  • error: Error object returned upon error (NULL if there is no error).

int tiledb_config_save_to_file(tiledb_config_t * config, const char * filename, tiledb_error_t ** error)

Saves the config parameters to a (local) text file.

Example:

tiledb_error_t* error = NULL;
tiledb_config_save_to_file(config, "tiledb.conf", &error);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • config: The config object.
  • filename: The name of the file.
  • error: Error object returned upon error (NULL if there is no error).

Config Iterator

int tiledb_config_iter_alloc(tiledb_config_t * config, const char * prefix, tiledb_config_iter_t ** config_iter, tiledb_error_t ** error)

Creates an iterator on a config object.

Examples:

The following creates a config iterator without a prefix. This will iterate over all config param/values.

tiledb_error_t* error = NULL;
tiledb_config_iter_t* config_iter;
tiledb_config_iter_alloc(config, NULL, &config_iter, &error);

The following creates a config iterator with a prefix. This will iterate over all S3 config param/values, stripping out vfs.s3.. For instance, instead of retrieving vfs.s3.region as a parameter via tiledb_config_iter_here, it will retrieve region.

tiledb_error_t* error = NULL;
tiledb_config_iter_t* config_iter;
tiledb_config_iter_alloc(config, "vfs.s3.", &config_iter, &error);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • config: A config object the iterator will operate on.
  • prefix: If not NULL, only the config parameters starting with prefix* will be iterated on. Moreover, the prefix will be stripped from the parameters. Otherwise, all parameters will be iterated on and their full name will be retrieved.
  • config_iter: The config iterator to be created.
  • error: Error object returned upon error (NULL if there is no error).

void tiledb_config_iter_free(tiledb_config_iter_t ** config_iter)

Frees a config iterator.

Example:

tiledb_config_iter_free(&config_iter);

Parameters
  • config_iter: The config iterator to be freed.

int tiledb_config_iter_here(tiledb_config_iter_t * config_iter, const char ** param, const char ** value, tiledb_error_t ** error)

Retrieves the config param and value currently pointed by the iterator.

Example:

const char *param, *value;
tiledb_config_iter_here(config_iter, &param, &value, &error);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • config_iter: The config iterator.
  • param: The config parameter to be retrieved (NULL if the iterator is at the end).
  • value: The config value to be retrieved (NULL if the iterator is at the end).
  • error: Error object returned upon error (NULL if there is no error).

int tiledb_config_iter_next(tiledb_config_iter_t * config_iter, tiledb_error_t ** error)

Moves the iterator to the next param.

Example:

tiledb_config_iter_next(config_iter, &error);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • config_iter: The config iterator.
  • error: Error object returned upon error (NULL if there is no error).

int tiledb_config_iter_done(tiledb_config_iter_t * config_iter, int * done, tiledb_error_t ** error)

Checks if the iterator is done.

Example:

int done;
tiledb_config_iter_done(config_iter, &done, &error);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • config_iter: The config iterator.
  • done: Sets this to 1 if the iterator is done, 0 otherwise.
  • error: Error object returned upon error (NULL if there is no error).

int tiledb_config_iter_reset(tiledb_config_t * config, tiledb_config_iter_t * config_iter, const char * prefix, tiledb_error_t ** error)

Resets the iterator.

Examples:

Without a prefix:

tiledb_config_iter_reset(config, config_iter, NULL, &error);

With a prefix:

tiledb_config_iter_reset(config, config_iter, "vfs.s3.", &error);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • config: A config object the iterator will operate on.
  • config_iter: The config iterator to be reset.
  • prefix: If not NULL, only the config parameters starting with prefix* will be iterated on. Moreover, the prefix will be stripped from the parameters. Otherwise, all parameters will be iterated on and their full name will be retrieved.
  • error: Error object returned upon error (NULL if there is no error).

Error

int tiledb_error_message(tiledb_error_t * err, const char ** errmsg)

Returns the error message associated with a TileDB error object.

Example:

The following shows how to get the last error from a TileDB context.

tiledb_error_t* err = NULL;
tiledb_ctx_get_last_error(ctx, &err);
const char* msg;
tiledb_error_message(err, &msg);
printf("%s\n", msg);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • err: A TileDB error object.
  • errmsg: A constant pointer to the error message.

void tiledb_error_free(tiledb_error_t ** err)

Frees the resources associated with a TileDB error object.

Example:

tiledb_error_t* err = NULL;
tiledb_ctx_get_last_error(ctx, &err);
const char* msg;
tiledb_error_message(err, &msg);
printf("%s\n", msg);
tiledb_error_free(&err);

Parameters
  • err: The TileDB error object.

Array

int tiledb_array_alloc(tiledb_ctx_t * ctx, const char * array_uri, tiledb_array_t ** array)

Allocates a TileDB array object.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_uri: The array URI.
  • array: The array object to be created.

int tiledb_array_open(tiledb_ctx_t * ctx, tiledb_array_t * array, tiledb_query_type_t query_type)

Opens a TileDB array. The array is opened using a query type as input. This is to indicate that queries created for this tiledb_array_t object will inherit the query type. In other words, tiledb_array_t objects are opened to receive only one type of queries. They can always be closed and be re-opened with another query type. Also there may be many different tiledb_array_t objects created and opened with different query types. For instance, one may create and open an array object array_read for reads and another one array_write for writes, and interleave creation and submission of queries for both these array objects.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Note
If the same array object is opened again without being closed, an error will be thrown.
Parameters
  • ctx: The TileDB context.
  • array: The array object to be opened.
  • query_type: The type of queries the array object will be receiving.

int tiledb_array_reopen(tiledb_ctx_t * ctx, tiledb_array_t * array)

Reopens a TileDB array (the array must be already open). This is useful when the array got updated after it got opened and the tiledb_array_t object got created. To sync-up with the updates, the user must either close the array and open with tiledb_array_open, or just use tiledb_array_reopen without closing. This function will be generally faster than the former alternative.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);
tiledb_array_reopen(ctx, array);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Note
This is applicable only to arrays opened for reads.
Parameters
  • ctx: The TileDB context.
  • array: The array object to be re-opened.

int tiledb_array_close(tiledb_ctx_t * ctx, tiledb_array_t * array)

Closes a TileDB array.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);
tiledb_array_close(ctx, array);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Note
If the array object has already been closed, the function has no effect.
Parameters
  • ctx: The TileDB context.
  • array: The array object to be closed.

void tiledb_array_free(tiledb_array_t ** array)

Frees a TileDB array object.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);
tiledb_array_close(ctx, array);
tiledb_array_free(&array);

Parameters
  • array: The array object to be freed.

int tiledb_array_create(tiledb_ctx_t * ctx, const char * array_uri, const tiledb_array_schema_t * array_schema)

Creates a new TileDB array given an input schema.

Example:

tiledb_array_create(ctx, "hdfs:///tiledb_arrays/my_array", array_schema);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_uri: The array name.
  • array_schema: The array schema.

int tiledb_array_consolidate(tiledb_ctx_t * ctx, const char * array_uri)

Consolidates the fragments of an array into a single fragment.

You must first finalize all queries to the array before consolidation can begin (as consolidation temporarily acquires an exclusive lock on the array).

Example:

tiledb_array_consolidate(ctx, "hdfs:///tiledb_arrays/my_array");

Return
TILEDB_OK on success, and TILEDB_ERR on error.
Parameters
  • ctx: The TileDB context.
  • array_uri: The name of the TileDB array to be consolidated.

int tiledb_array_get_schema(tiledb_ctx_t * ctx, tiledb_array_t * array, tiledb_array_schema_t ** array_schema)

Retrieves the schema of an array.

Example:

tiledb_array_schema_t* array_schema;
tiledb_array_get_schema(ctx, array, &array_schema);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Note
The user must free the array schema with tiledb_array_schema_free.
Parameters
  • ctx: The TileDB context.
  • array: The open array.
  • array_schema: The array schema to be retrieved.

int tiledb_array_get_query_type(tiledb_ctx_t * ctx, tiledb_array_t * array, tiledb_query_type_t * query_type)

Retrieves the query type with which the array was opened.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);
tiledb_query_type_t query_type;
tiledb_array_get_type(ctx, array, &query_type);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array: The array.
  • query_type: The query type to be retrieved.

int tiledb_array_get_non_empty_domain(tiledb_ctx_t * ctx, tiledb_array_t * array, void * domain, int * is_empty)

Retrieves the non-empty domain from an array. This is the union of the non-empty domains of the array fragments.

Example:

uint64_t domain[4]; // Assuming a 2D array, 2 [low, high] pairs
int is_empty;
tiledb_array_t* array;
tiledb_array_alloc(ctx, "my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);
tiledb_array_get_non_empty_domain(ctx, array, domain, &is_empty);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context
  • array: The array object (must be opened beforehand).
  • domain: The domain to be retrieved.
  • is_empty: The function sets it to 1 if the non-empty domain is empty (i.e., the array does not contain any data yet), and 0 otherwise.

int tiledb_array_max_buffer_size(tiledb_ctx_t * ctx, tiledb_array_t * array, const char * attribute, const void * subarray, uint64_t * buffer_size)

Computes an upper bound on the buffer size (in bytes) required for a read query, for a given **fixed-sized* attribute and subarray.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);
uint64_t buffer_size;
const char* attribute = "attr_1";
uint64_t subarray[] = {10, 20, 10, 100};
tiledb_array_max_buffer_size(ctx, array, attribute, subarray, buffer_size);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array: The array object (must be opened beforehand).
  • attribute: The fixed-sized attribute to focus on.
  • subarray: The subarray to focus on. Note that it must have the same underlying type as the array domain.
  • buffer_size: The buffer size (in bytes) to be retrieved.

int tiledb_array_max_buffer_size_var(tiledb_ctx_t * ctx, tiledb_array_t * array, const char * attribute, const void * subarray, uint64_t * buffer_off_size, uint64_t * buffer_val_size)

Computes an upper bound on the buffer size (in bytes) required for a read query, for a given **var-sized* attribute and subarray.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);
uint64_t buffer_off_size, buffer_val_size;
const char* attribute = "attr_2";
uint64_t subarray[] = {10, 20, 10, 100};
tiledb_array_max_buffer_size_var(
    ctx, array, attribute, subarray, buffer_off_size, buffer_val_size);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array: The array object (must be opened beforehand).
  • attribute: The var-sized attribute to focus on.
  • subarray: The subarray to focus on. Note that it must have the same underlying type as the array domain.
  • buffer_off_size: The offsets buffer size (in bytes) to be retrieved.
  • buffer_val_size: The values buffer size (in bytes) to be retrieved.

Array Schema

int tiledb_array_schema_alloc(tiledb_ctx_t * ctx, tiledb_array_type_t array_type, tiledb_array_schema_t ** array_schema)

Creates a TileDB array schema object.

Example:

tiledb_array_schema_t* array_schema;
tiledb_array_schema_alloc(ctx, TILEDB_DENSE, &array_schema);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_type: The array type.
  • array_schema: The TileDB array schema to be created.

void tiledb_array_schema_free(tiledb_array_schema_t ** array_schema)

Destroys an array schema, freeing associated memory.

Example:

tiledb_array_schema_free(&array_schema);

Parameters
  • array_schema: The array schema to be destroyed.

int tiledb_array_schema_add_attribute(tiledb_ctx_t * ctx, tiledb_array_schema_t * array_schema, tiledb_attribute_t * attr)

Adds an attribute to an array schema.

Example:

tiledb_attribute_t* attr;
tiledb_attribute_alloc(ctx, "my_attr", TILEDB_INT32, &attr);
tiledb_array_schema_add_attribute(ctx, array_schema, attr);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • attr: The attribute to be added.

int tiledb_array_schema_set_domain(tiledb_ctx_t * ctx, tiledb_array_schema_t * array_schema, tiledb_domain_t * domain)

Sets a domain for the array schema.

Example:

tiledb_domain_t* domain;
tiledb_domain_alloc(ctx, &domain);
// -- Add dimensions to the domain here -- //
tiledb_array_schema_set_domain(ctx, array_schema, domain);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • domain: The domain to be set.

int tiledb_array_schema_set_capacity(tiledb_ctx_t * ctx, tiledb_array_schema_t * array_schema, uint64_t capacity)

Sets the tile capacity.

Example:

tiledb_array_schema_set_capacity(ctx, array_schema, 10000);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • capacity: The capacity to be set.

int tiledb_array_schema_set_cell_order(tiledb_ctx_t * ctx, tiledb_array_schema_t * array_schema, tiledb_layout_t cell_order)

Sets the cell order.

Example:

tiledb_array_schema_set_cell_order(ctx, array_schema, TILEDB_ROW_MAJOR);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • cell_order: The cell order to be set.

int tiledb_array_schema_set_tile_order(tiledb_ctx_t * ctx, tiledb_array_schema_t * array_schema, tiledb_layout_t tile_order)

Sets the tile order.

Example:

tiledb_array_schema_set_cell_order(ctx, array_schema, TILEDB_COL_MAJOR);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • tile_order: The tile order to be set.

int tiledb_array_schema_set_coords_compressor(tiledb_ctx_t * ctx, tiledb_array_schema_t * array_schema, tiledb_compressor_t compressor, int compression_level)

Sets the compressor to use for the coordinates.

Example:

tiledb_array_schema_set_coords_compressor(
    ctx, array_schema, TILEDB_GZIP, -1);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • compressor: The coordinates compressor.
  • compression_level: The coordinates compression level (use -1 for default).

int tiledb_array_schema_set_offsets_compressor(tiledb_ctx_t * ctx, tiledb_array_schema_t * array_schema, tiledb_compressor_t compressor, int compression_level)

Sets the compressor to use for the offsets of variable-sized attribute values.

Example:

tiledb_array_schema_set_offsets_compressor(
    ctx, array_schema, TILEDB_GZIP, -1);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • compressor: The offsets compressor.
  • compression_level: The coordinates compression level (use -1 for default).

int tiledb_array_schema_check(tiledb_ctx_t * ctx, tiledb_array_schema_t * array_schema)

Checks the correctness of the array schema.

Example:

tiledb_array_schema_check(ctx, array_schema);

Return
TILEDB_OK if the array schema is correct and TILEDB_ERR upon any error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.

int tiledb_array_schema_load(tiledb_ctx_t * ctx, const char * array_uri, tiledb_array_schema_t ** array_schema)

Retrieves the schema of an array from the disk, creating an array schema struct.

Example:

tiledb_array_schema_t* array_schema;
tiledb_array_schema_load(ctx, "s3://tiledb_bucket/my_array", array_schema);
// Make sure to free the array schema in the end

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema to be retrieved, or NULL upon error.
  • array_uri: The array whose schema will be retrieved.

int tiledb_array_schema_get_array_type(tiledb_ctx_t * ctx, const tiledb_array_schema_t * array_schema, tiledb_array_type_t * array_type)

Retrieves the array type.

Example:

tiledb_array_schema_t* array_schema;
tiledb_array_schema_load(ctx, "s3://tiledb_bucket/my_array", array_schema);
tiledb_array_type_t* array_type;
tiledb_array_schema_get_array_type(ctx, array_schema, &array_type);
// Make sure to free the array schema in the end

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • array_type: The array type to be retrieved.

int tiledb_array_schema_get_capacity(tiledb_ctx_t * ctx, const tiledb_array_schema_t * array_schema, uint64_t * capacity)

Retrieves the capacity.

Example:

uint64_t capacity;
tiledb_array_schema_get_capacity(ctx, array_schema, &capacity);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • capacity: The capacity to be retrieved.

int tiledb_array_schema_get_cell_order(tiledb_ctx_t * ctx, const tiledb_array_schema_t * array_schema, tiledb_layout_t * cell_order)

Retrieves the cell order.

Example:

tiledb_layout_t cell_order;
tiledb_array_schema_get_cell_order(ctx, array_schema, &cell_order);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • cell_order: The cell order to be retrieved.

int tiledb_array_schema_get_coords_compressor(tiledb_ctx_t * ctx, const tiledb_array_schema_t * array_schema, tiledb_compressor_t * compressor, int * compression_level)

Retrieves the compressor info of the coordinates.

Example:

tiledb_compressor_t compressor;
int level;
tiledb_array_schema_get_coords_compressor(
    ctx, array_schema, &compressor, &level);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • compressor: The compressor to be retrieved.
  • compression_level: The compression level to be retrieved.

int tiledb_array_schema_get_offsets_compressor(tiledb_ctx_t * ctx, const tiledb_array_schema_t * array_schema, tiledb_compressor_t * compressor, int * compression_level)

Retrieves the compressor info of the offsets.

Example:

tiledb_compressor_t compressor;
int level;
tiledb_array_schema_get_offsets_compressor(
    ctx, array_schema, &compressor, &level);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • compressor: The compressor to be retrieved.
  • compression_level: The compression level to be retrieved.

int tiledb_array_schema_get_domain(tiledb_ctx_t * ctx, const tiledb_array_schema_t * array_schema, tiledb_domain_t ** domain)

Retrieves the array domain.

Example:

tiledb_domain_t* domain;
tiledb_array_schema_get_domain(ctx, array_schema, &domain);
// Make sure to delete domain in the end

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • domain: The array domain to be retrieved.

int tiledb_array_schema_get_tile_order(tiledb_ctx_t * ctx, const tiledb_array_schema_t * array_schema, tiledb_layout_t * tile_order)

Retrieves the tile order.

Example:

tiledb_layout_t tile_order;
tiledb_array_schema_get_tile_order(ctx, array_schema, &tile_order);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • tile_order: The tile order to be retrieved.

int tiledb_array_schema_get_attribute_num(tiledb_ctx_t * ctx, const tiledb_array_schema_t * array_schema, unsigned int * attribute_num)

Retrieves the number of array attributes.

Example:

unsigned attr_num;
tiledb_array_schema_get_attribute_num(ctx, array_schema, &attr_num);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • attribute_num: The number of attributes to be retrieved.

int tiledb_array_schema_get_attribute_from_index(tiledb_ctx_t * ctx, const tiledb_array_schema_t * array_schema, unsigned int index, tiledb_attribute_t ** attr)

Retrieves an attribute given its index.

Attributes are ordered the same way they were defined when constructing the array schema.

Example:

The following retrieves the first attribute in the schema.

tiledb_attribute_t* attr;
tiledb_array_schema_get_attribute_from_index(ctx, array_schema, 0, &attr);
// Make sure to delete the retrieved attribute in the end.

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • index: The index of the attribute to retrieve.
  • attr: The attribute object to retrieve.

int tiledb_array_schema_get_attribute_from_name(tiledb_ctx_t * ctx, const tiledb_array_schema_t * array_schema, const char * name, tiledb_attribute_t ** attr)

Retrieves an attribute given its name (key).

Example:

The following retrieves the first attribute in the schema.

tiledb_attribute_t* attr;
tiledb_array_schema_get_attribute_from_index(ctx, array_schema, "attr_0",
&attr);
// Make sure to delete the retrieved attribute in the end.

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • name: The name (key) of the attribute to retrieve.
  • attr: THe attribute object to retrieve.

int tiledb_array_schema_dump(tiledb_ctx_t * ctx, const tiledb_array_schema_t * array_schema, FILE * out)

Dumps the array schema in ASCII format in the selected output.

Example:

The following prints the array schema dump in standard output.

tiledb_array_schema_dump(ctx, array_schema, stdout);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • array_schema: The array schema.
  • out: The output.

Attribute

int tiledb_attribute_alloc(tiledb_ctx_t * ctx, const char * name, tiledb_datatype_t type, tiledb_attribute_t ** attr)

Creates a TileDB attribute.

Example:

tiledb_attribute_t* attr;
tiledb_attribute_alloc(ctx, "my_attr", TILEDB_INT32, &attr);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Note
The default number of values per cell is 1.
Parameters
  • ctx: The TileDB context.
  • name: The attribute name. Providing an empty string for the name creates an anonymous attribute.
  • type: The attribute type.
  • attr: The TileDB attribute to be created.

void tiledb_attribute_free(tiledb_attribute_t ** attr)

Destroys a TileDB attribute, freeing associated memory.

Example:

tiledb_attribute_t* attr;
tiledb_attribute_alloc(ctx, "my_attr", TILEDB_INT32, &attr);
tiledb_attribute_free(&attr);

Parameters
  • attr: The attribute to be destroyed.

int tiledb_attribute_set_compressor(tiledb_ctx_t * ctx, tiledb_attribute_t * attr, tiledb_compressor_t compressor, int compression_level)

Sets a compressor for an attribute.

Example:

tiledb_attribute_set_compressor(ctx, attr, TILEDB_BLOSC_ZSTD, -1);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • attr: The target attribute.
  • compressor: The compressor to be set.
  • compression_level: The compression level (use -1 for default).

int tiledb_attribute_set_cell_val_num(tiledb_ctx_t * ctx, tiledb_attribute_t * attr, unsigned int cell_val_num)

Sets the number of values per cell for an attribute. If this is not used, the default is 1.

Examples:

For a fixed-sized attribute:

tiledb_attribute_set_cell_val_num(ctx, attr, 3);

For a variable-sized attribute:

tiledb_attribute_set_cell_val_num(ctx, attr, TILEDB_VAR_NUM);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • attr: The target attribute.
  • cell_val_num: The number of values per cell.

int tiledb_attribute_get_name(tiledb_ctx_t * ctx, const tiledb_attribute_t * attr, const char ** name)

Retrieves the attribute name.

Example:

const char* attr_name;
tiledb_attribute_get_name(ctx, attr, &attr_name);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • attr: The attribute.
  • name: The name to be retrieved.

int tiledb_attribute_get_type(tiledb_ctx_t * ctx, const tiledb_attribute_t * attr, tiledb_datatype_t * type)

Retrieves the attribute type.

Example:

tiledb_datatype_t attr_type;
tiledb_attribute_get_type(ctx, attr, &attr_type);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • attr: The attribute.
  • type: The type to be retrieved.

int tiledb_attribute_get_compressor(tiledb_ctx_t * ctx, const tiledb_attribute_t * attr, tiledb_compressor_t * compressor, int * compression_level)

Retrieves the attribute compressor and the compression level.

Example:

tiledb_compressor_t compressor;
int level;
tiledb_attribute_get_compressor(ctx, attr, &compressor, &level);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • attr: The attribute.
  • compressor: The compressor to be retrieved.
  • compression_level: The compression level to be retrieved.

int tiledb_attribute_get_cell_val_num(tiledb_ctx_t * ctx, const tiledb_attribute_t * attr, unsigned int * cell_val_num)

Retrieves the number of values per cell for the attribute. For variable-sized attributes result is TILEDB_VAR_NUM.

Example:

unsigned num;
tiledb_attribute_get_cell_val_num(ctx, attr, &num);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • attr: The attribute.
  • cell_val_num: The number of values per cell to be retrieved.

int tiledb_attribute_get_cell_size(tiledb_ctx_t * ctx, const tiledb_attribute_t * attr, uint64_t * cell_size)

Retrieves the cell size for this attribute.

Example:

uint64_t cell_size;
tiledb_attribute_get_cell_size(ctx, attr, &cell_size);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • attr: The attribute.
  • cell_size: The cell size to be retrieved.

int tiledb_attribute_dump(tiledb_ctx_t * ctx, const tiledb_attribute_t * attr, FILE * out)

Dumps the contents of an attribute in ASCII form to some output (e.g., file or stdout).

Example:

The following prints the attribute dump to standard output.

tiledb_attribute_dump(ctx, attr, stdout);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • attr: The attribute.
  • out: The output.

Domain

int tiledb_domain_alloc(tiledb_ctx_t * ctx, tiledb_domain_t ** domain)

Creates a TileDB domain.

Example:

tiledb_domain_t* domain;
tiledb_domain_alloc(ctx, &domain);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • domain: The TileDB domain to be created.

void tiledb_domain_free(tiledb_domain_t ** domain)

Destroys a TileDB domain, freeing associated memory.

Example:

tiledb_domain_t* domain;
tiledb_domain_alloc(ctx, &domain);
tiledb_domain_free(&domain);

Parameters
  • domain: The domain to be destroyed.

int tiledb_domain_get_type(tiledb_ctx_t * ctx, const tiledb_domain_t * domain, tiledb_datatype_t * type)

Retrieves the domain’s type.

Example:

tiledb_datatype_t type;
tiledb_domain_get_type(ctx, domain, &type);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • domain: The domain.
  • type: The type to be retrieved.

int tiledb_domain_get_ndim(tiledb_ctx_t * ctx, const tiledb_domain_t * domain, unsigned int * ndim)

Retrieves the number of dimensions in a domain.

Example:

unsigned dim_num;
tiledb_domain_get_ndim(ctx, domain, &dim_num);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context
  • domain: The domain
  • ndim: The number of dimensions in a domain.

int tiledb_domain_add_dimension(tiledb_ctx_t * ctx, tiledb_domain_t * domain, tiledb_dimension_t * dim)

Adds a dimension to a TileDB domain.

Example:

tiledb_dimension_t* dim;
uint64_t dim_domain[] = {1, 10};
tiledb_dimension_alloc(ctx, "dim_0", TILEDB_INT64, dim_domain, 5, &dim);
tiledb_domain_add_dimension(ctx, domain, dim);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • domain: The domain to add the dimension to.
  • dim: The dimension to be added.

int tiledb_domain_get_dimension_from_index(tiledb_ctx_t * ctx, const tiledb_domain_t * domain, unsigned int index, tiledb_dimension_t ** dim)

Retrieves a dimension object from a domain by index.

Example:

The following retrieves the first dimension from a domain.

tiledb_dimension_t* dim;
tiledb_domain_get_dimension_from_index(ctx, domain, 0, &dim);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context
  • domain: The domain to add the dimension to.
  • index: The index of domain dimension
  • dim: The retrieved dimension object.

int tiledb_domain_get_dimension_from_name(tiledb_ctx_t * ctx, const tiledb_domain_t * domain, const char * name, tiledb_dimension_t ** dim)

Retrieves a dimension object from a domain by name (key).

Example:

tiledb_dimension_t* dim;
tiledb_domain_get_dimension_from_name(ctx, domain, "dim_0", &dim);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context
  • domain: The domain to add the dimension to.
  • name: The name (key) of the requested dimension
  • dim: The retrieved dimension object.

int tiledb_domain_dump(tiledb_ctx_t * ctx, const tiledb_domain_t * domain, FILE * out)

Dumps the info of a domain in ASCII form to some output (e.g., file or stdout).

Example:

The following prints the domain dump to the standard output.

tiledb_domain_dump(ctx, domain, stdout);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • domain: The domain.
  • out: The output.

Dimension

int tiledb_dimension_alloc(tiledb_ctx_t * ctx, const char * name, tiledb_datatype_t type, const void * dim_domain, const void * tile_extent, tiledb_dimension_t ** dim)

Creates a dimension.

Example:

tiledb_dimension_t* dim;
uint64_t dim_domain[] = {1, 10};
tiledb_dimension_alloc(ctx, "dim_0", TILEDB_INT64, dim_domain, 5, &dim);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • name: The dimension name.
  • type: The dimension type.
  • dim_domain: The dimension domain.
  • tile_extent: The dimension tile extent. This may be NULL, which is equivalent to the entire domain.
  • dim: The dimension to be created.

void tiledb_dimension_free(tiledb_dimension_t ** dim)

Destroys a TileDB dimension, freeing associated memory.

Example:

tiledb_dimension_free(&dim);

Parameters
  • dim: The dimension to be destroyed.

int tiledb_dimension_get_name(tiledb_ctx_t * ctx, const tiledb_dimension_t * dim, const char ** name)

Retrieves the dimension name.

Example:

const char* dim_name;
tiledb_dimension_get_name(ctx, dim, &dim_name);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • dim: The dimension.
  • name: The name to be retrieved.

int tiledb_dimension_get_type(tiledb_ctx_t * ctx, const tiledb_dimension_t * dim, tiledb_datatype_t * type)

Retrieves the dimension type.

Example:

tiledb_datatype_t dim_type;
tiledb_dimension_get_type(ctx, dim, &dim_type);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • dim: The dimension.
  • type: The type to be retrieved.

int tiledb_dimension_get_domain(tiledb_ctx_t * ctx, const tiledb_dimension_t * dim, void ** domain)

Retrieves the domain of the dimension.

Example:

uint64_t domain[2];
tiledb_dimension_get_domain(ctx, dim, &domain);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • dim: The dimension.
  • domain: The domain to be retrieved. Note that the defined type of input domain must be the same as the dimension type, otherwise the behavior is unpredictable (it will probably segfault).

int tiledb_dimension_get_tile_extent(tiledb_ctx_t * ctx, const tiledb_dimension_t * dim, void ** tile_extent)

Retrieves the tile extent of the dimension.

Example:

uint64_t tile_extent;
tiledb_dimension_get_tile_extent(ctx, dim, &tile_extent);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • dim: The dimension.
  • tile_extent: The tile extent to be retrieved. Note that the defined type of input tile_extent must be the same as the dimension type, otherwise the behavior is unpredictable (it will probably segfault).

int tiledb_dimension_dump(tiledb_ctx_t * ctx, const tiledb_dimension_t * dim, FILE * out)

Dumps the contents of a dimension in ASCII form to some output (e.g., file or stdout).

Example:

The following prints the dimension dump to standard output.

tiledb_dimension_dump(ctx, dim, stdout);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • dim: The dimension.
  • out: The output.

Query

int tiledb_query_alloc(tiledb_ctx_t * ctx, tiledb_array_t * array, tiledb_query_type_t query_type, tiledb_query_t ** query)

Creates a TileDB query object. Note that the query object is associated with a specific array object. The query type (read or write) is inferred from the array object, which was opened with a specific query type.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "file:///my_array", &array);
tiledb_array_open(ctx, array, TILEDB_WRITE);
tiledb_query_t* query;
tiledb_query_alloc(ctx, array, TILEDB_WRITE, &query);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • query: The query object to be created.
  • array: An opened array object.
  • query_type: The query type. This must comply with the query type array was opened.

int tiledb_query_set_subarray(tiledb_ctx_t * ctx, tiledb_query_t * query, const void * subarray)

Indicates that the query will write or read a subarray, and provides the appropriate information.

Example:

The following sets a 2D subarray [0,10], [20, 30] to the query.

uint64_t subarray[] = { 0, 10, 20, 30};
tiledb_query_set_subarray(ctx, query, subarray);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Note
If you set the subarray of a completed, incomplete or in-progress query, this function will clear the internal state and render it as uninitialized. However, the potentially set layout and attribute buffers will be retained. This is useful when the user wishes to fix the attributes and layout, but explore different subarrays with the same tiledb_query_t object (i.e., without having to created a new object).
Parameters
  • ctx: The TileDB context.
  • query: The TileDB query.
  • subarray: The subarray in which the array read/write will be constrained on. It should be a sequence of [low, high] pairs (one pair per dimension). For the case of writes, this is meaningful only for dense arrays, and specifically dense writes. Note that subarray must have the same type as the domain.

int tiledb_query_set_buffer(tiledb_ctx_t * ctx, tiledb_query_t * query, const char * attribute, void * buffer, uint64_t * buffer_size)

Sets the buffer for a fixed-sized attribute to a query, which will either hold the values to be written (if it is a write query), or will hold the results from a read query.

Example:

int a1[100];
uint64_t a2_size = sizeof(a1);
tiledb_query_set_buffer(ctx, query, "a1", a1, &a2_size);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • query: The TileDB query.
  • attribute: The attribute to set the buffer for. Note that the coordinates have special attribute name TILEDB_COORDS.
  • buffer: The buffer that either have the input data to be written, or will hold the data to be read.
  • buffer_size: In the case of writes, this is the size of buffer in bytes. In the case of reads, this initially contains the allocated size of buffer, but after the termination of the function it will contain the size of the useful (read) data in buffer.

int tiledb_query_set_buffer_var(tiledb_ctx_t * ctx, tiledb_query_t * query, const char * attribute, uint64_t * buffer_off, uint64_t * buffer_off_size, void * buffer_val, uint64_t * buffer_val_size)

Sets the buffer for a var-sized attribute to a query, which will either hold the values to be written (if it is a write query), or will hold the results from a read query.

Example:

uint64_t a2_off[10];
uint64_t a2_off_size = sizeof(a2_off);
char a2_val[100];
uint64_t a2_val_size = sizeof(a2_val);
tiledb_query_set_buffer_var(
    ctx, query, "a2", a2_off, &a2_off_size, a2_val, &a2_val_size);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • query: The TileDB query.
  • attribute: The attribute to set the buffer for.
  • buffer_off: The buffer that either have the input data to be written, or will hold the data to be read. This buffer holds the starting offsets of each cell value in buffer_val.
  • buffer_off_size: In the case of writes, it is the size of buffer_off in bytes. In the case of reads, this initially contains the allocated size of buffer_off, but after the termination of the function it will contain the size of the useful (read) data in buffer_off.
  • buffer_val: The buffer that either have the input data to be written, or will hold the data to be read. This buffer holds the actual var-sized cell values.
  • buffer_val_size: In the case of writes, it is the size of buffer_val in bytes. In the case of reads, this initially contains the allocated size of buffer_val, but after the termination of the function it will contain the size of the useful (read) data in buffer_val.

int tiledb_query_set_layout(tiledb_ctx_t * ctx, tiledb_query_t * query, tiledb_layout_t layout)

Sets the layout of the cells to be written or read.

Example:

tiledb_query_set_layout(ctx, query, TILEDB_ROW_MAJOR);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • query: The TileDB query.
  • layout: For a write query, this specifies the order of the cells provided by the user in the buffers. For a read query, this specifies the order of the cells that will be retrieved as results and stored in the user buffers. The layout can be one of the following:
    • TILEDB_COL_MAJOR: This means column-major order with respect to the subarray.
    • TILEDB_ROW_MAJOR: This means row-major order with respect to the subarray.
    • TILEDB_GLOBAL_ORDER: This means that cells are stored or retrieved in the array global cell order.
    • TILEDB_UNORDERED: This is applicable only to writes for sparse arrays, or for sparse writes to dense arrays. It specifies that the cells are unordered and, hence, TileDB must sort the cells in the global cell order prior to writing.

void tiledb_query_free(tiledb_query_t ** query)

Frees a TileDB query object.

Example:

tiledb_query_free(&query);

Parameters
  • query: The query object to be deleted.

int tiledb_query_finalize(tiledb_ctx_t * ctx, tiledb_query_t * query)

Flushes all internal state of a query object and finalizes the query. This is applicable only to global layout writes. It has no effect for any other query type.

Example:

tiledb_query_t* query;
// ... Your code here ... //
tiledb_query_finalize(ctx, query);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • query: The query object to be flushed.

int tiledb_query_submit(tiledb_ctx_t * ctx, tiledb_query_t * query)

Submits a TileDB query.

Example:

tiledb_query_submit(ctx, &query);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Note
tiledb_query_finalize must be invoked after finish writing in global layout (via repeated invocations of tiledb_query_submit), in order to flush any internal state.
Note
For the case of reads, if the returned status is TILEDB_INCOMPLETE, TileDB could not fit the entire result in the user’s buffers. In this case, the user should consume the read results (if any), optionally reset the buffers with tiledb_query_set_buffer, and then resubmit the query until the status becomes TILEDB_COMPLETED. If all buffer sizes after the termination of this function become 0, then this means that no useful data was read into the buffers, implying that larger buffers are needed for the query to proceed. In this case, the users must reallocate their buffers (increasing their size), reset the buffers with tiledb_query_set_buffer, and resubmit the query.
Parameters
  • ctx: The TileDB context.
  • query: The query to be submitted.

int tiledb_query_submit_async(tiledb_ctx_t * ctx, tiledb_query_t * query, void(*callback)(void *), void * callback_data)

Submits a TileDB query in asynchronous mode.

Examples:

Submit without a callback.

tiledb_query_submit_async(ctx, &query, NULL, NULL);

Submit with a callback function print that takes as input message msg and prints it upon completion of the query.

const char* msg = "Query completed";
tiledb_query_submit_async(ctx, &query, foo, msg);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Note
tiledb_query_finalize must be invoked after finish writing in global layout (via repeated invocations of tiledb_query_submit), in order to flush any internal state.
Note
For the case of reads, if the returned status is TILEDB_INCOMPLETE, TileDB could not fit the entire result in the user’s buffers. In this case, the user should consume the read results (if any), optionally reset the buffers with tiledb_query_set_buffer, and then resubmit the query until the status becomes TILEDB_COMPLETED. If all buffer sizes after the termination of this function become 0, then this means that no useful data was read into the buffers, implying that larger buffers are needed for the query to proceed. In this case, the users must reallocate their buffers (increasing their size), reset the buffers with tiledb_query_set_buffer, and resubmit the query.
Parameters
  • ctx: The TileDB context.
  • query: The query to be submitted.
  • callback: The function to be called when the query completes.
  • callback_data: The data to be passed to the callback function.

int tiledb_query_get_status(tiledb_ctx_t * ctx, tiledb_query_t * query, tiledb_query_status_t * status)

Retrieves the status of a query.

Example:

tiledb_query_status_t status;
tiledb_query_get_status(ctx, query, &status);

Return
TILEDB_OK upon success, and TILEDB_ERR upon error.
Parameters
  • ctx: The TileDB context.
  • query: The query.
  • status: The query status to be retrieved.

int tiledb_query_get_type(tiledb_ctx_t * ctx, tiledb_query_t * query, tiledb_query_type_t * query_type)

Retrieves the query type.

Example:

tiledb_query_type_t query_type;
tiledb_query_get_status(ctx, query, &query_type);

Return
TILEDB_OK upon success, and TILEDB_ERR upon error.
Parameters
  • ctx: The TileDB context.
  • query: The query.
  • query_type: The query type to be retrieved.

int tiledb_query_has_results(tiledb_ctx_t * ctx, tiledb_query_t * query, int * has_results)

Checks if the query has returned any results. Applicable only to read queries; it sets has_results to `0 in the case of writes.

Example:

int has_results;
tiledb_query_has_results(ctx, query, &has_results);

Return
TILEDB_OK upon success, and TILEDB_ERR upon error.
Parameters
  • ctx: The TileDB context.
  • query: The query.
  • has_results: Set to 1 if the query returned results and 0 otherwise.

Group

int tiledb_group_create(tiledb_ctx_t * ctx, const char * group_uri)

Creates a new TileDB group.

Example:

tiledb_group_create(ctx, "my_group");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • group_uri: The group URI.

Key-value

int tiledb_kv_alloc(tiledb_ctx_t * ctx, const char * kv_uri, tiledb_kv_t ** kv)

Creates a key-value store object.

Example:

tiledb_kv_t* kv;
tiledb_kv_alloc(ctx, "my_kv", &kv);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_uri: The URI of the key-value store.
  • kv: The key-value store object to be created.

int tiledb_kv_create(tiledb_ctx_t * ctx, const char * kv_uri, const tiledb_kv_schema_t * kv_schema)

Creates a key-value store from the input key-value schema.

Example:

tiledb_kv_create(ctx, "my_kv", kv_schema);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_uri: The URI of the key-value store.
  • kv_schema: The key-value store schema.

int tiledb_kv_consolidate(tiledb_ctx_t * ctx, const char * kv_uri)

Consolidates the fragments of a key-value store into a single fragment.

Example:

tiledb_kv_consolidate(ctx, "my_kv");

Return
TILEDB_OK on success, and TILEDB_ERR on error.
Parameters
  • ctx: The TileDB context.
  • kv_uri: The name of the TileDB key-value store to be consolidated.

int tiledb_kv_set_max_buffered_items(tiledb_ctx_t * ctx, tiledb_kv_t * kv, uint64_t max_items)

Sets the parameter that dictates the maximum number of written items buffered in memory before a flush is initiated.

Example:

tiledb_kv_set_max_buffered_items(ctx, kv, 1000);

Return
TILEDB_OK on success, and TILEDB_ERR on error.
Parameters
  • ctx: The TileDB context.
  • kv: The key-value store.
  • max_items: The number of maximum items to be set.

int tiledb_kv_open(tiledb_ctx_t * ctx, tiledb_kv_t * kv, const char ** attributes, unsigned int attribute_num)

Prepares a key-value store for reading/writing.

Example:

tiledb_kv_t* kv;
tiledb_kv_alloc(ctx, "my_kv", &kv);
const char* attributes[] = {"attr_1", "attr_2"};
tiledb_kv_open(ctx, kv, attributes, 2);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Note
If the key-value store is already open, the function throws an error.
Parameters
  • ctx: The TileDB context.
  • kv: The key-value store object to be opened.
  • attributes: The attributes to focus on. NULL indicates all attributes. If the key-value object is used for writing key-value items, all attributes must be specified.
  • attribute_num: The number of attributes.

int tiledb_kv_reopen(tiledb_ctx_t * ctx, tiledb_kv_t * kv)

Reopens a key-value store. This is useful when there were updates to the key-value store after it got opened. This function reopens the key-value store so that it can “see” the new fragments.

Example:

tiledb_kv_t* kv;
tiledb_kv_alloc(ctx, "my_kv", &kv);
const char* attributes[] = {"attr_1", "attr_2"};
tiledb_kv_open(ctx, kv, attributes, 2);
// Some code here
tiledb_kv_reopen(ctx, kv);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Note
Parameters
  • ctx: The TileDB context.
  • kv: An opened key-value store object.

int tiledb_kv_close(tiledb_ctx_t * ctx, tiledb_kv_t * kv)

Closes a key-value store and frees all memory. All buffered written items will be flushed to persistent storage.

Example:

tiledb_kv_close(ctx, kv);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Note
If the kv object is already closed, this function has no effect.
Parameters
  • ctx: The TileDB context.
  • kv: The key-value store to be closed.

void tiledb_kv_free(tiledb_kv_t ** kv)

Frees the key-value store object.

Parameters
  • kv: The key-value store object to be freed.

int tiledb_kv_add_item(tiledb_ctx_t * ctx, tiledb_kv_t * kv, tiledb_kv_item_t * kv_item)

Adds a key-value item to a key-value store. The item is buffered internally and periodically flushed to persistent storage. tiledb_kv_flush forces flushing the buffered items to storage.

Example:

tiledb_kv_item_t* kv_item;
tiledb_kv_item_alloc(ctx, &kv_item);
// Add a key and values to the kv item...
tiledb_kv_add_item(ctx, kv, kv_item);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv: The key-value store.
  • kv_item: The key-value item to be added to the store.

int tiledb_kv_flush(tiledb_ctx_t * ctx, tiledb_kv_t * kv)

Flushes the buffered items to persistent storage.

Example:

tiledb_kv_flush(ctx, kv);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv: The key-value store.

int tiledb_kv_get_item(tiledb_ctx_t * ctx, tiledb_kv_t * kv, const void * key, tiledb_datatype_t key_type, uint64_t key_size, tiledb_kv_item_t ** kv_item)

Retrieves a key-value item based on the input key. If the item with the input key does not exist, kv_item is set to NULL.

Example:

tiledb_kv_item_t* kv_item;
tiledb_kv_get_item(ctx, kv, "my_key", TILEDB_CHAR, strlen(my_key), &kv_item);
// Make sure to delete the kv item in the end

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv: The key-value store.
  • key: The key.
  • key_type: The key type.
  • key_size: The key size.
  • kv_item: The key-value item to be retrieved.

int tiledb_kv_get_schema(tiledb_ctx_t * ctx, tiledb_kv_t * kv, tiledb_kv_schema_t ** kv_schema)

Retrieves the schema of a kv object.

Example:

tiledb_kv_schema_t* kv_schema;
tiledb_kv_get_schema(ctx, kv, &kv_schema);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Note
The user must free the kv schema with tiledb_kv_schema_free.
Parameters
  • ctx: The TileDB context.
  • kv: The open kv.
  • kv_schema: The kv schema to be retrieved.

int tiledb_kv_has_key(tiledb_ctx_t * ctx, tiledb_kv_t * kv, const void * key, tiledb_datatype_t key_type, uint64_t key_size, int * has_key)

Checks if a key exists in the key-value store.

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv: The key-value store.
  • key: The key to check.
  • key_type: The key type.
  • key_size: The key size.
  • has_key: Set to 1 if the key exists and 0 otherwise.

int tiledb_kv_is_dirty(tiledb_ctx_t * ctx, tiledb_kv_t * kv, int * is_dirty)

Checks if the key-value store is dirty, i.e., if the user added items to the key-value store that are kept in main-memory and have not been flushed to persistent storage.

Example:

int is_dirty;
tiledb_kv_is_dirty(ctx, kv, &is_dirty);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv: The open kv.
  • is_dirty: Set to 1 or 0 based on whether the key-value store is dirty or not, respectively.

Key-value Schema

int tiledb_kv_schema_alloc(tiledb_ctx_t * ctx, tiledb_kv_schema_t ** kv_schema)

Creates a TileDB key-value schema object.

Example:

tiledb_kv_schema_t* kv_schema;
tiledb_kv_schema_alloc(ctx, &kv_schema);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_schema: The TileDB key-value schema to be created.

void tiledb_kv_schema_free(tiledb_kv_schema_t ** kv_schema)

Destroys a key-value schema, freeing associated memory.

Example:

tiledb_kv_schema_free(&kv_schema);

Parameters
  • kv_schema: The key-value schema to be destroyed.

int tiledb_kv_schema_add_attribute(tiledb_ctx_t * ctx, tiledb_kv_schema_t * kv_schema, tiledb_attribute_t * attr)

Adds an attribute to a key-value schema.

Example:

tiledb_attribute_t* attr;
tiledb_attribute_alloc(ctx, "my_attr", TILEDB_INT32, &attr);
tiledb_kv_schema_add_attribute(ctx, kv_schema, attr);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_schema: The key-value schema.
  • attr: The attribute to be added.

int tiledb_kv_schema_check(tiledb_ctx_t * ctx, tiledb_kv_schema_t * kv_schema)

Checks the correctness of the key-value schema.

Example:

tiledb_kv_schema_check(ctx, kv_schema);

Return
TILEDB_OK if the key-value schema is correct and TILEDB_ERR upon any error.
Parameters
  • ctx: The TileDB context.
  • kv_schema: The key-value schema.

int tiledb_kv_schema_load(tiledb_ctx_t * ctx, const char * kv_uri, tiledb_kv_schema_t ** kv_schema)

Retrieves the schema of a key-value store from the disk, creating a key-value schema struct.

Example:

tiledb_kv_schema_t* kv_schema;
tiledb_kv_schema_load(ctx, "file:///my_kv", &kv_schema);
// Make sure to delete the kv schema in the end

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_uri: The key-value store whose schema will be retrieved.
  • kv_schema: The key-value schema to be retrieved, or NULL upon error.

int tiledb_kv_schema_get_attribute_num(tiledb_ctx_t * ctx, const tiledb_kv_schema_t * kv_schema, unsigned int * attribute_num)

Retrieves the number of array attributes.

Example:

unsigned attribute_num;
tiledb_kv_schema_get_attribute_num(ctx, kv_schema, &attribute_num);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_schema: The key-value schema.
  • attribute_num: The number of attributes to be retrieved.

int tiledb_kv_schema_get_attribute_from_index(tiledb_ctx_t * ctx, const tiledb_kv_schema_t * kv_schema, unsigned int index, tiledb_attribute_t ** attr)

Retrieves an attribute given its index.

Attributes are ordered the same way they were defined when constructing the key-value schema.

Example:

The following retrieves the first attribute in the kv schema.

tiledb_attribute_t* attr;
tiledb_kv_schema_get_attribute_from_index(ctx, kv_schema, 0, &attr);
// Make sure to delete the attribute in the end

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_schema: The key-value schema.
  • index: The index of the attribute to retrieve.
  • attr: The attribute object to retrieve.

int tiledb_kv_schema_get_attribute_from_name(tiledb_ctx_t * ctx, const tiledb_kv_schema_t * kv_schema, const char * name, tiledb_attribute_t ** attr)

Retrieves an attribute given its name (key).

Example:

tiledb_attribute_t* attr;
tiledb_kv_schema_get_attribute_from_name(ctx, kv_schema, "my_attr", &attr);
// Make sure to delete the attribute in the end

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_schema: The key-value schema.
  • name: The name (key) of the attribute to retrieve.
  • attr: THe attribute object to retrieve.

int tiledb_kv_schema_dump(tiledb_ctx_t * ctx, const tiledb_kv_schema_t * kv_schema, FILE * out)

Dumps the key-value schema in ASCII format in the selected output.

Example:

The following prints the kv schema dump to standard output.

tiledb_kv_schema_dump(ctx, kv_schema, stdout);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_schema: The key-value schema.
  • out: The output.

int tiledb_kv_schema_set_capacity(tiledb_ctx_t * ctx, tiledb_kv_schema_t * kv_schema, uint64_t capacity)

Sets the tile capacity.

Example:

tiledb_kv_schema_set_capacity(ctx, kv_schema, 10000);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_schema: The kv schema.
  • capacity: The capacity to be set.

int tiledb_kv_schema_get_capacity(tiledb_ctx_t * ctx, const tiledb_kv_schema_t * kv_schema, uint64_t * capacity)

Retrieves the capacity.

Example:

uint64_t capacity;
tiledb_kv_schema_get_capacity(ctx, kv_schema, &capacity);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_schema: The kv schema.
  • capacity: The capacity to be retrieved.

Key-value Item

int tiledb_kv_item_alloc(tiledb_ctx_t * ctx, tiledb_kv_item_t ** kv_item)

Creates a key-value item.

Example:

tiledb_kv_item_t* kv_item;
tiledb_kv_item_alloc(ctx, &kv_item);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_item: The key-value item to be created.

void tiledb_kv_item_free(tiledb_kv_item_t ** kv_item)

Frees a key-value item.

Example:

tiledb_kv_item_free(&kv_item);

Parameters
  • kv_item: The key-value item to be freed.

int tiledb_kv_item_set_key(tiledb_ctx_t * ctx, tiledb_kv_item_t * kv_item, const void * key, tiledb_datatype_t key_type, uint64_t key_size)

Set the key in the key-value item.

Example:

tiledb_kv_item_set_key(ctx, kv_item, "my_key", TILEDB_CHAR, strlen(my_key));

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_item: The key-value item.
  • key: The key to be set.
  • key_type: The key type to be set.
  • key_size: The key size (in bytes).

int tiledb_kv_item_set_value(tiledb_ctx_t * ctx, tiledb_kv_item_t * kv_item, const char * attribute, const void * value, tiledb_datatype_t value_type, uint64_t value_size)

Sets a value for a particular attribute to the key-value item. This function works for both fixed- and variable-sized attributes.

Example:

int v = 10;
tiledb_kv_item_set_value(ctx, kv_item, "attr_1", v, TILEDB_INT32, sizeof(v));

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_item: The key-value item.
  • attribute: The attribute name.
  • value: The value to be added.
  • value_type: The value type.
  • value_size: The value size in bytes.

int tiledb_kv_item_get_key(tiledb_ctx_t * ctx, tiledb_kv_item_t * kv_item, const void ** key, tiledb_datatype_t * key_type, uint64_t * key_size)

Gets the key in the key-value item.

Example:

const char* key; // A pointer will be retrieved - not a new char object
uint64_t key_size;
tiledb_datatype_t key_type;
tiledb_kv_item_get_key(ctx, kv_item, &key, &key_type, &key_size);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_item: The key-value item.
  • key: The key to be retrieved.
  • key_type: The key type to be retrieved.
  • key_size: The key size (in bytes).

int tiledb_kv_item_get_value(tiledb_ctx_t * ctx, tiledb_kv_item_t * kv_item, const char * attribute, const void ** value, tiledb_datatype_t * value_type, uint64_t * value_size)

Gets the value and value size on a given attribute from a key-value item.

Example:

const int* v; // A pointer will be retrieved - not a new int object
uint64_t v_size;
tiledb_datatype_t v_type;
tiledb_kv_item_get_value(ctx, kv_item, &v, &v_type, &v_size);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_item: The key-value item.
  • attribute: The attribute name.
  • value: The value to be retrieved.
  • value_type: The value type to be retrieved.
  • value_size: The value size to be retrieved.

Key-value Iterator

int tiledb_kv_iter_alloc(tiledb_ctx_t * ctx, tiledb_kv_t * kv, tiledb_kv_iter_t ** kv_iter)

Creates an iterator for a key-value store. This can be used only for reading. This sets the pointer to the first key-value item.

Example:

tiledb_kv_t* kv;
tiledb_kv_alloc(ctx, "my_kv", &kv);
const char* attributes[] = {"attr_1", "attr_2"};
tiledb_kv_open(ctx, kv, attributes, 2);
tiledb_kv_iter_t* kv_iter;
tiledb_kv_iter_alloc(ctx, kv, &kv_iter);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv: The kv the iterator is associated with.
  • kv_iter: The kv iterator to be created.

void tiledb_kv_iter_free(tiledb_kv_iter_t ** kv_iter)

Frees a key-value store iterator.

Example:

tiledb_kv_iter_free(&kv_iter);

Parameters
  • kv_iter: The key-value store iterator to be freed.

int tiledb_kv_iter_here(tiledb_ctx_t * ctx, tiledb_kv_iter_t * kv_iter, tiledb_kv_item_t ** kv_item)

Retrieves the key-value item currently pointed by the iterator. Note that this function creates a new key-value item.

Example:

tiledb_kv_item_t* kv_item;
tiledb_kv_iter_here(ctx, kv_iter, &kv_iter);
// Make sure to delete kv item in the end

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_iter: The key-value store iterator.
  • kv_item: The current key-value item to be retrieved.

int tiledb_kv_iter_next(tiledb_ctx_t * ctx, tiledb_kv_iter_t * kv_iter)

Moves the iterator to the next item.

Example:

tiledb_kv_iter_next(ctx, kv_iter);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_iter: The key-value store iterator.

int tiledb_kv_iter_done(tiledb_ctx_t * ctx, tiledb_kv_iter_t * kv_iter, int * done)

Checks if the iterator is done.

Example:

int done;
tiledb_kv_iter_next(ctx, kv_iter, &done);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_iter: The key-value store iterator.
  • done: Sets this to 1 if the iterator is done, and to 0 otherwise.

int tiledb_kv_iter_reset(tiledb_ctx_t * ctx, tiledb_kv_iter_t * kv_iter)

Resets a key-value store iterator.

Example:

tiledb_kv_iter_reset(ctx, kv_iter);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • kv_iter: The key-value store iterator to be reset.

Object Management

int tiledb_object_type(tiledb_ctx_t * ctx, const char * path, tiledb_object_t * type)

Returns the TileDB object type for a given resource path.

Example:

tiledb_object_t type;
tiledb_object_type(ctx, "arrays/my_array", &type);

Return
TILEDB_OK on success, TILEDB_ERR on error.
Parameters
  • ctx: The TileDB context.
  • path: The URI path to the TileDB resource.
  • type: The type to be retrieved.

int tiledb_object_remove(tiledb_ctx_t * ctx, const char * path)

Deletes a TileDB resource (group, array, key-value).

Example:

tiledb_object_remove(ctx, "arrays/my_array");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • path: The URI path to the tiledb resource.

int tiledb_object_move(tiledb_ctx_t * ctx, const char * old_path, const char * new_path)

Moves a TileDB resource (group, array, key-value).

Example:

tiledb_object_move(ctx, "arrays/my_array", "arrays/my_array_2");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • old_path: The old TileDB directory.
  • new_path: The new TileDB directory.

int tiledb_object_walk(tiledb_ctx_t * ctx, const char * path, tiledb_walk_order_t order, int(*callback)(const char *, tiledb_object_t , void *), void * data)

Walks (iterates) over the TileDB objects contained in path. The traversal is done recursively in the order defined by the user. The user provides a callback function which is applied on each of the visited TileDB objects. The iteration continues for as long the callback returns non-zero, and stops when the callback returns 0. Note that this function ignores any object (e.g., file or directory) that is not TileDB-related.

Example:

tiledb_object_walk(ctx, "arrays", TILEDB_PREORDER, NULL, NULL);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • path: The path in which the traversal will occur.
  • order: The order of the recursive traversal (e.g., pre-order or post-order.
  • callback: The callback function to be applied on every visited object. The callback should return 0 if the iteration must stop, and 1 if the iteration must continue. It takes as input the currently visited path, the type of that path (e.g., array or group), and the data provided by the user for the callback. The callback returns -1 upon error. Note that path in the callback will be an absolute path.
  • data: The data passed in the callback as the last argument.

int tiledb_object_ls(tiledb_ctx_t * ctx, const char * path, int(*callback)(const char *, tiledb_object_t , void *), void * data)

Similar to tiledb_walk, but now the function visits only the children of path (i.e., it does not recursively continue to the children directories.

Example:

tiledb_object_ls(ctx, "arrays", NULL, NULL);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • path: The path in which the traversal will occur.
  • callback: The callback function to be applied on every visited object. The callback should return 0 if the iteration must stop, and 1 if the iteration must continue. It takes as input the currently visited path, the type of that path (e.g., array or group), and the data provided by the user for the callback. The callback returns -1 upon error. Note that path in the callback will be an absolute path.
  • data: The data passed in the callback as the last argument.

VFS

int tiledb_vfs_alloc(tiledb_ctx_t * ctx, tiledb_config_t * config, tiledb_vfs_t ** vfs)

Creates a virtual filesystem object.

Example:

tiledb_vfs_t* vfs;
tiledb_vfs_alloc(ctx, config, &vfs);

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object to be created.
  • config: Configuration parameters.

void tiledb_vfs_free(tiledb_vfs_t ** vfs)

Frees a virtual filesystem object.

Example:

tiledb_vfs_free(&vfs);

Parameters
  • vfs: The virtual filesystem object to be freed.

int tiledb_vfs_get_config(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, tiledb_config_t ** config)

Retrieves the config from a VFS context.

Example:

tiledb_config_t* config;
tiledb_vfs_get_config(ctx, vfs, &config);
// Make sure to free the retrieved config

Return
TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The VFS object.
  • config: The config to be retrieved.

int tiledb_vfs_create_bucket(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri)

Creates an object-store bucket.

Example:

tiledb_vfs_create_bucket(ctx, vfs, "s3://tiledb");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the bucket to be created.

int tiledb_vfs_remove_bucket(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri)

Deletes an object-store bucket.

Example:

tiledb_vfs_delete_bucket(ctx, vfs, "s3://tiledb");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the bucket to be deleted.

int tiledb_vfs_empty_bucket(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri)

Deletes the contents of an object-store bucket.

Example:

tiledb_vfs_empty_bucket(ctx, vfs, "s3://tiledb");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the bucket to be emptied.

int tiledb_vfs_is_empty_bucket(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri, int * is_empty)

Checks if an object-store bucket is empty.

Example:

int is_empty;
tiledb_vfs_is_empty_bucket(ctx, vfs, "s3://tiledb", &empty);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the bucket.
  • is_empty: Sets it to 1 if the input bucket is empty, and 0 otherwise.

int tiledb_vfs_is_bucket(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri, int * is_bucket)

Checks if an object-store bucket exists.

Example:

int exists;
tiledb_vfs_is_bucket(ctx, vfs, "s3://tiledb", &exists);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the bucket.
  • is_bucket: Sets it to 1 if the input URI is a bucket, and 0 otherwise.

int tiledb_vfs_create_dir(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri)

Creates a directory.

  • On S3, this is a noop.
  • On all other backends, if the directory exists, the function just succeeds without doing anything.

Example:

tiledb_vfs_create_dir(ctx, vfs, "hdfs:///temp/my_dir");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the directory to be created.

int tiledb_vfs_is_dir(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri, int * is_dir)

Checks if a directory exists.

Example:

int exists;
tiledb_vfs_is_dir(ctx, vfs, "hdfs:///temp/my_dir", &exists);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Note
For S3, this function will return true if there is an object with prefix uri/ (TileDB will append / internally to uri only if it does not exist), and false othewise.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the directory.
  • is_dir: Sets it to 1 if the directory exists and 0 otherwise.

int tiledb_vfs_remove_dir(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri)

Removes a directory (recursively).

Example:

tiledb_vfs_remove_dir(ctx, vfs, "hdfs:///temp/my_dir");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The uri of the directory to be removed

int tiledb_vfs_is_file(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri, int * is_file)

Checks if a file exists.

Example:

int exists;
tiledb_vfs_is_file(ctx, vfs, "hdfs:///temp/my_file", &is_file);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the file.
  • is_file: Sets it to 1 if the file exists and 0 otherwise.

int tiledb_vfs_remove_file(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri)

Deletes a file.

Example:

tiledb_vfs_remove_file(ctx, vfs, "hdfs:///temp/my_file");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the file.

int tiledb_vfs_file_size(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri, uint64_t * size)

Retrieves the size of a file.

Example:

uint64_t file_size;
tiledb_vfs_file_size(ctx, vfs, "hdfs:///temp/my_file", &file_size);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the file.
  • size: The file size to be retrieved.

int tiledb_vfs_move_dir(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * old_uri, const char * new_uri)

Renames a directory.

Example:

tiledb_vfs_move_dir(ctx, vfs, "hdfs:///temp/my_dir", "hdfs::///new_dir");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • old_uri: The old URI.
  • new_uri: The new URI.

int tiledb_vfs_move_file(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * old_uri, const char * new_uri)

Renames a file. If the destination file exists, it will be overwritten.

Example:

tiledb_vfs_move_file(
ctx, vfs, "hdfs:///temp/my_file", "hdfs::///new_file");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • old_uri: The old URI.
  • new_uri: The new URI.

int tiledb_vfs_open(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri, tiledb_vfs_mode_t mode, tiledb_vfs_fh_t ** fh)

Prepares a file for reading/writing.

Example:

tiledb_vfs_fh_t* fh;
tiledb_vfs_open(ctx, vfs, "some_file", TILEDB_VFS_READ, &fh);
// Make sure to close and delete the created file handle

Return
TILEDB_OK for success and TILEDB_ERR or TILEDB_OOM for error.
Note
If the file is closed after being opened, without having written any data to it, the file will not be created. If you wish to create an empty file, use tiledb_vfs_touch instead.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the file.
  • mode: The mode in which the file is opened:
    • TILEDB_VFS_READ: The file is opened for reading. An error is returned if the file does not exist.
    • TILEDB_VFS_WRITE: The file is opened for writing. If the file exists, it will be overwritten.
    • TILEDB_VFS_APPEND: The file is opened for writing. If the file exists, the write will start from the end of the file. Note that S3 does not support this operation and, thus, an error will be thrown in that case.
  • fh: The file handle that is created. This will be used in tiledb_vfs_read, tiledb_vfs_write and tiledb_vfs_sync.

int tiledb_vfs_close(tiledb_ctx_t * ctx, tiledb_vfs_fh_t * fh)

Closes a file. This is flushes the buffered data into the file when the file was opened in write (or append) mode. It is particularly important to be called after S3 writes, as otherwise the writes will not take effect.

Example:

tiledb_vfs_close(ctx, vfs, fh);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • fh: The file handle.

int tiledb_vfs_read(tiledb_ctx_t * ctx, tiledb_vfs_fh_t * fh, uint64_t offset, void * buffer, uint64_t nbytes)

Reads from a file.

Example:

char buffer[10000];
tiledb_vfs_read(ctx, fh, 100, buffer, 10000);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • fh: The URI file handle.
  • offset: The offset in the file where the read begins.
  • buffer: The buffer to read into.
  • nbytes: Number of bytes to read.

int tiledb_vfs_write(tiledb_ctx_t * ctx, tiledb_vfs_fh_t * fh, const void * buffer, uint64_t nbytes)

Writes the contents of a buffer into a file. Note that this function only appends data at the end of the file. If the file does not exist, it will be created.

Example:

const char* msg = "This will be written to the file";
tiledb_vfs_write(ctx, fh, buffer, strlen(msg));

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • fh: The URI file handle.
  • buffer: The buffer to write from.
  • nbytes: Number of bytes to write.

int tiledb_vfs_sync(tiledb_ctx_t * ctx, tiledb_vfs_fh_t * fh)

Syncs (flushes) a file.

Example:

tiledb_vfs_sync(ctx, fh);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Note
This has no effect for S3.
Parameters
  • ctx: The TileDB context.
  • fh: The URI file handle.

void tiledb_vfs_fh_free(tiledb_vfs_fh_t ** fh)

Frees a file handle.

Example:

tiledb_vfs_fh_free(&fh);

Parameters
  • fh: The URI file handle.

int tiledb_vfs_fh_is_closed(tiledb_ctx_t * ctx, tiledb_vfs_fh_t * fh, int * is_closed)

Checks if a file handle is closed.

Example:

int is_closed;
tiledb_vfs_fh_is_closed(ctx, fh, &is_closed);

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • fh: The URI file handle.
  • is_closed: Set to 1 if the file handle is closed, and 0 otherwise.

int tiledb_vfs_touch(tiledb_ctx_t * ctx, tiledb_vfs_t * vfs, const char * uri)

Touches a file, i.e., creates a new empty file.

Example:

tiledb_vfs_touch(ctx, vfs, "my_empty_file");

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • ctx: The TileDB context.
  • vfs: The virtual filesystem object.
  • uri: The URI of the file to be created.

URI

int tiledb_uri_to_path(tiledb_ctx_t * ctx, const char * uri, char * path_out, unsigned * path_length)

Converts the given file URI to a null-terminated platform-native file path.

Example:

char path[TILEDB_MAX_PATH];
unsigned length;
tiledb_uri_to_path(ctx, "file:///my_array", path, &length);
// This will set "my_array" to `path`

Return
TILEDB_OK for success and TILEDB_ERR for error.
Note
The path_out buffer must be allocated according to the platform’s maximum path length (e.g. `TILEDB_MAX_PATH), which includes space for the terminating null character.
Parameters
  • ctx: The TileDB context.
  • uri: The URI to be converted.
  • path_out: The buffer where the converted path string is stored.
  • path_length: The length of the path buffer. On return, this is set to the length of the converted path string, or 0 on error.

Version

void tiledb_version(int * major, int * minor, int * rev)

Retrieves the version of the TileDB library currently being used.

Parameters
  • major: Will store the major version number.
  • minor: Will store the minor version number.
  • rev: Will store the revision (patch) number.

Stats

int tiledb_stats_enable()

Enable internal statistics gathering.

Return
TILEDB_OK for success and TILEDB_ERR for error.

int tiledb_stats_disable()

Disable internal statistics gathering.

Return
TILEDB_OK for success and TILEDB_ERR for error.

int tiledb_stats_reset()

Reset all internal statistics counters to 0.

Return
TILEDB_OK for success and TILEDB_ERR for error.

int tiledb_stats_dump(FILE * out)

Dump all internal statistics counters to to some output (e.g., file or stdout).

Return
TILEDB_OK for success and TILEDB_ERR for error.
Parameters
  • out: The output.