Quickstart

Welcome to TileDB! This quickstart will walk you through getting TileDB installed and writing your first TileDB programs.

Install TileDB

C++ API

First, grab a TileDB release for your system:

For more in-depth installation information, see the Installation page.

Compiling TileDB programs

In the remainder of this quickstart and the tutorials to follow, you will learn how to create TileDB programs using the language API of your choice. To compile and run a TileDB program called my_tiledb_program.cc using the C++ API:

$ g++ -std=c++11 my_tiledb_program.cc -o my_tiledb_program -ltiledb
$ ./my_tiledb_program

If you run into compilation issues, see the Usage page for more complete instructions on how to compile and link against TileDB. If you are on Windows, use the Windows usage instructions to create a Visual Studio project instead.

Python API

A working TileDB Python system can be installed with pip:

$ pip install tiledb

This will automatically download and build the core TileDB library in addition to the Python bindings, so it may take a while.

To use TileDB-Py in a program, simply import the TileDB Python module:

import tiledb

And run your program as usual:

$ python my_tiledb_program.py

R API

TileDB needs to be installed. After the core library is installed, the R source package can be installed and built with devtools:

install.packages("devtools")
library(devtools)
devtools::install_github("TileDB-Inc/TileDB-R@latest")

To use the TileDB-R package, simply import the installed R library in your R script or REPL:

library(tiledb)

To run a TileDB-R script:

$ Rscript my_tiledb_program.R

Golang API

TileDB needs to be installed. After the core library is installed the Go api can be installed with go get:

$ go get -v github.com/TileDB/TileDB-Go

This will automatically download and build the Go API bindings and link to the core library.

To use the TileDB Go API, simply import the installed Go library in your Go source file:

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

And run your program as usual:

$ go run my_tiledb_program.go

A Simple Dense Array Example

First let’s create a simple 4x4 dense array, i.e., with two dimensions (called rows and cols), each with domain [1,4]. This array has a single int attribute, i.e., it will store integer values in its cells.

Next we populate the array by writing some values to its cells, specifically 1, 2, …, 16 in a row-major layout (i.e., the columns of the first row will be populated first, then those of the second row, etc.).

The resulting array is depicted in the figure below. Finally, we will read a portion of the array (called slicing) and simply output the contents of the selected cells on the screen. Suppose we wish to read subarray [1,2], [2,4], i.e., focus on the cells in rows 1, 2 and columns 2, 3, 4. The result values should be 2 3 4 6 7 8, reading again in row-major order (i.e., first the three selected columns of row 1, then the three selected columns of row 2).

_images/quickstart_dense.png

A 4x4 dense array, highlighting subarray [1:2,2:4]

If you run the example, you should see the following output:

A Simple Sparse Array Example

First let’s create a simple 4x4 sparse array, i.e., with two dimensions (called rows and cols), each with domain [1,4]. This array has a single int attribute, i.e., it will store integer values in its cells.

Next we populate the array by writing some values to its cells, specifically 1, 2, and 3 at cells (1,1), (2,4) and (2,3), respectively. Notice that, contrary to the dense case, here we specify the exact indices where the values will be written, i.e., we provide the cell coordinates. Do not worry about the “unordered” query layout for now, just know that it is important.

The resulting array is depicted in the figure below. Similar to the dense array example, we read subarray [1,2], [2,4], i.e., focus on the cells in rows 1, 2 and columns 2, 3, 4. The result values should be 3 for cell (2,3) and 2 for cell (2,4) reading again in row-major order.

_images/quickstart_sparse.png

A 4x4 sparse array, highlighting subarray [1:2,2:4]

One of the most challenging issues when using the C++ API is estimating how large the result of a read query on a sparse array is, so that you know how much space to allocate for your buffers, and how to parse the result (this was not an issue in the dense case). TileDB offers several utility functions in the C++ API to help deal with this issue; read through the “Tutorial” sections for the details. The Python API takes care of this issue for you automatically.

If you run the example, you should see the following output:

Links to full programs

Program

Links

quickstart_sparse

quickstartsparsecpp quickstartsparsepy quickstartsparser quickstartsparsego

A Simple Key-Value Example

Warning

Key-value arrays are not yet supported for the Go or R APIs.

First let’s create a simple map with a single integer attribute.

Note

Currently the Python key-value API only supports string-valued attributes. The C and C++ APIs support any attribute type for key-value arrays.

Next we populate the map with 3 key-value pairs: "key_1": 1, "key_2": 2 and "key_3": 3.

Finally, we read the data back using the keys and print them on the screen.

If you run the example, you should see the following output:

Links to full programs

Program

Links

quickstart_kv

quickstartkvcpp quickstartkvpy

Further reading

This quickstart omits discussion of several important concepts such as tiling, cell/tile layouts, types of write and read queries, memory management, and many more exciting topics. To learn more about these subjects, read through the “Tutorial” sections that cover all the TileDB concepts and functionality in great depth.