1 /** 2 * @file tiledb.h 3 * 4 * @section LICENSE 5 * 6 * The MIT License 7 * 8 * @copyright Copyright (c) 2017-2021 TileDB, Inc. 9 * @copyright Copyright (c) 2016 MIT and Intel Corporation 10 * 11 * Permission is hereby granted, free of charge, to any person obtaining a copy 12 * of this software and associated documentation files (the "Software"), to deal 13 * in the Software without restriction, including without limitation the rights 14 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 15 * copies of the Software, and to permit persons to whom the Software is 16 * furnished to do so, subject to the following conditions: 17 * 18 * The above copyright notice and this permission notice shall be included in 19 * all copies or substantial portions of the Software. 20 * 21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 22 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 24 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 26 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 27 * THE SOFTWARE. 28 * 29 * @section DESCRIPTION 30 * 31 * This file declares the C API for TileDB. 32 */ 33 34 #ifndef TILEDB_H 35 #define TILEDB_H 36 37 #include "tiledb_version.h" 38 39 // Generated by CMake; defines TILEDB_EXPORT (etc) macros. 40 #include "tiledb_export.h" 41 42 #include <stdint.h> 43 #include <stdio.h> 44 45 /* ********************************* */ 46 /* MACROS */ 47 /* ********************************* */ 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 /* ****************************** */ 54 /* TILEDB ENUMS */ 55 /* ****************************** */ 56 57 /** TileDB object type. */ 58 typedef enum { 59 /** Helper macro for defining object type enums. */ 60 #define TILEDB_OBJECT_TYPE_ENUM(id) TILEDB_##id 61 #include "tiledb_enum.h" 62 #undef TILEDB_OBJECT_TYPE_ENUM 63 } tiledb_object_t; 64 65 /** TileDB query type. */ 66 typedef enum { 67 /** Helper macro for defining query type enums. */ 68 #define TILEDB_QUERY_TYPE_ENUM(id) TILEDB_##id 69 #include "tiledb_enum.h" 70 #undef TILEDB_QUERY_TYPE_ENUM 71 } tiledb_query_type_t; 72 73 /** Query status. */ 74 typedef enum { 75 /** Helper macro for defining query status enums. */ 76 #define TILEDB_QUERY_STATUS_ENUM(id) TILEDB_##id 77 #include "tiledb_enum.h" 78 #undef TILEDB_QUERY_STATUS_ENUM 79 } tiledb_query_status_t; 80 81 /** Query condition operator. */ 82 typedef enum { 83 /** Helper macro for defining query condition operator enums. */ 84 #define TILEDB_QUERY_CONDITION_OP_ENUM(id) TILEDB_##id 85 #include "tiledb_enum.h" 86 #undef TILEDB_QUERY_CONDITION_OP_ENUM 87 } tiledb_query_condition_op_t; 88 89 /** Query condition combination operator. */ 90 typedef enum { 91 /** Helper macro for defining query condition combination operator enums. */ 92 #define TILEDB_QUERY_CONDITION_COMBINATION_OP_ENUM(id) TILEDB_##id 93 #include "tiledb_enum.h" 94 #undef TILEDB_QUERY_CONDITION_COMBINATION_OP_ENUM 95 } tiledb_query_condition_combination_op_t; 96 97 /** Filesystem type. */ 98 typedef enum { 99 /** Helper macro for defining filesystem enums. */ 100 #define TILEDB_FILESYSTEM_ENUM(id) TILEDB_##id 101 #include "tiledb_enum.h" 102 #undef TILEDB_FILESYSTEM_ENUM 103 } tiledb_filesystem_t; 104 105 /** TileDB datatype. */ 106 typedef enum { 107 /** Helper macro for defining datatype enums. */ 108 #define TILEDB_DATATYPE_ENUM(id) TILEDB_##id 109 #include "tiledb_enum.h" 110 #undef TILEDB_DATATYPE_ENUM 111 } tiledb_datatype_t; 112 113 /** Array type. */ 114 typedef enum { 115 /** Helper macro for defining array type enums. */ 116 #define TILEDB_ARRAY_TYPE_ENUM(id) TILEDB_##id 117 #include "tiledb_enum.h" 118 #undef TILEDB_ARRAY_TYPE_ENUM 119 } tiledb_array_type_t; 120 121 /** Tile or cell layout. */ 122 typedef enum { 123 /** Helper macro for defining layout type enums. */ 124 #define TILEDB_LAYOUT_ENUM(id) TILEDB_##id 125 #include "tiledb_enum.h" 126 #undef TILEDB_LAYOUT_ENUM 127 } tiledb_layout_t; 128 129 /** Filter type. */ 130 typedef enum { 131 /** Helper macro for defining filter type enums. */ 132 #define TILEDB_FILTER_TYPE_ENUM(id) TILEDB_##id 133 #include "tiledb_enum.h" 134 #undef TILEDB_FILTER_TYPE_ENUM 135 } tiledb_filter_type_t; 136 137 /** Filter option. */ 138 typedef enum { 139 /** Helper macro for defining filter option enums. */ 140 #define TILEDB_FILTER_OPTION_ENUM(id) TILEDB_##id 141 #include "tiledb_enum.h" 142 #undef TILEDB_FILTER_OPTION_ENUM 143 } tiledb_filter_option_t; 144 145 /** Encryption type. */ 146 typedef enum { 147 /** Helper macro for defining encryption enums. */ 148 #define TILEDB_ENCRYPTION_TYPE_ENUM(id) TILEDB_##id 149 #include "tiledb_enum.h" 150 #undef TILEDB_ENCRYPTION_TYPE_ENUM 151 } tiledb_encryption_type_t; 152 153 /** Walk traversal order. */ 154 typedef enum { 155 /** Helper macro for defining walk order enums. */ 156 #define TILEDB_WALK_ORDER_ENUM(id) TILEDB_##id 157 #include "tiledb_enum.h" 158 #undef TILEDB_WALK_ORDER_ENUM 159 } tiledb_walk_order_t; 160 161 /** VFS mode. */ 162 typedef enum { 163 /** Helper macro for defining VFS mode enums. */ 164 #define TILEDB_VFS_MODE_ENUM(id) TILEDB_##id 165 #include "tiledb_enum.h" 166 #undef TILEDB_VFS_MODE_ENUM 167 } tiledb_vfs_mode_t; 168 169 /* ****************************** */ 170 /* ENUMS TO/FROM STR */ 171 /* ****************************** */ 172 173 /** 174 * Returns a string representation of the given query type. 175 * 176 * @param query_type Query type 177 * @param str Set to point to a constant string representation of the query type 178 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 179 */ 180 TILEDB_EXPORT int32_t 181 tiledb_query_type_to_str(tiledb_query_type_t query_type, const char** str); 182 183 /** 184 * Parses a query type from the given string. 185 * 186 * @param str String representation to parse 187 * @param query_type Set to the parsed query type 188 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 189 */ 190 TILEDB_EXPORT int32_t 191 tiledb_query_type_from_str(const char* str, tiledb_query_type_t* query_type); 192 193 /** 194 * Returns a string representation of the given object type. 195 * 196 * @param object_type Object type 197 * @param str Set to point to a constant string representation of the object 198 * type 199 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 200 */ 201 TILEDB_EXPORT int32_t 202 tiledb_object_type_to_str(tiledb_object_t object_type, const char** str); 203 204 /** 205 * Parses a object type from the given string. 206 * 207 * @param str String representation to parse 208 * @param object_type Set to the parsed object type 209 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 210 */ 211 TILEDB_EXPORT int32_t 212 tiledb_object_type_from_str(const char* str, tiledb_object_t* object_type); 213 214 /** 215 * Returns a string representation of the given filesystem. 216 * 217 * @param filesystem Filesystem 218 * @param str Set to point to a constant string representation of the filesystem 219 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 220 */ 221 TILEDB_EXPORT int32_t 222 tiledb_filesystem_to_str(tiledb_filesystem_t filesystem, const char** str); 223 224 /** 225 * Parses a filesystem from the given string. 226 * 227 * @param str String representation to parse 228 * @param filesystem Set to the parsed filesystem 229 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 230 */ 231 TILEDB_EXPORT int32_t 232 tiledb_filesystem_from_str(const char* str, tiledb_filesystem_t* filesystem); 233 234 /** 235 * Returns a string representation of the given datatype. 236 * 237 * @param datatype Datatype 238 * @param str Set to point to a constant string representation of the datatype 239 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 240 */ 241 TILEDB_EXPORT int32_t 242 tiledb_datatype_to_str(tiledb_datatype_t datatype, const char** str); 243 244 /** 245 * Parses a datatype from the given string. 246 * 247 * @param str String representation to parse 248 * @param datatype Set to the parsed datatype 249 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 250 */ 251 TILEDB_EXPORT int32_t 252 tiledb_datatype_from_str(const char* str, tiledb_datatype_t* datatype); 253 254 /** 255 * Returns a string representation of the given array type. 256 * 257 * @param array_type Array type 258 * @param str Set to point to a constant string representation of the array type 259 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 260 */ 261 TILEDB_EXPORT int32_t 262 tiledb_array_type_to_str(tiledb_array_type_t array_type, const char** str); 263 264 /** 265 * Parses a array type from the given string. 266 * 267 * @param str String representation to parse 268 * @param array_type Set to the parsed array type 269 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 270 */ 271 TILEDB_EXPORT int32_t 272 tiledb_array_type_from_str(const char* str, tiledb_array_type_t* array_type); 273 274 /** 275 * Returns a string representation of the given layout. 276 * 277 * @param layout Layout 278 * @param str Set to point to a constant string representation of the layout 279 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 280 */ 281 TILEDB_EXPORT int32_t 282 tiledb_layout_to_str(tiledb_layout_t layout, const char** str); 283 284 /** 285 * Parses a layout from the given string. 286 * 287 * @param str String representation to parse 288 * @param layout Set to the parsed layout 289 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 290 */ 291 TILEDB_EXPORT int32_t 292 tiledb_layout_from_str(const char* str, tiledb_layout_t* layout); 293 294 /** 295 * Returns a string representation of the given filter type. 296 * 297 * @param filter_type Filter type 298 * @param str Set to point to a constant string representation of the filter 299 * type 300 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 301 */ 302 TILEDB_EXPORT int32_t 303 tiledb_filter_type_to_str(tiledb_filter_type_t filter_type, const char** str); 304 305 /** 306 * Parses a filter type from the given string. 307 * 308 * @param str String representation to parse 309 * @param filter_type Set to the parsed filter type 310 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 311 */ 312 TILEDB_EXPORT int32_t 313 tiledb_filter_type_from_str(const char* str, tiledb_filter_type_t* filter_type); 314 315 /** 316 * Returns a string representation of the given filter option. 317 * 318 * @param filter_option Filter option 319 * @param str Set to point to a constant string representation of the filter 320 * option 321 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 322 */ 323 TILEDB_EXPORT int32_t tiledb_filter_option_to_str( 324 tiledb_filter_option_t filter_option, const char** str); 325 326 /** 327 * Parses a filter option from the given string. 328 * 329 * @param str String representation to parse 330 * @param filter_option Set to the parsed filter option 331 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 332 */ 333 TILEDB_EXPORT int32_t tiledb_filter_option_from_str( 334 const char* str, tiledb_filter_option_t* filter_option); 335 336 /** 337 * Returns a string representation of the given encryption type. 338 * 339 * @param encryption_type Encryption type 340 * @param str Set to point to a constant string representation of the encryption 341 * type 342 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 343 */ 344 TILEDB_EXPORT int32_t tiledb_encryption_type_to_str( 345 tiledb_encryption_type_t encryption_type, const char** str); 346 347 /** 348 * Parses a encryption type from the given string. 349 * 350 * @param str String representation to parse 351 * @param encryption_type Set to the parsed encryption type 352 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 353 */ 354 TILEDB_EXPORT int32_t tiledb_encryption_type_from_str( 355 const char* str, tiledb_encryption_type_t* encryption_type); 356 357 /** 358 * Returns a string representation of the given query status. 359 * 360 * @param query_status Query status 361 * @param str Set to point to a constant string representation of the query 362 * status 363 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 364 */ 365 TILEDB_EXPORT int32_t tiledb_query_status_to_str( 366 tiledb_query_status_t query_status, const char** str); 367 368 /** 369 * Parses a query status from the given string. 370 * 371 * @param str String representation to parse 372 * @param query_status Set to the parsed query status 373 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 374 */ 375 TILEDB_EXPORT int32_t tiledb_query_status_from_str( 376 const char* str, tiledb_query_status_t* query_status); 377 378 /** 379 * Returns a string representation of the given walk order. 380 * 381 * @param walk_order Walk order 382 * @param str Set to point to a constant string representation of the walk order 383 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 384 */ 385 TILEDB_EXPORT int32_t 386 tiledb_walk_order_to_str(tiledb_walk_order_t walk_order, const char** str); 387 388 /** 389 * Parses a walk order from the given string. 390 * 391 * @param str String representation to parse 392 * @param walk_order Set to the parsed walk order 393 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 394 */ 395 TILEDB_EXPORT int32_t 396 tiledb_walk_order_from_str(const char* str, tiledb_walk_order_t* walk_order); 397 398 /** 399 * Returns a string representation of the given VFS mode. 400 * 401 * @param vfs_mode VFS mode 402 * @param str Set to point to a constant string representation of the VFS mode 403 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 404 */ 405 TILEDB_EXPORT int32_t 406 tiledb_vfs_mode_to_str(tiledb_vfs_mode_t vfs_mode, const char** str); 407 408 /** 409 * Parses a VFS mode from the given string. 410 * 411 * @param str String representation to parse 412 * @param vfs_mode Set to the parsed VFS mode 413 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 414 */ 415 TILEDB_EXPORT int32_t 416 tiledb_vfs_mode_from_str(const char* str, tiledb_vfs_mode_t* vfs_mode); 417 418 /* ****************************** */ 419 /* CONSTANTS */ 420 /* ****************************** */ 421 422 /** 423 * @name Return codes 424 */ 425 /**@{*/ 426 /** Success */ 427 #define TILEDB_OK 0 428 /** General error */ 429 #define TILEDB_ERR (-1) 430 /** Out of memory */ 431 #define TILEDB_OOM (-2) 432 /**@}*/ 433 434 /** 435 * Returns a special name indicating the coordinates attribute. 436 * 437 * The coordinate buffer has been deprecated. Set the coordinates for 438 * each individual dimension with the `set_buffer` API. Consult the current 439 * documentation for more information. 440 */ 441 TILEDB_DEPRECATED_EXPORT const char* tiledb_coords(void); 442 443 /** Returns a special value indicating a variable number of elements. */ 444 TILEDB_EXPORT uint32_t tiledb_var_num(void); 445 446 /** Returns the maximum path length on the current platform. */ 447 TILEDB_EXPORT uint32_t tiledb_max_path(void); 448 449 /** Returns the input datatype size. */ 450 TILEDB_EXPORT uint64_t tiledb_datatype_size(tiledb_datatype_t type); 451 452 /** 453 * Returns the size (in bytes) of an offset (used in variable-sized 454 * attributes). 455 */ 456 TILEDB_EXPORT uint64_t tiledb_offset_size(void); 457 458 /** Returns the current time in milliseconds. */ 459 TILEDB_EXPORT uint64_t tiledb_timestamp_now_ms(void); 460 461 /** 462 * @name Constants wrapping special functions 463 */ 464 /**@{*/ 465 /** A special name indicating the coordinates attribute. */ 466 #define TILEDB_COORDS tiledb_coords() 467 /** A special value indicating a variable number of elements. */ 468 #define TILEDB_VAR_NUM tiledb_var_num() 469 /** The maximum path length on the current platform. */ 470 #define TILEDB_MAX_PATH tiledb_max_path() 471 /** The size (in bytes) of an offset (used in variable-sized attributes). */ 472 #define TILEDB_OFFSET_SIZE tiledb_offset_size() 473 /** The current time in milliseconds. */ 474 #define TILEDB_TIMESTAMP_NOW_MS tiledb_timestamp_now_ms() 475 /**@}*/ 476 477 /* ****************************** */ 478 /* VERSION */ 479 /* ****************************** */ 480 481 /** 482 * Retrieves the version of the TileDB library currently being used. 483 * 484 * @param major Will store the major version number. 485 * @param minor Will store the minor version number. 486 * @param rev Will store the revision (patch) number. 487 */ 488 TILEDB_EXPORT void tiledb_version(int32_t* major, int32_t* minor, int32_t* rev); 489 490 /* ********************************* */ 491 /* TILEDB TYPES */ 492 /* ********************************* */ 493 494 /** An array object. */ 495 typedef struct tiledb_array_t tiledb_array_t; 496 497 /** A generic buffer object. */ 498 typedef struct tiledb_buffer_t tiledb_buffer_t; 499 500 /** A generic buffer list object. */ 501 typedef struct tiledb_buffer_list_t tiledb_buffer_list_t; 502 503 /** A config object. */ 504 typedef struct tiledb_config_t tiledb_config_t; 505 506 /** A config iterator. */ 507 typedef struct tiledb_config_iter_t tiledb_config_iter_t; 508 509 /** A TileDB context. */ 510 typedef struct tiledb_ctx_t tiledb_ctx_t; 511 512 /** A TileDB error. **/ 513 typedef struct tiledb_error_t tiledb_error_t; 514 515 /** A TileDB attribute. */ 516 typedef struct tiledb_attribute_t tiledb_attribute_t; 517 518 /** A TileDB array schema. */ 519 typedef struct tiledb_array_schema_t tiledb_array_schema_t; 520 521 /** A TileDB dimension. */ 522 typedef struct tiledb_dimension_t tiledb_dimension_t; 523 524 /** A TileDB domain. */ 525 typedef struct tiledb_domain_t tiledb_domain_t; 526 527 /** A TileDB filter. */ 528 typedef struct tiledb_filter_t tiledb_filter_t; 529 530 /** A TileDB filter list. */ 531 typedef struct tiledb_filter_list_t tiledb_filter_list_t; 532 533 /** A TileDB query. */ 534 typedef struct tiledb_query_t tiledb_query_t; 535 536 /** A TileDB query condition object. */ 537 typedef struct tiledb_query_condition_t tiledb_query_condition_t; 538 539 /** A virtual filesystem object. */ 540 typedef struct tiledb_vfs_t tiledb_vfs_t; 541 542 /** A virtual filesystem file handle. */ 543 typedef struct tiledb_vfs_fh_t tiledb_vfs_fh_t; 544 545 /** A fragment info object. */ 546 typedef struct tiledb_fragment_info_t tiledb_fragment_info_t; 547 548 /* ********************************* */ 549 /* ERROR */ 550 /* ********************************* */ 551 552 /** 553 * Returns the error message associated with a TileDB error object. 554 * 555 * **Example:** 556 * 557 * The following shows how to get the last error from a TileDB context. 558 * 559 * @code{.c} 560 * tiledb_error_t* err = NULL; 561 * tiledb_ctx_get_last_error(ctx, &err); 562 * const char* msg; 563 * tiledb_error_message(err, &msg); 564 * printf("%s\n", msg); 565 * @endcode 566 * 567 * @param err A TileDB error object. 568 * @param errmsg A constant pointer to the error message. 569 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 570 */ 571 TILEDB_EXPORT int32_t 572 tiledb_error_message(tiledb_error_t* err, const char** errmsg); 573 574 /** 575 * Frees the resources associated with a TileDB error object. 576 * 577 * **Example:** 578 * 579 * @code{.c} 580 * tiledb_error_t* err = NULL; 581 * tiledb_ctx_get_last_error(ctx, &err); 582 * const char* msg; 583 * tiledb_error_message(err, &msg); 584 * printf("%s\n", msg); 585 * tiledb_error_free(&err); 586 * @endcode 587 * 588 * @param err The TileDB error object. 589 */ 590 TILEDB_EXPORT void tiledb_error_free(tiledb_error_t** err); 591 592 /* ********************************* */ 593 /* BUFFER */ 594 /* ********************************* */ 595 596 /** 597 * Creates an empty buffer object. 598 * 599 * **Example:** 600 * 601 * @code{.c} 602 * tiledb_buffer_t* buffer; 603 * tiledb_buffer_alloc(ctx, &buffer); 604 * @endcode 605 * 606 * @param ctx TileDB context 607 * @param buffer The buffer to be created 608 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 609 */ 610 TILEDB_EXPORT int32_t 611 tiledb_buffer_alloc(tiledb_ctx_t* ctx, tiledb_buffer_t** buffer); 612 613 /** 614 * Destroys a TileDB buffer, freeing associated memory. 615 * 616 * **Example:** 617 * 618 * @code{.c} 619 * tiledb_buffer_t* buffer; 620 * tiledb_buffer_alloc(ctx, &buffer); 621 * tiledb_buffer_free(&buffer); 622 * @endcode 623 * 624 * @param buffer The buffer to be destroyed. 625 */ 626 TILEDB_EXPORT void tiledb_buffer_free(tiledb_buffer_t** buffer); 627 628 /** 629 * Sets a datatype for the given buffer. The default datatype is `TILEDB_UINT8`. 630 * 631 * **Example:** 632 * 633 * @code{.c} 634 * tiledb_buffer_t* buffer; 635 * tiledb_buffer_alloc(ctx, &buffer); 636 * tiledb_buffer_set_type(ctx, buffer, TILEDB_INT32); 637 * @endcode 638 * 639 * @param ctx TileDB context 640 * @param buffer TileDB buffer instance 641 * @param datatype The datatype to set on the buffer. 642 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 643 */ 644 TILEDB_EXPORT int32_t tiledb_buffer_set_type( 645 tiledb_ctx_t* ctx, tiledb_buffer_t* buffer, tiledb_datatype_t datatype); 646 647 /** 648 * Gets the datatype from the given buffer. 649 * 650 * **Example:** 651 * 652 * @code{.c} 653 * tiledb_datatype_t type; 654 * tiledb_buffer_get_type(ctx, buffer, &type); 655 * @endcode 656 * 657 * @param ctx TileDB context 658 * @param buffer TileDB buffer instance 659 * @param datatype Set to the datatype of the buffer. 660 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 661 */ 662 TILEDB_EXPORT int32_t tiledb_buffer_get_type( 663 tiledb_ctx_t* ctx, 664 const tiledb_buffer_t* buffer, 665 tiledb_datatype_t* datatype); 666 667 /** 668 * Gets a pointer to the current allocation and the current number of bytes in 669 * the specified buffer object. 670 * 671 * @note For string buffers allocated by TileDB, the number of bytes includes 672 * the terminating NULL byte. 673 * 674 * **Example:** 675 * 676 * @code{.c} 677 * tiledb_buffer_t* buffer; 678 * tiledb_buffer_alloc(ctx, &buffer); 679 * void* data; 680 * uint64_t num_bytes; 681 * tiledb_buffer_get_data(ctx, buffer, &data, num_bytes); 682 * // data == NULL and num_bytes == 0 because the buffer is currently empty. 683 * tiledb_buffer_free(&buffer); 684 * @endcode 685 * 686 * @param ctx TileDB context 687 * @param buffer TileDB buffer instance 688 * @param data The pointer to the data to be retrieved. 689 * @param num_bytes Set to the number of bytes in the buffer. 690 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 691 */ 692 TILEDB_EXPORT int32_t tiledb_buffer_get_data( 693 tiledb_ctx_t* ctx, 694 const tiledb_buffer_t* buffer, 695 void** data, 696 uint64_t* num_bytes); 697 698 /** 699 * Sets (wraps) a pre-allocated region of memory with the given buffer object. 700 * This does not perform a copy. 701 * 702 * @note The TileDB buffer object does not take ownership of the allocation 703 * set with this function. That means the call to `tiledb_buffer_free` will not 704 * free a user allocation set via `tiledb_buffer_set_buffer`. 705 * 706 * **Example:** 707 * 708 * @code{.c} 709 * tiledb_buffer_t* buffer; 710 * tiledb_buffer_alloc(ctx, &buffer); 711 * 712 * void* my_data = malloc(100); 713 * tiledb_buffer_set_data(ctx, buffer, my_data, 100); 714 * 715 * void* data; 716 * uint64_t num_bytes; 717 * tiledb_buffer_get_data(ctx, buffer, &data, num_bytes); 718 * assert(data == my_data); 719 * assert(num_bytes == 100); 720 * 721 * tiledb_buffer_free(&buffer); 722 * free(my_data); 723 * @endcode 724 * 725 * @param ctx TileDB context 726 * @param buffer TileDB buffer instance 727 * @param data Pre-allocated region of memory to wrap with this buffer. 728 * @param size Size (in bytes) of the region pointed to by data. 729 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 730 */ 731 TILEDB_EXPORT int32_t tiledb_buffer_set_data( 732 tiledb_ctx_t* ctx, tiledb_buffer_t* buffer, void* data, uint64_t size); 733 734 /* ********************************* */ 735 /* BUFFER LIST */ 736 /* ********************************* */ 737 738 /** 739 * Creates an empty buffer list object. 740 * 741 * **Example:** 742 * 743 * @code{.c} 744 * tiledb_buffer_list_t* buffer_list; 745 * tiledb_buffer_list_alloc(ctx, &buffer_list); 746 * @endcode 747 * 748 * @param ctx TileDB context 749 * @param buffer_list The buffer list to be created 750 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 751 */ 752 TILEDB_EXPORT int32_t 753 tiledb_buffer_list_alloc(tiledb_ctx_t* ctx, tiledb_buffer_list_t** buffer_list); 754 755 /** 756 * Destroys a TileDB buffer list, freeing associated memory. 757 * 758 * **Example:** 759 * 760 * @code{.c} 761 * tiledb_buffer_t* buffer_list; 762 * tiledb_buffer_list_alloc(ctx, &buffer_list); 763 * tiledb_buffer_list_free(&buffer_list); 764 * @endcode 765 * 766 * @param buffer_list The buffer list to be destroyed. 767 */ 768 TILEDB_EXPORT void tiledb_buffer_list_free(tiledb_buffer_list_t** buffer_list); 769 770 /** 771 * Gets the number of buffers in the buffer list. 772 * 773 * **Example:** 774 * 775 * @code{.c} 776 * tiledb_buffer_list_t* buffer_list; 777 * tiledb_buffer_list_alloc(ctx, &buffer_list); 778 * uint64_t num_buffers; 779 * tiledb_buffer_list_get_num_buffers(ctx, buffer_list, &num_buffers); 780 * // num_buffers == 0 because the list is empty. 781 * @endcode 782 * 783 * @param ctx TileDB context. 784 * @param buffer_list The buffer list. 785 * @param num_buffers Set to the number of buffers in the buffer list. 786 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 787 */ 788 TILEDB_EXPORT int32_t tiledb_buffer_list_get_num_buffers( 789 tiledb_ctx_t* ctx, 790 const tiledb_buffer_list_t* buffer_list, 791 uint64_t* num_buffers); 792 793 /** 794 * Gets the buffer at the given index in the buffer list. The returned buffer 795 * object is simply a pointer to memory managed by the underlying buffer 796 * list, meaning this function does not perform a copy. 797 * 798 * It is the caller's responsibility to free the returned buffer with 799 * `tiledb_buffer_free`. Since the returned buffer object does not "own" the 800 * underlying allocation, the underlying allocation is not freed when freeing it 801 * with `tiledb_buffer_free`. 802 * 803 * **Example:** 804 * 805 * @code{.c} 806 * tiledb_buffer_list_t* buffer_list; 807 * // Create and populate the buffer_list 808 * 809 * // Get the buffer at index 0. 810 * tiledb_buffer_t *buff0; 811 * tiledb_buffer_list_get_buffer(ctx, buffer_list, 0, &buff0); 812 * 813 * // Always free the returned buffer object 814 * tiledb_buffer_free(&buff0); 815 * tiledb_buffer_list_free(&buffer_list); 816 * @endcode 817 * 818 * @param ctx TileDB context. 819 * @param buffer_list The buffer list. 820 * @param buffer_idx Index of buffer to get from the buffer list. 821 * @param buffer Set to a newly allocated buffer object pointing to the 822 * underlying allocation in the buffer list corresponding to the buffer. 823 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 824 */ 825 TILEDB_EXPORT int32_t tiledb_buffer_list_get_buffer( 826 tiledb_ctx_t* ctx, 827 const tiledb_buffer_list_t* buffer_list, 828 uint64_t buffer_idx, 829 tiledb_buffer_t** buffer); 830 831 /** 832 * Gets the total number of bytes in the buffers in the buffer list. 833 * 834 * **Example:** 835 * 836 * @code{.c} 837 * tiledb_buffer_list_t* buffer_list; 838 * tiledb_buffer_list_alloc(ctx, &buffer_list); 839 * uint64_t total_size; 840 * tiledb_buffer_list_get_total_size(ctx, buffer_list, &total_size); 841 * // total_size == 0 because the list is empty. 842 * @endcode 843 * 844 * @param ctx TileDB context. 845 * @param buffer_list The buffer list. 846 * @param total_size Set to the total number of bytes in the buffers in the 847 * buffer list. 848 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 849 */ 850 TILEDB_EXPORT int32_t tiledb_buffer_list_get_total_size( 851 tiledb_ctx_t* ctx, 852 const tiledb_buffer_list_t* buffer_list, 853 uint64_t* total_size); 854 855 /** 856 * Copies and concatenates all the data in the buffer list into a new buffer. 857 * 858 * **Example:** 859 * 860 * @code{.c} 861 * tiledb_buffer_t* buff; 862 * tiledb_buffer_list_flatten(ctx, buffer_list, &buff); 863 * // ... 864 * tiledb_buffer_free(&buff); 865 * @endcode 866 * 867 * @param ctx TileDB context. 868 * @param buffer_list The buffer list. 869 * @param buffer Will be set to a newly allocated buffer holding a copy of the 870 * concatenated data from the buffer list. 871 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 872 */ 873 TILEDB_EXPORT int32_t tiledb_buffer_list_flatten( 874 tiledb_ctx_t* ctx, 875 const tiledb_buffer_list_t* buffer_list, 876 tiledb_buffer_t** buffer); 877 878 /* ********************************* */ 879 /* CONFIG */ 880 /* ********************************* */ 881 882 /** 883 * Creates a TileDB config. 884 * 885 * **Example:** 886 * 887 * @code{.c} 888 * tiledb_config_t* config; 889 * tiledb_error_t* error = NULL; 890 * tiledb_config_alloc(&config, &error); 891 * @endcode 892 * 893 * @param config The config to be created. 894 * @param error Error object returned upon error (`NULL` if there is 895 * no error). 896 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 897 */ 898 TILEDB_EXPORT int32_t 899 tiledb_config_alloc(tiledb_config_t** config, tiledb_error_t** error); 900 901 /** 902 * Frees a TileDB config. 903 * 904 * **Example:** 905 * 906 * @code{.c} 907 * tiledb_config_t* config; 908 * tiledb_error_t* error = NULL; 909 * tiledb_config_alloc(&config, &error); 910 * tiledb_config_free(&config); 911 * @endcode 912 * 913 * @param config The config to be freed. 914 */ 915 TILEDB_EXPORT void tiledb_config_free(tiledb_config_t** config); 916 917 /** 918 * Sets a config parameter. 919 * 920 * **Parameters** 921 * 922 * - `sm.dedup_coords` <br> 923 * If `true`, cells with duplicate coordinates will be removed during sparse 924 * fragment writes. Note that ties during deduplication are broken 925 * arbitrarily. <br> 926 * **Default**: false 927 * - `sm.check_coord_dups` <br> 928 * This is applicable only if `sm.dedup_coords` is `false`. 929 * If `true`, an error will be thrown if there are cells with duplicate 930 * coordinates during sparse fragmnet writes. If `false` and there are 931 * duplicates, the duplicates will be written without errors. <br> 932 * **Default**: true 933 * - `sm.check_coord_oob` <br> 934 * If `true`, an error will be thrown if there are cells with coordinates 935 * lying outside the domain during sparse fragment writes. <br> 936 * **Default**: true 937 * `sm.read_range_oob` <br> 938 * If `error`, this will check ranges for read with out-of-bounds on the 939 * dimension domain's. If `warn`, the ranges will be capped at the 940 * dimension's domain and a warning logged. <br> 941 * **Default**: warn 942 * - `sm.check_global_order` <br> 943 * Checks if the coordinates obey the global array order. Applicable only 944 * to sparse writes in global order. 945 * **Default**: true 946 * - `sm.tile_cache_size` <br> 947 * The tile cache size in bytes. Any `uint64_t` value is acceptable. <br> 948 * **Default**: 10,000,000 949 * - `sm.enable_signal_handlers` <br> 950 * Determines whether or not TileDB will install signal handlers. <br> 951 * **Default**: true 952 * - `sm.compute_concurrency_level` <br> 953 * Upper-bound on number of threads to allocate for compute-bound tasks. <br> 954 * **Default*: # cores 955 * - `sm.io_concurrency_level` <br> 956 * Upper-bound on number of threads to allocate for IO-bound tasks. <br> 957 * **Default*: # cores 958 * - `sm.vacuum.mode` <br> 959 * The vacuuming mode, one of `fragments` (remove consolidated fragments), 960 * `fragment_meta` (remove only consolidated fragment metadata), or 961 * `array_meta` (remove consolidated array metadata files). <br> 962 * **Default**: fragments 963 * - `sm.vacuum.timestamp_start` <br> 964 * **Experimental** <br> 965 * When set, an array will be vacuumed between this value and 966 * `sm.vacuum.timestamp_end` (inclusive). <br> 967 * Only for `fragments` and `array_meta` vacuum mode. <br> 968 * **Default**: 0 969 * - `sm.vacuum.timestamp_end` <br> 970 * **Experimental** <br> 971 * When set, an array will be vacuumed between `sm.vacuum.timestamp_start` 972 * and this value (inclusive). <br> 973 * Only for `fragments` and `array_meta` vacuum mode. <br> 974 * **Default**: UINT64_MAX 975 * - `sm.consolidation_mode` <br> 976 * The consolidation mode, one of `fragments` (consolidate all fragments), 977 * `fragment_meta` (consolidate only fragment metadata footers to a single 978 * file), or `array_meta` (consolidate array metadata only). <br> 979 * **Default**: "fragments" 980 * - `sm.consolidation.amplification` <br> 981 * The factor by which the size of the dense fragment resulting 982 * from consolidating a set of fragments (containing at least one 983 * dense fragment) can be amplified. This is important when 984 * the union of the non-empty domains of the fragments to be 985 * consolidated have a lot of empty cells, which the consolidated 986 * fragment will have to fill with the special fill value 987 * (since the resulting fragment is dense). <br> 988 * **Default**: 1.0 989 * - `sm.consolidation.buffer_size` <br> 990 * The size (in bytes) of the attribute buffers used during 991 * consolidation. <br> 992 * **Default**: 50,000,000 993 * - `sm.consolidation.steps` <br> 994 * The number of consolidation steps to be performed when executing 995 * the consolidation algorithm.<br> 996 * **Default**: 1 997 * - `sm.consolidation.step_min_frags` <br> 998 * The minimum number of fragments to consolidate in a single step.<br> 999 * **Default**: UINT32_MAX 1000 * - `sm.consolidation.step_max_frags` <br> 1001 * The maximum number of fragments to consolidate in a single step.<br> 1002 * **Default**: UINT32_MAX 1003 * - `sm.consolidation.step_size_ratio` <br> 1004 * The size ratio that two ("adjacent") fragments must satisfy to be 1005 * considered for consolidation in a single step.<br> 1006 * **Default**: 0.0 1007 * - `sm.consolidation.timestamp_start` <br> 1008 * **Experimental** <br> 1009 * When set, an array will be consolidated between this value and 1010 * `sm.consolidation.timestamp_end` (inclusive). <br> 1011 * Only for `fragments` and `array_meta` consolidation mode. <br> 1012 * **Default**: 0 1013 * - `sm.consolidation.timestamp_end` <br> 1014 * **Experimental** <br> 1015 * When set, an array will be consolidated between 1016 * `sm.consolidation.timestamp_start` and this value (inclusive). <br> 1017 * Only for `fragments` and `array_meta` consolidation mode. <br> 1018 * **Default**: UINT64_MAX 1019 * - `sm.memory_budget` <br> 1020 * The memory budget for tiles of fixed-sized attributes (or offsets for 1021 * var-sized attributes) to be fetched during reads.<br> 1022 * **Default**: 5GB 1023 * - `sm.memory_budget_var` <br> 1024 * The memory budget for tiles of var-sized attributes 1025 * to be fetched during reads.<br> 1026 * **Default**: 10GB 1027 * - `sm.var_offsets.bitsize` <br> 1028 * The size of offsets in bits to be used for offset buffers of var-sized 1029 * attributes<br> 1030 * **Default**: 64 1031 * - `sm.var_offsets.extra_element` <br> 1032 * Add an extra element to the end of the offsets buffer of var-sized 1033 * attributes which will point to the end of the values buffer.<br> 1034 * **Default**: false 1035 * - `sm.var_offsets.mode` <br> 1036 * The offsets format (`bytes` or `elements`) to be used for 1037 * var-sized attributes.<br> 1038 * **Default**: bytes 1039 * - `sm.query.dense.reader` <br> 1040 * Which reader to use for dense queries. "refactored" or "legacy".<br> 1041 * **Default**: lagacy 1042 * - `sm.query.sparse_global_order.reader` <br> 1043 * Which reader to use for sparse global order queries. "refactored" 1044 * or "legacy".<br> 1045 * **Default**: legacy 1046 * - `sm.query.sparse_unordered_with_dups.reader` <br> 1047 * Which reader to use for sparse unordered with dups queries. 1048 * "refactored" or "legacy".<br> 1049 * **Default**: refactored 1050 * - `sm.mem.malloc_trim` <br> 1051 * Should malloc_trim be called on context and query destruction? This might 1052 * reduce residual memory usage. <br> 1053 * **Default**: true 1054 * - `sm.mem.total_budget` <br> 1055 * Memory budget for readers and writers. <br> 1056 * **Default**: 10GB 1057 * - `sm.mem.reader.sparse_global_order.ratio_coords` <br> 1058 * Ratio of the budget allocated for coordinates in the sparse global 1059 * order reader. <br> 1060 * **Default**: 0.5 1061 * - `sm.mem.reader.sparse_global_order.ratio_query_condition` <br> 1062 * Ratio of the budget allocated for the query condition in the sparse 1063 * global order reader. <br> 1064 * **Default**: 0.25 1065 * - `sm.mem.reader.sparse_global_order.ratio_tile_ranges` <br> 1066 * Ratio of the budget allocated for tile ranges in the sparse global 1067 * order reader. <br> 1068 * **Default**: 0.1 1069 * - `sm.mem.reader.sparse_global_order.ratio_array_data` <br> 1070 * Ratio of the budget allocated for array data in the sparse global 1071 * order reader. <br> 1072 * **Default**: 0.1 1073 * - `sm.mem.reader.sparse_global_order.ratio_result_tiles` <br> 1074 * Ratio of the budget allocated for result tiles in the sparse global 1075 * order reader. <br> 1076 * **Default**: 0.05 1077 * - `sm.mem.reader.sparse_global_order.ratio_rcs` <br> 1078 * Ratio of the budget allocated for result cell slabs in the sparse 1079 * global order reader. <br> 1080 * **Default**: 0.05 1081 * - `sm.mem.reader.sparse_unordered_with_dups.ratio_coords` <br> 1082 * Ratio of the budget allocated for coordinates in the sparse unordered 1083 * with duplicates reader. <br> 1084 * **Default**: 0.5 1085 * - `sm.mem.reader.sparse_unordered_with_dups.ratio_query_condition` <br> 1086 * Ratio of the budget allocated for the query condition in the sparse 1087 * unordered with duplicates reader. <br> 1088 * **Default**: 0.25 1089 * - `sm.mem.reader.sparse_unordered_with_dups.ratio_tile_ranges` <br> 1090 * Ratio of the budget allocated for tile ranges in the sparse unordered 1091 * with duplicates reader. <br> 1092 * **Default**: 0.1 1093 * - `sm.mem.reader.sparse_unordered_with_dups.ratio_array_data` <br> 1094 * Ratio of the budget allocated for array data in the sparse unordered 1095 * with duplicates reader. <br> 1096 * **Default**: 0.1 1097 * - `sm.mem.reader.sparse_unordered_with_dups.ratio_result_tiles` <br> 1098 * Ratio of the budget allocated for result tiles in the sparse 1099 * unordered with duplicates reader. <br> 1100 * **Default**: 0.05 1101 * - `sm.mem.reader.sparse_unordered_with_dups.ratio_rcs` <br> 1102 * Ratio of the budget allocated for result cell slabs in the sparse 1103 * unordered with duplicates reader. <br> 1104 * **Default**: 0.05 1105 * - `vfs.read_ahead_size` <br> 1106 * The maximum byte size to read-ahead from the backend. <br> 1107 * **Default**: 102400 1108 * - `vfs.read_ahead_cache_size` <br> 1109 * The the total maximum size of the read-ahead cache, which is an LRU. <br> 1110 * **Default**: 10485760 1111 * - `vfs.min_parallel_size` <br> 1112 * The minimum number of bytes in a parallel VFS operation 1113 * (except parallel S3 writes, which are controlled by 1114 * `vfs.s3.multipart_part_size`). <br> 1115 * **Default**: 10MB 1116 * - `vfs.min_batch_size` <br> 1117 * The minimum number of bytes in a VFS read operation<br> 1118 * **Default**: 20MB 1119 * - `vfs.min_batch_gap` <br> 1120 * The minimum number of bytes between two VFS read batches.<br> 1121 * **Default**: 500KB 1122 * - `vfs.file.posix_file_permissions` <br> 1123 * Permissions to use for posix file system with file creation.<br> 1124 * **Default**: 644 1125 * - `vfs.file.posix_directory_permissions` <br> 1126 * Permissions to use for posix file system with directory creation.<br> 1127 * **Default**: 755 1128 * - `vfs.file.max_parallel_ops` <br> 1129 * The maximum number of parallel operations on objects with `file:///` 1130 * URIs. <br> 1131 * **Default**: `sm.io_concurrency_level` 1132 * - `vfs.file.enable_filelocks` <br> 1133 * If set to `false`, file locking operations are no-ops for `file:///` URIs 1134 * in VFS. <br> 1135 * **Default**: `true` 1136 * - `vfs.azure.storage_account_name` <br> 1137 * Set the Azure Storage Account name. <br> 1138 * **Default**: "" 1139 * - `vfs.azure.storage_account_key` <br> 1140 * Set the Azure Storage Account key. <br> 1141 * **Default**: "" 1142 * - `vfs.azure.storage_sas_token` <br> 1143 * Set the Azure Storage SAS (shared access signature) token. <br> 1144 * **Default**: "" 1145 * - `vfs.azure.blob_endpoint` <br> 1146 * Overrides the default Azure Storage Blob endpoint. If empty, the endpoint 1147 * will be constructed from the storage account name. This should not include 1148 * an http:// or https:// prefix. <br> 1149 * **Default**: "" 1150 * - `vfs.azure.block_list_block_size` <br> 1151 * The block size (in bytes) used in Azure blob block list writes. 1152 * Any `uint64_t` value is acceptable. Note: `vfs.azure.block_list_block_size 1153 * vfs.azure.max_parallel_ops` bytes will be buffered before issuing block 1154 * uploads in parallel. <br> 1155 * **Default**: "5242880" 1156 * - `vfs.azure.max_parallel_ops` <br> 1157 * The maximum number of Azure backend parallel operations. <br> 1158 * **Default**: `sm.io_concurrency_level` 1159 * - `vfs.azure.use_block_list_upload` <br> 1160 * Determines if the Azure backend can use chunked block uploads. <br> 1161 * **Default**: "true" 1162 * - `vfs.azure.use_https` <br> 1163 * Determines if the blob endpoint should use HTTP or HTTPS. 1164 * **Default**: "true" 1165 * - `vfs.gcs.project_id` <br> 1166 * Set the GCS project id. <br> 1167 * **Default**: "" 1168 * - `vfs.gcs.multi_part_size` <br> 1169 * The part size (in bytes) used in GCS multi part writes. 1170 * Any `uint64_t` value is acceptable. Note: 1171 * `vfs.gcs.multi_part_size * vfs.gcs.max_parallel_ops` bytes will 1172 * be buffered before issuing part uploads in parallel. <br> 1173 * **Default**: "5242880" 1174 * - `vfs.gcs.max_parallel_ops` <br> 1175 * The maximum number of GCS backend parallel operations. <br> 1176 * **Default**: `sm.io_concurrency_level` 1177 * - `vfs.gcs.use_multi_part_upload` <br> 1178 * Determines if the GCS backend can use chunked part uploads. <br> 1179 * **Default**: "true" 1180 * - `vfs.gcs.request_timeout_ms` <br> 1181 * The maximum amount of time to retry network requests to GCS. <br> 1182 * **Default**: "3000" 1183 * - `vfs.s3.region` <br> 1184 * The S3 region, if S3 is enabled. <br> 1185 * **Default**: us-east-1 1186 * - `vfs.s3.aws_access_key_id` <br> 1187 * Set the AWS_ACCESS_KEY_ID <br> 1188 * **Default**: "" 1189 * - `vfs.s3.aws_secret_access_key` <br> 1190 * Set the AWS_SECRET_ACCESS_KEY <br> 1191 * **Default**: "" 1192 * - `vfs.s3.aws_session_token` <br> 1193 * Set the AWS_SESSION_TOKEN <br> 1194 * **Default**: "" 1195 * - `vfs.s3.aws_role_arn` <br> 1196 * Determines the role that we want to assume. 1197 * Set the AWS_ROLE_ARN <br> 1198 * **Default**: "" 1199 * - `vfs.s3.aws_external_id` <br> 1200 * Third party access ID to your resources when assuming a role. 1201 * Set the AWS_EXTERNAL_ID <br> 1202 * **Default**: "" 1203 * - `vfs.s3.aws_load_frequency` <br> 1204 * Session time limit when assuming a role. 1205 * Set the AWS_LOAD_FREQUENCY <br> 1206 * **Default**: "" 1207 * - `vfs.s3.aws_session_name` <br> 1208 * (Optional) session name when assuming a role. 1209 * Can be used for tracing and bookkeeping. 1210 * Set the AWS_SESSION_NAME <br> 1211 * **Default**: "" 1212 * - `vfs.s3.scheme` <br> 1213 * The S3 scheme (`http` or `https`), if S3 is enabled. <br> 1214 * **Default**: https 1215 * - `vfs.s3.endpoint_override` <br> 1216 * The S3 endpoint, if S3 is enabled. <br> 1217 * **Default**: "" 1218 * - `vfs.s3.use_virtual_addressing` <br> 1219 * The S3 use of virtual addressing (`true` or `false`), if S3 is 1220 * enabled. <br> 1221 * **Default**: true 1222 * - `vfs.s3.skip_init` <br> 1223 * Skip Aws::InitAPI for the S3 layer (`true` or `false`) <br> 1224 * **Default**: false 1225 * - `vfs.s3.use_multipart_upload` <br> 1226 * The S3 use of multi-part upload requests (`true` or `false`), if S3 is 1227 * enabled. <br> 1228 * **Default**: true 1229 * - `vfs.s3.max_parallel_ops` <br> 1230 * The maximum number of S3 backend parallel operations. <br> 1231 * **Default**: `sm.io_concurrency_level` 1232 * - `vfs.s3.multipart_part_size` <br> 1233 * The part size (in bytes) used in S3 multipart writes. 1234 * Any `uint64_t` value is acceptable. Note: `vfs.s3.multipart_part_size * 1235 * vfs.s3.max_parallel_ops` bytes will be buffered before issuing multipart 1236 * uploads in parallel. <br> 1237 * **Default**: 5MB 1238 * - `vfs.s3.ca_file` <br> 1239 * Path to SSL/TLS certificate file to be used by cURL for for S3 HTTPS 1240 * encryption. Follows cURL conventions: 1241 * https://curl.haxx.se/docs/manpage.html 1242 * **Default**: "" 1243 * - `vfs.s3.ca_path` <br> 1244 * Path to SSL/TLS certificate directory to be used by cURL for S3 HTTPS 1245 * encryption. Follows cURL conventions: 1246 * https://curl.haxx.se/docs/manpage.html 1247 * **Default**: "" 1248 * - `vfs.s3.connect_timeout_ms` <br> 1249 * The connection timeout in ms. Any `long` value is acceptable. <br> 1250 * **Default**: 3000 1251 * - `vfs.s3.connect_max_tries` <br> 1252 * The maximum tries for a connection. Any `long` value is acceptable. <br> 1253 * **Default**: 5 1254 * - `vfs.s3.connect_scale_factor` <br> 1255 * The scale factor for exponential backoff when connecting to S3. 1256 * Any `long` value is acceptable. <br> 1257 * **Default**: 25 1258 * - `vfs.s3.logging_level` <br> 1259 * The AWS SDK logging level. This is a process-global setting. The 1260 * configuration of the most recently constructed context will set 1261 * process state. Log files are written to the process working directory. 1262 * **Default**: "" 1263 * - `vfs.s3.request_timeout_ms` <br> 1264 * The request timeout in ms. Any `long` value is acceptable. <br> 1265 * **Default**: 3000 1266 * - `vfs.s3.requester_pays` <br> 1267 * The requester pays for the S3 access charges. <br> 1268 * **Default**: false 1269 * - `vfs.s3.proxy_host` <br> 1270 * The S3 proxy host. <br> 1271 * **Default**: "" 1272 * - `vfs.s3.proxy_port` <br> 1273 * The S3 proxy port. <br> 1274 * **Default**: 0 1275 * - `vfs.s3.proxy_scheme` <br> 1276 * The S3 proxy scheme. <br> 1277 * **Default**: "http" 1278 * - `vfs.s3.proxy_username` <br> 1279 * The S3 proxy username. Note: this parameter is not serialized by 1280 * `tiledb_config_save_to_file`. <br> 1281 * **Default**: "" 1282 * - `vfs.s3.proxy_password` <br> 1283 * The S3 proxy password. Note: this parameter is not serialized by 1284 * `tiledb_config_save_to_file`. <br> 1285 * **Default**: "" 1286 * - `vfs.s3.verify_ssl` <br> 1287 * Enable HTTPS certificate verification. <br> 1288 * **Default**: true"" 1289 * - `vfs.s3.sse` <br> 1290 * The server-side encryption algorithm to use. Supported non-empty 1291 * values are "aes256" and "kms" (AWS key management service). <br> 1292 * **Default**: "" 1293 * - `vfs.s3.bucket_canned_acl` <br> 1294 * Names of values found in Aws::S3::Model::BucketCannedACL enumeration. 1295 * "NOT_SET" 1296 * "private_" 1297 * "public_read" 1298 * "public_read_write" 1299 * "authenticated_read" 1300 * **Default**: "NOT_SET" 1301 * - `vfs.s3.object_canned_acl` <br> 1302 * Names of values found in Aws::S3::Model::ObjectCannedACL enumeration. 1303 * (The first 5 are the same as for "vfs.s3.bucket_canned_acl".) 1304 * "NOT_SET" 1305 * "private_" 1306 * "public_read" 1307 * "public_read_write" 1308 * "authenticated_read" 1309 * (The following three items are found only in 1310 * Aws::S3::Model::ObjectCannedACL.) "aws_exec_read" "owner_read" 1311 * "bucket_owner_full_control" 1312 * **Default**: "NOT_SET" 1313 * - `vfs.hdfs.name_node_uri"` <br> 1314 * Name node for HDFS. <br> 1315 * **Default**: "" 1316 * - `vfs.hdfs.username` <br> 1317 * HDFS username. <br> 1318 * **Default**: "" 1319 * - `vfs.hdfs.kerb_ticket_cache_path` <br> 1320 * HDFS kerb ticket cache path. <br> 1321 * **Default**: "" 1322 * - `config.env_var_prefix` <br> 1323 * Prefix of environmental variables for reading configuration 1324 * parameters. <br> 1325 * **Default**: "TILEDB_" 1326 * - `config.logging_level` <br> 1327 * The logging level configured, possible values: "0": fatal, "1": error, 1328 * "2": warn, "3": info "4": debug, "5": trace <br> 1329 * **Default**: "1" if --enable-verbose bootstrap flag is provided, 1330 * "0" otherwise <br> 1331 * - `config.logging_format` <br> 1332 * The logging format configured (DEFAULT or JSON) 1333 * **Default**: "DEFAULT" 1334 * - `rest.server_address` <br> 1335 * URL for REST server to use for remote arrays. <br> 1336 * **Default**: "https://api.tiledb.com" 1337 * - `rest.server_serialization_format` <br> 1338 * Serialization format to use for remote array requests (CAPNP or 1339 * JSON). <br> 1340 * **Default**: "CAPNP" 1341 * - `rest.username` <br> 1342 * Username for login to REST server. <br> 1343 * **Default**: "" 1344 * - `rest.password` <br> 1345 * Password for login to REST server. <br> 1346 * **Default**: "" 1347 * - `rest.token` <br> 1348 * Authentication token for REST server (used instead of 1349 * username/password). <br> 1350 * **Default**: "" 1351 * - `rest.resubmit_incomplete` <br> 1352 * If true, incomplete queries received from server are automatically 1353 * resubmitted before returning to user control. <br> 1354 * **Default**: "true" 1355 * - `rest.ignore_ssl_validation` <br> 1356 * Have curl ignore ssl peer and host validation for REST server. <br> 1357 * **Default**: false 1358 * - `rest.creation_access_credentials_name` <br> 1359 * The name of the registered access key to use for creation of the REST 1360 * server. <br> 1361 * **Default**: no default set 1362 * - `rest.retry_http_codes` <br> 1363 * CSV list of http status codes to automatically retry a REST request for 1364 * <br> 1365 * **Default**: "503" 1366 * - `rest.retry_count` <br> 1367 * Number of times to retry failed REST requests <br> 1368 * **Default**: 3 1369 * - `rest.retry_initial_delay_ms` <br> 1370 * Initial delay in milliseconds to wait until retrying a REST request <br> 1371 * **Default**: 500 1372 * - `rest.retry_delay_factor` <br> 1373 * The delay factor to exponentially wait until further retries of a failed 1374 * REST request <br> 1375 * **Default**: 1.25 1376 * 1377 * **Example:** 1378 * 1379 * @code{.c} 1380 * tiledb_error_t* error = NULL; 1381 * tiledb_config_set(config, "sm.tile_cache_size", "1000000", &error); 1382 * @endcode 1383 * 1384 * @param config The config object. 1385 * @param param The parameter to be set. 1386 * @param value The value of the parameter to be set. 1387 * @param error Error object returned upon error (`NULL` if there is 1388 * no error). 1389 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1390 */ 1391 TILEDB_EXPORT int32_t tiledb_config_set( 1392 tiledb_config_t* config, 1393 const char* param, 1394 const char* value, 1395 tiledb_error_t** error); 1396 1397 /** 1398 * Gets a config parameter. 1399 * 1400 * **Example:** 1401 * 1402 * @code{.c} 1403 * const char* value; 1404 * tiledb_error_t* error = NULL; 1405 * tiledb_config_get(config, "sm.tile_cache_size", &value, &error); 1406 * @endcode 1407 * 1408 * @param config The config object. 1409 * @param param The parameter to be set. 1410 * @param value A pointer to the value of the parameter to be retrieved 1411 * (`NULL` if it does not exist). 1412 * @param error Error object returned upon error (`NULL` if there is 1413 * no error). 1414 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1415 */ 1416 TILEDB_EXPORT int32_t tiledb_config_get( 1417 tiledb_config_t* config, 1418 const char* param, 1419 const char** value, 1420 tiledb_error_t** error); 1421 1422 /** 1423 * Loads config parameters from a (local) text file. 1424 * 1425 * **Example:** 1426 * 1427 * @code{.c} 1428 * tiledb_error_t* error = NULL; 1429 * tiledb_config_load_from_file(config, "tiledb.conf", &error); 1430 * @endcode 1431 * 1432 * @param config The config object. 1433 * @param filename The name of the file. 1434 * @param error Error object returned upon error (`NULL` if there is 1435 * no error). 1436 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1437 */ 1438 TILEDB_EXPORT int32_t tiledb_config_load_from_file( 1439 tiledb_config_t* config, const char* filename, tiledb_error_t** error); 1440 1441 /** 1442 * Unsets a config parameter. This will set the config parameter to its 1443 * default value. 1444 * 1445 * **Example:** 1446 * 1447 * @code{.c} 1448 * tiledb_error_t* error = NULL; 1449 * tiledb_config_unset(config, "sm.tile_cache_size", &error); 1450 * @endcode 1451 * 1452 * @param config The config object. 1453 * @param param The parameter to be unset. 1454 * @param error Error object returned upon error (`NULL` if there is 1455 * no error). 1456 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1457 */ 1458 TILEDB_EXPORT int32_t tiledb_config_unset( 1459 tiledb_config_t* config, const char* param, tiledb_error_t** error); 1460 1461 /** 1462 * Saves the config parameters to a (local) text file. 1463 * 1464 * **Example:** 1465 * 1466 * @code{.c} 1467 * tiledb_error_t* error = NULL; 1468 * tiledb_config_save_to_file(config, "tiledb.conf", &error); 1469 * @endcode 1470 * 1471 * @param config The config object. 1472 * @param filename The name of the file. 1473 * @param error Error object returned upon error (`NULL` if there is 1474 * no error). 1475 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1476 */ 1477 TILEDB_EXPORT int32_t tiledb_config_save_to_file( 1478 tiledb_config_t* config, const char* filename, tiledb_error_t** error); 1479 1480 /** 1481 * Compares 2 configurations for equality 1482 * 1483 * **Example:** 1484 * 1485 * @code{.c} 1486 * tiledb_error_t error; 1487 * uint8_t equal; 1488 * tiledb_config_compare(lhs, rhs, &equal); 1489 * @endcode 1490 * 1491 * @param lhs The left-hand side config object. 1492 * @param rhs The right-hand side config object. 1493 * @param equal Integer of equality comparison 1494 * 1 = true, 0 = false 1495 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1496 */ 1497 TILEDB_EXPORT int32_t tiledb_config_compare( 1498 tiledb_config_t* lhs, tiledb_config_t* rhs, uint8_t* equal); 1499 1500 /* ****************************** */ 1501 /* CONFIG ITER */ 1502 /* ****************************** */ 1503 1504 /** 1505 * Creates an iterator on a config object. 1506 * 1507 * **Examples:** 1508 * 1509 * The following creates a config iterator without a prefix. This 1510 * will iterate over all config param/values. 1511 * 1512 * @code{.c} 1513 * tiledb_error_t* error = NULL; 1514 * tiledb_config_iter_t* config_iter; 1515 * tiledb_config_iter_alloc(config, NULL, &config_iter, &error); 1516 * @endcode 1517 * 1518 * The following creates a config iterator with a prefix. This 1519 * will iterate over all S3 config param/values, stripping out 1520 * `vfs.s3.`. For instance, instead of retrieving `vfs.s3.region` 1521 * as a parameter via `tiledb_config_iter_here`, it will retrieve 1522 * `region`. 1523 * 1524 * @code{.c} 1525 * tiledb_error_t* error = NULL; 1526 * tiledb_config_iter_t* config_iter; 1527 * tiledb_config_iter_alloc(config, "vfs.s3.", &config_iter, &error); 1528 * @endcode 1529 * 1530 * @param config A config object the iterator will operate on. 1531 * @param prefix If not `NULL`, only the config parameters starting 1532 * with `prefix*` will be iterated on. Moreover, the prefix will 1533 * be stripped from the parameters. Otherwise, all parameters will 1534 * be iterated on and their full name will be retrieved. 1535 * @param config_iter The config iterator to be created. 1536 * @param error Error object returned upon error (`NULL` if there is 1537 * no error). 1538 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 1539 */ 1540 TILEDB_EXPORT int32_t tiledb_config_iter_alloc( 1541 tiledb_config_t* config, 1542 const char* prefix, 1543 tiledb_config_iter_t** config_iter, 1544 tiledb_error_t** error); 1545 1546 /** 1547 * Resets the iterator. 1548 * 1549 * **Examples:** 1550 * 1551 * Without a prefix: 1552 * 1553 * @code{.c} 1554 * tiledb_config_iter_reset(config, config_iter, NULL, &error); 1555 * @endcode 1556 * 1557 * With a prefix: 1558 * 1559 * @code{.c} 1560 * tiledb_config_iter_reset(config, config_iter, "vfs.s3.", &error); 1561 * @endcode 1562 * 1563 * @param config A config object the iterator will operate on. 1564 * @param config_iter The config iterator to be reset. 1565 * @param prefix If not `NULL`, only the config parameters starting 1566 * with `prefix*` will be iterated on. Moreover, the prefix will 1567 * be stripped from the parameters. Otherwise, all parameters will 1568 * be iterated on and their full name will be retrieved. 1569 * @param error Error object returned upon error (`NULL` if there is 1570 * no error). 1571 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1572 */ 1573 TILEDB_EXPORT int32_t tiledb_config_iter_reset( 1574 tiledb_config_t* config, 1575 tiledb_config_iter_t* config_iter, 1576 const char* prefix, 1577 tiledb_error_t** error); 1578 1579 /** 1580 * Frees a config iterator. 1581 * 1582 * **Example:** 1583 * 1584 * @code{.c} 1585 * tiledb_config_iter_free(&config_iter); 1586 * @endcode 1587 * 1588 * @param config_iter The config iterator to be freed. 1589 */ 1590 TILEDB_EXPORT void tiledb_config_iter_free(tiledb_config_iter_t** config_iter); 1591 1592 /** 1593 * Retrieves the config param and value currently pointed by the iterator. 1594 * 1595 * **Example:** 1596 * 1597 * @code{.c} 1598 * const char *param, *value; 1599 * tiledb_config_iter_here(config_iter, ¶m, &value, &error); 1600 * @endcode 1601 * 1602 * @param config_iter The config iterator. 1603 * @param param The config parameter to be retrieved (`NULL` if the iterator 1604 * is at the end). 1605 * @param value The config value to be retrieved (`NULL` if the iterator 1606 * is at the end). 1607 * @param error Error object returned upon error (`NULL` if there is 1608 * no error). 1609 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1610 */ 1611 TILEDB_EXPORT int32_t tiledb_config_iter_here( 1612 tiledb_config_iter_t* config_iter, 1613 const char** param, 1614 const char** value, 1615 tiledb_error_t** error); 1616 1617 /** 1618 * Moves the iterator to the next param. 1619 * 1620 * **Example:** 1621 * 1622 * @code{.c} 1623 * tiledb_config_iter_next(config_iter, &error); 1624 * @endcode 1625 * 1626 * @param config_iter The config iterator. 1627 * @param error Error object returned upon error (`NULL` if there is 1628 * no error). 1629 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1630 */ 1631 TILEDB_EXPORT int32_t tiledb_config_iter_next( 1632 tiledb_config_iter_t* config_iter, tiledb_error_t** error); 1633 1634 /** 1635 * Checks if the iterator is done. 1636 * 1637 * **Example:** 1638 * 1639 * @code{.c} 1640 * int32_t done; 1641 * tiledb_config_iter_done(config_iter, &done, &error); 1642 * @endcode 1643 * 1644 * @param config_iter The config iterator. 1645 * @param done Sets this to `1` if the iterator is done, `0` otherwise. 1646 * @param error Error object returned upon error (`NULL` if there is 1647 * no error). 1648 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1649 */ 1650 TILEDB_EXPORT int32_t tiledb_config_iter_done( 1651 tiledb_config_iter_t* config_iter, int32_t* done, tiledb_error_t** error); 1652 1653 /* ********************************* */ 1654 /* CONTEXT */ 1655 /* ********************************* */ 1656 1657 /** 1658 * Creates a TileDB context, which contains the TileDB storage manager 1659 * that manages everything in the TileDB library. 1660 * 1661 * **Examples:** 1662 * 1663 * Without config (i.e., use default configuration): 1664 * 1665 * @code{.c} 1666 * tiledb_ctx_t* ctx; 1667 * tiledb_ctx_alloc(NULL, &ctx); 1668 * @endcode 1669 * 1670 * With some config: 1671 * 1672 * @code{.c} 1673 * tiledb_ctx_t* ctx; 1674 * tiledb_ctx_alloc(config, &ctx); 1675 * @endcode 1676 * 1677 * @param config The configuration parameters (`NULL` means default). 1678 * @param ctx The TileDB context to be created. 1679 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 1680 */ 1681 TILEDB_EXPORT int32_t 1682 tiledb_ctx_alloc(tiledb_config_t* config, tiledb_ctx_t** ctx); 1683 1684 /** 1685 * Destroys the TileDB context, freeing all associated memory and resources. 1686 * 1687 * **Example:** 1688 * 1689 * @code{.c} 1690 * tiledb_ctx_t* ctx; 1691 * tiledb_ctx_alloc(NULL, &ctx); 1692 * tiledb_ctx_free(&ctx); 1693 * @endcode 1694 * 1695 * @param ctx The TileDB context to be freed. 1696 */ 1697 TILEDB_EXPORT void tiledb_ctx_free(tiledb_ctx_t** ctx); 1698 1699 /** 1700 * Retrieves the stats from a TileDB context. 1701 * 1702 * **Example:** 1703 * 1704 * @code{.c} 1705 * char* stats_json; 1706 * tiledb_ctx_get_stats(ctx, &stats_json); 1707 * // Make sure to free the retrieved `stats_json` 1708 * @endcode 1709 * 1710 * @param ctx The TileDB context. 1711 * @param stats_json The output json. The caller takes ownership 1712 * of the c-string. 1713 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 1714 */ 1715 TILEDB_EXPORT int32_t 1716 tiledb_ctx_get_stats(tiledb_ctx_t* ctx, char** stats_json); 1717 1718 /** 1719 * Retrieves a copy of the config from a TileDB context. 1720 * Modifying this config will not affect the initialized 1721 * context configuration. 1722 * 1723 * 1724 * **Example:** 1725 * 1726 * @code{.c} 1727 * tiledb_config_t* config; 1728 * tiledb_ctx_get_config(ctx, &config); 1729 * // Make sure to free the retrieved config 1730 * @endcode 1731 * 1732 * @param ctx The TileDB context. 1733 * @param config The config to be retrieved. 1734 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 1735 */ 1736 TILEDB_EXPORT int32_t 1737 tiledb_ctx_get_config(tiledb_ctx_t* ctx, tiledb_config_t** config); 1738 1739 /** 1740 * Retrieves the last TileDB error associated with a TileDB context. 1741 * 1742 * **Example:** 1743 * 1744 * @code{.c} 1745 * tiledb_error_t* error; 1746 * tiledb_ctx_get_last_error(ctx, &error); 1747 * // Make sure to free the retrieved error, checking first if it is NULL 1748 * @endcode 1749 * 1750 * @param ctx The TileDB context. 1751 * @param err The last error, or `NULL` if no error has been raised. 1752 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 1753 */ 1754 TILEDB_EXPORT int32_t 1755 tiledb_ctx_get_last_error(tiledb_ctx_t* ctx, tiledb_error_t** err); 1756 1757 /** 1758 * Checks if a given storage filesystem backend is supported. 1759 * 1760 * **Example:** 1761 * 1762 * @code{.c} 1763 * int32_t is_supported; 1764 * tiledb_ctx_is_supported_fs(ctx, TILEDB_HDFS, &is_supported); 1765 * @endcode 1766 * 1767 * @param ctx The TileDB context. 1768 * @param fs The filesystem to be checked. 1769 * @param is_supported Sets it to `1` if the filesystem is supported, and 1770 * `0` otherwise. 1771 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1772 */ 1773 TILEDB_EXPORT int32_t tiledb_ctx_is_supported_fs( 1774 tiledb_ctx_t* ctx, tiledb_filesystem_t fs, int32_t* is_supported); 1775 1776 /** 1777 * Cancels all background or async tasks associated with the given context. 1778 * 1779 * @param ctx The TileDB context. 1780 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1781 */ 1782 TILEDB_EXPORT int32_t tiledb_ctx_cancel_tasks(tiledb_ctx_t* ctx); 1783 1784 /** 1785 * Sets a string key-value "tag" on the given context. 1786 * 1787 * **Example:** 1788 * 1789 * @code{.c} 1790 * tiledb_ctx_set_tag(ctx, "tag key", "tag value"); 1791 * @endcode 1792 * 1793 * @param ctx The TileDB context. 1794 * @param key The tag key 1795 * @param value The tag value. 1796 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1797 */ 1798 TILEDB_EXPORT int32_t 1799 tiledb_ctx_set_tag(tiledb_ctx_t* ctx, const char* key, const char* value); 1800 1801 /* ********************************* */ 1802 /* GROUP */ 1803 /* ********************************* */ 1804 1805 /** 1806 * Creates a new TileDB group. 1807 * 1808 * **Example:** 1809 * 1810 * @code{.c} 1811 * tiledb_group_create(ctx, "my_group"); 1812 * @endcode 1813 * 1814 * @param ctx The TileDB context. 1815 * @param group_uri The group URI. 1816 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1817 */ 1818 TILEDB_EXPORT int32_t 1819 tiledb_group_create(tiledb_ctx_t* ctx, const char* group_uri); 1820 1821 /* ********************************* */ 1822 /* FILTER */ 1823 /* ********************************* */ 1824 1825 /** 1826 * Creates a TileDB filter. 1827 * 1828 * **Example:** 1829 * 1830 * @code{.c} 1831 * tiledb_filter_t* filter; 1832 * tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter); 1833 * @endcode 1834 * 1835 * @param ctx The TileDB context. 1836 * @param type The filter type. 1837 * @param filter The TileDB filter to be created. 1838 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 1839 */ 1840 TILEDB_EXPORT int32_t tiledb_filter_alloc( 1841 tiledb_ctx_t* ctx, tiledb_filter_type_t type, tiledb_filter_t** filter); 1842 1843 /** 1844 * Destroys a TileDB filter, freeing associated memory. 1845 * 1846 * **Example:** 1847 * 1848 * @code{.c} 1849 * tiledb_filter_t* filter; 1850 * tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter); 1851 * tiledb_filter_free(&filter); 1852 * @endcode 1853 * 1854 * @param filter The filter to be destroyed. 1855 */ 1856 TILEDB_EXPORT void tiledb_filter_free(tiledb_filter_t** filter); 1857 1858 /** 1859 * Retrieves the type of a filter. 1860 * 1861 * **Example:** 1862 * 1863 * @code{.c} 1864 * tiledb_filter_t* filter; 1865 * tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter); 1866 * tiledb_filter_type_t type; 1867 * tiledb_filter_get_type(ctx, filter, &type); 1868 * // type == TILEDB_FILTER_BZIP2 1869 * @endcode 1870 * 1871 * @param ctx The TileDB context. 1872 * @param filter The TileDB filter. 1873 * @param type The filter type to be retrieved. 1874 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 1875 */ 1876 TILEDB_EXPORT int32_t tiledb_filter_get_type( 1877 tiledb_ctx_t* ctx, tiledb_filter_t* filter, tiledb_filter_type_t* type); 1878 1879 /** 1880 * Sets an option on a filter. Options are filter dependent; this function 1881 * returns an error if the given option is not valid for the given filter. 1882 * 1883 * **Example:** 1884 * 1885 * @code{.c} 1886 * tiledb_filter_t* filter; 1887 * tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter); 1888 * int32_t level = 5; 1889 * tiledb_filter_set_option(ctx, filter, TILEDB_COMPRESSION_LEVEL, &level); 1890 * tiledb_filter_free(&filter); 1891 * @endcode 1892 * 1893 * @param ctx TileDB context. 1894 * @param filter The target filter. 1895 * @param option Filter option to set. 1896 * @param value Value of option to set. 1897 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 1898 */ 1899 TILEDB_EXPORT int32_t tiledb_filter_set_option( 1900 tiledb_ctx_t* ctx, 1901 tiledb_filter_t* filter, 1902 tiledb_filter_option_t option, 1903 const void* value); 1904 1905 /** 1906 * Gets an option value from a filter. Options are filter dependent; this 1907 * function returns an error if the given option is not valid for the given 1908 * filter. 1909 * 1910 * **Example:** 1911 * 1912 * @code{.c} 1913 * tiledb_filter_t* filter; 1914 * tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter); 1915 * int32_t level; 1916 * tiledb_filter_get_option(ctx, filter, TILEDB_COMPRESSION_LEVEL, &level); 1917 * // level == -1 (the default) 1918 * tiledb_filter_free(&filter); 1919 * @endcode 1920 * 1921 * @note The buffer pointed to by `value` must be large enough to hold the 1922 * option value. 1923 * 1924 * @param ctx TileDB context. 1925 * @param filter The target filter. 1926 * @param option Filter option to get. 1927 * @param value Buffer that option value will be written to. 1928 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 1929 */ 1930 TILEDB_EXPORT int32_t tiledb_filter_get_option( 1931 tiledb_ctx_t* ctx, 1932 tiledb_filter_t* filter, 1933 tiledb_filter_option_t option, 1934 void* value); 1935 1936 /* ********************************* */ 1937 /* FILTER LIST */ 1938 /* ********************************* */ 1939 1940 /** 1941 * Creates a TileDB filter list (pipeline of filters). 1942 * 1943 * **Example:** 1944 * 1945 * @code{.c} 1946 * tiledb_filter_list_t* filter_list; 1947 * tiledb_filter_list_alloc(ctx, &filter_list); 1948 * @endcode 1949 * 1950 * @param ctx The TileDB context. 1951 * @param filter_list The TileDB filter list to be created. 1952 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 1953 */ 1954 TILEDB_EXPORT int32_t 1955 tiledb_filter_list_alloc(tiledb_ctx_t* ctx, tiledb_filter_list_t** filter_list); 1956 1957 /** 1958 * Destroys a TileDB filter list, freeing associated memory. 1959 * 1960 * **Example:** 1961 * 1962 * @code{.c} 1963 * tiledb_filter_list_t* filter_list; 1964 * tiledb_filter_list_alloc(ctx, &filter_list); 1965 * tiledb_filter_list_free(&filter_list); 1966 * @endcode 1967 * 1968 * @param filter_list The filter list to be destroyed. 1969 */ 1970 TILEDB_EXPORT void tiledb_filter_list_free(tiledb_filter_list_t** filter_list); 1971 1972 /** 1973 * Appends a filter to a filter list. Data is processed through each filter in 1974 * the order the filters were added. 1975 * 1976 * **Example:** 1977 * 1978 * @code{.c} 1979 * tiledb_filter_t* filter; 1980 * tiledb_filter_alloc(ctx, TILEDB_FILTER_BZIP2, &filter); 1981 * 1982 * tiledb_filter_list_t* filter_list; 1983 * tiledb_filter_list_alloc(ctx, &filter_list); 1984 * tiledb_filter_list_add_filter(ctx, filter_list, filter); 1985 * 1986 * tiledb_filter_list_free(&filter_list); 1987 * tiledb_filter_free(&filter); 1988 * @endcode 1989 * 1990 * @param ctx The TileDB context. 1991 * @param filter_list The target filter list. 1992 * @param filter The filter to add. 1993 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 1994 */ 1995 TILEDB_EXPORT int32_t tiledb_filter_list_add_filter( 1996 tiledb_ctx_t* ctx, 1997 tiledb_filter_list_t* filter_list, 1998 tiledb_filter_t* filter); 1999 2000 /** 2001 * Sets the maximum tile chunk size for a filter list. 2002 * 2003 * **Example:** 2004 * 2005 * @code{.c} 2006 * // Set max chunk size to 16KB: 2007 * tiledb_filter_list_set_max_chunk_size(ctx, filter_list, 16384); 2008 * @endcode 2009 * 2010 * @param ctx The TileDB context 2011 * @param filter_list The target filter list 2012 * @param max_chunk_size The max chunk size value to set 2013 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2014 */ 2015 TILEDB_EXPORT int32_t tiledb_filter_list_set_max_chunk_size( 2016 tiledb_ctx_t* ctx, 2017 const tiledb_filter_list_t* filter_list, 2018 uint32_t max_chunk_size); 2019 2020 /** 2021 * Retrieves the number of filters in a filter list. 2022 * 2023 * **Example:** 2024 * 2025 * @code{.c} 2026 * uint32_t num_filters; 2027 * tiledb_filter_list_get_nfilters(ctx, filter_list, &num_filters); 2028 * @endcode 2029 * 2030 * @param ctx The TileDB context 2031 * @param filter_list The filter list 2032 * @param nfilters The number of filters on the filter list 2033 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2034 */ 2035 TILEDB_EXPORT int32_t tiledb_filter_list_get_nfilters( 2036 tiledb_ctx_t* ctx, 2037 const tiledb_filter_list_t* filter_list, 2038 uint32_t* nfilters); 2039 2040 /** 2041 * Retrieves a filter object from a filter list by index. 2042 * 2043 * **Example:** 2044 * 2045 * The following retrieves the first filter from a filter list. 2046 * 2047 * @code{.c} 2048 * tiledb_filter_t* filter; 2049 * tiledb_filter_list_get_filter_from_index(ctx, filter_list, 0, &filter); 2050 * tiledb_filter_free(&filter); 2051 * @endcode 2052 * 2053 * @param ctx The TileDB context 2054 * @param filter_list The filter list to retrieve the filter from 2055 * @param index The index of the filter 2056 * @param filter The retrieved filter object. 2057 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2058 */ 2059 TILEDB_EXPORT int32_t tiledb_filter_list_get_filter_from_index( 2060 tiledb_ctx_t* ctx, 2061 const tiledb_filter_list_t* filter_list, 2062 uint32_t index, 2063 tiledb_filter_t** filter); 2064 2065 /** 2066 * Gets the maximum tile chunk size for a filter list. 2067 * 2068 * **Example:** 2069 * 2070 * @code{.c} 2071 * uint32_t max_chunk_size; 2072 * tiledb_filter_list_get_max_chunk_size(ctx, filter_list, &max_chunk_size); 2073 * @endcode 2074 * 2075 * @param ctx The TileDB context 2076 * @param filter_list The target filter list 2077 * @param max_chunk_size The retrieved max chunk size value 2078 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2079 */ 2080 TILEDB_EXPORT int32_t tiledb_filter_list_get_max_chunk_size( 2081 tiledb_ctx_t* ctx, 2082 const tiledb_filter_list_t* filter_list, 2083 uint32_t* max_chunk_size); 2084 2085 /* ********************************* */ 2086 /* ATTRIBUTE */ 2087 /* ********************************* */ 2088 2089 /** 2090 * Creates a TileDB attribute. 2091 * 2092 * **Example:** 2093 * 2094 * @code{.c} 2095 * tiledb_attribute_t* attr; 2096 * tiledb_attribute_alloc(ctx, "my_attr", TILEDB_INT32, &attr); 2097 * @endcode 2098 * 2099 * @param ctx The TileDB context. 2100 * @param name The attribute name. Providing an empty string for the name 2101 * creates an anonymous attribute. 2102 * @param type The attribute type. 2103 * @param attr The TileDB attribute to be created. 2104 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 2105 * 2106 * @note The default number of values per cell is 1. 2107 */ 2108 TILEDB_EXPORT int32_t tiledb_attribute_alloc( 2109 tiledb_ctx_t* ctx, 2110 const char* name, 2111 tiledb_datatype_t type, 2112 tiledb_attribute_t** attr); 2113 2114 /** 2115 * Destroys a TileDB attribute, freeing associated memory. 2116 * 2117 * **Example:** 2118 * 2119 * @code{.c} 2120 * tiledb_attribute_t* attr; 2121 * tiledb_attribute_alloc(ctx, "my_attr", TILEDB_INT32, &attr); 2122 * tiledb_attribute_free(&attr); 2123 * @endcode 2124 * 2125 * @param attr The attribute to be destroyed. 2126 */ 2127 TILEDB_EXPORT void tiledb_attribute_free(tiledb_attribute_t** attr); 2128 2129 /** 2130 * Sets the nullability of an attribute. 2131 * 2132 * **Example:** 2133 * 2134 * @code{.c} 2135 * tiledb_attribute_set_nullable(ctx, attr, 1); 2136 * @endcode 2137 * 2138 * @param ctx The TileDB context. 2139 * @param attr The target attribute. 2140 * @param nullable Non-zero if the attribute is nullable. 2141 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2142 */ 2143 TILEDB_EXPORT int32_t tiledb_attribute_set_nullable( 2144 tiledb_ctx_t* ctx, tiledb_attribute_t* attr, uint8_t nullable); 2145 2146 /** 2147 * Sets the filter list for an attribute. 2148 * 2149 * **Example:** 2150 * 2151 * @code{.c} 2152 * tiledb_filter_list_t* filter_list; 2153 * tiledb_filter_list_alloc(ctx, &filter_list); 2154 * tiledb_filter_list_add_filter(ctx, filter_list, filter); 2155 * tiledb_attribute_set_filter_list(ctx, attr, filter_list); 2156 * @endcode 2157 * 2158 * @param ctx The TileDB context. 2159 * @param attr The target attribute. 2160 * @param filter_list The filter_list to be set. 2161 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2162 */ 2163 TILEDB_EXPORT int32_t tiledb_attribute_set_filter_list( 2164 tiledb_ctx_t* ctx, 2165 tiledb_attribute_t* attr, 2166 tiledb_filter_list_t* filter_list); 2167 2168 /** 2169 * Sets the number of values per cell for an attribute. If this is not 2170 * used, the default is `1`. 2171 * 2172 * **Examples:** 2173 * 2174 * For a fixed-sized attribute: 2175 * 2176 * @code{.c} 2177 * tiledb_attribute_set_cell_val_num(ctx, attr, 3); 2178 * @endcode 2179 * 2180 * For a variable-sized attribute: 2181 * 2182 * @code{.c} 2183 * tiledb_attribute_set_cell_val_num(ctx, attr, TILEDB_VAR_NUM); 2184 * @endcode 2185 * 2186 * @param ctx The TileDB context. 2187 * @param attr The target attribute. 2188 * @param cell_val_num The number of values per cell. 2189 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2190 */ 2191 TILEDB_EXPORT int32_t tiledb_attribute_set_cell_val_num( 2192 tiledb_ctx_t* ctx, tiledb_attribute_t* attr, uint32_t cell_val_num); 2193 2194 /** 2195 * Retrieves the attribute name. 2196 * 2197 * **Example:** 2198 * 2199 * @code{.c} 2200 * const char* attr_name; 2201 * tiledb_attribute_get_name(ctx, attr, &attr_name); 2202 * @endcode 2203 * 2204 * @param ctx The TileDB context. 2205 * @param attr The attribute. 2206 * @param name The name to be retrieved. 2207 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2208 */ 2209 TILEDB_EXPORT int32_t tiledb_attribute_get_name( 2210 tiledb_ctx_t* ctx, const tiledb_attribute_t* attr, const char** name); 2211 2212 /** 2213 * Retrieves the attribute type. 2214 * 2215 * **Example:** 2216 * 2217 * @code{.c} 2218 * tiledb_datatype_t attr_type; 2219 * tiledb_attribute_get_type(ctx, attr, &attr_type); 2220 * @endcode 2221 * 2222 * @param ctx The TileDB context. 2223 * @param attr The attribute. 2224 * @param type The type to be retrieved. 2225 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2226 */ 2227 TILEDB_EXPORT int32_t tiledb_attribute_get_type( 2228 tiledb_ctx_t* ctx, const tiledb_attribute_t* attr, tiledb_datatype_t* type); 2229 2230 /** 2231 * Sets the nullability of an attribute. 2232 * 2233 * **Example:** 2234 * 2235 * @code{.c} 2236 * uint8_t nullable; 2237 * tiledb_attribute_get_nullable(ctx, attr, &nullable); 2238 * @endcode 2239 * 2240 * @param ctx The TileDB context. 2241 * @param attr The target attribute. 2242 * @param nullable Output argument, non-zero for nullable and zero 2243 * for non-nullable. 2244 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2245 */ 2246 TILEDB_EXPORT int32_t tiledb_attribute_get_nullable( 2247 tiledb_ctx_t* ctx, tiledb_attribute_t* attr, uint8_t* nullable); 2248 2249 /** 2250 * Retrieves the filter list for an attribute. 2251 * 2252 * **Example:** 2253 * 2254 * @code{.c} 2255 * tiledb_filter_list_t* filter_list; 2256 * tiledb_attribute_get_filter_list(ctx, attr, &filter_list); 2257 * tiledb_filter_list_free(&filter_list); 2258 * @endcode 2259 * 2260 * @param ctx The TileDB context. 2261 * @param attr The target attribute. 2262 * @param filter_list The filter list to be retrieved. 2263 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2264 */ 2265 TILEDB_EXPORT int32_t tiledb_attribute_get_filter_list( 2266 tiledb_ctx_t* ctx, 2267 tiledb_attribute_t* attr, 2268 tiledb_filter_list_t** filter_list); 2269 2270 /** 2271 * Retrieves the number of values per cell for the attribute. For variable-sized 2272 * attributes result is TILEDB_VAR_NUM. 2273 * 2274 * **Example:** 2275 * 2276 * @code{.c} 2277 * uint32_t num; 2278 * tiledb_attribute_get_cell_val_num(ctx, attr, &num); 2279 * @endcode 2280 * 2281 * @param ctx The TileDB context. 2282 * @param attr The attribute. 2283 * @param cell_val_num The number of values per cell to be retrieved. 2284 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2285 */ 2286 TILEDB_EXPORT int32_t tiledb_attribute_get_cell_val_num( 2287 tiledb_ctx_t* ctx, const tiledb_attribute_t* attr, uint32_t* cell_val_num); 2288 2289 /** 2290 * Retrieves the cell size for this attribute. 2291 * 2292 * **Example:** 2293 * 2294 * @code{.c} 2295 * uint64_t cell_size; 2296 * tiledb_attribute_get_cell_size(ctx, attr, &cell_size); 2297 * @endcode 2298 * 2299 * @param ctx The TileDB context. 2300 * @param attr The attribute. 2301 * @param cell_size The cell size to be retrieved. 2302 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2303 */ 2304 TILEDB_EXPORT int32_t tiledb_attribute_get_cell_size( 2305 tiledb_ctx_t* ctx, const tiledb_attribute_t* attr, uint64_t* cell_size); 2306 2307 /** 2308 * Dumps the contents of an attribute in ASCII form to some output (e.g., 2309 * file or stdout). 2310 * 2311 * **Example:** 2312 * 2313 * The following prints the attribute dump to standard output. 2314 * 2315 * @code{.c} 2316 * tiledb_attribute_dump(ctx, attr, stdout); 2317 * @endcode 2318 * 2319 * @param ctx The TileDB context. 2320 * @param attr The attribute. 2321 * @param out The output. 2322 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2323 */ 2324 TILEDB_EXPORT int32_t tiledb_attribute_dump( 2325 tiledb_ctx_t* ctx, const tiledb_attribute_t* attr, FILE* out); 2326 2327 /** 2328 * Sets the default fill value for the input attribute. This value will 2329 * be used for the input attribute whenever querying (1) an empty cell in 2330 * a dense array, or (2) a non-empty cell (in either dense or sparse array) 2331 * when values on the input attribute are missing (e.g., if the user writes 2332 * a subset of the attributes in a write operation). 2333 * 2334 * Applicable to var-sized attributes. 2335 * 2336 * **Example:** 2337 * 2338 * @code{.c} 2339 * // Assumming a int32 attribute 2340 * int32_t value = 0; 2341 * uint64_t size = sizeof(value); 2342 * tiledb_attribute_set_fill_value(ctx, attr, &value, size); 2343 * 2344 * // Assumming a var char attribute 2345 * const char* value = "foo"; 2346 * uint64_t size = strlen(value); 2347 * tiledb_attribute_set_fill_value(ctx, attr, value, size); 2348 * @endcode 2349 * 2350 * @param ctx The TileDB context. 2351 * @param attr The target attribute. 2352 * @param value The fill value to set. 2353 * @param size The fill value size in bytes. 2354 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2355 * 2356 * @note A call to `tiledb_attribute_cell_val_num` sets the fill value 2357 * of the attribute to its default. Therefore, make sure you invoke 2358 * `tiledb_attribute_set_fill_value` after deciding on the number 2359 * of values this attribute will hold in each cell. 2360 * 2361 * @note For fixed-sized attributes, the input `size` should be equal 2362 * to the cell size. 2363 */ 2364 TILEDB_EXPORT int32_t tiledb_attribute_set_fill_value( 2365 tiledb_ctx_t* ctx, 2366 tiledb_attribute_t* attr, 2367 const void* value, 2368 uint64_t size); 2369 2370 /** 2371 * Gets the default fill value for the input attribute. This value will 2372 * be used for the input attribute whenever querying (1) an empty cell in 2373 * a dense array, or (2) a non-empty cell (in either dense or sparse array) 2374 * when values on the input attribute are missing (e.g., if the user writes 2375 * a subset of the attributes in a write operation). 2376 * 2377 * Applicable to both fixed-sized and var-sized attributes. 2378 * 2379 * **Example:** 2380 * 2381 * @code{.c} 2382 * // Assuming a int32 attribute 2383 * const int32_t* value; 2384 * uint64_t size; 2385 * tiledb_attribute_get_fill_value(ctx, attr, &value, &size); 2386 * 2387 * // Assuming a var char attribute 2388 * const char* value; 2389 * uint64_t size; 2390 * tiledb_attribute_get_fill_value(ctx, attr, &value, &size); 2391 * @endcode 2392 * 2393 * @param ctx The TileDB context. 2394 * @param attr The target attribute. 2395 * @param value A pointer to the fill value to get. 2396 * @param size The size of the fill value to get. 2397 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2398 */ 2399 TILEDB_EXPORT int32_t tiledb_attribute_get_fill_value( 2400 tiledb_ctx_t* ctx, 2401 tiledb_attribute_t* attr, 2402 const void** value, 2403 uint64_t* size); 2404 2405 /** 2406 * Sets the default fill value for the input, nullable attribute. This value 2407 * will be used for the input attribute whenever querying (1) an empty cell in 2408 * a dense array, or (2) a non-empty cell (in either dense or sparse array) 2409 * when values on the input attribute are missing (e.g., if the user writes 2410 * a subset of the attributes in a write operation). 2411 * 2412 * Applicable to var-sized attributes. 2413 * 2414 * **Example:** 2415 * 2416 * @code{.c} 2417 * // Assumming a int32 attribute 2418 * int32_t value = 0; 2419 * uint64_t size = sizeof(value); 2420 * uint8_t valid = 0; 2421 * tiledb_attribute_set_fill_value_nullable(ctx, attr, &value, size, valid); 2422 * 2423 * // Assumming a var char attribute 2424 * const char* value = "foo"; 2425 * uint64_t size = strlen(value); 2426 * uint8_t valid = 1; 2427 * tiledb_attribute_set_fill_value_nullable(ctx, attr, value, size, valid); 2428 * @endcode 2429 * 2430 * @param ctx The TileDB context. 2431 * @param attr The target attribute. 2432 * @param value The fill value to set. 2433 * @param size The fill value size in bytes. 2434 * @param validity The validity fill value, zero for a null value and 2435 * non-zero for a valid attribute. 2436 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2437 * 2438 * @note A call to `tiledb_attribute_cell_val_num` sets the fill value 2439 * of the attribute to its default. Therefore, make sure you invoke 2440 * `tiledb_attribute_set_fill_value_nullable` after deciding on the 2441 * number of values this attribute will hold in each cell. 2442 * 2443 * @note For fixed-sized attributes, the input `size` should be equal 2444 * to the cell size. 2445 */ 2446 TILEDB_EXPORT int32_t tiledb_attribute_set_fill_value_nullable( 2447 tiledb_ctx_t* ctx, 2448 tiledb_attribute_t* attr, 2449 const void* value, 2450 uint64_t size, 2451 uint8_t validity); 2452 2453 /** 2454 * Gets the default fill value for the input, nullable attribute. This value 2455 * will be used for the input attribute whenever querying (1) an empty cell in 2456 * a dense array, or (2) a non-empty cell (in either dense or sparse array) 2457 * when values on the input attribute are missing (e.g., if the user writes 2458 * a subset of the attributes in a write operation). 2459 * 2460 * Applicable to both fixed-sized and var-sized attributes. 2461 * 2462 * **Example:** 2463 * 2464 * @code{.c} 2465 * // Assuming a int32 attribute 2466 * const int32_t* value; 2467 * uint64_t size; 2468 * uint8_t valid; 2469 * tiledb_attribute_get_fill_value_nullable(ctx, attr, &value, &size, &valid); 2470 * 2471 * // Assuming a var char attribute 2472 * const char* value; 2473 * uint64_t size; 2474 * uint8_t valid; 2475 * tiledb_attribute_get_fill_value_nullable(ctx, attr, &value, &size, &valid); 2476 * @endcode 2477 * 2478 * @param ctx The TileDB context. 2479 * @param attr The target attribute. 2480 * @param value A pointer to the fill value to get. 2481 * @param size The size of the fill value to get. 2482 * @param valid The fill value validity to get. 2483 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2484 */ 2485 TILEDB_EXPORT int32_t tiledb_attribute_get_fill_value_nullable( 2486 tiledb_ctx_t* ctx, 2487 tiledb_attribute_t* attr, 2488 const void** value, 2489 uint64_t* size, 2490 uint8_t* valid); 2491 2492 /* ********************************* */ 2493 /* DOMAIN */ 2494 /* ********************************* */ 2495 2496 /** 2497 * Creates a TileDB domain. 2498 * 2499 * **Example:** 2500 * 2501 * @code{.c} 2502 * tiledb_domain_t* domain; 2503 * tiledb_domain_alloc(ctx, &domain); 2504 * @endcode 2505 * 2506 * @param ctx The TileDB context. 2507 * @param domain The TileDB domain to be created. 2508 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 2509 */ 2510 TILEDB_EXPORT int32_t 2511 tiledb_domain_alloc(tiledb_ctx_t* ctx, tiledb_domain_t** domain); 2512 2513 /** 2514 * Destroys a TileDB domain, freeing associated memory. 2515 * 2516 * **Example:** 2517 * 2518 * @code{.c} 2519 * tiledb_domain_t* domain; 2520 * tiledb_domain_alloc(ctx, &domain); 2521 * tiledb_domain_free(&domain); 2522 * @endcode 2523 * 2524 * @param domain The domain to be destroyed. 2525 */ 2526 TILEDB_EXPORT void tiledb_domain_free(tiledb_domain_t** domain); 2527 2528 /** 2529 * Retrieves the domain's type. 2530 * 2531 * **Example:** 2532 * 2533 * @code{.c} 2534 * tiledb_datatype_t type; 2535 * tiledb_domain_get_type(ctx, domain, &type); 2536 * @endcode 2537 * 2538 * @param ctx The TileDB context. 2539 * @param domain The domain. 2540 * @param type The type to be retrieved. 2541 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2542 */ 2543 TILEDB_EXPORT int32_t tiledb_domain_get_type( 2544 tiledb_ctx_t* ctx, const tiledb_domain_t* domain, tiledb_datatype_t* type); 2545 2546 /** 2547 * Retrieves the number of dimensions in a domain. 2548 * 2549 * **Example:** 2550 * 2551 * @code{.c} 2552 * uint32_t dim_num; 2553 * tiledb_domain_get_ndim(ctx, domain, &dim_num); 2554 * @endcode 2555 * 2556 * @param ctx The TileDB context 2557 * @param domain The domain 2558 * @param ndim The number of dimensions in a domain. 2559 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2560 */ 2561 TILEDB_EXPORT int32_t tiledb_domain_get_ndim( 2562 tiledb_ctx_t* ctx, const tiledb_domain_t* domain, uint32_t* ndim); 2563 2564 /** 2565 * Adds a dimension to a TileDB domain. 2566 * 2567 * **Example:** 2568 * 2569 * @code{.c} 2570 * tiledb_dimension_t* dim; 2571 * int64_t dim_domain[] = {1, 10}; 2572 * int64_t tile_extent = 5; 2573 * tiledb_dimension_alloc( 2574 * ctx, "dim_0", TILEDB_INT64, dim_domain, &tile_extent, &dim); 2575 * tiledb_domain_add_dimension(ctx, domain, dim); 2576 * @endcode 2577 * 2578 * @param ctx The TileDB context. 2579 * @param domain The domain to add the dimension to. 2580 * @param dim The dimension to be added. 2581 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2582 */ 2583 TILEDB_EXPORT int32_t tiledb_domain_add_dimension( 2584 tiledb_ctx_t* ctx, tiledb_domain_t* domain, tiledb_dimension_t* dim); 2585 2586 /** 2587 * Retrieves a dimension object from a domain by index. 2588 * 2589 * **Example:** 2590 * 2591 * The following retrieves the first dimension from a domain. 2592 * 2593 * @code{.c} 2594 * tiledb_dimension_t* dim; 2595 * tiledb_domain_get_dimension_from_index(ctx, domain, 0, &dim); 2596 * @endcode 2597 * 2598 * @param ctx The TileDB context 2599 * @param domain The domain to add the dimension to. 2600 * @param index The index of domain dimension 2601 * @param dim The retrieved dimension object. 2602 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2603 */ 2604 TILEDB_EXPORT int32_t tiledb_domain_get_dimension_from_index( 2605 tiledb_ctx_t* ctx, 2606 const tiledb_domain_t* domain, 2607 uint32_t index, 2608 tiledb_dimension_t** dim); 2609 2610 /** 2611 * Retrieves a dimension object from a domain by name (key). 2612 * 2613 * **Example:** 2614 * 2615 * @code{.c} 2616 * tiledb_dimension_t* dim; 2617 * tiledb_domain_get_dimension_from_name(ctx, domain, "dim_0", &dim); 2618 * @endcode 2619 * 2620 * @param ctx The TileDB context 2621 * @param domain The domain to add the dimension to. 2622 * @param name The name (key) of the requested dimension 2623 * @param dim The retrieved dimension object. 2624 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2625 */ 2626 TILEDB_EXPORT int32_t tiledb_domain_get_dimension_from_name( 2627 tiledb_ctx_t* ctx, 2628 const tiledb_domain_t* domain, 2629 const char* name, 2630 tiledb_dimension_t** dim); 2631 2632 /** 2633 * Checks whether the domain has a dimension of the given name. 2634 * 2635 * **Example:** 2636 * 2637 * @code{.c} 2638 * int32_t has_dim; 2639 * tiledb_domain_has_dimension(ctx, domain, "dim_0", &has_dim); 2640 * @endcode 2641 * 2642 * @param ctx The TileDB context. 2643 * @param domain The domain. 2644 * @param name The name of the dimension to check for. 2645 * @param has_dim Set to `1` if the domain has a dimension of the given name, 2646 * else `0`. 2647 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2648 */ 2649 TILEDB_EXPORT int32_t tiledb_domain_has_dimension( 2650 tiledb_ctx_t* ctx, 2651 const tiledb_domain_t* domain, 2652 const char* name, 2653 int32_t* has_dim); 2654 2655 /** 2656 * Dumps the info of a domain in ASCII form to some output (e.g., 2657 * file or `stdout`). 2658 * 2659 * **Example:** 2660 * 2661 * The following prints the domain dump to the standard output. 2662 * 2663 * @code{.c} 2664 * tiledb_domain_dump(ctx, domain, stdout); 2665 * @endcode 2666 * 2667 * @param ctx The TileDB context. 2668 * @param domain The domain. 2669 * @param out The output. 2670 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2671 */ 2672 TILEDB_EXPORT int32_t 2673 tiledb_domain_dump(tiledb_ctx_t* ctx, const tiledb_domain_t* domain, FILE* out); 2674 2675 /* ********************************* */ 2676 /* DIMENSION */ 2677 /* ********************************* */ 2678 2679 /** 2680 * Creates a dimension. 2681 * 2682 * **Example:** 2683 * 2684 * @code{.c} 2685 * tiledb_dimension_t* dim; 2686 * int64_t dim_domain[] = {1, 10}; 2687 * int64_t tile_extent = 5; 2688 * tiledb_dimension_alloc( 2689 * ctx, "dim_0", TILEDB_INT64, dim_domain, &tile_extent, &dim); 2690 * @endcode 2691 * 2692 * @param ctx The TileDB context. 2693 * @param name The dimension name. 2694 * @param type The dimension type. 2695 * @param dim_domain The dimension domain. 2696 * @param tile_extent The dimension tile extent. 2697 * @param dim The dimension to be created. 2698 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2699 */ 2700 TILEDB_EXPORT int32_t tiledb_dimension_alloc( 2701 tiledb_ctx_t* ctx, 2702 const char* name, 2703 tiledb_datatype_t type, 2704 const void* dim_domain, 2705 const void* tile_extent, 2706 tiledb_dimension_t** dim); 2707 2708 /** 2709 * Destroys a TileDB dimension, freeing associated memory. 2710 * 2711 * **Example:** 2712 * 2713 * @code{.c} 2714 * tiledb_dimension_free(&dim); 2715 * @endcode 2716 * 2717 * @param dim The dimension to be destroyed. 2718 */ 2719 TILEDB_EXPORT void tiledb_dimension_free(tiledb_dimension_t** dim); 2720 2721 /** 2722 * Sets the filter list for a dimension. 2723 * 2724 * **Example:** 2725 * 2726 * @code{.c} 2727 * tiledb_filter_list_t* filter_list; 2728 * tiledb_filter_list_alloc(ctx, &filter_list); 2729 * tiledb_filter_list_add_filter(ctx, filter_list, filter); 2730 * tiledb_dimension_set_filter_list(ctx, dim, filter_list); 2731 * @endcode 2732 * 2733 * @param ctx The TileDB context. 2734 * @param dim The target dimension. 2735 * @param filter_list The filter_list to be set. 2736 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2737 */ 2738 TILEDB_EXPORT int32_t tiledb_dimension_set_filter_list( 2739 tiledb_ctx_t* ctx, 2740 tiledb_dimension_t* dim, 2741 tiledb_filter_list_t* filter_list); 2742 2743 /** 2744 * Sets the number of values per cell for a dimension. If this is not 2745 * used, the default is `1`. 2746 * 2747 * **Examples:** 2748 * 2749 * For a fixed-sized dimension: 2750 * 2751 * @code{.c} 2752 * tiledb_dimension_set_cell_val_num(ctx, dim, 3); 2753 * @endcode 2754 * 2755 * For a variable-sized dimension: 2756 * 2757 * @code{.c} 2758 * tiledb_dimension_set_cell_val_num(ctx, dim, TILEDB_VAR_NUM); 2759 * @endcode 2760 * 2761 * @param ctx The TileDB context. 2762 * @param dim The target dimension. 2763 * @param cell_val_num The number of values per cell. 2764 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2765 */ 2766 TILEDB_EXPORT int32_t tiledb_dimension_set_cell_val_num( 2767 tiledb_ctx_t* ctx, tiledb_dimension_t* dim, uint32_t cell_val_num); 2768 2769 /** 2770 * Retrieves the filter list for a dimension. 2771 * 2772 * **Example:** 2773 * 2774 * @code{.c} 2775 * tiledb_filter_list_t* filter_list; 2776 * tiledb_dimension_get_filter_list(ctx, dim, &filter_list); 2777 * tiledb_filter_list_free(&filter_list); 2778 * @endcode 2779 * 2780 * @param ctx The TileDB context. 2781 * @param dim The target dimension. 2782 * @param filter_list The filter list to be retrieved. 2783 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2784 */ 2785 TILEDB_EXPORT int32_t tiledb_dimension_get_filter_list( 2786 tiledb_ctx_t* ctx, 2787 tiledb_dimension_t* dim, 2788 tiledb_filter_list_t** filter_list); 2789 2790 /** 2791 * Retrieves the number of values per cell for a dimension. For variable-sized 2792 * dimensions the result is TILEDB_VAR_NUM. 2793 * 2794 * **Example:** 2795 * 2796 * @code{.c} 2797 * uint32_t num; 2798 * tiledb_dimension_get_cell_val_num(ctx, dim, &num); 2799 * @endcode 2800 * 2801 * @param ctx The TileDB context. 2802 * @param dim The dimension. 2803 * @param cell_val_num The number of values per cell to be retrieved. 2804 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2805 */ 2806 TILEDB_EXPORT int32_t tiledb_dimension_get_cell_val_num( 2807 tiledb_ctx_t* ctx, const tiledb_dimension_t* dim, uint32_t* cell_val_num); 2808 2809 /** 2810 * Retrieves the dimension name. 2811 * 2812 * **Example:** 2813 * 2814 * @code{.c} 2815 * const char* dim_name; 2816 * tiledb_dimension_get_name(ctx, dim, &dim_name); 2817 * @endcode 2818 * 2819 * @param ctx The TileDB context. 2820 * @param dim The dimension. 2821 * @param name The name to be retrieved. 2822 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2823 */ 2824 TILEDB_EXPORT int32_t tiledb_dimension_get_name( 2825 tiledb_ctx_t* ctx, const tiledb_dimension_t* dim, const char** name); 2826 2827 /** 2828 * Retrieves the dimension type. 2829 * 2830 * **Example:** 2831 * 2832 * @code{.c} 2833 * tiledb_datatype_t dim_type; 2834 * tiledb_dimension_get_type(ctx, dim, &dim_type); 2835 * @endcode 2836 * 2837 * @param ctx The TileDB context. 2838 * @param dim The dimension. 2839 * @param type The type to be retrieved. 2840 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2841 */ 2842 TILEDB_EXPORT int32_t tiledb_dimension_get_type( 2843 tiledb_ctx_t* ctx, const tiledb_dimension_t* dim, tiledb_datatype_t* type); 2844 2845 /** 2846 * Retrieves the domain of the dimension. 2847 * 2848 * **Example:** 2849 * 2850 * @code{.c} 2851 * uint64_t* domain; 2852 * tiledb_dimension_get_domain(ctx, dim, &domain); 2853 * @endcode 2854 * 2855 * @param ctx The TileDB context. 2856 * @param dim The dimension. 2857 * @param domain The domain to be retrieved. Note that the defined type of 2858 * input `domain` must be the same as the dimension type, otherwise the 2859 * behavior is unpredictable (it will probably segfault). 2860 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2861 */ 2862 TILEDB_EXPORT int32_t tiledb_dimension_get_domain( 2863 tiledb_ctx_t* ctx, const tiledb_dimension_t* dim, const void** domain); 2864 2865 /** 2866 * Retrieves the tile extent of the dimension. 2867 * 2868 * **Example:** 2869 * 2870 * @code{.c} 2871 * uint64_t* tile_extent; 2872 * tiledb_dimension_get_tile_extent(ctx, dim, &tile_extent); 2873 * @endcode 2874 * 2875 * @param ctx The TileDB context. 2876 * @param dim The dimension. 2877 * @param tile_extent The tile extent (pointer) to be retrieved. 2878 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2879 */ 2880 TILEDB_EXPORT int32_t tiledb_dimension_get_tile_extent( 2881 tiledb_ctx_t* ctx, const tiledb_dimension_t* dim, const void** tile_extent); 2882 2883 /** 2884 * Dumps the contents of a dimension in ASCII form to some output (e.g., 2885 * file or stdout). 2886 * 2887 * **Example:** 2888 * 2889 * The following prints the dimension dump to standard output. 2890 * 2891 * @code{.c} 2892 * tiledb_dimension_dump(ctx, dim, stdout); 2893 * @endcode 2894 * 2895 * @param ctx The TileDB context. 2896 * @param dim The dimension. 2897 * @param out The output. 2898 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2899 */ 2900 TILEDB_EXPORT int32_t tiledb_dimension_dump( 2901 tiledb_ctx_t* ctx, const tiledb_dimension_t* dim, FILE* out); 2902 2903 /* ********************************* */ 2904 /* ARRAY SCHEMA */ 2905 /* ********************************* */ 2906 2907 /** 2908 * Creates a TileDB array schema object. 2909 * 2910 * **Example:** 2911 * 2912 * @code{.c} 2913 * tiledb_array_schema_t* array_schema; 2914 * tiledb_array_schema_alloc(ctx, TILEDB_DENSE, &array_schema); 2915 * @endcode 2916 * 2917 * @param ctx The TileDB context. 2918 * @param array_type The array type. 2919 * @param array_schema The TileDB array schema to be created. 2920 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 2921 */ 2922 TILEDB_EXPORT int32_t tiledb_array_schema_alloc( 2923 tiledb_ctx_t* ctx, 2924 tiledb_array_type_t array_type, 2925 tiledb_array_schema_t** array_schema); 2926 2927 /** 2928 * Destroys an array schema, freeing associated memory. 2929 * 2930 * **Example:** 2931 * 2932 * @code{.c} 2933 * tiledb_array_schema_free(&array_schema); 2934 * @endcode 2935 * 2936 * @param array_schema The array schema to be destroyed. 2937 */ 2938 TILEDB_EXPORT void tiledb_array_schema_free( 2939 tiledb_array_schema_t** array_schema); 2940 2941 /** 2942 * Adds an attribute to an array schema. 2943 * 2944 * **Example:** 2945 * 2946 * @code{.c} 2947 * tiledb_attribute_t* attr; 2948 * tiledb_attribute_alloc(ctx, "my_attr", TILEDB_INT32, &attr); 2949 * tiledb_array_schema_add_attribute(ctx, array_schema, attr); 2950 * @endcode 2951 * 2952 * @param ctx The TileDB context. 2953 * @param array_schema The array schema. 2954 * @param attr The attribute to be added. 2955 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2956 */ 2957 TILEDB_EXPORT int32_t tiledb_array_schema_add_attribute( 2958 tiledb_ctx_t* ctx, 2959 tiledb_array_schema_t* array_schema, 2960 tiledb_attribute_t* attr); 2961 2962 /** 2963 * Sets whether the array can allow coordinate duplicates or not. 2964 * Applicable only to sparse arrays (it errors out if set to `1` for dense 2965 * arrays). 2966 * 2967 * **Example:** 2968 * 2969 * @code{.c} 2970 * int allows_dups = 1; 2971 * tiledb_array_schema_set_allows_dups(ctx, array_schema, allows_dups); 2972 * @endcode 2973 * 2974 * @param ctx The TileDB context. 2975 * @param array_schema The array schema. 2976 * @param allows_dups Whether or not the array allows coordinate duplicates. 2977 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2978 */ 2979 TILEDB_EXPORT int32_t tiledb_array_schema_set_allows_dups( 2980 tiledb_ctx_t* ctx, tiledb_array_schema_t* array_schema, int allows_dups); 2981 2982 /** 2983 * Gets whether the array can allow coordinate duplicates or not. 2984 * It should always be `0` for dense arrays. 2985 * 2986 * **Example:** 2987 * 2988 * @code{.c} 2989 * int allows_dups; 2990 * tiledb_array_schema_get_allows_dups(ctx, array_schema, &allows_dups); 2991 * @endcode 2992 * 2993 * @param ctx The TileDB context. 2994 * @param array_schema The array schema. 2995 * @param allows_dups Whether or not the array allows coordinate duplicates. 2996 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 2997 */ 2998 TILEDB_EXPORT int32_t tiledb_array_schema_get_allows_dups( 2999 tiledb_ctx_t* ctx, tiledb_array_schema_t* array_schema, int* allows_dups); 3000 3001 /** 3002 * Sets a domain for the array schema. 3003 * 3004 * **Example:** 3005 * 3006 * @code{.c} 3007 * tiledb_domain_t* domain; 3008 * tiledb_domain_alloc(ctx, &domain); 3009 * // -- Add dimensions to the domain here -- // 3010 * tiledb_array_schema_set_domain(ctx, array_schema, domain); 3011 * @endcode 3012 * 3013 * @param ctx The TileDB context. 3014 * @param array_schema The array schema. 3015 * @param domain The domain to be set. 3016 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3017 */ 3018 TILEDB_EXPORT int32_t tiledb_array_schema_set_domain( 3019 tiledb_ctx_t* ctx, 3020 tiledb_array_schema_t* array_schema, 3021 tiledb_domain_t* domain); 3022 3023 /** 3024 * Sets the tile capacity. 3025 * 3026 * **Example:** 3027 * 3028 * @code{.c} 3029 * tiledb_array_schema_set_capacity(ctx, array_schema, 10000); 3030 * @endcode 3031 * 3032 * @param ctx The TileDB context. 3033 * @param array_schema The array schema. 3034 * @param capacity The capacity of a sparse data tile. Note that 3035 * sparse data tiles exist in sparse fragments, which can be created 3036 * in both sparse and dense arrays. For more details, 3037 * see [tutorials/tiling-sparse.html](tutorials/tiling-sparse.html). 3038 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3039 */ 3040 TILEDB_EXPORT int32_t tiledb_array_schema_set_capacity( 3041 tiledb_ctx_t* ctx, tiledb_array_schema_t* array_schema, uint64_t capacity); 3042 3043 /** 3044 * Sets the cell order. 3045 * 3046 * **Example:** 3047 * 3048 * @code{.c} 3049 * tiledb_array_schema_set_cell_order(ctx, array_schema, TILEDB_ROW_MAJOR); 3050 * @endcode 3051 * 3052 * @param ctx The TileDB context. 3053 * @param array_schema The array schema. 3054 * @param cell_order The cell order to be set. 3055 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3056 */ 3057 TILEDB_EXPORT int32_t tiledb_array_schema_set_cell_order( 3058 tiledb_ctx_t* ctx, 3059 tiledb_array_schema_t* array_schema, 3060 tiledb_layout_t cell_order); 3061 3062 /** 3063 * Sets the tile order. 3064 * 3065 * **Example:** 3066 * 3067 * @code{.c} 3068 * tiledb_array_schema_set_cell_order(ctx, array_schema, TILEDB_COL_MAJOR); 3069 * @endcode 3070 * 3071 * @param ctx The TileDB context. 3072 * @param array_schema The array schema. 3073 * @param tile_order The tile order to be set. 3074 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3075 */ 3076 TILEDB_EXPORT int32_t tiledb_array_schema_set_tile_order( 3077 tiledb_ctx_t* ctx, 3078 tiledb_array_schema_t* array_schema, 3079 tiledb_layout_t tile_order); 3080 3081 /** 3082 * Sets the filter list to use for the coordinates. 3083 * 3084 * **Example:** 3085 * 3086 * @code{.c} 3087 * tiledb_filter_list_t* filter_list; 3088 * tiledb_filter_list_alloc(ctx, &filter_list); 3089 * tiledb_filter_list_add_filter(ctx, filter_list, filter); 3090 * tiledb_array_schema_set_coords_filter_list(ctx, array_schema, filter_list); 3091 * @endcode 3092 * 3093 * @param ctx The TileDB context. 3094 * @param array_schema The array schema. 3095 * @param filter_list The filter list to be set. 3096 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3097 */ 3098 TILEDB_EXPORT int32_t tiledb_array_schema_set_coords_filter_list( 3099 tiledb_ctx_t* ctx, 3100 tiledb_array_schema_t* array_schema, 3101 tiledb_filter_list_t* filter_list); 3102 3103 /** 3104 * Sets the filter list to use for the offsets of variable-sized attribute 3105 * values. 3106 * 3107 * **Example:** 3108 * 3109 * @code{.c} 3110 * tiledb_filter_list_t* filter_list; 3111 * tiledb_filter_list_alloc(ctx, &filter_list); 3112 * tiledb_filter_list_add_filter(ctx, filter_list, filter); 3113 * tiledb_array_schema_set_offsets_filter_list(ctx, array_schema, filter_list); 3114 * @endcode 3115 * 3116 * @param ctx The TileDB context. 3117 * @param array_schema The array schema. 3118 * @param filter_list The filter list to be set. 3119 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3120 */ 3121 TILEDB_EXPORT int32_t tiledb_array_schema_set_offsets_filter_list( 3122 tiledb_ctx_t* ctx, 3123 tiledb_array_schema_t* array_schema, 3124 tiledb_filter_list_t* filter_list); 3125 3126 /** 3127 * Checks the correctness of the array schema. 3128 * 3129 * **Example:** 3130 * 3131 * @code{.c} 3132 * tiledb_array_schema_check(ctx, array_schema); 3133 * @endcode 3134 * 3135 * @param ctx The TileDB context. 3136 * @param array_schema The array schema. 3137 * @return `TILEDB_OK` if the array schema is correct and `TILEDB_ERR` upon any 3138 * error. 3139 */ 3140 TILEDB_EXPORT int32_t tiledb_array_schema_check( 3141 tiledb_ctx_t* ctx, tiledb_array_schema_t* array_schema); 3142 3143 /** 3144 * Retrieves the schema of an array from the disk, creating an array schema 3145 * struct. 3146 * 3147 * **Example:** 3148 * 3149 * @code{.c} 3150 * tiledb_array_schema_t* array_schema; 3151 * tiledb_array_schema_load(ctx, "s3://tiledb_bucket/my_array", &array_schema); 3152 * // Make sure to free the array schema in the end 3153 * @endcode 3154 * 3155 * @param ctx The TileDB context. 3156 * @param array_uri The array whose schema will be retrieved. 3157 * @param array_schema The array schema to be retrieved, or `NULL` upon error. 3158 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 3159 */ 3160 TILEDB_EXPORT int32_t tiledb_array_schema_load( 3161 tiledb_ctx_t* ctx, 3162 const char* array_uri, 3163 tiledb_array_schema_t** array_schema); 3164 3165 /** 3166 * Retrieves the schema of an encrypted array from the disk, creating an array 3167 * schema struct. 3168 * 3169 * **Example:** 3170 * 3171 * @code{.c} 3172 * // Load AES-256 key from disk, environment variable, etc. 3173 * uint8_t key[32] = ...; 3174 * tiledb_array_schema_t* array_schema; 3175 * tiledb_array_schema_load_with_key( 3176 * ctx, "s3://tiledb_bucket/my_array", TILEDB_AES_256_GCM, 3177 * key, sizeof(key), &array_schema); 3178 * // Make sure to free the array schema in the end 3179 * @endcode 3180 * 3181 * @param ctx The TileDB context. 3182 * @param array_uri The array whose schema will be retrieved. 3183 * @param encryption_type The encryption type to use. 3184 * @param encryption_key The encryption key to use. 3185 * @param key_length Length in bytes of the encryption key. 3186 * @param array_schema The array schema to be retrieved, or `NULL` upon error. 3187 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 3188 */ 3189 TILEDB_DEPRECATED_EXPORT int32_t tiledb_array_schema_load_with_key( 3190 tiledb_ctx_t* ctx, 3191 const char* array_uri, 3192 tiledb_encryption_type_t encryption_type, 3193 const void* encryption_key, 3194 uint32_t key_length, 3195 tiledb_array_schema_t** array_schema); 3196 3197 /** 3198 * Retrieves the array type. 3199 * 3200 * **Example:** 3201 * 3202 * @code{.c} 3203 * tiledb_array_schema_t* array_schema; 3204 * tiledb_array_schema_load(ctx, "s3://tiledb_bucket/my_array", array_schema); 3205 * tiledb_array_type_t* array_type; 3206 * tiledb_array_schema_get_array_type(ctx, array_schema, &array_type); 3207 * // Make sure to free the array schema in the end 3208 * @endcode 3209 * 3210 * @param ctx The TileDB context. 3211 * @param array_schema The array schema. 3212 * @param array_type The array type to be retrieved. 3213 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3214 */ 3215 TILEDB_EXPORT int32_t tiledb_array_schema_get_array_type( 3216 tiledb_ctx_t* ctx, 3217 const tiledb_array_schema_t* array_schema, 3218 tiledb_array_type_t* array_type); 3219 3220 /** 3221 * Retrieves the capacity. 3222 * 3223 * **Example:** 3224 * 3225 * @code{.c} 3226 * uint64_t capacity; 3227 * tiledb_array_schema_get_capacity(ctx, array_schema, &capacity); 3228 * @endcode 3229 * 3230 * @param ctx The TileDB context. 3231 * @param array_schema The array schema. 3232 * @param capacity The capacity to be retrieved. 3233 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3234 */ 3235 TILEDB_EXPORT int32_t tiledb_array_schema_get_capacity( 3236 tiledb_ctx_t* ctx, 3237 const tiledb_array_schema_t* array_schema, 3238 uint64_t* capacity); 3239 3240 /** 3241 * Retrieves the cell order. 3242 * 3243 * **Example:** 3244 * 3245 * @code{.c} 3246 * tiledb_layout_t cell_order; 3247 * tiledb_array_schema_get_cell_order(ctx, array_schema, &cell_order); 3248 * @endcode 3249 * 3250 * @param ctx The TileDB context. 3251 * @param array_schema The array schema. 3252 * @param cell_order The cell order to be retrieved. 3253 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3254 */ 3255 TILEDB_EXPORT int32_t tiledb_array_schema_get_cell_order( 3256 tiledb_ctx_t* ctx, 3257 const tiledb_array_schema_t* array_schema, 3258 tiledb_layout_t* cell_order); 3259 3260 /** 3261 * Retrieves the filter list used for the coordinates. 3262 * 3263 * **Example:** 3264 * 3265 * @code{.c} 3266 * tiledb_filter_list_t* filter_list; 3267 * tiledb_array_schema_get_coords_filter_list(ctx, array_schema, &filter_list); 3268 * tiledb_filter_list_free(ctx, &filter_list); 3269 * @endcode 3270 * 3271 * @param ctx The TileDB context. 3272 * @param array_schema The array schema. 3273 * @param filter_list The filter list to be retrieved. 3274 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3275 */ 3276 TILEDB_EXPORT int32_t tiledb_array_schema_get_coords_filter_list( 3277 tiledb_ctx_t* ctx, 3278 tiledb_array_schema_t* array_schema, 3279 tiledb_filter_list_t** filter_list); 3280 3281 /** 3282 * Retrieves the filter list used for the offsets. 3283 * 3284 * **Example:** 3285 * 3286 * @code{.c} 3287 * tiledb_filter_list_t* filter_list; 3288 * tiledb_array_schema_get_offsets_filter_list(ctx, array_schema, &filter_list); 3289 * tiledb_filter_list_free(ctx, &filter_list); 3290 * @endcode 3291 * 3292 * @param ctx The TileDB context. 3293 * @param array_schema The array schema. 3294 * @param filter_list The filter list to be retrieved. 3295 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3296 */ 3297 TILEDB_EXPORT int32_t tiledb_array_schema_get_offsets_filter_list( 3298 tiledb_ctx_t* ctx, 3299 tiledb_array_schema_t* array_schema, 3300 tiledb_filter_list_t** filter_list); 3301 3302 /** 3303 * Retrieves the array domain. 3304 * 3305 * **Example:** 3306 * 3307 * @code{.c} 3308 * tiledb_domain_t* domain; 3309 * tiledb_array_schema_get_domain(ctx, array_schema, &domain); 3310 * // Make sure to delete domain in the end 3311 * @endcode 3312 * 3313 * @param ctx The TileDB context. 3314 * @param array_schema The array schema. 3315 * @param domain The array domain to be retrieved. 3316 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 3317 */ 3318 TILEDB_EXPORT int32_t tiledb_array_schema_get_domain( 3319 tiledb_ctx_t* ctx, 3320 const tiledb_array_schema_t* array_schema, 3321 tiledb_domain_t** domain); 3322 3323 /** 3324 * Retrieves the tile order. 3325 * 3326 * **Example:** 3327 * 3328 * @code{.c} 3329 * tiledb_layout_t tile_order; 3330 * tiledb_array_schema_get_tile_order(ctx, array_schema, &tile_order); 3331 * @endcode 3332 * 3333 * @param ctx The TileDB context. 3334 * @param array_schema The array schema. 3335 * @param tile_order The tile order to be retrieved. 3336 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3337 */ 3338 TILEDB_EXPORT int32_t tiledb_array_schema_get_tile_order( 3339 tiledb_ctx_t* ctx, 3340 const tiledb_array_schema_t* array_schema, 3341 tiledb_layout_t* tile_order); 3342 3343 /** 3344 * Retrieves the number of array attributes. 3345 * 3346 * **Example:** 3347 * 3348 * @code{.c} 3349 * uint32_t attr_num; 3350 * tiledb_array_schema_get_attribute_num(ctx, array_schema, &attr_num); 3351 * @endcode 3352 * 3353 * @param ctx The TileDB context. 3354 * @param array_schema The array schema. 3355 * @param attribute_num The number of attributes to be retrieved. 3356 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3357 */ 3358 TILEDB_EXPORT int32_t tiledb_array_schema_get_attribute_num( 3359 tiledb_ctx_t* ctx, 3360 const tiledb_array_schema_t* array_schema, 3361 uint32_t* attribute_num); 3362 3363 /** 3364 * Retrieves an attribute given its index. 3365 * 3366 * Attributes are ordered the same way they were defined 3367 * when constructing the array schema. 3368 * 3369 * **Example:** 3370 * 3371 * The following retrieves the first attribute in the schema. 3372 * 3373 * @code{.c} 3374 * tiledb_attribute_t* attr; 3375 * tiledb_array_schema_get_attribute_from_index(ctx, array_schema, 0, &attr); 3376 * // Make sure to delete the retrieved attribute in the end. 3377 * @endcode 3378 * 3379 * @param ctx The TileDB context. 3380 * @param array_schema The array schema. 3381 * @param index The index of the attribute to retrieve. 3382 * @param attr The attribute object to retrieve. 3383 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3384 */ 3385 TILEDB_EXPORT int32_t tiledb_array_schema_get_attribute_from_index( 3386 tiledb_ctx_t* ctx, 3387 const tiledb_array_schema_t* array_schema, 3388 uint32_t index, 3389 tiledb_attribute_t** attr); 3390 3391 /** 3392 * Retrieves an attribute given its name (key). 3393 * 3394 * **Example:** 3395 * 3396 * The following retrieves the first attribute in the schema. 3397 * 3398 * @code{.c} 3399 * tiledb_attribute_t* attr; 3400 * tiledb_array_schema_get_attribute_from_name( 3401 * ctx, array_schema, "attr_0", &attr); 3402 * // Make sure to delete the retrieved attribute in the end. 3403 * @endcode 3404 * 3405 * @param ctx The TileDB context. 3406 * @param array_schema The array schema. 3407 * @param name The name (key) of the attribute to retrieve. 3408 * @param attr THe attribute object to retrieve. 3409 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3410 */ 3411 TILEDB_EXPORT int32_t tiledb_array_schema_get_attribute_from_name( 3412 tiledb_ctx_t* ctx, 3413 const tiledb_array_schema_t* array_schema, 3414 const char* name, 3415 tiledb_attribute_t** attr); 3416 3417 /** 3418 * Checks whether the array schema has an attribute of the given name. 3419 * 3420 * **Example:** 3421 * 3422 * @code{.c} 3423 * int32_t has_attr; 3424 * tiledb_array_schema_has_attribute(ctx, array_schema, "attr_0", &has_attr); 3425 * @endcode 3426 * 3427 * @param ctx The TileDB context. 3428 * @param array_schema The array schema. 3429 * @param name The name of the attribute to check for. 3430 * @param has_attr Set to `1` if the array schema has an attribute of the 3431 * given name, else `0`. 3432 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3433 */ 3434 TILEDB_EXPORT int32_t tiledb_array_schema_has_attribute( 3435 tiledb_ctx_t* ctx, 3436 const tiledb_array_schema_t* array_schema, 3437 const char* name, 3438 int32_t* has_attr); 3439 3440 /** 3441 * Dumps the array schema in ASCII format in the selected output. 3442 * 3443 * **Example:** 3444 * 3445 * The following prints the array schema dump in standard output. 3446 * 3447 * @code{.c} 3448 * tiledb_array_schema_dump(ctx, array_schema, stdout); 3449 * @endcode 3450 * 3451 * @param ctx The TileDB context. 3452 * @param array_schema The array schema. 3453 * @param out The output. 3454 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3455 */ 3456 TILEDB_EXPORT int32_t tiledb_array_schema_dump( 3457 tiledb_ctx_t* ctx, const tiledb_array_schema_t* array_schema, FILE* out); 3458 3459 /* ********************************* */ 3460 /* QUERY */ 3461 /* ********************************* */ 3462 3463 /** 3464 * Creates a TileDB query object. Note that the query object is associated 3465 * with a specific array object. The query type (read or write) is inferred 3466 * from the array object, which was opened with a specific query type. 3467 * 3468 * **Example:** 3469 * 3470 * @code{.c} 3471 * tiledb_array_t* array; 3472 * tiledb_array_alloc(ctx, "file:///my_array", &array); 3473 * tiledb_array_open(ctx, array, TILEDB_WRITE); 3474 * tiledb_query_t* query; 3475 * tiledb_query_alloc(ctx, array, TILEDB_WRITE, &query); 3476 * @endcode 3477 * 3478 * @param ctx The TileDB context. 3479 * @param query The query object to be created. 3480 * @param array An opened array object. 3481 * @param query_type The query type. This must comply with the query type 3482 * `array` was opened. 3483 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 3484 */ 3485 TILEDB_EXPORT int32_t tiledb_query_alloc( 3486 tiledb_ctx_t* ctx, 3487 tiledb_array_t* array, 3488 tiledb_query_type_t query_type, 3489 tiledb_query_t** query); 3490 3491 /** 3492 * Retrieves the stats from a Query. 3493 * 3494 * **Example:** 3495 * 3496 * @code{.c} 3497 * char* stats_json; 3498 * tiledb_query_get_stats(ctx, query, &stats_json); 3499 * // Make sure to free the retrieved `stats_json` 3500 * @endcode 3501 * 3502 * @param ctx The TileDB context. 3503 * @param query The query object. 3504 * @param stats_json The output json. The caller takes ownership 3505 * of the c-string. 3506 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 3507 */ 3508 TILEDB_EXPORT int32_t tiledb_query_get_stats( 3509 tiledb_ctx_t* ctx, tiledb_query_t* query, char** stats_json); 3510 3511 /** 3512 * Set the query config 3513 * 3514 * Setting the configuration with this function overrides the following 3515 * Query-level parameters only: 3516 * 3517 * - `sm.memory_budget` 3518 * - `sm.memory_budget_var` 3519 * - `sm.var_offsets.mode` 3520 * - `sm.var_offsets.extra_element` 3521 * - `sm.var_offsets.bitsize` 3522 * - `sm.check_coord_dups` 3523 * - `sm.check_coord_oob` 3524 * - `sm.check_global_order` 3525 * - `sm.dedup_coords` 3526 */ 3527 TILEDB_EXPORT int32_t tiledb_query_set_config( 3528 tiledb_ctx_t* ctx, tiledb_query_t* query, tiledb_config_t* config); 3529 3530 /** 3531 * Retrieves the config from a Query. 3532 * 3533 * **Example:** 3534 * 3535 * @code{.c} 3536 * tiledb_config_t* config; 3537 * tiledb_query_get_config(ctx, vfs, &config); 3538 * // Make sure to free the retrieved config 3539 * @endcode 3540 * 3541 * @param ctx The TileDB context. 3542 * @param query The query object. 3543 * @param config The config to be retrieved. 3544 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 3545 */ 3546 TILEDB_EXPORT int32_t tiledb_query_get_config( 3547 tiledb_ctx_t* ctx, tiledb_query_t* query, tiledb_config_t** config); 3548 /** 3549 * Indicates that the query will write or read a subarray, and provides 3550 * the appropriate information. 3551 * 3552 * **Example:** 3553 * 3554 * The following sets a 2D subarray [0,10], [20, 30] to the query. 3555 * 3556 * @code{.c} 3557 * uint64_t subarray[] = { 0, 10, 20, 30}; 3558 * tiledb_query_set_subarray(ctx, query, subarray); 3559 * @endcode 3560 * 3561 * @param ctx The TileDB context. 3562 * @param query The TileDB query. 3563 * @param subarray The subarray in which the array read/write will be 3564 * constrained on. It should be a sequence of [low, high] pairs (one 3565 * pair per dimension). For the case of writes, this is meaningful only 3566 * for dense arrays, and specifically dense writes. Note that `subarray` 3567 * must have the same type as the domain. 3568 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3569 * 3570 * @note If you set the subarray of a completed, incomplete or in-progress 3571 * query, this function will clear the internal state and render it 3572 * as uninitialized. However, the potentially set layout and attribute 3573 * buffers will be retained. This is useful when the user wishes to 3574 * fix the attributes and layout, but explore different subarrays with 3575 * the same `tiledb_query_t` object (i.e., without having to create 3576 * a new object). 3577 * 3578 * @note Setting the subarray in sparse writes is meaningless and, thus, 3579 * this function will error in the following two cases, provided that 3580 * this is a write query: 3581 * (i) the array is sparse, and (ii) the array is dense and the 3582 * layout has been set to `TILEDB_UNORDERED`. In the second case, 3583 * if the user sets the layout to `TILEDB_UNORDERED` **after** 3584 * the subarray has been set, the subarray will simply be ignored. 3585 */ 3586 TILEDB_EXPORT int32_t tiledb_query_set_subarray( 3587 tiledb_ctx_t* ctx, tiledb_query_t* query, const void* subarray); 3588 3589 /** 3590 * Sets the buffer for a fixed-sized attribute/dimension to a query, which will 3591 * either hold the values to be written (if it is a write query), or will hold 3592 * the results from a read query. 3593 * 3594 * **Example:** 3595 * 3596 * @code{.c} 3597 * int32_t a1[100]; 3598 * uint64_t a1_size = sizeof(a1); 3599 * tiledb_query_set_buffer(ctx, query, "a1", a1, &a1_size); 3600 * @endcode 3601 * 3602 * @param ctx The TileDB context. 3603 * @param query The TileDB query. 3604 * @param name The attribute/dimension to set the buffer for. Note that 3605 * zipped coordinates have special name `TILEDB_COORDS`. 3606 * @param buffer The buffer that either have the input data to be written, 3607 * or will hold the data to be read. 3608 * @param buffer_size In the case of writes, this is the size of `buffer` 3609 * in bytes. In the case of reads, this initially contains the allocated 3610 * size of `buffer`, but after the termination of the query 3611 * it will contain the size of the useful (read) data in `buffer`. 3612 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3613 */ 3614 TILEDB_DEPRECATED_EXPORT int32_t tiledb_query_set_buffer( 3615 tiledb_ctx_t* ctx, 3616 tiledb_query_t* query, 3617 const char* name, 3618 void* buffer, 3619 uint64_t* buffer_size); 3620 3621 /** 3622 * Sets the buffer for a var-sized attribute/dimension to a query, which will 3623 * either hold the values to be written (if it is a write query), or will hold 3624 * the results from a read query. 3625 * 3626 * **Example:** 3627 * 3628 * @code{.c} 3629 * uint64_t a2_off[10]; 3630 * uint64_t a2_off_size = sizeof(a2_off); 3631 * char a2_val[100]; 3632 * uint64_t a2_val_size = sizeof(a2_val); 3633 * tiledb_query_set_buffer_var( 3634 * ctx, query, "a2", a2_off, &a2_off_size, a2_val, &a2_val_size); 3635 * @endcode 3636 * 3637 * @param ctx The TileDB context. 3638 * @param query The TileDB query. 3639 * @param name The attribute/dimension to set the buffer for. 3640 * @param buffer_off The buffer that either have the input data to be written, 3641 * or will hold the data to be read. This buffer holds the starting offsets 3642 * of each cell value in `buffer_val`. 3643 * @param buffer_off_size In the case of writes, it is the size of `buffer_off` 3644 * in bytes. In the case of reads, this initially contains the allocated 3645 * size of `buffer_off`, but after the *end of the query* 3646 * (`tiledb_query_submit`) it will contain the size of the useful (read) 3647 * data in `buffer_off`. 3648 * @param buffer_val The buffer that either have the input data to be written, 3649 * or will hold the data to be read. This buffer holds the actual var-sized 3650 * cell values. 3651 * @param buffer_val_size In the case of writes, it is the size of `buffer_val` 3652 * in bytes. In the case of reads, this initially contains the allocated 3653 * size of `buffer_val`, but after the termination of the function 3654 * it will contain the size of the useful (read) data in `buffer_val`. 3655 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3656 */ 3657 TILEDB_DEPRECATED_EXPORT int32_t tiledb_query_set_buffer_var( 3658 tiledb_ctx_t* ctx, 3659 tiledb_query_t* query, 3660 const char* name, 3661 uint64_t* buffer_off, 3662 uint64_t* buffer_off_size, 3663 void* buffer_val, 3664 uint64_t* buffer_val_size); 3665 3666 /** 3667 * Sets the buffer for a fixed-sized, nullable attribute to a query, which will 3668 * either hold the values to be written (if it is a write query), or will hold 3669 * the results from a read query. The validity buffer is a byte map, where each 3670 * non-zero byte represents a valid (i.e. "non-null") attribute value. 3671 * 3672 * **Example:** 3673 * 3674 * @code{.c} 3675 * int32_t a1[100]; 3676 * uint64_t a1_size = sizeof(a1); 3677 * uint8_t a1_validity[100]; 3678 * uint64_t a1_validity_size = sizeof(a1_validity); 3679 * tiledb_query_set_buffer_nullable( 3680 * ctx, query, "a1", a1, &a1_size, a1_validity, &a1_validity_size); 3681 * @endcode 3682 * 3683 * @param ctx The TileDB context. 3684 * @param query The TileDB query. 3685 * @param name The attribute/dimension to set the buffer for. Note that 3686 * zipped coordinates have special name `TILEDB_COORDS`. 3687 * @param buffer The buffer that either have the input data to be written, 3688 * or will hold the data to be read. 3689 * @param buffer_size In the case of writes, this is the size of `buffer` 3690 * in bytes. In the case of reads, this initially contains the allocated 3691 * size of `buffer`, but after the termination of the query 3692 * it will contain the size of the useful (read) data in `buffer`. 3693 * @param buffer_validity_bytemap The validity byte map that has exactly 3694 * one value for each value in `buffer`. 3695 * @param buffer_validity_bytemap_size In the case of writes, this is the 3696 * size of `buffer_validity_bytemap` in bytes. In the case of reads, 3697 * this initially contains the allocated size of `buffer_validity_bytemap`, 3698 * but after the termination of the query it will contain the size of the 3699 * useful (read) data in `buffer_validity_bytemap`. 3700 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3701 */ 3702 TILEDB_DEPRECATED_EXPORT int32_t tiledb_query_set_buffer_nullable( 3703 tiledb_ctx_t* ctx, 3704 tiledb_query_t* query, 3705 const char* name, 3706 void* buffer, 3707 uint64_t* buffer_size, 3708 uint8_t* buffer_validity_bytemap, 3709 uint64_t* buffer_validity_bytemap_size); 3710 3711 /** 3712 * Sets the buffer for a var-sized, nullable attribute to a query, which will 3713 * either hold the values to be written (if it is a write query), or will hold 3714 * the results from a read query. 3715 * 3716 * **Example:** 3717 * 3718 * @code{.c} 3719 * uint64_t a2_off[10]; 3720 * uint64_t a2_off_size = sizeof(a2_off); 3721 * char a2_val[100]; 3722 * uint64_t a2_val_size = sizeof(a2_val); 3723 * uint8_t a2_validity[100]; 3724 * uint64_t a2_validity_size = sizeof(a2_validity); 3725 * tiledb_query_set_buffer_var( 3726 * ctx, query, "a2", a2_off, &a2_off_size, a2_val, &a2_val_size, 3727 * a2_validity, &a2_validity_size); 3728 * @endcode 3729 * 3730 * @param ctx The TileDB context. 3731 * @param query The TileDB query. 3732 * @param name The attribute/dimension to set the buffer for. 3733 * @param buffer_off The buffer that either have the input data to be written, 3734 * or will hold the data to be read. This buffer holds the starting offsets 3735 * of each cell value in `buffer_val`. 3736 * @param buffer_off_size In the case of writes, it is the size of `buffer_off` 3737 * in bytes. In the case of reads, this initially contains the allocated 3738 * size of `buffer_off`, but after the *end of the query* 3739 * (`tiledb_query_submit`) it will contain the size of the useful (read) 3740 * data in `buffer_off`. 3741 * @param buffer_val The buffer that either have the input data to be written, 3742 * or will hold the data to be read. This buffer holds the actual var-sized 3743 * cell values. 3744 * @param buffer_val_size In the case of writes, it is the size of `buffer_val` 3745 * in bytes. In the case of reads, this initially contains the allocated 3746 * size of `buffer_val`, but after the termination of the function 3747 * it will contain the size of the useful (read) data in `buffer_val`. 3748 * @param buffer_validity_bytemap The validity byte map that has exactly 3749 * one value for each value in `buffer`. 3750 * @param buffer_validity_bytemap_size In the case of writes, this is the 3751 * size of `buffer_validity_bytemap` in bytes. In the case of reads, 3752 * this initially contains the allocated size of `buffer_validity_bytemap`, 3753 * but after the termination of the query it will contain the size of the 3754 * useful (read) data in `buffer_validity_bytemap`. 3755 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3756 */ 3757 TILEDB_DEPRECATED_EXPORT int32_t tiledb_query_set_buffer_var_nullable( 3758 tiledb_ctx_t* ctx, 3759 tiledb_query_t* query, 3760 const char* name, 3761 uint64_t* buffer_off, 3762 uint64_t* buffer_off_size, 3763 void* buffer_val, 3764 uint64_t* buffer_val_size, 3765 uint8_t* buffer_validity_bytemap, 3766 uint64_t* buffer_validity_bytemap_size); 3767 3768 /** 3769 * Sets the buffer for an attribute/dimension to a query, which will 3770 * either hold the values to be written (if it is a write query), or will hold 3771 * the results from a read query. 3772 * 3773 * **Example:** 3774 * 3775 * @code{.c} 3776 * int32_t a1[100]; 3777 * uint64_t a1_size = sizeof(a1); 3778 * tiledb_query_set_data_buffer(ctx, query, "a1", a1, &a1_size); 3779 * @endcode 3780 * 3781 * @param ctx The TileDB context. 3782 * @param query The TileDB query. 3783 * @param name The attribute/dimension to set the buffer for. Note that 3784 * zipped coordinates have special name `TILEDB_COORDS`. 3785 * @param buffer The buffer that either have the input data to be written, 3786 * or will hold the data to be read. 3787 * @param buffer_size In the case of writes, this is the size of `buffer` 3788 * in bytes. In the case of reads, this initially contains the allocated 3789 * size of `buffer`, but after the termination of the query 3790 * it will contain the size of the useful (read) data in `buffer`. 3791 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3792 */ 3793 TILEDB_EXPORT int32_t tiledb_query_set_data_buffer( 3794 tiledb_ctx_t* ctx, 3795 tiledb_query_t* query, 3796 const char* name, 3797 void* buffer, 3798 uint64_t* buffer_size); 3799 3800 /** 3801 * Sets the starting offsets of each cell value in the data buffer. 3802 * 3803 * **Example:** 3804 * 3805 * @code{.c} 3806 * uint64_t a1[100]; 3807 * uint64_t a1_size = sizeof(a1); 3808 * tiledb_query_set_offsets_buffer(ctx, query, "a1", a1, &a1_size); 3809 * @endcode 3810 * 3811 * @param ctx The TileDB context. 3812 * @param query The TileDB query. 3813 * @param name The attribute/dimension to set the buffer for. Note that 3814 * zipped coordinates have special name `TILEDB_COORDS`. 3815 * @param buffer This buffer holds the starting offsets 3816 * of each cell value in `buffer_val`. 3817 * @param buffer_size In the case of writes, it is the size of `buffer_off` 3818 * in bytes. In the case of reads, this initially contains the allocated 3819 * size of `buffer_off`, but after the *end of the query* 3820 * (`tiledb_query_submit`) it will contain the size of the useful (read) 3821 * data in `buffer_off`. 3822 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3823 */ 3824 TILEDB_EXPORT int32_t tiledb_query_set_offsets_buffer( 3825 tiledb_ctx_t* ctx, 3826 tiledb_query_t* query, 3827 const char* name, 3828 uint64_t* buffer, 3829 uint64_t* buffer_size); 3830 3831 /** 3832 * Sets the validity byte map that has exactly one value for each value in the 3833 * data buffer. 3834 * 3835 * **Example:** 3836 * 3837 * @code{.c} 3838 * uint8_t a1[100]; 3839 * uint64_t a1_size = sizeof(a1); 3840 * tiledb_query_set_validity_buffer(ctx, query, "a1", a1, &a1_size); 3841 * @endcode 3842 * 3843 * @param ctx The TileDB context. 3844 * @param query The TileDB query. 3845 * @param name The attribute/dimension to set the buffer for. Note that 3846 * zipped coordinates have special name `TILEDB_COORDS`. 3847 * @param buffer The validity byte map that has exactly 3848 * one value for each value in `buffer`. 3849 * @param buffer_size In the case of writes, this is the 3850 * size of `buffer_validity_bytemap` in bytes. In the case of reads, 3851 * this initially contains the allocated size of `buffer_validity_bytemap`, 3852 * but after the termination of the query it will contain the size of the 3853 * useful (read) data in `buffer_validity_bytemap`. 3854 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3855 */ 3856 TILEDB_EXPORT int32_t tiledb_query_set_validity_buffer( 3857 tiledb_ctx_t* ctx, 3858 tiledb_query_t* query, 3859 const char* name, 3860 uint8_t* buffer, 3861 uint64_t* buffer_size); 3862 3863 /** 3864 * Gets the buffer of a fixed-sized attribute/dimension from a query. If the 3865 * buffer has not been set, then `buffer` is set to `nullptr`. 3866 * 3867 * **Example:** 3868 * 3869 * @code{.c} 3870 * int* a1; 3871 * uint64_t* a1_size; 3872 * tiledb_query_get_buffer(ctx, query, "a1", &a1, &a1_size); 3873 * @endcode 3874 * 3875 * @param ctx The TileDB context. 3876 * @param query The TileDB query. 3877 * @param name The attribute/dimension to get the buffer for. Note that the 3878 * zipped coordinates have special name `TILEDB_COORDS`. 3879 * @param buffer The buffer to retrieve. 3880 * @param buffer_size A pointer to the size of the buffer. Note that this is 3881 * a double pointer and returns the original variable address from 3882 * `set_buffer`. 3883 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3884 */ 3885 TILEDB_DEPRECATED_EXPORT int32_t tiledb_query_get_buffer( 3886 tiledb_ctx_t* ctx, 3887 tiledb_query_t* query, 3888 const char* name, 3889 void** buffer, 3890 uint64_t** buffer_size); 3891 3892 /** 3893 * Gets the values and offsets buffers for a var-sized attribute/dimension 3894 * to a query. If the buffers have not been set, then `buffer_off` and 3895 * `buffer_val` are set to `nullptr`. 3896 * 3897 * **Example:** 3898 * 3899 * @code{.c} 3900 * uint64_t* a2_off; 3901 * uint64_t* a2_off_size; 3902 * char* a2_val; 3903 * uint64_t* a2_val_size; 3904 * tiledb_query_get_buffer_var( 3905 * ctx, query, "a2", &a2_off, &a2_off_size, &a2_val, &a2_val_size); 3906 * @endcode 3907 * 3908 * @param ctx The TileDB context. 3909 * @param query The TileDB query. 3910 * @param name The attribute/dimension to set the buffer for. 3911 * @param buffer_off The offsets buffer to be retrieved. 3912 * @param buffer_off_size A pointer to the size of the offsets buffer. Note that 3913 * this is a `uint_64**` pointer and returns the original variable address 3914 * from `set_buffer`. 3915 * @param buffer_val The values buffer to be retrieved. 3916 * @param buffer_val_size A pointer to the size of the values buffer. Note that 3917 * this is a `uint_64**` pointer and returns the original variable address 3918 * from `set_buffer`. 3919 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3920 */ 3921 TILEDB_DEPRECATED_EXPORT int32_t tiledb_query_get_buffer_var( 3922 tiledb_ctx_t* ctx, 3923 tiledb_query_t* query, 3924 const char* name, 3925 uint64_t** buffer_off, 3926 uint64_t** buffer_off_size, 3927 void** buffer_val, 3928 uint64_t** buffer_val_size); 3929 3930 /** 3931 * Gets the buffer of a fixed-sized, nullable attribute from a query. If the 3932 * buffer has not been set, then `buffer` and `buffer_validity_bytemap` are 3933 * set to `nullptr`. 3934 * 3935 * **Example:** 3936 * 3937 * @code{.c} 3938 * int* a1; 3939 * uint64_t* a1_size; 3940 * uint8_t* a1_validity; 3941 * uint64_t* a1_validity_size; 3942 * tiledb_query_get_buffer_nullable( 3943 * ctx, query, "a1", &a1, &a1_size, &a1_validity, &a1_validity_size); 3944 * @endcode 3945 * 3946 * @param ctx The TileDB context. 3947 * @param query The TileDB query. 3948 * @param name The attribute/dimension to get the buffer for. Note that the 3949 * zipped coordinates have special name `TILEDB_COORDS`. 3950 * @param buffer The buffer to retrieve. 3951 * @param buffer_size A pointer to the size of the buffer. Note that this is 3952 * a double pointer and returns the original variable address from 3953 * `set_buffer`. 3954 * @param buffer_validity_bytemap The validity bytemap buffer to retrieve. 3955 * @param buffer_validity_bytemap_size A pointer to the size of the validity 3956 * bytemap buffer. Note that this is a double pointer and returns the 3957 * origina variable address from `set_buffer_nullable`. 3958 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 3959 */ 3960 TILEDB_DEPRECATED_EXPORT int32_t tiledb_query_get_buffer_nullable( 3961 tiledb_ctx_t* ctx, 3962 tiledb_query_t* query, 3963 const char* name, 3964 void** buffer, 3965 uint64_t** buffer_size, 3966 uint8_t** buffer_validity_bytemap, 3967 uint64_t** buffer_validity_bytemap_size); 3968 3969 /** 3970 * Gets the values and offsets buffers for a var-sized, nullable attribute 3971 * to a query. If the buffers have not been set, then `buffer_off`, 3972 * `buffer_val`, and `buffer_validity_bytemap` are set to `nullptr`. 3973 * 3974 * **Example:** 3975 * 3976 * @code{.c} 3977 * uint64_t* a2_off; 3978 * uint64_t* a2_off_size; 3979 * char* a2_val; 3980 * uint64_t* a2_val_size; 3981 * uint8_t* a2_validity; 3982 * uint64_t* a2_validity_size; 3983 * tiledb_query_get_buffer_var_nullable( 3984 * ctx, query, "a2", &a2_off, &a2_off_size, &a2_val, &a2_val_size, 3985 * &a2_validity, &a2_validity_size); 3986 * @endcode 3987 * 3988 * @param ctx The TileDB context. 3989 * @param query The TileDB query. 3990 * @param name The attribute/dimension to set the buffer for. 3991 * @param buffer_off The offsets buffer to be retrieved. 3992 * @param buffer_off_size A pointer to the size of the offsets buffer. Note that 3993 * this is a `uint_64**` pointer and returns the original variable address 3994 * from `set_buffer`. 3995 * @param buffer_val The values buffer to be retrieved. 3996 * @param buffer_val_size A pointer to the size of the values buffer. Note that 3997 * this is a `uint_64**` pointer and returns the original variable address 3998 * from `set_buffer`. 3999 * @param buffer_validity_bytemap The validity bytemap buffer to retrieve. 4000 * @param buffer_validity_bytemap_size A pointer to the size of the validity 4001 * bytemap buffer. Note that this is a double pointer and returns the 4002 * origina variable address from `set_buffer_var_nullable`. 4003 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4004 */ 4005 TILEDB_DEPRECATED_EXPORT int32_t tiledb_query_get_buffer_var_nullable( 4006 tiledb_ctx_t* ctx, 4007 tiledb_query_t* query, 4008 const char* name, 4009 uint64_t** buffer_off, 4010 uint64_t** buffer_off_size, 4011 void** buffer_val, 4012 uint64_t** buffer_val_size, 4013 uint8_t** buffer_validity_bytemap, 4014 uint64_t** buffer_validity_bytemap_size); 4015 4016 /** 4017 * Gets the buffer of a fixed-sized attribute/dimension from a query. If the 4018 * buffer has not been set, then `buffer` is set to `nullptr`. 4019 * 4020 * **Example:** 4021 * 4022 * @code{.c} 4023 * int* a1; 4024 * uint64_t* a1_size; 4025 * tiledb_query_get_data_buffer(ctx, query, "a1", &a1, &a1_size); 4026 * @endcode 4027 * 4028 * @param ctx The TileDB context. 4029 * @param query The TileDB query. 4030 * @param name The attribute/dimension to get the buffer for. Note that the 4031 * zipped coordinates have special name `TILEDB_COORDS`. 4032 * @param buffer The buffer to retrieve. 4033 * @param buffer_size A pointer to the size of the buffer. Note that this is 4034 * a double pointer and returns the original variable address from 4035 * `set_buffer`. 4036 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4037 */ 4038 TILEDB_EXPORT int32_t tiledb_query_get_data_buffer( 4039 tiledb_ctx_t* ctx, 4040 tiledb_query_t* query, 4041 const char* name, 4042 void** buffer, 4043 uint64_t** buffer_size); 4044 4045 /** 4046 * Gets the starting offsets of each cell value in the data buffer. 4047 * 4048 * **Example:** 4049 * 4050 * @code{.c} 4051 * int* a1; 4052 * uint64_t* a1_size; 4053 * tiledb_query_get_offsets_buffer(ctx, query, "a1", &a1, &a1_size); 4054 * @endcode 4055 * 4056 * @param ctx The TileDB context. 4057 * @param query The TileDB query. 4058 * @param name The attribute/dimension to get the buffer for. Note that the 4059 * zipped coordinates have special name `TILEDB_COORDS`. 4060 * @param buffer The buffer to retrieve. 4061 * @param buffer_size A pointer to the size of the buffer. Note that this is 4062 * a double pointer and returns the original variable address from 4063 * `set_buffer`. 4064 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4065 */ 4066 TILEDB_EXPORT int32_t tiledb_query_get_offsets_buffer( 4067 tiledb_ctx_t* ctx, 4068 tiledb_query_t* query, 4069 const char* name, 4070 uint64_t** buffer, 4071 uint64_t** buffer_size); 4072 4073 /** 4074 * Gets the validity byte map that has exactly one value for each value in the 4075 * data buffer. 4076 * 4077 * **Example:** 4078 * 4079 * @code{.c} 4080 * int* a1; 4081 * uint64_t* a1_size; 4082 * tiledb_query_get_validity_buffer(ctx, query, "a1", &a1, &a1_size); 4083 * @endcode 4084 * 4085 * @param ctx The TileDB context. 4086 * @param query The TileDB query. 4087 * @param name The attribute/dimension to get the buffer for. Note that the 4088 * zipped coordinates have special name `TILEDB_COORDS`. 4089 * @param buffer The buffer to retrieve. 4090 * @param buffer_size A pointer to the size of the buffer. Note that this is 4091 * a double pointer and returns the original variable address from 4092 * `set_buffer`. 4093 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4094 */ 4095 TILEDB_EXPORT int32_t tiledb_query_get_validity_buffer( 4096 tiledb_ctx_t* ctx, 4097 tiledb_query_t* query, 4098 const char* name, 4099 uint8_t** buffer, 4100 uint64_t** buffer_size); 4101 4102 /** 4103 * Sets the layout of the cells to be written or read. 4104 * 4105 * **Example:** 4106 * 4107 * @code{.c} 4108 * tiledb_query_set_layout(ctx, query, TILEDB_ROW_MAJOR); 4109 * @endcode 4110 * 4111 * @param ctx The TileDB context. 4112 * @param query The TileDB query. 4113 * @param layout For a write query, this specifies the order of the cells 4114 * provided by the user in the buffers. For a read query, this specifies 4115 * the order of the cells that will be retrieved as results and stored 4116 * in the user buffers. The layout can be one of the following: 4117 * - `TILEDB_COL_MAJOR`: 4118 * This means column-major order with respect to the subarray. 4119 * - `TILEDB_ROW_MAJOR`: 4120 * This means row-major order with respect to the subarray. 4121 * - `TILEDB_GLOBAL_ORDER`: 4122 * This means that cells are stored or retrieved in the array global 4123 * cell order. 4124 * - `TILEDB_UNORDERED`: 4125 * This is applicable only to reads and writes for sparse arrays, or for 4126 * sparse writes to dense arrays. For writes, it specifies that the cells 4127 * are unordered and, hence, TileDB must sort the cells in the global cell 4128 * order prior to writing. For reads, TileDB will return the cells without 4129 * any particular order, which will often lead to better performance. 4130 * * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4131 */ 4132 TILEDB_EXPORT int32_t tiledb_query_set_layout( 4133 tiledb_ctx_t* ctx, tiledb_query_t* query, tiledb_layout_t layout); 4134 4135 /** 4136 * Sets the query condition to be applied on a read. 4137 * 4138 * **Example:** 4139 * 4140 * @code{.c} 4141 * tiledb_query_condition_t* query_condition; 4142 * tiledb_query_condition_alloc(ctx, &query_condition); 4143 * uint32_t value = 5; 4144 * tiledb_query_condition_init( 4145 * ctx, query_condition, "longitude", &value, sizeof(value), TILEDB_LT); 4146 * tiledb_query_set_condition(ctx, query, query_condition); 4147 * @endcode 4148 * 4149 * @param ctx The TileDB context. 4150 * @param query The TileDB query. 4151 * @param cond The TileDB query condition. 4152 */ 4153 TILEDB_EXPORT int32_t tiledb_query_set_condition( 4154 tiledb_ctx_t* ctx, 4155 tiledb_query_t* query, 4156 const tiledb_query_condition_t* cond); 4157 4158 /** 4159 * Flushes all internal state of a query object and finalizes the query. 4160 * This is applicable only to global layout writes. It has no effect for 4161 * any other query type. 4162 * 4163 * **Example:** 4164 * 4165 * @code{.c} 4166 * tiledb_query_t* query; 4167 * // ... Your code here ... // 4168 * tiledb_query_finalize(ctx, query); 4169 * @endcode 4170 * 4171 * @param ctx The TileDB context. 4172 * @param query The query object to be flushed. 4173 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4174 */ 4175 TILEDB_EXPORT int32_t 4176 tiledb_query_finalize(tiledb_ctx_t* ctx, tiledb_query_t* query); 4177 4178 /** 4179 * Frees a TileDB query object. 4180 * 4181 * **Example:** 4182 * 4183 * @code{.c} 4184 * tiledb_query_free(&query); 4185 * @endcode 4186 * 4187 * @param query The query object to be deleted. 4188 */ 4189 TILEDB_EXPORT void tiledb_query_free(tiledb_query_t** query); 4190 4191 /** 4192 * Submits a TileDB query. 4193 * 4194 * **Example:** 4195 * 4196 * @code{.c} 4197 * tiledb_query_submit(ctx, query); 4198 * @endcode 4199 * 4200 * @param ctx The TileDB context. 4201 * @param query The query to be submitted. 4202 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4203 * 4204 * @note `tiledb_query_finalize` must be invoked after finish writing in 4205 * global layout (via repeated invocations of `tiledb_query_submit`), 4206 * in order to flush any internal state. 4207 * 4208 * @note For the case of reads, if the returned status is `TILEDB_INCOMPLETE`, 4209 * TileDB could not fit the entire result in the user's buffers. In this 4210 * case, the user should consume the read results (if any), optionally 4211 * reset the buffers with `tiledb_query_set_buffer`, and then resubmit the 4212 * query until the status becomes `TILEDB_COMPLETED`. If all buffer sizes 4213 * after the termination of this function become 0, then this means that 4214 * **no** useful data was read into the buffers, implying that larger 4215 * buffers are needed for the query to proceed. In this case, the users 4216 * must reallocate their buffers (increasing their size), reset the buffers 4217 * with `tiledb_query_set_buffer`, and resubmit the query. 4218 */ 4219 TILEDB_EXPORT int32_t 4220 tiledb_query_submit(tiledb_ctx_t* ctx, tiledb_query_t* query); 4221 4222 /** 4223 * Submits a TileDB query in asynchronous mode. 4224 * 4225 * **Examples:** 4226 * 4227 * Submit without a callback. 4228 * 4229 * @code{.c} 4230 * tiledb_query_submit_async(ctx, query, NULL, NULL); 4231 * @endcode 4232 * 4233 * Submit with a callback function `print` that takes as input message 4234 * `msg` and prints it upon completion of the query. 4235 * 4236 * @code{.c} 4237 * const char* msg = "Query completed"; 4238 * tiledb_query_submit_async(ctx, &query, foo, msg); 4239 * @endcode 4240 * 4241 * @param ctx The TileDB context. 4242 * @param query The query to be submitted. 4243 * @param callback The function to be called when the query completes. 4244 * @param callback_data The data to be passed to the callback function. 4245 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 4246 * 4247 * @note `tiledb_query_finalize` must be invoked after finish writing in 4248 * global layout (via repeated invocations of `tiledb_query_submit`), 4249 * in order to flush any internal state. 4250 * 4251 * @note For the case of reads, if the returned status is `TILEDB_INCOMPLETE`, 4252 * TileDB could not fit the entire result in the user's buffers. In this 4253 * case, the user should consume the read results (if any), optionally 4254 * reset the buffers with `tiledb_query_set_buffer`, and then resubmit the 4255 * query until the status becomes `TILEDB_COMPLETED`. If all buffer sizes 4256 * after the termination of this function become 0, then this means that 4257 * **no** useful data was read into the buffers, implying that larger 4258 * buffers are needed for the query to proceed. In this case, the users 4259 * must reallocate their buffers (increasing their size), reset the buffers 4260 * with `tiledb_query_set_buffer`, and resubmit the query. 4261 */ 4262 TILEDB_EXPORT int32_t tiledb_query_submit_async( 4263 tiledb_ctx_t* ctx, 4264 tiledb_query_t* query, 4265 void (*callback)(void*), 4266 void* callback_data); 4267 4268 /** 4269 * Checks if the query has returned any results. Applicable only to 4270 * read queries; it sets `has_results` to `0 in the case of writes. 4271 * 4272 * **Example:** 4273 * 4274 * @code{.c} 4275 * int32_t has_results; 4276 * tiledb_query_has_results(ctx, query, &has_results); 4277 * @endcode 4278 * 4279 * @param ctx The TileDB context. 4280 * @param query The query. 4281 * @param has_results Set to `1` if the query returned results and `0` 4282 * otherwise. 4283 * @return `TILEDB_OK` upon success, and `TILEDB_ERR` upon error. 4284 */ 4285 TILEDB_EXPORT int32_t tiledb_query_has_results( 4286 tiledb_ctx_t* ctx, tiledb_query_t* query, int32_t* has_results); 4287 4288 /** 4289 * Retrieves the status of a query. 4290 * 4291 * **Example:** 4292 * 4293 * @code{.c} 4294 * tiledb_query_status_t status; 4295 * tiledb_query_get_status(ctx, query, &status); 4296 * @endcode 4297 * 4298 * @param ctx The TileDB context. 4299 * @param query The query. 4300 * @param status The query status to be retrieved. 4301 * @return `TILEDB_OK` upon success, and `TILEDB_ERR` upon error. 4302 */ 4303 TILEDB_EXPORT int32_t tiledb_query_get_status( 4304 tiledb_ctx_t* ctx, tiledb_query_t* query, tiledb_query_status_t* status); 4305 4306 /** 4307 * Retrieves the query type. 4308 * 4309 * **Example:** 4310 * 4311 * @code{.c} 4312 * tiledb_query_type_t query_type; 4313 * tiledb_query_get_status(ctx, query, &query_type); 4314 * @endcode 4315 * 4316 * @param ctx The TileDB context. 4317 * @param query The query. 4318 * @param query_type The query type to be retrieved. 4319 * @return `TILEDB_OK` upon success, and `TILEDB_ERR` upon error. 4320 */ 4321 TILEDB_EXPORT int32_t tiledb_query_get_type( 4322 tiledb_ctx_t* ctx, tiledb_query_t* query, tiledb_query_type_t* query_type); 4323 4324 /** 4325 * Retrieves the query layout. 4326 * 4327 * **Example:** 4328 * 4329 * @code{.c} 4330 * tiledb_layout_t query_layout; 4331 * tiledb_query_get_layout(ctx, query, &query_layout); 4332 * @endcode 4333 * 4334 * @param ctx The TileDB context. 4335 * @param query The query. 4336 * @param query_layout The query layout to be retrieved. 4337 * @return `TILEDB_OK` upon success, and `TILEDB_ERR` upon error. 4338 */ 4339 TILEDB_EXPORT int32_t tiledb_query_get_layout( 4340 tiledb_ctx_t* ctx, tiledb_query_t* query, tiledb_layout_t* query_layout); 4341 4342 /** 4343 * Retrieves the query array. 4344 * 4345 * **Example:** 4346 * 4347 * @code{.c} 4348 * tiledb_array_t* array; 4349 * tiledb_query_get_array(ctx, query, &array); 4350 * @endcode 4351 * 4352 * @param ctx The TileDB context. 4353 * @param query The query. 4354 * @param array The query array to be retrieved. 4355 * @return `TILEDB_OK` upon success, and `TILEDB_ERR` upon error. 4356 */ 4357 TILEDB_EXPORT int32_t tiledb_query_get_array( 4358 tiledb_ctx_t* ctx, tiledb_query_t* query, tiledb_array_t** array); 4359 /** 4360 * Adds a 1D range along a subarray dimension index, which is in the form 4361 * (start, end, stride). The datatype of the range components 4362 * must be the same as the type of the domain of the array in the query. 4363 * 4364 * **Example:** 4365 * 4366 * @code{.c} 4367 * uint32_t dim_idx = 2; 4368 * int64_t start = 10; 4369 * int64_t end = 20; 4370 * tiledb_query_add_range(ctx, query, dim_idx, &start, &end, nullptr); 4371 * @endcode 4372 * 4373 * @param ctx The TileDB context. 4374 * @param query The query to add the range to. 4375 * @param dim_idx The index of the dimension to add the range to. 4376 * @param start The range start. 4377 * @param end The range end. 4378 * @param stride The range stride. 4379 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4380 * 4381 * @note The stride is currently unsupported. Use `nullptr` as the 4382 * stride argument. 4383 */ 4384 TILEDB_EXPORT int32_t tiledb_query_add_range( 4385 tiledb_ctx_t* ctx, 4386 tiledb_query_t* query, 4387 uint32_t dim_idx, 4388 const void* start, 4389 const void* end, 4390 const void* stride); 4391 4392 /** 4393 * Adds a 1D range along a subarray dimension name, which is in the form 4394 * (start, end, stride). The datatype of the range components 4395 * must be the same as the type of the domain of the array in the query. 4396 * 4397 * **Example:** 4398 * 4399 * @code{.c} 4400 * uint32_t dim_name = "rows"; 4401 * int64_t start = 10; 4402 * int64_t end = 20; 4403 * tiledb_query_add_range_by_name(ctx, query, dim_name, &start, &end, nullptr); 4404 * @endcode 4405 * 4406 * @param ctx The TileDB context. 4407 * @param query The query to add the range to. 4408 * @param dim_name The name of the dimension to add the range to. 4409 * @param start The range start. 4410 * @param end The range end. 4411 * @param stride The range stride. 4412 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4413 * 4414 * @note The stride is currently unsupported. Use `nullptr` as the 4415 * stride argument. 4416 */ 4417 TILEDB_EXPORT int32_t tiledb_query_add_range_by_name( 4418 tiledb_ctx_t* ctx, 4419 tiledb_query_t* query, 4420 const char* dim_name, 4421 const void* start, 4422 const void* end, 4423 const void* stride); 4424 4425 /** 4426 * Adds a 1D variable-sized range along a subarray dimension index, which is in 4427 * the form (start, end). Applicable only to variable-sized dimensions. 4428 * 4429 * **Example:** 4430 * 4431 * @code{.c} 4432 * uint32_t dim_idx = 2; 4433 * char start[] = "a"; 4434 * char end[] = "bb"; 4435 * tiledb_query_add_range_var(ctx, query, dim_idx, start, 1, end, 2); 4436 * @endcode 4437 * 4438 * @param ctx The TileDB context. 4439 * @param query The query to add the range to. 4440 * @param dim_idx The index of the dimension to add the range to. 4441 * @param start The range start. 4442 * @param start_size The size of the range start in bytes. 4443 * @param end The range end. 4444 * @param end_size The size of the range end in bytes. 4445 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4446 */ 4447 TILEDB_EXPORT int32_t tiledb_query_add_range_var( 4448 tiledb_ctx_t* ctx, 4449 tiledb_query_t* query, 4450 uint32_t dim_idx, 4451 const void* start, 4452 uint64_t start_size, 4453 const void* end, 4454 uint64_t end_size); 4455 4456 /** 4457 * Adds a 1D variable-sized range along a subarray dimension name, which is in 4458 * the form (start, end). Applicable only to variable-sized dimensions. 4459 * 4460 * **Example:** 4461 * 4462 * @code{.c} 4463 * uint32_t dim_name = "rows"; 4464 * char start[] = "a"; 4465 * char end[] = "bb"; 4466 * tiledb_query_add_range_var_by_name(ctx, query, dim_name, start, 1, end, 2); 4467 * @endcode 4468 * 4469 * @param ctx The TileDB context. 4470 * @param query The query to add the range to. 4471 * @param dim_name The name of the dimension to add the range to. 4472 * @param start The range start. 4473 * @param start_size The size of the range start in bytes. 4474 * @param end The range end. 4475 * @param end_size The size of the range end in bytes. 4476 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4477 */ 4478 TILEDB_EXPORT int32_t tiledb_query_add_range_var_by_name( 4479 tiledb_ctx_t* ctx, 4480 tiledb_query_t* query, 4481 const char* dim_name, 4482 const void* start, 4483 uint64_t start_size, 4484 const void* end, 4485 uint64_t end_size); 4486 4487 /** 4488 * Retrieves the number of ranges of the query subarray along a given dimension 4489 * index. 4490 * 4491 * **Example:** 4492 * 4493 * @code{.c} 4494 * uint64_t range_num; 4495 * tiledb_query_get_range_num(ctx, query, dim_idx, &range_num); 4496 * @endcode 4497 * 4498 * @param ctx The TileDB context 4499 * @param query The query. 4500 * @param dim_idx The index of the dimension whose range number to retrieve. 4501 * @param range_num The number of ranges to retrieve. 4502 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4503 */ 4504 TILEDB_EXPORT int32_t tiledb_query_get_range_num( 4505 tiledb_ctx_t* ctx, 4506 const tiledb_query_t* query, 4507 uint32_t dim_idx, 4508 uint64_t* range_num); 4509 4510 /** 4511 * Retrieves the number of ranges of the query subarray along a given dimension 4512 * name. 4513 * 4514 * **Example:** 4515 * 4516 * @code{.c} 4517 * uint64_t range_num; 4518 * tiledb_query_get_range_num_from_name(ctx, query, dim_name, &range_num); 4519 * @endcode 4520 * 4521 * @param ctx The TileDB context 4522 * @param query The query. 4523 * @param dim_name The name of the dimension whose range number to retrieve. 4524 * @param range_num The number of ranges to retrieve. 4525 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4526 */ 4527 TILEDB_EXPORT int32_t tiledb_query_get_range_num_from_name( 4528 tiledb_ctx_t* ctx, 4529 const tiledb_query_t* query, 4530 const char* dim_name, 4531 uint64_t* range_num); 4532 4533 /** 4534 * Retrieves a specific range of the query subarray along a given dimension 4535 * index. 4536 * 4537 * **Example:** 4538 * 4539 * @code{.c} 4540 * const void* start; 4541 * const void* end; 4542 * const void* stride; 4543 * tiledb_query_get_range( 4544 * ctx, query, dim_idx, range_idx, &start, &end, &stride); 4545 * @endcode 4546 * 4547 * @param ctx The TileDB context 4548 * @param query The query. 4549 * @param dim_idx The index of the dimension to retrieve the range from. 4550 * @param range_idx The index of the range to retrieve. 4551 * @param start The range start to retrieve. 4552 * @param end The range end to retrieve. 4553 * @param stride The range stride to retrieve. 4554 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4555 */ 4556 TILEDB_EXPORT int32_t tiledb_query_get_range( 4557 tiledb_ctx_t* ctx, 4558 const tiledb_query_t* query, 4559 uint32_t dim_idx, 4560 uint64_t range_idx, 4561 const void** start, 4562 const void** end, 4563 const void** stride); 4564 4565 /** 4566 * Retrieves a specific range of the query subarray along a given dimension 4567 * name. 4568 * 4569 * **Example:** 4570 * 4571 * @code{.c} 4572 * const void* start; 4573 * const void* end; 4574 * const void* stride; 4575 * tiledb_query_get_range_from_name( 4576 * ctx, query, dim_name, range_idx, &start, &end, &stride); 4577 * @endcode 4578 * 4579 * @param ctx The TileDB context 4580 * @param query The query. 4581 * @param dim_name The name of the dimension to retrieve the range from. 4582 * @param range_idx The index of the range to retrieve. 4583 * @param start The range start to retrieve. 4584 * @param end The range end to retrieve. 4585 * @param stride The range stride to retrieve. 4586 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4587 */ 4588 TILEDB_EXPORT int32_t tiledb_query_get_range_from_name( 4589 tiledb_ctx_t* ctx, 4590 const tiledb_query_t* query, 4591 const char* dim_name, 4592 uint64_t range_idx, 4593 const void** start, 4594 const void** end, 4595 const void** stride); 4596 4597 /** 4598 * Retrieves a range's start and end size for a given variable-length 4599 * dimension index at a given range index. 4600 * 4601 * **Example:** 4602 * 4603 * @code{.c} 4604 * uint64_t start_size; 4605 * uint64_t end_size; 4606 * tiledb_query_get_range_var_size( 4607 * ctx, query, dim_idx, range_idx, &start_size, &end_size); 4608 * @endcode 4609 * 4610 * @param ctx The TileDB context 4611 * @param query The query. 4612 * @param dim_idx The index of the dimension to retrieve the range from. 4613 * @param range_idx The index of the range to retrieve. 4614 * @param start_size range start size in bytes 4615 * @param end_size range end size in bytes 4616 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4617 */ 4618 TILEDB_EXPORT int32_t tiledb_query_get_range_var_size( 4619 tiledb_ctx_t* ctx, 4620 const tiledb_query_t* query, 4621 uint32_t dim_idx, 4622 uint64_t range_idx, 4623 uint64_t* start_size, 4624 uint64_t* end_size); 4625 4626 /** 4627 * Retrieves a range's start and end size for a given variable-length 4628 * dimension name at a given range index. 4629 * 4630 * **Example:** 4631 * 4632 * @code{.c} 4633 * uint64_t start_size; 4634 * uint64_t end_size; 4635 * tiledb_query_get_range_var_size_from_name( 4636 * ctx, query, dim_name, range_idx, &start_size, &end_size); 4637 * @endcode 4638 * 4639 * @param ctx The TileDB context 4640 * @param query The query. 4641 * @param dim_name The name of the dimension to retrieve the range from. 4642 * @param range_idx The index of the range to retrieve. 4643 * @param start_size range start size in bytes 4644 * @param end_size range end size in bytes 4645 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4646 */ 4647 TILEDB_EXPORT int32_t tiledb_query_get_range_var_size_from_name( 4648 tiledb_ctx_t* ctx, 4649 const tiledb_query_t* query, 4650 const char* dim_name, 4651 uint64_t range_idx, 4652 uint64_t* start_size, 4653 uint64_t* end_size); 4654 4655 /** 4656 * Retrieves a specific range of the query subarray along a given 4657 * variable-length dimension index. 4658 * 4659 * **Example:** 4660 * 4661 * @code{.c} 4662 * const void* start; 4663 * const void* end; 4664 * tiledb_query_get_range_var( 4665 * ctx, query, dim_idx, range_idx, &start, &end); 4666 * @endcode 4667 * 4668 * @param ctx The TileDB context 4669 * @param query The query. 4670 * @param dim_idx The index of the dimension to retrieve the range from. 4671 * @param range_idx The index of the range to retrieve. 4672 * @param start The range start to retrieve. 4673 * @param end The range end to retrieve. 4674 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4675 */ 4676 TILEDB_EXPORT int32_t tiledb_query_get_range_var( 4677 tiledb_ctx_t* ctx, 4678 const tiledb_query_t* query, 4679 uint32_t dim_idx, 4680 uint64_t range_idx, 4681 void* start, 4682 void* end); 4683 4684 /** 4685 * Retrieves a specific range of the query subarray along a given 4686 * variable-length dimension name. 4687 * 4688 * **Example:** 4689 * 4690 * @code{.c} 4691 * const void* start; 4692 * const void* end; 4693 * tiledb_query_get_range_var_from_name( 4694 * ctx, query, dim_name, range_idx, &start, &end); 4695 * @endcode 4696 * 4697 * @param ctx The TileDB context 4698 * @param query The query. 4699 * @param dim_name The name of the dimension to retrieve the range from. 4700 * @param range_idx The index of the range to retrieve. 4701 * @param start The range start to retrieve. 4702 * @param end The range end to retrieve. 4703 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4704 */ 4705 TILEDB_EXPORT int32_t tiledb_query_get_range_var_from_name( 4706 tiledb_ctx_t* ctx, 4707 const tiledb_query_t* query, 4708 const char* dim_name, 4709 uint64_t range_idx, 4710 void* start, 4711 void* end); 4712 4713 /** 4714 * Retrieves the estimated result size for a fixed-sized attribute/dimension. 4715 * 4716 * **Example:** 4717 * 4718 * @code{.c} 4719 * uint64_t size; 4720 * tiledb_query_get_est_result_size(ctx, query, "a", &size); 4721 * @endcode 4722 * 4723 * @param ctx The TileDB context 4724 * @param query The query. 4725 * @param name The attribute/dimension name. 4726 * @param size The size (in bytes) to be retrieved. 4727 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4728 */ 4729 TILEDB_EXPORT int32_t tiledb_query_get_est_result_size( 4730 tiledb_ctx_t* ctx, 4731 const tiledb_query_t* query, 4732 const char* name, 4733 uint64_t* size); 4734 4735 /** 4736 * Retrieves the estimated result size for a var-sized attribute/dimension. 4737 * 4738 * **Example:** 4739 * 4740 * @code{.c} 4741 * uint64_t size_off, size_val; 4742 * tiledb_query_get_est_result_size_var( 4743 * ctx, query, "a", &size_off, &size_val); 4744 * @endcode 4745 * 4746 * @param ctx The TileDB context 4747 * @param query The query. 4748 * @param name The attribute/dimension name. 4749 * @param size_off The size of the offsets (in bytes) to be retrieved. 4750 * @param size_val The size of the values (in bytes) to be retrieved. 4751 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4752 */ 4753 TILEDB_EXPORT int32_t tiledb_query_get_est_result_size_var( 4754 tiledb_ctx_t* ctx, 4755 const tiledb_query_t* query, 4756 const char* name, 4757 uint64_t* size_off, 4758 uint64_t* size_val); 4759 4760 /** 4761 * Retrieves the estimated result size for a fixed-sized, nullable attribute. 4762 * 4763 * **Example:** 4764 * 4765 * @code{.c} 4766 * uint64_t size_val; 4767 * uint64_t size_validity; 4768 * tiledb_query_get_est_result_size_nullable(ctx, query, "a", &size_val, 4769 * &size_validity); 4770 * @endcode 4771 * 4772 * @param ctx The TileDB context 4773 * @param query The query. 4774 * @param name The attribute name. 4775 * @param size_val The size of the values (in bytes) to be retrieved. 4776 * @param size_validity The size of the validity values (in bytes) to be 4777 * retrieved. 4778 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4779 */ 4780 TILEDB_EXPORT int32_t tiledb_query_get_est_result_size_nullable( 4781 tiledb_ctx_t* ctx, 4782 const tiledb_query_t* query, 4783 const char* name, 4784 uint64_t* size_val, 4785 uint64_t* size_validity); 4786 4787 /** 4788 * Retrieves the estimated result size for a var-sized, nullable attribute. 4789 * 4790 * **Example:** 4791 * 4792 * @code{.c} 4793 * uint64_t size_off, size_val, size_validity; 4794 * tiledb_query_get_est_result_size_var_nullable( 4795 * ctx, query, "a", &size_off, &size_val, &size_validity); 4796 * @endcode 4797 * 4798 * @param ctx The TileDB context 4799 * @param query The query. 4800 * @param name The attribute name. 4801 * @param size_off The size of the offsets (in bytes) to be retrieved. 4802 * @param size_val The size of the values (in bytes) to be retrieved. 4803 * @param size_validity The size of the validity values (in bytes) to be 4804 * retrieved. 4805 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4806 */ 4807 TILEDB_EXPORT int32_t tiledb_query_get_est_result_size_var_nullable( 4808 tiledb_ctx_t* ctx, 4809 const tiledb_query_t* query, 4810 const char* name, 4811 uint64_t* size_off, 4812 uint64_t* size_val, 4813 uint64_t* size_validity); 4814 4815 /** 4816 * Retrieves the number of written fragments. Applicable only to WRITE 4817 * queries. 4818 * 4819 * **Example:** 4820 * 4821 * @code{.c} 4822 * uint32_t num; 4823 * tiledb_query_get_fragment_num(ctx, query, &num); 4824 * @endcode 4825 * 4826 * @param ctx The TileDB context 4827 * @param query The query. 4828 * @param num The number of written fragments to be retrieved. 4829 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4830 */ 4831 TILEDB_EXPORT int32_t tiledb_query_get_fragment_num( 4832 tiledb_ctx_t* ctx, const tiledb_query_t* query, uint32_t* num); 4833 4834 /** 4835 * Retrieves the URI of the written fragment with the input index. Applicable 4836 * only to WRITE queries. 4837 * 4838 * **Example:** 4839 * 4840 * @code{.c} 4841 * const char* uri; 4842 * tiledb_query_get_fragment_uri( 4843 * ctx, query, 0, &uri); 4844 * @endcode 4845 * 4846 * @param ctx The TileDB context 4847 * @param query The query. 4848 * @param idx The index of the written fragment. 4849 * @param uri The URI of the written fragment to be returned. 4850 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4851 * 4852 * @note Make sure to make a copy of `uri` after its retrieval, as the 4853 * constant pointer may be updated internally as new fragments 4854 * are being written. 4855 */ 4856 TILEDB_EXPORT int32_t tiledb_query_get_fragment_uri( 4857 tiledb_ctx_t* ctx, 4858 const tiledb_query_t* query, 4859 uint64_t idx, 4860 const char** uri); 4861 4862 /** 4863 * Retrieves the timestamp range of the written fragment with the input index. 4864 * Applicable only to WRITE queries. 4865 * 4866 * **Example:** 4867 * 4868 * @code{.c} 4869 * uint64_t t1, t2; 4870 * tiledb_query_get_fragment_timestamp_range( 4871 * ctx, query, 0, &t1, &t2); 4872 * @endcode 4873 * 4874 * @param ctx The TileDB context 4875 * @param query The query. 4876 * @param idx The index of the written fragment. 4877 * @param t1 The start value of the timestamp range of the 4878 * written fragment to be returned. 4879 * @param t2 The end value of the timestamp range of the 4880 * written fragment to be returned. 4881 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4882 */ 4883 TILEDB_EXPORT int32_t tiledb_query_get_fragment_timestamp_range( 4884 tiledb_ctx_t* ctx, 4885 const tiledb_query_t* query, 4886 uint64_t idx, 4887 uint64_t* t1, 4888 uint64_t* t2); 4889 4890 /* ****************************** */ 4891 /* QUERY CONDITION */ 4892 /* ****************************** */ 4893 4894 /** 4895 * Allocates a TileDB query condition object. 4896 * 4897 * **Example:** 4898 * 4899 * @code{.c} 4900 * tiledb_query_condition_t* query_condition; 4901 * tiledb_query_condition_alloc(ctx, &query_condition); 4902 * @endcode 4903 * 4904 * @param ctx The TileDB context. 4905 * @param cond The allocated query condition object. 4906 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 4907 */ 4908 TILEDB_EXPORT int32_t tiledb_query_condition_alloc( 4909 tiledb_ctx_t* ctx, tiledb_query_condition_t** cond); 4910 4911 /** 4912 * Frees a TileDB query condition object. 4913 * 4914 * **Example:** 4915 * 4916 * @code{.c} 4917 * uint32_t value = 5; 4918 * tiledb_query_condition_t* query_condition; 4919 * tiledb_query_condition_alloc( 4920 * ctx, "longitude", &value, sizeof(value), TILEDB_LT, &query_condition); 4921 * tiledb_query_set_condition(ctx, query, query_condition); 4922 * tiledb_query_submit(ctx, query); 4923 * tiledb_query_condition_free(&query_condition); 4924 * @endcode 4925 * 4926 * @param cond The query condition object to be freed. 4927 */ 4928 TILEDB_EXPORT void tiledb_query_condition_free(tiledb_query_condition_t** cond); 4929 4930 /** 4931 * Initializes a TileDB query condition object. 4932 * 4933 * **Example:** 4934 * 4935 * @code{.c} 4936 * tiledb_query_condition_t* query_condition; 4937 * tiledb_query_condition_alloc(ctx, &query_condition); 4938 * 4939 * uint32_t value = 5; 4940 * tiledb_query_condition_init( 4941 * ctx, query_condition, "longitude", &value, sizeof(value), TILEDB_LT); 4942 * @endcode 4943 * 4944 * @param ctx The TileDB context. 4945 * @param cond The allocated query condition object. 4946 * @param attribute_name The attribute name. 4947 * @param condition_value The value to compare against an attribute value. 4948 * @param condition_value_size The byte size of `condition_value`. 4949 * @param op The comparison operator. 4950 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 4951 */ 4952 TILEDB_EXPORT int32_t tiledb_query_condition_init( 4953 tiledb_ctx_t* ctx, 4954 tiledb_query_condition_t* cond, 4955 const char* attribute_name, 4956 const void* condition_value, 4957 uint64_t condition_value_size, 4958 tiledb_query_condition_op_t op); 4959 4960 /** 4961 * Combines two query condition objects into a newly allocated 4962 * condition. Does not mutate or free the input condition objects. 4963 * 4964 * **Example:** 4965 * 4966 * @code{.c} 4967 * tiledb_query_condition_t* query_condition_1; 4968 * tiledb_query_condition_alloc(ctx, &query_condition_1); 4969 * uint32_t value_1 = 5; 4970 * tiledb_query_condition_init( 4971 * ctx, 4972 * query_condition_1, 4973 * "longitude", 4974 * &value_1, 4975 * sizeof(value_1), 4976 * TILEDB_LT); 4977 * 4978 * tiledb_query_condition_t* query_condition_2; 4979 * tiledb_query_condition_alloc(ctx, &query_condition_2); 4980 * uint32_t value_2 = 20; 4981 * tiledb_query_condition_init( 4982 * ctx, 4983 * query_condition_2, 4984 * "latitude", 4985 * &value_2, 4986 * sizeof(value_2), 4987 * TILEDB_GE); 4988 * 4989 * tiledb_query_condition_t* query_condition_3; 4990 * tiledb_query_condition_combine( 4991 * ctx, query_condition_1, query_condition_2, TILEDB_AND, &query_condition_3); 4992 * 4993 * tiledb_query_condition_free(&query_condition_1); 4994 * tiledb_query_condition_free(&query_condition_2); 4995 * 4996 * tiledb_query_set_condition(ctx, query, query_condition_3); 4997 * tiledb_query_submit(ctx, query); 4998 * tiledb_query_condition_free(&query_condition_3); 4999 * @endcode 5000 * 5001 * @param ctx The TileDB context. 5002 * @param attribute_name The attribute name. 5003 * @param condition_value The value to compare against an attribute value. 5004 * @param condition_value_size The byte size of `condition_value`. 5005 * @param op The comparison operator. 5006 * @param cond The allocated query condition object. 5007 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 5008 */ 5009 TILEDB_EXPORT int32_t tiledb_query_condition_combine( 5010 tiledb_ctx_t* ctx, 5011 const tiledb_query_condition_t* left_cond, 5012 const tiledb_query_condition_t* right_cond, 5013 tiledb_query_condition_combination_op_t combination_op, 5014 tiledb_query_condition_t** combined_cond); 5015 5016 /* ********************************* */ 5017 /* ARRAY */ 5018 /* ********************************* */ 5019 5020 /** 5021 * Allocates a TileDB array object. 5022 * 5023 * **Example:** 5024 * 5025 * @code{.c} 5026 * tiledb_array_t* array; 5027 * tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); 5028 * @endcode 5029 * 5030 * @param ctx The TileDB context. 5031 * @param array_uri The array URI. 5032 * @param array The array object to be created. 5033 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 5034 */ 5035 TILEDB_EXPORT int32_t tiledb_array_alloc( 5036 tiledb_ctx_t* ctx, const char* array_uri, tiledb_array_t** array); 5037 5038 /** 5039 * Sets the starting timestamp to use when opening (and reopening) the array. 5040 * This is an inclusive bound. The default value is `0`. 5041 * 5042 * **Example:** 5043 * 5044 * @code{.c} 5045 * tiledb_array_t* array; 5046 * tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array); 5047 * tiledb_array_set_open_timestamp_start(ctx, array, 1234); 5048 * tiledb_array_open(ctx, array, TILEDB_READ); 5049 * @endcode 5050 * 5051 * @param ctx The TileDB context. 5052 * @param array The array to set the timestamp on. 5053 * @param timestamp_start The epoch timestamp in milliseconds. 5054 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 5055 */ 5056 TILEDB_EXPORT int32_t tiledb_array_set_open_timestamp_start( 5057 tiledb_ctx_t* ctx, tiledb_array_t* array, uint64_t timestamp_start); 5058 5059 /** 5060 * Sets the ending timestamp to use when opening (and reopening) the array. 5061 * This is an inclusive bound. The UINT64_MAX timestamp is a reserved timestamp 5062 * that will be interpretted as the current timestamp when an array is opened. 5063 * The default value is `UINT64_MAX`. 5064 * 5065 * **Example:** 5066 * 5067 * @code{.c} 5068 * tiledb_array_t* array; 5069 * tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array); 5070 * tiledb_array_set_open_timestamp_end(ctx, array, 5678); 5071 * tiledb_array_open(ctx, array, TILEDB_READ); 5072 * @endcode 5073 * 5074 * @param ctx The TileDB context. 5075 * @param array The array to set the timestamp on. 5076 * @param timestamp_end The epoch timestamp in milliseconds. Use UINT64_MAX for 5077 * the current timestamp. 5078 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 5079 */ 5080 TILEDB_EXPORT int32_t tiledb_array_set_open_timestamp_end( 5081 tiledb_ctx_t* ctx, tiledb_array_t* array, uint64_t timestamp_end); 5082 5083 /** 5084 * Gets the starting timestamp used when opening (and reopening) the array. 5085 * This is an inclusive bound. 5086 * 5087 * **Example:** 5088 * 5089 * @code{.c} 5090 * tiledb_array_t* array; 5091 * tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array); 5092 * tiledb_array_set_open_timestamp_start(ctx, array, 1234); 5093 * tiledb_array_open(ctx, array, TILEDB_READ); 5094 * 5095 * uint64_t timestamp_start; 5096 * tiledb_array_get_open_timestamp_start(ctx, array, ×tamp_start); 5097 * assert(timestamp_start == 1234); 5098 * @endcode 5099 * 5100 * @param ctx The TileDB context. 5101 * @param array The array to set the timestamp on. 5102 * @param timestamp_start The output epoch timestamp in milliseconds. 5103 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 5104 */ 5105 TILEDB_EXPORT int32_t tiledb_array_get_open_timestamp_start( 5106 tiledb_ctx_t* ctx, tiledb_array_t* array, uint64_t* timestamp_start); 5107 5108 /** 5109 * Gets the ending timestamp used when opening (and reopening) the array. 5110 * This is an inclusive bound. If UINT64_MAX was set, this will return 5111 * the timestamp at the time the array was opened. If the array has not 5112 * yet been opened, it will return UINT64_MAX.` 5113 * 5114 * **Example:** 5115 * 5116 * @code{.c} 5117 * tiledb_array_t* array; 5118 * tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array); 5119 * tiledb_array_set_open_timestamp_end(ctx, array, 5678); 5120 * tiledb_array_open(ctx, array, TILEDB_READ); 5121 * 5122 * uint64_t timestamp_end; 5123 * tiledb_array_get_open_timestamp_end(ctx, array, ×tamp_end); 5124 * assert(timestamp_start == 5678); 5125 * @endcode 5126 * 5127 * @param ctx The TileDB context. 5128 * @param array The array to set the timestamp on. 5129 * @param timestamp_end The output epoch timestamp in milliseconds. 5130 * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. 5131 */ 5132 TILEDB_EXPORT int32_t tiledb_array_get_open_timestamp_end( 5133 tiledb_ctx_t* ctx, tiledb_array_t* array, uint64_t* timestamp_end); 5134 5135 /** 5136 * Opens a TileDB array. The array is opened using a query type as input. 5137 * This is to indicate that queries created for this `tiledb_array_t` 5138 * object will inherit the query type. In other words, `tiledb_array_t` 5139 * objects are opened to receive only one type of queries. 5140 * They can always be closed and be re-opened with another query type. 5141 * Also there may be many different `tiledb_array_t` 5142 * objects created and opened with different query types. 5143 * 5144 * **Example:** 5145 * 5146 * @code{.c} 5147 * tiledb_array_t* array; 5148 * tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); 5149 * tiledb_array_open(ctx, array, TILEDB_READ); 5150 * @endcode 5151 * 5152 * @param ctx The TileDB context. 5153 * @param array The array object to be opened. 5154 * @param query_type The type of queries the array object will be receiving. 5155 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5156 * 5157 * @note If the same array object is opened again without being closed, 5158 * an error will be thrown. 5159 * @note The config should be set before opening an array. 5160 * @note If the array is to be opened at a specfic time interval, the 5161 * `timestamp{start, end}` values should be set to a config that's set to 5162 * the array object before opening the array. 5163 */ 5164 TILEDB_EXPORT int32_t tiledb_array_open( 5165 tiledb_ctx_t* ctx, tiledb_array_t* array, tiledb_query_type_t query_type); 5166 5167 /** 5168 * Similar to `tiledb_array_open`, but this function takes as input a 5169 * timestamp, representing time in milliseconds ellapsed since 5170 * 1970-01-01 00:00:00 +0000 (UTC). Opening the array at a 5171 * timestamp provides a view of the array with all writes/updates that 5172 * happened at or before `timestamp` (i.e., excluding those that 5173 * occurred after `timestamp`). This function is useful to ensure 5174 * consistency at a potential distributed setting, where machines 5175 * need to operate on the same view of the array. 5176 * 5177 * **Example:** 5178 * 5179 * @code{.c} 5180 * tiledb_array_t* array; 5181 * tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); 5182 * // Assuming `timestamp` is time represented in milliseconds: 5183 * tiledb_array_open_at(ctx, array, TILEDB_READ, timestamp); 5184 * @endcode 5185 * 5186 * @param ctx The TileDB context. 5187 * @param array The array object to be opened. 5188 * @param query_type The type of queries the array object will be receiving. 5189 * @param timestamp The timestamp to open the array at. 5190 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5191 * 5192 * @note If the same array object is opened again without being closed, 5193 * an error will be thrown. 5194 * @note This function is applicable only to read queries. 5195 * @note The config should be set before opening an array. 5196 * @note If the array is to be opened at a specfic time interval, the 5197 * `timestamp{start, end}` values should be set to a config that's set to 5198 * the array object before opening the array. 5199 */ 5200 TILEDB_DEPRECATED_EXPORT int32_t tiledb_array_open_at( 5201 tiledb_ctx_t* ctx, 5202 tiledb_array_t* array, 5203 tiledb_query_type_t query_type, 5204 uint64_t timestamp); 5205 5206 /** 5207 * Opens an encrypted array using the given encryption key. This function has 5208 * the same semantics as `tiledb_array_open()` but is used for encrypted arrays. 5209 * 5210 * An encrypted array must be opened with this function before queries can be 5211 * issued to it. 5212 * 5213 * **Example:** 5214 * 5215 * @code{.c} 5216 * // Load AES-256 key from disk, environment variable, etc. 5217 * uint8_t key[32] = ...; 5218 * tiledb_array_t* array; 5219 * tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); 5220 * tiledb_array_open_with_key(ctx, array, TILEDB_READ, 5221 * TILEDB_AES_256_GCM, key, sizeof(key)); 5222 * @endcode 5223 * 5224 * @param ctx The TileDB context. 5225 * @param array The array object to be opened. 5226 * @param query_type The type of queries the array object will be receiving. 5227 * @param encryption_type The encryption type to use. 5228 * @param encryption_key The encryption key to use. 5229 * @param key_length Length in bytes of the encryption key. 5230 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5231 * 5232 * @note The config should be set before opening an array. 5233 */ 5234 TILEDB_DEPRECATED_EXPORT int32_t tiledb_array_open_with_key( 5235 tiledb_ctx_t* ctx, 5236 tiledb_array_t* array, 5237 tiledb_query_type_t query_type, 5238 tiledb_encryption_type_t encryption_type, 5239 const void* encryption_key, 5240 uint32_t key_length); 5241 5242 /** 5243 * Similar to `tiledb_array_open_with_key`, but this function takes as 5244 * input a timestamp, representing time in milliseconds ellapsed since 5245 * 1970-01-01 00:00:00 +0000 (UTC). Opening the array at a 5246 * timestamp provides a view of the array with all writes/updates that 5247 * happened at or before `timestamp` (i.e., excluding those that 5248 * occurred after `timestamp`). This function is useful to ensure 5249 * consistency at a potential distributed setting, where machines 5250 * need to operate on the same view of the array. 5251 * 5252 * **Example:** 5253 * 5254 * @code{.c} 5255 * // Load AES-256 key from disk, environment variable, etc. 5256 * uint8_t key[32] = ...; 5257 * tiledb_array_t* array; 5258 * tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); 5259 * // Assuming `timestamp` is time represented in milliseconds: 5260 * tiledb_array_open_at_with_key(ctx, array, TILEDB_READ, 5261 * TILEDB_AES_256_GCM, key, sizeof(key), timestamp); 5262 * @endcode 5263 * 5264 * @param ctx The TileDB context. 5265 * @param array The array object to be opened. 5266 * @param query_type The type of queries the array object will be receiving. 5267 * @param encryption_type The encryption type to use. 5268 * @param encryption_key The encryption key to use. 5269 * @param key_length Length in bytes of the encryption key. 5270 * @param timestamp The timestamp to open the array at. 5271 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5272 * 5273 * @note If the same array object is opened again without being closed, 5274 * an error will be thrown. 5275 * @note This function is applicable only to read queries. 5276 * @note The config should be set before opening an array. 5277 */ 5278 TILEDB_DEPRECATED_EXPORT int32_t tiledb_array_open_at_with_key( 5279 tiledb_ctx_t* ctx, 5280 tiledb_array_t* array, 5281 tiledb_query_type_t query_type, 5282 tiledb_encryption_type_t encryption_type, 5283 const void* encryption_key, 5284 uint32_t key_length, 5285 uint64_t timestamp); 5286 5287 /** 5288 * Checks if the array is open. 5289 * 5290 * @param ctx The TileDB context. 5291 * @param array The array to be checked. 5292 * @param is_open `1` if the array is open and `0` otherwise. 5293 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5294 */ 5295 TILEDB_EXPORT int32_t tiledb_array_is_open( 5296 tiledb_ctx_t* ctx, tiledb_array_t* array, int32_t* is_open); 5297 5298 /** 5299 * Reopens a TileDB array (the array must be already open). This is useful 5300 * when the array got updated after it got opened and the `tiledb_array_t` 5301 * object got created. To sync-up with the updates, the user must either 5302 * close the array and open with `tiledb_array_open`, or just use 5303 * `tiledb_array_reopen` without closing. This function will be generally 5304 * faster than the former alternative. 5305 * 5306 * Note: reopening encrypted arrays does not require the encryption key. 5307 * 5308 * **Example:** 5309 * 5310 * @code{.c} 5311 * tiledb_array_t* array; 5312 * tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); 5313 * tiledb_array_open(ctx, array, TILEDB_READ); 5314 * tiledb_array_reopen(ctx, array); 5315 * 5316 * @endcode 5317 * 5318 * @param ctx The TileDB context. 5319 * @param array The array object to be re-opened. 5320 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5321 * 5322 * @note This is applicable only to arrays opened for reads. 5323 * @note If the array is to be reopened after opening at a specfic time 5324 * interval, the `timestamp{start, end}` values and subsequent config 5325 * object should be reset for the array before reopening. 5326 */ 5327 TILEDB_EXPORT int32_t 5328 tiledb_array_reopen(tiledb_ctx_t* ctx, tiledb_array_t* array); 5329 5330 /** 5331 * Reopens a TileDB array (the array must be already open) at a specific 5332 * timestamp. 5333 * 5334 * **Example:** 5335 * 5336 * @code{.c} 5337 * tiledb_array_t* array; 5338 * tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); 5339 * tiledb_array_open(ctx, array, TILEDB_READ); 5340 * uint64_t timestamp = tiledb_timestamp_now_ms(); 5341 * tiledb_array_reopen_at(ctx, array, timestamp); 5342 * 5343 * @endcode 5344 * 5345 * @param ctx The TileDB context. 5346 * @param array The array object to be re-opened. 5347 * @param timestamp Timestamp at which to reopen. 5348 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5349 * 5350 * @note This is applicable only to arrays opened for reads. 5351 * @note If the array is to be reopened after opening at a specfic time 5352 * interval, the `timestamp{start, end}` values and subsequent config 5353 * object should be reset for the array before reopening. 5354 */ 5355 TILEDB_DEPRECATED_EXPORT int32_t tiledb_array_reopen_at( 5356 tiledb_ctx_t* ctx, tiledb_array_t* array, uint64_t timestamp); 5357 5358 /** 5359 * The start/end timestamps for opening an array 5360 * are now set in the config. 5361 * 5362 * Returns the timestamp, representing time in milliseconds ellapsed since 5363 * 1970-01-01 00:00:00 +0000 (UTC), at which the array was opened. See also the 5364 * documentation of `tiledb_array_open_at`. 5365 * 5366 * **Example:** 5367 * 5368 * @code{.c} 5369 * tiledb_array_t* array; 5370 * tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array); 5371 * tiledb_array_open(ctx, array, TILEDB_READ); 5372 * // Get the timestamp the array at which the array was opened. 5373 * uint64_t timestamp; 5374 * tiledb_array_get_timestamp(ctx, array, ×tamp); 5375 * @endcode 5376 * 5377 * @param ctx The TileDB context. 5378 * @param array The array to retrieve the timestamp for. 5379 * @param timestamp Set to the timestamp at which the array was opened. 5380 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5381 * 5382 * @note The array does not need to be open to use this function. 5383 */ 5384 TILEDB_DEPRECATED_EXPORT int32_t tiledb_array_get_timestamp( 5385 tiledb_ctx_t* ctx, tiledb_array_t* array, uint64_t* timestamp); 5386 5387 /** 5388 * Sets the array config. 5389 * 5390 * **Example:** 5391 * 5392 * @code{.c} 5393 * tiledb_array_t* array; 5394 * tiledb_array_alloc(ctx, "s3://tiledb_bucket/my_array", &array); 5395 * tiledb_array_open(ctx, array, TILEDB_READ); 5396 * // Set the config for the given array. 5397 * tiledb_config_t* config; 5398 * tiledb_array_set_config(ctx, array, config); 5399 * @endcode 5400 * 5401 * @param ctx The TileDB context. 5402 * @param array The array to set the config for. 5403 * @param config The config to be set. 5404 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5405 * 5406 * @note The array does not need to be opened via `tiledb_array_open_at` to use 5407 * this function. 5408 * @note The config should be set before opening an array. 5409 */ 5410 TILEDB_EXPORT int32_t tiledb_array_set_config( 5411 tiledb_ctx_t* ctx, tiledb_array_t* array, tiledb_config_t* config); 5412 5413 /** 5414 * Gets the array config. 5415 * 5416 * **Example:** 5417 * 5418 * @code{.c} 5419 * // Retrieve the config for the given array. 5420 * tiledb_config_t* config; 5421 * tiledb_array_get_config(ctx, array, config); 5422 * @endcode 5423 * 5424 * @param ctx The TileDB context. 5425 * @param array The array to set the config for. 5426 * @param config Set to the retrieved config. 5427 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5428 */ 5429 TILEDB_EXPORT int32_t tiledb_array_get_config( 5430 tiledb_ctx_t* ctx, tiledb_array_t* array, tiledb_config_t** config); 5431 5432 /** 5433 * Closes a TileDB array. 5434 * 5435 * **Example:** 5436 * 5437 * @code{.c} 5438 * tiledb_array_t* array; 5439 * tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); 5440 * tiledb_array_open(ctx, array, TILEDB_READ); 5441 * tiledb_array_close(ctx, array); 5442 * @endcode 5443 * 5444 * @param ctx The TileDB context. 5445 * @param array The array object to be closed. 5446 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5447 * 5448 * @note If the array object has already been closed, the function has 5449 * no effect. 5450 */ 5451 TILEDB_EXPORT int32_t 5452 tiledb_array_close(tiledb_ctx_t* ctx, tiledb_array_t* array); 5453 5454 /** 5455 * Frees a TileDB array object. 5456 * 5457 * **Example:** 5458 * 5459 * @code{.c} 5460 * tiledb_array_t* array; 5461 * tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); 5462 * tiledb_array_open(ctx, array, TILEDB_READ); 5463 * tiledb_array_close(ctx, array); 5464 * tiledb_array_free(&array); 5465 * @endcode 5466 * 5467 * @param array The array object to be freed. 5468 */ 5469 TILEDB_EXPORT void tiledb_array_free(tiledb_array_t** array); 5470 5471 /** 5472 * Retrieves the schema of an array. 5473 * 5474 * **Example:** 5475 * 5476 * @code{.c} 5477 * tiledb_array_schema_t* array_schema; 5478 * tiledb_array_get_schema(ctx, array, &array_schema); 5479 * @endcode 5480 * 5481 * @param ctx The TileDB context. 5482 * @param array The open array. 5483 * @param array_schema The array schema to be retrieved. 5484 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 5485 * 5486 * @note The user must free the array schema with `tiledb_array_schema_free`. 5487 */ 5488 TILEDB_EXPORT int32_t tiledb_array_get_schema( 5489 tiledb_ctx_t* ctx, 5490 tiledb_array_t* array, 5491 tiledb_array_schema_t** array_schema); 5492 5493 /** 5494 * Retrieves the query type with which the array was opened. 5495 * 5496 * **Example:** 5497 * 5498 * @code{.c} 5499 * tiledb_array_t* array; 5500 * tiledb_array_alloc(ctx, "hdfs:///tiledb_arrays/my_array", &array); 5501 * tiledb_array_open(ctx, array, TILEDB_READ); 5502 * tiledb_query_type_t query_type; 5503 * tiledb_array_get_type(ctx, array, &query_type); 5504 * @endcode 5505 * 5506 * @param ctx The TileDB context. 5507 * @param array The array. 5508 * @param query_type The query type to be retrieved. 5509 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5510 */ 5511 TILEDB_EXPORT int32_t tiledb_array_get_query_type( 5512 tiledb_ctx_t* ctx, tiledb_array_t* array, tiledb_query_type_t* query_type); 5513 5514 /** 5515 * Creates a new TileDB array given an input schema. 5516 * 5517 * **Example:** 5518 * 5519 * @code{.c} 5520 * tiledb_array_create(ctx, "hdfs:///tiledb_arrays/my_array", array_schema); 5521 * @endcode 5522 * 5523 * @param ctx The TileDB context. 5524 * @param array_uri The array name. 5525 * @param array_schema The array schema. 5526 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5527 */ 5528 TILEDB_EXPORT int32_t tiledb_array_create( 5529 tiledb_ctx_t* ctx, 5530 const char* array_uri, 5531 const tiledb_array_schema_t* array_schema); 5532 5533 /** 5534 * Creates a new encrypted TileDB array given an input schema. 5535 * 5536 * Encrypted arrays can only be created through this function. 5537 * 5538 * **Example:** 5539 * 5540 * @code{.c} 5541 * uint8_t key[32] = ...; 5542 * tiledb_array_create_with_key( 5543 * ctx, "hdfs:///tiledb_arrays/my_array", array_schema, 5544 * TILEDB_AES_256_GCM, key, sizeof(key)); 5545 * @endcode 5546 * 5547 * @param ctx The TileDB context. 5548 * @param array_uri The array name. 5549 * @param array_schema The array schema. 5550 * @param encryption_type The encryption type to use. 5551 * @param encryption_key The encryption key to use. 5552 * @param key_length Length in bytes of the encryption key. 5553 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5554 */ 5555 TILEDB_DEPRECATED_EXPORT int32_t tiledb_array_create_with_key( 5556 tiledb_ctx_t* ctx, 5557 const char* array_uri, 5558 const tiledb_array_schema_t* array_schema, 5559 tiledb_encryption_type_t encryption_type, 5560 const void* encryption_key, 5561 uint32_t key_length); 5562 5563 /** 5564 * Depending on the consoliation mode in the config, consolidates either the 5565 * fragment files, fragment metadata files, or array metadata files into a 5566 * single file. 5567 * 5568 * You must first finalize all queries to the array before consolidation can 5569 * begin (as consolidation temporarily acquires an exclusive lock on the array). 5570 * 5571 * **Example:** 5572 * 5573 * @code{.c} 5574 * tiledb_array_consolidate( 5575 * ctx, "hdfs:///tiledb_arrays/my_array", nullptr); 5576 * @endcode 5577 * 5578 * @param ctx The TileDB context. 5579 * @param array_uri The name of the TileDB array whose metadata will 5580 * be consolidated. 5581 * @param config Configuration parameters for the consolidation 5582 * (`nullptr` means default, which will use the config from `ctx`). 5583 * The `sm.consolidation.mode` parameter determines which type of 5584 * consolidation to perform. 5585 * 5586 * @return `TILEDB_OK` on success, and `TILEDB_ERR` on error. 5587 */ 5588 TILEDB_EXPORT int32_t tiledb_array_consolidate( 5589 tiledb_ctx_t* ctx, const char* array_uri, tiledb_config_t* config); 5590 5591 /** 5592 * Depending on the consoliation mode in the config, consolidates either the 5593 * fragment files, fragment metadata files, or array metadata files into a 5594 * single file. 5595 * 5596 * You must first finalize all queries to the array before consolidation can 5597 * begin (as consolidation temporarily acquires an exclusive lock on the array). 5598 * 5599 * **Example:** 5600 * 5601 * @code{.c} 5602 * uint8_t key[32] = ...; 5603 * tiledb_array_consolidate_with_key( 5604 * ctx, "hdfs:///tiledb_arrays/my_array", 5605 * TILEDB_AES_256_GCM, key, sizeof(key), nullptr); 5606 * @endcode 5607 * 5608 * @param ctx The TileDB context. 5609 * @param array_uri The name of the TileDB array to be consolidated. 5610 * @param encryption_type The encryption type to use. 5611 * @param encryption_key The encryption key to use. 5612 * @param key_length Length in bytes of the encryption key. 5613 * @param config Configuration parameters for the consolidation 5614 * (`nullptr` means default, which will use the config from `ctx`). 5615 * The `sm.consolidation.mode` parameter determines which type of 5616 * consolidation to perform. 5617 * 5618 * @return `TILEDB_OK` on success, and `TILEDB_ERR` on error. 5619 */ 5620 TILEDB_DEPRECATED_EXPORT int32_t tiledb_array_consolidate_with_key( 5621 tiledb_ctx_t* ctx, 5622 const char* array_uri, 5623 tiledb_encryption_type_t encryption_type, 5624 const void* encryption_key, 5625 uint32_t key_length, 5626 tiledb_config_t* config); 5627 5628 /** 5629 * Cleans up the array, such as consolidated fragments and array metadata. 5630 * Note that this will coarsen the granularity of time traveling (see docs 5631 * for more information). 5632 * 5633 * **Example:** 5634 * 5635 * @code{.c} 5636 * tiledb_array_vacuum(ctx, "hdfs:///tiledb_arrays/my_array"); 5637 * @endcode 5638 * 5639 * @param ctx The TileDB context. 5640 * @param array_uri The name of the TileDB array to vacuum. 5641 * @param config Configuration parameters for the vacuuming 5642 * (`nullptr` means default, which will use the config from `ctx`). 5643 * @return `TILEDB_OK` on success, and `TILEDB_ERR` on error. 5644 */ 5645 TILEDB_EXPORT int32_t tiledb_array_vacuum( 5646 tiledb_ctx_t* ctx, const char* array_uri, tiledb_config_t* config); 5647 5648 /** 5649 * Retrieves the non-empty domain from an array. This is the union of the 5650 * non-empty domains of the array fragments. 5651 * 5652 * **Example:** 5653 * 5654 * @code{.c} 5655 * uint64_t domain[4]; // Assuming a 2D array, 2 [low, high] pairs 5656 * int32_t is_empty; 5657 * tiledb_array_t* array; 5658 * tiledb_array_alloc(ctx, "my_array", &array); 5659 * tiledb_array_open(ctx, array, TILEDB_READ); 5660 * tiledb_array_get_non_empty_domain(ctx, array, domain, &is_empty); 5661 * @endcode 5662 * 5663 * @param ctx The TileDB context 5664 * @param array The array object (must be opened beforehand). 5665 * @param domain The domain to be retrieved. 5666 * @param is_empty The function sets it to `1` if the non-empty domain is 5667 * empty (i.e., the array does not contain any data yet), and `0` otherwise. 5668 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5669 */ 5670 TILEDB_EXPORT int32_t tiledb_array_get_non_empty_domain( 5671 tiledb_ctx_t* ctx, tiledb_array_t* array, void* domain, int32_t* is_empty); 5672 5673 /** 5674 * Retrieves the non-empty domain from an array for a given dimension index. 5675 * This is the union of the non-empty domains of the array fragments on 5676 * the given dimension. 5677 * 5678 * **Example:** 5679 * 5680 * @code{.c} 5681 * uint64_t domain[2]; 5682 * int32_t is_empty; 5683 * tiledb_array_t* array; 5684 * tiledb_array_alloc(ctx, "my_array", &array); 5685 * tiledb_array_open(ctx, array, TILEDB_READ); 5686 * tiledb_array_get_non_empty_domain_from_index(ctx, array, 0, domain, 5687 * &is_empty); 5688 * @endcode 5689 * 5690 * @param ctx The TileDB context 5691 * @param array The array object (must be opened beforehand). 5692 * @param idx The dimension index, following the order as it was defined 5693 * in the domain of the array schema. 5694 * @param domain The domain to be retrieved. 5695 * @param is_empty The function sets it to `1` if the non-empty domain is 5696 * empty (i.e., the array does not contain any data yet), and `0` otherwise. 5697 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5698 */ 5699 TILEDB_EXPORT int32_t tiledb_array_get_non_empty_domain_from_index( 5700 tiledb_ctx_t* ctx, 5701 tiledb_array_t* array, 5702 uint32_t idx, 5703 void* domain, 5704 int32_t* is_empty); 5705 5706 /** 5707 * Retrieves the non-empty domain from an array for a given dimension name. 5708 * This is the union of the non-empty domains of the array fragments on 5709 * the given dimension. 5710 * 5711 * **Example:** 5712 * 5713 * @code{.c} 5714 * uint64_t domain[2]; 5715 * int32_t is_empty; 5716 * tiledb_array_t* array; 5717 * tiledb_array_alloc(ctx, "my_array", &array); 5718 * tiledb_array_open(ctx, array, TILEDB_READ); 5719 * tiledb_array_get_non_empty_domain_from_name(ctx, array, "d1", domain, 5720 * &is_empty); 5721 * @endcode 5722 * 5723 * @param ctx The TileDB context 5724 * @param array The array object (must be opened beforehand). 5725 * @param name The dimension name. 5726 * @param domain The domain to be retrieved. 5727 * @param is_empty The function sets it to `1` if the non-empty domain is 5728 * empty (i.e., the array does not contain any data yet), and `0` otherwise. 5729 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5730 */ 5731 TILEDB_EXPORT int32_t tiledb_array_get_non_empty_domain_from_name( 5732 tiledb_ctx_t* ctx, 5733 tiledb_array_t* array, 5734 const char* name, 5735 void* domain, 5736 int32_t* is_empty); 5737 5738 /** 5739 * Retrieves the non-empty domain range sizes from an array for a given 5740 * dimension index. This is the union of the non-empty domains of the array 5741 * fragments on the given dimension. Applicable only to var-sized dimensions. 5742 * 5743 * **Example:** 5744 * 5745 * @code{.c} 5746 * int32_t is_empty; 5747 * tiledb_array_t* array; 5748 * tiledb_array_alloc(ctx, "my_array", &array); 5749 * tiledb_array_open(ctx, array, TILEDB_READ); 5750 * uint64_t start_size, end_size; 5751 * tiledb_array_get_non_empty_domain_var_size_from_index( 5752 * ctx, array, 0, &start_size, &end_size, &is_empty); 5753 * // If non-empty domain range is `[aa, dddd]`, then `start_size = 2` 5754 * // and `end_size = 4`. 5755 * @endcode 5756 * 5757 * @param ctx The TileDB context 5758 * @param array The array object (must be opened beforehand). 5759 * @param idx The dimension index, following the order as it was defined 5760 * in the domain of the array schema. 5761 * @param start_size The size in bytes of the start range. 5762 * @param end_size The size in bytes of the end range. 5763 * @param is_empty The function sets it to `1` if the non-empty domain is 5764 * empty (i.e., the array does not contain any data yet), and `0` otherwise. 5765 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5766 */ 5767 TILEDB_EXPORT int32_t tiledb_array_get_non_empty_domain_var_size_from_index( 5768 tiledb_ctx_t* ctx, 5769 tiledb_array_t* array, 5770 uint32_t idx, 5771 uint64_t* start_size, 5772 uint64_t* end_size, 5773 int32_t* is_empty); 5774 5775 /** 5776 * Retrieves the non-empty domain range sizes from an array for a given 5777 * dimension name. This is the union of the non-empty domains of the array 5778 * fragments on the given dimension. Applicable only to var-sized dimensions. 5779 * 5780 * **Example:** 5781 * 5782 * @code{.c} 5783 * int32_t is_empty; 5784 * tiledb_array_t* array; 5785 * tiledb_array_alloc(ctx, "my_array", &array); 5786 * tiledb_array_open(ctx, array, TILEDB_READ); 5787 * uint64_t start_size, end_size; 5788 * tiledb_array_get_non_empty_domain_var_size_from_name( 5789 * ctx, array, "d", &start_size, &end_size, &is_empty); 5790 * // If non-empty domain range is `[aa, dddd]`, then `start_size = 2` 5791 * // and `end_size = 4`. 5792 * @endcode 5793 * 5794 * @param ctx The TileDB context 5795 * @param array The array object (must be opened beforehand). 5796 * @param name The dimension name. 5797 * @param start_size The size in bytes of the start range. 5798 * @param end_size The size in bytes of the end range. 5799 * @param is_empty The function sets it to `1` if the non-empty domain is 5800 * empty (i.e., the array does not contain any data yet), and `0` otherwise. 5801 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5802 */ 5803 TILEDB_EXPORT int32_t tiledb_array_get_non_empty_domain_var_size_from_name( 5804 tiledb_ctx_t* ctx, 5805 tiledb_array_t* array, 5806 const char* name, 5807 uint64_t* start_size, 5808 uint64_t* end_size, 5809 int32_t* is_empty); 5810 5811 /** 5812 * Retrieves the non-empty domain from an array for a given 5813 * dimension index. This is the union of the non-empty domains of the array 5814 * fragments on the given dimension. Applicable only to var-sized dimensions. 5815 * 5816 * **Example:** 5817 * 5818 * @code{.c} 5819 * int32_t is_empty; 5820 * tiledb_array_t* array; 5821 * tiledb_array_alloc(ctx, "my_array", &array); 5822 * tiledb_array_open(ctx, array, TILEDB_READ); 5823 * 5824 * // Get range sizes first 5825 * uint64_t start_size, end_size; 5826 * tiledb_array_get_non_empty_domain_var_size_from_index( 5827 * ctx, array, 0, &start_size, &end_size, &is_empty); 5828 * 5829 * // Get domain 5830 * char start[start_size]; 5831 * char end[end_size]; 5832 * tiledb_array_get_non_empty_domain_var_from_index( 5833 * ctx, array, 0, start, end, &is_empty); 5834 * @endcode 5835 * 5836 * @param ctx The TileDB context 5837 * @param array The array object (must be opened beforehand). 5838 * @param idx The dimension index, following the order as it was defined 5839 * in the domain of the array schema. 5840 * @param start The domain range start to set. 5841 * @param end The domain range end to set. 5842 * @param is_empty The function sets it to `1` if the non-empty domain is 5843 * empty (i.e., the array does not contain any data yet), and `0` otherwise. 5844 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5845 */ 5846 TILEDB_EXPORT int32_t tiledb_array_get_non_empty_domain_var_from_index( 5847 tiledb_ctx_t* ctx, 5848 tiledb_array_t* array, 5849 uint32_t idx, 5850 void* start, 5851 void* end, 5852 int32_t* is_empty); 5853 5854 /** 5855 * Retrieves the non-empty domain from an array for a given 5856 * dimension name. This is the union of the non-empty domains of the array 5857 * fragments on the given dimension. Applicable only to var-sized dimensions. 5858 * 5859 * **Example:** 5860 * 5861 * @code{.c} 5862 * uint64_t domain[2]; 5863 * int32_t is_empty; 5864 * tiledb_array_t* array; 5865 * tiledb_array_alloc(ctx, "my_array", &array); 5866 * tiledb_array_open(ctx, array, TILEDB_READ); 5867 * 5868 * // Get range sizes first 5869 * uint64_t start_size, end_size; 5870 * tiledb_array_get_non_empty_domain_var_size_from_name( 5871 * ctx, array, "d", &start_size, &end_size, &is_empty); 5872 * 5873 * // Get domain 5874 * char start[start_size]; 5875 * char end[end_size]; 5876 * tiledb_array_get_non_empty_domain_var_from_name( 5877 * ctx, array, "d", start, end, &is_empty); 5878 * @endcode 5879 * 5880 * @param ctx The TileDB context 5881 * @param array The array object (must be opened beforehand). 5882 * @param name The dimension name. 5883 * @param start The domain range start to set. 5884 * @param end The domain range end to set. 5885 * @param is_empty The function sets it to `1` if the non-empty domain is 5886 * empty (i.e., the array does not contain any data yet), and `0` otherwise. 5887 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5888 */ 5889 TILEDB_EXPORT int32_t tiledb_array_get_non_empty_domain_var_from_name( 5890 tiledb_ctx_t* ctx, 5891 tiledb_array_t* array, 5892 const char* name, 5893 void* start, 5894 void* end, 5895 int32_t* is_empty); 5896 5897 /** 5898 * Retrieves the URI the array was opened with. It outputs an error 5899 * if the array is not open. 5900 * 5901 * @param ctx The TileDB context. 5902 * @param array The input array. 5903 * @param array_uri The array URI to be retrieved. 5904 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5905 */ 5906 TILEDB_EXPORT int32_t tiledb_array_get_uri( 5907 tiledb_ctx_t* ctx, tiledb_array_t* array, const char** array_uri); 5908 5909 /** 5910 * Retrieves the encryption type the array at the given URI was created with. 5911 * 5912 * @param ctx The TileDB context. 5913 * @param array_uri The array URI. 5914 * @param encryption_type The array encryption type to be retrieved. 5915 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5916 */ 5917 TILEDB_EXPORT int32_t tiledb_array_encryption_type( 5918 tiledb_ctx_t* ctx, 5919 const char* array_uri, 5920 tiledb_encryption_type_t* encryption_type); 5921 5922 /** 5923 * It puts a metadata key-value item to an open array. The array must 5924 * be opened in WRITE mode, otherwise the function will error out. 5925 * 5926 * @param ctx The TileDB context. 5927 * @param array An array opened in WRITE mode. 5928 * @param key The key of the metadata item to be added. UTF-8 encodings 5929 * are acceptable. 5930 * @param value_type The datatype of the value. 5931 * @param value_num The value may consist of more than one items of the 5932 * same datatype. This argument indicates the number of items in the 5933 * value component of the metadata. 5934 * @param value The metadata value in binary form. 5935 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5936 * 5937 * @note The writes will take effect only upon closing the array. 5938 */ 5939 TILEDB_EXPORT int32_t tiledb_array_put_metadata( 5940 tiledb_ctx_t* ctx, 5941 tiledb_array_t* array, 5942 const char* key, 5943 tiledb_datatype_t value_type, 5944 uint32_t value_num, 5945 const void* value); 5946 5947 /** 5948 * It deletes a metadata key-value item from an open array. The array must 5949 * be opened in WRITE mode, otherwise the function will error out. 5950 * 5951 * @param ctx The TileDB context. 5952 * @param array An array opened in WRITE mode. 5953 * @param key The key of the metadata item to be deleted. 5954 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5955 * 5956 * @note The writes will take effect only upon closing the array. 5957 * 5958 * @note If the key does not exist, this will take no effect 5959 * (i.e., the function will not error out). 5960 */ 5961 TILEDB_EXPORT int32_t tiledb_array_delete_metadata( 5962 tiledb_ctx_t* ctx, tiledb_array_t* array, const char* key); 5963 5964 /** 5965 * It gets a metadata key-value item from an open array. The array must 5966 * be opened in READ mode, otherwise the function will error out. 5967 * 5968 * @param ctx The TileDB context. 5969 * @param array An array opened in READ mode. 5970 * @param key The key of the metadata item to be retrieved. UTF-8 encodings 5971 * are acceptable. 5972 * @param value_type The datatype of the value. 5973 * @param value_num The value may consist of more than one items of the 5974 * same datatype. This argument indicates the number of items in the 5975 * value component of the metadata. Keys with empty values are indicated 5976 * by value_num == 1 and value == NULL. 5977 * @param value The metadata value in binary form. 5978 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5979 * 5980 * @note If the key does not exist, then `value` will be NULL. 5981 */ 5982 TILEDB_EXPORT int32_t tiledb_array_get_metadata( 5983 tiledb_ctx_t* ctx, 5984 tiledb_array_t* array, 5985 const char* key, 5986 tiledb_datatype_t* value_type, 5987 uint32_t* value_num, 5988 const void** value); 5989 5990 /** 5991 * It gets then number of metadata items in an open array. The array must 5992 * be opened in READ mode, otherwise the function will error out. 5993 * 5994 * @param ctx The TileDB context. 5995 * @param array An array opened in READ mode. 5996 * @param num The number of metadata items to be retrieved. 5997 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 5998 */ 5999 TILEDB_EXPORT int32_t tiledb_array_get_metadata_num( 6000 tiledb_ctx_t* ctx, tiledb_array_t* array, uint64_t* num); 6001 6002 /** 6003 * It gets a metadata item from an open array using an index. 6004 * The array must be opened in READ mode, otherwise the function will 6005 * error out. 6006 * 6007 * @param ctx The TileDB context. 6008 * @param array An array opened in READ mode. 6009 * @param index The index used to get the metadata. 6010 * @param key The metadata key. 6011 * @param key_len The metadata key length. 6012 * @param value_type The datatype of the value. 6013 * @param value_num The value may consist of more than one items of the 6014 * same datatype. This argument indicates the number of items in the 6015 * value component of the metadata. 6016 * @param value The metadata value in binary form. 6017 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6018 */ 6019 TILEDB_EXPORT int32_t tiledb_array_get_metadata_from_index( 6020 tiledb_ctx_t* ctx, 6021 tiledb_array_t* array, 6022 uint64_t index, 6023 const char** key, 6024 uint32_t* key_len, 6025 tiledb_datatype_t* value_type, 6026 uint32_t* value_num, 6027 const void** value); 6028 6029 /** 6030 * Checks whether a key exists in metadata from an open array. The array must 6031 * be opened in READ mode, otherwise the function will error out. 6032 * 6033 * @param ctx The TileDB context. 6034 * @param array An array opened in READ mode. 6035 * @param key The key to be checked. UTF-8 encoding are acceptable. 6036 * @param value_type The datatype of the value, if any. 6037 * @param has_key Set to `1` if the metadata with given key exists, else `0`. 6038 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6039 * 6040 * @note If the key does not exist, then `value` will be NULL. 6041 */ 6042 TILEDB_EXPORT int32_t tiledb_array_has_metadata_key( 6043 tiledb_ctx_t* ctx, 6044 tiledb_array_t* array, 6045 const char* key, 6046 tiledb_datatype_t* value_type, 6047 int32_t* has_key); 6048 6049 /** 6050 * Consolidates the array metadata into a single array metadata file. 6051 * 6052 * You must first finalize all queries to the array before consolidation can 6053 * begin (as consolidation temporarily acquires an exclusive lock on the array). 6054 * 6055 * **Example:** 6056 * 6057 * @code{.c} 6058 * tiledb_array_consolidate_metadata( 6059 * ctx, "hdfs:///tiledb_arrays/my_array", nullptr); 6060 * @endcode 6061 * 6062 * @param ctx The TileDB context. 6063 * @param array_uri The name of the TileDB array whose metadata will 6064 * be consolidated. 6065 * @param config Configuration parameters for the consolidation 6066 * (`nullptr` means default, which will use the config from `ctx`). 6067 * @return `TILEDB_OK` on success, and `TILEDB_ERR` on error. 6068 */ 6069 TILEDB_DEPRECATED_EXPORT int32_t tiledb_array_consolidate_metadata( 6070 tiledb_ctx_t* ctx, const char* array_uri, tiledb_config_t* config); 6071 6072 /** 6073 * Consolidates the array metadata of an encrypted array into a single file. 6074 * 6075 * You must first finalize all queries to the array before consolidation can 6076 * begin (as consolidation temporarily acquires an exclusive lock on the array). 6077 * 6078 * **Example:** 6079 * 6080 * @code{.c} 6081 * uint8_t key[32] = ...; 6082 * tiledb_array_consolidate_metadata_with_key( 6083 * ctx, "hdfs:///tiledb_arrays/my_array", 6084 * TILEDB_AES_256_GCM, key, sizeof(key), nullptr); 6085 * @endcode 6086 * 6087 * @param ctx The TileDB context. 6088 * @param array_uri The name of the TileDB array to be consolidated. 6089 * @param encryption_type The encryption type to use. 6090 * @param encryption_key The encryption key to use. 6091 * @param key_length Length in bytes of the encryption key. 6092 * @param config Configuration parameters for the consolidation 6093 * (`nullptr` means default, which will use the config from `ctx`). 6094 * 6095 * @return `TILEDB_OK` on success, and `TILEDB_ERR` on error. 6096 */ 6097 TILEDB_DEPRECATED_EXPORT int32_t tiledb_array_consolidate_metadata_with_key( 6098 tiledb_ctx_t* ctx, 6099 const char* array_uri, 6100 tiledb_encryption_type_t encryption_type, 6101 const void* encryption_key, 6102 uint32_t key_length, 6103 tiledb_config_t* config); 6104 6105 /* ********************************* */ 6106 /* OBJECT MANAGEMENT */ 6107 /* ********************************* */ 6108 6109 /** 6110 * Returns the TileDB object type for a given resource path. 6111 * 6112 * **Example:** 6113 * 6114 * @code{.c} 6115 * tiledb_object_t type; 6116 * tiledb_object_type(ctx, "arrays/my_array", &type); 6117 * @endcode 6118 * 6119 * @param ctx The TileDB context. 6120 * @param path The URI path to the TileDB resource. 6121 * @param type The type to be retrieved. 6122 * @return `TILEDB_OK` on success, `TILEDB_ERR` on error. 6123 */ 6124 TILEDB_EXPORT int32_t 6125 tiledb_object_type(tiledb_ctx_t* ctx, const char* path, tiledb_object_t* type); 6126 6127 /** 6128 * Deletes a TileDB resource (group, array, key-value). 6129 * 6130 * **Example:** 6131 * 6132 * @code{.c} 6133 * tiledb_object_remove(ctx, "arrays/my_array"); 6134 * @endcode 6135 * 6136 * @param ctx The TileDB context. 6137 * @param path The URI path to the tiledb resource. 6138 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6139 */ 6140 TILEDB_EXPORT int32_t tiledb_object_remove(tiledb_ctx_t* ctx, const char* path); 6141 6142 /** 6143 * Moves a TileDB resource (group, array, key-value). 6144 * 6145 * **Example:** 6146 * 6147 * @code{.c} 6148 * tiledb_object_move(ctx, "arrays/my_array", "arrays/my_array_2"); 6149 * @endcode 6150 * 6151 * @param ctx The TileDB context. 6152 * @param old_path The old TileDB directory. 6153 * @param new_path The new TileDB directory. 6154 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6155 */ 6156 TILEDB_EXPORT int32_t tiledb_object_move( 6157 tiledb_ctx_t* ctx, const char* old_path, const char* new_path); 6158 6159 /** 6160 * Walks (iterates) over the TileDB objects contained in *path*. The traversal 6161 * is done recursively in the order defined by the user. The user provides 6162 * a callback function which is applied on each of the visited TileDB objects. 6163 * The iteration continues for as long the callback returns non-zero, and stops 6164 * when the callback returns 0. Note that this function ignores any object 6165 * (e.g., file or directory) that is not TileDB-related. 6166 * 6167 * **Example:** 6168 * 6169 * @code{.c} 6170 * tiledb_object_walk(ctx, "arrays", TILEDB_PREORDER, NULL, NULL); 6171 * @endcode 6172 * 6173 * @param ctx The TileDB context. 6174 * @param path The path in which the traversal will occur. 6175 * @param order The order of the recursive traversal (e.g., pre-order or 6176 * post-order. 6177 * @param callback The callback function to be applied on every visited object. 6178 * The callback should return `0` if the iteration must stop, and `1` 6179 * if the iteration must continue. It takes as input the currently visited 6180 * path, the type of that path (e.g., array or group), and the data 6181 * provided by the user for the callback. The callback returns `-1` upon 6182 * error. Note that `path` in the callback will be an **absolute** path. 6183 * @param data The data passed in the callback as the last argument. 6184 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6185 */ 6186 TILEDB_EXPORT int32_t tiledb_object_walk( 6187 tiledb_ctx_t* ctx, 6188 const char* path, 6189 tiledb_walk_order_t order, 6190 int32_t (*callback)(const char*, tiledb_object_t, void*), 6191 void* data); 6192 6193 /** 6194 * Similar to `tiledb_walk`, but now the function visits only the children of 6195 * `path` (i.e., it does not recursively continue to the children directories). 6196 * 6197 * **Example:** 6198 * 6199 * @code{.c} 6200 * tiledb_object_ls(ctx, "arrays", NULL, NULL); 6201 * @endcode 6202 * 6203 * @param ctx The TileDB context. 6204 * @param path The path in which the traversal will occur. 6205 * @param callback The callback function to be applied on every visited object. 6206 * The callback should return `0` if the iteration must stop, and `1` 6207 * if the iteration must continue. It takes as input the currently visited 6208 * path, the type of that path (e.g., array or group), and the data 6209 * provided by the user for the callback. The callback returns `-1` upon 6210 * error. Note that `path` in the callback will be an **absolute** path. 6211 * @param data The data passed in the callback as the last argument. 6212 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6213 */ 6214 TILEDB_EXPORT int32_t tiledb_object_ls( 6215 tiledb_ctx_t* ctx, 6216 const char* path, 6217 int32_t (*callback)(const char*, tiledb_object_t, void*), 6218 void* data); 6219 6220 /* ****************************** */ 6221 /* VIRTUAL FILESYSTEM */ 6222 /* ****************************** */ 6223 6224 /** 6225 * Creates a virtual filesystem object. 6226 * 6227 * **Example:** 6228 * 6229 * @code{.c} 6230 * tiledb_vfs_t* vfs; 6231 * tiledb_vfs_alloc(ctx, config, &vfs); 6232 * @endcode 6233 * 6234 * @param ctx The TileDB context. 6235 * @param vfs The virtual filesystem object to be created. 6236 * @param config Configuration parameters. 6237 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 6238 */ 6239 TILEDB_EXPORT int32_t tiledb_vfs_alloc( 6240 tiledb_ctx_t* ctx, tiledb_config_t* config, tiledb_vfs_t** vfs); 6241 6242 /** 6243 * Frees a virtual filesystem object. 6244 * 6245 * **Example:** 6246 * 6247 * @code{.c} 6248 * tiledb_vfs_free(&vfs); 6249 * @endcode 6250 * 6251 * @param vfs The virtual filesystem object to be freed. 6252 */ 6253 TILEDB_EXPORT void tiledb_vfs_free(tiledb_vfs_t** vfs); 6254 6255 /** 6256 * Retrieves the config from a VFS context. 6257 * 6258 * **Example:** 6259 * 6260 * @code{.c} 6261 * tiledb_config_t* config; 6262 * tiledb_vfs_get_config(ctx, vfs, &config); 6263 * // Make sure to free the retrieved config 6264 * @endcode 6265 * 6266 * @param ctx The TileDB context. 6267 * @param vfs The VFS object. 6268 * @param config The config to be retrieved. 6269 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 6270 */ 6271 TILEDB_EXPORT int32_t tiledb_vfs_get_config( 6272 tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, tiledb_config_t** config); 6273 6274 /** 6275 * Creates an object-store bucket. 6276 * 6277 * **Example:** 6278 * 6279 * @code{.c} 6280 * tiledb_vfs_create_bucket(ctx, vfs, "s3://tiledb"); 6281 * @endcode 6282 * 6283 * @param ctx The TileDB context. 6284 * @param vfs The virtual filesystem object. 6285 * @param uri The URI of the bucket to be created. 6286 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6287 */ 6288 TILEDB_EXPORT int32_t 6289 tiledb_vfs_create_bucket(tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri); 6290 6291 /** 6292 * Deletes an object-store bucket. 6293 * 6294 * **Example:** 6295 * 6296 * @code{.c} 6297 * tiledb_vfs_delete_bucket(ctx, vfs, "s3://tiledb"); 6298 * @endcode 6299 * 6300 * @param ctx The TileDB context. 6301 * @param vfs The virtual filesystem object. 6302 * @param uri The URI of the bucket to be deleted. 6303 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6304 */ 6305 TILEDB_EXPORT int32_t 6306 tiledb_vfs_remove_bucket(tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri); 6307 6308 /** 6309 * Deletes the contents of an object-store bucket. 6310 * 6311 * **Example:** 6312 * 6313 * @code{.c} 6314 * tiledb_vfs_empty_bucket(ctx, vfs, "s3://tiledb"); 6315 * @endcode 6316 * 6317 * @param ctx The TileDB context. 6318 * @param vfs The virtual filesystem object. 6319 * @param uri The URI of the bucket to be emptied. 6320 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6321 */ 6322 TILEDB_EXPORT int32_t 6323 tiledb_vfs_empty_bucket(tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri); 6324 6325 /** 6326 * Checks if an object-store bucket is empty. 6327 * 6328 * **Example:** 6329 * 6330 * @code{.c} 6331 * int32_t is_empty; 6332 * tiledb_vfs_is_empty_bucket(ctx, vfs, "s3://tiledb", &empty); 6333 * @endcode 6334 * 6335 * @param ctx The TileDB context. 6336 * @param vfs The virtual filesystem object. 6337 * @param uri The URI of the bucket. 6338 * @param is_empty Sets it to `1` if the input bucket is empty, 6339 * and `0` otherwise. 6340 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6341 */ 6342 TILEDB_EXPORT int32_t tiledb_vfs_is_empty_bucket( 6343 tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri, int32_t* is_empty); 6344 6345 /** 6346 * Checks if an object-store bucket exists. 6347 * 6348 * **Example:** 6349 * 6350 * @code{.c} 6351 * int32_t exists; 6352 * tiledb_vfs_is_bucket(ctx, vfs, "s3://tiledb", &exists); 6353 * @endcode 6354 * 6355 * @param ctx The TileDB context. 6356 * @param vfs The virtual filesystem object. 6357 * @param uri The URI of the bucket. 6358 * @param is_bucket Sets it to `1` if the input URI is a bucket, and `0` 6359 * otherwise. 6360 * @return TILEDB_OK for success and TILEDB_ERR for error. 6361 */ 6362 TILEDB_EXPORT int32_t tiledb_vfs_is_bucket( 6363 tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri, int32_t* is_bucket); 6364 6365 /** 6366 * Creates a directory. 6367 * 6368 * - On S3, this is a noop. 6369 * - On all other backends, if the directory exists, the function 6370 * just succeeds without doing anything. 6371 * 6372 * **Example:** 6373 * 6374 * @code{.c} 6375 * tiledb_vfs_create_dir(ctx, vfs, "hdfs:///temp/my_dir"); 6376 * @endcode 6377 * 6378 * @param ctx The TileDB context. 6379 * @param vfs The virtual filesystem object. 6380 * @param uri The URI of the directory to be created. 6381 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6382 */ 6383 TILEDB_EXPORT int32_t 6384 tiledb_vfs_create_dir(tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri); 6385 6386 /** 6387 * Checks if a directory exists. 6388 * 6389 * **Example:** 6390 * 6391 * @code{.c} 6392 * int32_t exists; 6393 * tiledb_vfs_is_dir(ctx, vfs, "hdfs:///temp/my_dir", &exists); 6394 * @endcode 6395 * 6396 * @param ctx The TileDB context. 6397 * @param vfs The virtual filesystem object. 6398 * @param uri The URI of the directory. 6399 * @param is_dir Sets it to `1` if the directory exists and `0` 6400 * otherwise. 6401 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6402 * 6403 * @note For S3, this function will return `true` if there is an object 6404 * with prefix `uri/` (TileDB will append `/` internally to `uri` 6405 * only if it does not exist), and `false` othewise. 6406 */ 6407 TILEDB_EXPORT int32_t tiledb_vfs_is_dir( 6408 tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri, int32_t* is_dir); 6409 6410 /** 6411 * Removes a directory (recursively). 6412 * 6413 * **Example:** 6414 * 6415 * @code{.c} 6416 * tiledb_vfs_remove_dir(ctx, vfs, "hdfs:///temp/my_dir"); 6417 * @endcode 6418 * 6419 * @param ctx The TileDB context. 6420 * @param vfs The virtual filesystem object. 6421 * @param uri The uri of the directory to be removed 6422 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6423 */ 6424 TILEDB_EXPORT int32_t 6425 tiledb_vfs_remove_dir(tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri); 6426 6427 /** 6428 * Checks if a file exists. 6429 * 6430 * **Example:** 6431 * 6432 * @code{.c} 6433 * int32_t exists; 6434 * tiledb_vfs_is_file(ctx, vfs, "hdfs:///temp/my_file", &is_file); 6435 * @endcode 6436 * 6437 * @param ctx The TileDB context. 6438 * @param vfs The virtual filesystem object. 6439 * @param uri The URI of the file. 6440 * @param is_file Sets it to `1` if the file exists and `0` otherwise. 6441 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6442 */ 6443 TILEDB_EXPORT int32_t tiledb_vfs_is_file( 6444 tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri, int32_t* is_file); 6445 6446 /** 6447 * Deletes a file. 6448 * 6449 * **Example:** 6450 * 6451 * @code{.c} 6452 * tiledb_vfs_remove_file(ctx, vfs, "hdfs:///temp/my_file"); 6453 * @endcode 6454 * 6455 * @param ctx The TileDB context. 6456 * @param vfs The virtual filesystem object. 6457 * @param uri The URI of the file. 6458 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6459 */ 6460 TILEDB_EXPORT int32_t 6461 tiledb_vfs_remove_file(tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri); 6462 6463 /** 6464 * Retrieves the size of a directory. This function is **recursive**, i.e., 6465 * it will consider all files in the directory tree rooted at `uri`. 6466 * 6467 * **Example:** 6468 * 6469 * @code{.c} 6470 * uint64_t dir_size; 6471 * tiledb_vfs_dir_size(ctx, vfs, "hdfs:///temp/my_dir", &dir_size); 6472 * @endcode 6473 * 6474 * @param ctx The TileDB context. 6475 * @param vfs The virtual filesystem object. 6476 * @param uri The URI of the directory. 6477 * @param size The directory size to be retrieved. 6478 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6479 */ 6480 TILEDB_EXPORT int32_t tiledb_vfs_dir_size( 6481 tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri, uint64_t* size); 6482 6483 /** 6484 * Retrieves the size of a file. 6485 * 6486 * **Example:** 6487 * 6488 * @code{.c} 6489 * uint64_t file_size; 6490 * tiledb_vfs_file_size(ctx, vfs, "hdfs:///temp/my_file", &file_size); 6491 * @endcode 6492 * 6493 * @param ctx The TileDB context. 6494 * @param vfs The virtual filesystem object. 6495 * @param uri The URI of the file. 6496 * @param size The file size to be retrieved. 6497 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6498 */ 6499 TILEDB_EXPORT int32_t tiledb_vfs_file_size( 6500 tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri, uint64_t* size); 6501 6502 /** 6503 * Renames a file. If the destination file exists, it will be overwritten. 6504 * 6505 * **Example:** 6506 * 6507 * @code{.c} 6508 * tiledb_vfs_move_file( 6509 * ctx, vfs, "hdfs:///temp/my_file", "hdfs::///new_file"); 6510 * @endcode 6511 * 6512 * @param ctx The TileDB context. 6513 * @param vfs The virtual filesystem object. 6514 * @param old_uri The old URI. 6515 * @param new_uri The new URI. 6516 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6517 */ 6518 TILEDB_EXPORT int32_t tiledb_vfs_move_file( 6519 tiledb_ctx_t* ctx, 6520 tiledb_vfs_t* vfs, 6521 const char* old_uri, 6522 const char* new_uri); 6523 6524 /** 6525 * Renames a directory. 6526 * 6527 * **Example:** 6528 * 6529 * @code{.c} 6530 * tiledb_vfs_move_dir(ctx, vfs, "hdfs:///temp/my_dir", "hdfs::///new_dir"); 6531 * @endcode 6532 * 6533 * @param ctx The TileDB context. 6534 * @param vfs The virtual filesystem object. 6535 * @param old_uri The old URI. 6536 * @param new_uri The new URI. 6537 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6538 */ 6539 TILEDB_EXPORT int32_t tiledb_vfs_move_dir( 6540 tiledb_ctx_t* ctx, 6541 tiledb_vfs_t* vfs, 6542 const char* old_uri, 6543 const char* new_uri); 6544 6545 /** 6546 * Copies a file. If the destination file exists, it will be overwritten. 6547 * 6548 * **Example:** 6549 * 6550 * @code{.c} 6551 * tiledb_vfs_copy_file( 6552 * ctx, vfs, "hdfs:///temp/my_file", "hdfs::///new_file"); 6553 * @endcode 6554 * 6555 * @param ctx The TileDB context. 6556 * @param vfs The virtual filesystem object. 6557 * @param old_uri The old URI. 6558 * @param new_uri The new URI. 6559 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6560 */ 6561 TILEDB_EXPORT int32_t tiledb_vfs_copy_file( 6562 tiledb_ctx_t* ctx, 6563 tiledb_vfs_t* vfs, 6564 const char* old_uri, 6565 const char* new_uri); 6566 6567 /** 6568 * Copies a directory. If the destination directory exists, it will be 6569 * overwritten. 6570 * 6571 * **Example:** 6572 * 6573 * @code{.c} 6574 * tiledb_vfs_copy_dir( 6575 * ctx, vfs, "hdfs:///temp/my_dir", "hdfs::///new_dir"); 6576 * @endcode 6577 * 6578 * @param ctx The TileDB context. 6579 * @param vfs The virtual filesystem object. 6580 * @param old_uri The old URI. 6581 * @param new_uri The new URI. 6582 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6583 */ 6584 TILEDB_EXPORT int32_t tiledb_vfs_copy_dir( 6585 tiledb_ctx_t* ctx, 6586 tiledb_vfs_t* vfs, 6587 const char* old_uri, 6588 const char* new_uri); 6589 6590 /** 6591 * Prepares a file for reading/writing. 6592 * 6593 * **Example:** 6594 * 6595 * @code{.c} 6596 * tiledb_vfs_fh_t* fh; 6597 * tiledb_vfs_open(ctx, vfs, "some_file", TILEDB_VFS_READ, &fh); 6598 * // Make sure to close and delete the created file handle 6599 * @endcode 6600 * 6601 * @param ctx The TileDB context. 6602 * @param vfs The virtual filesystem object. 6603 * @param uri The URI of the file. 6604 * @param mode The mode in which the file is opened: 6605 * - `TILEDB_VFS_READ`: 6606 * The file is opened for reading. An error is returned if the file 6607 * does not exist. 6608 * - `TILEDB_VFS_WRITE`: 6609 * The file is opened for writing. If the file exists, it will be 6610 * overwritten. 6611 * - `TILEDB_VFS_APPEND`: 6612 * The file is opened for writing. If the file exists, the write 6613 * will start from the end of the file. Note that S3 does not 6614 * support this operation and, thus, an error will be thrown in 6615 * that case. 6616 * @param fh The file handle that is created. This will be used in 6617 * `tiledb_vfs_read`, `tiledb_vfs_write` and `tiledb_vfs_sync`. 6618 * @return `TILEDB_OK` for success and `TILEDB_ERR` or `TILEDB_OOM` for error. 6619 * 6620 * @note If the file is closed after being opened, without having 6621 * written any data to it, the file will not be created. If you 6622 * wish to create an empty file, use `tiledb_vfs_touch` 6623 * instead. 6624 */ 6625 TILEDB_EXPORT int32_t tiledb_vfs_open( 6626 tiledb_ctx_t* ctx, 6627 tiledb_vfs_t* vfs, 6628 const char* uri, 6629 tiledb_vfs_mode_t mode, 6630 tiledb_vfs_fh_t** fh); 6631 6632 /** 6633 * Closes a file. This is flushes the buffered data into the file 6634 * when the file was opened in write (or append) mode. It is particularly 6635 * important to be called after S3 writes, as otherwise the writes will 6636 * not take effect. 6637 * 6638 * **Example:** 6639 * 6640 * @code{.c} 6641 * tiledb_vfs_close(ctx, vfs, fh); 6642 * @endcode 6643 * 6644 * @param ctx The TileDB context. 6645 * @param fh The file handle. 6646 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6647 */ 6648 TILEDB_EXPORT int32_t tiledb_vfs_close(tiledb_ctx_t* ctx, tiledb_vfs_fh_t* fh); 6649 6650 /** 6651 * Reads from a file. 6652 * 6653 * **Example:** 6654 * 6655 * @code{.c} 6656 * char buffer[10000]; 6657 * tiledb_vfs_read(ctx, fh, 100, buffer, 10000); 6658 * @endcode 6659 * 6660 * @param ctx The TileDB context. 6661 * @param fh The URI file handle. 6662 * @param offset The offset in the file where the read begins. 6663 * @param buffer The buffer to read into. 6664 * @param nbytes Number of bytes to read. 6665 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6666 */ 6667 TILEDB_EXPORT int32_t tiledb_vfs_read( 6668 tiledb_ctx_t* ctx, 6669 tiledb_vfs_fh_t* fh, 6670 uint64_t offset, 6671 void* buffer, 6672 uint64_t nbytes); 6673 6674 /** 6675 * Writes the contents of a buffer into a file. Note that this 6676 * function only **appends** data at the end of the file. If the 6677 * file does not exist, it will be created. 6678 * 6679 * **Example:** 6680 * 6681 * @code{.c} 6682 * const char* msg = "This will be written to the file"; 6683 * tiledb_vfs_write(ctx, fh, buffer, strlen(msg)); 6684 * @endcode 6685 * 6686 * @param ctx The TileDB context. 6687 * @param fh The URI file handle. 6688 * @param buffer The buffer to write from. 6689 * @param nbytes Number of bytes to write. 6690 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6691 */ 6692 TILEDB_EXPORT int32_t tiledb_vfs_write( 6693 tiledb_ctx_t* ctx, 6694 tiledb_vfs_fh_t* fh, 6695 const void* buffer, 6696 uint64_t nbytes); 6697 6698 /** 6699 * Syncs (flushes) a file. 6700 * 6701 * **Example:** 6702 * 6703 * @code{.c} 6704 * tiledb_vfs_sync(ctx, fh); 6705 * @endcode 6706 * 6707 * @param ctx The TileDB context. 6708 * @param fh The URI file handle. 6709 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6710 * 6711 * @note This has no effect for S3. 6712 */ 6713 TILEDB_EXPORT int32_t tiledb_vfs_sync(tiledb_ctx_t* ctx, tiledb_vfs_fh_t* fh); 6714 6715 /** 6716 * The function visits only the children of `path` (i.e., it does not 6717 * recursively continue to the children directories) and applies the `callback` 6718 * function using the input `data`. 6719 * 6720 * **Example:** 6721 * 6722 * @code{.c} 6723 * tiledb_vfs_ls(ctx, vfs, "my_dir", NULL, NULL); 6724 * @endcode 6725 * 6726 * @param ctx The TileDB context. 6727 * @param vfs The virtual filesystem object. 6728 * @param path The path in which the traversal will occur. 6729 * @param callback The callback function to be applied on every visited object. 6730 * The callback should return `0` if the iteration must stop, and `1` 6731 * if the iteration must continue. It takes as input the currently visited 6732 * path, the type of that path (e.g., array or group), and the data 6733 * provided by the user for the callback. The callback returns `-1` upon 6734 * error. Note that `path` in the callback will be an **absolute** path. 6735 * @param data The data passed in the callback as the last argument. 6736 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6737 */ 6738 TILEDB_EXPORT int32_t tiledb_vfs_ls( 6739 tiledb_ctx_t* ctx, 6740 tiledb_vfs_t* vfs, 6741 const char* path, 6742 int32_t (*callback)(const char*, void*), 6743 void* data); 6744 6745 /** 6746 * Frees a file handle. 6747 * 6748 * **Example:** 6749 * 6750 * @code{.c} 6751 * tiledb_vfs_fh_free(&fh); 6752 * @endcode 6753 * 6754 * @param fh The URI file handle. 6755 */ 6756 TILEDB_EXPORT void tiledb_vfs_fh_free(tiledb_vfs_fh_t** fh); 6757 6758 /** 6759 * Checks if a file handle is closed. 6760 * 6761 * **Example:** 6762 * 6763 * @code{.c} 6764 * int32_t is_closed; 6765 * tiledb_vfs_fh_is_closed(ctx, fh, &is_closed); 6766 * @endcode 6767 * 6768 * @param ctx The TileDB context. 6769 * @param fh The URI file handle. 6770 * @param is_closed Set to `1` if the file handle is closed, and `0` otherwise. 6771 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6772 */ 6773 TILEDB_EXPORT int32_t tiledb_vfs_fh_is_closed( 6774 tiledb_ctx_t* ctx, tiledb_vfs_fh_t* fh, int32_t* is_closed); 6775 6776 /** 6777 * Touches a file, i.e., creates a new empty file. 6778 * 6779 * **Example:** 6780 * 6781 * @code{.c} 6782 * tiledb_vfs_touch(ctx, vfs, "my_empty_file"); 6783 * @endcode 6784 * 6785 * @param ctx The TileDB context. 6786 * @param vfs The virtual filesystem object. 6787 * @param uri The URI of the file to be created. 6788 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6789 */ 6790 TILEDB_EXPORT int32_t 6791 tiledb_vfs_touch(tiledb_ctx_t* ctx, tiledb_vfs_t* vfs, const char* uri); 6792 6793 /* ****************************** */ 6794 /* URI */ 6795 /* ****************************** */ 6796 6797 /** 6798 * Converts the given file URI to a null-terminated platform-native file path. 6799 * 6800 * **Example:** 6801 * 6802 * @code{.c} 6803 * char path[TILEDB_MAX_PATH]; 6804 * uint32_t length = TILEDB_MAX_PATH; // Must be set to non-zero 6805 * tiledb_uri_to_path(ctx, "file:///my_array", path, &length); 6806 * // This will set "my_array" to `path` 6807 * @endcode 6808 * 6809 * @param ctx The TileDB context. 6810 * @param uri The URI to be converted. 6811 * @param path_out The buffer where the converted path string is stored. 6812 * @param path_length The length of the path buffer. On return, this is set to 6813 * the length of the converted path string, or 0 on error. 6814 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6815 * 6816 * @note The path_out buffer must be allocated according to the platform's 6817 * maximum path length (e.g. `TILEDB_MAX_PATH), which includes space for the 6818 * terminating null character. 6819 */ 6820 TILEDB_EXPORT int32_t tiledb_uri_to_path( 6821 tiledb_ctx_t* ctx, const char* uri, char* path_out, uint32_t* path_length); 6822 6823 /* ****************************** */ 6824 /* Stats */ 6825 /* ****************************** */ 6826 6827 /** 6828 * Enable internal statistics gathering. 6829 * 6830 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6831 */ 6832 TILEDB_EXPORT int32_t tiledb_stats_enable(void); 6833 6834 /** 6835 * Disable internal statistics gathering. 6836 * 6837 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6838 */ 6839 TILEDB_EXPORT int32_t tiledb_stats_disable(void); 6840 6841 /** 6842 * Reset all internal statistics counters to 0. 6843 * 6844 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6845 */ 6846 TILEDB_EXPORT int32_t tiledb_stats_reset(void); 6847 6848 /** 6849 * Dump all internal statistics counters to some output (e.g., 6850 * file or stdout). 6851 * 6852 * @param out The output. 6853 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6854 */ 6855 TILEDB_EXPORT int32_t tiledb_stats_dump(FILE* out); 6856 6857 /** 6858 * Dump all internal statistics counters to an output string. The caller is 6859 * responsible for freeing the resulting string. 6860 * 6861 * **Example:** 6862 * 6863 * @code{.c} 6864 * char *stats_str; 6865 * tiledb_stats_dump_str(&stats_str); 6866 * // ... 6867 * tiledb_stats_free_str(&stats_str); 6868 * @endcode 6869 * 6870 * @param out Will be set to point to an allocated string containing the stats. 6871 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6872 */ 6873 TILEDB_EXPORT int32_t tiledb_stats_dump_str(char** out); 6874 6875 /** 6876 * Dump all raw internal statistics counters to some output (e.g., 6877 * file or stdout) as a JSON. 6878 * 6879 * @param out The output. 6880 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6881 */ 6882 TILEDB_EXPORT int32_t tiledb_stats_raw_dump(FILE* out); 6883 6884 /** 6885 * Dump all raw internal statistics counters to a JSON-formatted output string. 6886 * The caller is responsible for freeing the resulting string. 6887 * 6888 * **Example:** 6889 * 6890 * @code{.c} 6891 * char *stats_str; 6892 * tiledb_stats_raw_dump_str(&stats_str); 6893 * // ... 6894 * tiledb_stats_raw_free_str(&stats_str); 6895 * @endcode 6896 * 6897 * @param out Will be set to point to an allocated string containing the stats. 6898 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6899 */ 6900 TILEDB_EXPORT int32_t tiledb_stats_raw_dump_str(char** out); 6901 6902 /** 6903 * 6904 * Free the memory associated with a previously dumped stats string. 6905 * 6906 * @param out Pointer to a previously allocated stats string. 6907 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6908 */ 6909 TILEDB_EXPORT int32_t tiledb_stats_free_str(char** out); 6910 6911 /* ****************************** */ 6912 /* Heap Profiler */ 6913 /* ****************************** */ 6914 6915 /** 6916 * Enable heap profiling. 6917 * 6918 * @param file_name_prefix If empty or null, stats are dumped 6919 * to stdout. If non-empty, this specifies the file_name prefix to 6920 * write to. For example, value "tiledb_mem_stats" will write 6921 * to "tiledb_mem_stats__1611170501", where the postfix is 6922 * determined by the current epoch. 6923 * @param dump_interval_ms If non-zero, this spawns a dedicated 6924 * thread to dump on this time interval. 6925 * @param dump_interval_bytes If non-zero, a dump will occur when 6926 * the total number of lifetime allocated bytes is increased by 6927 * more than this amount. 6928 * @param dump_threshold_bytes If non-zero, labeled allocations with 6929 * a number of bytes lower than this threshold will not be reported 6930 * in the dump. 6931 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6932 */ 6933 TILEDB_EXPORT int32_t tiledb_heap_profiler_enable( 6934 const char* file_name_prefix, 6935 uint64_t dump_interval_ms, 6936 uint64_t dump_interval_bytes, 6937 uint64_t dump_threshold_bytes); 6938 6939 /* ****************************** */ 6940 /* FRAGMENT INFO */ 6941 /* ****************************** */ 6942 6943 /** 6944 * Creates a fragment info object for a given array, and fetches all 6945 * the fragment information for that array. 6946 * 6947 * **Example:** 6948 * 6949 * @code{.c} 6950 * tiledb_fragment_info* fragment_info; 6951 * tiledb_fragment_info_alloc(ctx, "array_uri", &fragment_info); 6952 * @endcode 6953 * 6954 * @param ctx The TileDB context. 6955 * @param array_uri The array URI. 6956 * @param fragment_info The fragment info object to be created and populated. 6957 * @return `TILEDB_OK` for success and `TILEDB_OOM` or `TILEDB_ERR` for error. 6958 */ 6959 TILEDB_EXPORT int32_t tiledb_fragment_info_alloc( 6960 tiledb_ctx_t* ctx, 6961 const char* array_uri, 6962 tiledb_fragment_info_t** fragment_info); 6963 6964 /** 6965 * Frees a fragment info object. 6966 * 6967 * **Example:** 6968 * 6969 * @code{.c} 6970 * tiledb_fragment_info_free(&fragment_info); 6971 * @endcode 6972 * 6973 * @param fragment_info The fragment info object to be freed. 6974 */ 6975 TILEDB_EXPORT void tiledb_fragment_info_free( 6976 tiledb_fragment_info_t** fragment_info); 6977 6978 /** 6979 * Loads the fragment info. 6980 * 6981 * **Example:** 6982 * 6983 * @code{.c} 6984 * tiledb_fragment_info_load(ctx, fragment_info); 6985 * @endcode 6986 * 6987 * @param ctx The TileDB context. 6988 * @param fragment_info The fragment info object. 6989 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 6990 */ 6991 TILEDB_EXPORT int32_t tiledb_fragment_info_load( 6992 tiledb_ctx_t* ctx, tiledb_fragment_info_t* fragment_info); 6993 6994 /** 6995 * Loads the fragment info from an encrypted array. 6996 * 6997 * **Example:** 6998 * 6999 * @code{.c} 7000 * tiledb_fragment_info_load_with_key( 7001 * ctx, fragment_info, TILEDB_AES_256_GCM, key, sizeof(key)); 7002 * @endcode 7003 * 7004 * @param ctx The TileDB context. 7005 * @param fragment_info The fragment info object. 7006 * @param encryption_type The encryption type to use. 7007 * @param encryption_key The encryption key to use. 7008 * @param key_length Length in bytes of the encryption key. 7009 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7010 */ 7011 TILEDB_DEPRECATED_EXPORT int32_t tiledb_fragment_info_load_with_key( 7012 tiledb_ctx_t* ctx, 7013 tiledb_fragment_info_t* fragment_info, 7014 tiledb_encryption_type_t encryption_type, 7015 const void* encryption_key, 7016 uint32_t key_length); 7017 7018 /** 7019 * Gets the number of fragments. 7020 * 7021 * **Example:** 7022 * 7023 * @code{.c} 7024 * uint32_t fragment_num; 7025 * tiledb_fragment_info_get_fragment_num(ctx, fragment_info, &fragment_num); 7026 * @endcode 7027 * 7028 * @param ctx The TileDB context. 7029 * @param fragment_info The fragment info object. 7030 * @param fragment_num The number of fragments to retrieve. 7031 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7032 */ 7033 TILEDB_EXPORT int32_t tiledb_fragment_info_get_fragment_num( 7034 tiledb_ctx_t* ctx, 7035 tiledb_fragment_info_t* fragment_info, 7036 uint32_t* fragment_num); 7037 7038 /** 7039 * Gets a fragment URI. 7040 * 7041 * **Example:** 7042 * 7043 * @code{.c} 7044 * const char* uri; 7045 * tiledb_fragment_info_get_fragment_uri(ctx, fragment_info, 1, &uri); 7046 * @endcode 7047 * 7048 * @param ctx The TileDB context. 7049 * @param fragment_info The fragment info object. 7050 * @param fid The index of the fragment of interest. 7051 * @param uri The fragment URI to be retrieved. 7052 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7053 */ 7054 TILEDB_EXPORT int32_t tiledb_fragment_info_get_fragment_uri( 7055 tiledb_ctx_t* ctx, 7056 tiledb_fragment_info_t* fragment_info, 7057 uint32_t fid, 7058 const char** uri); 7059 7060 /** 7061 * Gets the fragment size in bytes. 7062 * 7063 * **Example:** 7064 * 7065 * @code{.c} 7066 * uint64_t size; 7067 * tiledb_fragment_info_get_fragment_size(ctx, fragment_info, 1, &size); 7068 * @endcode 7069 * 7070 * @param ctx The TileDB context. 7071 * @param fragment_info The fragment info object. 7072 * @param fid The index of the fragment of interest. 7073 * @param size The fragment size to be retrieved. 7074 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7075 */ 7076 TILEDB_EXPORT int32_t tiledb_fragment_info_get_fragment_size( 7077 tiledb_ctx_t* ctx, 7078 tiledb_fragment_info_t* fragment_info, 7079 uint32_t fid, 7080 uint64_t* size); 7081 7082 /** 7083 * Checks if a fragment is dense. 7084 * 7085 * **Example:** 7086 * 7087 * @code{.c} 7088 * int32_t dense; 7089 * tiledb_fragment_info_get_dense(ctx, fragment_info, 1, &dense); 7090 * @endcode 7091 * 7092 * @param ctx The TileDB context. 7093 * @param fragment_info The fragment info object. 7094 * @param fid The index of the fragment of interest. 7095 * @param dense `1` if the fragment is dense. 7096 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7097 */ 7098 TILEDB_EXPORT int32_t tiledb_fragment_info_get_dense( 7099 tiledb_ctx_t* ctx, 7100 tiledb_fragment_info_t* fragment_info, 7101 uint32_t fid, 7102 int32_t* dense); 7103 7104 /** 7105 * Checks if a fragment is sparse. 7106 * 7107 * **Example:** 7108 * 7109 * @code{.c} 7110 * int32_t sparse; 7111 * tiledb_fragment_info_get_sparse(ctx, fragment_info, 1, &sparse); 7112 * @endcode 7113 * 7114 * @param ctx The TileDB context. 7115 * @param fragment_info The fragment info object. 7116 * @param fid The index of the fragment of interest. 7117 * @param sparse `1` if the fragment is sparse. 7118 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7119 */ 7120 TILEDB_EXPORT int32_t tiledb_fragment_info_get_sparse( 7121 tiledb_ctx_t* ctx, 7122 tiledb_fragment_info_t* fragment_info, 7123 uint32_t fid, 7124 int32_t* sparse); 7125 7126 /** 7127 * Gets the timestamp range of a fragment. 7128 * 7129 * **Example:** 7130 * 7131 * @code{.c} 7132 * uint64_t start, end; 7133 * tiledb_fragment_info_get_timestamp_range(ctx, fragment_info, 1, &start, 7134 * &end); 7135 * @endcode 7136 * 7137 * @param ctx The TileDB context. 7138 * @param fragment_info The fragment info object. 7139 * @param fid The index of the fragment of interest. 7140 * @param start The start of the timestamp range to be retrieved. 7141 * @param end The end of the timestamp range to be retrieved. 7142 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7143 */ 7144 TILEDB_EXPORT int32_t tiledb_fragment_info_get_timestamp_range( 7145 tiledb_ctx_t* ctx, 7146 tiledb_fragment_info_t* fragment_info, 7147 uint32_t fid, 7148 uint64_t* start, 7149 uint64_t* end); 7150 7151 /** 7152 * Retrieves the non-empty domain from a given fragment for a given 7153 * dimension index. 7154 * 7155 * **Example:** 7156 * 7157 * @code{.c} 7158 * uint64_t domain[2]; 7159 * tiledb_fragment_info_get_non_empty_domain_from_index( 7160 * ctx, fragment_info, 0, 0, domain); 7161 * @endcode 7162 * 7163 * @param ctx The TileDB context 7164 * @param fragment_info The fragment info object. 7165 * @param fid The index of the fragment of interest. 7166 * @param did The dimension index, following the order as it was defined 7167 * in the domain of the array schema. 7168 * @param domain The domain to be retrieved. 7169 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7170 */ 7171 TILEDB_EXPORT int32_t tiledb_fragment_info_get_non_empty_domain_from_index( 7172 tiledb_ctx_t* ctx, 7173 tiledb_fragment_info_t* fragment_info, 7174 uint32_t fid, 7175 uint32_t did, 7176 void* domain); 7177 7178 /** 7179 * Retrieves the non-empty domain from a given fragment for a given 7180 * dimension name. 7181 * 7182 * **Example:** 7183 * 7184 * @code{.c} 7185 * uint64_t domain[2]; 7186 * tiledb_fragment_info_get_non_empty_domain_from_name( 7187 * ctx, fragment_info, 0, "d1", domain); 7188 * @endcode 7189 * 7190 * @param ctx The TileDB context 7191 * @param fragment_info The fragment info object. 7192 * @param fid The index of the fragment of interest. 7193 * @param dim_name The dimension name. 7194 * @param domain The domain to be retrieved. 7195 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7196 */ 7197 TILEDB_EXPORT int32_t tiledb_fragment_info_get_non_empty_domain_from_name( 7198 tiledb_ctx_t* ctx, 7199 tiledb_fragment_info_t* fragment_info, 7200 uint32_t fid, 7201 const char* dim_name, 7202 void* domain); 7203 7204 /** 7205 * Retrieves the non-empty domain range sizes from a fragment for a given 7206 * dimension index. Applicable to var-sized dimensions. 7207 * 7208 * **Example:** 7209 * 7210 * @code{.c} 7211 * uint64_t start_size, end_size; 7212 * tiledb_fragment_info_get_non_empty_domain_var_size_from_index( 7213 * ctx, fragment_info, 0, &start_size, &end_size); 7214 * // If non-empty domain range is `[aa, dddd]`, then `start_size = 2` 7215 * // and `end_size = 4`. 7216 * @endcode 7217 * 7218 * @param ctx The TileDB context 7219 * @param fragment_info The fragment information object. 7220 * @param fid The fragment index. 7221 * @param did The dimension index, following the order as it was defined 7222 * in the domain of the array schema. 7223 * @param start_size The size in bytes of the start range. 7224 * @param end_size The size in bytes of the end range. 7225 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7226 */ 7227 TILEDB_EXPORT int32_t 7228 tiledb_fragment_info_get_non_empty_domain_var_size_from_index( 7229 tiledb_ctx_t* ctx, 7230 tiledb_fragment_info_t* fragment_info, 7231 uint32_t fid, 7232 uint32_t did, 7233 uint64_t* start_size, 7234 uint64_t* end_size); 7235 7236 /** 7237 * Retrieves the non-empty domain range sizes from a fragment for a given 7238 * dimension name. Applicable to var-sized dimensions. 7239 * 7240 * **Example:** 7241 * 7242 * @code{.c} 7243 * uint64_t start_size, end_size; 7244 * tiledb_fragment_info_get_non_empty_domain_var_size_from_name( 7245 * ctx, fragment_info, "d", &start_size, &end_size); 7246 * // If non-empty domain range is `[aa, dddd]`, then `start_size = 2` 7247 * // and `end_size = 4`. 7248 * @endcode 7249 * 7250 * @param ctx The TileDB context 7251 * @param fragment_info The fragment information object. 7252 * @param fid The fragment index. 7253 * @param dim_name The dimension name. 7254 * @param start_size The size in bytes of the start range. 7255 * @param end_size The size in bytes of the end range. 7256 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7257 */ 7258 TILEDB_EXPORT int32_t 7259 tiledb_fragment_info_get_non_empty_domain_var_size_from_name( 7260 tiledb_ctx_t* ctx, 7261 tiledb_fragment_info_t* fragment_info, 7262 uint32_t fid, 7263 const char* dim_name, 7264 uint64_t* start_size, 7265 uint64_t* end_size); 7266 7267 /** 7268 * Retrieves the non-empty domain from a fragment for a given 7269 * dimension index. Applicable to var-sized dimensions. 7270 * 7271 * **Example:** 7272 * 7273 * @code{.c} 7274 * 7275 * // Get range sizes first 7276 * uint64_t start_size, end_size; 7277 * tiledb_fragment_info_get_non_empty_domain_var_size_from_index( 7278 * ctx, fragment_info, 0, 0, &start_size, &end_size); 7279 * 7280 * // Get domain 7281 * char start[start_size]; 7282 * char end[end_size]; 7283 * tiledb_fragment_info_get_non_empty_domain_var_from_index( 7284 * ctx, fragment_info, 0, 0, start, end); 7285 * @endcode 7286 * 7287 * @param ctx The TileDB context 7288 * @param fragment_info The fragment info object. 7289 * @param fid The fragment index. 7290 * @param did The dimension index, following the order as it was defined 7291 * in the domain of the array schema. 7292 * @param start The domain range start to set. 7293 * @param end The domain range end to set. 7294 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7295 */ 7296 TILEDB_EXPORT int32_t tiledb_fragment_info_get_non_empty_domain_var_from_index( 7297 tiledb_ctx_t* ctx, 7298 tiledb_fragment_info_t* fragment_info, 7299 uint32_t fid, 7300 uint32_t did, 7301 void* start, 7302 void* end); 7303 7304 /** 7305 * Retrieves the non-empty domain from a fragment for a given dimension name. 7306 * Applicable to var-sized dimensions. 7307 * 7308 * **Example:** 7309 * 7310 * @code{.c} 7311 * 7312 * // Get range sizes first 7313 * uint64_t start_size, end_size; 7314 * tiledb_fragment_info_get_non_empty_domain_var_size_from_name( 7315 * ctx, fragment_info, 0, "d", &start_size, &end_size); 7316 * 7317 * // Get domain 7318 * char start[start_size]; 7319 * char end[end_size]; 7320 * tiledb_fragment_info_get_non_empty_domain_var_from_name( 7321 * ctx, fragment_info, 0, "d", start, end); 7322 * @endcode 7323 * 7324 * @param ctx The TileDB context 7325 * @param fragment_info The fragment info object. 7326 * @param fid The fragment index. 7327 * @param dim_name The dimension name. 7328 * @param start The domain range start to set. 7329 * @param end The domain range end to set. 7330 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7331 */ 7332 TILEDB_EXPORT int32_t tiledb_fragment_info_get_non_empty_domain_var_from_name( 7333 tiledb_ctx_t* ctx, 7334 tiledb_fragment_info_t* fragment_info, 7335 uint32_t fid, 7336 const char* dim_name, 7337 void* start, 7338 void* end); 7339 7340 /** 7341 * Retrieves the number of MBRs from the fragment. 7342 * 7343 * In the case of sparse fragments, this is the number of physical tiles. 7344 * 7345 * Dense fragments do not contain MBRs. 7346 * 7347 * **Example:** 7348 * 7349 * @code{.c} 7350 * uint64_t mbr_num; 7351 * tiledb_fragment_info_get_mbr_num(ctx, fragment_info, 0, &mbr_num); 7352 * @endcode 7353 * 7354 * @param ctx The TileDB context 7355 * @param fragment_info The fragment info object. 7356 * @param fid The index of the fragment of interest. 7357 * @param mbrs_num The number of MBRs to be retrieved. 7358 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7359 */ 7360 TILEDB_EXPORT int32_t tiledb_fragment_info_get_mbr_num( 7361 tiledb_ctx_t* ctx, 7362 tiledb_fragment_info_t* fragment_info, 7363 uint32_t fid, 7364 uint64_t* mbr_num); 7365 7366 /** 7367 * Retrieves the MBR from a given fragment for a given dimension index. 7368 * 7369 * **Example:** 7370 * 7371 * @code{.c} 7372 * uint64_t mbr[2]; 7373 * tiledb_fragment_info_get_mbr_from_index(ctx, fragment_info, 0, 0, 0, mbr); 7374 * @endcode 7375 * 7376 * @param ctx The TileDB context 7377 * @param fragment_info The fragment info object. 7378 * @param fid The index of the fragment of interest. 7379 * @param mid The mbr of the fragment of interest. 7380 * @param did The dimension index, following the order as it was defined 7381 * in the domain of the array schema. 7382 * @param mbr The mbr to be retrieved. 7383 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7384 */ 7385 TILEDB_EXPORT int32_t tiledb_fragment_info_get_mbr_from_index( 7386 tiledb_ctx_t* ctx, 7387 tiledb_fragment_info_t* fragment_info, 7388 uint32_t fid, 7389 uint32_t mid, 7390 uint32_t did, 7391 void* mbr); 7392 7393 /** 7394 * Retrieves the MBR from a given fragment for a given dimension name. 7395 * 7396 * **Example:** 7397 * 7398 * @code{.c} 7399 * uint64_t mbr[2]; 7400 * tiledb_fragment_info_get_mbr_from_name(ctx, fragment_info, 0, 0, "d1", mbr); 7401 * @endcode 7402 * 7403 * @param ctx The TileDB context 7404 * @param fragment_info The fragment info object. 7405 * @param fid The index of the fragment of interest. 7406 * @param mid The mbr of the fragment of interest. 7407 * @param dim_name The dimension name. 7408 * @param mbr The mbr to be retrieved. 7409 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7410 */ 7411 TILEDB_EXPORT int32_t tiledb_fragment_info_get_mbr_from_name( 7412 tiledb_ctx_t* ctx, 7413 tiledb_fragment_info_t* fragment_info, 7414 uint32_t fid, 7415 uint32_t mid, 7416 const char* dim_name, 7417 void* mbr); 7418 7419 /** 7420 * Retrieves the MBR sizes from a fragment for a given dimension index. 7421 * Applicable to var-sized dimensions. 7422 * 7423 * **Example:** 7424 * 7425 * @code{.c} 7426 * uint64_t start_size, end_size; 7427 * tiledb_fragment_info_get_mbr_var_size_from_index( 7428 * ctx, fragment_info, 0, 0, 0, &start_size, &end_size); 7429 * // If non-empty domain range is `[aa, dddd]`, then `start_size = 2` 7430 * // and `end_size = 4`. 7431 * @endcode 7432 * 7433 * @param ctx The TileDB context 7434 * @param fragment_info The fragment information object. 7435 * @param fid The fragment index. 7436 @param mid The mbr of the fragment of interest. 7437 * @param did The dimension index, following the order as it was defined 7438 * in the domain of the array schema. 7439 * @param start_size The size in bytes of the start range. 7440 * @param end_size The size in bytes of the end range. 7441 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7442 */ 7443 TILEDB_EXPORT int32_t tiledb_fragment_info_get_mbr_var_size_from_index( 7444 tiledb_ctx_t* ctx, 7445 tiledb_fragment_info_t* fragment_info, 7446 uint32_t fid, 7447 uint32_t mid, 7448 uint32_t did, 7449 uint64_t* start_size, 7450 uint64_t* end_size); 7451 7452 /** 7453 * Retrieves the MBR range sizes from a fragment for a given dimension name. 7454 * Applicable to var-sized dimensions. 7455 * 7456 * **Example:** 7457 * 7458 * @code{.c} 7459 * uint64_t start_size, end_size; 7460 * tiledb_fragment_info_get_mbr_var_size_from_name( 7461 * ctx, fragment_info, 0, 0, "d1", &start_size, &end_size); 7462 * // If non-empty domain range is `[aa, dddd]`, then `start_size = 2` 7463 * // and `end_size = 4`. 7464 * @endcode 7465 * 7466 * @param ctx The TileDB context 7467 * @param fragment_info The fragment information object. 7468 * @param fid The fragment index. 7469 * @param mid The mbr of the fragment of interest. 7470 * @param dim_name The dimension name. 7471 * @param start_size The size in bytes of the start range. 7472 * @param end_size The size in bytes of the end range. 7473 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7474 */ 7475 TILEDB_EXPORT int32_t tiledb_fragment_info_get_mbr_var_size_from_name( 7476 tiledb_ctx_t* ctx, 7477 tiledb_fragment_info_t* fragment_info, 7478 uint32_t fid, 7479 uint32_t mid, 7480 const char* dim_name, 7481 uint64_t* start_size, 7482 uint64_t* end_size); 7483 7484 /** 7485 * Retrieves the MBR from a fragment for a given dimension index. 7486 * Applicable to var-sized dimensions. 7487 * 7488 * **Example:** 7489 * 7490 * @code{.c} 7491 * 7492 * // Get range sizes first 7493 * uint64_t start_size, end_size; 7494 * tiledb_fragment_info_get_mbr_var_size_from_index( 7495 * ctx, fragment_info, 0, 0, 0, &start_size, &end_size); 7496 * 7497 * // Get domain 7498 * char start[start_size]; 7499 * char end[end_size]; 7500 * tiledb_fragment_info_get_mbr_var_from_index( 7501 * ctx, fragment_info, 0, 0, 0, start, end); 7502 * @endcode 7503 * 7504 * @param ctx The TileDB context 7505 * @param fragment_info The fragment info object. 7506 * @param fid The fragment index. 7507 * @param mid The mbr of the fragment of interest. 7508 * @param did The dimension index, following the order as it was defined 7509 * in the domain of the array schema. 7510 * @param start The domain range start to set. 7511 * @param end The domain range end to set. 7512 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7513 */ 7514 TILEDB_EXPORT int32_t tiledb_fragment_info_get_mbr_var_from_index( 7515 tiledb_ctx_t* ctx, 7516 tiledb_fragment_info_t* fragment_info, 7517 uint32_t fid, 7518 uint32_t mid, 7519 uint32_t did, 7520 void* start, 7521 void* end); 7522 7523 /** 7524 * Retrieves the MBR from a fragment for a given dimension name. 7525 * Applicable to var-sized dimensions. 7526 * 7527 * **Example:** 7528 * 7529 * @code{.c} 7530 * 7531 * // Get range sizes first 7532 * uint64_t start_size, end_size; 7533 * tiledb_fragment_info_get_mbr_var_size_from_name( 7534 * ctx, fragment_info, 0, 0, "d1", &start_size, &end_size); 7535 * 7536 * // Get domain 7537 * char start[start_size]; 7538 * char end[end_size]; 7539 * tiledb_fragment_info_get_mbr_var_from_name( 7540 * ctx, fragment_info, 0, 0, "d1", start, end); 7541 * @endcode 7542 * 7543 * @param ctx The TileDB context 7544 * @param fragment_info The fragment info object. 7545 * @param fid The fragment index. 7546 * @param mid The mbr of the fragment of interest. 7547 * @param dim_name The dimension name. 7548 * @param start The domain range start to set. 7549 * @param end The domain range end to set. 7550 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7551 */ 7552 TILEDB_EXPORT int32_t tiledb_fragment_info_get_mbr_var_from_name( 7553 tiledb_ctx_t* ctx, 7554 tiledb_fragment_info_t* fragment_info, 7555 uint32_t fid, 7556 uint32_t mid, 7557 const char* dim_name, 7558 void* start, 7559 void* end); 7560 7561 /** 7562 * Retrieves the number of cells written to the fragment by the user. 7563 * 7564 * In the case of sparse fragments, this is the number of non-empty 7565 * cells in the fragment. 7566 * 7567 * In the case of dense fragments, TileDB may add fill 7568 * values to populate partially populated tiles. Those fill values 7569 * are counted in the returned number of cells. In other words, 7570 * the cell number is derived from the number of *integral* tiles 7571 * written in the file. 7572 * 7573 * **Example:** 7574 * 7575 * @code{.c} 7576 * uint64_t cell_num; 7577 * tiledb_fragment_info_get_cell_num(ctx, fragment_info, 0, &cell_num); 7578 * @endcode 7579 * 7580 * @param ctx The TileDB context 7581 * @param fragment_info The fragment info object. 7582 * @param fid The index of the fragment of interest. 7583 * @param cell_num The number of cells to be retrieved. 7584 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7585 */ 7586 TILEDB_EXPORT int32_t tiledb_fragment_info_get_cell_num( 7587 tiledb_ctx_t* ctx, 7588 tiledb_fragment_info_t* fragment_info, 7589 uint32_t fid, 7590 uint64_t* cell_num); 7591 7592 /** 7593 * Retrieves the format version of a fragment. 7594 * 7595 * **Example:** 7596 * 7597 * @code{.c} 7598 * uint32_t version; 7599 * tiledb_fragment_info_get_version(ctx, fragment_info, 0, &version); 7600 * @endcode 7601 * 7602 * @param ctx The TileDB context 7603 * @param fragment_info The fragment info object. 7604 * @param fid The index of the fragment of interest. 7605 * @param version The format version to be retrieved. 7606 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7607 */ 7608 TILEDB_EXPORT int32_t tiledb_fragment_info_get_version( 7609 tiledb_ctx_t* ctx, 7610 tiledb_fragment_info_t* fragment_info, 7611 uint32_t fid, 7612 uint32_t* version); 7613 7614 /** 7615 * Checks if a fragment has consolidated metadata. 7616 * 7617 * **Example:** 7618 * 7619 * @code{.c} 7620 * int32_t has; 7621 * tiledb_fragment_info_has_consolidated_metadata(ctx, fragment_info, 0, &has); 7622 * @endcode 7623 * 7624 * @param ctx The TileDB context 7625 * @param fragment_info The fragment info object. 7626 * @param fid The index of the fragment of interest. 7627 * @param has True if the fragment has consolidated metadata. 7628 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7629 */ 7630 TILEDB_EXPORT int32_t tiledb_fragment_info_has_consolidated_metadata( 7631 tiledb_ctx_t* ctx, 7632 tiledb_fragment_info_t* fragment_info, 7633 uint32_t fid, 7634 int32_t* has); 7635 7636 /** 7637 * Gets the number of fragments with unconsolidated metadata. 7638 * 7639 * **Example:** 7640 * 7641 * @code{.c} 7642 * uint32_t unconsolidated; 7643 * tiledb_fragment_info_get_unconsolidated_metadata_num(ctx, fragment_info, 7644 * &unconsolidated); 7645 * @endcode 7646 * 7647 * @param ctx The TileDB context 7648 * @param fragment_info The fragment info object. 7649 * @param unconsolidated The number of fragments with unconsolidated metadata. 7650 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7651 */ 7652 TILEDB_EXPORT int32_t tiledb_fragment_info_get_unconsolidated_metadata_num( 7653 tiledb_ctx_t* ctx, 7654 tiledb_fragment_info_t* fragment_info, 7655 uint32_t* unconsolidated); 7656 7657 /** 7658 * Gets the number of fragments to vacuum. 7659 * 7660 * **Example:** 7661 * 7662 * @code{.c} 7663 * uint32_t to_vacuum_num; 7664 * tiledb_fragment_info_get_to_vacuum_num(ctx, fragment_info, &to_vacuum_num); 7665 * @endcode 7666 * 7667 * @param ctx The TileDB context 7668 * @param fragment_info The fragment info object. 7669 * @param to_vacuum_num The number of fragments to vacuum. 7670 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7671 */ 7672 TILEDB_EXPORT int32_t tiledb_fragment_info_get_to_vacuum_num( 7673 tiledb_ctx_t* ctx, 7674 tiledb_fragment_info_t* fragment_info, 7675 uint32_t* to_vacuum_num); 7676 7677 /** 7678 * Gets the URI of the fragment to vacuum with the given index. 7679 * 7680 * **Example:** 7681 * 7682 * @code{.c} 7683 * const char* uri; 7684 * tiledb_fragment_info_get_to_vacuum_uri(ctx, fragment_info, 1, &uri); 7685 * @endcode 7686 * 7687 * @param ctx The TileDB context. 7688 * @param fragment_info The fragment info object. 7689 * @param fid The index of the fragment to vacuum of interest. 7690 * @param uri The fragment URI to be retrieved. 7691 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7692 */ 7693 TILEDB_EXPORT int32_t tiledb_fragment_info_get_to_vacuum_uri( 7694 tiledb_ctx_t* ctx, 7695 tiledb_fragment_info_t* fragment_info, 7696 uint32_t fid, 7697 const char** uri); 7698 7699 /** 7700 * Retrieves the array schema name a fragment. 7701 * 7702 * **Example:** 7703 * 7704 * @code{.c} 7705 * tiledb_array_schema_t* array_schema; 7706 * tiledb_fragment_info_get_array_schema(ctx, fragment_info, 0, &array_schema); 7707 * @endcode 7708 * 7709 * @param ctx The TileDB context 7710 * @param fragment_info The fragment info object. 7711 * @param fid The index of the fragment of interest. 7712 * @param array_schema The array schema to be retrieved. 7713 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7714 */ 7715 TILEDB_EXPORT int32_t tiledb_fragment_info_get_array_schema( 7716 tiledb_ctx_t* ctx, 7717 tiledb_fragment_info_t* fragment_info, 7718 uint32_t fid, 7719 tiledb_array_schema_t** array_schema); 7720 7721 /** 7722 * Get the fragment info schema name. 7723 * 7724 * **Example:** 7725 * 7726 * @code{.c} 7727 * char* name; 7728 * tiledb_fragment_info_schema_name(ctx, fragment_info, &schema_name); 7729 * @endcode 7730 * 7731 * @param ctx The TileDB context. 7732 * @param fragment_info The fragment info object. 7733 * @param name The schema name. 7734 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7735 */ 7736 TILEDB_EXPORT int32_t tiledb_fragment_info_get_array_schema_name( 7737 tiledb_ctx_t* ctx, 7738 tiledb_fragment_info_t* fragment_info, 7739 uint32_t fid, 7740 const char** schema_name); 7741 7742 /** 7743 * Dumps the fragment info in ASCII format in the selected output. 7744 * 7745 * **Example:** 7746 * 7747 * The following prints the fragment info dump in standard output. 7748 * 7749 * @code{.c} 7750 * tiledb_fragment_info_dump(ctx, fragment_info, stdout); 7751 * @endcode 7752 * 7753 * @param ctx The TileDB context. 7754 * @param fragment_info The fragment info object. 7755 * @param out The output. 7756 * @return `TILEDB_OK` for success and `TILEDB_ERR` for error. 7757 */ 7758 TILEDB_EXPORT int32_t tiledb_fragment_info_dump( 7759 tiledb_ctx_t* ctx, const tiledb_fragment_info_t* fragment_info, FILE* out); 7760 7761 #ifdef __cplusplus 7762 } 7763 #endif 7764 7765 #endif // TILEDB_H 7766