TileDB C API Reference¶
Types¶
-
typedef struct tiledb_array_t
tiledb_array_t
¶ An array object.
-
typedef struct tiledb_buffer_t
tiledb_buffer_t
¶ A generic buffer object.
-
typedef struct tiledb_buffer_list_t
tiledb_buffer_list_t
¶ A generic buffer list object.
-
typedef struct tiledb_config_t
tiledb_config_t
¶ A config object.
-
typedef struct tiledb_config_iter_t
tiledb_config_iter_t
¶ A config iterator.
-
typedef struct tiledb_ctx_t
tiledb_ctx_t
¶ A TileDB context.
-
typedef struct tiledb_error_t
tiledb_error_t
¶ A TileDB error.
-
typedef struct tiledb_attribute_t
tiledb_attribute_t
¶ A TileDB attribute.
-
typedef struct tiledb_array_schema_t
tiledb_array_schema_t
¶ A TileDB array schema.
-
typedef struct tiledb_dimension_t
tiledb_dimension_t
¶ A TileDB dimension.
-
typedef struct tiledb_domain_t
tiledb_domain_t
¶ A TileDB domain.
-
typedef struct tiledb_query_t
tiledb_query_t
¶ A TileDB query.
-
typedef struct tiledb_filter_t
tiledb_filter_t
¶ A TileDB filter.
-
typedef struct tiledb_filter_list_t
tiledb_filter_list_t
¶ A TileDB filter list.
-
typedef struct tiledb_vfs_t
tiledb_vfs_t
¶ A virtual filesystem object.
-
typedef struct tiledb_vfs_fh_t
tiledb_vfs_fh_t
¶ A virtual filesystem file handle.
Return Codes¶
-
TILEDB_OK
¶ Success
-
TILEDB_ERR
¶ General error
-
TILEDB_OOM
¶ Out of memory
Constants¶
-
TILEDB_COORDS
¶ A special name indicating the coordinates attribute.
-
TILEDB_VAR_NUM
¶ A special value indicating a variable number of elements.
-
TILEDB_MAX_PATH
¶ The maximum path length on the current platform.
-
TILEDB_OFFSET_SIZE
¶ The size (in bytes) of an offset (used in variable-sized attributes).
-
const char *
tiledb_coords
(void)¶ Returns a special name indicating the coordinates attribute.
The coordinate buffer has been deprecated. Set the coordinates for each individual dimension with the
set_buffer
API. Consult the current documentation for more information.
-
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).
Enumerations¶
-
enum
tiledb_object_t
¶ TileDB object type.
Values:
-
enumerator
TILEDB_INVALID
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.Invalid object
-
enumerator
TILEDB_GROUP
¶ Group object
-
enumerator
TILEDB_ARRAY
¶ Array object
-
enumerator
-
enum
tiledb_query_type_t
¶ TileDB query type.
Values:
-
enumerator
TILEDB_READ
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.Read query
-
enumerator
TILEDB_WRITE
¶ Write query
-
enumerator
-
enum
tiledb_query_status_t
¶ Query status.
Values:
-
enumerator
TILEDB_FAILED
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.Query failed
-
enumerator
TILEDB_COMPLETED
¶ Query completed (all data has been read)
-
enumerator
TILEDB_INPROGRESS
¶ Query is in progress
-
enumerator
TILEDB_INCOMPLETE
¶ Query completed (but not all data has been read)
-
enumerator
TILEDB_UNINITIALIZED
¶ Query not initialized.
-
enumerator
-
enum
tiledb_filesystem_t
¶ Filesystem type.
Values:
-
enumerator
TILEDB_HDFS
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.HDFS filesystem
-
enumerator
TILEDB_S3
¶ S3 filesystem
-
enumerator
TILEDB_AZURE
¶ Azure filesystem
-
enumerator
TILEDB_GCS
¶ GCS filesystem
-
enumerator
TILEDB_MEMFS
¶ In-memory filesystem
-
enumerator
-
enum
tiledb_datatype_t
¶ TileDB datatype.
Values:
-
enumerator
TILEDB_INT32
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.32-bit signed integer
-
enumerator
TILEDB_INT64
¶ 64-bit signed integer
-
enumerator
TILEDB_FLOAT32
¶ 32-bit floating point value
-
enumerator
TILEDB_FLOAT64
¶ 64-bit floating point value
-
enumerator
TILEDB_CHAR
¶ Character
-
enumerator
TILEDB_INT8
¶ 8-bit signed integer
-
enumerator
TILEDB_UINT8
¶ 8-bit unsigned integer
-
enumerator
TILEDB_INT16
¶ 16-bit signed integer
-
enumerator
TILEDB_UINT16
¶ 16-bit unsigned integer
-
enumerator
TILEDB_UINT32
¶ 32-bit unsigned integer
-
enumerator
TILEDB_UINT64
¶ 64-bit unsigned integer
-
enumerator
TILEDB_STRING_ASCII
¶ ASCII string
-
enumerator
TILEDB_STRING_UTF8
¶ UTF-8 string
-
enumerator
TILEDB_STRING_UTF16
¶ UTF-16 string
-
enumerator
TILEDB_STRING_UTF32
¶ UTF-32 string
-
enumerator
TILEDB_STRING_UCS2
¶ UCS2 string
-
enumerator
TILEDB_STRING_UCS4
¶ UCS4 string
-
enumerator
TILEDB_ANY
¶ This can be any datatype. Must store (type tag, value) pairs.
-
enumerator
TILEDB_DATETIME_YEAR
¶ Datetime with year resolution
-
enumerator
TILEDB_DATETIME_MONTH
¶ Datetime with month resolution
-
enumerator
TILEDB_DATETIME_WEEK
¶ Datetime with week resolution
-
enumerator
TILEDB_DATETIME_DAY
¶ Datetime with day resolution
-
enumerator
TILEDB_DATETIME_HR
¶ Datetime with hour resolution
-
enumerator
TILEDB_DATETIME_MIN
¶ Datetime with minute resolution
-
enumerator
TILEDB_DATETIME_SEC
¶ Datetime with second resolution
-
enumerator
TILEDB_DATETIME_MS
¶ Datetime with millisecond resolution
-
enumerator
TILEDB_DATETIME_US
¶ Datetime with microsecond resolution
-
enumerator
TILEDB_DATETIME_NS
¶ Datetime with nanosecond resolution
-
enumerator
TILEDB_DATETIME_PS
¶ Datetime with picosecond resolution
-
enumerator
TILEDB_DATETIME_FS
¶ Datetime with femtosecond resolution
-
enumerator
TILEDB_DATETIME_AS
¶ Datetime with attosecond resolution
-
enumerator
TILEDB_TIME_HR
¶ Time with hour resolution
-
enumerator
TILEDB_TIME_MIN
¶ Time with minute resolution
-
enumerator
TILEDB_TIME_SEC
¶ Time with second resolution
-
enumerator
TILEDB_TIME_MS
¶ Time with millisecond resolution
-
enumerator
TILEDB_TIME_US
¶ Time with microsecond resolution
-
enumerator
TILEDB_TIME_NS
¶ Time with nanosecond resolution
-
enumerator
TILEDB_TIME_PS
¶ Time with picosecond resolution
-
enumerator
TILEDB_TIME_FS
¶ Time with femtosecond resolution
-
enumerator
TILEDB_TIME_AS
¶ Time with attosecond resolution
-
enumerator
TILEDB_BLOB
¶ std::byte
-
enumerator
TILEDB_BOOL
¶ Boolean
-
enumerator
-
enum
tiledb_array_type_t
¶ Array type.
Values:
-
enumerator
TILEDB_DENSE
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.Dense array
-
enumerator
TILEDB_SPARSE
¶ Sparse array
-
enumerator
-
enum
tiledb_layout_t
¶ Tile or cell layout.
Values:
-
enumerator
TILEDB_ROW_MAJOR
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.Row-major layout
-
enumerator
TILEDB_COL_MAJOR
¶ Column-major layout
-
enumerator
TILEDB_GLOBAL_ORDER
¶ Global-order layout
-
enumerator
TILEDB_UNORDERED
¶ Unordered layout
-
enumerator
TILEDB_HILBERT
¶ Hilbert layout
-
enumerator
-
enum
tiledb_filter_type_t
¶ Filter type.
Values:
-
enumerator
TILEDB_FILTER_NONE
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.No-op filter
-
enumerator
TILEDB_FILTER_GZIP
¶ Gzip compressor
-
enumerator
TILEDB_FILTER_ZSTD
¶ Zstandard compressor
-
enumerator
TILEDB_FILTER_LZ4
¶ LZ4 compressor
-
enumerator
TILEDB_FILTER_RLE
¶ Run-length encoding compressor
-
enumerator
TILEDB_FILTER_BZIP2
¶ Bzip2 compressor
-
enumerator
TILEDB_FILTER_DOUBLE_DELTA
¶ Double-delta compressor
-
enumerator
TILEDB_FILTER_BIT_WIDTH_REDUCTION
¶ Bit width reduction filter.
-
enumerator
TILEDB_FILTER_BITSHUFFLE
¶ Bitshuffle filter.
-
enumerator
TILEDB_FILTER_BYTESHUFFLE
¶ Byteshuffle filter.
-
enumerator
TILEDB_FILTER_POSITIVE_DELTA
¶ Positive-delta encoding filter.
-
enumerator
TILEDB_FILTER_CHECKSUM_MD5
¶ MD5 checksum filter. Starts at 12 because 11 is used for encryption, see tiledb/sm/enums/filter_type.h
-
enumerator
TILEDB_FILTER_CHECKSUM_SHA256
¶ SHA256 checksum filter.
-
enumerator
TILEDB_FILTER_DICTIONARY
¶ Dictionary encoding filter.
-
enumerator
-
enum
tiledb_filter_option_t
¶ Filter option.
Values:
-
enumerator
TILEDB_COMPRESSION_LEVEL
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.Compression level. Type:
int32_t
.
-
enumerator
TILEDB_BIT_WIDTH_MAX_WINDOW
¶ Max window length for bit width reduction. Type:
uint32_t
.
-
enumerator
TILEDB_POSITIVE_DELTA_MAX_WINDOW
¶ Max window length for positive-delta encoding. Type:
uint32_t
.
-
enumerator
-
enum
tiledb_walk_order_t
¶ Walk traversal order.
Values:
-
enumerator
TILEDB_PREORDER
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.Pre-order traversal
-
enumerator
TILEDB_POSTORDER
¶ Post-order traversal
-
enumerator
-
enum
tiledb_vfs_mode_t
¶ VFS mode.
Values:
-
enumerator
TILEDB_VFS_READ
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.TileDB VFS mode Read mode
-
enumerator
TILEDB_VFS_WRITE
¶ Write mode
-
enumerator
TILEDB_VFS_APPEND
¶ Append mode
-
enumerator
-
enum
tiledb_encryption_type_t
¶ Encryption type.
Values:
-
enumerator
TILEDB_NO_ENCRYPTION
¶ NOTE: The values of these enums are serialized to the array schema and/or fragment metadata. Therefore, the values below should never change, otherwise backwards compatibility breaks.No encryption.
-
enumerator
TILEDB_AES_256_GCM
¶ AES-256-GCM encryption.
-
enumerator
Enumeration String Conversion¶
-
int32_t
tiledb_query_type_to_str
(tiledb_query_type_t query_type, const char **str)¶ Returns a string representation of the given query type.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
query_type
: Query typestr
: Set to point to a constant string representation of the query type
-
int32_t
tiledb_query_type_from_str
(const char *str, tiledb_query_type_t *query_type)¶ Parses a query type from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parsequery_type
: Set to the parsed query type
-
int32_t
tiledb_object_type_to_str
(tiledb_object_t object_type, const char **str)¶ Returns a string representation of the given object type.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
object_type
: Object typestr
: Set to point to a constant string representation of the object type
-
int32_t
tiledb_object_type_from_str
(const char *str, tiledb_object_t *object_type)¶ Parses a object type from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parseobject_type
: Set to the parsed object type
-
int32_t
tiledb_filesystem_to_str
(tiledb_filesystem_t filesystem, const char **str)¶ Returns a string representation of the given filesystem.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
filesystem
: Filesystemstr
: Set to point to a constant string representation of the filesystem
-
int32_t
tiledb_filesystem_from_str
(const char *str, tiledb_filesystem_t *filesystem)¶ Parses a filesystem from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parsefilesystem
: Set to the parsed filesystem
-
int32_t
tiledb_datatype_to_str
(tiledb_datatype_t datatype, const char **str)¶ Returns a string representation of the given datatype.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
datatype
: Datatypestr
: Set to point to a constant string representation of the datatype
-
int32_t
tiledb_datatype_from_str
(const char *str, tiledb_datatype_t *datatype)¶ Parses a datatype from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parsedatatype
: Set to the parsed datatype
-
int32_t
tiledb_array_type_to_str
(tiledb_array_type_t array_type, const char **str)¶ Returns a string representation of the given array type.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
array_type
: Array typestr
: Set to point to a constant string representation of the array type
-
int32_t
tiledb_array_type_from_str
(const char *str, tiledb_array_type_t *array_type)¶ Parses a array type from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parsearray_type
: Set to the parsed array type
-
int32_t
tiledb_layout_to_str
(tiledb_layout_t layout, const char **str)¶ Returns a string representation of the given layout.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
layout
: Layoutstr
: Set to point to a constant string representation of the layout
-
int32_t
tiledb_layout_from_str
(const char *str, tiledb_layout_t *layout)¶ Parses a layout from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parselayout
: Set to the parsed layout
-
int32_t
tiledb_filter_type_to_str
(tiledb_filter_type_t filter_type, const char **str)¶ Returns a string representation of the given filter type.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
filter_type
: Filter typestr
: Set to point to a constant string representation of the filter type
-
int32_t
tiledb_filter_type_from_str
(const char *str, tiledb_filter_type_t *filter_type)¶ Parses a filter type from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parsefilter_type
: Set to the parsed filter type
-
int32_t
tiledb_filter_option_to_str
(tiledb_filter_option_t filter_option, const char **str)¶ Returns a string representation of the given filter option.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
filter_option
: Filter optionstr
: Set to point to a constant string representation of the filter option
-
int32_t
tiledb_filter_option_from_str
(const char *str, tiledb_filter_option_t *filter_option)¶ Parses a filter option from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parsefilter_option
: Set to the parsed filter option
-
int32_t
tiledb_encryption_type_to_str
(tiledb_encryption_type_t encryption_type, const char **str)¶ Returns a string representation of the given encryption type.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
encryption_type
: Encryption typestr
: Set to point to a constant string representation of the encryption type
-
int32_t
tiledb_encryption_type_from_str
(const char *str, tiledb_encryption_type_t *encryption_type)¶ Parses a encryption type from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parseencryption_type
: Set to the parsed encryption type
-
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.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
query_status
: Query statusstr
: Set to point to a constant string representation of the query status
-
int32_t
tiledb_query_status_from_str
(const char *str, tiledb_query_status_t *query_status)¶ Parses a query status from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parsequery_status
: Set to the parsed query status
-
int32_t
tiledb_walk_order_to_str
(tiledb_walk_order_t walk_order, const char **str)¶ Returns a string representation of the given walk order.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
walk_order
: Walk orderstr
: Set to point to a constant string representation of the walk order
-
int32_t
tiledb_walk_order_from_str
(const char *str, tiledb_walk_order_t *walk_order)¶ Parses a walk order from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parsewalk_order
: Set to the parsed walk order
-
int32_t
tiledb_vfs_mode_to_str
(tiledb_vfs_mode_t vfs_mode, const char **str)¶ Returns a string representation of the given VFS mode.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
vfs_mode
: VFS modestr
: Set to point to a constant string representation of the VFS mode
-
int32_t
tiledb_vfs_mode_from_str
(const char *str, tiledb_vfs_mode_t *vfs_mode)¶ Parses a VFS mode from the given string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
str
: String representation to parsevfs_mode
: Set to the parsed VFS mode
Context¶
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
config
: The configuration parameters (NULL
means default).ctx
: The TileDB context to be created.
-
void
tiledb_ctx_free
(tiledb_ctx_t **ctx)¶ Destroys the TileDB context, freeing all associated memory and resources.
Example:
tiledb_ctx_t* ctx; tiledb_ctx_alloc(NULL, &ctx); tiledb_ctx_free(&ctx);
- Parameters
ctx
: The TileDB context to be freed.
-
int32_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); // Make sure to free the retrieved `stats_json`
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.stats_json
: The output json. The caller takes ownership of the c-string.
-
int32_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
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.config
: The config to be retrieved.
-
int32_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
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.err
: The last error, orNULL
if no error has been raised.
-
int32_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_HDFS, &is_supported);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fs
: The filesystem to be checked.is_supported
: Sets it to1
if the filesystem is supported, and0
otherwise.
-
int32_t
tiledb_ctx_cancel_tasks
(tiledb_ctx_t *ctx)¶ Cancels all background or async tasks associated with the given context.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.
-
int32_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");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.key
: The tag keyvalue
: The tag value.
Config¶
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
config
: The config to be created.error
: Error object returned upon error (NULL
if there is no error).
-
void
tiledb_config_free
(tiledb_config_t **config)¶ Frees a TileDB config.
Example:
tiledb_config_t* config; tiledb_error_t* error = NULL; tiledb_config_alloc(&config, &error); tiledb_config_free(&config);
- Parameters
config
: The config to be freed.
-
int32_t
tiledb_config_set
(tiledb_config_t *config, const char *param, const char *value, tiledb_error_t **error)¶ Sets a config parameter.
Parameters
sm.dedup_coords
If
true
, cells with duplicate coordinates will be removed during sparse fragment writes. Note that ties during deduplication are broken arbitrarily. Default: falsesm.check_coord_dups
This is applicable only if
sm.dedup_coords
isfalse
. Iftrue
, an error will be thrown if there are cells with duplicate coordinates during sparse fragmnet writes. Iffalse
and there are duplicates, the duplicates will be written without errors. Default: truesm.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: truesm.read_range_oob
If
error
, this will check ranges for read with out-of-bounds on the dimension domain’s. Ifwarn
, the ranges will be capped at the dimension’s domain and a warning logged. Default: warnsm.check_global_order
Checks if the coordinates obey the global array order. Applicable only to sparse writes in global order.
Default: truesm.tile_cache_size
The tile cache size in bytes. Any
uint64_t
value is acceptable. Default: 10,000,000sm.enable_signal_handlers
Determines whether or not TileDB will install signal handlers.
Default: truesm.compute_concurrency_level
Upper-bound on number of threads to allocate for compute-bound tasks.
Default*: # coresUpper-bound on number of threads to allocate for IO-bound tasks.
**Default*: # cores
The vacuuming mode, one of
(remove consolidated fragments), (remove only consolidated fragment metadata), or (remove consolidated array metadata files).**Default
: fragmentssm.consolidation_mode
The consolidation mode, one of
fragments
(consolidate all fragments),fragment_meta
(consolidate only fragment metadata footers to a single file), orarray_meta
(consolidate array 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.0sm.consolidation.buffer_size
The size (in bytes) of the attribute buffers used during consolidation.
Default: 50,000,000sm.consolidation.steps
The number of consolidation steps to be performed when executing the consolidation algorithm.
Default: 1sm.consolidation.step_min_frags
The minimum number of fragments to consolidate in a single step.
Default: UINT32_MAXsm.consolidation.step_max_frags
The maximum number of fragments to consolidate in a single step.
Default: UINT32_MAXsm.consolidation.step_size_ratio
The size ratio that two (“adjacent”) fragments must satisfy to be considered for consolidation in a single step.
Default: 0.0sm.consolidation.timestamp_start
ExperimentalWhen set, an array will be consolidated between this value and
sm.consolidation.timestamp_end
(inclusive).Only for
fragments
andarray_meta
consolidation mode. Default: 0sm.consolidation.timestamp_end
ExperimentalWhen set, an array will be consolidated between
sm.consolidation.timestamp_start
and this value (inclusive).Only for
fragments
andarray_meta
consolidation mode. Default: UINT64_MAXsm.consolidation.with_timestamps
ExperimentalConsolidation with timestamps will include, for each cells, the timestamp at which the cell was written.
Default: “false”sm.memory_budget
The memory budget for tiles of fixed-sized attributes (or offsets for var-sized attributes) to be fetched during reads.
Default: 5GBsm.memory_budget_var
The memory budget for tiles of var-sized attributes to be fetched during reads.
Default: 10GBsm.var_offsets.bitsize
The size of offsets in bits to be used for offset buffers of var-sized attributes
Default: 64sm.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: falsesm.var_offsets.mode
The offsets format (
bytes
orelements
) to be used for var-sized attributes.Default: bytessm.query.dense.reader
Which reader to use for dense queries. “refactored” or “legacy”.
Default: refactoredsm.query.sparse_global_order.reader
Which reader to use for sparse global order queries. “refactored” or “legacy”.
Default: legacysm.query.sparse_unordered_with_dups.reader
Which reader to use for sparse unordered with dups queries. “refactored” or “legacy”.
Default: refactoredsm.mem.malloc_trim
Should malloc_trim be called on context and query destruction? This might reduce residual memory usage.
Default: truesm.mem.total_budget
Memory budget for readers and writers.
Default: 10GBsm.mem.reader.sparse_global_order.ratio_coords
Ratio of the budget allocated for coordinates in the sparse global order reader.
Default: 0.5sm.mem.reader.sparse_global_order.ratio_query_condition
Ratio of the budget allocated for the query condition in the sparse global order reader.
Default: 0.25sm.mem.reader.sparse_global_order.ratio_tile_ranges
Ratio of the budget allocated for tile ranges in the sparse global order reader.
Default: 0.1sm.mem.reader.sparse_global_order.ratio_array_data
Ratio of the budget allocated for array data in the sparse global order reader.
Default: 0.1sm.mem.reader.sparse_unordered_with_dups.ratio_coords
Ratio of the budget allocated for coordinates in the sparse unordered with duplicates reader.
Default: 0.5sm.mem.reader.sparse_unordered_with_dups.ratio_query_condition
Ratio of the budget allocated for the query condition in the sparse unordered with duplicates reader.
Default: 0.25sm.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.1sm.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: 102400sm.group.timestamp_start
The start timestamp used for opening the group.
Default: 0sm.group.timestamp_end
The end timestamp used for opening the group.
Also used for the write timestamp if set.
Default: UINT64_MAXvfs.read_ahead_cache_size
The the total maximum size of the read-ahead cache, which is an LRU.
Default: 10485760vfs.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: 10MBvfs.max_batch_size
The maximum number of bytes in a VFS read operation
Default: UINT64_MAXvfs.min_batch_size
The minimum number of bytes in a VFS read operation
Default: 20MBvfs.min_batch_gap
The minimum number of bytes between two VFS read batches.
Default: 500KBvfs.file.posix_file_permissions
Permissions to use for posix file system with file creation.
Default: 644vfs.file.posix_directory_permissions
Permissions to use for posix file system with directory creation.
Default: 755vfs.file.max_parallel_ops
The maximum number of parallel operations on objects with
URIs. Default:
sm.io_concurrency_level
vfs.azure.storage_account_name
Set the Azure Storage Account name.
Default: “”vfs.azure.storage_account_key
Set the Azure Storage Account key.
Default: “”vfs.azure.storage_sas_token
Set the Azure Storage SAS (shared access signature) token.
Default: “”vfs.azure.blob_endpoint
Overrides the default Azure Storage Blob endpoint. If empty, the endpoint will be constructed from the storage account name. This should not include an
http:// or https:// prefix. 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.use_https
Determines if the blob endpoint should use HTTP or HTTPS.
Default: “true”vfs.gcs.project_id
Set the GCS project id.
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.s3.region
The S3 region, if S3 is enabled.
Default: us-east-1vfs.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
orhttps
), if S3 is enabled. Default: httpsvfs.s3.endpoint_override
The S3 endpoint, if S3 is enabled.
Default: “”vfs.s3.use_virtual_addressing
The S3 use of virtual addressing (
true
orfalse
), if S3 is enabled. Default: truevfs.s3.skip_init
Skip Aws::InitAPI for the S3 layer (
true
orfalse
) Default: falsevfs.s3.use_multipart_upload
The S3 use of multi-part upload requests (
true
orfalse
), if S3 is enabled. Default: truevfs.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: 5MBvfs.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: 3000vfs.s3.connect_max_tries
The maximum tries for a connection. Any
long
value is acceptable. Default: 5vfs.s3.connect_scale_factor
The scale factor for exponential backoff when connecting to S3. Any
long
value is acceptable. Default: 25vfs.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: “”vfs.s3.request_timeout_ms
The request timeout in ms. Any
long
value is acceptable. Default: 3000vfs.s3.requester_pays
The requester pays for the S3 access charges.
Default: falsevfs.s3.proxy_host
The S3 proxy host.
Default: “”vfs.s3.proxy_port
The S3 proxy port.
Default: 0vfs.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.sse
The server-side encryption algorithm to use. Supported non-empty values are “aes256” and “kms” (AWS key management service).
Default: “”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.hdfs.name_node_uri"
Name node for HDFS.
Default: “”vfs.hdfs.username
HDFS username.
Default: “”vfs.hdfs.kerb_ticket_cache_path
HDFS kerb ticket cache path.
Default: “”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” otherwiseconfig.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: falserest.creation_access_credentials_name
The name of the registered access key to use for creation of the REST server.
Default: no default setrest.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: 3rest.retry_initial_delay_ms
Initial delay in milliseconds to wait until retrying a REST request
Default: 500rest.retry_delay_factor
The delay factor to exponentially wait until further retries of a failed REST request
Default: 1.25rest.curl.verbose
Set curl to run in verbose mode for REST requests
curl will print to stdout with this option
Default: falsefilestore.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.tile_cache_size", "1000000", &error);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
config
: The config object.param
: The parameter to be set.value
: The value of the parameter to be set.error
: Error object returned upon error (NULL
if there is no error).
-
int32_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.tile_cache_size", &value, &error);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
config
: The config object.param
: The parameter to be set.value
: A pointer to the value of the parameter to be retrieved (NULL
if it does not exist).error
: Error object returned upon error (NULL
if there is no error).
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
config
: The config object.filename
: The name of the file.error
: Error object returned upon error (NULL
if there is no error).
-
int32_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.tile_cache_size", &error);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
config
: The config object.param
: The parameter to be unset.error
: Error object returned upon error (NULL
if there is no error).
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
config
: The config object.filename
: The name of the file.error
: Error object returned upon error (NULL
if there is no error).
Config Iterator¶
-
int32_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 retrievingvfs.s3.region
as a parameter viatiledb_config_iter_here
, it will retrieveregion
.tiledb_error_t* error = NULL; tiledb_config_iter_t* config_iter; tiledb_config_iter_alloc(config, "vfs.s3.", &config_iter, &error);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
config
: A config object the iterator will operate on.prefix
: If notNULL
, only the config parameters starting withprefix*
will be iterated on. Moreover, the prefix will be stripped from the parameters. Otherwise, all parameters will be iterated on and their full name will be retrieved.config_iter
: The config iterator to be created.error
: Error object returned upon error (NULL
if there is no error).
-
void
tiledb_config_iter_free
(tiledb_config_iter_t **config_iter)¶ Frees a config iterator.
Example:
tiledb_config_iter_free(&config_iter);
- Parameters
config_iter
: The config iterator to be freed.
-
int32_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, ¶m, &value, &error);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
config_iter
: The config iterator.param
: The config parameter to be retrieved (NULL
if the iterator is at the end).value
: The config value to be retrieved (NULL
if the iterator is at the end).error
: Error object returned upon error (NULL
if there is no error).
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
config_iter
: The config iterator.error
: Error object returned upon error (NULL
if there is no error).
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
config_iter
: The config iterator.done
: Sets this to1
if the iterator is done,0
otherwise.error
: Error object returned upon error (NULL
if there is no error).
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
config
: A config object the iterator will operate on.config_iter
: The config iterator to be reset.prefix
: If notNULL
, only the config parameters starting withprefix*
will be iterated on. Moreover, the prefix will be stripped from the parameters. Otherwise, all parameters will be iterated on and their full name will be retrieved.error
: Error object returned upon error (NULL
if there is no error).
Error¶
-
int32_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.
tiledb_error_t* err = NULL; tiledb_ctx_get_last_error(ctx, &err); const char* msg; tiledb_error_message(err, &msg); printf("%s\n", msg);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
err
: A TileDB error object.errmsg
: A constant pointer to the error message.
-
void
tiledb_error_free
(tiledb_error_t **err)¶ Frees the resources associated with a TileDB error object.
Example:
tiledb_error_t* err = NULL; tiledb_ctx_get_last_error(ctx, &err); const char* msg; tiledb_error_message(err, &msg); printf("%s\n", msg); tiledb_error_free(&err);
- Parameters
err
: The TileDB error object.
Array¶
-
int32_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, "hdfs:///tiledb_arrays/my_array", &array);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_uri
: The array URI.array
: The array object to be created.
-
int32_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 differenttiledb_array_t
objects created and opened with different query types.Example:
tiledb_array_t* array; tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); tiledb_array_open(ctx, array, TILEDB_READ);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- 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
: The TileDB context.array
: The array object to be opened.query_type
: The type of queries the array object will be receiving.
-
int32_t
tiledb_array_open_with_key
(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_query_type_t query_type, tiledb_encryption_type_t encryption_type, const void *encryption_key, uint32_t key_length)¶ Opens an encrypted array using the given encryption key. This function has the same semantics as
tiledb_array_open()
but is used for encrypted arrays.An encrypted array must be opened with this function before queries can be issued to it.
Example:
// Load AES-256 key from disk, environment variable, etc. uint8_t key[32] = ...; tiledb_array_t* array; tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); tiledb_array_open_with_key(ctx, array, TILEDB_READ, TILEDB_AES_256_GCM, key, sizeof(key));
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
The config should be set before opening an array.
- Parameters
ctx
: The TileDB context.array
: The array object to be opened.query_type
: The type of queries the array object will be receiving.encryption_type
: The encryption type to use.encryption_key
: The encryption key to use.key_length
: Length in bytes of the encryption key.
-
int32_t
tiledb_array_open_at
(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_query_type_t query_type, uint64_t timestamp)¶ Similar to
tiledb_array_open
, but this function takes as input a timestamp, representing time in milliseconds ellapsed since 1970-01-01 00:00:00 +0000 (UTC). Opening the array at a timestamp provides a view of the array with all writes/updates that happened at or beforetimestamp
(i.e., excluding those that occurred aftertimestamp
). This function is useful to ensure consistency at a potential distributed setting, where machines need to operate on the same view of the array.Example:
tiledb_array_t* array; tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); // Assuming `timestamp` is time represented in milliseconds: tiledb_array_open_at(ctx, array, TILEDB_READ, timestamp);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
If the same array object is opened again without being closed, an error will be thrown.
- Note
This function is applicable only to read queries.
- 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
: The TileDB context.array
: The array object to be opened.query_type
: The type of queries the array object will be receiving.timestamp
: The timestamp to open the array at.
-
int32_t
tiledb_array_open_at_with_key
(tiledb_ctx_t *ctx, tiledb_array_t *array, tiledb_query_type_t query_type, tiledb_encryption_type_t encryption_type, const void *encryption_key, uint32_t key_length, uint64_t timestamp)¶ Similar to
tiledb_array_open_with_key
, but this function takes as input a timestamp, representing time in milliseconds ellapsed since 1970-01-01 00:00:00 +0000 (UTC). Opening the array at a timestamp provides a view of the array with all writes/updates that happened at or beforetimestamp
(i.e., excluding those that occurred aftertimestamp
). This function is useful to ensure consistency at a potential distributed setting, where machines need to operate on the same view of the array.Example:
// Load AES-256 key from disk, environment variable, etc. uint8_t key[32] = ...; tiledb_array_t* array; tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); // Assuming `timestamp` is time represented in milliseconds: tiledb_array_open_at_with_key(ctx, array, TILEDB_READ, TILEDB_AES_256_GCM, key, sizeof(key), timestamp);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
If the same array object is opened again without being closed, an error will be thrown.
- Note
This function is applicable only to read queries.
- Note
The config should be set before opening an array.
- Parameters
ctx
: The TileDB context.array
: The array object to be opened.query_type
: The type of queries the array object will be receiving.encryption_type
: The encryption type to use.encryption_key
: The encryption key to use.key_length
: Length in bytes of the encryption key.timestamp
: The timestamp to open the array at.
-
int32_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 withtiledb_array_open
, or just usetiledb_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, "hdfs:///tiledb_arrays/my_array", &array); tiledb_array_open(ctx, array, TILEDB_READ); tiledb_array_reopen(ctx, array);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- 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
: The TileDB context.array
: The array object to be re-opened.
-
int32_t
tiledb_array_reopen_at
(tiledb_ctx_t *ctx, tiledb_array_t *array, uint64_t timestamp)¶ Reopens a TileDB array (the array must be already open) at a specific timestamp.
Example:
tiledb_array_t* array; tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); tiledb_array_open(ctx, array, TILEDB_READ); uint64_t timestamp = tiledb_timestamp_now_ms(); tiledb_array_reopen_at(ctx, array, timestamp);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- 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
: The TileDB context.array
: The array object to be re-opened.timestamp
: Timestamp at which to reopen.
-
int32_t
tiledb_array_get_timestamp
(tiledb_ctx_t *ctx, tiledb_array_t *array, uint64_t *timestamp)¶ The start/end timestamps for opening an array are now set in the config.
Returns the timestamp, representing time in milliseconds ellapsed since 1970-01-01 00:00:00 +0000 (UTC), at which the array was opened. See also the documentation of
tiledb_array_open_at
.Example:
tiledb_array_t* array; tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array); tiledb_array_open(ctx, array, TILEDB_READ); // Get the timestamp the array at which the array was opened. uint64_t timestamp; tiledb_array_get_timestamp(ctx, array, ×tamp);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
The array does not need to be open to use this function.
- Parameters
ctx
: The TileDB context.array
: The array to retrieve the timestamp for.timestamp
: Set to the timestamp at which the array was opened.
-
int32_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, "hdfs:///tiledb_arrays/my_array", &array); tiledb_array_open(ctx, array, TILEDB_READ); tiledb_array_close(ctx, array);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
If the array object has already been closed, the function has no effect.
- Parameters
ctx
: The TileDB context.array
: The array object to be closed.
-
void
tiledb_array_free
(tiledb_array_t **array)¶ Frees a TileDB array object.
Example:
tiledb_array_t* array; tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); tiledb_array_open(ctx, array, TILEDB_READ); tiledb_array_close(ctx, array); tiledb_array_free(&array);
- Parameters
array
: The array object to be freed.
-
int32_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, "hdfs:///tiledb_arrays/my_array", array_schema);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_uri
: The array name.array_schema
: The array schema.
-
int32_t
tiledb_array_create_with_key
(tiledb_ctx_t *ctx, const char *array_uri, const tiledb_array_schema_t *array_schema, tiledb_encryption_type_t encryption_type, const void *encryption_key, uint32_t key_length)¶ Creates a new encrypted TileDB array given an input schema.
Encrypted arrays can only be created through this function.
Example:
uint8_t key[32] = ...; tiledb_array_create_with_key( ctx, "hdfs:///tiledb_arrays/my_array", array_schema, TILEDB_AES_256_GCM, key, sizeof(key));
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_uri
: The array name.array_schema
: The array schema.encryption_type
: The encryption type to use.encryption_key
: The encryption key to use.key_length
: Length in bytes of the encryption key.
-
int32_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, "hdfs:///tiledb_arrays/my_array", nullptr);
- Return
TILEDB_OK
on success, andTILEDB_ERR
on error.- Parameters
ctx
: The TileDB context.array_uri
: The name of the TileDB array whose metadata will be consolidated.config
: Configuration parameters for the consolidation (nullptr
means default, which will use the config fromctx
). Thesm.consolidation.mode
parameter determines which type of consolidation to perform.
-
int32_t
tiledb_array_consolidate_with_key
(tiledb_ctx_t *ctx, const char *array_uri, tiledb_encryption_type_t encryption_type, const void *encryption_key, uint32_t key_length, 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:
uint8_t key[32] = ...; tiledb_array_consolidate_with_key( ctx, "hdfs:///tiledb_arrays/my_array", TILEDB_AES_256_GCM, key, sizeof(key), nullptr);
- Return
TILEDB_OK
on success, andTILEDB_ERR
on error.- Parameters
ctx
: The TileDB context.array_uri
: The name of the TileDB array to be consolidated.encryption_type
: The encryption type to use.encryption_key
: The encryption key to use.key_length
: Length in bytes of the encryption key.config
: Configuration parameters for the consolidation (nullptr
means default, which will use the config fromctx
). Thesm.consolidation.mode
parameter determines which type of consolidation to perform.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Note
The user must free the array schema with
tiledb_array_schema_free
.- Parameters
ctx
: The TileDB context.array
: The open array.array_schema
: The array schema to be retrieved.
-
int32_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, "hdfs:///tiledb_arrays/my_array", &array); tiledb_array_open(ctx, array, TILEDB_READ); tiledb_query_type_t query_type; tiledb_array_get_type(ctx, array, &query_type);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array
: The array.query_type
: The query type to be retrieved.
-
int32_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.
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextarray
: The array object (must be opened beforehand).domain
: The domain to be retrieved.is_empty
: The function sets it to1
if the non-empty domain is empty (i.e., the array does not contain any data yet), and0
otherwise.
-
int32_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.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array
: The input array.array_uri
: The array URI to be retrieved.
-
int32_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.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_uri
: The array URI.encryption_type
: The array encryption type to be retrieved.
-
int32_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.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
The writes will take effect only upon closing the array.
- Parameters
ctx
: The TileDB context.array
: An array opened in WRITE mode.key
: The key of the metadata item to be added. UTF-8 encodings are acceptable.value_type
: The datatype of the value.value_num
: 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
: The metadata value in binary form.
-
int32_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.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
If the key does not exist, then
value
will be NULL.- Parameters
ctx
: The TileDB context.array
: An array opened in READ mode.key
: The key of the metadata item to be retrieved. UTF-8 encodings are acceptable.value_type
: The datatype of the value.value_num
: 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
: The metadata value in binary form.
-
int32_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.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array
: An array opened in READ mode.index
: The index used to get the metadata.key
: The metadata key.key_len
: The metadata key length.value_type
: The datatype of the value.value_num
: 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
: The metadata value in binary form.
-
int32_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.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array
: An array opened in READ mode.num
: The number of metadata items to be retrieved.
-
int32_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.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- 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
: The TileDB context.array
: An array opened in WRITE mode.key
: The key of the metadata item to be deleted.
-
int32_t
tiledb_array_consolidate_metadata
(tiledb_ctx_t *ctx, const char *array_uri, tiledb_config_t *config)¶ Consolidates the array metadata into a single array metadata file.
Example:
tiledb_array_consolidate_metadata( ctx, "hdfs:///tiledb_arrays/my_array", nullptr);
- Return
TILEDB_OK
on success, andTILEDB_ERR
on error.- Parameters
ctx
: The TileDB context.array_uri
: The name of the TileDB array whose metadata will be consolidated.config
: Configuration parameters for the consolidation (nullptr
means default, which will use the config fromctx
).
-
int32_t
tiledb_array_consolidate_metadata_with_key
(tiledb_ctx_t *ctx, const char *array_uri, tiledb_encryption_type_t encryption_type, const void *encryption_key, uint32_t key_length, tiledb_config_t *config)¶ Consolidates the array metadata of an encrypted array into a single file.
Example:
uint8_t key[32] = ...; tiledb_array_consolidate_metadata_with_key( ctx, "hdfs:///tiledb_arrays/my_array", TILEDB_AES_256_GCM, key, sizeof(key), nullptr);
- Return
TILEDB_OK
on success, andTILEDB_ERR
on error.- Parameters
ctx
: The TileDB context.array_uri
: The name of the TileDB array to be consolidated.encryption_type
: The encryption type to use.encryption_key
: The encryption key to use.key_length
: Length in bytes of the encryption key.config
: Configuration parameters for the consolidation (nullptr
means default, which will use the config fromctx
).
Array Schema¶
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_type
: The array type.array_schema
: The TileDB array schema to be created.
-
void
tiledb_array_schema_free
(tiledb_array_schema_t **array_schema)¶ Destroys an array schema, freeing associated memory.
Example:
tiledb_array_schema_free(&array_schema);
- Parameters
array_schema
: The array schema to be destroyed.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.attr
: The attribute to be added.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.domain
: The domain to be set.
-
int32_t
tiledb_array_schema_set_capacity
(tiledb_ctx_t *ctx, tiledb_array_schema_t *array_schema, uint64_t capacity)¶ Sets the tile capacity.
Example:
tiledb_array_schema_set_capacity(ctx, array_schema, 10000);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.capacity
: The capacity of a sparse data tile. Note that sparse data tiles exist in sparse fragments, which can be created in both sparse and dense arrays. For more details, see tutorials/tiling-sparse.html.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.cell_order
: The cell order to be set.
-
int32_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_cell_order(ctx, array_schema, TILEDB_COL_MAJOR);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.tile_order
: The tile order to be set.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.filter_list
: The filter list to be set.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.filter_list
: The filter list to be set.
-
int32_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);
- Return
TILEDB_OK
if the array schema is correct andTILEDB_ERR
upon any error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.
-
int32_t
tiledb_array_schema_load
(tiledb_ctx_t *ctx, const char *array_uri, tiledb_array_schema_t **array_schema)¶ Retrieves the schema of an array from the disk, creating an array schema struct.
Example:
tiledb_array_schema_t* array_schema; tiledb_array_schema_load(ctx, "s3://tiledb_bucket/my_array", &array_schema); // Make sure to free the array schema in the end
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_uri
: The array whose schema will be retrieved.array_schema
: The array schema to be retrieved, orNULL
upon error.
-
int32_t
tiledb_array_schema_load_with_key
(tiledb_ctx_t *ctx, const char *array_uri, tiledb_encryption_type_t encryption_type, const void *encryption_key, uint32_t key_length, tiledb_array_schema_t **array_schema)¶ Retrieves the schema of an encrypted array from the disk, creating an array schema struct.
Example:
// Load AES-256 key from disk, environment variable, etc. uint8_t key[32] = ...; tiledb_array_schema_t* array_schema; tiledb_array_schema_load_with_key( ctx, "s3://tiledb_bucket/my_array", TILEDB_AES_256_GCM, key, sizeof(key), &array_schema); // Make sure to free the array schema in the end
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_uri
: The array whose schema will be retrieved.encryption_type
: The encryption type to use.encryption_key
: The encryption key to use.key_length
: Length in bytes of the encryption key.array_schema
: The array schema to be retrieved, orNULL
upon error.
-
int32_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
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.array_type
: The array type to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.capacity
: The capacity to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.cell_order
: The cell order to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.filter_list
: The filter list to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.filter_list
: The filter list to be retrieved.
-
int32_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); // Make sure to delete domain in the end
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.domain
: The array domain to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.tile_order
: The tile order to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.attribute_num
: The number of attributes to be retrieved.
-
int32_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); // Make sure to delete the retrieved attribute in the end.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.index
: The index of the attribute to retrieve.attr
: The attribute object to retrieve.
-
int32_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 first attribute in the schema.
tiledb_attribute_t* attr; tiledb_array_schema_get_attribute_from_name( ctx, array_schema, "attr_0", &attr); // Make sure to delete the retrieved attribute in the end.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.name
: The name (key) of the attribute to retrieve.attr
: THe attribute object to retrieve.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.name
: The name of the attribute to check for.has_attr
: Set to1
if the array schema has an attribute of the given name, else0
.
-
int32_t
tiledb_array_schema_dump
(tiledb_ctx_t *ctx, const tiledb_array_schema_t *array_schema, FILE *out)¶ Dumps the array schema in ASCII format in the selected output.
Example:
The following prints the array schema dump in standard output.
tiledb_array_schema_dump(ctx, array_schema, stdout);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_schema
: The array schema.out
: The output.
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);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Note
The default number of values per cell is 1.
- Parameters
ctx
: The TileDB context.name
: The attribute name. Providing an empty string for the name creates an anonymous attribute.type
: The attribute type.attr
: The TileDB attribute to be created.
-
void
tiledb_attribute_free
(tiledb_attribute_t **attr)¶ Destroys a TileDB attribute, freeing associated memory.
Example:
tiledb_attribute_t* attr; tiledb_attribute_alloc(ctx, "my_attr", TILEDB_INT32, &attr); tiledb_attribute_free(&attr);
- Parameters
attr
: The attribute to be destroyed.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.attr
: The target attribute.nullable
: Non-zero if the attribute is nullable.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.attr
: The target attribute.filter_list
: The filter_list to be set.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.attr
: The target attribute.cell_val_num
: The number of values per cell.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.attr
: The attribute.name
: The name to be retrieved.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.attr
: The attribute.type
: The type to be retrieved.
-
int32_t
tiledb_attribute_get_nullable
(tiledb_ctx_t *ctx, tiledb_attribute_t *attr, uint8_t *nullable)¶ Sets the nullability of an attribute.
Example:
uint8_t nullable; tiledb_attribute_get_nullable(ctx, attr, &nullable);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.attr
: The target attribute.nullable
: Output argument, non-zero for nullable and zero for non-nullable.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.attr
: The target attribute.filter_list
: The filter list to be retrieved.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.attr
: The attribute.cell_val_num
: The number of values per cell to be retrieved.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.attr
: The attribute.cell_size
: The cell size to be retrieved.
-
int32_t
tiledb_attribute_dump
(tiledb_ctx_t *ctx, const tiledb_attribute_t *attr, FILE *out)¶ Dumps the contents of an attribute in ASCII form to some output (e.g., file or stdout).
Example:
The following prints the attribute dump to standard output.
tiledb_attribute_dump(ctx, attr, stdout);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error./- Parameters
ctx
: The TileDB context.attr
: The attribute.out
: The output.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
A call to
tiledb_attribute_cell_val_num
sets the fill value of the attribute to its default. Therefore, make sure you invoketiledb_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.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- 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.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
A call to
tiledb_attribute_cell_val_num
sets the fill value of the attribute to its default. Therefore, make sure you invoketiledb_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.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- 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.
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);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.domain
: The TileDB domain to be created.
-
void
tiledb_domain_free
(tiledb_domain_t **domain)¶ Destroys a TileDB domain, freeing associated memory.
Example:
tiledb_domain_t* domain; tiledb_domain_alloc(ctx, &domain); tiledb_domain_free(&domain);
- Parameters
domain
: The domain to be destroyed.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.domain
: The domain.type
: The type to be retrieved.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextdomain
: The domainndim
: The number of dimensions in a domain.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.domain
: The domain to add the dimension to.dim
: The dimension to be added.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextdomain
: The domain to add the dimension to.index
: The index of domain dimensiondim
: The retrieved dimension object.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextdomain
: The domain to add the dimension to.name
: The name (key) of the requested dimensiondim
: The retrieved dimension object.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.domain
: The domain.name
: The name of the dimension to check for.has_dim
: Set to1
if the domain has a dimension of the given name, else0
.
-
int32_t
tiledb_domain_dump
(tiledb_ctx_t *ctx, const tiledb_domain_t *domain, FILE *out)¶ Dumps the info of a domain in ASCII form to some output (e.g., file or
stdout
).Example:
The following prints the domain dump to the standard output.
tiledb_domain_dump(ctx, domain, stdout);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.domain
: The domain.out
: The output.
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.name
: The dimension name.type
: The dimension type.dim_domain
: The dimension domain.tile_extent
: The dimension tile extent.dim
: The dimension to be created.
-
void
tiledb_dimension_free
(tiledb_dimension_t **dim)¶ Destroys a TileDB dimension, freeing associated memory.
Example:
tiledb_dimension_free(&dim);
- Parameters
dim
: The dimension to be destroyed.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.dim
: The dimension.name
: The name to be retrieved.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.dim
: The dimension.type
: The type to be retrieved.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.dim
: The dimension.domain
: The domain to be retrieved. Note that the defined type of inputdomain
must be the same as the dimension type, otherwise the behavior is unpredictable (it will probably segfault).
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.dim
: The dimension.cell_val_num
: The number of values per cell to be retrieved.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.dim
: The target dimension.cell_val_num
: The number of values per cell.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.dim
: The target dimension.filter_list
: The filter list to be retrieved.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.dim
: The target dimension.filter_list
: The filter_list to be set.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.dim
: The dimension.tile_extent
: The tile extent (pointer) to be retrieved.
-
int32_t
tiledb_dimension_dump
(tiledb_ctx_t *ctx, const tiledb_dimension_t *dim, FILE *out)¶ Dumps the contents of a dimension in ASCII form to some output (e.g., file or stdout).
Example:
The following prints the dimension dump to standard output.
tiledb_dimension_dump(ctx, dim, stdout);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.dim
: The dimension.out
: The output.
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);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.query
: The query object to be created.array
: An opened array object.query_type
: The query type. This must comply with the query typearray
was opened.
-
int32_t
tiledb_query_set_subarray
(tiledb_ctx_t *ctx, tiledb_query_t *query, const void *subarray)¶ Indicates that the query will write or read a subarray, and provides the appropriate information.
Example:
The following sets a 2D subarray [0,10], [20, 30] to the query.
uint64_t subarray[] = { 0, 10, 20, 30}; tiledb_query_set_subarray(ctx, query, subarray);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Note
If you set the subarray of a completed, incomplete or in-progress query, this function will clear the internal state and render it as uninitialized. However, the potentially set layout and attribute buffers will be retained. This is useful when the user wishes to fix the attributes and layout, but explore different subarrays with the same
tiledb_query_t
object (i.e., without having to create a new object).- Note
This function will error in the following case, provided that this is a write query: (i) the array is dense and the layout has been set to
TILEDB_UNORDERED
. In this case, if the user sets the layout toTILEDB_UNORDERED
after the subarray has been set, the subarray will simply be ignored.- Parameters
ctx
: The TileDB context.query
: The TileDB query.subarray
: The subarray in which the array read/write will be constrained on. It should be a sequence of [low, high] pairs (one pair per dimension). For the case of writes, this is meaningful only for dense arrays, and specifically dense writes. Note thatsubarray
must have the same type as the domain.
-
int32_t
tiledb_query_set_buffer
(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, void *buffer, uint64_t *buffer_size)¶ Sets the buffer for a fixed-sized 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.
Example:
int32_t a1[100]; uint64_t a1_size = sizeof(a1); tiledb_query_set_buffer(ctx, query, "a1", a1, &a1_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.query
: The TileDB query.name
: The attribute/dimension to set the buffer for. Note that zipped coordinates have special nameTILEDB_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 ofbuffer
in bytes. In the case of reads, this initially contains the allocated size ofbuffer
, but after the termination of the query it will contain the size of the useful (read) data inbuffer
.
-
int32_t
tiledb_query_set_buffer_var
(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, uint64_t *buffer_off, uint64_t *buffer_off_size, void *buffer_val, uint64_t *buffer_val_size)¶ Sets the buffer for a var-sized attribute/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.
Example:
uint64_t a2_off[10]; uint64_t a2_off_size = sizeof(a2_off); char a2_val[100]; uint64_t a2_val_size = sizeof(a2_val); tiledb_query_set_buffer_var( ctx, query, "a2", a2_off, &a2_off_size, a2_val, &a2_val_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.query
: The TileDB query.name
: The attribute/dimension to set the buffer for.buffer_off
: The buffer that either have the input data to be written, or will hold the data to be read. This buffer holds the starting offsets of each cell value inbuffer_val
.buffer_off_size
: In the case of writes, it is the size ofbuffer_off
in bytes. In the case of reads, this initially contains the allocated size ofbuffer_off
, but after the end of the query (tiledb_query_submit
) it will contain the size of the useful (read) data inbuffer_off
.buffer_val
: The buffer that either have the input data to be written, or will hold the data to be read. This buffer holds the actual var-sized cell values.buffer_val_size
: In the case of writes, it is the size ofbuffer_val
in bytes. In the case of reads, this initially contains the allocated size ofbuffer_val
, but after the termination of the function it will contain the size of the useful (read) data inbuffer_val
.
-
int32_t
tiledb_query_set_buffer_nullable
(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, void *buffer, uint64_t *buffer_size, uint8_t *buffer_validity_bytemap, uint64_t *buffer_validity_bytemap_size)¶ Sets the buffer for a fixed-sized, nullable attribute to a query, which will either hold the values to be written (if it is a write query), or will hold the results from a read query. The validity buffer is a byte map, where each non-zero byte represents a valid (i.e. “non-null”) attribute value.
Example:
int32_t a1[100]; uint64_t a1_size = sizeof(a1); uint8_t a1_validity[100]; uint64_t a1_validity_size = sizeof(a1_validity); tiledb_query_set_buffer_nullable( ctx, query, "a1", a1, &a1_size, a1_validity, &a1_validity_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.query
: The TileDB query.name
: The attribute/dimension to set the buffer for. Note that zipped coordinates have special nameTILEDB_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 ofbuffer
in bytes. In the case of reads, this initially contains the allocated size ofbuffer
, but after the termination of the query it will contain the size of the useful (read) data inbuffer
.buffer_validity_bytemap
: The validity byte map that has exactly one value for each value inbuffer
.buffer_validity_bytemap_size
: In the case of writes, this is the size ofbuffer_validity_bytemap
in bytes. In the case of reads, this initially contains the allocated size ofbuffer_validity_bytemap
, but after the termination of the query it will contain the size of the useful (read) data inbuffer_validity_bytemap
.
-
int32_t
tiledb_query_set_buffer_var_nullable
(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, uint64_t *buffer_off, uint64_t *buffer_off_size, void *buffer_val, uint64_t *buffer_val_size, uint8_t *buffer_validity_bytemap, uint64_t *buffer_validity_bytemap_size)¶ Sets the buffer for a var-sized, nullable attribute to a query, which will either hold the values to be written (if it is a write query), or will hold the results from a read query.
Example:
uint64_t a2_off[10]; uint64_t a2_off_size = sizeof(a2_off); char a2_val[100]; uint64_t a2_val_size = sizeof(a2_val); uint8_t a2_validity[100]; uint64_t a2_validity_size = sizeof(a2_validity); tiledb_query_set_buffer_var( ctx, query, "a2", a2_off, &a2_off_size, a2_val, &a2_val_size, a2_validity, &a2_validity_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.query
: The TileDB query.name
: The attribute/dimension to set the buffer for.buffer_off
: The buffer that either have the input data to be written, or will hold the data to be read. This buffer holds the starting offsets of each cell value inbuffer_val
.buffer_off_size
: In the case of writes, it is the size ofbuffer_off
in bytes. In the case of reads, this initially contains the allocated size ofbuffer_off
, but after the end of the query (tiledb_query_submit
) it will contain the size of the useful (read) data inbuffer_off
.buffer_val
: The buffer that either have the input data to be written, or will hold the data to be read. This buffer holds the actual var-sized cell values.buffer_val_size
: In the case of writes, it is the size ofbuffer_val
in bytes. In the case of reads, this initially contains the allocated size ofbuffer_val
, but after the termination of the function it will contain the size of the useful (read) data inbuffer_val
.buffer_validity_bytemap
: The validity byte map that has exactly one value for each value inbuffer
.buffer_validity_bytemap_size
: In the case of writes, this is the size ofbuffer_validity_bytemap
in bytes. In the case of reads, this initially contains the allocated size ofbuffer_validity_bytemap
, but after the termination of the query it will contain the size of the useful (read) data inbuffer_validity_bytemap
.
-
int32_t
tiledb_query_get_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 tonullptr
.Example:
int* a1; uint64_t* a1_size; tiledb_query_get_buffer(ctx, query, "a1", &a1, &a1_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- 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 nameTILEDB_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 fromset_buffer
.
-
int32_t
tiledb_query_get_buffer_var
(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, uint64_t **buffer_off, uint64_t **buffer_off_size, void **buffer_val, uint64_t **buffer_val_size)¶ Gets the values and offsets buffers for a var-sized attribute/dimension to a query. If the buffers have not been set, then
buffer_off
andbuffer_val
are set tonullptr
.Example:
uint64_t* a2_off; uint64_t* a2_off_size; char* a2_val; uint64_t* a2_val_size; tiledb_query_get_buffer_var( ctx, query, "a2", &a2_off, &a2_off_size, &a2_val, &a2_val_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.query
: The TileDB query.name
: The attribute/dimension to set the buffer for.buffer_off
: The offsets buffer to be retrieved.buffer_off_size
: A pointer to the size of the offsets buffer. Note that this is auint_64**
pointer and returns the original variable address fromset_buffer
.buffer_val
: The values buffer to be retrieved.buffer_val_size
: A pointer to the size of the values buffer. Note that this is auint_64**
pointer and returns the original variable address fromset_buffer
.
-
int32_t
tiledb_query_get_buffer_nullable
(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, void **buffer, uint64_t **buffer_size, uint8_t **buffer_validity_bytemap, uint64_t **buffer_validity_bytemap_size)¶ Gets the buffer of a fixed-sized, nullable attribute from a query. If the buffer has not been set, then
buffer
andbuffer_validity_bytemap
are set tonullptr
.Example:
int* a1; uint64_t* a1_size; uint8_t* a1_validity; uint64_t* a1_validity_size; tiledb_query_get_buffer_nullable( ctx, query, "a1", &a1, &a1_size, &a1_validity, &a1_validity_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- 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 nameTILEDB_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 fromset_buffer
.buffer_validity_bytemap
: The validity bytemap buffer to retrieve.buffer_validity_bytemap_size
: A pointer to the size of the validity bytemap buffer. Note that this is a double pointer and returns the origina variable address fromset_buffer_nullable
.
-
int32_t
tiledb_query_get_buffer_var_nullable
(tiledb_ctx_t *ctx, tiledb_query_t *query, const char *name, uint64_t **buffer_off, uint64_t **buffer_off_size, void **buffer_val, uint64_t **buffer_val_size, uint8_t **buffer_validity_bytemap, uint64_t **buffer_validity_bytemap_size)¶ Gets the values and offsets buffers for a var-sized, nullable attribute to a query. If the buffers have not been set, then
buffer_off
,buffer_val
, andbuffer_validity_bytemap
are set tonullptr
.Example:
uint64_t* a2_off; uint64_t* a2_off_size; char* a2_val; uint64_t* a2_val_size; uint8_t* a2_validity; uint64_t* a2_validity_size; tiledb_query_get_buffer_var_nullable( ctx, query, "a2", &a2_off, &a2_off_size, &a2_val, &a2_val_size, &a2_validity, &a2_validity_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.query
: The TileDB query.name
: The attribute/dimension to set the buffer for.buffer_off
: The offsets buffer to be retrieved.buffer_off_size
: A pointer to the size of the offsets buffer. Note that this is auint_64**
pointer and returns the original variable address fromset_buffer
.buffer_val
: The values buffer to be retrieved.buffer_val_size
: A pointer to the size of the values buffer. Note that this is auint_64**
pointer and returns the original variable address fromset_buffer
.buffer_validity_bytemap
: The validity bytemap buffer to retrieve.buffer_validity_bytemap_size
: A pointer to the size of the validity bytemap buffer. Note that this is a double pointer and returns the origina variable address fromset_buffer_var_nullable
.
-
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_set_layout
(tiledb_ctx_t *ctx, tiledb_query_t *query, tiledb_layout_t layout)¶ Sets the layout of the cells to be written or read.
Example:
tiledb_query_set_layout(ctx, query, TILEDB_ROW_MAJOR);
- Return
TILEDB_OK
for success andTILEDB_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.
-
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_finalize
(tiledb_ctx_t *ctx, tiledb_query_t *query)¶ Flushes all internal state of a query object and finalizes the query. This is applicable only to global layout writes. It has no effect for any other query type.
Example:
tiledb_query_t* query; // ... Your code here ... // tiledb_query_finalize(ctx, query);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.query
: The query object to be flushed.
-
int32_t
tiledb_query_submit
(tiledb_ctx_t *ctx, tiledb_query_t *query)¶ Submits a TileDB query.
Example:
tiledb_query_submit(ctx, query);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
tiledb_query_finalize
must be invoked after finish writing in global layout (via repeated invocations oftiledb_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 withtiledb_query_set_buffer
, and then resubmit the query until the status becomesTILEDB_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 withtiledb_query_set_buffer
, and resubmit the query.- Parameters
ctx
: The TileDB context.query
: The query to be submitted.
-
int32_t
tiledb_query_submit_async
(tiledb_ctx_t *ctx, tiledb_query_t *query, void (*callback)(void*), void *callback_data, )¶ Submits a TileDB query in asynchronous mode.
Examples:
Submit without a callback.
tiledb_query_submit_async(ctx, query, NULL, NULL);
Submit with a callback function
print
that takes as input messagemsg
and prints it upon completion of the query.const char* msg = "Query completed"; tiledb_query_submit_async(ctx, &query, foo, msg);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Note
tiledb_query_finalize
must be invoked after finish writing in global layout (via repeated invocations oftiledb_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 withtiledb_query_set_buffer
, and then resubmit the query until the status becomesTILEDB_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 withtiledb_query_set_buffer
, and resubmit the query.- Parameters
ctx
: The TileDB context.query
: The query to be submitted.callback
: The function to be called when the query completes.callback_data
: The data to be passed to the callback function.
-
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);
- Return
TILEDB_OK
upon success, andTILEDB_ERR
upon error.- Parameters
ctx
: The TileDB context.query
: The query.status
: The query status to be retrieved.
-
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);
- Return
TILEDB_OK
upon success, andTILEDB_ERR
upon error.- Parameters
ctx
: The TileDB context.query
: The query.query_type
: The query type to be retrieved.
-
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);
- Return
TILEDB_OK
upon success, andTILEDB_ERR
upon error.- Parameters
ctx
: The TileDB context.query
: The query.query_layout
: The query layout to be retrieved.
-
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);
- Return
TILEDB_OK
upon success, andTILEDB_ERR
upon error.- Parameters
ctx
: The TileDB context.query
: The query.has_results
: Set to1
if the query returned results and0
otherwise.
-
int32_t
tiledb_query_add_range
(tiledb_ctx_t *ctx, tiledb_query_t *query, 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_query_add_range(ctx, query, dim_idx, &start, &end, nullptr);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
The stride is currently unsupported. Use
nullptr
as the stride argument.- Parameters
ctx
: The TileDB context.query
: The query to add the range to.dim_idx
: The index of the dimension to add the range to.start
: The range start.end
: The range end.stride
: The range stride.
-
int32_t
tiledb_query_add_range_by_name
(tiledb_ctx_t *ctx, tiledb_query_t *query, 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_query_add_range_by_name(ctx, query, dim_name, &start, &end, nullptr);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
The stride is currently unsupported. Use
nullptr
as the stride argument.- Parameters
ctx
: The TileDB context.query
: The query to add the range to.dim_name
: The name of the dimension to add the range to.start
: The range start.end
: The range end.stride
: The range stride.
-
int32_t
tiledb_query_get_range
(tiledb_ctx_t *ctx, const tiledb_query_t *query, uint32_t dim_idx, uint64_t range_idx, const void **start, const void **end, const void **stride)¶ Retrieves a specific range of the query subarray along a given dimension index.
Example:
const void* start; const void* end; const void* stride; tiledb_query_get_range( ctx, query, dim_idx, range_idx, &start, &end, &stride);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: The query.dim_idx
: The index of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start
: The range start to retrieve.end
: The range end to retrieve.stride
: The range stride to retrieve.
-
int32_t
tiledb_query_get_range_from_name
(tiledb_ctx_t *ctx, const tiledb_query_t *query, const char *dim_name, uint64_t range_idx, const void **start, const void **end, const void **stride)¶ Retrieves a specific range of the query subarray along a given dimension name.
Example:
const void* start; const void* end; const void* stride; tiledb_query_get_range_from_name( ctx, query, dim_name, range_idx, &start, &end, &stride);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: The query.dim_name
: The name of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start
: The range start to retrieve.end
: The range end to retrieve.stride
: The range stride to retrieve.
-
int32_t
tiledb_query_add_range_var
(tiledb_ctx_t *ctx, tiledb_query_t *query, 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_query_add_range_var(ctx, query, dim_idx, start, 1, end, 2);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.query
: The query to add the range to.dim_idx
: The index of the dimension to add the range to.start
: The range start.start_size
: The size of the range start in bytes.end
: The range end.end_size
: The size of the range end in bytes.
-
int32_t
tiledb_query_add_range_var_by_name
(tiledb_ctx_t *ctx, tiledb_query_t *query, 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_query_add_range_var_by_name(ctx, query, dim_name, start, 1, end, 2);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.query
: The query to add the range to.dim_name
: The name of the dimension to add the range to.start
: The range start.start_size
: The size of the range start in bytes.end
: The range end.end_size
: The size of the range end in bytes.
-
int32_t
tiledb_query_get_range_var
(tiledb_ctx_t *ctx, const tiledb_query_t *query, uint32_t dim_idx, uint64_t range_idx, void *start, void *end)¶ Retrieves a specific range of the query subarray along a given variable-length dimension index.
Example:
const void* start; const void* end; tiledb_query_get_range_var( ctx, query, dim_idx, range_idx, &start, &end);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: The query.dim_idx
: The index of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start
: The range start to retrieve.end
: The range end to retrieve.
-
int32_t
tiledb_query_get_range_var_from_name
(tiledb_ctx_t *ctx, const tiledb_query_t *query, const char *dim_name, uint64_t range_idx, void *start, void *end)¶ Retrieves a specific range of the query subarray along a given variable-length dimension name.
Example:
const void* start; const void* end; tiledb_query_get_range_var_from_name( ctx, query, dim_name, range_idx, &start, &end);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: The query.dim_name
: The name of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start
: The range start to retrieve.end
: The range end to retrieve.
-
int32_t
tiledb_query_get_range_var_size
(tiledb_ctx_t *ctx, const tiledb_query_t *query, 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_query_get_range_var_size( ctx, query, dim_idx, range_idx, &start_size, &end_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: The query.dim_idx
: The index of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start_size
: range start size in bytesend_size
: range end size in bytes
-
int32_t
tiledb_query_get_range_var_size_from_name
(tiledb_ctx_t *ctx, const tiledb_query_t *query, 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_query_get_range_var_size_from_name( ctx, query, dim_name, range_idx, &start_size, &end_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: The query.dim_name
: The name of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start_size
: range start size in bytesend_size
: range end size in bytes
-
int32_t
tiledb_query_get_range_num
(tiledb_ctx_t *ctx, const tiledb_query_t *query, 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_query_get_range_num(ctx, query, dim_idx, &range_num);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: The query.dim_idx
: The index of the dimension whose range number to retrieve.range_num
: The number of ranges to retrieve.
-
int32_t
tiledb_query_get_range_num_from_name
(tiledb_ctx_t *ctx, const tiledb_query_t *query, const char *dim_name, uint64_t *range_num)¶ Retrieves the number of ranges of the query subarray along a given dimension name.
Example:
uint64_t range_num; tiledb_query_get_range_num_from_name(ctx, query, dim_name, &range_num);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: The query.dim_name
: The name of the dimension whose range number to retrieve.range_num
: The number of ranges to retrieve.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: The query.name
: The attribute/dimension name.size
: The size (in bytes) to be retrieved.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: 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.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: The query.num
: The number of written fragments to be retrieved.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- 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 contextquery
: The query.idx
: The index of the written fragment.uri
: The URI of the written fragment to be returned.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextquery
: 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.
-
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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Note
If you set the subarray of a completed, or uninitialized query, this function will clear the internal state and render it as uninitialized. However, the potentially set layout and attribute buffers will be retained. This is useful when the user wishes to fix the attributes and layout, but explore different subarrays with the same
tiledb_query_t
object (i.e., without having to create a new object).- Note
Setting the subarray in sparse writes is meaningless and, thus, this function will error in the following two cases, provided that this is a write query: (i) the array is sparse, and (ii) the array is dense and the layout has been set to
TILEDB_UNORDERED
. In the second case, if the user sets the layout toTILEDB_UNORDERED
after the subarray has been set, the subarray will simply be ignored.- Parameters
ctx
: The TileDB context.query
: The TileDB query.subarray
: The subarray by which the array read/write will be constrained. It should be a sequence of [low, high] pairs (one pair per dimension). For the case of writes, this is meaningful only for dense arrays, and specifically dense writes. Note thatsubarray
must have the same type as the domain.
-
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);
- Return
TILEDB_OK
for success orTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array
: An open array object.subarray
: The retrieved subarray object if available.
Subarray¶
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_OOM
orTILEDB_ERR
for error.- Note
The allocated subarray initially has internal coalesce_ranges == true.
- Parameters
ctx
: The TileDB context.array
: An open array object.subarray
: The subarray object to be created.
-
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
: The subarray object to be freed.
-
int32_t
tiledb_subarray_set_coalesce_ranges
(tiledb_ctx_t *ctx, tiledb_subarray_t *subarray, int coalesce_ranges)¶ Set 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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.subarray
: The subarray object to change.coalesce_ranges
: The true/false value to be set
-
int32_t
tiledb_subarray_set_subarray
(tiledb_ctx_t *ctx, tiledb_subarray_t *subarray_s, const void *subarray_v)¶ Populates a subarray with specific indicies.
Example:
The following sets a 2D subarray [0,10], [20, 30] to the subarray.
tiledb_subarray_t *subarray; uint64_t subarray_v[] = { 0, 10, 20, 30}; tiledb_subarray_set_subarray(ctx, subarray, subarray_v);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.subarray
: The TileDB subarray object.subarray_v
: 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 thatsubarray_a
must have the same type as the domain of the subarray’s associated array.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Note
The stride is currently unsupported. Use 0/NULL/nullptr as the stride argument.
- Parameters
ctx
: The TileDB context.query
: The subarray to add the range to.dim_idx
: The index of the dimension to add the range to.start
: The range start.end
: The range end.stride
: The range stride.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Note
The stride is currently unsupported. Use 0/NULL/nullptr as the stride argument.
- Parameters
ctx
: The TileDB context.subarray
: The subarray to add the range to.dim_name
: The name of the dimension to add the range to.start
: The range start.end
: The range end.stride
: The range stride.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.subarray
: The subarray to add the range to.dim_idx
: The index of the dimension to add the range to.start
: The range start.start_size
: The size of the range start in bytes.end
: The range end.end_size
: The size of the range end in bytes.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.subarray
: The subarray to add the range to.dim_name
: The name of the dimension to add the range to.start
: The range start.start_size
: The size of the range start in bytes.end
: The range end.end_size
: The size of the range end in bytes.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextsubarray
: The subarray.dim_idx
: The index of the dimension for which to retrieve number of ranges.range_num
: Receives the retrieved number of ranges.
-
int32_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)¶ Retrieves 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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextsubarray
: The subarray.dim_name
: The name of the dimension whose range number to retrieve.range_num
: Receives the retrieved number of ranges.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextsubarray
: The subarray.dim_idx
: The index of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start
: Receives the retrieved range start.end
: Receives the received range end.stride
: Receives the retrieved range stride.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextsubarray
: The subarray.dim_name
: The name of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start
: Receives the retrieved range start.end
: Receives the retrieved range end.stride
: Receives the retrieved range stride.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextsubarray
: The subarray.dim_idx
: The index of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start_size
: Receives the retrieved range start size in bytesend_size
: Receives the retrieved range end size in bytes
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextsubarray
: The subarray.dim_name
: The name of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start_size
: Receives the retrieved range start size in bytesend_size
: Receives the retrieved range end size in bytes
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextsubarray
: The subarray.dim_idx
: The index of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start
: Receives the retrieved range start.end
: Receives the retrieved range end.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextsubarray
: The subarray.dim_name
: The name of the dimension to retrieve the range from.range_idx
: The index of the range to retrieve.start
: Receives the retrieved range start.end
: Receives the retrieved range end.
Filter¶
-
int32_t
tiledb_filter_alloc
(tiledb_ctx_t *ctx, tiledb_filter_type_t type, tiledb_filter_t **filter)¶ Creates a TileDB filter.
Example:
tiledb_filter_t* filter; tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.type
: The filter type.filter
: The TileDB filter to be created.
-
void
tiledb_filter_free
(tiledb_filter_t **filter)¶ Destroys a TileDB filter, freeing associated memory.
Example:
tiledb_filter_t* filter; tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter); tiledb_filter_free(&filter);
- Parameters
filter
: The filter to be destroyed.
-
int32_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
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.filter
: The TileDB filter.type
: The filter type to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: TileDB context.filter
: The target filter.option
: Filter option to set.value
: Value of option to set.
-
int32_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.- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: TileDB context.filter
: The target filter.option
: Filter option to get.value
: Buffer that option value will be written to.
Filter List¶
-
int32_t
tiledb_filter_list_alloc
(tiledb_ctx_t *ctx, tiledb_filter_list_t **filter_list)¶ Creates a TileDB filter list (pipeline of filters).
Example:
tiledb_filter_list_t* filter_list; tiledb_filter_list_alloc(ctx, &filter_list);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.filter_list
: The TileDB filter list to be created.
-
void
tiledb_filter_list_free
(tiledb_filter_list_t **filter_list)¶ Destroys a TileDB filter list, freeing associated memory.
Example:
tiledb_filter_list_t* filter_list; tiledb_filter_list_alloc(ctx, &filter_list); tiledb_filter_list_free(&filter_list);
- Parameters
filter_list
: The filter list to be destroyed.
-
int32_t
tiledb_filter_list_add_filter
(tiledb_ctx_t *ctx, tiledb_filter_list_t *filter_list, tiledb_filter_t *filter)¶ Appends a filter to a filter list. Data is processed through each filter in the order the filters were added.
Example:
tiledb_filter_t* filter; tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter); tiledb_filter_list_t* filter_list; tiledb_filter_list_alloc(ctx, &filter_list); tiledb_filter_list_add_filter(ctx, filter_list, filter); tiledb_filter_list_free(&filter_list); tiledb_filter_free(&filter);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.filter_list
: The target filter list.filter
: The filter to add.
-
int32_t
tiledb_filter_list_set_max_chunk_size
(tiledb_ctx_t *ctx, const tiledb_filter_list_t *filter_list, uint32_t max_chunk_size)¶ Sets the maximum tile chunk size for a filter list.
Example:
// Set max chunk size to 16KB: tiledb_filter_list_set_max_chunk_size(ctx, filter_list, 16384);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfilter_list
: The target filter listmax_chunk_size
: The max chunk size value to set
-
int32_t
tiledb_filter_list_get_nfilters
(tiledb_ctx_t *ctx, const tiledb_filter_list_t *filter_list, uint32_t *nfilters)¶ Retrieves the number of filters in a filter list.
Example:
uint32_t num_filters; tiledb_filter_list_get_nfilters(ctx, filter_list, &num_filters);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfilter_list
: The filter listnfilters
: The number of filters on the filter list
-
int32_t
tiledb_filter_list_get_filter_from_index
(tiledb_ctx_t *ctx, const tiledb_filter_list_t *filter_list, uint32_t index, tiledb_filter_t **filter)¶ Retrieves a filter object from a filter list by index.
Example:
The following retrieves the first filter from a filter list.
tiledb_filter_t* filter; tiledb_filter_list_get_filter_from_index(ctx, filter_list, 0, &filter); tiledb_filter_free(&filter);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfilter_list
: The filter list to retrieve the filter fromindex
: The index of the filterfilter
: The retrieved filter object.
-
int32_t
tiledb_filter_list_get_max_chunk_size
(tiledb_ctx_t *ctx, const tiledb_filter_list_t *filter_list, uint32_t *max_chunk_size)¶ Gets the maximum tile chunk size for a filter list.
Example:
uint32_t max_chunk_size; tiledb_filter_list_get_max_chunk_size(ctx, filter_list, &max_chunk_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfilter_list
: The target filter listmax_chunk_size
: The retrieved max chunk size value
Group¶
-
int32_t
tiledb_group_create
(tiledb_ctx_t *ctx, const char *group_uri)¶ Creates a new TileDB group.
Example:
tiledb_group_create(ctx, "my_group");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.group_uri
: The group URI.
Buffer¶
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: TileDB contextbuffer
: The buffer to be created
-
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.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: TileDB contextbuffer
: TileDB buffer instancedatatype
: Set to the datatype of the buffer.
-
int32_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: TileDB contextbuffer
: TileDB buffer instancedatatype
: The datatype to set on the buffer.
-
int32_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:
- Note
For string buffers allocated by TileDB, the number of bytes includes the terminating NULL byte.
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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: TileDB contextbuffer
: TileDB buffer instancedata
: The pointer to the data to be retrieved.num_bytes
: Set to the number of bytes in the buffer.
-
int32_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:
- 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 viatiledb_buffer_set_buffer
.
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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: TileDB contextbuffer
: TileDB buffer instancedata
: Pre-allocated region of memory to wrap with this buffer.size
: Size (in bytes) of the region pointed to by data.
BufferList¶
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: TileDB contextbuffer_list
: The buffer list to be created
-
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.
-
int32_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.
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- Parameters
ctx
: TileDB context.buffer_list
: The buffer list.num_buffers
: Set to the number of buffers in the buffer list.
-
int32_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.
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- 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.
-
int32_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 withtiledb_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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- 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.
-
int32_t
tiledb_buffer_list_flatten
(tiledb_ctx_t *ctx, const 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);
- Return
TILEDB_OK
for success orTILEDB_ERR
for error.- 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.
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);
- Return
TILEDB_OK
on success,TILEDB_ERR
on error.- Parameters
ctx
: The TileDB context.path
: The URI path to the TileDB resource.type
: The type to be retrieved.
-
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");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.path
: The URI path to the tiledb resource.
-
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");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.old_path
: The old TileDB directory.new_path
: The new TileDB directory.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.path
: The path in which the traversal will occur.order
: The order of the recursive traversal (e.g., pre-order or post-order.callback
: The callback function to be applied on every visited object. The callback should return0
if the iteration must stop, and1
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 thatpath
in the callback will be an absolute path.data
: The data passed in the callback as the last argument.
-
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 ofpath
(i.e., it does not recursively continue to the children directories).Example:
tiledb_object_ls(ctx, "arrays", NULL, NULL);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.path
: The path in which the traversal will occur.callback
: The callback function to be applied on every visited object. The callback should return0
if the iteration must stop, and1
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 thatpath
in the callback will be an absolute path.data
: The data passed in the callback as the last argument.
VFS¶
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object to be created.config
: Configuration parameters.
-
void
tiledb_vfs_free
(tiledb_vfs_t **vfs)¶ Frees a virtual filesystem object.
Example:
tiledb_vfs_free(&vfs);
- Parameters
vfs
: The virtual filesystem object to be freed.
-
int32_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
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The VFS object.config
: The config to be retrieved.
-
int32_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");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the bucket to be created.
-
int32_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");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the bucket to be deleted.
-
int32_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");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the bucket to be emptied.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the bucket.is_empty
: Sets it to1
if the input bucket is empty, and0
otherwise.
-
int32_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);
- Return
TILEDB_OK for success and TILEDB_ERR for error.
- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the bucket.is_bucket
: Sets it to1
if the input URI is a bucket, and0
otherwise.
-
int32_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, "hdfs:///temp/my_dir");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the directory to be created.
-
int32_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, "hdfs:///temp/my_dir", &exists);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
For S3, this function will return
true
if there is an object with prefixuri/
(TileDB will append/
internally touri
only if it does not exist), andfalse
othewise.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the directory.is_dir
: Sets it to1
if the directory exists and0
otherwise.
-
int32_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, "hdfs:///temp/my_dir");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The uri of the directory to be removed
-
int32_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, "hdfs:///temp/my_file", &is_file);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the file.is_file
: Sets it to1
if the file exists and0
otherwise.
-
int32_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, "hdfs:///temp/my_file");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the file.
-
int32_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, "hdfs:///temp/my_dir", &dir_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the directory.size
: The directory size to be retrieved.
-
int32_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 thecallback
function using the inputdata
.Example:
tiledb_vfs_ls(ctx, vfs, "my_dir", NULL, NULL);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.path
: The path in which the traversal will occur.callback
: The callback function to be applied on every visited object. The callback should return0
if the iteration must stop, and1
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 thatpath
in the callback will be an absolute path.data
: The data passed in the callback as the last argument.
-
int32_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, "hdfs:///temp/my_file", &file_size);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the file.size
: The file size to be retrieved.
-
int32_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, "hdfs:///temp/my_dir", "hdfs::///new_dir");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.old_uri
: The old URI.new_uri
: The new URI.
-
int32_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, "hdfs:///temp/my_file", "hdfs::///new_file");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.old_uri
: The old URI.new_uri
: The new URI.
-
int32_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
- Return
TILEDB_OK
for success andTILEDB_ERR
orTILEDB_OOM
for error.- Note
If the file is closed after being opened, without having written any data to it, the file will not be created. If you wish to create an empty file, use
tiledb_vfs_touch
instead.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the file.mode
: The mode in which the file is opened:TILEDB_VFS_READ
: The file is opened for reading. An error is returned if the file does not exist.TILEDB_VFS_WRITE
: The file is opened for writing. If the file exists, it will be overwritten.TILEDB_VFS_APPEND
: The file is opened for writing. If the file exists, the write will start from the end of the file. Note that S3 does not support this operation and, thus, an error will be thrown in that case.
fh
: The file handle that is created. This will be used intiledb_vfs_read
,tiledb_vfs_write
andtiledb_vfs_sync
.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fh
: The file handle.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fh
: The URI file handle.offset
: The offset in the file where the read begins.buffer
: The buffer to read into.nbytes
: Number of bytes to read.
-
int32_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));
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fh
: The URI file handle.buffer
: The buffer to write from.nbytes
: Number of bytes to write.
-
int32_t
tiledb_vfs_sync
(tiledb_ctx_t *ctx, tiledb_vfs_fh_t *fh)¶ Syncs (flushes) a file.
Example:
tiledb_vfs_sync(ctx, fh);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
This has no effect for S3.
- Parameters
ctx
: The TileDB context.fh
: The URI file handle.
-
void
tiledb_vfs_fh_free
(tiledb_vfs_fh_t **fh)¶ Frees a file handle.
Example:
tiledb_vfs_fh_free(&fh);
- Parameters
fh
: The URI file handle.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fh
: The URI file handle.is_closed
: Set to1
if the file handle is closed, and0
otherwise.
-
int32_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.
Example:
tiledb_vfs_touch(ctx, vfs, "my_empty_file");
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.vfs
: The virtual filesystem object.uri
: The URI of the file to be created.
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`
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Note
The path_out buffer must be allocated according to the platform’s maximum path length (e.g. `TILEDB_MAX_PATH), which includes space for the terminating null character.
- Parameters
ctx
: The TileDB context.uri
: The URI to be converted.path_out
: The buffer where the converted path string is stored.path_length
: The length of the path buffer. On return, this is set to the length of the converted path string, or 0 on error.
Version¶
-
void
tiledb_version
(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.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.
-
int32_t
tiledb_stats_disable
(void)¶ Disable internal statistics gathering.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.
-
int32_t
tiledb_stats_reset
(void)¶ Reset all internal statistics counters to 0.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.
-
int32_t
tiledb_stats_dump
(FILE *out)¶ Dump all internal statistics counters to some output (e.g., file or stdout).
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
out
: The output.
-
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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
out
: Will be set to point to an allocated string containing the stats.
-
int32_t
tiledb_stats_free_str
(char **out)¶ Free the memory associated with a previously dumped stats string.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
out
: Pointer to a previously allocated stats string.
Fragment Info¶
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_OOM
orTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.array_uri
: The array URI.fragment_info
: The fragment info object to be created and populated.
-
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
: The fragment info object to be freed.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fragment_info
: The fragment info object.
-
int32_t
tiledb_fragment_info_load_with_key
(tiledb_ctx_t *ctx, tiledb_fragment_info_t *fragment_info, tiledb_encryption_type_t encryption_type, const void *encryption_key, uint32_t key_length)¶ Loads the fragment info from an encrypted array.
Example:
tiledb_fragment_info_load_with_key( ctx, fragment_info, TILEDB_AES_256_GCM, key, sizeof(key));
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fragment_info
: The fragment info object.encryption_type
: The encryption type to use.encryption_key
: The encryption key to use.key_length
: Length in bytes of the encryption key.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment info object.fid
: The index of the fragment of interest.array_schema
: The array schema to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fragment_info
: The fragment info object.name
: The schema name.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fragment_info
: The fragment info object.fragment_num
: The number of fragments to retrieve.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fragment_info
: The fragment info object.fid
: The index of the fragment of interest.uri
: The fragment URI to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fragment_info
: The fragment info object.fid
: The index of the fragment of interest.size
: The fragment size to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fragment_info
: The fragment info object.fid
: The index of the fragment of interest.dense
:1
if the fragment is dense.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fragment_info
: The fragment info object.fid
: The index of the fragment of interest.sparse
:1
if the fragment is sparse.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fragment_info
: The fragment info object.fid
: The index of the fragment of interest.start
: The start of the timestamp range to be retrieved.end
: The end of the timestamp range to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment info object.fid
: The index of the fragment of interest.did
: The dimension index, following the order as it was defined in the domain of the array schema.domain
: The domain to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment info object.fid
: The index of the fragment of interest.dim_name
: The dimension name.domain
: The domain to be retrieved.
-
int32_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`.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment information object.fid
: The fragment index.did
: The dimension index, following the order as it was defined in the domain of the array schema.start_size
: The size in bytes of the start range.end_size
: The size in bytes of the end range.
-
int32_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`.
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment information object.fid
: The fragment index.dim_name
: The dimension name.start_size
: The size in bytes of the start range.end_size
: The size in bytes of the end range.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment info object.fid
: The fragment index.did
: The dimension index, following the order as it was defined in the domain of the array schema.start
: The domain range start to set.end
: The domain range end to set.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment info object.fid
: The fragment index.dim_name
: The dimension name.start
: The domain range start to set.end
: The domain range end to set.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment info object.fid
: The index of the fragment of interest.cell_num
: The number of cells to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment info object.fid
: The index of the fragment of interest.version
: The format version to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment info object.fid
: The index of the fragment of interest.has
: True if the fragment has consolidated metadata.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment info object.unconsolidated
: The number of fragments with unconsolidated metadata.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB contextfragment_info
: The fragment info object.to_vacuum_num
: The number of fragments to vacuum.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fragment_info
: The fragment info object.fid
: The index of the fragment to vacuum of interest.uri
: The fragment URI to be retrieved.
-
int32_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);
- Return
TILEDB_OK
for success andTILEDB_ERR
for error.- Parameters
ctx
: The TileDB context.fragment_info
: The fragment info object.out
: The output.