Introduction

TileDB provides the Universal Data Engine that can be accessed in a variety of ways. The C/C++ library offered by TileDB Embedded is one approach, and the R package, as well as the Python package and other language bindings use it. Another interface is provided by the MariaDB Integration via the MyTile storage plugin.

This provides TileDB integration with any frontend that interfaces with MariaDB—such as the RMariaDB package for R. So this vignette illustrates the use of TileDB via MariaDB using R and the RMariaDB packages.

Installation or Using Docker

In order to use the MyTile storage plugin, one has to compile both the storage plugin itself and the MariaDB server with consistent compiler flags. As the build also requires the TileDB Embedded library and headers, using a Docker container may be easiest. The Dockerfile also provides a concrete example of the build setup.

So here we will use the tiledb/tiledb-mariadb-r container.

Launch Container in Background

We launch the container ‘tiledb/tiledb-mariadb-r’ as a daemon, allowing MariaDB to accept an empty password (using an older MySQL variable setting), and name the running image ‘tiledb-mariadb-r’:

docker run --name tiledb-mariadb-r -it -d --rm -e MYSQL_ALLOW_EMPTY_PASSWORD=1 tiledb/tiledb-mariadb-r

Access Container Once to Write via TileDB

Using the name given to the running instance, we start an R session to write data with TileDB:

docker exec -it -u root tiledb-mariadb-r R

Examples

Palmer Penguins

With the sessions started as in the previous section, we start an R session.

> library(tiledb)
> library(palmerpenguins)
> praw <- penguins_raw
> fromDataFrame(praw, "/tmp/penguinsraw")

Access Container Again to Read via RMariaDB

In another shell, we can access the container once more and launch another R process:

docker exec -it -u root tiledb-mariadb-r R

where we use RMariaDB to access the data via a tibble object and magrittr pipe

> library(RMariaDB)
> library(dplyr, warn.conflicts=FALSE)
> con <- DBI::dbConnect(RMariaDB::MariaDB(), dbname="test")
> tbl(con, "/tmp/penguinsraw") %>%
+        dplyr::select(contains("Length"))
# Source:   lazy query [?? x 2]
# Database: mysql [@localhost:NA/test]
   `Culmen Length (mm)` `Flipper Length (mm)`
                  <dbl>                 <dbl>
 1                 39.1                   181
 2                 39.5                   186
 3                 40.3                   195
 4                 NA                      NA
 5                 36.7                   193
 6                 39.3                   190
 7                 38.9                   181
 8                 39.2                   195
 9                 34.1                   193
10                 42                     190
# ... with more rows

Note that this R session uses TileDB only via the MyTile plugin which is activated implicitly via the ‘table location’ (here /tmp/penguinsraw) of the test database enabling plugins.

Also note that the query is still ‘lazy’: only column names and the first ten observations have been retrieved, and the total size is still unknown as indicated by lazy query [?? x 2]. Adding a collect() verb materialized the full subset.

> tbl(con, "/tmp/penguinsraw")  %>%
+     dplyr::select(contains("Length")) %>%
+     collect()
# A tibble: 344 x 2
   `Culmen Length (mm)` `Flipper Length (mm)`
                  <dbl>                 <dbl>
 1                 39.1                   181
 2                 39.5                   186
 3                 40.3                   195
 4                 NA                      NA
 5                 36.7                   193
 6                 39.3                   190
 7                 38.9                   181
 8                 39.2                   195
 9                 34.1                   193
10                 42                     190
# ... with 334 more rows
>

We now see that all 344 rows of this particular result set have been accessed.

Similarly, we can also run summaries on selected column:

