Multi-Range Subarrays

You can slice a multi-range subarray as follows (also see Subarray):

C

// ... create context ctx
// ... create query

// Create subarray object
tiledb_subarray_t* subarray;
tiledb_subarray_alloc(ctx, array, &subarray);

// Add two ranges to first dimension
int row_0_start = 1, row_0_end = 2;
int row_1_start = 4, row_1_end = 4;
tiledb_subarray_add_range(ctx, subarray, 0, &row_0_start, &row_0_end, NULL);
tiledb_subarray_add_range(ctx, subarray, 0, &row_1_start, &row_1_end, NULL);

// Add one range to the second dimension
int col_0_start = 1, col_0_end = 4;
tiledb_subarray_add_range(ctx, subarray, 1, &col_0_start, &col_0_end, NULL);

// For var-sized dimensions:
const char* start = "abc";
const char* end = "def";
tiledb_subarray_add_range_var(
    ctx, subarray, 0, start, strlen(start), end, strlen(end));

// Set the subarray to the query
tiledb_query_set_subarray_t(ctx, query, subarray);

// ... Do stuff with the query.

tiledb_subarray_free(&subarray);

C++

// ... create query

Subarray subarray(ctx, array);

// Add two ranges to first dimension
int row_0_start = 1, row_0_end = 2;
int row_1_start = 4, row_1_end = 4;
subarray.add_range(0, row_0_start, row_0_end)
        .add_range(0, row_1_start, row_1_end);
       
// Add one range to the second dimension       
int col_0_start = 1, col_0_end = 4;       
subarray.add_range(1, col_0_start, col_0_end);

// For var-sized dimensions:
subarray.add_range(1, "abc", "def");

// Set the subarray to the query
query.set_subarray(subarray);

Python

# ... open array

# slice subarrays [1,2]x[1,4] and [4,4]x[1,4]
A.multi_index[ [slice(1,2), 4], 1:4 ]

# NOTE: Ranges in multi_index are all inclusive

# multi-range slicing of a dense array returns a NumPy array
# matching the shape of the selection.

# multi-range slicing of a sparse array returns a coordinate
# array and value array(s) for each attribute, similar to
# other sparse queries

# slicing string dimensions
# assuming array with nonempty_domain() == ('a', 'c'):
A.multi_index['a':'c']

