Creating Dimensions

Creating a dimension requires specifying a name, the dimension datatype, the dimension domain and the space tile extent. Below you can see an example of creating an int32 dimension called dim with domain [1,4], and tile extent 2.

C

#include <tiledb/tiledb.h>

// Create context
tiledb_ctx_t* ctx;
tiledb_ctx_alloc(NULL, &ctx);

// Create dimension
int dim_domain[] = {1, 4};
int tile_extent = 2;
tiledb_dimension_t* dim;
tiledb_dimension_alloc(ctx, "dim", TILEDB_INT32, &dim_domain[0], &tile_extent, &dim);

// ...

// Create string dimension
// No values are accepted for domain and tile extent
tiledb_dimension_t* str_dim;
tiledb_dimension_alloc(ctx, "str_dim", TILEDB_STRING_ASCII, NULL, NULL, &str_dim);

// Make sure to free the dimension and context
tiledb_dimension_free(&dim);
tiledb_ctx_free(&ctx);

C++

#include <tiledb/tiledb>
using namespace tiledb;

// Create context
Context ctx;

// Create dimension
auto dim = Dimension::create<int32_t>(ctx, "dim", {{1, 4}}, 2);
 
// Or alternatively:
int dim_domain[] = {1, 4};
int tile_extent = 2;
auto dim = Dimension::create(ctx, "dim", TILEDB_INT32, dim_domain, &tile_extent);

// String dimension
// No values are accepted for domain and tile extent
auto dim = Dimension::create(ctx, "dim", TILEDB_STRING_ASCII, nullptr, nullptr);

Python

import tiledb
import numpy as np

dim = tiledb.Dim(name="dim", domain=(1, 4), tile=2, dtype=np.int32)

# for string dimensions, the domain and tiling are handled implicitly
str_dim = tiledb.Dim(name="str_dim", tile=None, dtype="ascii")

R

library(tiledb)

# Create dimension
dim <- tiledb_dim("dim1", c(1L, 4L), 2L, "INT32")

# String dimenions: no values for domain and extent
strdim <- tiledb_dim("dim2", NULL, NULL, "ASCII")

Java

// Create context
try(Context ctx = new Context()) {
    // Create dimension
    Dimension dim = new Dimension(ctx, "dim", TILEDB_INT32, new Pair<Integer, Integer>(1, 4), 2);
    
    // String dimension
    // No values are accepted for domain and tile extent
    Dimension strDim = new Dimension(ctx, "strDim", Datatype.TILEDB_STRING_ASCII, null, null);
}

Go

import tiledb "github.com/TileDB/TileDB-Go"

// Create context
ctx, _ := tiledb.NewContext(nil)

// Create dimension
dim, _ := tiledb.NewDimension(ctx, "dim", []int32{1, 4}, int32(2))

// String dimension
dim, _ := tiledb.NewStringDimension(ctx, "dim")

C#

using TileDB.CSharp;

using Context ctx = new Context();
 
// Create dimension
using Dimension dim = Dimension.Create(ctx, "dim", 1, 4, 2);

// String dimension
using Dimension strDim = Dimension.CreateString(ctx, "dim");

Supported Dimension Datatypes:

C/C++/Java/Go

Datatype	Description	Array Type
TILEDB_STRING_ASCII	Variable length string	Sparse
TILEDB_INT8	8-bit integer	Dense & Sparse
TILEDB_UINT8	8-bit unsigned integer	Dense & Sparse
TILEDB_INT16	16-bit integer	Dense & Sparse
TILEDB_UINT16	16-bit unsigned integer	Dense & Sparse
TILEDB_INT32	32-bit integer	Dense & Sparse
TILEDB_UINT32	32-bit unsigned integer	Dense & Sparse
TILEDB_INT64	64-bit integer	Dense & Sparse
TILEDB_UINT64	64-bit unsigned integer	Dense & Sparse
TILEDB_FLOAT32	32-bit floating point	Sparse
TILEDB_FLOAT64	64-bit floating point	Sparse
TILEDB_DATETIME_YEAR	Years	Dense & Sparse
TILEDB_DATETIME_MONTH	Months	Dense & Sparse
TILEDB_DATETIME_WEEK	Weeks	Dense & Sparse
TILEDB_DATETIME_DAY	Days	Dense & Sparse
TILEDB_DATETIME_HR	Hours	Dense & Sparse
TILEDB_DATETIME_MIN	Minutes	Dense & Sparse
TILEDB_DATETIME_SEC	Seconds	Dense & Sparse
TILEDB_DATETIME_MS	Milliseconds	Dense & Sparse
TILEDB_DATETIME_US	Microseconds	Dense & Sparse
TILEDB_DATETIME_NS	Nanoseconds	Dense & Sparse
TILEDB_DATETIME_PS	Picoseconds	Dense & Sparse
TILEDB_DATETIME_FS	Femtoseconds	Dense & Sparse
TILEDB_DATETIME_AS	Attoseconds	Dense & Sparse

Python

