feat: [sc-58279] [core] add tiledb_array_schema_get_enumeration API (#5359)

Story details: https://app.shortcut.com/tiledb-inc/story/58279

Adds functions `tiledb_array_schema_get_enumeration_from_name` and `tiledb_array_schema_get_enumeration_from_attribute_name` which load the
contents of an enumeration and return a handle to the user.

---
TYPE: FEATURE | C_API | CPP_API
DESC: add tiledb_array_schema_get_enumeration

---------

Co-authored-by: Shaun M Reed <[email protected]>

Author: rroelke

test/src/unit-cppapi-enumerations.cc

@@ -33,6 +33,7 @@
 #include <fstream>
 
 #include <test/support/tdb_catch.h>
+#include "test/support/src/array_schema_helpers.h"
 #include "test/support/src/vfs_helpers.h"
 #include "tiledb/api/c_api/array/array_api_internal.h"
 #include "tiledb/api/c_api/array_schema/array_schema_api_internal.h"
@@ -313,6 +314,96 @@ TEST_CASE_METHOD(
   REQUIRE(enmr_name2.has_value() == false);
 }
 
+TEST_CASE_METHOD(
+    CPPEnumerationFx,
+    "CPP: Enumerations From Disk - ArraySchema::get_enumeration_from_name",
+    "[enumeration][array-schema-get-enumeration-from-name][rest]") {
+  create_array();
+
+  std::optional<Enumeration> expect_enumeration;
+  {
+    auto array = tiledb::Array(ctx_, uri_, TILEDB_READ);
+    expect_enumeration =
+        ArrayExperimental::get_enumeration(ctx_, array, enmr_name);
+  }
+
+  SECTION("default schema load retrieves enumeration on request only") {
+    auto schema = Array::load_schema(ctx_, uri_);
+
+    CHECK(!schema.ptr()->array_schema()->is_enumeration_loaded(enmr_name));
+
+    auto actual_enumeration =
+        ArraySchemaExperimental::get_enumeration_from_name(
+            ctx_, schema, enmr_name);
+    CHECK(schema.ptr()->array_schema()->is_enumeration_loaded(enmr_name));
+    CHECK(test::is_equivalent_enumeration(
+        *expect_enumeration, actual_enumeration));
+  }
+
+  SECTION("schema load with rest config retrieves enumeration eagerly") {
+    Config config;
+    config["rest.load_enumerations_on_array_open"] = "true";
+
+    auto schema = Array::load_schema_with_config(ctx_, config, uri_);
+    CHECK(schema.ptr()->array_schema()->is_enumeration_loaded(enmr_name));
+
+    // requesting it should do no I/O (we did it already),
+    // unclear how to check that
+    auto actual_enumeration =
+        ArraySchemaExperimental::get_enumeration_from_name(
+            ctx_, schema, enmr_name);
+    CHECK(schema.ptr()->array_schema()->is_enumeration_loaded(enmr_name));
+    CHECK(test::is_equivalent_enumeration(
+        *expect_enumeration, actual_enumeration));
+  }
+}
+
+TEST_CASE_METHOD(
+    CPPEnumerationFx,
+    "CPP: Enumerations From Disk - "
+    "ArraySchema::get_enumeration_from_attribute_name",
+    "[enumeration][array-schema-get-enumeration-from-attribute-name][rest]") {
+  create_array();
+
+  const std::string attr_name = "attr1";
+
+  std::optional<Enumeration> expect_enumeration;
+  {
+    auto array = tiledb::Array(ctx_, uri_, TILEDB_READ);
+    expect_enumeration =
+        ArrayExperimental::get_enumeration(ctx_, array, enmr_name);
+  }
+
+  SECTION("default schema load retrieves enumeration on request only") {
+    auto schema = Array::load_schema(ctx_, uri_);
+
+    CHECK(!schema.ptr()->array_schema()->is_enumeration_loaded(enmr_name));
+
+    auto actual_enumeration =
+        ArraySchemaExperimental::get_enumeration_from_attribute_name(
+            ctx_, schema, attr_name);
+    CHECK(schema.ptr()->array_schema()->is_enumeration_loaded(enmr_name));
+    CHECK(test::is_equivalent_enumeration(
+        *expect_enumeration, actual_enumeration));
+  }
+
+  SECTION("schema load with rest config retrieves enumeration eagerly") {
+    Config config;
+    config["rest.load_enumerations_on_array_open"] = "true";
+
+    auto schema = Array::load_schema_with_config(ctx_, config, uri_);
+    CHECK(schema.ptr()->array_schema()->is_enumeration_loaded(enmr_name));
+
+    // requesting it should do no I/O (we did it already),
+    // unclear how to check that
+    auto actual_enumeration =
+        ArraySchemaExperimental::get_enumeration_from_attribute_name(
+            ctx_, schema, attr_name);
+    CHECK(schema.ptr()->array_schema()->is_enumeration_loaded(enmr_name));
+    CHECK(test::is_equivalent_enumeration(
+        *expect_enumeration, actual_enumeration));
+  }
+}
 TEST_CASE_METHOD(
     CPPEnumerationFx,
     "CPP: Array::load_all_enumerations",

test/support/CMakeLists.txt

@@ -36,6 +36,7 @@ list(APPEND TILEDB_CORE_INCLUDE_DIR "${CMAKE_SOURCE_DIR}/tiledb/sm/c_api")
 
 # Gather the test source files
 set(TILEDB_TEST_SUPPORT_SOURCES
+  src/array_schema_helpers.cc
   src/ast_helpers.h
   src/ast_helpers.cc
   src/helpers.h

test/support/src/array_schema_helpers.cc

@@ -0,0 +1,54 @@
+/**
+ * @file   array_schema_helpers.cc
+ *
+ * @section LICENSE
+ *
+ * The MIT License
+ *
+ * @copyright Copyright (c) 2017-2024 TileDB, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @section DESCRIPTION
+ *
+ * This file defines some array schema test suite helper functions.
+ */
+
+#include "test/support/src/array_schema_helpers.h"
+#include "tiledb/api/c_api/enumeration/enumeration_api_internal.h"
+#include "tiledb/sm/array_schema/enumeration.h"
+#include "tiledb/sm/cpp_api/tiledb"
+
+using namespace tiledb;
+
+namespace tiledb::test {
+
+bool is_equivalent_enumeration(
+    const Enumeration& left, const Enumeration& right) {
+  return left.name() == right.name() && left.type() == right.type() &&
+         left.cell_val_num() == right.cell_val_num() &&
+         left.ordered() == right.ordered() &&
+         std::equal(
+             left.ptr()->data().begin(),
+             left.ptr()->data().end(),
+             right.ptr()->data().begin(),
+             right.ptr()->data().end());
+}
+
+}  // namespace tiledb::test

test/support/src/array_schema_helpers.h

@@ -0,0 +1,50 @@
+/**
+ * @file   array_schema_helpers.h
+ *
+ * @section LICENSE
+ *
+ * The MIT License
+ *
+ * @copyright Copyright (c) 2017-2024 TileDB, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @section DESCRIPTION
+ *
+ * This file declares some array schema test suite helper functions.
+ */
+
+#ifndef TILEDB_TEST_ARRAY_SCHEMA_HELPERS_H
+#define TILEDB_TEST_ARRAY_SCHEMA_HELPERS_H
+
+#include "tiledb/sm/cpp_api/tiledb"
+#include "tiledb/sm/cpp_api/tiledb_experimental"
+
+namespace tiledb::test {
+
+/**
+ * @return if two enumerations `left` and `right` are equivalent,
+ *         i.e. have the same name, datatype, variants, etc
+ */
+bool is_equivalent_enumeration(
+    const tiledb::Enumeration& left, const tiledb::Enumeration& right);
+
+}  // namespace tiledb::test
+
+#endif

tiledb/api/c_api/array/test/CMakeLists.txt

@@ -31,7 +31,6 @@ commence(unit_test capi_array)
   this_target_object_libraries(
     capi_array_stub
     capi_array_schema_stub
-    capi_attribute_stub
     capi_domain_stub
   )
   this_target_link_libraries(tiledb_test_support_lib)

tiledb/api/c_api/array_schema/CMakeLists.txt

@@ -36,6 +36,8 @@ commence(object_library capi_array_schema_stub)
   this_target_sources(${SOURCES})
   this_target_link_libraries(export)
   this_target_object_libraries(array_schema)
+  this_target_object_libraries(array)
+  this_target_object_libraries(capi_attribute_stub)
   this_target_object_libraries(capi_context_stub)
 conclude(object_library)
 

tiledb/api/c_api/array_schema/array_schema_api.cc

@@ -34,6 +34,7 @@
 #include "array_schema_api_experimental.h"
 #include "array_schema_api_internal.h"
 
+#include "tiledb/api/c_api/attribute/attribute_api_external_experimental.h"
 #include "tiledb/api/c_api/attribute/attribute_api_internal.h"
 #include "tiledb/api/c_api/context/context_api_internal.h"
 #include "tiledb/api/c_api/current_domain/current_domain_api_external_experimental.h"
@@ -181,6 +182,54 @@ capi_return_t tiledb_array_schema_timestamp_range(
   return TILEDB_OK;
 }
 
+capi_return_t tiledb_array_schema_get_enumeration_from_name(
+    tiledb_ctx_t* ctx,
+    tiledb_array_schema_t* array_schema,
+    const char* enumeration_name,
+    tiledb_enumeration_t** enumeration) {
+  ensure_array_schema_is_valid(array_schema);
+  ensure_output_pointer_is_valid(enumeration);
+
+  if (enumeration_name == nullptr) {
+    throw CAPIException("'enumeration_name' must not be null");
+  }
+
+  array_schema->load_enumeration(ctx, enumeration_name);
+
+  auto ptr = array_schema->get_enumeration(enumeration_name);
+  *enumeration = tiledb_enumeration_handle_t::make_handle(ptr);
+
+  return TILEDB_OK;
+}
+
+capi_return_t tiledb_array_schema_get_enumeration_from_attribute_name(
+    tiledb_ctx_t* ctx,
+    tiledb_array_schema_t* array_schema,
+    const char* attribute_name,
+    tiledb_enumeration_t** enumeration) {
+  ensure_array_schema_is_valid(array_schema);
+  ensure_output_pointer_is_valid(enumeration);
+
+  tiledb_attribute_t* attribute;
+  capi_return_t getattr = tiledb_array_schema_get_attribute_from_name(
+      ctx, array_schema, attribute_name, &attribute);
+  if (tiledb_status(getattr) != TILEDB_OK) {
+    return getattr;
+  }
+
+  tiledb_string_t* enumeration_name_inner;
+  capi_return_t getenmr = tiledb_attribute_get_enumeration_name(
+      ctx, attribute, &enumeration_name_inner);
+  if (tiledb_status(getenmr) != TILEDB_OK) {
+    return getenmr;
+  }
+
+  std::string enumeration_name(enumeration_name_inner->view());
+  return api_entry_with_context<
+      tiledb::api::tiledb_array_schema_get_enumeration_from_name>(
+      ctx, array_schema, enumeration_name.c_str(), enumeration);
+}
+
 capi_return_t tiledb_array_schema_add_enumeration(
     tiledb_array_schema_t* array_schema, tiledb_enumeration_t* enumeration) {
   ensure_array_schema_is_valid(array_schema);
@@ -365,6 +414,10 @@ capi_return_t tiledb_array_schema_get_attribute_from_name(
   ensure_array_schema_is_valid(array_schema);
   ensure_output_pointer_is_valid(attr);
 
+  if (name == nullptr) {
+    throw CAPIException("'attribute_name' must not be null");
+  }
+
   uint32_t attribute_num = array_schema->attribute_num();
   if (attribute_num == 0) {
     *attr = nullptr;
@@ -540,6 +593,28 @@ CAPI_INTERFACE(
       ctx, array_schema, lo, hi);
 }
 
+CAPI_INTERFACE(
+    array_schema_get_enumeration_from_name,
+    tiledb_ctx_t* ctx,
+    tiledb_array_schema_t* array_schema,
+    const char* enumeration_name,
+    tiledb_enumeration_t** enumeration) {
+  return api_entry_with_context<
+      tiledb::api::tiledb_array_schema_get_enumeration_from_name>(
+      ctx, array_schema, enumeration_name, enumeration);
+}
+
+CAPI_INTERFACE(
+    array_schema_get_enumeration_from_attribute_name,
+    tiledb_ctx_t* ctx,
+    tiledb_array_schema_t* array_schema,
+    const char* attribute_name,
+    tiledb_enumeration_t** enumeration) {
+  return api_entry_with_context<
+      tiledb::api::tiledb_array_schema_get_enumeration_from_attribute_name>(
+      ctx, array_schema, attribute_name, enumeration);
+}
+
 CAPI_INTERFACE(
     array_schema_add_enumeration,
     tiledb_ctx_t* ctx,