TileDB C API Reference¶

Types¶

typedef struct tiledb_array_handle_t tiledb_array_t¶: C API carrier for a TileDB array

typedef struct tiledb_buffer_handle_t tiledb_buffer_t¶: A buffer object.

typedef struct tiledb_buffer_list_handle_t tiledb_buffer_list_t¶: A buffer object.

typedef struct tiledb_config_handle_t tiledb_config_t¶: C API carrier for a TileDB configuration

typedef struct tiledb_config_iter_handle_t tiledb_config_iter_t¶: C API carrier for an iterator over a TileDB configuration

typedef struct tiledb_ctx_handle_t tiledb_ctx_t¶: C API carrier for a TileDB context

typedef struct tiledb_error_handle_t tiledb_error_t¶: C API carrier for a TileDB error

typedef struct tiledb_attribute_handle_t tiledb_attribute_t¶: A TileDB attribute

typedef struct tiledb_array_schema_handle_t tiledb_array_schema_t¶: C API carrier for a TileDB array schema

typedef struct tiledb_dimension_handle_t tiledb_dimension_t¶: A TileDB dimension.

typedef struct tiledb_domain_handle_t tiledb_domain_t¶: A TileDB domain.

typedef struct tiledb_query_t tiledb_query_t¶

typedef struct tiledb_filter_handle_t tiledb_filter_t¶: C API carrier for a TileDB filter

typedef struct tiledb_filter_list_handle_t tiledb_filter_list_t¶: C API carrier for a TileDB filter

typedef struct tiledb_fragment_info_handle_t tiledb_fragment_info_t¶: C API carrier for a TileDB fragment info object.

typedef struct tiledb_vfs_handle_t tiledb_vfs_t¶: C API carrier for a TileDB virtual filesystem

typedef struct tiledb_vfs_fh_handle_t tiledb_vfs_fh_t¶: C API carrier for a TileDB virtual filesystem

Return Codes¶

TILEDB_OK¶: Success.

TILEDB_ERR¶: An error state, not otherwise specified.

TILEDB_OOM¶: Out of memory. The implementation threw std::bad_alloc somewhere.

Constants¶

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).

TILEDB_TIMESTAMPS¶: A special name indicating the timestamps attribute.

uint32_t tiledb_var_num(void)¶: Returns a special value indicating a variable number of elements.

uint32_t tiledb_max_path(void)¶: Returns the maximum path length on the current platform.

uint64_t tiledb_datatype_size(tiledb_datatype_t type)¶: Returns the input datatype size for a given type. Returns zero if the type is not valid.

uint64_t tiledb_offset_size(void)¶: Returns the size (in bytes) of an offset (used in variable-sized attributes).

const char *tiledb_timestamps(void)¶: Returns a special name indicating the timestamps attribute.

Enumerations¶

enum tiledb_object_t¶

TileDB object type.

Values:

enum tiledb_query_type_t¶

TileDB query type.

Values:

enum tiledb_query_status_t¶

Query status.

Values:

enum tiledb_filesystem_t¶

Filesystem type.

Values:

enum tiledb_datatype_t¶

TileDB datatype.

Values:

enum tiledb_array_type_t¶

Array type.

Values:

enum tiledb_layout_t¶

Tile or cell layout.

Values:

enum tiledb_filter_type_t¶

Filter type.

Values:

enum tiledb_filter_option_t¶

Filter option.

Values:

enum tiledb_walk_order_t¶

Walk traversal order.

Values:

enum tiledb_vfs_mode_t¶

VFS mode.

Values:

enum tiledb_mime_type_t¶

MIME Type.

Values:

enum tiledb_encryption_type_t¶

Encryption type.

Values:

Enumeration String Conversion¶

capi_return_t tiledb_query_type_to_str(tiledb_query_type_t query_type, const char **str)¶

Returns a string representation of the given query type.

Parameters:

query_type – Query type
str – Set to point to a constant string representation of the query type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_query_type_from_str(const char *str, tiledb_query_type_t *query_type)¶

Parses a query type from the given string.

Parameters:

str – String representation to parse
query_type – Set to the parsed query type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_object_type_to_str(tiledb_object_t object_type, const char **str)¶

Returns a string representation of the given object type.

Parameters:

object_type – Object type
str – Set to point to a constant string representation of the object type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_object_type_from_str(const char *str, tiledb_object_t *object_type)¶

Parses a object type from the given string.

Parameters:

str – String representation to parse
object_type – Set to the parsed object type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_filesystem_to_str(tiledb_filesystem_t filesystem, const char **str)¶

Returns a string representation of the given filesystem.

Parameters:

filesystem – Filesystem
str – Set to point to a constant string representation of the filesystem

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_filesystem_from_str(const char *str, tiledb_filesystem_t *filesystem)¶

Parses a filesystem from the given string.

Parameters:

str – String representation to parse
filesystem – Set to the parsed filesystem

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_datatype_to_str(tiledb_datatype_t datatype, const char **str)¶

Returns a string representation of the given datatype.

Parameters:

datatype – Datatype
str – Set to point to a constant string representation of the datatype

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_datatype_from_str(const char *str, tiledb_datatype_t *datatype)¶

Parses a datatype from the given string.

Parameters:

str – String representation to parse
datatype – Set to the parsed datatype

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_type_to_str(tiledb_array_type_t array_type, const char **str)¶

Returns a string representation of the given array type.

Parameters:

array_type – [in] Array type
str – [out] A constant string representation of the array type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_type_from_str(const char *str, tiledb_array_type_t *array_type)¶

Parses an array type from the given string.

Parameters:

str – [in] String representation to parse
array_type – [out] The parsed array type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_layout_to_str(tiledb_layout_t layout, const char **str)¶

Returns a string representation of the given layout.

Parameters:

layout – [in] Layout
str – [out] A constant string representation of the layout

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_layout_from_str(const char *str, tiledb_layout_t *layout)¶

Parses a layout from the given string.

Parameters:

str – [in] String representation to parse
layout – [out] The parsed layout

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_filter_type_to_str(tiledb_filter_type_t filter_type, const char **str)¶

Returns a string representation of the given filter type.

Parameters:

filter_type – [in] Filter type
str – [out] Set to point to a constant string representation of the filter type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_filter_type_from_str(const char *str, tiledb_filter_type_t *filter_type)¶

Parses a filter type from the given string.

Parameters:

str – [in] String representation to parse
filter_type – [out] Set to the parsed filter type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_filter_option_to_str(tiledb_filter_option_t filter_option, const char **str)¶

Returns a string representation of the given filter option.

Parameters:

filter_option – [in] Filter option
str – [out] Set to point to a constant string representation of the filter option

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_filter_option_from_str(const char *str, tiledb_filter_option_t *filter_option)¶

Parses a filter option from the given string.

Parameters:

str – [in] String representation to parse
filter_option – [out] Set to the parsed filter option

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_encryption_type_to_str(tiledb_encryption_type_t encryption_type, const char **str)¶

Returns a string representation of the given encryption type.

Parameters:

encryption_type – [in] Encryption type
str – [out] A constant string representation of the encryption type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_encryption_type_from_str(const char *str, tiledb_encryption_type_t *encryption_type)¶

Parses a encryption type from the given string.

Parameters:

str – [in] String representation to parse
encryption_type – [out] The parsed encryption type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_status_to_str(tiledb_query_status_t query_status, const char **str)¶

Returns a string representation of the given query status.

Parameters:

query_status – Query status
str – Set to point to a constant string representation of the query status

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_status_from_str(const char *str, tiledb_query_status_t *query_status)¶

Parses a query status from the given string.

Parameters:

str – String representation to parse
query_status – Set to the parsed query status

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_walk_order_to_str(tiledb_walk_order_t walk_order, const char **str)¶

Returns a string representation of the given walk order.

Parameters:

walk_order – Walk order
str – Set to point to a constant string representation of the walk order

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_walk_order_from_str(const char *str, tiledb_walk_order_t *walk_order)¶

Parses a walk order from the given string.

Parameters:

str – String representation to parse
walk_order – Set to the parsed walk order

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_vfs_mode_to_str(tiledb_vfs_mode_t vfs_mode, const char **str)¶

Returns a string representation of the given VFS mode.

Parameters:

vfs_mode – [in] VFS mode
str – [out] Set to point to a constant string representation of the VFS mode

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_vfs_mode_from_str(const char *str, tiledb_vfs_mode_t *vfs_mode)¶

Parses a VFS mode from the given string.

Parameters:

str – [in] String representation to parse
vfs_mode – [out] Set to the parsed VFS mode

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Context¶

capi_return_t 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);

Parameters:

config – The configuration parameters (NULL means default).
ctx – The TileDB context to be created.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

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.

capi_return_t tiledb_ctx_get_stats(tiledb_ctx_t *ctx, char **stats_json)¶

Retrieves the stats from a TileDB context.

Example:

char* stats_json;
tiledb_ctx_get_stats(ctx, &stats_json);
// Use the string
tiledb_stats_free_str(&stats_json);

Parameters:

ctx – The TileDB context.
stats_json – The output json. The caller takes ownership of the c-string and must free it using tiledb_stats_free_str().

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

capi_return_t tiledb_ctx_get_config(tiledb_ctx_t *ctx, tiledb_config_t **config)¶

Retrieves a copy of the config from a TileDB context. Modifying this config will not affect the initialized context configuration.

Example:

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

Parameters:

ctx – The TileDB context.
config – The config to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

capi_return_t 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

Parameters:

ctx – The TileDB context.
err – The last error, or NULL if no error has been raised.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

capi_return_t tiledb_ctx_is_supported_fs(tiledb_ctx_t *ctx, tiledb_filesystem_t fs, int32_t *is_supported)¶

Checks if a given storage filesystem backend is supported.

Example:

int32_t is_supported;
tiledb_ctx_is_supported_fs(ctx, TILEDB_S3, &is_supported);

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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_ctx_cancel_tasks(tiledb_ctx_t *ctx)¶

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

Parameters:: ctx – The TileDB context.
Returns:: TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_ctx_set_tag(tiledb_ctx_t *ctx, const char *key, const char *value)¶

Sets a string key-value “tag” on the given context.

Example:

tiledb_ctx_set_tag(ctx, "tag key", "tag value");

Parameters:

ctx – The TileDB context.
key – The tag key
value – The tag value.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Config¶

capi_return_t 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);

Parameters:

config – The config to be created.
error – Error object returned upon error (NULL if there is no error).

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for 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.

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

Sets a config parameter.

Parameters

sm.allow_separate_attribute_writes Experimental Allow separate attribute write queries.Default: false
sm.allow_updates_experimental Experimental Allow update queries. Experimental for testing purposes, do not use.Default: false
sm.dedup_coords If true, cells with duplicate coordinates will be removed during sparse fragment writes. Note that ties during deduplication are broken arbitrarily. Also note that this check means that it will take longer to perform the write operation. 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 fragmnet writes. If false and there are duplicates, the duplicates will be written without errors. Note that this check is much ligher weight than the coordinate deduplication check enabled by sm.dedup_coords. Default: true
sm.check_coord_oob If true, an error will be thrown if there are cells with coordinates lying outside the domain during sparse fragment writes. Default: true
sm.read_range_oob If error, this will check ranges for read with out-of-bounds on the dimension domain’s. If warn, the ranges will be capped at the dimension’s domain and a warning logged. Default: warn
sm.check_global_order Checks if the coordinates obey the global array order. Applicable only to sparse writes in global order. Default: true
sm.merge_overlapping_ranges_experimental If true, merge overlapping Subarray ranges. Else, overlapping ranges will not be merged and multiplicities will be returned. Experimental for testing purposes, do not use.Default: true
sm.enable_signal_handlers Determines whether or not TileDB will install signal handlers. Default: true
sm.compute_concurrency_level Upper-bound on number of threads to allocate for compute-bound tasks. Default*: # cores
Upper-bound on number of threads to allocate for IO-bound tasks. **Default*: # cores
The vacuuming mode, one of (remove only consolidated commit files), (remove only consolidated fragments), (remove only consolidated fragment metadata), (remove only consolidated array metadata files), or (remove only consolidate group metadata only). **Default: fragments
sm.consolidation.mode The consolidation mode, one of commits (consolidate all commit files), fragments (consolidate all fragments), fragment_meta (consolidate only fragment metadata footers to a single file), array_meta (consolidate array metadata only), or group_meta (consolidate group metadata only). Default: “fragments”
sm.consolidation.amplification The factor by which the size of the dense fragment resulting from consolidating a set of fragments (containing at least one dense fragment) can be amplified. This is important when the union of the non-empty domains of the fragments to be consolidated have a lot of empty cells, which the consolidated fragment will have to fill with the special fill value (since the resulting fragment is dense). Default: 1.0
sm.consolidation.buffer_size Deprecated The size (in bytes) of the attribute buffers used during consolidation. Default: 50,000,000
sm.consolidation.max_fragment_size Experimental The size (in bytes) of the maximum on-disk fragment size that will be created by consolidation. When it is reached, consolidation will continue the operation in a new fragment. The result will be a multiple fragments, but with seperate MBRs.
sm.consolidation.steps The number of consolidation steps to be performed when executing the consolidation algorithm.Default: UINT32_MAX
sm.consolidation.purge_deleted_cells Experimental Purge deleted cells from the consolidated fragment or not.Default: false
sm.consolidation.step_min_frags The minimum number of fragments to consolidate in a single step.Default: UINT32_MAX
sm.consolidation.step_max_frags The maximum number of fragments to consolidate in a single step.Default: UINT32_MAX
sm.consolidation.step_size_ratio The size ratio that two (“adjacent”) fragments must satisfy to be considered for consolidation in a single step.Default: 0.0
sm.consolidation.timestamp_start Experimental When set, an array will be consolidated between this value and sm.consolidation.timestamp_end
(inclusive).

Only for
fragments and array_meta consolidation mode. Default: 0
sm.consolidation.timestamp_end Experimental When set, an array will be consolidated between sm.consolidation.timestamp_start
and this value (inclusive).

Only for
fragments and array_meta consolidation mode. Default: UINT64_MAX
sm.encryption_key The key for encrypted arrays. Default: “”
sm.encryption_type The type of encryption used for encrypted arrays. Default: “NO_ENCRYPTION”
sm.enumerations_max_size
Maximum in memory size for an enumeration. If the enumeration is

var sized, the size will include the data and the offsets.
Default: 10MB
sm.enumerations_max_total_size
Maximum in memory size for all enumerations. If the enumeration

is var sized, the size will include the data and the offsets.
Default: 50MB
sm.max_tile_overlap_size
Maximum size for the tile overlap structure which holds

information about which tiles are covered by ranges. Only used
in dense reads and legacy reads. Default: 300MB
sm.memory_budget The memory budget for tiles of fixed-sized attributes (or offsets for var-sized attributes) to be fetched during reads.Default: 5GB
sm.memory_budget_var The memory budget for tiles of var-sized attributes to be fetched during reads.Default: 10GB
sm.var_offsets.bitsize The size of offsets in bits to be used for offset buffers of var-sized attributesDefault: 64
sm.var_offsets.extra_element Add an extra element to the end of the offsets buffer of var-sized attributes which will point to the end of the values buffer.Default: false
sm.var_offsets.mode The offsets format (bytes or elements) to be used for var-sized attributes.Default: bytes
sm.query.dense.reader Which reader to use for dense queries. “refactored” or “legacy”.Default: refactored
sm.query.dense.qc_coords_mode
Dense configuration that allows to only return the coordinates of

the cells that match a query condition without any attribute data.
Default: “false”
sm.query.sparse_global_order.reader Which reader to use for sparse global order queries. “refactored” or “legacy”.Default: refactored
sm.query.sparse_global_order.preprocess_tile_merge Experimental for testing purposes, do not use. Performance configuration for sparse global order read queries. If nonzero, prior to loading the first tiles, the reader will run a preprocessing step to arrange tiles from all fragments in a single globally ordered list. This is expected to improve performance when there are many fragments or when the distribution in space of the tiles amongst the fragments is skewed. The value of the parameter specifies the amount of work per parallel task. Default: “32768”
sm.query.sparse_unordered_with_dups.reader Which reader to use for sparse unordered with dups queries. “refactored” or “legacy”.Default: refactored
sm.skip_checksum_validation Skip checksum validation on reads for the md5 and sha256 filters. Default: “false”
sm.mem.malloc_trim Should malloc_trim be called on context and query destruction? This might reduce residual memory usage. Default: true
sm.mem.tile_upper_memory_limit Experimental This is the upper memory limit that is used when loading tiles. For now it is only used in the dense reader but will be eventually used by all readers. The readers using this value will use it as a way to limit the amount of tile data that is brought into memory at once so that we don’t incur performance penalties during memory movement operations. It is a soft limit that we might go over if a single tile doesn’t fit into memory, we will allow to load that tile if it still fits within sm.mem.total_budget. Default: 1GB
sm.mem.total_budget Memory budget for readers and writers. Default: 10GB
sm.mem.consolidation.buffers_weight Weight used to split sm.mem.total_budget and assign to the consolidation buffers. The budget is split across 3 values, sm.mem.consolidation.buffers_weight, sm.mem.consolidation.reader_weight and sm.mem.consolidation.writer_weight. Default: 1
sm.mem.consolidation.reader_weight Weight used to split sm.mem.total_budget and assign to the reader query. The budget is split across 3 values, sm.mem.consolidation.buffers_weight, sm.mem.consolidation.reader_weight and sm.mem.consolidation.writer_weight. Default: 3
sm.mem.consolidation.writer_weight Weight used to split sm.mem.total_budget and assign to the writer query. The budget is split across 3 values, sm.mem.consolidation.buffers_weight, sm.mem.consolidation.reader_weight and sm.mem.consolidation.writer_weight. Default: 2
sm.mem.reader.sparse_global_order.ratio_coords Ratio of the budget allocated for coordinates in the sparse global order reader. Default: 0.5
sm.mem.reader.sparse_global_order.ratio_tile_ranges Ratio of the budget allocated for tile ranges in the sparse global order reader. Default: 0.1
sm.mem.reader.sparse_global_order.ratio_array_data Ratio of the budget allocated for array data in the sparse global order reader. Default: 0.1
sm.mem.reader.sparse_unordered_with_dups.ratio_coords Ratio of the budget allocated for coordinates in the sparse unordered with duplicates reader. Default: 0.5
sm.mem.reader.sparse_unordered_with_dups.ratio_tile_ranges Ratio of the budget allocated for tile ranges in the sparse unordered with duplicates reader. Default: 0.1
sm.mem.reader.sparse_unordered_with_dups.ratio_array_data Ratio of the budget allocated for array data in the sparse unordered with duplicates reader. Default: 0.1 The maximum byte size to read-ahead from the backend. Default: 102400
sm.group.timestamp_start The start timestamp used for opening the group. Default: 0
sm.group.timestamp_end
The end timestamp used for opening the group.

Also used for the write timestamp if set.
Default: UINT64_MAX
sm.partial_tile_offsets_loading Experimental If true tile offsets can be partially loaded and unloaded by the readers. Default: false
sm.fragment_info.preload_mbrs If true MBRs will be loaded at the same time as the rest of fragment info, otherwise they will be loaded lazily when some info related to MBRs is requested by the user. Default: false
sm.partial_tile_offset_loading Experimental If true tile offsets can be partially loaded and unloaded by the readers. Default: false
ssl.ca_file
The path to CA certificate to use when validating server certificates. Applies to all SSL/TLS connections.

This option might be ignored on platforms that have native certificate stores like Windows.
Default: “”
ssl.ca_path
The path to a directory with CA certificates to use when validating server certificates. Applies to all SSL/TLS connections.

This option might be ignored on platforms that have native certificate stores like Windows.
Default: “”
ssl.verify
Whether to verify the server’s certificate. Applies to all SSL/TLS connections.

Disabling verification is insecure and should only used for testing purposes.
Default: true
vfs.read_ahead_cache_size The the total maximum size of the read-ahead cache, which is an LRU. Default: 10485760
vfs.log_operations Enables logging all VFS operations in trace mode. Default: false
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.max_batch_size The maximum number of bytes in a VFS read operationDefault: 100MB
vfs.min_batch_size The minimum number of bytes in a VFS read operationDefault: 20MB
vfs.min_batch_gap The minimum number of bytes between two VFS read batches.Default: 500KB
vfs.read_logging_mode Log read operations at varying levels of verbosity.Default: “” Possible values:
- An empty string disables read logging.
- Log each fragment read.
- Log each individual fragment file read.
- Log all files read.
- Log all files with offset and length parameters.
- Log all files with offset and length parameters on every read, not just the first read. On large arrays the read cache may get large so this trades of RAM usage vs increased log verbosity.
vfs.file.posix_file_permissions Permissions to use for posix file system with file creation.Default: 644
vfs.file.posix_directory_permissions Permissions to use for posix file system with directory creation.Default: 755
vfs.azure.storage_account_name Set the name of the Azure Storage account to use. Default: “”
vfs.azure.storage_account_key Set the Shared Key to authenticate to Azure Storage. Default: “”
vfs.azure.storage_sas_token Set the Azure Storage SAS (shared access signature) token to use. If this option is set along with vfs.azure.blob_endpoint, the latter must not include a SAS token. Default: “”
vfs.azure.blob_endpoint
Set the default Azure Storage Blob endpoint.

