From dd3927814761c1bf2585570828c9477e0990a3e0 Mon Sep 17 00:00:00 2001 From: Shaun M Reed Date: Wed, 2 Aug 2023 11:46:03 -0400 Subject: [PATCH] Add C APIs for dimension label REST support. (#4072) Adds two C APIs required for dimension label REST support to allocate and set read buffers on remote queries. For dimension label REST support, we will need to add the following C APIs to core, which will then be wrapped in TileDB-Go. tiledb_array_schema_get_dimension_label_num tiledb_array_schema_get_dimension_label_from_index TileDB-Cloud-REST can then use these APIs via TileDB-Go for read buffer allocation similar to how attribute and dimension buffers are currently allocated in [allocateQueryBuffers](https://github.com/TileDB-Inc/TileDB-Cloud-REST/blob/master/internal/query/v2/query.go#L167). --- TYPE: FEATURE DESC: Adds C APIs for dimension label REST support. --- test/src/test-capi-dimension-label.cc | 34 ++++++++---- tiledb/sm/c_api/tiledb_dimension_label.cc | 35 ++++++++++++ .../tiledb_dimension_label_experimental.h | 54 +++++++++++++++++++ 3 files changed, 114 insertions(+), 9 deletions(-) diff --git a/test/src/test-capi-dimension-label.cc b/test/src/test-capi-dimension-label.cc index 75f127852f0e..9d1fa3150e13 100644 --- a/test/src/test-capi-dimension-label.cc +++ b/test/src/test-capi-dimension-label.cc @@ -92,13 +92,27 @@ TEST_CASE_METHOD( // Check array schema and number of dimension labels. require_tiledb_ok(tiledb_array_schema_check(ctx, array_schema)); - auto dim_label_num = array_schema->array_schema_->dim_label_num(); + uint64_t dim_label_num = 0; + require_tiledb_ok(tiledb_array_schema_get_dimension_label_num( + ctx, array_schema, &dim_label_num)); REQUIRE(dim_label_num == 1); - // Check the dimension label properies. - tiledb_dimension_label_t* dim_label; - require_tiledb_ok(tiledb_array_schema_get_dimension_label_from_name( - ctx, array_schema, "label", &dim_label)); + tiledb_dimension_label_t* dim_label{nullptr}; + SECTION("get dimension label from index -") { + require_tiledb_ok(tiledb_array_schema_get_dimension_label_from_index( + ctx, array_schema, 0, &dim_label)); + } + SECTION("get dimension label from name -") { + require_tiledb_ok(tiledb_array_schema_get_dimension_label_from_name( + ctx, array_schema, "label", &dim_label)); + } + + const char* dim_label_name; + require_tiledb_ok( + tiledb_dimension_label_get_name(ctx, dim_label, &dim_label_name)); + REQUIRE(!strcmp(dim_label_name, "label")); + + // Check the dimension label properties. uint32_t label_cell_val_num; check_tiledb_ok(tiledb_dimension_label_get_label_cell_val_num( ctx, dim_label, &label_cell_val_num)); @@ -130,9 +144,9 @@ TEST_CASE_METHOD( tiledb_array_schema_load(ctx, array_name.c_str(), &loaded_array_schema)); // Check the array schema has the expected dimension label. - auto loaded_dim_label_num = - loaded_array_schema->array_schema_->dim_label_num(); - CHECK(loaded_dim_label_num == 1); + require_tiledb_ok(tiledb_array_schema_get_dimension_label_num( + ctx, loaded_array_schema, &dim_label_num)); + CHECK(dim_label_num == 1); int32_t has_label; check_tiledb_ok(tiledb_array_schema_has_dimension_label( ctx, loaded_array_schema, "label", &has_label)); @@ -234,7 +248,9 @@ TEST_CASE_METHOD( // Check array schema and number of dimension labels. require_tiledb_ok(tiledb_array_schema_check(ctx, array_schema)); - auto dim_label_num = array_schema->array_schema_->dim_label_num(); + uint64_t dim_label_num = 0; + require_tiledb_ok(tiledb_array_schema_get_dimension_label_num( + ctx, array_schema, &dim_label_num)); REQUIRE(dim_label_num == 1); // Create array diff --git a/tiledb/sm/c_api/tiledb_dimension_label.cc b/tiledb/sm/c_api/tiledb_dimension_label.cc index a40cc22759b5..5db966e77e25 100644 --- a/tiledb/sm/c_api/tiledb_dimension_label.cc +++ b/tiledb/sm/c_api/tiledb_dimension_label.cc @@ -109,6 +109,23 @@ capi_return_t tiledb_array_schema_set_dimension_label_tile_extent( return TILEDB_OK; } +capi_return_t tiledb_array_schema_get_dimension_label_num( + tiledb_array_schema_t* array_schema, uint64_t* dim_label_num) { + *dim_label_num = array_schema->array_schema_->dim_label_num(); + return TILEDB_OK; +} + +capi_return_t tiledb_array_schema_get_dimension_label_from_index( + tiledb_array_schema_t* array_schema, + uint64_t dim_label_index, + tiledb_dimension_label_t** dim_label) { + tiledb::api::ensure_output_pointer_is_valid(dim_label); + *dim_label = tiledb_dimension_label_t::make_handle( + array_schema->array_schema_->array_uri(), + array_schema->array_schema_->dimension_label(dim_label_index)); + return TILEDB_OK; +} + capi_return_t tiledb_subarray_add_label_range( tiledb_subarray_t* subarray, const char* label_name, @@ -244,6 +261,24 @@ capi_return_t tiledb_array_schema_set_dimension_label_tile_extent( ctx, array_schema, label_name, type, tile_extent); } +capi_return_t tiledb_array_schema_get_dimension_label_num( + tiledb_ctx_t* ctx, + tiledb_array_schema_t* array_schema, + uint64_t* dim_label_num) noexcept { + return api_entry_context( + ctx, array_schema, dim_label_num); +} + +capi_return_t tiledb_array_schema_get_dimension_label_from_index( + tiledb_ctx_t* ctx, + tiledb_array_schema_t* array_schema, + uint64_t dim_label_index, + tiledb_dimension_label_t** dim_label) noexcept { + return api_entry_context< + detail::tiledb_array_schema_get_dimension_label_from_index>( + ctx, array_schema, dim_label_index, dim_label); +} + capi_return_t tiledb_subarray_add_label_range( tiledb_ctx_t* ctx, tiledb_subarray_t* subarray, diff --git a/tiledb/sm/c_api/tiledb_dimension_label_experimental.h b/tiledb/sm/c_api/tiledb_dimension_label_experimental.h index 8f3d4c6e2332..484bea226b2a 100644 --- a/tiledb/sm/c_api/tiledb_dimension_label_experimental.h +++ b/tiledb/sm/c_api/tiledb_dimension_label_experimental.h @@ -183,6 +183,60 @@ TILEDB_EXPORT capi_return_t tiledb_array_schema_set_dimension_label_tile_extent( tiledb_datatype_t type, const void* tile_extent) TILEDB_NOEXCEPT; +/** + * Retrieve the number of dimension labels attached to an array schema. + * + * **Example:** + * + * @code{.c} + * uint64_t dim_label_num = 0; + * tiledb_array_schema_get_dimension_label_num( + * ctx, + * array_schema, + * &dim_label_num); + * @endcode + * + * @param ctx The TileDB context. + * @param array_schema The array schema. + * @param dim_label_num Retrieved number of dimension labels for the schema. + * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. + */ +TILEDB_EXPORT capi_return_t tiledb_array_schema_get_dimension_label_num( + tiledb_ctx_t* ctx, + tiledb_array_schema_t* array_schema, + uint64_t* dim_label_num) TILEDB_NOEXCEPT; + +/** + * Retrieve a dimension label from an array schema by index position. + * + * **Example:** + * + * @code{.c} + * uint64_t dim_label_index = 1; + * tiledb_dimension_label_t* dim_label; + * tiledb_array_schema_get_dimension_label_from_index( + * ctx, + * array_schema, + * dim_label_index, + * &dim_label); + * // ... + * + * // Free dimension label object when work is complete. + * tiledb_dimension_label_free(&dim_label); + * @endcode + * + * @param ctx The TileDB context. + * @param array_schema The array schema. + * @param dim_label_index Index position of the dimension label. + * @param dim_label Retrieved dimension label. + * @return `TILEDB_OK` for success or `TILEDB_ERR` for error. + */ +TILEDB_EXPORT capi_return_t tiledb_array_schema_get_dimension_label_from_index( + tiledb_ctx_t* ctx, + tiledb_array_schema_t* array_schema, + uint64_t dim_label_index, + tiledb_dimension_label_t** dim_label) TILEDB_NOEXCEPT; + /** * Adds a 1D range along a subarray for a dimension label, which is in the form * (start, end, stride). The datatype of the range components must be the same