Creating Attributes

Creating an attribute requires specifying a (optional) name and a (required) datatype. In the example below we create an int32 attribute called attr.

C
C++
Python
R
Java
Go
C
#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);
C++
#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);
Python
import tiledb
import numpy as np
attr = tiledb.Attr(name="attr", dtype=np.int32)
R
# Create attribute
attr <- tiledb_attr("attr", "INT32")
Java
// Create context
try(Context ctx = new Context()) {
// Create attribute
Attribute attr = new Attribute(ctx, "attr", TILEDB_INT32);
}
Go
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
C
// 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);
C++
// 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);
Python
# 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)
R
## 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)
Java
// Setting a fixed number of values
attr.setCellValNum(3);
// Setting a variable number of values
attr.setCellValNum(TILEDB_VAR_NUM);
Go
// Setting a fixed number of values
attr.SetCellValNum(3)
// Setting a variable number of values
attr.SetCellValNum(tiledb.TILEDB_VAR_NUM)

Supported Attribute Datatypes:

C/C++/Java/Go
Python
R
C/C++/Java/Go

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)

Python

Datatype

Description

np.int8

8-bit integer

np.uint8

8-bit unsigned integer

np.int16

16-bit integer

np.uint16

16-bit unsigned integer

np.int32

32-bit integer

np.uint32

32-bit unsigned integer

np.int64

64-bit integer

np.uint64

64-bit unsigned integer

np.float32

32-bit floating point

np.float64

64-bit floating point

np.dtype('S1')

Character

np.dtype('U1')

Unicode UTF-8

"datetime64[Y]"

Years

"datetime64[M]"

Months

"datetime64[W]"

Weeks

"datetime64[D]"

Days

"datetime64[h]"

Hours

"datetime64[m]"

Minutes

"datetime64[s]"

Seconds

"datetime64[ms]"

Milliseconds

"datetime64[us]"

Microseconds

"datetime64[ns]"

Nanoseconds

"datetime64[ps]"

Picoseconds

"datetime64[fs]"

Femtoseconds

"datetime64[as]"

Attoseconds

R

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
C
// 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);
C++
// 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());
Python
# 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"
R
# ... 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, "...")
Java
// TODO
Go
// 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.