# to slice with a constructed list, pass arguments as a tuple:
slices = [slice(1,2), (slice(3,4)]
A.mtuli_index[tuple(slices)]

R

# The array will be 10x10 with dimensions "rows" and "cols", with domain [1,10]
dom <- tiledb_domain(dims = c(tiledb_dim("rows", c(1L, 10L), 4L, "INT32"),
                              tiledb_dim("cols", c(1L, 10L), 4L, "INT32")))

# The array will be dense with a single attribute "a" so each (i,j) cell 
# can store an integer value
schema <- tiledb_array_schema(dom, attrs = c(tiledb_attr("a", type = "INT32")))

# Create the (empty) array on disk.
tiledb_array_create(uri, schema)

# Prepare a query
qry <- tiledb_query(arr, "READ")

# Allocate storage: for simple types we can use R vectors
# For more complex types we need to allocate data structures
rows <- integer(100)
cols <- integer(100)
values <- integer(100)
tiledb_query_set_buffer(qry, "rows", rows)
tiledb_query_set_buffer(qry, "cols", cols)
tiledb_query_set_buffer(qry, "a", values)

# Now set two ranges on the first dimension and one on the second
sch <- schema(arr)
tiledb_query_add_range(qry, sch, "rows", 3L, 4L)
tiledb_query_add_range(qry, sch, "rows", 7L, 9L)
tiledb_query_add_range(qry, sch, "cols", 2L, 4L)

tiledb_query_submit(qry)
tiledb_query_finalize(qry)

n <- tiledb_query_result_buffer_elements(qry, "a")
print(data.frame(rows=rows,cols=cols,a=values)[1:n,])



# This also works on string or float columns provided they have no 
# missing values as in the is demo of 'penguins' where NAs have
# been removed so that we can index on 'species' and 'body_mass_g'
uri <- tempfile()
ppnona <- na.omit(penguins)
fromDataFrame(ppnona, uri, col_index=c("species", "body_mass_g"))

# We specify ranges as (named) list with one or more entries corresponding
# to the dimension name.  Each list contains a matrix where each row contains
# the min and max value of a selection.  Here we request species names from 
# 'Aa' to 'Bz' (matching 'Adelie' penguins) as well as two body mass ranges
# from 2900 to 2999 and 3100 to 3199 grams, respectively.  This returns 
# eleven matching rows.
rngs <- list(species = cbind("Aa", "Bz"),
             body_mass_g = matrix(c(2900,2999,
                                    3100,3199),
                                  2, 2, byrow=TRUE))

dat <- tiledb_array(uri, selected_range=rngs)[]
print(dat)

Java

// ... create query

// Add two ranges to first dimension
int row_0_start = 1, row_0_end = 2;
int row_1_start = 4, row_1_end = 4;
query.addRange(0, row_0_start, row_0_end)
     .addRange(0, row_1_start, row_1_end);
       
// Add one range to the second dimension       
int col_0_start = 1, col_0_end = 4;       
query.addRange(1, col_0_start, col_0_end);

// For var-sized dimensions:
query.addRangeVar(1, "abc", "def");

Go

// ... create query

// Add two ranges to first dimension
query.AddRange(0, int32(1), int32(2))
query.AddRange(0, int32(4), int32(4))
       
// Add one range to the second dimension  
query.AddRange(1, int32(1), int32(4))

// For var-sized dimensions:
query.AddRangeVar(0, []byte("abc"), []byte("def"))

C#

// ... create array and query

// Create subarray
using Subarray subarray = new Subarray(array);

// Add two ranges to the first dimension
subarray.AddRange(0, 1, 2);
subarray.AddRange(0, 4, 4);

// Add one range to the second dimension  
subarray.AddRange(1, 1, 4);

// For var-sized dimensions:
subarray.AddRange(1, "abc", "def");

// Set the subarray to the query.
query.SetSubarray(subarray);

Slicing with a stride is not currently supported, but it is work in progress. See our roadmap for updates.

You can also get the various ranges set to the query as follows:

C

// ... create context ctx
// ... create query
// ... set range

// Get subarray from query
tiledb_subarray_t* subarray;
tiledb_query_get_subarray_t(ctx, query, &subarray);

// Get the number of ranges for a dimension
int dim_idx = 1;
unsigned long long range_num;
tiledb_subarray_get_range_num(ctx, subarray, dim_idx, &range_num);

// Get a range based on a dimension index
// NOTE: This function does not copy, it assigns pointers
const void* start;
const void* end;
const void* stride;
int dim_idx = 0;
unsigned long long range_idx = 2;
tiledb_subarray_get_range(
    ctx, subarray, dim_idx, range_idx, &start, &end, &stride);

// For var-sized dimensions, we need to get the sizes of the start/end of the range
unsigned long long start_size, end_size;
tiledb_subarray_get_range_var_size(
     ctx, subarray, dim_idx, range_idx, &start_size, &end_size);
 
// And then get the var-sized start and end
// NOTE: This function copies into the inputs
char start_str[start_size];
char end_str[end_size];
tiledb_subarray_get_range_var(
     ctx, subarray, dim_idx, range_idx, start_str, end_str);

C++

// ... create query
// ... set ranges

// Get the number of ranges
unsigned dim_idx = 1;
uint64_t range_num = query.range_num(dim_idx);

// Get a range given a dimension index
unsigned dim_idx = 0;
unsigned range_idx = 0;
auto range = query.range<int32_t>(dim_idx, range_idx);
// This returns a triplet (start, end, strid)

// For var-sized dimensions:
std::array<std::string, 2> range = query.range(dim_idx, range_idx);
// This returns a pair of strings (start, end)

Python

# TODO: not supported yet

R

# number of ranges given index
num <- tiledb_query_get_range_num(qry, idx)

# range start, end and stride for range i (1 <= i <= num)
rng <- tiledb_query_get_range(qry, idx, i)

# range start and end for variable-sized dimension for range i (1 <= i <= num)
strrng <- tiledb_query_get_range_var(qry, idx, i)

Java

// ... create query
// ... set ranges

// Get the number of ranges
int dimIdx = 1;
long rangeNum = query.getRangeNum(dimIdx);

// Get a range given a dimension index
int dimIdx = 0;
int rangeIdx = 0;
Pair<Object, Object> range = query.getRange(dimIdx, rangeIdx);
// This returns a triplet (start, end, strid)

// For var-sized dimensions:
Pair<Object, Object> range = query.getRangeVar(dimIdx, BigInteger.valueOf(rangeIdx));
// This returns a pair of strings (start, end)

Go

// ... create query
// ... set ranges

// Get the number of ranges
dimIdx := 1;
numOfRanges, _ := query.GetRangeNum(dimIdx)

// Get a range given a dimension index
var I uint64
for I = 0; I < *numOfRanges; I++ {
	start, end, _ := query.GetRange(dimIdx, I)
	fmt.Printf("Range for dimension: %d, start: %v, end: %v\n", dimIdx, start, end)
}

// For var-sized dimensions:
rangeIdx := 0
start, end, _ := query.GetRangeVar(dimIdx, rangeIdx)
// This returns a pair of strings (start, end)

C#

// ... create context ctx, query and subarray

// Get the number of ranges for a dimension
ulong rangeCount = subarray.GetRangeCount(1);

// Get a range based on a dimension index
// NOTE: This will throw if the types mismatch
(int Start, int End) = subarray.GetRange<int>(0, 2);

// For var-sized dimensions, we need to call GetStringRange
(string StartVar, string EndVar) = subarray.GetStringRange(0, 2);