Reading the Array Schema

Inspecting the Array Schema

You can get the schema of an existing array as follows:

C
C++
Python
R
Java
Go
C
// ... create context ctx
tiledb_array_schema_t* schema;
// Get schema directly from storage
tiledb_array_schema_load(ctx, "<array-uri>", &schema);
// Or, load with key if the array is encrypted
const char key[] = "0123456789abcdeF0123456789abcdeF";
tiledb_array_schema_t* array_schema;
tiledb_array_schema_load_with_key(
ctx, "<array-uri>", TILEDB_AES_256_GCM, key, sizeof(key), &schema);
// Alternatively, you can get the schema from an open array
tiledb_array_t* array;
tiledb_array_alloc(ctx, "<array-uri>", &array);
tiledb_array_open(ctx, array, TILEDB_READ);
tiledb_array_get_schema(ctx, array, &array_schema);
// Or, open the array with key if it is encrypted
tiledb_array_open_with_key(
ctx, array, TILEDB_READ, TILEDB_AES_256_GCM, key, sizeof(key));
tiledb_array_get_schema(ctx, array, &array_schema);
// Make sure to free the array schema object
tiledb_array_schema_free(&schema);
tiledb_array_free(&array);
C++
// ... create context ctx
// Get schema directly from storage
ArraySchema schema(ctx, "<array-uri>");
// Or, load with key if the array is encrypted
const char key[] = "0123456789abcdeF0123456789abcdeF";
ArraySchema schema(ctx, "<array-uri>", TILEDB_AES_256_GCM, key, sizeof(key));
// Alternatively, you can get the schema from an open array
Array array(ctx, "<array-uri>", TILEDB_READ);
auto schema = array.schema();
// Or, open the array with key if it is encrypted
Array array(
ctx, "<array-uri>", TILEDB_WRITE, TILEDB_AES_256_GCM, key, sizeof(key));
auto schema = array.schema();
Python
# load the schema directly
# optionally pass `key=...` for encrypted arrays
schema = tiledb.ArraySchema.load(array_name)
# or access the schema from an open array object
A = tiledb.Array(array_name)
schema = A.schema
R
# TODO: Loading the array schema directly is not supported in R
Java
// ... create context ctx
// Get schema directly from storage
ArraySchema schema = new ArraySchema(ctx, "<array-uri>");
// Or, load with key if the array is encrypted
String key = "0123456789abcdeF0123456789abcdeF";
ArraySchema schema = new ArraySchema(ctx, "<array-uri>", TILEDB_AES_256_GCM, key.getBytes(StandardCharsets.UTF_8));
// Alternatively, you can get the schema from an open array
Array array = new Array(ctx, "<array-uri>", TILEDB_READ);
ArraySchema schema = array.schema();
// Or, open the array with key if it is encrypted
Array array = new Array(
ctx, "<array-uri>", TILEDB_WRITE, TILEDB_AES_256_GCM, key.getBytes(StandardCharsets.UTF_8));
ArraySchema schema = array.schema();
Go
// ... create context ctx
// Get schema directly from storage
schema, _ := LoadArraySchema(ctx, "<array-uri>")
// Or, load with key if the array is encrypted
key := "0123456789abcdeF0123456789abcdeF"
schema, _ := LoadArraySchemaWithKey(ctx, "<array-uri>", TILEDB_AES_256_GCM, key)
// Alternatively, you can get the schema from an open array
array, _ := NewArray(ctx, "<array-uri>")
array.Open(TILEDB_READ)
schema, _ = array.Schema()
// Or, open the array with key if it is encrypted
array.OpenWithKey(TILEDB_READ, TILEDB_AES_256_GCM, key)
schema, err = array.Schema()

The following code snippet shows how to inspect the various array schema members.

