Comment on page
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
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);
#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)
using TileDB.CSharp;
// Create context
using Context ctx = new Context();
// Create attribute
using var attr = new Attribute(ctx, "attr", DataType.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);
// 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) # multiple int32
# Strings are implicitly `var=True`:
attr = tiledb.Attr(name="str_attr", dtype=str)
# is equivalent to:
attr = tiledb.Attr(name="foo", dtype=str, 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)
// Setting a fixed number of values
attr.SetCellValNum(3);
// Setting a variable number of values
attr.SetCellValNum(Attribute.VariableSized);
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
C#
// Setting a nullable attribute
tiledb_attribute_set_nullable(ctx, attr, 1);
// Setting a nullable attribute
attr.set_nullable(true);
Note: nullable Python attributes should be used with the
from_pandas API or Pandas series with a Pandas extension dtype (e.g. StringDtype).tiledb.Attr(name="foo", dtype=str, nullable=True)
## Create a nullable attribute
attr <- tiledb_attr("a1", type = "INT32", nullable = TRUE)
attr.setNullable(true)
// TODO
attr.SetNullable(true);
Supported Attribute Datatypes:
Crossed data types are deprecated.
C/C++/Java/Go
Python
R
Datatype | Description |
|---|---|
TILEDB_BLOB | Opaque bytes. Note: the TILEDB_BLOB datatype does not support query conditions. |
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_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 |
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);
// 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")
// Assumming a int32 attribute
attr.SetFillValue(0);
// Assumming a var-sized attribute
strAttr.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.
Last modified 1mo ago