Expose tiledb_array_upgrade_version (#675)

* Expose tiledb_array_upgrade_version

* Update NEWS, increase micro version [ci skip]

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: tiledb
 Type: Package
-Version: 0.24.0.10
+Version: 0.24.0.11
 Title: Modern Database Engine for Multi-Modal Data via Sparse and Dense Multidimensional Arrays
 Authors@R: c(person("TileDB, Inc.", role = c("aut", "cph")),
  person("Dirk", "Eddelbuettel", email = "dirk@tiledb.com", role = "cre"))

NAMESPACE

@@ -114,6 +114,7 @@ export(tiledb_array_schema_set_enumeration_empty)
 export(tiledb_array_schema_set_offsets_filter_list)
 export(tiledb_array_schema_set_validity_filter_list)
 export(tiledb_array_schema_version)
+export(tiledb_array_upgrade_version)
 export(tiledb_arrow_array_del)
 export(tiledb_arrow_array_ptr)
 export(tiledb_arrow_schema_del)

NEWS.md

@@ -10,6 +10,8 @@
 
 * Query conditions can be expressed against non-existing enumeration (_i.e._, `factor`) values when TileDB Core 2.21.0 or later is used (#674)
 
+* The `tiledb_array_upgrade_version` helper function to upgrade an schema version is now available (#675)
+
 ## Bug Fixes
 
 * The `tiledb_get_query_range_var()` accessor now correctly calls the range getter for variable-sized dimensions (#662)

R/Array.R

@@ -1,6 +1,6 @@
 #  MIT License
 #
-#  Copyright (c) 2017-2023 TileDB Inc.
+#  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
@@ -211,3 +211,18 @@ tiledb_array_apply_aggregate <- function(array, attrname,
 
     libtiledb_query_apply_aggregate(query@ptr, attrname, operation, nullable)
 }
+
+##' Upgrade an Array to the current TileDB Array Schema Format
+##'
+##' @param array A TileDB Array object
+##' @param config A TileDB Configuration (optional, default NULL)
+##' @param ctx A tiledb_ctx object (optional)
+##' @return Nothing is returned as the function is invoked for its side effect
+##' @export
+tiledb_array_upgrade_version <- function(array, config = NULL, ctx = tiledb_get_context()) {
+    stopifnot("The 'array' argument must be a TileDB Array object" = is(array, "tiledb_array"),
+              "The 'config' argument must be NULL or a TileDB Config" =
+                  is.null(config) || is(config, "tiledb_config"))
+    libtiledb_array_upgrade_version(ctx@ptr, array@ptr, array@uri,
+                                    if (is.null(config)) NULL else config@ptr)
+}

R/RcppExports.R

@@ -630,6 +630,10 @@ libtiledb_array_has_enumeration_vector <- function(ctx, array) {
     .Call(`_tiledb_libtiledb_array_has_enumeration_vector`, ctx, array)
 }
 
+libtiledb_array_upgrade_version <- function(ctx, array, uri, cfg = NULL) {
+    invisible(.Call(`_tiledb_libtiledb_array_upgrade_version`, ctx, array, uri, cfg))
+}
+
 libtiledb_query <- function(ctx, array, type) {
     .Call(`_tiledb_libtiledb_query`, ctx, array, type)
 }

inst/tinytest/test_tiledbarray.R

@@ -1580,3 +1580,19 @@ res <- arr[]
 expect_true(tiledb_array_is_open(arr))
 arr <- tiledb_array_close(arr)
 expect_false(tiledb_array_is_open(arr))
+
+## tiledb_array_upgrade_version, re-using an old array as an upgrade candidate
+tdir <- tempfile()
+tgzfile <- system.file("sampledata", "legacy_write.tar.gz", package="tiledb")
+untar(tarfile = tgzfile, exdir = tdir)
+uri <- file.path(tdir, "legacy_write", "penguins")
+oldarr <- tiledb_array(uri)
+oldsch <- tiledb::schema(oldarr)    # explicit namespace to not get arrow::schema
+oldver <- tiledb_array_schema_version(oldsch)
+expect_silent(tiledb_array_upgrade_version(oldarr))
+rc <- tiledb_array_close(oldarr)
+newarr <- tiledb_array(uri)
+newsch <- tiledb::schema(newarr)    # explicit namespace to not get arrow::schema
+newver <- tiledb_array_schema_version(newsch)
+rc <- tiledb_array_close(newarr)
+expect_true(newver > oldver)

src/RcppExports.cpp

@@ -1847,6 +1847,19 @@ BEGIN_RCPP
     return rcpp_result_gen;
 END_RCPP
 }
+// libtiledb_array_upgrade_version
+void libtiledb_array_upgrade_version(XPtr<tiledb::Context> ctx, XPtr<tiledb::Array> array, std::string& uri, Rcpp::Nullable<XPtr<tiledb::Config>> cfg);
+RcppExport SEXP _tiledb_libtiledb_array_upgrade_version(SEXP ctxSEXP, SEXP arraySEXP, SEXP uriSEXP, SEXP cfgSEXP) {
+BEGIN_RCPP
+    Rcpp::RNGScope rcpp_rngScope_gen;
+    Rcpp::traits::input_parameter< XPtr<tiledb::Context> >::type ctx(ctxSEXP);
+    Rcpp::traits::input_parameter< XPtr<tiledb::Array> >::type array(arraySEXP);
+    Rcpp::traits::input_parameter< std::string& >::type uri(uriSEXP);
+    Rcpp::traits::input_parameter< Rcpp::Nullable<XPtr<tiledb::Config>> >::type cfg(cfgSEXP);
+    libtiledb_array_upgrade_version(ctx, array, uri, cfg);
+    return R_NilValue;
+END_RCPP
+}
 // libtiledb_query
 XPtr<tiledb::Query> libtiledb_query(XPtr<tiledb::Context> ctx, XPtr<tiledb::Array> array, std::string type);
 RcppExport SEXP _tiledb_libtiledb_query(SEXP ctxSEXP, SEXP arraySEXP, SEXP typeSEXP) {
@@ -3737,6 +3750,7 @@ static const R_CallMethodDef CallEntries[] = {
     {"_tiledb_libtiledb_array_has_enumeration", (DL_FUNC) &_tiledb_libtiledb_array_has_enumeration, 3},
     {"_tiledb_libtiledb_array_get_enumeration", (DL_FUNC) &_tiledb_libtiledb_array_get_enumeration, 3},
     {"_tiledb_libtiledb_array_has_enumeration_vector", (DL_FUNC) &_tiledb_libtiledb_array_has_enumeration_vector, 2},
+    {"_tiledb_libtiledb_array_upgrade_version", (DL_FUNC) &_tiledb_libtiledb_array_upgrade_version, 4},
     {"_tiledb_libtiledb_query", (DL_FUNC) &_tiledb_libtiledb_query, 3},
     {"_tiledb_libtiledb_query_type", (DL_FUNC) &_tiledb_libtiledb_query_type, 1},
     {"_tiledb_libtiledb_query_set_layout", (DL_FUNC) &_tiledb_libtiledb_query_set_layout, 2},

src/libtiledb.cpp

@@ -2818,6 +2818,21 @@ Rcpp::LogicalVector libtiledb_array_has_enumeration_vector(XPtr<tiledb::Context>
     return has_enum;
 }
 
+// [[Rcpp::export]]
+void libtiledb_array_upgrade_version(XPtr<tiledb::Context> ctx,
+                                     XPtr<tiledb::Array> array,
+                                     std::string& uri,
+                                     Rcpp::Nullable<XPtr<tiledb::Config>> cfg = R_NilValue) {
+    check_xptr_tag<tiledb::Context>(ctx);
+    check_xptr_tag<tiledb::Array>(array);
+    if (cfg.isNull()) {
+        array->upgrade_version(*ctx.get(), uri);
+    } else {
+        XPtr<tiledb::Config> config(cfg);
+        array->upgrade_version(*ctx.get(), uri, config.get());
+    }
+}
+
 
 /**
  * Query