C
C++
Python
R
Java
Go
C
// ... create context ctx
// ... get array schema
// Get array type
tiledb_array_type_t* array_type;
tiledb_array_schema_get_array_type(ctx, schema, &array_type);
// Get tile capacity
uint64_t capacity;
tiledb_array_schema_get_capacity(ctx, schema, &capacity);
// Get tile order
tiledb_layout_t tile_order;
tiledb_array_schema_get_tile_order(ctx, schema, &tile_order);
// Get cell order
tiledb_layout_t cell_order;
tiledb_array_schema_get_cell_order(ctx, schema, &cell_order);
// Get coordinates filter list
tiledb_filter_list_t* filter_list;
tiledb_array_schema_get_coords_filter_list(ctx, schema, &filter_list);
// Make sure to call `tiledb_filter_list_free(ctx, &filter_list);`
// Get offsets filter list
tiledb_filter_list_t* filter_list;
tiledb_array_schema_get_offsets_filter_list(ctx, schema, &filter_list);
// Make sure to call `tiledb_filter_list_free(ctx, &filter_list);`
// Get the array domain
tiledb_domain_t* domain;
tiledb_array_schema_get_domain(ctx, schema, &domain);
// Make sure to call `tiledb_domain_free(&domain);`
// Get number of attributes
uint32_t attr_num;
tiledb_array_schema_get_attribute_num(ctx, schema, &attr_num);
// Get attribute from index (0 <= idx < attr_num)
tiledb_attribute_t* attr;
tiledb_array_schema_get_attribute_from_index(ctx, schema, idx, &attr);
// Make sure to call `tiledb_attribute_free(&attr);`
// Get attribute from name
tiledb_attribute_t* attr;
tiledb_array_schema_get_attribute_from_name(ctx, schema, "attr", &attr);
// Make sure to call `tiledb_attribute_free(&attr);`
// Check if array schema has attribute with a given name
int32_t has_attr;
tiledb_array_schema_has_attribute(ctx, array_schema, "attr", &has_attr);
// Dump the array schema in ASCII format in the selected output
tiledb_array_schema_dump(ctx, array_schema, stdout);
C++
// ... get array schema
// Get array type
tiledb_array_type_t array_type = schema.array_type();
// Get tile capacity
uint64_t capacity = schema.capacity()
// Get tile order
tiledb_layout_t tile_order = schema.tile_order();
// Get cell order
tiledb_layout_t cell_order = schema.cell_order();
// Get coordinates filter list
FilterList filter_list = schema.coords_filter_list();
// Get offsets filter list
FilterList filter_list = schema.offsets_filter_list();
// Get the array domain
Domain domain = schema.domain();
// Get number of attributes
uint32_t attr_num = schema.attribute_num();
// Get attribute from index (0 <= idx < attr_num)
Attribute attr = schema.attribute(idx);
// Get attribute from name
Attribute attr = schema.attribute("attr");
// Check if array schema has attribute with a given name
bool has_attr = schema.has_attribute("attr");
// Dump the array schema in ASCII format in the selected output
schema.dump(stdout);
Python
# ... get array schema
# Check if array is sparse
schema.sparse
# Get tile capacity
schema.capacity
# Cell and tile order return 'row-major', 'col-major', or 'global'
# Get tile order
schema.tile_order
# Get cell order
schema.cell_order
# Get coordinates filter list
coords_filters = schema.coords_filters
# Get offsets filter list
offsets_filters = schema.offsets_filters
# Get the array domain
domain = schema.domain
# Get number of attributes
attr_num = schema.nattr
# Get attribute by index (0 <= idx < attr_num)
attr = schema.attr(idx)
# Get attribute by name
attr = schema.attr("attr")
# Print the array schema in ASCII format
schema.dump()
R
# Get array schema
A <- tiledb_sparse(uri = array_name, ctx=ctx) # Similar for tiledb_dense()
schema <- schema(A)
# Get array type
sparse <- is.sparse(schema)
# Get tile capacity
# TODO: tile capacity is not supported in R currently
# Get tile order
t_order <- tile_order(schema)
# Get cell order
c_order <- cell_order(schema)
# Get coordinates and offset filter list
reslist <- filter_list(schema)
# Get the array domain
dom <- domain(schema)
# Get all attributes as list
attrs <- attrs(schema)
# Get attribute from name
attr <- attrs(schema, "attr")
# Dump the array schema in ASCII format in the selected output
show(schema)
Java
// ... get array schema
// Get array type
ArrayType arrayType = schema.getArrayType();
// Get tile capacity
long capacity = schema.getCapacity()
// Get tile order
Layout tileOrder = schema.getTileOrder();
// Get cell order
Layout cellOrder = schema.getCellOrder();
// Get coordinates filter list
FilterList filterList = schema.getCoordsFilterList();
// Get offsets filter list
FilterList filterList = schema.getOffsetsFilterList();
// Get the array domain
Domain domain = schema.getDomain();
// Get number of attributes
long attrNnum = schema.getAttributeNum();
// Get all attributes
HashMap<String, Attribute> attrs = schema.getAttributes();
// Get attribute from index (0 <= idx < attr_num)
Attribute attr = schema.getAttribute(idx);
// Get attribute from name
Attribute attr = schema.getAttribute("attr");
// Check if array schema has attribute with a given name
boolean hasAttr = schema.hasAttribute("attr");
// Dump the array schema in ASCII format in the selected output
schema.dump();
Go
// ... get array schema
// Get array type
arrayType, _ := schema.Type()
// Get tile capacity
capacity, _ := schema.Capacity()
// Get tile order
tileOrder, _ := schema.TileOrder()
// Get cell order
cellOrder := schema.CellOrder()
// Get coordinates filter list
filterList, _ := schema.CoordsFilterList()
// Get offsets filter list
filterList, _ := schema.OffsetsFilterList()
// Get the array domain
domain, _ := schema.Domain()
// Get number of attributes
attrNum := schema.AttributeNum()
// Get attribute from index (0 <= idx < attr_num)
attr, _ := schema.AttributeFromIndex(idx)
// Get attribute from name
attr, _ := schema.AttributeFromName("attr")
// Check if array schema has attribute with a given name
// ToDo: not supported yet
// Dump the array schema in ASCII format in the selected output
schema.DumpSTDOUT()

