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
).
If you run the example, you should see the following output:
Links to full programs¶
Program | Links |
quickstart_dense |
![]() ![]() ![]() ![]() |
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.
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 |
![]() ![]() ![]() ![]() |
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 |
![]() ![]() |
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.