If not specified, it will take a value of
<account-name>.blob.core.windows.net, where <account-name> is the value of the vfs.azure.storage_account_name option. This means that at least one of these two options must be set (or both if shared key authentication is used). Default: “”
vfs.azure.block_list_block_size The block size (in bytes) used in Azure blob block list writes. Any uint64_t value is acceptable. Note: vfs.azure.block_list_block_size vfs.azure.max_parallel_ops bytes will be buffered before issuing block uploads in parallel. Default: “5242880”
vfs.azure.max_parallel_ops The maximum number of Azure backend parallel operations. Default: sm.io_concurrency_level
vfs.azure.use_block_list_upload Determines if the Azure backend can use chunked block uploads. Default: “true”
vfs.azure.max_retries The maximum number of times to retry an Azure network request. Default: 5
vfs.azure.retry_delay_ms The minimum permissible delay between Azure netwwork request retry attempts, in milliseconds. Default: 800
vfs.azure.max_retry_delay_ms The maximum permissible delay between Azure netwwork request retry attempts, in milliseconds. Default: 60000
vfs.gcs.endpoint The GCS endpoint. Default: “”
vfs.gcs.project_id Set the GCS project ID to create new buckets to. Not required unless you are going to use the VFS to create buckets. Default: “”
vfs.gcs.service_account_key Experimental Set the JSON string with GCS service account key. Takes precedence over vfs.gcs.workload_identity_configuration if both are specified. If neither is specified, Application Default Credentials will be used. Default: “”
vfs.gcs.workload_identity_configuration Experimental Set the JSON string with Workload Identity Federation configuration. vfs.gcs.service_account_key takes precedence over this if both are specified. If neither is specified, Application Default Credentials will be used. Default: “”
vfs.gcs.impersonate_service_account Experimental Set the GCS service account to impersonate. A chain of impersonated accounts can be formed by specifying many service accounts, separated by a comma. Default: “”
vfs.gcs.multi_part_size The part size (in bytes) used in GCS multi part writes. Any uint64_t value is acceptable. Note: vfs.gcs.multi_part_size * vfs.gcs.max_parallel_ops bytes will be buffered before issuing part uploads in parallel. Default: “5242880”
vfs.gcs.max_parallel_ops The maximum number of GCS backend parallel operations. Default: sm.io_concurrency_level
vfs.gcs.use_multi_part_upload Determines if the GCS backend can use chunked part uploads. Default: “true”
vfs.gcs.request_timeout_ms The maximum amount of time to retry network requests to GCS. Default: “3000”
vfs.gcs.max_direct_upload_size The maximum size in bytes of a direct upload to GCS. Ignored if vfs.gcs.use_multi_part_upload is set to true. Default: “10737418240”
vfs.s3.region
The S3 region, if S3 is enabled.

If empty, the region will be determined by the AWS SDK using sources such as environment variables, profile configuration, or instance metadata.
Default: “”
vfs.s3.aws_access_key_id Set the AWS_ACCESS_KEY_ID Default: “”
vfs.s3.aws_secret_access_key Set the AWS_SECRET_ACCESS_KEY Default: “”
vfs.s3.aws_session_token Set the AWS_SESSION_TOKEN Default: “”
vfs.s3.aws_role_arn Determines the role that we want to assume. Set the AWS_ROLE_ARN Default: “”
vfs.s3.aws_external_id Third party access ID to your resources when assuming a role. Set the AWS_EXTERNAL_ID Default: “”
vfs.s3.aws_load_frequency Session time limit when assuming a role. Set the AWS_LOAD_FREQUENCY Default: “”
vfs.s3.aws_session_name (Optional) session name when assuming a role. Can be used for tracing and bookkeeping. Set the AWS_SESSION_NAME Default: “”
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.skip_init Skip Aws::InitAPI for the S3 layer (true or false) Default: false
vfs.s3.use_multipart_upload The S3 use of multi-part upload requests (true or false), if S3 is enabled. Default: true
vfs.s3.max_parallel_ops The maximum number of S3 backend parallel operations. Default: sm.io_concurrency_level
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.ca_file Path to SSL/TLS certificate file to be used by cURL for for S3 HTTPS encryption. Follows cURL conventions: https://curl.haxx.se/docs/manpage.html Default: “”
vfs.s3.ca_path Path to SSL/TLS certificate directory to be used by cURL for S3 HTTPS encryption. Follows cURL conventions: https://curl.haxx.se/docs/manpage.html Default: “”
vfs.s3.connect_timeout_ms The connection timeout in ms. Any long value is acceptable. Default: 10800
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 backoff when connecting to S3. Any long value is acceptable. Default: 25
vfs.s3.custom_headers.* (Optional) Prefix for custom headers on s3 requests. For each custom header, use “vfs.s3.custom_headers.header_key” = “header_value” Optional. No Default
vfs.s3.logging_level The AWS SDK logging level. This is a process-global setting. The configuration of the most recently constructed context will set process state. Log files are written to the process working directory. Default: “Off”
vfs.s3.request_timeout_ms The request timeout in ms. Any long value is acceptable. Default: 3000
vfs.s3.requester_pays The requester pays for the S3 access charges. Default: false
vfs.s3.proxy_host The S3 proxy host. Default: “”
vfs.s3.proxy_port The S3 proxy port. Default: 0
vfs.s3.proxy_scheme The S3 proxy scheme. Default: “http”
vfs.s3.proxy_username The S3 proxy username. Note: this parameter is not serialized by tiledb_config_save_to_file. Default: “”
vfs.s3.proxy_password The S3 proxy password. Note: this parameter is not serialized by tiledb_config_save_to_file. Default: “”
vfs.s3.verify_ssl Enable HTTPS certificate verification. Default: true””
vfs.s3.no_sign_request Make unauthenticated requests to s3. Default: false
vfs.s3.sse The server-side encryption algorithm to use. Supported non-empty values are “aes256” and “kms” (AWS key management service). Default: “”
vfs.s3.sse_kms_key_id The server-side encryption key to use if vfs.s3.sse == “kms” (AWS key management service). Default: “”
vfs.s3.storage_class The storage class to use for the newly uploaded S3 objects. The set of accepted values is found in the Aws::S3::Model::StorageClass enumeration. “NOT_SET” “STANDARD” “REDUCED_REDUNDANCY” “STANDARD_IA” “ONEZONE_IA” “INTELLIGENT_TIERING” “GLACIER” “DEEP_ARCHIVE” “OUTPOSTS” “GLACIER_IR” “SNOW” “EXPRESS_ONEZONE” Default: “NOT_SET”
vfs.s3.bucket_canned_acl Names of values found in Aws::S3::Model::BucketCannedACL enumeration. “NOT_SET” “private_” “public_read” “public_read_write” “authenticated_read” Default: “NOT_SET”
vfs.s3.object_canned_acl Names of values found in Aws::S3::Model::ObjectCannedACL enumeration. (The first 5 are the same as for “vfs.s3.bucket_canned_acl”.) “NOT_SET” “private_” “public_read” “public_read_write” “authenticated_read” (The following three items are found only in Aws::S3::Model::ObjectCannedACL.) “aws_exec_read” “owner_read” “bucket_owner_full_control” Default: “NOT_SET”
vfs.s3.config_source Force S3 SDK to only load config options from a set source. The supported options are auto (TileDB config options are considered first, then SDK-defined precedence: env vars, config files, ec2 metadata), config_files (forces SDK to only consider options found in aws config files), sts_profile_with_web_identity (force SDK to consider assume roles/sts from config files with support for web tokens, commonly used by EKS/ECS). Default: auto
vfs.s3.install_sigpipe_handler When set to true, the S3 SDK uses a handler that ignores SIGPIPE signals. Default: “true”
config.env_var_prefix Prefix of environmental variables for reading configuration parameters. Default: “TILEDB_”
config.logging_level The logging level configured, possible values: “0”: fatal, “1”: error, “2”: warn, “3”: info “4”: debug, “5”: trace Default: “1” if —enable-verbose bootstrap flag is provided, “0” otherwise
config.logging_format The logging format configured (DEFAULT or JSON) Default: “DEFAULT”
rest.server_address URL for REST server to use for remote arrays. Default: “https://api.tiledb.com”
rest.server_serialization_format Serialization format to use for remote array requests (CAPNP or JSON). Default: “CAPNP”
rest.username Username for login to REST server. Default: “”
rest.password Password for login to REST server. Default: “”
rest.token Authentication token for REST server (used instead of username/password). Default: “”
rest.resubmit_incomplete If true, incomplete queries received from server are automatically resubmitted before returning to user control. Default: “true”
rest.ignore_ssl_validation Have curl ignore ssl peer and host validation for REST server. Default: false
rest.creation_access_credentials_name The name of the registered access key to use for creation of the REST server. Default: no default set
rest.retry_http_codes CSV list of http status codes to automatically retry a REST request for Default: “503”
rest.retry_count Number of times to retry failed REST requests Default: 25
rest.retry_initial_delay_ms Initial delay in milliseconds to wait until retrying a REST request Default: 500
rest.retry_delay_factor The delay factor to exponentially wait until further retries of a failed REST request Default: 1.25
rest.curl.retry_errors If true any curl requests that returned an error will be retried Default: true
rest.curl.verbose
Set curl to run in verbose mode for REST requests

curl will print to stdout with this option
Default: false
rest.curl.tcp_keepalive Set curl to use TCP keepalive for REST requests Default: true
rest.load_metadata_on_array_open If true, array metadata will be loaded and sent to server together with the open array Default: true
rest.load_non_empty_domain_on_array_open If true, array non empty domain will be loaded and sent to server together with the open array Default: true
rest.load_enumerations_on_array_open If true, enumerations will be loaded for the latest array schema and sent to server together with the open array. Default: false
rest.load_enumerations_on_array_open_all_schemas If true, enumerations will be loaded for all schemas and sent to server together with the open array. Default: false
rest.use_refactored_array_open If true, the new REST routes and APIs for opening an array will be used Default: true
rest.use_refactored_array_open_and_query_submit If true, the new REST routes and APIs for opening an array and submitting a query will be used Default: true
rest.curl.buffer_size Set curl buffer size for REST requests Default: 524288 (512KB)
rest.capnp_traversal_limit CAPNP traversal limit used in the deserialization of messages(bytes) Default: 2147483648 (2GB)
rest.custom_headers.* (Optional) Prefix for custom headers on REST requests. For each custom header, use “rest.custom_headers.header_key” = “header_value” Optional. No Default
rest.payer_namespace The namespace that should be charged for the request. Default: no default set
filestore.buffer_size Specifies the size in bytes of the internal buffers used in the filestore API. The size should be bigger than the minimum tile size filestore currently supports, that is currently 1024bytes. Default: 100MB

Example:

tiledb_error_t* error = NULL;
tiledb_config_set(config, "sm.memory_budget", "1000000", &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).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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.memory_budget", &value, &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).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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);

Parameters:

config – The config object.
filename – The name of the file.
error – Error object returned upon error (NULL if there is no error).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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.memory_budget", &error);

Parameters:

config – The config object.
param – The parameter to be unset.
error – Error object returned upon error (NULL if there is no error).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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);

Parameters:

config – The config object.
filename – The name of the file.
error – Error object returned upon error (NULL if there is no error).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Config Iterator¶

capi_return_t 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);

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).

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for 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.

capi_return_t 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);

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).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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);

Parameters:

config_iter – The config iterator.
error – Error object returned upon error (NULL if there is no error).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_config_iter_done(tiledb_config_iter_t *config_iter, int32_t *done, tiledb_error_t **error)¶

Checks if the iterator is done.

Example:

int32_t done;
tiledb_config_iter_done(config_iter, &done, &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).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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);

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).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Error¶

capi_return_t 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. If the error does not contain an error message errmsg is set to NULL.

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

Parameters:

err – A TileDB error object.
errmsg – A constant pointer to the error message.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

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¶

capi_return_t 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, "s3://tiledb_arrays/my_array", &array);

Parameters:

ctx – [in] The TileDB context.
array_uri – [in] The array URI.
array – [out] The array object to be created.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

capi_return_t tiledb_array_set_open_timestamp_start(tiledb_ctx_t *ctx, tiledb_array_t *array, uint64_t timestamp_start)¶

Sets the starting timestamp to use when opening (and reopening) the array. This is an inclusive bound. The default value is 0.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array);
tiledb_array_set_open_timestamp_start(ctx, array, 1234);
tiledb_array_open(ctx, array, TILEDB_READ);

Parameters:

ctx – [in] The TileDB context.
array – [in] The array to set the timestamp on.
timestamp_start – [in] The epoch timestamp in milliseconds.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_array_set_open_timestamp_end(tiledb_ctx_t *ctx, tiledb_array_t *array, uint64_t timestamp_end)¶

Sets the ending timestamp to use when opening (and reopening) the array. This is an inclusive bound. The default value is UINT64_MAX.

When opening the array for reads, this value will be used to determine the ending timestamp of fragments to load. A value of UINT64_MAX will be translated to the current timestamp at which the array is opened.

When opening the array for writes, this value will be used to determine the timestamp to write new fragments. A value of UINT64_MAX will use the current timestamp at which the array is opened. A value of 0 will use the current timestamp at which the fragment is written.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array);
tiledb_array_set_open_timestamp_end(ctx, array, 5678);
tiledb_array_open(ctx, array, TILEDB_READ);

Parameters:

ctx – [in] The TileDB context.
array – [in] The array to set the timestamp on.
timestamp_end – [in] The epoch timestamp in milliseconds. Use UINT64_MAX for the current timestamp.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_array_get_open_timestamp_start(tiledb_ctx_t *ctx, tiledb_array_t *array, uint64_t *timestamp_start)¶

Gets the starting timestamp used when opening (and reopening) the array. This is an inclusive bound.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array);
tiledb_array_set_open_timestamp_start(ctx, array, 1234);
tiledb_array_open(ctx, array, TILEDB_READ);

uint64_t timestamp_start;
tiledb_array_get_open_timestamp_start(ctx, array, &timestamp_start);
assert(timestamp_start == 1234);

Parameters:

ctx – [in] The TileDB context.
array – [in] The array to set the timestamp on.
timestamp_start – [out] The output epoch timestamp in milliseconds.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_array_get_open_timestamp_end(tiledb_ctx_t *ctx, tiledb_array_t *array, uint64_t *timestamp_end)¶