Datatype	Description	Array Type	Internal TILEDB Datatype Mapping
"ascii" / np.bytes_	Variable length string	Sparse	TILEDB_STRING_ASCII
np.int8	8-bit integer	Dense & Sparse	TILEDB_INT8
np.uint8	8-bit unsigned integer	Dense & Sparse	TILEDB_UINT8
np.int16	16-bit integer	Dense & Sparse	TILEDB_INT16
np.uint16	16-bit unsigned integer	Dense & Sparse	TILEDB_UINT16
np.int32	32-bit integer	Dense & Sparse	TILEDB_INT32
np.uint32	32-bit unsigned integer	Dense & Sparse	TILEDB_UINT32
np.int64	64-bit integer	Dense & Sparse	TILEDB_INT64
np.uint64	64-bit unsigned integer	Dense & Sparse	TILEDB_UINT64
np.float32	32-bit floating point	Sparse	TILEDB_FLOAT32
np.float64	64-bit floating point	Sparse	TILEDB_FLOAT64
"datetime64[Y]"	Years	Dense & Sparse	TILEDB_DATETIME_YEAR
"datetime64['M']	Months	Dense & Sparse	TILEDB_DATETIME_MONTH
"datetime64['W']"	Weeks	Dense & Sparse	TILEDB_DATETIME_WEEK
"datetime64['D']"	Days	Dense & Sparse	TILEDB_DATETIME_DAY
"datetime64['h']"	Hours	Dense & Sparse	TILEDB_DATETIME_HR
"datetime64['m']"	Minutes	Dense & Sparse	TILEDB_DATETIME_MIN
"datetime64['s']"	Seconds	Dense & Sparse	TILEDB_DATETIME_SEC
"datetime64['ms']"	Milliseconds	Dense & Sparse	TILEDB_DATETIME_MS
"datetime64['us']"	Microseconds	Dense & Sparse	TILEDB_DATETIME_US
"datetime64['ns']"	Nanoseconds	Dense & Sparse	TILEDB_DATETIME_NS
"datetime64['ps']"	Picoseconds	Dense & Sparse	TILEDB_DATETIME_PS
"datetime64['fs']"	Femtoseconds	Dense & Sparse	TILEDB_DATETIME_FS
"datetime64['as']"	Attoseconds	Dense & Sparse	TILEDB_DATETIME_AS

R

Datatype	Description	Array Type
"ASCII"	Variable length string	Sparse
"INT8"	8-bit integer	Dense & Sparse
"UINT8"	8-bit unsigned integer	Dense & Sparse
"INT16"	16-bit integer	Dense & Sparse
"UINT16"	16-bit unsigned integer	Dense & Sparse
"INT32"	32-bit integer	Dense & Sparse
"UINT32"	32-bit unsigned integer	Dense & Sparse
"INT64"	64-bit integer	Dense & Sparse
"UINT64"	64-bit unsigned integer	Dense & Sparse
"FLOAT32"	32-bit floating point	Sparse
"FLOAT64"	64-bit floating point	Sparse
"DATETIME_YEAR"	Years	Dense & Sparse
"DATETIME_MONTH"	Months	Dense & Sparse
"DATETIME_WEEK"	Weeks	Dense & Sparse
"DATETIME_DAY"	Days	Dense & Sparse
"DATETIME_HR"	Hours	Dense & Sparse
"DATETIME_MIN"	Minutes	Dense & Sparse
"DATETIME_SEC"	Seconds	Dense & Sparse
"DATETIME_MS"	Milliseconds	Dense & Sparse
"DATETIME_US"	Microseconds	Dense & Sparse
"DATETIME_NS"	Nanoseconds	Dense & Sparse
"DATETIME_PS"	Picoseconds	Dense & Sparse
"DATETIME_FS"	Femtoseconds	Dense & Sparse
"DATETIME_AS"	Attoseconds	Dense & Sparse

C#

The following values are members of the TileDB.CSharp.DataType enum:

Datatype	Description	Array Type
StringAscii	Variable length string	Sparse
Int8	8-bit integer	Dense & Sparse
UInt8	8-bit unsigned integer	Dense & Sparse
Int16	16-bit integer	Dense & Sparse
UInt16	16-bit unsigned integer	Dense & Sparse
Int32	32-bit integer	Dense & Sparse
UInt32	32-bit unsigned integer	Dense & Sparse
Int64	64-bit integer	Dense & Sparse
UInt64	64-bit unsigned integer	Dense & Sparse
Float32	32-bit floating point	Sparse
Float64	64-bit floating point	Sparse
DateTimeYear	Years	Dense & Sparse
DateTimeMonth	Months	Dense & Sparse
DateTimeWeek	Weeks	Dense & Sparse
DateTimeDay	Days	Dense & Sparse
DateTimeHour	Hours	Dense & Sparse
DateTimeMinute	Minutes	Dense & Sparse
DateTimeSecond	Seconds	Dense & Sparse
DateTimeMillisecond	Milliseconds	Dense & Sparse
DateTimeMicrosecond	Microseconds	Dense & Sparse
DateTimeNanosecond	Nanoseconds	Dense & Sparse
DateTimePicosecond	Picoseconds	Dense & Sparse
DateTimeFemtosecond	Femtoseconds	Dense & Sparse
DateTimeAttosecond	Attoseconds	Dense & Sparse

Setting Filters

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