Creating Attributes
Creating an attribute requires specifying a (optional; attribute names starting with __ are reserved) name and a (required) datatype. In the example below we create an int32 attribute called attr.
C
C++
Python
R
Java
Go
#include <tiledb/tiledb.h>
// Create context
tiledb_ctx_t* ctx;
tiledb_ctx_alloc(NULL, &ctx);
// Create attribute
tiledb_attribute_t* attr;
tiledb_attribute_alloc(ctx, "attr", TILEDB_INT32, &attr);
// ...
// Make sure to free the attribute and context
tiledb_attribute_free(&attr);
tiledb_ctx_free(&ctx);
#include <tiledb/tiledb>
using namespace tiledb;
// Create context
Context ctx;
// Create attribute
auto attr = Attribute::create<int32>(ctx, "attr")
// Or alternatively:
Attribute attr(ctx, "attr", TILEDB_INT32);
import tiledb
import numpy as np
attr = tiledb.Attr(name="attr", dtype=np.int32)
# Create attribute
attr <- tiledb_attr("attr", "INT32")
// Create context
try(Context ctx = new Context()) {
// Create attribute
Attribute attr = new Attribute(ctx, "attr", TILEDB_INT32);
}
import tiledb "github.com/TileDB/TileDB-Go"
// Create context
ctx, _ := tiledb.NewContext(nil)
// Create attribute
attr, _ := tiledb.NewAttribute(ctx, "attr", tiledb.TILEDB_INT32)
An attribute can also store a fixed number of values (of the same datatype) in a single cell, or a variable number of values. You can specify this as follows:
C
C++
Python
R
Java
Go
// Setting a fixed number of values
tiledb_attribute_set_cell_val_num(ctx, attr, 3);
// Setting a variable number of values
tiledb_attribute_set_cell_val_num(ctx, attr, TILEDB_VAR_NUM);
// Setting a fixed number of values
attr.set_cell_val_num(3);
// Setting a variable number of values
attr.set_cell_val_num(TILEDB_VAR_NUM);
# Setting a fixed number of values
attr = tiledb.Attr(name="attr", dtype=np.dtype('i4, i4, i4'))
# Setting a variable number of values
attr = tiledb.Attr(name="attr", dtype=np.int32, var=True)
## Attribute value counts can be retrieved from R
attr <- tiledb_attr("a1", type = "INT32")
cell_val_num(a1)
## Attribute value counts can be set via the lower level API
## set int32 attribute to length three
attr <- tiledb_attr("a1", type = "INT32")
tiledb:::libtiledb_attribute_set_cell_val_num(attr@ptr, 3)
## set char attribute to variable length which is encoded as a NA
attr <- tiledb_attr("a1", type = "CHAR")
tiledb:::libtiledb_attribute_set_cell_val_num(attr@ptr, NA)
// Setting a fixed number of values
attr.setCellValNum(3);
// Setting a variable number of values
attr.setCellValNum(TILEDB_VAR_NUM);
// Setting a fixed number of values
attr.SetCellValNum(3)
// Setting a variable number of values
attr.SetCellValNum(tiledb.TILEDB_VAR_NUM)
An attribute may also be nullable. This allows designating each cell as valid or null. Applicable to both fixed-sized and var-sized attributes.
C
C++
Python
R
Java
Go
// Setting a nullable attribute
tiledb_attribute_set_nullable(ctx, attr, 1);
// Setting a nullable attribute
attr.set_nullable(true);
# TODO
## TODO
attr.setNullable(true)
// TODO
Supported Attribute Datatypes:
C/C++/Java/Go
Python
R
Datatype
Description
TILEDB_INT8
8-bit integer
TILEDB_UINT8
8-bit unsigned integer
TILEDB_INT16
16-bit integer
TILEDB_UINT16
16-bit unsigned integer
TILEDB_INT32
32-bit integer
TILEDB_UINT32
32-bit unsigned integer
TILEDB_INT64
64-bit integer
TILEDB_UINT64
64-bit unsigned integer
TILEDB_FLOAT32
32-bit floating point
TILEDB_FLOAT64
64-bit floating point
TILEDB_DATETIME_YEAR
Years
TILEDB_DATETIME_MONTH
Months
TILEDB_DATETIME_WEEK
Weeks
TILEDB_DATETIME_DAY
Days
TILEDB_DATETIME_HR
Hours
TILEDB_DATETIME_MIN
Minutes
TILEDB_DATETIME_SEC
Seconds
TILEDB_DATETIME_MS
Milliseconds
TILEDB_DATETIME_US
Microseconds
TILEDB_DATETIME_NS
Nanoseconds
TILEDB_DATETIME_PS
Picoseconds
TILEDB_DATETIME_FS
Femtoseconds
TILEDB_DATETIME_AS
Attoseconds
TILEDB_DATETIME_CHAR
Single character
TILEDB_STRING_ASCII
ASCII string
TILEDB_STRING_UTF8
UTF-8 string
TILEDB_STRING_UTF16
UTF-16 string
TILEDB_STRING_UTF32
UTF-32 string
TILEDB_STRING_UCS2
UCS-2 string
TILEDB_STRING_UCS4
UCS-4 string
TILEDB_ANY
(datatype, bytelength, value)
Datatype
Description
Internal TILEDB Datatype Mapping
np.int8
8-bit integer
TILEDB_INT8
np.uint8
8-bit unsigned integer
TILEDB_UINT8
np.int16
16-bit integer
TILEDB_INT16
np.uint16
16-bit unsigned integer
TILEDB_UINT16
np.int32
32-bit integer
TILEDB_INT32
np.uint32
32-bit unsigned integer
TILEDB_UINT32
np.int64
64-bit integer
TILEDB_INT64
np.uint64
64-bit unsigned integer
TILEDB_UINT64
np.float32
32-bit floating point
TILEDB_FLOAT32
np.float64
64-bit floating point
TILEDB_FLOAT64
"ascii"
ASCII
TILEDB_STRING_ASCII
np.dtype('S1')
Character
TILEDB_CHAR
np.dtype('U1')
Unicode UTF-8
TILEDB_STRING_UTF8
"datetime64[Y]"
Years
TILEDB_DATETIME_YEAR
"datetime64[M]"
Months
TILEDB_DATETIME_MONTH
"datetime64[W]"
Weeks
TILEDB_DATETIME_WEEK
"datetime64[D]"
Days
TILEDB_DATETIME_DAY
"datetime64[h]"
Hours
TILEDB_DATETIME_HR
"datetime64[m]"
Minutes
TILEDB_DATETIME_MIN
"datetime64[s]"
Seconds
TILEDB_DATETIME_SEC
"datetime64[ms]"
Milliseconds
TILEDB_DATETIME_MS
"datetime64[us]"
Microseconds
TILEDB_DATETIME_US
"datetime64[ns]"
Nanoseconds
TILEDB_DATETIME_NS
"datetime64[ps]"
Picoseconds
TILEDB_DATETIME_PS
"datetime64[fs]"
Femtoseconds
TILEDB_DATETIME_FS
"datetime64[as]"
Attoseconds
TILEDB_DATETIME_AS
Datatype
Description
"CHAR"
Single character
"INT8"
8-bit integer
"UINT8"
8-bit unsigned integer
"INT16"
16-bit integer
"UINT16"
16-bit unsigned integer
"INT32"
32-bit integer
"UINT32"
32-bit unsigned integer
"INT64"
64-bit integer
"UINT64"
64-bit unsigned integer
"FLOAT32"
32-bit floating point
"FLOAT64"
64-bit floating point
"DATETIME_YEAR"
Years
"DATETIME_MONTH"
Months
"DATETIME_WEEK"
Weeks
"DATETIME_DAY"
Days
"DATETIME_HR"
Hours
"DATETIME_MIN"
Minutes
"DATETIME_SEC"
Seconds
"DATETIME_MS"
Milliseconds
"DATETIME_US"
Microseconds
"DATETIME_NS"
Nanoseconds
"DATETIME_PS"
Picoseconds
"DATETIME_FS"
Femtoseconds
"DATETIME_AS"
Attoseconds