> tbl(con, "/tmp/penguinsraw") %>%
+     group_by(Species) %>%
+     summarise(across(starts_with("Flipper"),
+                      list(~mean(.x, na.rm=TRUE), ~sd(.x, na.rm=TRUE))))
# Source:   lazy query [?? x 3]
# Database: mysql [@localhost:NA/test]
  Species              `\`Flipper Length (mm)\`_~me~ `\`Flipper Length (mm)\`_~~
  <chr>                                        <dbl>                       <dbl>
1 Adelie Penguin (Pyg~                          190.                        6.54
2 Chinstrap penguin (~                          196.                        7.13
3 Gentoo penguin (Pyg~                          217.                        6.48
>

DBI

We can connect directly using the DBI package along with the RMariaDB package and its MyTile bindings:

library(DBI)
con <- dbConnect(RMariaDB::MariaDB(), dbname="test")
res <- dbSendQuery(con, "select * from `/work/penguins` as `q91` limit 10")
df <- dbFetch(res, n = 10)
dbClearResult(res)
print(df)
dbDisconnect(con)

S3

When using Docker, the container setup needs to be modified to include the required AWS access environment variables:

docker run --name tiledb-mariadb-r \
       -it -d --rm \
       -v $PWD:/work -w /work \
       -e MYSQL_ALLOW_EMPTY_PASSWORD=1 \
       -e AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY} \
       -e AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID} \
       tiledb/tiledb-mariadb-r

This exports the current working directory (accessed as $PWD in the shell) as /work inside the container (via the -v switch), and instructs the container to start in directory /work (via the -w switch).

In the following example we also set a TileDB configuration option to switch AWS regions.

> library(dplyr, warn.conflicts=FALSE)
> # connect as usual
> con <- DBI::dbConnect(RMariaDB::MariaDB(), dbname="test")
> # use connection to update config in order to switch s3 regions
> res1 <- DBI::dbSendQuery(con, "set mytile_tiledb_config=\"vfs.s3.region=us-west-1\";")
> DBI::dbClearResult(res1)
> # run simple query
> tbl(con, "s3://tiledb-public-us-west-1/test-array-4x4") %>% collect()
# A tibble: 16 x 3
   `__dim_0` `__dim_1` `__attr`
     <int64>   <int64>    <dbl>
 1         0         0   0.397
 2         0         1   0.432
 3         0         2   0.617
 4         0         3   0.403
 5         1         0   0.837
 6         1         1   0.670
 7         1         2   0.235
 8         1         3   0.841
 9         2         0   0.222
10         2         1   0.468
11         2         2   0.970
12         2         3   0.551
13         3         0   0.628
14         3         1   0.0149
15         3         2   0.0540
16         3         3   0.445
>
> DBI::dbDisconnect(con)  # close connection

NYC Taxis

We can write the New York taxi data into TileDB (in the current directory) after reading it as a csv:

> nyc <- data.table::fread("trip_data_1.csv")
> tiledb::fromDataFrame(nyc, "trip_data_1")

Then we can access it via the path /work/trip_data_1 via RMariaDB.

> library(dplyr, warn.conflicts=FALSE)
> con <- DBI::dbConnect(RMariaDB::MariaDB(), dbname="test")
> # list column names
> tbl(con, "/work/trip_data_1") %>% colnames()
> tbl(con, "/work/trip_data_1") %>% colnames()
 [1] "__tiledb_rows"      "dropoff_latitude"   "medallion"
 [4] "hack_license"       "dropoff_longitude"  "vendor_id"
 [7] "rate_code"          "store_and_fwd_flag" "pickup_datetime"
[10] "dropoff_datetime"   "trip_time_in_secs"  "pickup_latitude"
[13] "passenger_count"    "trip_distance"      "pickup_longitude"
> # extract one column (here passenger_count) completely and tabulate in R
> tbl(con, "/work/trip_data_1") %>% select(passenger_count) %>% collect() %>% table()
.
       0        1        2        3        4        5        6        9
     166 10471701  1986196   597485   280992   920006   520066        1
     208      255
       1        1
> # alternatively, run a lazy query
> tbl(con, "/work/trip_data_1") %>% group_by(passenger_count) %>% summarize(nobs = n())
# Source:   lazy query [?? x 2]
# Database: mysql [@localhost:NA/test]
   passenger_count     nobs
             <int>  <int64>
 1               0      166
 2               1 10471701
 3               2  1986196
 4               3   597485
 5               4   280992
 6               5   920006
 7               6   520066
 8               9        1
 9             208        1
10             255        1
> # here the request is actually sent as SQL and the computation is done in the SQL layer
> tbl(con, "/work/trip_data_1")  %>%
+      group_by(passenger_count) %>%
+      summarize(nobs = n())     %>%
+      show_query()
<SQL>
SELECT `passenger_count`, COUNT(*) AS `nobs`
FROM `/work/trip_data_1`
GROUP BY `passenger_count`
> # naturally we can also send the query directly to the SQL backend
> sql <- "SELECT passenger_count, count(*) AS n FROM `/work/trip_data_1` GROUP BY passenger_count;"
> DBI::dbGetQuery(con, sql)
   passenger_count        n
1                0      166
2                1 10471701
3                2  1986196
4                3   597485
5                4   280992
6                5   920006
7                6   520066
8                9        1
9              208        1
10             255        1
>
> DBI::dbDisconnect(con)  # close connection

Summary

This short vignette demonstrates the use of TileDB-stored data from R using RMariaDB via the MyTile storage extension to MariaBD.