Add C APIs for dimension label REST support. (TileDB-Inc#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.
davisp · Sep 6, 2023 · dd39278 · dd39278
1 parent 1eebb27
commit dd39278
Show file tree

Hide file tree

Showing 3 changed files with 114 additions and 9 deletions.
diff --git 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
@@ -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<detail::tiledb_array_schema_get_dimension_label_num>(
+      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
@@ -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