Inspecting Domain

You can inspect the members of the domain as follows:

C
C++
Python
R
Java
Go
C
// ... create context
// ... get array schema
// ... get domain from schema
// Get the domain datatype (i.e., the datatype of all dimensions)
tiledb_datatype_t type;
tiledb_domain_get_type(ctx, domain, &type);
// Get number of dimensions
uint32_t dim_num;
tiledb_domain_get_ndim(ctx, domain, &dim_num);
// Get dimension by index (0 <= idx < dim_num)
tiledb_dimension_t* dim;
tiledb_domain_get_dimension_from_index(ctx, domain, idx, &dim);
// Get dimension from name
tiledb_dimension_t* dim;
tiledb_domain_get_dimension_from_name(ctx, domain, "dim", &dim);
// Check if domain has dimension with a given name
int32_t has_dim;
tiledb_domain_has_dimension(ctx, domain, "dim", &has_dim);
// Dump the domain in ASCII format in the selected output
tiledb_domain_dump(ctx, domain, stdout);
C++
// ... get array schema
// ... get domain from schema
// Get the domain datatype (i.e., the datatype of all dimensions)
tiledb_datatype_t type = domain.type();
// Get number of dimensions
uint32_t dim_num = domain.ndim();
// Get dimension by index (0 <= idx < dim_num)
Dimension dim = domain.dimensions()[idx];
// Get dimension from name
// TODO: not supported yet
// Check if domain has dimension with a given name
bool has_dim = domain.has_dimension("dim");
// Dump the domain in ASCII format in the selected output
domain.dump(stdout);
Python
# ... get array schema
# ... get domain from schema
# Get the domain data type (i.e., the datatype of all dimensions)
# note: types are automatically converted to NumPy dtypes
domain_dtype = domain.dtype
# Get number of dimensions
dim_num = domain.ndim
# Get dimension by index (0 <= idx < dim_num)
dim = domain.dim(idx)
# Get dimenion by name
# TODO: not supported yet
# Print the domain in ASCII format
domain.dump()
R
# ... get array schema
# ... get domain from schema
# Get the domain datatype (i.e., the datatype of all dimensions)
type <- datatype(dom)
# Get number of dimensions
dim_num <- dim(dom)
# Get all dimension
dims <- dimensions(dom)
# Dump the domain in ASCII format in the selected output
show(dom)
Java
// ... get array schema
// ... get domain from schema
// Get the domain datatype (i.e., the datatype of all dimensions)
Datatype type = domain.getType();
// Get number of dimensions
long dim_num = domain.getNDim();
// Get dimension by index (0 <= idx < dim_num)
Dimension dim = domain.getDimension(idx);
// Get dimension from name
Dimension dim = domain.getDimension("dim);
// Check if domain has dimension with a given name
boolean hasDim = domain.hasDimension("dim");
// Dump the domain in ASCII format in the selected output
domain.dump(stdout);
Go
// ... get array schema
// ... get domain from schema
// Get the domain datatype (i.e., the datatype of all dimensions)
domainType, _ := domain.Type()
// Get number of dimensions
dimNum, _ := domain.NDim();
// Get dimension by index (0 <= idx < dim_num)
dim, _ := domain.DimensionFromIndex(idx)
// Get dimension from name
dim, _ := domain.DimensionFromName("<dimension_name>")
// Check if domain has dimension with a given name
// ToDo: not supported yet
// Dump the domain in ASCII format in the selected output
domain.DumpSTDOUT()

Inspecting Dimensions

You can inspect a dimensions as follows:

C
C++
Python
R
Java
Go
C
// ... create context ctx
// ... get array schema
// ... get domain
// ... get dimension by index or name
// Get dimension name
const char* dim_name;
tiledb_dimension_get_name(ctx, dim, &dim_name);
// Get dimension datatype
tiledb_datatype_t dim_type;
tiledb_dimension_get_type(ctx, dim, &dim_type);
// Get dimension domain
const int* domain;
tiledb_dimension_get_domain(ctx, dim, &domain);
// Get tile extent
const int* tile_extent;
tiledb_dimension_get_tile_extent(ctx, dim, &tile_extent);
// Dump the dimension in ASCII format in the selected output
tiledb_dimension_dump(ctx, dim, stdout);
// Make sure to delete the dimension in the end
tiledb_dimension_free(&dim);
C++
// ... get array schema
// ... get domain
// ... get dimension by index
// Get dimension name
std::string dim_name = dimension.name();
// Get dimension datatype
tiledb_datatype_t dim_type = dimension.type();
// Get dimension domain
std::pair<int, int> domain = dimension.domain<int>();
// Get tile extent
int tile_extent = dimension.tile_extent<int>();
// Dump the dimension in ASCII format in the selected output
dimension.dump(stdout);
Python
# ... get array schema
# ... get domain
# ... get dimension by index
# Get dimension name
dim_name = dimension.name
# Get dimension datatype
dim_dtype = dimension.dtype
# Get dimension domain
dim_domain = dimension.domain
# Get tile extent
tile_extent = dimension.tile
R
# ... get array schema
# ... get domain
# ... get dimension by index or name
# Get dimension name
dim_name <- name(dim)
# Get dimension datatype
dim_type <- datatype(dim)
# Get dimension domain
domain <- domain(dim)
# Get tile extent
tile_extent <- tile(dim)
# Dump the dimension in ASCII format in the selected output
show(dim)
Java
// ... get array schema
// ... get domain
// ... get dimension by index
// Get dimension name
String dimName = dimension.getName();
// Get dimension datatype
Datatype dim_type = dimension.getType();
// Get dimension domain
Pair domain = dimension.domain();
// Get tile extent
Integer tileExtent = dimension.getTileExtent();
Go
// ... get array schema
// ... get domain
// ... get dimension by index or name
// Get dimension name
dimName, _ := dimension.Name()
// Get dimension datatype
dimType, _ := dimension.Type()
// Get dimension domain
domain, _ := dimension.Domain()
// Get tile extent
extent, _ := dimension.Extent;
// Dump the dimension in ASCII format in the selected output
dimension.DumpSTDOUT()

Inspecting Attributes

You can inspect an attribute as follows:

C
C++
Python
R
Java
Go
C
// ... create context
// ... get array schema
// ... get attribute by index or name
// Get attribute name
const char* attr_name;
tiledb_attribute_get_name(ctx, attr, &attr_name);
// Get attribute datatype
tiledb_datatype_t attr_type;
tiledb_attribute_get_type(ctx, attr, &attr_type);
// Get filter list
tiledb_filter_list_t* filter_list;
tiledb_attribute_get_filter_list(ctx, attr, &filter_list);
// Make sure to call `tiledb_filter_list_free(&filter_list);`
// Get number of values per cell
uint32_t num;
tiledb_attribute_get_cell_val_num(ctx, attr, &num);
// Get cell size for this attribute
uint64_t cell_size;
tiledb_attribute_get_cell_size(ctx, attr, &cell_size);
// Dump the attribute in ASCII format in the selected output
tiledb_attribute_dump(ctx, dim, stdout);
// Make sure to delete the attribute in the end
tiledb_attribute_free(&attr);
C++
// ... get array schema
// ... get attribute by index or name
// Get attribute name
std::string attr_name = attr.name();
// Get attribute datatype
tiledb_datatype_t attr_type = attr.type();
// Get filter list
FilterList filter_list = attr.filter_list();
// Check if attribute is variable-length
bool var_length = attr.variable_size();
// Get number of values per cell
uint32_t num = attr.cell_val_num();
// Get cell size for this attribute
uint64_t cell_size = attr.cell_size();
// Dump the attribute in ASCII format in the selected output
attr.dump(stdout);
Python
# ... create context
# ... get array schema
# ... get attribute by index or name
# Get attribute name
attr_name = attr.name
# Get attribute datatype
attr_dtype = attr.dtype
# Get filter list
filter_list = attr.filters
# Check if attribute is variable-length
var_length = attr.isvar
# Get number of values per cell
# note: for variable-length attributes, ncells == typemax(np.uint32)
num = attr.ncells
# Get datatype size (bytes) for this attribute
cell_size = attr.dtype.itemsize
R
# ... get array schema
# ... get attribute by index or name
# Get attribute name
attr_name <- name(attr)
# Get attribute datatype
attr_type <- datatype(attr)
# Get filter list
filter_list <- filter_list(attr)
# Check if attribute is variable-length
# variable length attribtues are not supported in R currently
# Get number of values per cell
num <- ncells(attr)
# Get cell size for this attribute
# TODO: not supportded yet
# Dump the attribute in ASCII format in the selected output
show(attr)
Java
// ... get array schema
// ... get attribute by index or name
// Get attribute name
String attr_name = attr.getName();
// Get attribute datatype
Datatype attr_type = attr.getType();
// Get filter list
FilterList filter_list = attr.filter_list();
// Check if attribute is variable-length
boolean varLength = attr.isVar();
// Get number of values per cell
long num = attr.getCellValNum();
// Get cell size for this attribute
long cellSize = attr.getCellSize();
// Dump the attribute in ASCII format in the selected output
System.out.Println(attr.toString());
Go
// ... get array schema
// ... get attribute by index or name
// Get attribute name
attrName, _ := attr.Name()
// Get attribute datatype
attrType, _ := attr.Type()
// Get filter list
filterList , _= attr.FilterList();
// Check if attribute is variable-length
TILEDB_VAR_NUM, _ := attr.CellValNum()
// Get number of values per cell
num, _ := attr.CellValNum()
// Get cell size for this attribute
// ToDo: not supported yet
// Dump the attribute in ASCII format in the selected output
attr.DumpSTDOUT()

Inspecting Filters

You can inspect filters as follows:

C
C++
Python
R
Java
Go
C
// ... create context ctx
// ... get filter list
// Get number of filters
uint32_t num_filters;
tiledb_filter_list_get_nfilters(ctx, filter_list, &num_filters);
// Get the maximum tile chunk size
uint32_t max_chunk_size;
tiledb_filter_list_get_max_chunk_size(ctx, filter_list, &max_chunk_size);
// Get a filter by index (0 <= idx < num_filters)
tiledb_filter_t* filter;
tiledb_filter_list_get_filter_from_index(ctx, filter_list, idx, &filter);
// Get filter type
tiledb_filter_type_t type;
tiledb_filter_get_type(ctx, filter, &type);
// Get filter option (depends on the filter)
int32_t level;
tiledb_filter_get_option(ctx, filter, TILEDB_COMPRESSION_LEVEL, &level);
// Make sure to delete the filter list and filter
tiledb_filter_list_free(&filter_list);
tiledb_filter_free(&filter);
C++
// ... get filter list
// Get number of filters
uint32_t num_filters = filter_list.nfilters();
// Get the maximum tile chunk size
uint32_t max_chunk_size = filter_list.max_chunk_size();
// Get a filter by index (0 <= idx < num_filters)
Filter filter = filter_list.filter(idx);
// Get filter type
tiledb_filter_type_t type = filter.filter_type();
// Get filter option (depends on the filter)
int32_t level;
filter.get_option(TILEDB_COMPRESSION_LEVEL, &level);
Python
# ... get filter list
# Get number of filters
num_filters = len(filter_list)
# Get the maximum tile chunk size
max_chunk_size = filter_list.chunksize
# Get a filter by index (0 <= idx < num_filters)
filter = filter_list[idx]
# Get filter type
filter.__class__
# Get filter option (depends on the filter: `filter.<option name>`)
level = filter.level
R
# TODO: Not supported in R currently
Java
// ... get filter list
// Get number of filters
uint32_t numFilters = filterList.getNumFilters();
// Get the maximum tile chunk size
uint32_t maxChunkSize = filterList.getMaxChunkSize();
// Get a filter by index (0 <= idx < num_filters)
Filter filter = filterList.getFilter(idx);
// Get filter type
if (filter instanceof BitShuffleFilter) {
} else if (filter instanceof BitWidthReductionFilter) {
} else if (filter instanceof ByteShuffleFilter) {
} else if (filter instanceof Bzip2Filter) {
} else if (filter instanceof CompressionFilter) {
} else if (filter instanceof DoubleDeltaFilter) {
} else if (filter instanceof GzipFilter) {
} else if (filter instanceof LZ4Filter) {
} else if (filter instanceof NoneFilter) {
} else if (filter instanceof PositiveDeltaFilter) {
} else if (filter instanceof RleFilter) {
} else if (filter instanceof ZstdFilter) {
}
// Get filter option (depends on the filter)
// TODO: getting the filter level is not supported in Java
Go
// ... get filter list
// Get number of filters
numFilters, _ := filter_list.NFilters()
// Get the maximum tile chunk size
maxChunkSize, _ := filter_list.max_chunk_size()
// Get a filter by index (0 <= idx < num_filters)
filter, _ := filter_list.FilterFromIndex(idx)
// Get filter type
filterType, _ := filter.Type()
// Get filter option (depends on the filter)
level, _ := filter.Option(TILEDB_COMPRESSION_LEVEL)