Gets the ending timestamp used when opening (and reopening) the array. This is an inclusive bound. If UINT64_MAX was set, this will return the timestamp at the time the array was opened. If the array has not yet been opened, it will return UINT64_MAX.`

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array);
tiledb_array_set_open_timestamp_end(ctx, array, 5678);
tiledb_array_open(ctx, array, TILEDB_READ);

uint64_t timestamp_end;
tiledb_array_get_open_timestamp_end(ctx, array, &timestamp_end);
assert(timestamp_start == 5678);

Parameters:

ctx – [in] The TileDB context.
array – [in] The array to set the timestamp on.
timestamp_end – [out] The output epoch timestamp in milliseconds.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_array_delete_fragments_list(tiledb_ctx_t *ctx, const char *uri_str, const char *fragment_uris[], const size_t num_fragments)¶

Deletes array fragments with the input uris.

Example:

const char* fragment_uris[2] = {
  "s3://tiledb_arrays/my_array/__fragments/1",
  "s3://tiledb_arrays/my_array/__fragments/2"};
tiledb_array_delete_fragments_list(
  ctx, "s3://tiledb_arrays/my_array", fragment_uris, 2);

Parameters:

ctx – [in] The TileDB context.
uri_str – [in] The URI of the fragments’ parent Array.
fragment_uris – [in] The URIs of the fragments to be deleted.
num_fragments – [in] The number of fragments to be deleted.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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.

Example:

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

Note

If the same array object is opened again without being closed, an error will be thrown.

Note

The config should be set before opening an array.

Note

If the array is to be opened at a specfic time interval, the timestamp{start, end} values should be set to a config that’s set to the array object before opening the array.

Parameters:

ctx – [in] The TileDB context.
array – [in] The array object to be opened.
query_type – [in] The type of queries the array object will be receiving.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_is_open(tiledb_ctx_t *ctx, tiledb_array_t *array, int32_t *is_open)¶

Checks if the array is open.

Parameters:

ctx – [in] The TileDB context.
array – [in] The array to be checked.
is_open – [out] 1 if the array is open and 0 otherwise.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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.

Note: reopening encrypted arrays does not require the encryption key.

Example:

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

Note

This is applicable only to arrays opened for reads.

Note

If the array is to be reopened after opening at a specfic time interval, the timestamp{start, end} values and subsequent config object should be reset for the array before reopening.

Parameters:

ctx – [in] The TileDB context.
array – [in] The array object to be re-opened.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_set_config(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_config_t *config)¶

Sets the array config.

Example:

tiledb_array_t* array;
tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array);
// Set the config for the given array.
tiledb_config_t* config;
tiledb_array_set_config(ctx, array, config);
tiledb_array_open(ctx, array, TILEDB_READ);

Note

The config should be set before opening an array.

Parameters:

ctx – [in] The TileDB context.
array – [in] The array to set the config for.
config – [in] The config to be set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_config(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_config_t **config)¶

Gets the array config.

Example:

// Retrieve the config for the given array.
tiledb_config_t* config;
tiledb_array_get_config(ctx, array, config);

Parameters:

ctx – [in] The TileDB context.
array – [in] The array to set the config for.
config – [out] Set to the retrieved config.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_close(tiledb_ctx_t *ctx, tiledb_array_t *array)¶

Closes a TileDB array.

Example:

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

Note

If the array object has already been closed, the function has no effect.

Parameters:

ctx – [in] The TileDB context.
array – [in] The array object to be closed.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

void tiledb_array_free(tiledb_array_t **array)¶

Frees a TileDB array object.

Example:

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

Parameters:: array – [in] The array object to be freed.

capi_return_t 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, "s3://tiledb_arrays/my_array", array_schema);

Parameters:

ctx – [in] The TileDB context.
array_uri – [in] The array name.
array_schema – [in] The array schema.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_consolidate(tiledb_ctx_t *ctx, const char *array_uri, tiledb_config_t *config)¶

Depending on the consoliation mode in the config, consolidates either the fragment files, fragment metadata files, or array metadata files into a single file.

Example:

tiledb_array_consolidate(
    ctx, "s3:///tiledb_arrays/my_array", nullptr);

Parameters:

ctx – [in] The TileDB context.
array_uri – [in] The name of the TileDB array whose metadata will be consolidated.
config – [in] Configuration parameters for the consolidation (nullptr means default, which will use the config from ctx). The sm.consolidation.mode parameter determines which type of consolidation to perform.

Returns:

TILEDB_OK on success, and TILEDB_ERR on error.

capi_return_t tiledb_array_vacuum(tiledb_ctx_t *ctx, const char *array_uri, tiledb_config_t *config)¶

Cleans up the array, such as consolidated fragments and array metadata. Note that this will coarsen the granularity of time traveling (see docs for more information).

Example:

tiledb_array_vacuum(ctx, "s3:///tiledb_arrays/my_array");

Parameters:

ctx – [in] The TileDB context.
array_uri – [in] The name of the TileDB array to vacuum.
config – [in] Configuration parameters for the vacuuming (nullptr means default, which will use the config from ctx).

Returns:

TILEDB_OK on success, and TILEDB_ERR on error.

capi_return_t 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);

Note

The user must free the array schema with tiledb_array_schema_free.

Parameters:

ctx – [in] The TileDB context.
array – [in] The open array.
array_schema – [out] The array schema to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

capi_return_t 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, "s3://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);

Parameters:

ctx – [in] The TileDB context.
array – [in] The array.
query_type – [out] The query type to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_non_empty_domain(tiledb_ctx_t *ctx, tiledb_array_t *array, void *domain, int32_t *is_empty)¶

Retrieves the non-empty domain from an array. This is the union of the non-empty domains of the array fragments. This API only works for arrays that have numeric dimensions and all dimensions of the same type.

The domain passed in is memory that can contain the number of dimensions * 2

sizeof(type of dimension). The previous two is because we return the non empty domain as min/max. Dimensions are returned in order.

Example:

uint64_t domain[4]; // Assuming a 2D array, 2 [low, high] pairs
int32_t 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);

Parameters:

ctx – [in] The TileDB context
array – [in] The array object (must be opened beforehand).
domain – [out] The domain to be retrieved.
is_empty – [out] 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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_non_empty_domain_from_index(tiledb_ctx_t *ctx, tiledb_array_t *array, uint32_t idx, void *domain, int32_t *is_empty)¶

Retrieves the non-empty domain from an array for a given dimension index. This is the union of the non-empty domains of the array fragments on the given dimension.

Example:

uint64_t domain[2];
int32_t 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_from_index(ctx, array, 0, domain,
&is_empty);

Parameters:

ctx – [in] The TileDB context
array – [in] The array object (must be opened beforehand).
idx – [in] The dimension index, following the order as it was defined in the domain of the array schema.
domain – [out] The domain to be retrieved.
is_empty – [out] 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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_non_empty_domain_from_name(tiledb_ctx_t *ctx, tiledb_array_t *array, const char *name, void *domain, int32_t *is_empty)¶

Retrieves the non-empty domain from an array for a given dimension name. This is the union of the non-empty domains of the array fragments on the given dimension.

Example:

uint64_t domain[2];
int32_t 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_from_name(ctx, array, "d1", domain,
&is_empty);

Parameters:

ctx – [in] The TileDB context
array – [in] The array object (must be opened beforehand).
name – [in] The dimension name.
domain – [out] The domain to be retrieved.
is_empty – [out] 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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_non_empty_domain_var_size_from_index(tiledb_ctx_t *ctx, tiledb_array_t *array, uint32_t idx, uint64_t *start_size, uint64_t *end_size, int32_t *is_empty)¶

Retrieves the non-empty domain range sizes from an array for a given dimension index. This is the union of the non-empty domains of the array fragments on the given dimension. Applicable only to var-sized dimensions.

Example:

int32_t is_empty;
tiledb_array_t* array;
tiledb_array_alloc(ctx, "my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);
uint64_t start_size, end_size;
tiledb_array_get_non_empty_domain_var_size_from_index(
    ctx, array, 0, &start_size, &end_size, &is_empty);
// If non-empty domain range is `[aa, dddd]`, then `start_size = 2`
// and `end_size = 4`.

Parameters:

ctx – [in] The TileDB context
array – [in] The array object (must be opened beforehand).
idx – [in] The dimension index, following the order as it was defined in the domain of the array schema.
start_size – [out] The size in bytes of the start range.
end_size – [out] The size in bytes of the end range.
is_empty – [out] 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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_non_empty_domain_var_size_from_name(tiledb_ctx_t *ctx, tiledb_array_t *array, const char *name, uint64_t *start_size, uint64_t *end_size, int32_t *is_empty)¶

Retrieves the non-empty domain range sizes from an array for a given dimension name. This is the union of the non-empty domains of the array fragments on the given dimension. Applicable only to var-sized dimensions.

Example:

int32_t is_empty;
tiledb_array_t* array;
tiledb_array_alloc(ctx, "my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);
uint64_t start_size, end_size;
tiledb_array_get_non_empty_domain_var_size_from_name(
    ctx, array, "d", &start_size, &end_size, &is_empty);
// If non-empty domain range is `[aa, dddd]`, then `start_size = 2`
// and `end_size = 4`.

Parameters:

ctx – [in] The TileDB context
array – [in] The array object (must be opened beforehand).
name – [in] The dimension name.
start_size – [out] The size in bytes of the start range.
end_size – [out] The size in bytes of the end range.
is_empty – [out] 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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_non_empty_domain_var_from_index(tiledb_ctx_t *ctx, tiledb_array_t *array, uint32_t idx, void *start, void *end, int32_t *is_empty)¶

Retrieves the non-empty domain from an array for a given dimension index. This is the union of the non-empty domains of the array fragments on the given dimension. Applicable only to var-sized dimensions.

Example:

int32_t is_empty;
tiledb_array_t* array;
tiledb_array_alloc(ctx, "my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);

// Get range sizes first
uint64_t start_size, end_size;
tiledb_array_get_non_empty_domain_var_size_from_index(
    ctx, array, 0, &start_size, &end_size, &is_empty);

// Get domain
char start[start_size];
char end[end_size];
tiledb_array_get_non_empty_domain_var_from_index(
    ctx, array, 0, start, end, &is_empty);

Parameters:

ctx – [in] The TileDB context
array – [in] The array object (must be opened beforehand).
idx – [in] The dimension index, following the order as it was defined in the domain of the array schema.
start – [out] The domain range start to set.
end – [out] The domain range end to set.
is_empty – [out] 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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_non_empty_domain_var_from_name(tiledb_ctx_t *ctx, tiledb_array_t *array, const char *name, void *start, void *end, int32_t *is_empty)¶

Retrieves the non-empty domain from an array for a given dimension name. This is the union of the non-empty domains of the array fragments on the given dimension. Applicable only to var-sized dimensions.

Example:

uint64_t domain[2];
int32_t is_empty;
tiledb_array_t* array;
tiledb_array_alloc(ctx, "my_array", &array);
tiledb_array_open(ctx, array, TILEDB_READ);

// Get range sizes first
uint64_t start_size, end_size;
tiledb_array_get_non_empty_domain_var_size_from_name(
    ctx, array, "d", &start_size, &end_size, &is_empty);

// Get domain
char start[start_size];
char end[end_size];
tiledb_array_get_non_empty_domain_var_from_name(
    ctx, array, "d", start, end, &is_empty);

Parameters:

ctx – [in] The TileDB context
array – [in] The array object (must be opened beforehand).
name – [in] The dimension name.
start – [out] The domain range start to set.
end – [out] The domain range end to set.
is_empty – [out] 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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_uri(tiledb_ctx_t *ctx, tiledb_array_t *array, const char **array_uri)¶

Retrieves the URI the array was opened with. It outputs an error if the array is not open.

Parameters:

ctx – [in] The TileDB context.
array – [in] The input array.
array_uri – [out] The array URI to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_encryption_type(tiledb_ctx_t *ctx, const char *array_uri, tiledb_encryption_type_t *encryption_type)¶

Retrieves the encryption type the array at the given URI was created with.

Parameters:

ctx – [in] The TileDB context.
array_uri – [in] The array URI.
encryption_type – [out] The array encryption type to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_put_metadata(tiledb_ctx_t *ctx, tiledb_array_t *array, const char *key, tiledb_datatype_t value_type, uint32_t value_num, const void *value)¶

It puts a metadata key-value item to an open array. The array must be opened in WRITE mode, otherwise the function will error out.

Note

The writes will take effect only upon closing the array.

Parameters:

ctx – [in] The TileDB context.
array – [in] An array opened in WRITE mode.
key – [in] The key of the metadata item to be added. UTF-8 encodings are acceptable.
value_type – [in] The datatype of the value.
value_num – [in] The value may consist of more than one items of the same datatype. This argument indicates the number of items in the value component of the metadata.
value – [in] The metadata value in binary form.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_metadata(tiledb_ctx_t *ctx, tiledb_array_t *array, const char *key, tiledb_datatype_t *value_type, uint32_t *value_num, const void **value)¶

It gets a metadata key-value item from an open array. The array must be opened in READ mode, otherwise the function will error out.

Note

If the key does not exist, then value will be NULL.

Parameters:

ctx – [in] The TileDB context.
array – [in] An array opened in READ mode.
key – [in] The key of the metadata item to be retrieved. UTF-8 encodings are acceptable.
value_type – [out] The datatype of the value.
value_num – [out] The value may consist of more than one items of the same datatype. This argument indicates the number of items in the value component of the metadata. Keys with empty values are indicated by value_num == 1 and value == NULL.
value – [out] The metadata value in binary form.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_metadata_from_index(tiledb_ctx_t *ctx, tiledb_array_t *array, uint64_t index, const char **key, uint32_t *key_len, tiledb_datatype_t *value_type, uint32_t *value_num, const void **value)¶

It gets a metadata item from an open array using an index. The array must be opened in READ mode, otherwise the function will error out.

Parameters:

ctx – [in] The TileDB context.
array – [in] An array opened in READ mode.
index – [in] The index used to get the metadata.
key – [out] The metadata key.
key_len – [out] The metadata key length.
value_type – [out] The datatype of the value.
value_num – [out] The value may consist of more than one items of the same datatype. This argument indicates the number of items in the value component of the metadata.
value – [out] The metadata value in binary form.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_has_metadata_key(tiledb_ctx_t *ctx, tiledb_array_t *array, const char *key, tiledb_datatype_t *value_type, int32_t *has_key)¶

Checks whether a key exists in metadata from an open array. The array must be opened in READ mode, otherwise the function will error out.

Note

If the key does not exist, then value will be NULL.

Parameters:

ctx – [in] The TileDB context.
array – [in] An array opened in READ mode.
key – [in] The key to be checked. UTF-8 encoding are acceptable.
value_type – [out] The datatype of the value, if any.
has_key – [out] Set to 1 if the metadata with given key exists, else 0.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_get_metadata_num(tiledb_ctx_t *ctx, tiledb_array_t *array, uint64_t *num)¶

It gets then number of metadata items in an open array. The array must be opened in READ mode, otherwise the function will error out.

Parameters:

ctx – [in] The TileDB context.
array – [in] An array opened in READ mode.
num – [out] The number of metadata items to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_delete_metadata(tiledb_ctx_t *ctx, tiledb_array_t *array, const char *key)¶

It deletes a metadata key-value item from an open array. The array must be opened in WRITE mode, otherwise the function will error out.

Note

The writes will take effect only upon closing the array.

Note

If the key does not exist, this will take no effect (i.e., the function will not error out).

Parameters:

ctx – [in] The TileDB context.
array – [in] An array opened in WRITE mode.
key – [in] The key of the metadata item to be deleted.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Array Schema¶

capi_return_t 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);

Parameters:

ctx – [in] The TileDB context.
array_type – [in] The array type.
array_schema – [out] The TileDB array schema to be created.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

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 – [in] The array schema to be destroyed.

capi_return_t 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);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
attr – [in] The attribute to be added.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_set_allows_dups(tiledb_ctx_t *ctx, tiledb_array_schema_t *array_schema, int allows_dups)¶

Sets whether the array can allow coordinate duplicates or not. Applicable only to sparse arrays (it errors out if set to 1 for dense arrays).

Example:

int allows_dups = 1;
tiledb_array_schema_set_allows_dups(ctx, array_schema, allows_dups);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
allows_dups – [in] Whether or not the array allows coordinate duplicates.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_get_allows_dups(tiledb_ctx_t *ctx, tiledb_array_schema_t *array_schema, int *allows_dups)¶

Gets whether the array can allow coordinate duplicates or not. It should always be 0 for dense arrays.

Example:

int allows_dups;
tiledb_array_schema_get_allows_dups(ctx, array_schema, &allows_dups);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
allows_dups – [out] Whether or not the array allows coordinate duplicates.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_get_version(tiledb_ctx_t *ctx, tiledb_array_schema_t *array_schema, uint32_t *version)¶

Returns the array schema version.

Example:

uint32_t version;
tiledb_array_schema_get_version(ctx, array_schema, &version);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
version – [out] The version.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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);

Pre:

The domain has at least one dimension set.

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
domain – [in] The domain to be set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_set_capacity(tiledb_ctx_t *ctx, tiledb_array_schema_t *array_schema, uint64_t capacity)¶

Sets the tile capacity. Applies to sparse arrays only.

Example:

tiledb_array_schema_set_capacity(ctx, array_schema, 10000);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
capacity – [in] The capacity of a sparse data tile. Note that sparse data tiles exist in sparse fragments, which can be created in sparse arrays only. For more details, see tutorials/tiling-sparse.html.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
cell_order – [in] The cell order to be set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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_tile_order(ctx, array_schema, TILEDB_COL_MAJOR);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
tile_order – [in] The tile order to be set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_set_coords_filter_list(tiledb_ctx_t *ctx, tiledb_array_schema_t *array_schema, tiledb_filter_list_t *filter_list)¶

Sets the filter list to use for the coordinates.

Example:

tiledb_filter_list_t* filter_list;
tiledb_filter_list_alloc(ctx, &filter_list);
tiledb_filter_list_add_filter(ctx, filter_list, filter);
tiledb_array_schema_set_coords_filter_list(ctx, array_schema, filter_list);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
filter_list – [in] The filter list to be set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_set_offsets_filter_list(tiledb_ctx_t *ctx, tiledb_array_schema_t *array_schema, tiledb_filter_list_t *filter_list)¶

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

Example:

tiledb_filter_list_t* filter_list;
tiledb_filter_list_alloc(ctx, &filter_list);
tiledb_filter_list_add_filter(ctx, filter_list, filter);
tiledb_array_schema_set_offsets_filter_list(ctx, array_schema, filter_list);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
filter_list – [in] The filter list to be set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_set_validity_filter_list(tiledb_ctx_t *ctx, tiledb_array_schema_t *array_schema, tiledb_filter_list_t *filter_list)¶

Sets the filter list to use for the validity array of nullable attribute values.

Example:

tiledb_filter_list_t* filter_list;
tiledb_filter_list_alloc(ctx, &filter_list);
tiledb_filter_list_add_filter(ctx, filter_list, filter);
tiledb_array_schema_set_validity_filter_list(ctx, array_schema, filter_list);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
filter_list – [in] The filter list to be set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.

Returns:

TILEDB_OK if the array schema is correct and TILEDB_ERR upon any error.

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

Retrieves the latest 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

Parameters:

ctx – [in] The TileDB context.
array_uri – [in] The array whose schema will be retrieved.
array_schema – [out] The array schema to be retrieved, or NULL upon error.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

capi_return_t 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

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
array_type – [out] The array type to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
capacity – [out] The capacity to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
cell_order – [out] The cell order to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_get_coords_filter_list(tiledb_ctx_t *ctx, tiledb_array_schema_t *array_schema, tiledb_filter_list_t **filter_list)¶

Retrieves the filter list used for the coordinates.

Example:

tiledb_filter_list_t* filter_list;
tiledb_array_schema_get_coords_filter_list(ctx, array_schema, &filter_list);
tiledb_filter_list_free(ctx, &filter_list);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
filter_list – [out] The filter list to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_get_offsets_filter_list(tiledb_ctx_t *ctx, tiledb_array_schema_t *array_schema, tiledb_filter_list_t **filter_list)¶

Retrieves the filter list used for the offsets.

Example:

tiledb_filter_list_t* filter_list;
tiledb_array_schema_get_offsets_filter_list(ctx, array_schema, &filter_list);
tiledb_filter_list_free(ctx, &filter_list);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
filter_list – [out] The filter list to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_get_validity_filter_list(tiledb_ctx_t *ctx, tiledb_array_schema_t *array_schema, tiledb_filter_list_t **filter_list)¶

Retrieves the filter list used for validity maps.

Example:

tiledb_filter_list_t* filter_list;
tiledb_array_schema_get_validity_filter_list(
 ctx, array_schema, &filter_list);
tiledb_filter_list_free(ctx, &filter_list);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
filter_list – [out] The filter list to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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);
tiledb_domain_free(&domain);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
domain – [out] The array domain to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

capi_return_t 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);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
tile_order – [out] The tile order to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_get_attribute_num(tiledb_ctx_t *ctx, const tiledb_array_schema_t *array_schema, uint32_t *attribute_num)¶

Retrieves the number of array attributes.

Example:

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

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
attribute_num – [out] The number of attributes to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_get_attribute_from_index(tiledb_ctx_t *ctx, const tiledb_array_schema_t *array_schema, uint32_t 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);
tiledb_attribute_free(&attr);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
index – [in] The index of the attribute to retrieve.
attr – [out] The attribute object to retrieve.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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 attribute named “a” in the schema.

tiledb_attribute_t* attr;
tiledb_array_schema_get_attribute_from_name(ctx, array_schema, "a", &attr);
tiledb_attribute_free(&attr);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
name – [in] The name (key) of the attribute to retrieve.
attr – [out] The attribute object to retrieve.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_has_attribute(tiledb_ctx_t *ctx, const tiledb_array_schema_t *array_schema, const char *name, int32_t *has_attr)¶

Checks whether the array schema has an attribute of the given name.

Example:

int32_t has_attr;
tiledb_array_schema_has_attribute(ctx, array_schema, "attr_0", &has_attr);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
name – [in] The name of the attribute to check for.
has_attr – [out] Set to 1 if the array schema has an attribute of the given name, else 0.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_array_schema_dump_str(tiledb_ctx_t *ctx, const tiledb_array_schema_t *array_schema, tiledb_string_t **out)¶

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

The output string handle must be freed by the user after use.

Example:

tiledb_string_t* tdb_string;
tiledb_array_schema_dump_str(ctx, array_schema, &tdb_string);
// Use the string
tiledb_string_free(&tdb_string);

Parameters:

ctx – [in] The TileDB context.
array_schema – [in] The array schema.
out – [out] The output string.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Attribute¶

int32_t 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);

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.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

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.

int32_t tiledb_attribute_set_nullable(tiledb_ctx_t *ctx, tiledb_attribute_t *attr, uint8_t nullable)¶

Sets the nullability of an attribute.

Example:

tiledb_attribute_set_nullable(ctx, attr, 1);

Parameters:

ctx – The TileDB context.
attr – The target attribute.
nullable – Non-zero if the attribute is nullable.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_attribute_set_filter_list(tiledb_ctx_t *ctx, tiledb_attribute_t *attr, tiledb_filter_list_t *filter_list)¶

Sets the filter list for an attribute.

Example:

tiledb_filter_list_t* filter_list;
tiledb_filter_list_alloc(ctx, &filter_list);
tiledb_filter_list_add_filter(ctx, filter_list, filter);
tiledb_attribute_set_filter_list(ctx, attr, filter_list);

Parameters:

ctx – The TileDB context.
attr – The target attribute.
filter_list – The filter_list to be set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_attribute_set_cell_val_num(tiledb_ctx_t *ctx, tiledb_attribute_t *attr, uint32_t 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);

Parameters:

ctx – The TileDB context.
attr – The target attribute.
cell_val_num – The number of values per cell.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t 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);

Parameters:

ctx – The TileDB context.
attr – The attribute.
name – The name to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t 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);

Parameters:

ctx – The TileDB context.
attr – The attribute.
type – The type to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_attribute_get_nullable(tiledb_ctx_t *ctx, tiledb_attribute_t *attr, uint8_t *nullable)¶

Retrieves the nullability of an attribute.

Example:

uint8_t nullable;
tiledb_attribute_get_nullable(ctx, attr, &nullable);

Parameters:

ctx – The TileDB context.
attr – The target attribute.
nullable – Output argument, non-zero for nullable and zero for non-nullable.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_attribute_get_filter_list(tiledb_ctx_t *ctx, tiledb_attribute_t *attr, tiledb_filter_list_t **filter_list)¶

Retrieves the filter list for an attribute.

Example:

tiledb_filter_list_t* filter_list;
tiledb_attribute_get_filter_list(ctx, attr, &filter_list);
tiledb_filter_list_free(&filter_list);

Parameters:

ctx – The TileDB context.
attr – The target attribute.
filter_list – The filter list to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_attribute_get_cell_val_num(tiledb_ctx_t *ctx, const tiledb_attribute_t *attr, uint32_t *cell_val_num)¶

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

Example:

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

Parameters:

ctx – The TileDB context.
attr – The attribute.
cell_val_num – The number of values per cell to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t 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);

Parameters:

ctx – The TileDB context.
attr – The attribute.
cell_size – The cell size to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_attribute_dump_str(tiledb_ctx_t *ctx, const tiledb_attribute_t *attr, tiledb_string_t **out)¶

Dumps the contents of an Attribute in ASCII form to the selected string output.

The output string handle must be freed by the user after use.

Example:

tiledb_string_t* tdb_string;
tiledb_attribute_dump_str(ctx, attr, &tdb_string);
// Use the string
tiledb_string_free(&tdb_string);

Parameters:

ctx – The TileDB context.
attr – The attribute.
out – The output string.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_attribute_set_fill_value(tiledb_ctx_t *ctx, tiledb_attribute_t *attr, const void *value, uint64_t size)¶

Sets the default fill value for the input attribute. This value will be used for the input attribute whenever querying (1) an empty cell in a dense array, or (2) a non-empty cell (in either dense or sparse array) when values on the input attribute are missing (e.g., if the user writes a subset of the attributes in a write operation).

Applicable to var-sized attributes.

Example:

// Assumming a int32 attribute
int32_t value = 0;
uint64_t size = sizeof(value);
tiledb_attribute_set_fill_value(ctx, attr, &value, size);

// Assumming a var char attribute
const char* value = "foo";
uint64_t size = strlen(value);
tiledb_attribute_set_fill_value(ctx, attr, value, size);

Note

A call to tiledb_attribute_cell_val_num sets the fill value of the attribute to its default. Therefore, make sure you invoke tiledb_attribute_set_fill_value after deciding on the number of values this attribute will hold in each cell.

Note

For fixed-sized attributes, the input size should be equal to the cell size.

Parameters:

ctx – The TileDB context.
attr – The target attribute.
value – The fill value to set.
size – The fill value size in bytes.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_attribute_get_fill_value(tiledb_ctx_t *ctx, tiledb_attribute_t *attr, const void **value, uint64_t *size)¶

Gets the default fill value for the input attribute. This value will be used for the input attribute whenever querying (1) an empty cell in a dense array, or (2) a non-empty cell (in either dense or sparse array) when values on the input attribute are missing (e.g., if the user writes a subset of the attributes in a write operation).

Applicable to both fixed-sized and var-sized attributes.

Example:

// Assuming a int32 attribute
const int32_t* value;
uint64_t size;
tiledb_attribute_get_fill_value(ctx, attr, &value, &size);

// Assuming a var char attribute
const char* value;
uint64_t size;
tiledb_attribute_get_fill_value(ctx, attr, &value, &size);

Parameters:

ctx – The TileDB context.
attr – The target attribute.
value – A pointer to the fill value to get.
size – The size of the fill value to get.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_attribute_set_fill_value_nullable(tiledb_ctx_t *ctx, tiledb_attribute_t *attr, const void *value, uint64_t size, uint8_t validity)¶

Sets the default fill value for the input, nullable attribute. This value will be used for the input attribute whenever querying (1) an empty cell in a dense array, or (2) a non-empty cell (in either dense or sparse array) when values on the input attribute are missing (e.g., if the user writes a subset of the attributes in a write operation).

Applicable to var-sized attributes.

Example:

// Assumming a int32 attribute
int32_t value = 0;
uint64_t size = sizeof(value);
uint8_t valid = 0;
tiledb_attribute_set_fill_value_nullable(ctx, attr, &value, size, valid);

// Assumming a var char attribute
const char* value = "foo";
uint64_t size = strlen(value);
uint8_t valid = 1;
tiledb_attribute_set_fill_value_nullable(ctx, attr, value, size, valid);

Note

A call to tiledb_attribute_cell_val_num sets the fill value of the attribute to its default. Therefore, make sure you invoke tiledb_attribute_set_fill_value_nullable after deciding on the number of values this attribute will hold in each cell.

Note

For fixed-sized attributes, the input size should be equal to the cell size.

Parameters:

ctx – The TileDB context.
attr – The target attribute.
value – The fill value to set.
size – The fill value size in bytes.
validity – The validity fill value, zero for a null value and non-zero for a valid attribute.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_attribute_get_fill_value_nullable(tiledb_ctx_t *ctx, tiledb_attribute_t *attr, const void **value, uint64_t *size, uint8_t *valid)¶

Gets the default fill value for the input, nullable attribute. This value will be used for the input attribute whenever querying (1) an empty cell in a dense array, or (2) a non-empty cell (in either dense or sparse array) when values on the input attribute are missing (e.g., if the user writes a subset of the attributes in a write operation).

Applicable to both fixed-sized and var-sized attributes.

Example:

// Assuming a int32 attribute
const int32_t* value;
uint64_t size;
uint8_t valid;
tiledb_attribute_get_fill_value_nullable(ctx, attr, &value, &size, &valid);

// Assuming a var char attribute
const char* value;
uint64_t size;
uint8_t valid;
tiledb_attribute_get_fill_value_nullable(ctx, attr, &value, &size, &valid);

Parameters:

ctx – The TileDB context.
attr – The target attribute.
value – A pointer to the fill value to get.
size – The size of the fill value to get.
valid – The fill value validity to get.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Domain¶

int32_t 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);

Parameters:

ctx – The TileDB context.
domain – The TileDB domain to be created.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

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.

int32_t 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);

Parameters:

ctx – The TileDB context.
domain – The domain.
type – The type to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_domain_get_ndim(tiledb_ctx_t *ctx, const tiledb_domain_t *domain, uint32_t *ndim)¶

Retrieves the number of dimensions in a domain.

Example:

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

Parameters:

ctx – The TileDB context
domain – The domain
ndim – The number of dimensions in a domain.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t 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;
int64_t dim_domain[] = {1, 10};
int64_t tile_extent = 5;
tiledb_dimension_alloc(
    ctx, "dim_0", TILEDB_INT64, dim_domain, &tile_extent, &dim);
tiledb_domain_add_dimension(ctx, domain, dim);

Parameters:

ctx – The TileDB context.
domain – The domain to add the dimension to.
dim – The dimension to be added.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_domain_get_dimension_from_index(tiledb_ctx_t *ctx, const tiledb_domain_t *domain, uint32_t 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);

Parameters:

ctx – The TileDB context
domain – The domain to add the dimension to.
index – The index of domain dimension
dim – The retrieved dimension object.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t 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);

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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_domain_has_dimension(tiledb_ctx_t *ctx, const tiledb_domain_t *domain, const char *name, int32_t *has_dim)¶

Checks whether the domain has a dimension of the given name.

Example:

int32_t has_dim;
tiledb_domain_has_dimension(ctx, domain, "dim_0", &has_dim);

Parameters:

ctx – The TileDB context.
domain – The domain.
name – The name of the dimension to check for.
has_dim – Set to 1 if the domain has a dimension of the given name, else 0.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_domain_dump_str(tiledb_ctx_t *ctx, const tiledb_domain_t *domain, tiledb_string_t **out)¶

Dumps the contents of a domain in ASCII form to the selected string output.

The output string handle must be freed by the user after use.

Example:

tiledb_string_t* tdb_string;
tiledb_domain_dump_str(ctx, domain, &tdb_string);
// Use the string
tiledb_string_free(&tdb_string);

Parameters:

ctx – The TileDB context.
domain – The domain.
out – The output string.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Dimension¶

int32_t 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;
int64_t dim_domain[] = {1, 10};
int64_t tile_extent = 5;
tiledb_dimension_alloc(
    ctx, "dim_0", TILEDB_INT64, dim_domain, &tile_extent, &dim);

Note: as laid out in the Storage Format, the following Datatypes are not valid for Dimension: TILEDB_CHAR, TILEDB_BLOB, TILEDB_GEOM_WKB, TILEDB_GEOM_WKT, TILEDB_BOOL, TILEDB_STRING_UTF8, TILEDB_STRING_UTF16, TILEDB_STRING_UTF32, TILEDB_STRING_UCS2, TILEDB_STRING_UCS4, TILEDB_ANY

Parameters:

ctx – The TileDB context.
name – The dimension name.
type – The dimension type.
dim_domain – The dimension domain.
tile_extent – The dimension tile extent.
dim – The dimension to be created.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

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.

int32_t 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);

Parameters:

ctx – The TileDB context.
dim – The dimension.
name – The name to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t 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);

Parameters:

ctx – The TileDB context.
dim – The dimension.
type – The type to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

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

Retrieves the domain of the dimension.

Example:

uint64_t* domain;
tiledb_dimension_get_domain(ctx, dim, &domain);

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).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_dimension_get_cell_val_num(tiledb_ctx_t *ctx, const tiledb_dimension_t *dim, uint32_t *cell_val_num)¶

Retrieves the number of values per cell for a dimension. For variable-sized dimensions the result is TILEDB_VAR_NUM.

Example:

uint32_t num;
tiledb_dimension_get_cell_val_num(ctx, dim, &num);

Parameters:

ctx – The TileDB context.
dim – The dimension.
cell_val_num – The number of values per cell to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_dimension_set_cell_val_num(tiledb_ctx_t *ctx, tiledb_dimension_t *dim, uint32_t cell_val_num)¶

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

Examples:

For a fixed-sized dimension:

tiledb_dimension_set_cell_val_num(ctx, dim, 3);

For a variable-sized dimension:

tiledb_dimension_set_cell_val_num(ctx, dim, TILEDB_VAR_NUM);

Parameters:

ctx – The TileDB context.
dim – The target dimension.
cell_val_num – The number of values per cell.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_dimension_get_filter_list(tiledb_ctx_t *ctx, tiledb_dimension_t *dim, tiledb_filter_list_t **filter_list)¶

Retrieves the filter list for a dimension.

Example:

tiledb_filter_list_t* filter_list;
tiledb_dimension_get_filter_list(ctx, dim, &filter_list);
tiledb_filter_list_free(&filter_list);

Parameters:

ctx – The TileDB context.
dim – The target dimension.
filter_list – The filter list to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_dimension_set_filter_list(tiledb_ctx_t *ctx, tiledb_dimension_t *dim, tiledb_filter_list_t *filter_list)¶

Sets the filter list for a dimension.

Example:

tiledb_filter_list_t* filter_list;
tiledb_filter_list_alloc(ctx, &filter_list);
tiledb_filter_list_add_filter(ctx, filter_list, filter);
tiledb_dimension_set_filter_list(ctx, dim, filter_list);

Parameters:

ctx – The TileDB context.
dim – The target dimension.
filter_list – The filter_list to be set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

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

Retrieves the tile extent of the dimension.

Example:

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

Parameters:

ctx – The TileDB context.
dim – The dimension.
tile_extent – The tile extent (pointer) to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_dimension_dump_str(tiledb_ctx_t *ctx, const tiledb_dimension_t *dimension, tiledb_string_t **out)¶

Dumps the contents of a dimension in ASCII form to the selected string output.

The output string handle must be freed by the user after use.

Example:

tiledb_string_t* tdb_string;
tiledb_dimension_dump_str(ctx, dimension, &tdb_string);
// Use the string
tiledb_string_free(&tdb_string);

Parameters:

ctx – The TileDB context.
dimension – The dimension.
out – The output string.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Query¶

int32_t 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);

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.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

int32_t tiledb_query_get_stats(tiledb_ctx_t *ctx, tiledb_query_t *query, char **stats_json)¶

Retrieves the stats from a Query.

Example:

char* stats_json;
tiledb_query_get_stats(ctx, query, &stats_json);
// Use the string
tiledb_stats_free_str(&stats_json);

Parameters:

ctx – The TileDB context.
query – The query object.
stats_json – The output json. The caller takes ownership of the c-string and must free it using tiledb_stats_free_str().

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

int32_t tiledb_query_set_config(tiledb_ctx_t *ctx, tiledb_query_t *query, tiledb_config_t *config)¶

Set the query config

Setting the query config will also set the subarray configuration in order to maintain existing behavior. If you wish the subarray to have a different configuration than the query, set it after calling tiledb_query_set_config.

Setting the configuration with this function overrides the following Query-level parameters only:

sm.memory_budget
sm.memory_budget_var
sm.var_offsets.mode
sm.var_offsets.extra_element
sm.var_offsets.bitsize
sm.check_coord_dups
sm.check_coord_oob
sm.check_global_order
sm.dedup_coords

int32_t tiledb_query_get_config(tiledb_ctx_t *ctx, tiledb_query_t *query, tiledb_config_t **config)¶

Retrieves the config from a Query.

Example:

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

Parameters:

ctx – The TileDB context.
query – The query object.
config – The config to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

int32_t tiledb_query_set_data_buffer(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, void *buffer, uint64_t *buffer_size)¶

Sets the buffer for an attribute/dimension 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.

The caller owns the buffer provided and is responsible for freeing the memory associated with it. For writes, the buffer holds values to be written which can be freed at any time after query completion. For reads, the buffer is allocated by the caller and will contain data read by the query after completion. The freeing of this memory is up to the caller once they are done referencing the read data.

Example:

int32_t a1[100];
uint64_t a1_size = sizeof(a1);
tiledb_query_set_data_buffer(ctx, query, "a1", a1, &a1_size);

Parameters:

ctx – The TileDB context.
query – The TileDB query.
name – The attribute/dimension to set the buffer for. Note that zipped coordinates have special 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 query it will contain the size of the useful (read) data in buffer.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_set_offsets_buffer(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, uint64_t *buffer, uint64_t *buffer_size)¶

Sets the starting offsets of each cell value in the data buffer.

The caller owns the buffer provided and is responsible for freeing the memory associated with it. For writes, the buffer holds offsets to be written which can be freed at any time after query completion. For reads, the buffer is allocated by the caller and will contain offset data read by the query after completion. The freeing of this memory is up to the caller once they are done referencing the read data.

Example:

uint64_t a1[100];
uint64_t a1_size = sizeof(a1);
tiledb_query_set_offsets_buffer(ctx, query, "a1", a1, &a1_size);

Parameters:

ctx – The TileDB context.
query – The TileDB query.
name – The attribute/dimension to set the buffer for. Note that zipped coordinates have special name TILEDB_COORDS.
buffer – This buffer holds the starting offsets of each cell value in buffer_val.
buffer_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 end of the query (tiledb_query_submit) it will contain the size of the useful (read) data in buffer_off.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_set_validity_buffer(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, uint8_t *buffer, uint64_t *buffer_size)¶

Sets the validity byte map that has exactly one value for each value in the data buffer.

The caller owns the buffer provided and is responsible for freeing the memory associated with it. For writes, the buffer holds validity values to be written which can be freed at any time after query completion. For reads, the buffer is allocated by the caller and will contain the validity map read by the query after completion. The freeing of this memory is up to the caller once they are done referencing the read data.

Example:

uint8_t a1[100];
uint64_t a1_size = sizeof(a1);
tiledb_query_set_validity_buffer(ctx, query, "a1", a1, &a1_size);

Parameters:

ctx – The TileDB context.
query – The TileDB query.
name – The attribute/dimension to set the buffer for. Note that zipped coordinates have special name TILEDB_COORDS.
buffer – The validity byte map that has exactly one value for each value in buffer.
buffer_size – In the case of writes, this is the size of buffer_validity_bytemap in bytes. In the case of reads, this initially contains the allocated size of buffer_validity_bytemap, but after the termination of the query it will contain the size of the useful (read) data in buffer_validity_bytemap.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_get_data_buffer(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, void **buffer, uint64_t **buffer_size)¶

Gets the buffer of a fixed-sized attribute/dimension from a query. If the buffer has not been set, then buffer is set to nullptr.

Example:

int* a1;
uint64_t* a1_size;
tiledb_query_get_data_buffer(ctx, query, "a1", &a1, &a1_size);

Parameters:

ctx – The TileDB context.
query – The TileDB query.
name – The attribute/dimension to get the buffer for. Note that the zipped coordinates have special name TILEDB_COORDS.
buffer – The buffer to retrieve.
buffer_size – A pointer to the size of the buffer. Note that this is a double pointer and returns the original variable address from set_buffer.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_get_offsets_buffer(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, uint64_t **buffer, uint64_t **buffer_size)¶

Gets the starting offsets of each cell value in the data buffer.

Example:

int* a1;
uint64_t* a1_size;
tiledb_query_get_offsets_buffer(ctx, query, "a1", &a1, &a1_size);

Parameters:

ctx – The TileDB context.
query – The TileDB query.
name – The attribute/dimension to get the buffer for. Note that the zipped coordinates have special name TILEDB_COORDS.
buffer – The buffer to retrieve.
buffer_size – A pointer to the size of the buffer. Note that this is a double pointer and returns the original variable address from set_buffer.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_get_validity_buffer(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, uint8_t **buffer, uint64_t **buffer_size)¶

Gets the validity byte map that has exactly one value for each value in the data buffer.

Example:

int* a1;
uint64_t* a1_size;
tiledb_query_get_validity_buffer(ctx, query, "a1", &a1, &a1_size);

Parameters:

ctx – The TileDB context.
query – The TileDB query.
name – The attribute/dimension to get the buffer for. Note that the zipped coordinates have special name TILEDB_COORDS.
buffer – The buffer to retrieve.
buffer_size – A pointer to the size of the buffer. Note that this is a double pointer and returns the original variable address from set_buffer.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t 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);

Returns:

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 reads and writes for sparse arrays, or for sparse writes to dense arrays. For writes, it specifies that the cells are unordered and, hence, TileDB must sort the cells in the global cell order prior to writing. For reads, TileDB will return the cells without any particular order, which will often lead to better performance.

int32_t tiledb_query_set_condition(tiledb_ctx_t *ctx, tiledb_query_t *query, const tiledb_query_condition_t *cond)¶

Sets the query condition to be applied on a read.

Example:

tiledb_query_condition_t* query_condition;
tiledb_query_condition_alloc(ctx, &query_condition);
uint32_t value = 5;
tiledb_query_condition_init(
  ctx, query_condition, "longitude", &value, sizeof(value), TILEDB_LT);
tiledb_query_set_condition(ctx, query, query_condition);

Parameters:

ctx – The TileDB context.
query – The TileDB query.
cond – The TileDB query condition.

int32_t 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);

Parameters:

ctx – The TileDB context.
query – The query object to be flushed.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_submit_and_finalize(tiledb_ctx_t *ctx, tiledb_query_t *query)¶

Submits and finalizes the query. This is applicable only to global layout writes. The function will error out if called on a query with non global layout. Its purpose is to submit the final chunk (partial or full tile) in a global order write query. tiledb_query_submit_and_finalize drops the tile alignment restriction of the buffers (i.e. compared to the regular global layout submit call) given the last chunk of a global order write is most frequently smaller in size than a tile.

Example:

tiledb_query_t* query;
while (stop_condition) {
  tiledb_query_set_buffer(ctx, query, attr, tile_aligned_buffer, &size);
  tiledb_query_submit(ctx, query);
}
tiledb_query_set_buffer(ctx, query, attr, final_chunk, &size);
tiledb_query_submit_and_finalize(ctx, query);

Parameters:

ctx – The TileDB context.
query – The query object to be flushed.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

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.

int32_t tiledb_query_submit(tiledb_ctx_t *ctx, tiledb_query_t *query)¶

Submits a TileDB query.

Example:

tiledb_query_submit(ctx, query);

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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t 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);

Parameters:

ctx – The TileDB context.
query – The query.
status – The query status to be retrieved.

Returns:

TILEDB_OK upon success, and TILEDB_ERR upon error.

int32_t 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);

Parameters:

ctx – The TileDB context.
query – The query.
query_type – The query type to be retrieved.

Returns:

TILEDB_OK upon success, and TILEDB_ERR upon error.

int32_t tiledb_query_get_layout(tiledb_ctx_t *ctx, tiledb_query_t *query, tiledb_layout_t *query_layout)¶

Retrieves the query layout.

Example:

tiledb_layout_t query_layout;
tiledb_query_get_layout(ctx, query, &query_layout);

Parameters:

ctx – The TileDB context.
query – The query.
query_layout – The query layout to be retrieved.

Returns:

TILEDB_OK upon success, and TILEDB_ERR upon error.

int32_t tiledb_query_get_array(tiledb_ctx_t *ctx, tiledb_query_t *query, tiledb_array_t **array)¶

Retrieves the query array.

Example:

tiledb_array_t* array;
tiledb_query_get_array(ctx, query, &array);

Parameters:

ctx – The TileDB context.
query – The query.
array – The query array to be retrieved.

Returns:

TILEDB_OK upon success, and TILEDB_ERR upon error.

int32_t tiledb_query_has_results(tiledb_ctx_t *ctx, tiledb_query_t *query, int32_t *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:

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

Parameters:

ctx – The TileDB context.
query – The query.
has_results – Set to 1 if the query returned results and 0 otherwise.

Returns:

TILEDB_OK upon success, and TILEDB_ERR upon error.

int32_t tiledb_query_get_est_result_size(tiledb_ctx_t *ctx, const tiledb_query_t *query, const char *name, uint64_t *size)¶

Retrieves the estimated result size for a fixed-sized attribute/dimension. This is an estimate and may not be sufficient to read all results for the requested range, in particular for sparse arrays or array with var-length attributes. Query status must be checked and resubmitted if not complete.

Example:

uint64_t size;
tiledb_query_get_est_result_size(ctx, query, "a", &size);

Parameters:

ctx – The TileDB context
query – The query.
name – The attribute/dimension name.
size – The size (in bytes) to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_get_est_result_size_var(tiledb_ctx_t *ctx, const tiledb_query_t *query, const char *name, uint64_t *size_off, uint64_t *size_val)¶

Retrieves the estimated result size for a var-sized attribute/dimension. This is an estimate and may not be sufficient to read all results for the requested range, for sparse arrays or any array with var-length attributes. Query status must be checked and resubmitted if not complete.

Example:

uint64_t size_off, size_val;
tiledb_query_get_est_result_size_var(
    ctx, query, "a", &size_off, &size_val);

Parameters:

ctx – The TileDB context
query – The query.
name – The attribute/dimension name.
size_off – The size of the offsets (in bytes) to be retrieved.
size_val – The size of the values (in bytes) to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_get_est_result_size_nullable(tiledb_ctx_t *ctx, const tiledb_query_t *query, const char *name, uint64_t *size_val, uint64_t *size_validity)¶

Retrieves the estimated result size for a fixed-sized, nullable attribute. This is an estimate and may not be sufficient to read all results for the requested range, for sparse arrays or any array with var-length attributes. Query status must be checked and resubmitted if not complete.

Example:

uint64_t size_val;
uint64_t size_validity;
tiledb_query_get_est_result_size_nullable(ctx, query, "a", &size_val,
&size_validity);

Parameters:

ctx – The TileDB context
query – The query.
name – The attribute name.
size_val – The size of the values (in bytes) to be retrieved.
size_validity – The size of the validity values (in bytes) to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_get_est_result_size_var_nullable(tiledb_ctx_t *ctx, const tiledb_query_t *query, const char *name, uint64_t *size_off, uint64_t *size_val, uint64_t *size_validity)¶

Retrieves the estimated result size for a var-sized, nullable attribute.

Example:

uint64_t size_off, size_val, size_validity;
tiledb_query_get_est_result_size_var_nullable(
    ctx, query, "a", &size_off, &size_val, &size_validity);

Parameters:

ctx – The TileDB context
query – The query.
name – The attribute name.
size_off – The size of the offsets (in bytes) to be retrieved.
size_val – The size of the values (in bytes) to be retrieved.
size_validity – The size of the validity values (in bytes) to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_get_fragment_num(tiledb_ctx_t *ctx, const tiledb_query_t *query, uint32_t *num)¶

Retrieves the number of written fragments. Applicable only to WRITE queries.

Example:

uint32_t num;
tiledb_query_get_fragment_num(ctx, query, &num);

Parameters:

ctx – The TileDB context
query – The query.
num – The number of written fragments to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_get_fragment_uri(tiledb_ctx_t *ctx, const tiledb_query_t *query, uint64_t idx, const char **uri)¶

Retrieves the URI of the written fragment with the input index. Applicable only to WRITE queries.

Example:

const char* uri;
tiledb_query_get_fragment_uri(
    ctx, query, 0, &uri);

Note

Make sure to make a copy of uri after its retrieval, as the constant pointer may be updated internally as new fragments are being written.

Parameters:

ctx – The TileDB context
query – The query.
idx – The index of the written fragment.
uri – The URI of the written fragment to be returned.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_get_fragment_timestamp_range(tiledb_ctx_t *ctx, const tiledb_query_t *query, uint64_t idx, uint64_t *t1, uint64_t *t2)¶

Retrieves the timestamp range of the written fragment with the input index. Applicable only to WRITE queries.

Example:

uint64_t t1, t2;
tiledb_query_get_fragment_timestamp_range(
    ctx, query, 0, &t1, &t2);

Parameters:

ctx – The TileDB context
query – The query.
idx – The index of the written fragment.
t1 – The start value of the timestamp range of the written fragment to be returned.
t2 – The end value of the timestamp range of the written fragment to be returned.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_set_subarray_t(tiledb_ctx_t *ctx, tiledb_query_t *query, const tiledb_subarray_t *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.

tiledb_subarray_t *subarray;
tiledb_subarray_alloc(ctx, array, &subarray);
uint64_t subarray_v[] = { 0, 10, 20, 30};
tiledb_subarray_set_subarray(ctx, subarray, subarray_v);
tiledb_query_set_subarray_t(ctx, query, subarray);

Note

This will error if the query is already initialized.

Note

This will error for writes to sparse arrays.

Parameters:

ctx – The TileDB context.
query – The TileDB query.
subarray – The subarray by which the array read/write will be constrained. For the case of writes, this is meaningful only for dense arrays.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

int32_t tiledb_query_get_subarray_t(tiledb_ctx_t *ctx, const tiledb_query_t *query, tiledb_subarray_t **subarray)¶

Return a TileDB subarray object from the given query.

Example:

tiledb_subarray_t* subarray;
tiledb_query_get_subarray_t(array, &subarray);

Parameters:

ctx – The TileDB context.
query – An open Query object.
subarray – The retrieved subarray object if available.

Returns:

TILEDB_OK for success or TILEDB_OOM or TILEDB_ERR for error.

Subarray¶

capi_return_t tiledb_subarray_alloc(tiledb_ctx_t *ctx, const tiledb_array_t *array, tiledb_subarray_t **subarray)¶

Allocates a TileDB subarray object.

Example:

tiledb_subarray_t* subarray;
tiledb_subarray_alloc(ctx, array, &subarray);

Note

The allocated subarray initially has internal coalesce_ranges == true.

Parameters:

ctx – [in] The TileDB context.
array – [in] An open array object.
subarray – [out] The subarray object to be created.

Returns:

TILEDB_OK for success or TILEDB_OOM or TILEDB_ERR for error.

capi_return_t tiledb_subarray_set_config(tiledb_ctx_t *ctx, tiledb_subarray_t *subarray, tiledb_config_t *config)¶

Set the subarray config.

Example:

tiledb_subarray_t* subarray;
tiledb_subarray_alloc(ctx, array, &subarray);
tiledb_config_t config;
tiledb_subarray_set_config(ctx, subarray, &config);

Note

This function only overrides config parameter sm.read_range_oob.

Parameters:

ctx – [in] The TileDB context.
subarray – [in] The subarray object to set the config on.
config – [in] The config to set on the subarray.

void tiledb_subarray_free(tiledb_subarray_t **subarray)¶

Frees a TileDB subarray object.

Example:

tiledb_subarray_t* subarray;
tiledb_array_open(ctx, array, TILEDB_READ);
tiledb_subarray_alloc(ctx, array, &subarray);
tiledb_array_close(ctx, array);
tiledb_subarray_free(&subarray);

Parameters:: subarray – [in] The subarray object to be freed.

capi_return_t tiledb_subarray_set_coalesce_ranges(tiledb_ctx_t *ctx, tiledb_subarray_t *subarray, int coalesce_ranges)¶

Sets coalesce_ranges property on a TileDB subarray object. Intended to be used just after tiledb_subarray_alloc() to replace the initial coalesce_ranges == true with coalesce_ranges = false if needed.

Example:

tiledb_subarray_t* subarray;
//tiledb_subarray_alloc internally defaults to 'coalesce_ranges == true'
tiledb_subarray_alloc(ctx, array, &subarray);
// so manually set to 'false' to match earlier behaviour with older
// tiledb_query_ subarray actions.
bool coalesce_ranges = false;
tiledb_subarray_set_coalesce_ranges(ctx, subarray, coalesce_ranges);

Parameters:

ctx – [in] The TileDB context.
subarray – [in] The subarray object to change.
coalesce_ranges – [in] The true/false value to be set

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_set_subarray(tiledb_ctx_t *ctx, tiledb_subarray_t *subarray, const void *subarray_v)¶

Populates a subarray with specific indicies.

Example:

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

tiledb_subarray_t *subarray;
uint64_t subarray_v[] = { 0, 10, 20, 30};
tiledb_subarray_set_subarray(ctx, subarray, subarray_v);

Parameters:

ctx – [in] The TileDB context.
subarray – [in] The TileDB subarray object.
subarray_v – [in] The subarray values which can be used to limit the subarray read/write. It should be a sequence of [low, high] pairs (one pair per dimension). When the subarray is used for writes, this is meaningful only for dense arrays, and specifically dense writes. Note that subarray_a must have the same type as the domain of the subarray’s associated array.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_add_range(tiledb_ctx_t *ctx, tiledb_subarray_t *subarray, uint32_t dim_idx, const void *start, const void *end, const void *stride)¶

Adds a 1D range along a subarray dimension index, which is in the form (start, end, stride). The datatype of the range components must be the same as the type of the domain of the array in the query.

Example:

uint32_t dim_idx = 2;
int64_t start = 10;
int64_t end = 20;
tiledb_subarray_add_range(ctx, subarray, dim_idx, &start, &end, nullptr);

Note

The stride is currently unsupported. Use 0/NULL/nullptr as the stride argument.

Parameters:

ctx – [in] The TileDB context.
subarray – [in] The subarray to add the range to.
dim_idx – [in] The index of the dimension to add the range to.
start – [in] The range start.
end – [in] The range end.
stride – [in] The range stride.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_add_range_by_name(tiledb_ctx_t *ctx, tiledb_subarray_t *subarray, const char *dim_name, const void *start, const void *end, const void *stride)¶

Adds a 1D range along a subarray dimension name, which is in the form (start, end, stride). The datatype of the range components must be the same as the type of the domain of the array in the query.

Example:

char* dim_name = "rows";
int64_t start = 10;
int64_t end = 20;
tiledb_subarray_add_range_by_name(
    ctx, subarray, dim_name, &start, &end, nullptr);

Note

The stride is currently unsupported. Use 0/NULL/nullptr as the stride argument.

Parameters:

ctx – [in] The TileDB context.
subarray – [in] The subarray to add the range to.
dim_name – [in] The name of the dimension to add the range to.
start – [in] The range start.
end – [in] The range end.
stride – [in] The range stride.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_add_range_var(tiledb_ctx_t *ctx, tiledb_subarray_t *subarray, uint32_t dim_idx, const void *start, uint64_t start_size, const void *end, uint64_t end_size)¶

Adds a 1D variable-sized range along a subarray dimension index, which is in the form (start, end). Applicable only to variable-sized dimensions.

Example:

uint32_t dim_idx = 2;
char start[] = "a";
char end[] = "bb";
tiledb_subarray_add_range_var(ctx, subarray, dim_idx, start, 1, end, 2);

Parameters:

ctx – [in] The TileDB context.
subarray – [in] The subarray to add the range to.
dim_idx – [in] The index of the dimension to add the range to.
start – [in] The range start.
start_size – [in] The size of the range start in bytes.
end – [in] The range end.
end_size – [in] The size of the range end in bytes.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_add_range_var_by_name(tiledb_ctx_t *ctx, tiledb_subarray_t *subarray, const char *dim_name, const void *start, uint64_t start_size, const void *end, uint64_t end_size)¶

Adds a 1D variable-sized range along a subarray dimension name, which is in the form (start, end). Applicable only to variable-sized dimensions.

Example:

char* dim_name = "rows";
char start[] = "a";
char end[] = "bb";
tiledb_subarray_add_range_var_by_name(
    ctx, subarray, dim_name, start, 1, end, 2);

Parameters:

ctx – [in] The TileDB context.
subarray – [in] The subarray to add the range to.
dim_name – [in] The name of the dimension to add the range to.
start – [in] The range start.
start_size – [in] The size of the range start in bytes.
end – [in] The range end.
end_size – [in] The size of the range end in bytes.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_get_range_num(tiledb_ctx_t *ctx, const tiledb_subarray_t *subarray, uint32_t dim_idx, uint64_t *range_num)¶

Retrieves the number of ranges of the query subarray along a given dimension index.

Example:

uint64_t range_num;
tiledb_subarray_get_range_num(ctx, subarray, dim_idx, &range_num);

Parameters:

ctx – [in] The TileDB context
subarray – [in] The subarray.
dim_idx – [in] The index of the dimension for which to retrieve number of ranges.
range_num – [out] The retrieved number of ranges.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_get_range_num_from_name(tiledb_ctx_t *ctx, const tiledb_subarray_t *subarray, const char *dim_name, uint64_t *range_num)¶

Retrieve the number of ranges of the subarray along a given dimension name.

Example:

uint64_t range_num;
tiledb_subarray_get_range_num_from_name(ctx, subarray, dim_name, &range_num);

Parameters:

ctx – [in] The TileDB context
subarray – [in] The subarray.
dim_name – [in] The name of the dimension whose range number to retrieve.
range_num – [out] The retrieved number of ranges.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_get_range(tiledb_ctx_t *ctx, const tiledb_subarray_t *subarray, uint32_t dim_idx, uint64_t range_idx, const void **start, const void **end, const void **stride)¶

Retrieves a specific range of the subarray along a given dimension index.

Example:

const void* start;
const void* end;
const void* stride;
tiledb_subarray_get_range(
    ctx, subarray, dim_idx, range_idx, &start, &end, &stride);

Parameters:

ctx – [in] The TileDB context
subarray – [in] The subarray.
dim_idx – [in] The index of the dimension to retrieve the range from.
range_idx – [in] The index of the range to retrieve.
start – [out] The retrieved range start.
end – [out] The received range end.
stride – [out] The retrieved range stride.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_get_range_from_name(tiledb_ctx_t *ctx, const tiledb_subarray_t *subarray, const char *dim_name, uint64_t range_idx, const void **start, const void **end, const void **stride)¶

Retrieves a specific range of the subarray along a given dimension name.

Example:

const void* start;
const void* end;
const void* stride;
tiledb_subarray_get_range_from_name(
    ctx, query, dim_name, range_idx, &start, &end, &stride);

Parameters:

ctx – [in] The TileDB context
subarray – [in] The subarray.
dim_name – [in] The name of the dimension to retrieve the range from.
range_idx – [in] The index of the range to retrieve.
start – [out] The retrieved range start.
end – [out] The retrieved range end.
stride – [out] The retrieved range stride.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_get_range_var_size(tiledb_ctx_t *ctx, const tiledb_subarray_t *subarray, uint32_t dim_idx, uint64_t range_idx, uint64_t *start_size, uint64_t *end_size)¶

Retrieves a range’s start and end size for a given variable-length dimension index at a given range index.

Example:

uint64_t start_size;
uint64_t end_size;
tiledb_subarray_get_range_var_size(
    ctx, subarray, dim_idx, range_idx, &start_size, &end_size);

Parameters:

ctx – [in] The TileDB context
subarray – [in] The subarray.
dim_idx – [in] The index of the dimension to retrieve the range from.
range_idx – [in] The index of the range to retrieve.
start_size – [out] The retrieved range start size in bytes
end_size – [out] The retrieved range end size in bytes

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_get_range_var_size_from_name(tiledb_ctx_t *ctx, const tiledb_subarray_t *subarray, const char *dim_name, uint64_t range_idx, uint64_t *start_size, uint64_t *end_size)¶

Retrieves a range’s start and end size for a given variable-length dimension name at a given range index.

Example:

uint64_t start_size;
uint64_t end_size;
tiledb_subarray_get_range_var_size_from_name(
    ctx, subarray, dim_name, range_idx, &start_size, &end_size);

Parameters:

ctx – [in] The TileDB context
subarray – [in] The subarray.
dim_name – [in] The name of the dimension to retrieve the range from.
range_idx – [in] The index of the range to retrieve.
start_size – [out] The retrieved range start size in bytes
end_size – [out] The retrieved range end size in bytes

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_get_range_var(tiledb_ctx_t *ctx, const tiledb_subarray_t *subarray, uint32_t dim_idx, uint64_t range_idx, void *start, void *end)¶

Retrieves a specific range of the subarray along a given variable-length dimension index.

Example:

const void* start;
const void* end;
tiledb_subarray_get_range_var(
    ctx, subarray, dim_idx, range_idx, &start, &end);

Parameters:

ctx – [in] The TileDB context
subarray – [in] The subarray.
dim_idx – [in] The index of the dimension to retrieve the range from.
range_idx – [in] The index of the range to retrieve.
start – [out] The retrieved range start.
end – [out] The retrieved range end.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_subarray_get_range_var_from_name(tiledb_ctx_t *ctx, const tiledb_subarray_t *subarray, const char *dim_name, uint64_t range_idx, void *start, void *end)¶

Retrieves a specific range of the subarray along a given variable-length dimension name.

Example:

const void* start;
const void* end;
tiledb_subarray_get_range_var_from_name(
    ctx, subarray, dim_name, range_idx, &start, &end);

Parameters:

ctx – [in] The TileDB context
subarray – [in] The subarray.
dim_name – [in] The name of the dimension to retrieve the range from.
range_idx – [in] The index of the range to retrieve.
start – [out] The retrieved range start.
end – [out] The retrieved range end.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

Query Condition¶

int32_t tiledb_query_condition_alloc(tiledb_ctx_t *ctx, tiledb_query_condition_t **cond)¶

Allocates a TileDB query condition object.

Example:

tiledb_query_condition_t* query_condition;
tiledb_query_condition_alloc(ctx, &query_condition);

Parameters:

ctx – The TileDB context.
cond – The allocated query condition object.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

void tiledb_query_condition_free(tiledb_query_condition_t **cond)¶

Frees a TileDB query condition object.

Example:

uint32_t value = 5;
tiledb_query_condition_t* query_condition;
tiledb_query_condition_alloc(
  ctx, "longitude", &value, sizeof(value), TILEDB_LT, &query_condition);
tiledb_query_set_condition(ctx, query, query_condition);
tiledb_query_submit(ctx, query);
tiledb_query_condition_free(&query_condition);

Parameters:

cond – The query condition object to be freed.

int32_t tiledb_query_condition_init(tiledb_ctx_t *ctx, tiledb_query_condition_t *cond, const char *attribute_name, const void *condition_value, uint64_t condition_value_size, tiledb_query_condition_op_t op)¶

Initializes a TileDB query condition object.

Example:

tiledb_query_condition_t* query_condition;
tiledb_query_condition_alloc(ctx, &query_condition);

uint32_t value = 5;
tiledb_query_condition_init(
  ctx, query_condition, "longitude", &value, sizeof(value), TILEDB_LT);

Parameters:

ctx – The TileDB context.
cond – The allocated query condition object.
attribute_name – The attribute name.
condition_value – The value to compare against an attribute value.
condition_value_size – The byte size of condition_value.
op – The comparison operator.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_query_condition_combine(tiledb_ctx_t *ctx, const tiledb_query_condition_t *left_cond, const tiledb_query_condition_t *right_cond, tiledb_query_condition_combination_op_t combination_op, tiledb_query_condition_t **combined_cond)¶

Combines two query condition objects into a newly allocated condition. Does not mutate or free the input condition objects.

Example:

tiledb_query_condition_t* query_condition_1;
tiledb_query_condition_alloc(ctx, &query_condition_1);
uint32_t value_1 = 5;
tiledb_query_condition_init(
  ctx,
  query_condition_1,
  "longitude",
  &value_1,
  sizeof(value_1),
  TILEDB_LT);

tiledb_query_condition_t* query_condition_2;
tiledb_query_condition_alloc(ctx, &query_condition_2);
uint32_t value_2 = 20;
tiledb_query_condition_init(
  ctx,
  query_condition_2,
  "latitude",
  &value_2,
  sizeof(value_2),
  TILEDB_GE);

tiledb_query_condition_t* query_condition_3;
tiledb_query_condition_combine(
  ctx, query_condition_1, query_condition_2, TILEDB_AND, &query_condition_3);

tiledb_query_condition_free(&query_condition_1);
tiledb_query_condition_free(&query_condition_2);

tiledb_query_set_condition(ctx, query, query_condition_3);
tiledb_query_submit(ctx, query);
tiledb_query_condition_free(&query_condition_3);

Parameters:

ctx – [in] The TileDB context.
left_cond – [in] The first input condition.
right_cond – [in] The second input condition.
combination_op – [in] The combination operation.
combined_cond – [out] The output condition holder.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

Filter¶

capi_return_t tiledb_filter_alloc(tiledb_ctx_t *ctx, tiledb_filter_type_t type, tiledb_filter_t **filter)¶

Creates a TileDB filter.

The filter returned has independent lifespan. It will be available until tiledb_filter_free is called on it.

Example:

tiledb_filter_t* filter;
tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter);

Parameters:

ctx – [in] The TileDB context.
type – [in] The filter type.
filter – [out] The TileDB filter to be created.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

void tiledb_filter_free(tiledb_filter_t **filter)¶

Destroys a TileDB filter, freeing associated memory.

This function must be called on every filter returned from the API, whether they have independent or subordinate lifespans.

Example:

tiledb_filter_t* filter;
tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter);
tiledb_filter_free(&filter);

Parameters:: filter – [inout] The filter to be destroyed.

capi_return_t tiledb_filter_get_type(tiledb_ctx_t *ctx, tiledb_filter_t *filter, tiledb_filter_type_t *type)¶

Retrieves the type of a filter.

Example:

tiledb_filter_t* filter;
tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter);
tiledb_filter_type_t type;
tiledb_filter_get_type(ctx, filter, &type);
// type == TILEDB_FILTER_BZIP2

Parameters:

ctx – [in] The TileDB context.
filter – [in] The TileDB filter.
type – [out] The filter type to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

capi_return_t tiledb_filter_set_option(tiledb_ctx_t *ctx, tiledb_filter_t *filter, tiledb_filter_option_t option, const void *value)¶

Sets an option on a filter. Options are filter dependent; this function returns an error if the given option is not valid for the given filter.

Example:

tiledb_filter_t* filter;
tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter);
int32_t level = 5;
tiledb_filter_set_option(ctx, filter, TILEDB_COMPRESSION_LEVEL, &level);
tiledb_filter_free(&filter);

Parameters:

ctx – [in] TileDB context.
filter – [in] The target filter.
option – [in] Filter option to set.
value – [out] Value of option to set.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_filter_get_option(tiledb_ctx_t *ctx, tiledb_filter_t *filter, tiledb_filter_option_t option, void *value)¶

Gets an option value from a filter. Options are filter dependent; this function returns an error if the given option is not valid for the given filter.

Example:

tiledb_filter_t* filter;
tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter);
int32_t level;
tiledb_filter_get_option(ctx, filter, TILEDB_COMPRESSION_LEVEL, &level);
// level == -1 (the default)
tiledb_filter_free(&filter);

Note

The buffer pointed to by value must be large enough to hold the option value.

Parameters:

ctx – [in] TileDB context.
filter – [in] The target filter.
option – [in] Filter option to get.
value – [out] Buffer that option value will be written to.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

Group¶

capi_return_t tiledb_group_create(tiledb_ctx_t *ctx, const char *group_uri)¶

Creates a new TileDB group.

Example:

tiledb_group_create(ctx, "my_group");

Parameters:

ctx – The TileDB context.
group_uri – The group URI.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_group_dump_str(tiledb_ctx_t *ctx, tiledb_group_t *group, char **dump_ascii, const uint8_t recursive)¶

Dump a string representation of a group.

Deprecated, use tiledb_group_dump_str_v2 instead.

Parameters:

ctx – The TileDB context.
group – The group.
dump_ascii – The output string. The caller takes ownership of the c-string.
recursive – True if the dump should recurse into subgroups.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Buffer¶

capi_return_t tiledb_buffer_alloc(tiledb_ctx_t *ctx, tiledb_buffer_t **buffer)¶

Creates an empty buffer object.

Example:

tiledb_buffer_t* buffer;
tiledb_buffer_alloc(ctx, &buffer);

Parameters:

ctx – TileDB context
buffer – The buffer to be created

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

void tiledb_buffer_free(tiledb_buffer_t **buffer)¶

Destroys a TileDB buffer, freeing associated memory.

Example:

tiledb_buffer_t* buffer;
tiledb_buffer_alloc(ctx, &buffer);
tiledb_buffer_free(&buffer);

Parameters:: buffer – The buffer to be destroyed.

capi_return_t tiledb_buffer_get_type(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, tiledb_datatype_t *datatype)¶

Gets the datatype from the given buffer.

Example:

tiledb_datatype_t type;
tiledb_buffer_get_type(ctx, buffer, &type);

Parameters:

ctx – TileDB context
buffer – TileDB buffer instance
datatype – Set to the datatype of the buffer.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_buffer_set_type(tiledb_ctx_t *ctx, tiledb_buffer_t *buffer, tiledb_datatype_t datatype)¶

Sets a datatype for the given buffer. The default datatype is TILEDB_UINT8.

Example:

tiledb_buffer_t* buffer;
tiledb_buffer_alloc(ctx, &buffer);
tiledb_buffer_set_type(ctx, buffer, TILEDB_INT32);

Parameters:

ctx – TileDB context
buffer – TileDB buffer instance
datatype – The datatype to set on the buffer.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_buffer_get_data(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, void **data, uint64_t *num_bytes)¶

Gets a pointer to the current allocation and the current number of bytes in the specified buffer object.

Example:

tiledb_buffer_t* buffer;
tiledb_buffer_alloc(ctx, &buffer);
void* data;
uint64_t num_bytes;
tiledb_buffer_get_data(ctx, buffer, &data, num_bytes);
// data == NULL and num_bytes == 0 because the buffer is currently empty.
tiledb_buffer_free(&buffer);

Note

For string buffers allocated by TileDB, the number of bytes includes the terminating NULL byte.

Parameters:

ctx – TileDB context
buffer – TileDB buffer instance
data – The pointer to the data to be retrieved.
num_bytes – Set to the number of bytes in the buffer.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_buffer_set_data(tiledb_ctx_t *ctx, tiledb_buffer_t *buffer, void *data, uint64_t size)¶

Sets (wraps) a pre-allocated region of memory with the given buffer object. This does not perform a copy.

Example:

tiledb_buffer_t* buffer;
tiledb_buffer_alloc(ctx, &buffer);

void* my_data = malloc(100);
tiledb_buffer_set_data(ctx, buffer, my_data, 100);

void* data;
uint64_t num_bytes;
tiledb_buffer_get_data(ctx, buffer, &data, num_bytes);
assert(data == my_data);
assert(num_bytes == 100);

tiledb_buffer_free(&buffer);
free(my_data);

Note

The TileDB buffer object does not take ownership of the allocation set with this function. That means the call to tiledb_buffer_free will not free a user allocation set via tiledb_buffer_set_buffer.

Parameters:

ctx – TileDB context
buffer – TileDB buffer instance
data – Pre-allocated region of memory to wrap with this buffer.
size – Size (in bytes) of the region pointed to by data.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

BufferList¶

capi_return_t tiledb_buffer_list_alloc(tiledb_ctx_t *ctx, tiledb_buffer_list_t **buffer_list)¶

Creates an empty buffer list object.

Example:

tiledb_buffer_list_t* buffer_list;
tiledb_buffer_list_alloc(ctx, &buffer_list);

Parameters:

ctx – TileDB context
buffer_list – The buffer list to be created

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

void tiledb_buffer_list_free(tiledb_buffer_list_t **buffer_list)¶

Destroys a TileDB buffer list, freeing associated memory.

Example:

tiledb_buffer_t* buffer_list;
tiledb_buffer_list_alloc(ctx, &buffer_list);
tiledb_buffer_list_free(&buffer_list);

Parameters:: buffer_list – The buffer list to be destroyed.

capi_return_t tiledb_buffer_list_get_num_buffers(tiledb_ctx_t *ctx, const tiledb_buffer_list_t *buffer_list, uint64_t *num_buffers)¶

Gets the number of buffers in the buffer list.

Example:

tiledb_buffer_list_t* buffer_list;
tiledb_buffer_list_alloc(ctx, &buffer_list);
uint64_t num_buffers;
tiledb_buffer_list_get_num_buffers(ctx, buffer_list, &num_buffers);
// num_buffers == 0 because the list is empty.

Parameters:

ctx – TileDB context.
buffer_list – The buffer list.
num_buffers – Set to the number of buffers in the buffer list.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_buffer_list_get_total_size(tiledb_ctx_t *ctx, const tiledb_buffer_list_t *buffer_list, uint64_t *total_size)¶

Gets the total number of bytes in the buffers in the buffer list.

Example:

tiledb_buffer_list_t* buffer_list;
tiledb_buffer_list_alloc(ctx, &buffer_list);
uint64_t total_size;
tiledb_buffer_list_get_total_size(ctx, buffer_list, &total_size);
// total_size == 0 because the list is empty.

Parameters:

ctx – TileDB context.
buffer_list – The buffer list.
total_size – Set to the total number of bytes in the buffers in the buffer list.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_buffer_list_get_buffer(tiledb_ctx_t *ctx, const tiledb_buffer_list_t *buffer_list, uint64_t buffer_idx, tiledb_buffer_t **buffer)¶

Gets the buffer at the given index in the buffer list. The returned buffer object is simply a pointer to memory managed by the underlying buffer list, meaning this function does not perform a copy.

It is the caller’s responsibility to free the returned buffer with tiledb_buffer_free. Since the returned buffer object does not “own” the underlying allocation, the underlying allocation is not freed when freeing it with tiledb_buffer_free.

Example:

tiledb_buffer_list_t* buffer_list;
// Create and populate the buffer_list

// Get the buffer at index 0.
tiledb_buffer_t *buff0;
tiledb_buffer_list_get_buffer(ctx, buffer_list, 0, &buff0);

// Always free the returned buffer object
tiledb_buffer_free(&buff0);
tiledb_buffer_list_free(&buffer_list);

Parameters:

ctx – TileDB context.
buffer_list – The buffer list.
buffer_idx – Index of buffer to get from the buffer list.
buffer – Set to a newly allocated buffer object pointing to the underlying allocation in the buffer list corresponding to the buffer.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

capi_return_t tiledb_buffer_list_flatten(tiledb_ctx_t *ctx, tiledb_buffer_list_t *buffer_list, tiledb_buffer_t **buffer)¶

Copies and concatenates all the data in the buffer list into a new buffer.

Example:

tiledb_buffer_t* buff;
tiledb_buffer_list_flatten(ctx, buffer_list, &buff);
// ...
tiledb_buffer_free(&buff);

Parameters:

ctx – TileDB context.
buffer_list – The buffer list.
buffer – Will be set to a newly allocated buffer holding a copy of the concatenated data from the buffer list.

Returns:

TILEDB_OK for success or TILEDB_ERR for error.

Object Management¶

int32_t 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);

Parameters:

ctx – The TileDB context.
path – The URI path to the TileDB resource.
type – The type to be retrieved.

Returns:

TILEDB_OK on success, TILEDB_ERR on error.

int32_t 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");

Parameters:

ctx – The TileDB context.
path – The URI path to the tiledb resource.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t 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");

Parameters:

ctx – The TileDB context.
old_path – The old TileDB directory.
new_path – The new TileDB directory.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_object_walk(tiledb_ctx_t *ctx, const char *path, tiledb_walk_order_t order, int32_t (*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);

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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_object_ls(tiledb_ctx_t *ctx, const char *path, int32_t (*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);

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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

VFS¶

capi_return_t 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);

Parameters:

ctx – [in] The TileDB context.
config – [in] Configuration parameters.
vfs – [out] The virtual filesystem object to be created.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

void tiledb_vfs_free(tiledb_vfs_t **vfs)¶

Frees a virtual filesystem object.

Example:

tiledb_vfs_free(&vfs);

Parameters:: vfs – [inout] The virtual filesystem object to be freed.

capi_return_t 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

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The VFS object.
config – [out] The config to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

capi_return_t 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");

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the bucket to be created.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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");

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the bucket to be deleted.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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");

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the bucket to be emptied.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_vfs_is_empty_bucket(tiledb_ctx_t *ctx, tiledb_vfs_t *vfs, const char *uri, int32_t *is_empty)¶

Checks if an object-store bucket is empty.

Example:

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

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the bucket.
is_empty – [out] Sets it to 1 if the input bucket is empty, and 0 otherwise.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_vfs_is_bucket(tiledb_ctx_t *ctx, tiledb_vfs_t *vfs, const char *uri, int32_t *is_bucket)¶

Checks if an object-store bucket exists.

Example:

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

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the bucket.
is_bucket – [out] Sets it to 1 if the input URI is a bucket, and 0 otherwise.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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, "s3://my_bucket/my_dir");

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the directory to be created.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_vfs_is_dir(tiledb_ctx_t *ctx, tiledb_vfs_t *vfs, const char *uri, int32_t *is_dir)¶

Checks if a directory exists.

Example:

int32_t exists;
tiledb_vfs_is_dir(ctx, vfs, "s3://my_bucket/my_dir", &exists);

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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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, "s3://my_bucket/my_dir");

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The uri of the directory to be removed

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_vfs_is_file(tiledb_ctx_t *ctx, tiledb_vfs_t *vfs, const char *uri, int32_t *is_file)¶

Checks if a file exists.

Example:

int32_t exists;
tiledb_vfs_is_file(ctx, vfs, "s3://my_bucket/my_file", &is_file);

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the file.
is_file – [out] Sets it to 1 if the file exists and 0 otherwise.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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, "s3://my_bucket/my_file");

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the file.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_vfs_dir_size(tiledb_ctx_t *ctx, tiledb_vfs_t *vfs, const char *uri, uint64_t *size)¶

Retrieves the size of a directory. This function is recursive, i.e., it will consider all files in the directory tree rooted at uri.

Example:

uint64_t dir_size;
tiledb_vfs_dir_size(ctx, vfs, "s3://my_bucket/my_dir", &dir_size);

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the directory.
size – [out] The directory size to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_vfs_ls(tiledb_ctx_t *ctx, tiledb_vfs_t *vfs, const char *path, int32_t (*callback)(const char*, void*), void *data)¶

The function visits only the children of path (i.e., it does not recursively continue to the children directories) and applies the callback function using the input data.

Example:

tiledb_vfs_ls(ctx, vfs, "my_dir", NULL, NULL);

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
path – [in] The path in which the traversal will occur.
callback – [inout] 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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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, "s3://my_bucket/my_file", &file_size);

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the file.
size – [out] The file size to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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, "s3://my_bucket/my_dir",
"s3://new_bucket/new_dir");

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
old_uri – [in] The old URI.
new_uri – [in] The new URI.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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, "s3://my_bucket/my_file", "s3://new_bucket/new_file");

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
old_uri – [in] The old URI.
new_uri – [in] The new URI.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_vfs_copy_dir(tiledb_ctx_t *ctx, tiledb_vfs_t *vfs, const char *old_uri, const char *new_uri)¶

Copies a directory. If the destination directory exists, it will be overwritten.

Example:

tiledb_vfs_copy_dir(
 ctx, vfs, "s3://my_bucket/my_dir", "s3://new_bucket/new_dir");

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
old_uri – [in] The old URI.
new_uri – [in] The new URI.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_vfs_copy_file(tiledb_ctx_t *ctx, tiledb_vfs_t *vfs, const char *old_uri, const char *new_uri)¶

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

Example:

tiledb_vfs_copy_file(
ctx, vfs, "s3://my_bucket/my_file", "s3://new_bucket/new_file");

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
old_uri – [in] The old URI.
new_uri – [in] The new URI.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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

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 – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the file.
mode – [in] 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 – [out] The file handle that is created. This will be used in tiledb_vfs_read, tiledb_vfs_write and tiledb_vfs_sync.

Returns:

TILEDB_OK for success and TILEDB_ERR or TILEDB_OOM for error.

capi_return_t 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);

Parameters:

ctx – [in] The TileDB context.
fh – [in] The file handle.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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);

Parameters:

ctx – [in] The TileDB context.
fh – [in] The URI file handle.
offset – [in] The offset in the file where the read begins.
buffer – [out] The buffer to read into.
nbytes – [in] Number of bytes to read.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t 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));

Parameters:

ctx – [in] The TileDB context.
fh – [in] The URI file handle.
buffer – [in] The buffer to write from.
nbytes – [in] Number of bytes to write.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_vfs_sync(tiledb_ctx_t *ctx, tiledb_vfs_fh_t *fh)¶

Syncs (flushes) a file.

Example:

tiledb_vfs_sync(ctx, fh);

Note

This has no effect for S3.

Parameters:

ctx – [in] The TileDB context.
fh – [in] The URI file handle.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

void tiledb_vfs_fh_free(tiledb_vfs_fh_t **fh)¶

Frees a file handle.

Example:

tiledb_vfs_fh_free(&fh);

Parameters:: fh – [inout] The URI file handle.

capi_return_t tiledb_vfs_fh_is_closed(tiledb_ctx_t *ctx, tiledb_vfs_fh_t *fh, int32_t *is_closed)¶

Checks if a file handle is closed.

Example:

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

Parameters:

ctx – [in] The TileDB context.
fh – [in] The URI file handle.
is_closed – [out] Set to 1 if the file handle is closed, and 0 otherwise.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

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

Touches a file, i.e., creates a new empty file if it does not already exist.

The access timestamps of the file are not guaranteed to change.

Example:

tiledb_vfs_touch(ctx, vfs, "my_empty_file");

Parameters:

ctx – [in] The TileDB context.
vfs – [in] The virtual filesystem object.
uri – [in] The URI of the file to be created.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

URI¶

int32_t tiledb_uri_to_path(tiledb_ctx_t *ctx, const char *uri, char *path_out, uint32_t *path_length)¶

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

Example:

char path[TILEDB_MAX_PATH];
uint32_t length = TILEDB_MAX_PATH; // Must be set to non-zero
tiledb_uri_to_path(ctx, "file:///my_array", path, &length);
// This will set "my_array" to `path`

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.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Version¶

void tiledb_version(int32_t *major, int32_t *minor, int32_t *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¶

int32_t tiledb_stats_enable(void)¶

Enable internal statistics gathering.

Returns:: TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_stats_disable(void)¶

Disable internal statistics gathering.

Returns:: TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_stats_reset(void)¶

Reset all internal statistics counters to 0.

Returns:: TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_stats_dump(FILE *out)¶

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

Parameters:

out – The output.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_stats_dump_str(char **out)¶

Dump all internal statistics counters to an output string. The caller is responsible for freeing the resulting string.

Example:

char *stats_str;
tiledb_stats_dump_str(&stats_str);
// ...
tiledb_stats_free_str(&stats_str);

Parameters:

out – Will be set to point to an allocated string containing the stats.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_stats_raw_dump(FILE *out)¶

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

Parameters:

out – The output.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_stats_raw_dump_str(char **out)¶

Dump all raw internal statistics counters to a JSON-formatted output string. The caller is responsible for freeing the resulting string.

Example:

char *stats_str;
tiledb_stats_raw_dump_str(&stats_str);
// ...
tiledb_stats_raw_free_str(&stats_str);

Parameters:

out – Will be set to point to an allocated string containing the stats.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

int32_t tiledb_stats_free_str(char **out)¶

Free the memory associated with a previously dumped stats string.

Parameters:

out – Pointer to a previously allocated stats string.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Heap Profiler¶

int32_t tiledb_heap_profiler_enable(const char *file_name_prefix, uint64_t dump_interval_ms, uint64_t dump_interval_bytes, uint64_t dump_threshold_bytes)¶

Enable heap profiling.

Parameters:

file_name_prefix – If empty or null, stats are dumped to stdout. If non-empty, this specifies the file_name prefix to write to. For example, value “tiledb_mem_stats” will write to “tiledb_mem_stats__1611170501”, where the postfix is determined by the current epoch.
dump_interval_ms – If non-zero, this spawns a dedicated thread to dump on this time interval.
dump_interval_bytes – If non-zero, a dump will occur when the total number of lifetime allocated bytes is increased by more than this amount.
dump_threshold_bytes – If non-zero, labeled allocations with a number of bytes lower than this threshold will not be reported in the dump.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Fragment Info¶

capi_return_t tiledb_fragment_info_alloc(tiledb_ctx_t *ctx, const char *array_uri, tiledb_fragment_info_t **fragment_info)¶

Creates a fragment info object for a given array, and fetches all the fragment information for that array.

Example:

tiledb_fragment_info* fragment_info;
tiledb_fragment_info_alloc(ctx, "array_uri", &fragment_info);

Parameters:

ctx – [in] The TileDB context.
array_uri – [in] The array URI.
fragment_info – [out] The fragment info object to be created.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

void tiledb_fragment_info_free(tiledb_fragment_info_t **fragment_info)¶

Frees a fragment info object.

Example:

tiledb_fragment_info_free(&fragment_info);

Parameters:: fragment_info – [in] The fragment info object to be freed.

capi_return_t tiledb_fragment_info_set_config(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, tiledb_config_t *config)¶

Set the fragment info config. Useful for passing timestamp ranges and encryption key via the config before loading the fragment info.

Example:

tiledb_fragment_info* fragment_info;
tiledb_fragment_info_alloc(ctx, "array_uri", &fragment_info);

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

tiledb_fragment_info_load(ctx, fragment_info);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
config – [in] The config to be set.

capi_return_t tiledb_fragment_info_get_config(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, tiledb_config_t **config)¶

Retrieves the config from fragment info.

Example:

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

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
config – [out] The config to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_load(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info)¶

Loads the fragment info.

Example:

tiledb_fragment_info_load(ctx, fragment_info);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_fragment_name_v2(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, tiledb_string_t **name)¶

Gets the name of a fragment.

Example:

tiledb_string_t* name;
tiledb_fragment_info_get_fragment_name_v2(ctx, fragment_info, 1, &name);
// Remember to free the string using tiledb_string_free when done with it.

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
name – [out] A pointer to a tiledb_string_t* that will hold the fragment’s name.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_fragment_num(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t *fragment_num)¶

Gets the number of fragments.

Example:

uint32_t fragment_num;
tiledb_fragment_info_get_fragment_num(ctx, fragment_info, &fragment_num);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
fragment_num – [out] The number of fragments to retrieve.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_fragment_uri(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, const char **uri)¶

Gets a fragment URI.

Example:

const char* uri;
tiledb_fragment_info_get_fragment_uri(ctx, fragment_info, 1, &uri);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
uri – [out] The fragment URI to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_fragment_size(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint64_t *size)¶

Gets the fragment size in bytes.

Example:

uint64_t size;
tiledb_fragment_info_get_fragment_size(ctx, fragment_info, 1, &size);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
size – [out] The fragment size to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_dense(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, int32_t *dense)¶

Checks if a fragment is dense.

Example:

int32_t dense;
tiledb_fragment_info_get_dense(ctx, fragment_info, 1, &dense);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
dense – [out] 1 if the fragment is dense.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_sparse(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, int32_t *sparse)¶

Checks if a fragment is sparse.

Example:

int32_t sparse;
tiledb_fragment_info_get_sparse(ctx, fragment_info, 1, &sparse);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
sparse – [out] 1 if the fragment is sparse.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_timestamp_range(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint64_t *start, uint64_t *end)¶

Gets the timestamp range of a fragment.

Example:

uint64_t start, end;
tiledb_fragment_info_get_timestamp_range(
    ctx, fragment_info, 1, &start, &end);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
start – [out] The start of the timestamp range to be retrieved.
end – [out] The end of the timestamp range to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_non_empty_domain_from_index(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint32_t did, void *domain)¶

Retrieves the non-empty domain from a given fragment for a given dimension index.

Example:

uint64_t domain[2];
tiledb_fragment_info_get_non_empty_domain_from_index(
    ctx, fragment_info, 0, 0, domain);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
did – [in] The dimension index, following the order as it was defined in the domain of the array schema.
domain – [out] The domain to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_non_empty_domain_from_name(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, const char *dim_name, void *domain)¶

Retrieves the non-empty domain from a given fragment for a given dimension name.

Example:

uint64_t domain[2];
tiledb_fragment_info_get_non_empty_domain_from_name(
    ctx, fragment_info, 0, "d1", domain);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
dim_name – [in] The dimension name.
domain – [out] The domain to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_non_empty_domain_var_size_from_index(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint32_t did, uint64_t *start_size, uint64_t *end_size)¶

Retrieves the non-empty domain range sizes from a fragment for a given dimension index. Applicable to var-sized dimensions.

Example:

uint64_t start_size, end_size;
tiledb_fragment_info_get_non_empty_domain_var_size_from_index(
    ctx, fragment_info, 0, &start_size, &end_size);
// If non-empty domain range is `[aa, dddd]`,
// then `start_size = 2`, and `end_size = 4`.

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment information object.
fid – [in] The fragment index.
did – [in] The dimension index, following the order as it was defined in the domain of the array schema.
start_size – [out] The size in bytes of the start range.
end_size – [out] The size in bytes of the end range.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_non_empty_domain_var_size_from_name(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, const char *dim_name, uint64_t *start_size, uint64_t *end_size)¶

Retrieves the non-empty domain range sizes from a fragment for a given dimension name. Applicable to var-sized dimensions.

Example:

uint64_t start_size, end_size;
tiledb_fragment_info_get_non_empty_domain_var_size_from_name(
    ctx, fragment_info, "d", &start_size, &end_size);
// If non-empty domain range is `[aa, dddd]`,
// then `start_size = 2`, and `end_size = 4`.

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment information object.
fid – [in] The fragment index.
dim_name – [in] The dimension name.
start_size – [out] The size in bytes of the start range.
end_size – [out] The size in bytes of the end range.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_non_empty_domain_var_from_index(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint32_t did, void *start, void *end)¶

Retrieves the non-empty domain from a fragment for a given dimension index. Applicable to var-sized dimensions.

Example:

// Get range sizes first
uint64_t start_size, end_size;
tiledb_fragment_info_get_non_empty_domain_var_size_from_index(
    ctx, fragment_info, 0, 0, &start_size, &end_size);

// Get domain
char start[start_size];
char end[end_size];
tiledb_fragment_info_get_non_empty_domain_var_from_index(
    ctx, fragment_info, 0, 0, start, end);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The fragment index.
did – [in] The dimension index, following the order as it was defined in the domain of the array schema.
start – [out] The domain range start to set.
end – [out] The domain range end to set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_non_empty_domain_var_from_name(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, const char *dim_name, void *start, void *end)¶

Retrieves the non-empty domain from a fragment for a given dimension name. Applicable to var-sized dimensions.

Example:

// Get range sizes first
uint64_t start_size, end_size;
tiledb_fragment_info_get_non_empty_domain_var_size_from_name(
    ctx, fragment_info, 0, "d", &start_size, &end_size);

// Get domain
char start[start_size];
char end[end_size];
tiledb_fragment_info_get_non_empty_domain_var_from_name(
    ctx, fragment_info, 0, "d", start, end);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The fragment index.
dim_name – [in] The dimension name.
start – [out] The domain range start to set.
end – [out] The domain range end to set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_mbr_num(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint64_t *mbr_num)¶

Retrieves the number of MBRs from the fragment. In the case of sparse fragments, this is the number of physical tiles. Dense fragments do not contain MBRs.

Example:

uint64_t mbr_num;
tiledb_fragment_info_get_mbr_num(ctx, fragment_info, 0, &mbr_num);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
mbr_num – [out] The number of MBRs to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_mbr_from_index(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint32_t mid, uint32_t did, void *mbr)¶

Retrieves the MBR from a given fragment for a given dimension index.

Example:

uint64_t mbr[2];
tiledb_fragment_info_get_mbr_from_index(ctx, fragment_info, 0, 0, 0, mbr);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
mid – [in] The mbr of the fragment of interest.
did – [in] The dimension index, following the order as it was defined in the domain of the array schema.
mbr – [out] The mbr to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_mbr_from_name(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint32_t mid, const char *dim_name, void *mbr)¶

Retrieves the MBR from a given fragment for a given dimension name.

Example:

uint64_t mbr[2];
tiledb_fragment_info_get_mbr_from_name(ctx, fragment_info, 0, 0, "d1", mbr);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
mid – [in] The mbr of the fragment of interest.
dim_name – [in] The dimension name.
mbr – [out] The mbr to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_mbr_var_size_from_index(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint32_t mid, uint32_t did, uint64_t *start_size, uint64_t *end_size)¶

Retrieves the MBR sizes from a fragment for a given dimension index. Applicable to var-sized dimensions.

Example:

uint64_t start_size, end_size;
tiledb_fragment_info_get_mbr_var_size_from_index(
    ctx, fragment_info, 0, 0, 0, &start_size, &end_size);
// If non-empty domain range is `[aa, dddd]`,
// then `start_size = 2`, and `end_size = 4`.

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment information object.
fid – [in] The fragment index.
mid – [in] The mbr of the fragment of interest.
did – [in] The dimension index, following the order as it was defined in the domain of the array schema.
start_size – [out] The size in bytes of the start range.
end_size – [out] The size in bytes of the end range.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_mbr_var_size_from_name(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint32_t mid, const char *dim_name, uint64_t *start_size, uint64_t *end_size)¶

Retrieves the MBR range sizes from a fragment for a given dimension name. Applicable to var-sized dimensions.

Example:

uint64_t start_size, end_size;
tiledb_fragment_info_get_mbr_var_size_from_name(
    ctx, fragment_info, 0, 0, "d1", &start_size, &end_size);
// If non-empty domain range is `[aa, dddd]`,
// then `start_size = 2`, and `end_size = 4`.

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment information object.
fid – [in] The fragment index.
mid – [in] The mbr of the fragment of interest.
dim_name – [in] The dimension name.
start_size – [out] The size in bytes of the start range.
end_size – [out] The size in bytes of the end range.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_mbr_var_from_index(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint32_t mid, uint32_t did, void *start, void *end)¶

Retrieves the MBR from a fragment for a given dimension index. Applicable to var-sized dimensions.

Example:

// Get range sizes first
uint64_t start_size, end_size;
tiledb_fragment_info_get_mbr_var_size_from_index(
    ctx, fragment_info, 0, 0, 0, &start_size, &end_size);

// Get domain
char start[start_size];
char end[end_size];
tiledb_fragment_info_get_mbr_var_from_index(
    ctx, fragment_info, 0, 0, 0, start, end);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The fragment index.
mid – [in] The mbr of the fragment of interest.
did – [in] The dimension index, following the order as it was defined in the domain of the array schema.
start – [out] The domain range start to set.
end – [out] The domain range end to set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_mbr_var_from_name(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint32_t mid, const char *dim_name, void *start, void *end)¶

Retrieves the MBR from a fragment for a given dimension name. Applicable to var-sized dimensions.

Example:

// Get range sizes first
uint64_t start_size, end_size;
tiledb_fragment_info_get_mbr_var_size_from_name(
    ctx, fragment_info, 0, 0, "d1", &start_size, &end_size);

// Get domain
char start[start_size];
char end[end_size];
tiledb_fragment_info_get_mbr_var_from_name(
    ctx, fragment_info, 0, 0, "d1", start, end);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The fragment index.
mid – [in] The mbr of the fragment of interest.
dim_name – [in] The dimension name.
start – [out] The domain range start to set.
end – [out] The domain range end to set.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_cell_num(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint64_t *cell_num)¶

Retrieves the number of cells written to the fragment by the user.

In the case of sparse fragments, this is the number of non-empty cells in the fragment.

In the case of dense fragments, TileDB may add fill values to populate partially populated tiles. Those fill values are counted in the returned number of cells. In other words, the cell number is derived from the number of integral tiles written in the file.

Example:

uint64_t cell_num;
tiledb_fragment_info_get_cell_num(ctx, fragment_info, 0, &cell_num);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
cell_num – [out] The number of cells to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_version(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, uint32_t *version)¶

Retrieves the format version of a fragment.

Example:

uint32_t version;
tiledb_fragment_info_get_version(ctx, fragment_info, 0, &version);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
version – [out] The format version to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_has_consolidated_metadata(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, int32_t *has)¶

Checks if a fragment has consolidated metadata.

Example:

int32_t has;
tiledb_fragment_info_has_consolidated_metadata(ctx, fragment_info, 0, &has);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
has – [out] True if the fragment has consolidated metadata.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_unconsolidated_metadata_num(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t *unconsolidated)¶

Gets the number of fragments with unconsolidated metadata.

Example:

uint32_t unconsolidated;
tiledb_fragment_info_get_unconsolidated_metadata_num(
     ctx, fragment_info, &unconsolidated);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
unconsolidated – [out] The number of fragments with unconsolidated metadata.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_to_vacuum_num(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t *to_vacuum_num)¶

Gets the number of fragments to vacuum.

Example:

uint32_t to_vacuum_num;
tiledb_fragment_info_get_to_vacuum_num(ctx, fragment_info, &to_vacuum_num);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
to_vacuum_num – [out] The number of fragments to vacuum.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_to_vacuum_uri(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, const char **uri)¶

Gets the URI of the fragment to vacuum with the given index.

Example:

const char* uri;
tiledb_fragment_info_get_to_vacuum_uri(ctx, fragment_info, 1, &uri);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment to vacuum of interest.
uri – [out] The fragment URI to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_array_schema(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, tiledb_array_schema_t **array_schema)¶

Retrieves the array schema name a fragment.

Example:

tiledb_array_schema_t* array_schema;
tiledb_fragment_info_get_array_schema(ctx, fragment_info, 0, &array_schema);

Parameters:

ctx – [in] The TileDB context
fragment_info – [in] The fragment info object.
fid – [in] The index of the fragment of interest.
array_schema – [out] The array schema to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_get_array_schema_name(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, uint32_t fid, const char **schema_name)¶

Get the fragment info schema name.

Example:

char* name;
tiledb_fragment_info_schema_name(ctx, fragment_info, &schema_name);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
fid – [in] The fragment info index.
schema_name – [out] The schema name.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_dump(tiledb_ctx_t *ctx, const tiledb_fragment_info_t *fragment_info, FILE *out)¶

Dumps the fragment info in ASCII format in the selected output.

Example:

The following prints the fragment info dump in standard output.

tiledb_fragment_info_dump(ctx, fragment_info, stdout);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
out – [out] The output.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

capi_return_t tiledb_fragment_info_dump_str(tiledb_ctx_t *ctx, const tiledb_fragment_info_t *fragment_info, tiledb_string_t **out)¶

Dumps the fragment info in ASCII format in the selected string output.

The output string handle must be freed by the user after use.

Example:

tiledb_string_t* tdb_string;
tiledb_fragment_info_dump_str(ctx, fragment_info, &tdb_string);
// Use the string
tiledb_string_free(&tdb_string);

Parameters:

ctx – [in] The TileDB context.
fragment_info – [in] The fragment info object.
out – [out] The output string.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Experimental¶

Defines

TILEDB_QUERY_STATUS_DETAILS_ENUM(id)¶: Helper macro for defining status details type enums.

Typedefs

typedef struct tiledb_experimental_query_status_details_t tiledb_query_status_details_t¶: This should move to c_api/tiledb_struct_defs.h when stabilized

Enums

enum tiledb_query_status_details_reason_t¶

TileDB query status details type.

Values:

Functions

TILEDB_EXPORT capi_return_t tiledb_log_warn(tiledb_ctx_t *ctx, const char *message) TILEDB_NOEXCEPT¶

Log a message at WARN level using TileDB’s internal logging mechanism

Example:

tiledb_log_warn(ctx, "This is a log message.");

Parameters:

ctx – The TileDB Context.
message – The message to log

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT capi_return_t tiledb_as_built_dump(tiledb_string_t **out) TILEDB_NOEXCEPT¶

Dumps the TileDB build configuration to a string.

Example

tiledb_string_t* out;
tiledb_as_built_dump(&out);
tiledb_string_free(&out);

Parameters:

out – The output.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_array_schema_evolution_alloc(tiledb_ctx_t *ctx, tiledb_array_schema_evolution_t **array_schema_evolution) TILEDB_NOEXCEPT¶

Creates a TileDB schema evolution object.

Example:

tiledb_array_schema_evolution_t* array_schema_evolution;
tiledb_array_schema_evolution_alloc(ctx, &array_schema_evolution);

Parameters:

ctx – The TileDB context.
array_schema_evolution – The TileDB schema evolution to be created.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

TILEDB_EXPORT void tiledb_array_schema_evolution_free(tiledb_array_schema_evolution_t **array_schema_evolution) TILEDB_NOEXCEPT¶

Destroys an array schema evolution, freeing associated memory.

Example:

tiledb_array_schema_evolution_free(&array_schema_evolution);

Parameters:

array_schema_evolution – The array schema evolution to be destroyed.

TILEDB_EXPORT int32_t tiledb_array_schema_evolution_add_attribute(tiledb_ctx_t *ctx, tiledb_array_schema_evolution_t *array_schema_evolution, tiledb_attribute_t *attribute) TILEDB_NOEXCEPT¶

Adds an attribute to an array schema evolution.

Example:

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

Parameters:

ctx – [in] The TileDB context.
array_schema_evolution – [in] The schema evolution.
attribute – [in] The attribute to be added.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_array_schema_evolution_drop_attribute(tiledb_ctx_t *ctx, tiledb_array_schema_evolution_t *array_schema_evolution, const char *attribute_name) TILEDB_NOEXCEPT¶

Drops an attribute to an array schema evolution.

Example:

const char* attribute_name="a1";
tiledb_array_schema_evolution_drop_attribute(ctx, array_schema_evolution,
attribute_name);

Parameters:

ctx – The TileDB context.
array_schema_evolution – The schema evolution.
attribute_name – The name of the attribute to be dropped.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT capi_return_t tiledb_array_schema_evolution_add_enumeration(tiledb_ctx_t *ctx, tiledb_array_schema_evolution_t *array_schema_evolution, tiledb_enumeration_t *enumeration) TILEDB_NOEXCEPT¶

Adds an enumeration to an array schema evolution.

Example:

tiledb_enumeration_t* enmr;
void* data = get_data();
uint64_t data_size = get_data_size();
tiledb_enumeration_alloc(
    ctx,
    TILEDB_INT64,
    cell_val_num,
    FALSE,
    data,
    data_size,
    nullptr,
    0,
    &enumeration);
tiledb_array_schema_evolution_add_enumeration(ctx, array_schema_evolution,
enmr);

Parameters:

ctx – The TileDB context.
array_schema_evolution – The schema evolution.
enumeration – The enumeration to be added.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT capi_return_t tiledb_array_schema_evolution_extend_enumeration(tiledb_ctx_t *ctx, tiledb_array_schema_evolution_t *array_schema_evolution, tiledb_enumeration_t *enumeration) TILEDB_NOEXCEPT¶

Extends an enumeration during array schema evolution.

Example:

tiledb_enumeration_t* original_enmr = get_existing_enumeration();
const void* data = get_new_data();
uint64_t data_size = get_new_data_size();
tiledb_enumeration_t* new_enmr;
tiledb_enumeration_extend(
    ctx,
    original_enmr,
    data,
    data_size,
    nullptr,
    0,
    &new_enmr);
tiledb_array_schema_evolution_extend_enumeration(
    ctx,
    array_schema_evolution,
    new_enmr);

Parameters:

ctx – The TileDB context.
array_schema_evolution – The schema evolution.
enumeration – The enumeration to be extended. This should be the result of a call to tiledb_enumeration_extend.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT capi_return_t tiledb_array_schema_evolution_drop_enumeration(tiledb_ctx_t *ctx, tiledb_array_schema_evolution_t *array_schema_evolution, const char *enumeration_name) TILEDB_NOEXCEPT¶

Drops an enumeration from an array schema evolution.

Example:

const char* enumeration_name = "enumeration_1";
tiledb_array_schema_evolution_drop_enumeration(ctx, array_schema_evolution,
enumeration_name);

Parameters:

ctx – The TileDB context.
array_schema_evolution – The schema evolution.
enumeration_name – The name of the enumeration to be dropped.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_array_schema_evolution_set_timestamp_range(tiledb_ctx_t *ctx, tiledb_array_schema_evolution_t *array_schema_evolution, uint64_t lo, uint64_t hi) TILEDB_NOEXCEPT¶

Sets timestamp range in an array schema evolution This function sets the output timestamp of the committed array schema after evolution. The lo and hi values are currently required to be the same or else an error is thrown.

Example:

uint64_t timestamp = tiledb_timestamp_now_ms();
tiledb_array_schema_evolution_set_timestamp_range(ctx,
array_schema_evolution, timestamp, timestamp);

Parameters:

ctx – The TileDB context.
array_schema_evolution – The schema evolution.
lo – The lower bound of timestamp range.
hi – The upper bound of timestamp range, it must euqal to the lower bound.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT capi_return_t tiledb_array_schema_evolution_expand_current_domain(tiledb_ctx_t *ctx, tiledb_array_schema_evolution_t *array_schema_evolution, tiledb_current_domain_t *expanded_domain) TILEDB_NOEXCEPT¶

Expands the current domain during array schema evolution. TileDB will enforce that the new current domain is expanding on the current one and not contracting during tiledb_array_evolve.

Example:

tiledb_current_domain_t *new_domain;
tiledb_current_domain_create(ctx, &new_domain);
tiledb_ndrectangle_t *ndr;
tiledb_ndrectangle_alloc(ctx, domain, &ndr);

tiledb_range_t range;
range.min = &expanded_min;
range.min_size = sizeof(expanded_min);
range.max = &expanded_max;
range.max_size = sizeof(expanded_max);
tiledb_ndrectangle_set_range_for_name(ctx, ndr, "dim1", &range);
tiledb_ndrectangle_set_range_for_name(ctx, ndr, "dim2", &range);

tiledb_current_domain_set_ndrectangle(new_domain, ndr);

tiledb_array_schema_evolution_expand_current_domain(ctx,
     array_schema_evolution, new_domain);

tiledb_array_evolve(ctx, array_uri, array_schema_evolution);

tiledb_ndrectangle_free(&ndr);
tiledb_current_domain_free(&new_domain);

Parameters:

ctx – The TileDB context.
array_schema_evolution – The schema evolution.
expanded_domain – The current domain we want to expand the schema to.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_query_add_update_value(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *field_name, const void *update_value, uint64_t update_value_size) TILEDB_NOEXCEPT¶

Adds a query update values to be applied on an update.

Example:

uint32_t value = 5;
tiledb_query_add_update_value(
  ctx, query, "longitude", &value, sizeof(value), &update_value);

Parameters:

ctx – The TileDB context.
query – The TileDB query.
field_name – The attribute name.
update_value – The value to set.
update_value_size – The byte size of update_value.

TILEDB_EXPORT int32_t tiledb_query_get_relevant_fragment_num(tiledb_ctx_t *ctx, const tiledb_query_t *query, uint64_t *relevant_fragment_num) TILEDB_NOEXCEPT¶

Get the number of relevant fragments from the subarray. Should only be called after size estimation was asked for.

Note

Should only be called after size estimation was run.

Parameters:

ctx – The TileDB context.
query – The query to get the data fron.
relevant_fragment_num – Variable to receive the number of relevant fragments.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT capi_return_t tiledb_query_condition_alloc_set_membership(tiledb_ctx_t *ctx, const char *field_name, const void *data, uint64_t data_size, const void *offsets, uint64_t offests_size, tiledb_query_condition_op_t op, tiledb_query_condition_t **cond) TILEDB_NOEXCEPT¶

Initializes a TileDB query condition set membership object.

Example:

tiledb_query_condition_t* cond
tiledb_query_condition_alloc_set_membership(
  ctx,
  "some_name",
  data,
  data_size,
  offsets,
  offsets_size,
  TILEDB_QUERY_CONDITION_OP_IN,
  &cond);

Parameters:

ctx – The TileDB context.
field_name – The field name.
data – A pointer to the set member data.
data_size – The length of the data buffer.
offsets – A pointer to the array of offsets of members.
offsets_size – The length of the offsets array in bytes.
op – The set membership operator to use.
cond – The allocated query condition object.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_query_condition_set_use_enumeration(tiledb_ctx_t *ctx, const tiledb_query_condition_t *cond, int use_enumeration) TILEDB_NOEXCEPT¶

Disable the use of enumerations on the given QueryCondition

Example:

tiledb_query_condition_t* query_condition;
tiledb_query_condition_alloc(ctx, &query_condition);
uint32_t value = 5;
tiledb_query_condition_init(
  ctx,
  query_condition,
  "longitude",
  &value,
  sizeof(value),
  TILEDB_LT);
tiledb_query_condition_set_use_enumeration(ctx, query_condition, 0);

Parameters:

ctx – [in] The TileDB context.
cond – [in] The query condition
use_enumeration – [in] Non-zero to use the associated enumeration

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_query_get_status_details(tiledb_ctx_t *ctx, tiledb_query_t *query, tiledb_query_status_details_t *status_details) TILEDB_NOEXCEPT¶

Get extended query status details.

The contained enumeration tiledb_query_status_details_reason_t indicates extended information about a returned query status in order to allow improved client-side handling of buffers and potential resubmissions.

Example:

tiledb_query_status_details_t status_details;
tiledb_query_get_status_details(ctx, query, &status_details);

Parameters:

ctx – The TileDB context.
query – The query from which to retrieve status details.
status_details – The tiledb_query_status_details_t struct.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT capi_return_t tiledb_array_consolidate_fragments(tiledb_ctx_t *ctx, const char *array_uri, const char **fragment_uris, const uint64_t num_fragments, tiledb_config_t *config) TILEDB_NOEXCEPT¶

Consolidates the given fragment URIs into a single fragment.

Note: This API needs to be used with caution until we implement consolidation with timestamps. For now, if the non-empty domain of the consolidated fragments overlap anything in the fragments that come in between, this could lead to unpredictable behavior.

Example:

const char* uris[2]={"__0_0_0807b1428b6c4ff48b3cdb3283ca7903_10",
                     "__1_1_d9d965753d224194965575c1e9cdeeda_10"};
tiledb_array_consolidate_fragments(ctx, "my_array", uris, 2, nullptr);

Parameters:

ctx – [in] The TileDB context.
array_uri – [in] The name of the TileDB array whose metadata will be consolidated.
fragment_uris – [in] Fragment names of the fragments to consolidate. The names can be recovered using tiledb_fragment_info_get_fragment_name_v2.
num_fragments – [in] Number of URIs to consolidate.
config – [in] Configuration parameters for the consolidation (nullptr means default, which will use the config from ctx).

Returns:

TILEDB_OK on success, and TILEDB_ERR on error.

TILEDB_EXPORT int32_t tiledb_consolidation_plan_create_with_mbr(tiledb_ctx_t *ctx, tiledb_array_t *array, uint64_t fragment_size, tiledb_consolidation_plan_t **consolidation_plan) TILEDB_NOEXCEPT¶

Creates a consolidation plan object.

Example:

tiledb_consolidation_plan_t* consolidation_plan;
tiledb_consolidation_plan_create_with_mbr(ctx, array, 1024*1024*1024,
&consolidation_plan);

Parameters:

ctx – TileDB context.
array – The array to create the plan for.
fragment_size – The desired fragment size.
consolidation_plan – The consolidation plan object to be created and populated.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

TILEDB_EXPORT void tiledb_consolidation_plan_free(tiledb_consolidation_plan_t **consolidation_plan) TILEDB_NOEXCEPT¶

Frees a consolidation plan object.

Example:

tiledb_consolidation_plan_free(&consolidation_plan);

Parameters:

consolidation_plan – The consolidation plan object to be freed.

TILEDB_EXPORT int32_t tiledb_consolidation_plan_get_num_nodes(tiledb_ctx_t *ctx, tiledb_consolidation_plan_t *consolidation_plan, uint64_t *num_nodes) TILEDB_NOEXCEPT¶

Get the number of nodes of a consolidation plan object.

Example:

uint64_t num_nodes;
tiledb_consolidation_plan_get_num_nodes(ctx, consolidation_plan, &num_nodes);

Parameters:

ctx – TileDB context.
consolidation_plan – The consolidation plan.
num_nodes – The number of nodes to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_consolidation_plan_get_num_fragments(tiledb_ctx_t *ctx, tiledb_consolidation_plan_t *consolidation_plan, uint64_t node_index, uint64_t *num_fragments) TILEDB_NOEXCEPT¶

Get the number of fragments for a specific node of a consolidation plan object.

Example:

uint64_t num_fragments;
tiledb_consolidation_plan_get_num_fragments(ctx, consolidation_plan, 0,
&num_fragments);

Parameters:

ctx – TileDB context.
consolidation_plan – The consolidation plan.
node_index – The node index.
num_fragments – The number of fragments to be retrieved.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_consolidation_plan_get_fragment_uri(tiledb_ctx_t *ctx, tiledb_consolidation_plan_t *consolidation_plan, uint64_t node_index, uint64_t fragment_index, const char **uri) TILEDB_NOEXCEPT¶

Get the number of fragments for a specific node of a consolidation plan object.

Example:

uint64_t num_fragments;
tiledb_consolidation_plan_get_num_fragments(ctx, consolidation_plan, 0,
&num_fragments);

Parameters:

ctx – TileDB context.
consolidation_plan – The consolidation plan.
node_index – The node index.
fragment_index – The fragment index.
uri – The fragment uri to be retreived.

Returns:

TILEDB_OK for success and TILEDB_OOM or TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_consolidation_plan_dump_json_str(tiledb_ctx_t *ctx, const tiledb_consolidation_plan_t *consolidation_plan, char **str) TILEDB_NOEXCEPT¶

Dumps the consolidation plan in JSON format to a null terminated string. The string needs to be freed with tiledb_consolidation_plan_free_json_str.

Example:

char* str;
tiledb_consolidation_plan_dump_json_str(ctx, consolidation_plan, str);
tiledb_consolidation_plan_free_json_str(str);

Parameters:

ctx – The TileDB context.
consolidation_plan – The consolidation plan.
str – The output string.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_consolidation_plan_free_json_str(char **str) TILEDB_NOEXCEPT¶

Frees a string created by tiledb_consolidation_plan_dump_json_str.

Example:

char* str;
tiledb_consolidation_plan_dump_json_str(ctx, consolidation_plan, str);
tiledb_consolidation_plan_free_json_str(str);

Parameters:

str – The string to be freed.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

struct tiledb_experimental_query_status_details_t¶

#include <tiledb_experimental.h>

This should move to c_api/tiledb_struct_defs.h when stabilized

Public Members

tiledb_query_status_details_reason_t incomplete_reason¶: Reason enum for the incomplete query.

Deprecated¶

Functions

TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_schema_create(tiledb_ctx_t *ctx, const char *uri, tiledb_array_schema_t **array_schema) TILEDB_NOEXCEPT¶

Creates an array schema based on the properties of the provided URI or a default schema if no URI is provided Example:

tiledb_array_schema_t* schema;
tiledb_filestore_schema_create(ctx, "/path/file.pdf", &schema);

Parameters:

ctx – The TileDB context.
uri – The file URI.
array_schema – The TileDB array schema to be created

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_uri_import(tiledb_ctx_t *ctx, const char *filestore_array_uri, const char *file_uri, tiledb_mime_type_t mime_type) TILEDB_NOEXCEPT¶

Imports a file into a TileDB filestore array Example:

tiledb_array_schema_t* schema;
tiledb_filestore_schema_create(ctx, path_to_file, &schema);
tiledb_array_create(ctx, path_to_array, schema);
tiledb_filestore_uri_import(ctx, path_to_array, path_to_file,
TILEDB_MIME_AUTODETECT);

Parameters:

ctx – The TileDB context.
filestore_array_uri – The array URI.
file_uri – The file URI.
mime_type – The mime type of the file

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_uri_export(tiledb_ctx_t *ctx, const char *file_uri, const char *filestore_array_uri) TILEDB_NOEXCEPT¶

Exports a filestore array into a bare file Example:

tiledb_filestore_uri_export(ctx, path_to_file, path_to_array);

Parameters:

ctx – The TileDB context.
file_uri – The file URI.
filestore_array_uri – The array URI.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_buffer_import(tiledb_ctx_t *ctx, const char *filestore_array_uri, void *buf, size_t size, tiledb_mime_type_t mime_type) TILEDB_NOEXCEPT¶

Writes size bytes starting at address buf into filestore array Example:

tiledb_array_schema_t* schema;
tiledb_filestore_schema_create(ctx, NULL, &schema);
tiledb_array_create(ctx, path_to_array, schema);
tiledb_filestore_buffer_import(ctx, path_to_array, buf, size,
TILEDB_MIME_AUTODETECT);

Parameters:

ctx – The TileDB context.
filestore_array_uri – The array URI.
buf – The input buffer
size – Number of bytes to be imported
mime_type – The mime type of the data

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_buffer_export(tiledb_ctx_t *ctx, const char *filestore_array_uri, size_t offset, void *buf, size_t size) TILEDB_NOEXCEPT¶

Dump the content of a filestore array into a buffer Example:

size_t size = 1024;
void *buf = malloc(size);
tiledb_filestore_buffer_export(ctx, path_to_array, 0, buf, size);

Parameters:

ctx – The TileDB context.
filestore_array_uri – The array URI.
offset – The offset at which we should start exporting from the array
buf – The buffer that will contain the filestore array content
size – The number of bytes to be exported into the buffer

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_DEPRECATED_EXPORT int32_t tiledb_filestore_size(tiledb_ctx_t *ctx, const char *filestore_array_uri, size_t *size) TILEDB_NOEXCEPT¶

Get the uncompressed size of a filestore array Example:

size_t size;
tiledb_filestore_size(ctx, path_to_array, &size);
void *buf = malloc(size);
tiledb_filestore_buffer_export(ctx, path_to_array, 0, buf, size);
free(buf);

Parameters:

ctx – [in] The TileDB context.
filestore_array_uri – [in] The array URI.
size – [in] The returned uncompressed size of the filestore array

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_DEPRECATED_EXPORT int32_t tiledb_mime_type_to_str(tiledb_mime_type_t mime_type, const char **str) TILEDB_NOEXCEPT¶

Get the string representation of a mime type enum

Parameters:

mime_type – The mime enum
str – The resulted string representation

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_DEPRECATED_EXPORT int32_t tiledb_mime_type_from_str(const char *str, tiledb_mime_type_t *mime_type) TILEDB_NOEXCEPT¶

Turn a string mime type into a TileDB enum

Parameters:

str – The mime type string
mime_type – The resulted mime enum

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

Serialization¶

Defines

TILEDB_SERIALIZATION_TYPE_ENUM(id)¶: Helper macro for defining array type enums.

Enums

enum tiledb_serialization_type_t¶

Serialization type.

Values:

Functions

TILEDB_EXPORT int32_t tiledb_serialization_type_to_str(tiledb_serialization_type_t serialization_type, const char **str) TILEDB_NOEXCEPT¶

Returns a string representation of the given serialization type.

Parameters:

serialization_type – Serialization type
str – Set to point to a constant string representation of the serialization type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialization_type_from_str(const char *str, tiledb_serialization_type_t *serialization_type) TILEDB_NOEXCEPT¶

Parses a serialization type from the given string.

Parameters:

str – String representation to parse
serialization_type – Set to the parsed serialization type

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_array(tiledb_ctx_t *ctx, const tiledb_array_t *array, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the given array.

Note

The caller must free the returned tiledb_buffer_t.

Parameters:

ctx – The TileDB context.
array – The array to serialize.
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
buffer – Will be set to a newly allocated buffer containing the serialized max buffer sizes.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_array(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, int32_t client_side, const char *array_uri, tiledb_array_t **array) TILEDB_NOEXCEPT¶

Deserializes a new array from the given buffer.

Parameters:

ctx – The TileDB context.
buffer – Buffer to deserialize from
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
array_uri – uri of the array to deserialize.
array – Will be set to a newly allocated array.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_array_schema(tiledb_ctx_t *ctx, const tiledb_array_schema_t *array_schema, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the given array schema.

Note

The caller must free the returned tiledb_buffer_t.

Parameters:

ctx – The TileDB context.
array_schema – The array schema to serialize.
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
buffer – Will be set to a newly allocated buffer containing the serialized max buffer sizes.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_array_schema(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_array_schema_t **array_schema) TILEDB_NOEXCEPT¶

Deserializes a new array schema from the given buffer.

Parameters:

ctx – The TileDB context.
buffer – Buffer to deserialize from
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
array_schema – Will be set to a newly allocated array schema.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_array_open(tiledb_ctx_t *ctx, const tiledb_array_t *array, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_buffer_t **buffer_list) TILEDB_NOEXCEPT¶

Serializes the given array open information into the given buffer.

Note

The caller must free the returned tiledb_buffer_t.

Parameters:

ctx – The TileDB context.
array – The array to get the information to serialize from.
serialization_type – Type of serialization to use.
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
tiledb_buffer_t – Will be set to a newly allocated buffer containing the serialized array open information.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_array_open(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_array_t **array) TILEDB_NOEXCEPT¶

Deserializes into an existing array from the given buffer.

Note

The deserialization is zero-copy, so the source buffer must exceed the lifetime of the array being deserialized to.

Parameters:

ctx – The TileDB context.
buffer – Buffer to deserialize from.
serialization_type – Type of deserialization to use.
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
array – The array object to deserialize into (must be pre-allocated).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_array_schema_evolution(tiledb_ctx_t *ctx, const tiledb_array_schema_evolution_t *array_schema_evolution, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the given array schema evolution.

Note

The caller must free the returned tiledb_buffer_t.

Parameters:

ctx – The TileDB context.
array_schema_evolution – The array schema evolution to serialize.
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
buffer – Will be set to a newly allocated buffer containing the serialized max buffer sizes.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_array_schema_evolution(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_array_schema_evolution_t **array_schema_evolution) TILEDB_NOEXCEPT¶

Deserializes a new array schema evolution object from the given buffer.

Parameters:

ctx – The TileDB context.
buffer – Buffer to deserialize from
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
array_schema_evolution – Will be set to a newly allocated array schema evolution.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_query(tiledb_ctx_t *ctx, const tiledb_query_t *query, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_buffer_list_t **buffer_list) TILEDB_NOEXCEPT¶

Serializes the given query.

Where possible the serialization is zero-copy. The returned buffer list contains an ordered list of pointers to buffers that logically contain the entire serialized query when concatenated.

Note

The caller must free the returned tiledb_buffer_list_t.

Parameters:

ctx – The TileDB context.
query – The query.
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
buffer_list – Will be set to a newly allocated buffer list containing the serialized query.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_query(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_query_t *query) TILEDB_NOEXCEPT¶

Deserializes into an existing query from the given buffer.

Note

The deserialization is zero-copy, so the source buffer must exceed the lifetime of the query being deserialized to.

Parameters:

ctx – The TileDB context.
buffer – Buffer to deserialize from
serialization_type – Type of deserialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
query – The query object to deserialize into (must be pre-allocated).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_query_and_array(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, int32_t client_side, const char *array_uri, tiledb_query_t **query, tiledb_array_t **array) TILEDB_NOEXCEPT¶

Deserializes into a new query object from the given buffer, while deserializing at the same time the (open) array object stored in the query object as a member. The caller has the responsibility to free the returned query and array objects.

Note

The deserialization is zero-copy, so the source buffer must exceed the lifetime of the query being deserialized to.

Parameters:

ctx – The TileDB context.
buffer – Buffer to deserialize from.
serialization_type – Type of deserialization to use.
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
array_uri – uri of the array the query is submitted to.
query – The query object to allocate and deserialize into.
array – The array object to allocate and deserialize into. It can also be referenced as query->array().

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_array_nonempty_domain(tiledb_ctx_t *ctx, const tiledb_array_t *array, const void *nonempty_domain, int32_t is_empty, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the given non-empty domain information into the given buffer.

Note

The caller must free the returned tiledb_buffer_t.

Parameters:

ctx – The TileDB context.
array – Array to which the domain belongs to
nonempty_domain – The domain to serialize
is_empty – 1 if the domain is empty
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
buffer – Will be set to a newly allocated buffer containing the serialized max buffer sizes.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_array_nonempty_domain(tiledb_ctx_t *ctx, const tiledb_array_t *array, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, int32_t client_side, void *nonempty_domain, int32_t *is_empty) TILEDB_NOEXCEPT¶

Deserializes non-empty domain information from the given buffer.

Parameters:

ctx – The TileDB context.
array – Array to which the domain belongs to
buffer – Buffer to deserialize from
serialization_type – Type of deserialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
nonempty_domain – The buffer to deserialize into
is_empty – Will be set to 1 if the domain is empty

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_array_non_empty_domain_all_dimensions(tiledb_ctx_t *ctx, const tiledb_array_t *array, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the given non-empty domain information into the given buffer.

Note

The caller must free the returned tiledb_buffer_t.

Parameters:

ctx – The TileDB context.
Array – array to which the domain belongs to
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
buffer – Will be set to a newly allocated buffer containing the serialized max buffer sizes.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_array_non_empty_domain_all_dimensions(tiledb_ctx_t *ctx, tiledb_array_t *array, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, int32_t client_side) TILEDB_NOEXCEPT¶

Deserializes non-empty domain information from the given buffer.

Parameters:

ctx – The TileDB context.
array – Array to which the domain belongs to
buffer – Buffer to deserialize from
serialization_type – Type of deserialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_DEPRECATED_EXPORT int32_t tiledb_serialize_array_max_buffer_sizes(tiledb_ctx_t *ctx, const tiledb_array_t *array, const void *subarray, tiledb_serialization_type_t serialize_type, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the array max buffer sizes information into the given buffer.

This API is deprecated and using it will always return an error.

Parameters:

ctx – The TileDB context.
array – Array to which the subarray belongs to
subarray – The subarray to use for max buffer size calculation.
serialization_type – Type of serialization to use
buffer – Will be set to a newly allocated buffer containing the serialized max buffer sizes.

Returns:

TILEDB_ERR

TILEDB_EXPORT capi_return_t tiledb_handle_array_delete_fragments_timestamps_request(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_serialization_type_t serialization_type, const tiledb_buffer_t *request) TILEDB_NOEXCEPT¶

Process a delete fragments request.

Parameters:

ctx – The TileDB context.
array – The TileDB Array.
serialization_type – Type of serialization to use
request – Buffer containing serialized fragment timestamps.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT capi_return_t tiledb_handle_array_delete_fragments_list_request(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_serialization_type_t serialization_type, const tiledb_buffer_t *request) TILEDB_NOEXCEPT¶

Process a delete fragments list request.

Parameters:

ctx – The TileDB context.
array – The TileDB Array.
serialization_type – Type of serialization to use
buffer – Buffer containing serialized fragments list.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_array_metadata(tiledb_ctx_t *ctx, const tiledb_array_t *array, tiledb_serialization_type_t serialization_type, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the array metadata into the given buffer.

Note

The caller must free the returned tiledb_buffer_t.

Parameters:

ctx – The TileDB context.
array – Array whose metadata to serialize.
serialization_type – Type of serialization to use
buffer – Will be set to a newly allocated buffer containing the serialized array metadata.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_array_metadata(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_serialization_type_t serialization_type, const tiledb_buffer_t *buffer) TILEDB_NOEXCEPT¶

Sets the array metadata on the given array instance by deserializing the array metadata from the given buffer.

Parameters:

ctx – The TileDB context.
array – Array whose metadata to set.
serialization_type – Type of serialization to use
buffer – Buffer containing serialized array metadata.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_query_est_result_sizes(tiledb_ctx_t *ctx, const tiledb_query_t *query, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the given query’s estimated result sizes map.

Note

The caller must free the returned tiledb_buffer_list_t.

Parameters:

ctx – The TileDB context.
query – The query to get the estimated result sizes of.
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization. Currently unused.
buffer – Will be set to a newly allocated buffer containing the serialized query estimated result sizes.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_query_est_result_sizes(tiledb_ctx_t *ctx, tiledb_query_t *query, tiledb_serialization_type_t serialize_type, int32_t client_side, const tiledb_buffer_t *buffer) TILEDB_NOEXCEPT¶

Deserializes into an existing query from the given buffer.

Parameters:

ctx – The TileDB context.
query – The query object to deserialize into (must be pre-allocated).
serialization_type – Type of deserialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization. Currently unused.
buffer – Buffer to deserialize from

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_config(tiledb_ctx_t *ctx, const tiledb_config_t *config, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the given config.

Note

The caller must free the returned tiledb_buffer_t.

Parameters:

ctx – The TileDB context.
config – The config to serialize.
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization. Currently unused for config
buffer – Will be set to a newly allocated buffer containing the serialized max buffer sizes.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_config(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_config_t **config) TILEDB_NOEXCEPT¶

Deserializes a new config from the given buffer.

Parameters:

ctx – The TileDB context.
buffer – Buffer to deserialize from
serialization_type – Type of serialization to use.
client_side – If set to 1, deserialize from “client-side” perspective. Else, “server-side.”. Currently unused for config
config – Will be set to a newly allocated config.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_fragment_info_request(tiledb_ctx_t *ctx, const tiledb_fragment_info_t *fragment_info, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the fragment info request into the given buffer.

Note

The caller must free the returned tiledb_buffer_t.

Parameters:

ctx – The TileDB context.
fragment_info – Fragment info to get the info to serialize.
serialization_type – Type of serialization to use.
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
buffer – Will be set to a newly allocated buffer containing the serialized fragment info request.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_fragment_info_request(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_fragment_info_t *fragment_info) TILEDB_NOEXCEPT¶

Populates fragment info by deserializing the fragment info request from the given buffer.

Parameters:

ctx – The TileDB context.
buffer – Buffer containing serialized fragment info request.
serialization_type – Type of serialization to use.
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
fragment_info – Fragment info object to deserialize the info into.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_fragment_info(tiledb_ctx_t *ctx, const tiledb_fragment_info_t *fragment_info, tiledb_serialization_type_t serialization_type, int32_t client_side, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the fragment info into the given buffer.

Note

The caller must free the returned tiledb_buffer_t.

Parameters:

ctx – The TileDB context.
fragment_info – Fragment info to serialize.
serialization_type – Type of serialization to use.
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
buffer – Will be set to a newly allocated buffer containing the serialized fragment info.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_fragment_info(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, const char *array_uri, int32_t client_side, tiledb_fragment_info_t *fragment_info) TILEDB_NOEXCEPT¶

Populates the fragment info by deserializing from the given buffer.

Parameters:

ctx – The TileDB context.
buffer – Buffer containing serialized fragment info.
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
array_uri – array that fragment info belongs to
fragment_info – Fragment info to deserialize into.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_group(tiledb_ctx_t *ctx, const tiledb_group_t *group, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_buffer_t **buffer_list) TILEDB_NOEXCEPT¶

Serializes the given group.

Where possible the serialization is zero-copy. The returned buffer list contains an ordered list of pointers to buffers that logically contain the entire serialized group when concatenated.

Note

The caller must free the returned tiledb_buffer_list_t.

Parameters:

ctx – The TileDB context.
group – The group.
serialization_type – Type of serialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
tiledb_buffer_t – Will be set to a newly allocated buffer containing the serialized group.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_group(tiledb_ctx_t *ctx, const tiledb_buffer_t *buffer, tiledb_serialization_type_t serialize_type, int32_t client_side, tiledb_group_t *group) TILEDB_NOEXCEPT¶

Deserializes into an existing group from the given buffer.

Note

The deserialization is zero-copy, so the source buffer must exceed the lifetime of the group being deserialized to.

Parameters:

ctx – The TileDB context.
buffer – Buffer to deserialize from
serialization_type – Type of deserialization to use
client_side – Allows to specify different behavior depending on who is serializing, the client (1) or the Cloud server (0). This is sometimes needed since they are both using the same Core library APIs for serialization.
group – The group object to deserialize into (must be pre-allocated).

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_serialize_group_metadata(tiledb_ctx_t *ctx, const tiledb_group_t *group, tiledb_serialization_type_t serialization_type, tiledb_buffer_t **buffer) TILEDB_NOEXCEPT¶

Serializes the group metadata into the given buffer.

Note

The caller must free the returned tiledb_buffer_t.

Parameters:

ctx – The TileDB context.
group – Group whose metadata to serialize.
serialization_type – Type of serialization to use
buffer – Will be set to a newly allocated buffer containing the serialized group metadata.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT int32_t tiledb_deserialize_group_metadata(tiledb_ctx_t *ctx, tiledb_group_t *group, tiledb_serialization_type_t serialization_type, const tiledb_buffer_t *buffer) TILEDB_NOEXCEPT¶

Sets the group metadata on the given group instance by deserializing the group metadata from the given buffer.

Parameters:

ctx – The TileDB context.
group – Group whose metadata to set.
serialization_type – Type of serialization to use
buffer – Buffer containing serialized group metadata.

Returns:

TILEDB_OK for success and TILEDB_ERR for error.

TILEDB_EXPORT capi_return_t tiledb_handle_load_array_schema_request(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_serialization_type_t serialization_type, const tiledb_buffer_t *request, tiledb_buffer_t *response) TILEDB_NOEXCEPT¶

Process a load array schema request.

Parameters:

ctx – The TileDB context.
array – The TileDB Array.
serialization_type – The type of Cap’n Proto serialization used.
request – A buffer containing the LoadArraySchemaRequest Cap’n Proto message.
response – An allocated buffer that will contain the LoadArraySchemaResponse Cap’n Proto message.

Returns:

capi_return_t TILEDB_OK on success, TILEDB_ERR on error.

TILEDB_EXPORT capi_return_t tiledb_handle_load_enumerations_request(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_serialization_type_t serialization_type, const tiledb_buffer_t *request, tiledb_buffer_t *response) TILEDB_NOEXCEPT¶

Process a load enumerations request.

Parameters:

ctx – The TileDB context.
array – The TileDB Array.
serialization_type – The type of Cap’n Proto serialization used.
request – A buffer containing the LoadEnumerationsRequest Capnp message.
response – An allocated buffer that will contain the LoadEnumerationsResponse Capnp message.

Returns:

capi_return_t TILEDB_OK on success, TILEDB_ERR on error.

TILEDB_EXPORT capi_return_t tiledb_handle_query_plan_request(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_serialization_type_t serialization_type, const tiledb_buffer_t *request, tiledb_buffer_t *response) TILEDB_NOEXCEPT¶

Process a query plan request.

Parameters:

ctx – The TileDB context.
array – The TileDB Array.
serialization_type – The type of Cap’n Proto serialization used.
request – A buffer containing the QueryPlanRequest Capnp message.
response – An allocated buffer that will contain the QueryPlanResponse Capnp message.

Returns:

capi_return_t TILEDB_OK on success, TILEDB_ERR on error.

TILEDB_EXPORT capi_return_t tiledb_handle_consolidation_plan_request(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_serialization_type_t serialization_type, const tiledb_buffer_t *request, tiledb_buffer_t *response) TILEDB_NOEXCEPT¶

Process a consolidation plan request.

Parameters:

ctx – The TileDB context.
array – The TileDB Array.
serialization_type – The type of Cap’n Proto serialization used.
request – A buffer containing the ConsolidationPlanRequest Capnp message.
response – An allocated buffer that will contain the ConsolidationPlanResponse Capnp message.

Returns:

capi_return_t TILEDB_OK on success, TILEDB_ERR on error.

TileDB C API Reference¶

Types¶

Return Codes¶

Constants¶

Enumerations¶

Enumeration String Conversion¶

Context¶

Config¶

Config Iterator¶

Error¶

Array¶

Array Schema¶

Attribute¶

Domain¶

Dimension¶

Query¶

Subarray¶

Query Condition¶

Filter¶

Filter List¶

Group¶

Buffer¶

BufferList¶

Object Management¶

VFS¶

URI¶

Version¶

Stats¶

Heap Profiler¶

Fragment Info¶

Experimental¶

Deprecated¶

Serialization¶

Table of Contents

Previous topic

Next topic

This Page