Setting Filters

Attributes accept filters such as compressors. This is described in detail here.

Setting Fill Values

There are situations where you may read "empty spaces" from TileDB arrays. For those empty spaces, a read query will return some default fill values for the selected attributes. You can set your own fill values for these cases as follows:
C
C++
Python
R
Java
Go
// Assumming a int32 attribute
int value = 0;
unsigned long long size = sizeof(value);
tiledb_attribute_set_fill_value(ctx, attr, &value, size);
// Assumming a var-sized attribute
const char* value = "null";
unsigned long long size = strlen(value);
tiledb_attribute_set_fill_value(ctx, attr, value, size);
// Fixed-sized attribute
auto a1 = tiledb::Attribute::create<int>(ctx, "a1");
int32_t value = 0;
uint64_t size = sizeof(value);
a1.set_fill_value(&value, size);
// Var-sized attribute
auto a2 = tiledb::Attribute::create<std::string>(ctx, "a2");
std::string value("null");
a2.set_fill_value(value.c_str(), value.size());
# Setting a fixed-size fill value
attr = tiledb.Attr(name="attr", dtype=np.int32, fill=123)
# Setting a var-sized (string attribute) fill value
attr = tiledb.Attr(name="attr", dtype=np.str, fill="filler")
# Retrieving the value
attr.fill # -> "filler"
# ... create int attribute attr
# set fill value to 42L
tiledb_attribute_set_fill_value(attr, 42L)
# ... create variable-sized attributte attr
# set fill value to "..."
tiledb_attribute_set_fill_value(attr, "...")
attr.setFillValue((byte) 'c');
// Assumming a int32 attribute
attribute.SetFillValue(0)
// Assumming a var-sized attribute
attribute.SetFillValue("null")
A call to setting the number of cells for an attribute (see above) sets the fill value of the attribute to its default. Therefore, make sure you set the fill values after deciding on the number of values this attribute will hold in each cell.
For fixed-sized attributes, the input fill value size should be equal to the cell size.
Export as PDF
Copy link
Outline
Setting Filters
Setting Fill Values