This vignette will provide an overview of key functionality. Other vignettes will focus on specific topics in detail including how-to examples.
R6.tiledb offers TileDBArray and TileDBGroup R6 objects that represent a
TileDB array and group respectively. These objects have minimum encapsulated
functionality so they can be further extended and used by other packages.
The package also offers expanded versions built on top of the above classes and
can be accessed via the functional wrappers tdb_array() and tdb_group().
Use tdb_group_create() to create a group and instantiate the TileDBGroupExp
object.
# group uri
uri_root <- tempfile()
# create a group
grp <- tdb_group_create(uri_root)
# check if created
grp$exists()
# [1] TRUE
Checking for members:
# no members (empty list)
grp$members
# list()
# count members
grp$count_members()
# [1] 0
# group's uri path
grp$uri
# [1] "C:\\Users\\cgiac\\AppData\\Local\\Temp\\RtmpqCes68\\file76f8729a43ad"
Create two arrays with URI paths relative to group.
tdb_array_create() is a convenient way to create an array given a schema and instantiate a TileDBArrayExp object.
# array uri
uri_array1 <- file.path(grp$uri, "array_1")
schema <- tiledb::tiledb_array_schema(
dom = tiledb::tiledb_domain(
dims = tiledb::tiledb_dim("id", c(1L, 4L), 4L, "INT32")),
attrs = tiledb::tiledb_attr("model", type = "ASCII")
)
# create array_1
arrobj_1 <- tdb_array_create(uri_array1, sch = schema)
# array uri
uri_array2 <- file.path(grp$uri, "array_2")
# demo array
demo_array_UCBAdmissions(uri_array2)
# create array_2
arrobj_2 <- tdb_array(uri_array2)
Having created a TileDB group and two arrays, we can organise everything as a collection by adding the above arrays as group members:
# add array_1
grp$set_member(arrobj_1)
# add array_2
grp$set_member(arrobj_2)
# reopen to READ mode
grp$reopen()
Checking for members:
# members names
grp$names()
# [1] "array_1" "array_2"
# count members
grp$count_members()
# [1] 2
Print group structure:
# dump raw string
grp$dump()
#
# ── TileDB Directory ─────────────────────────────────────────────────────────────────
#
# -> file76f8729a43ad GROUP
# |-- array_1 ARRAY
# |-- array_2 ARRAY
# print
grp
# R6Class: <TileDBGroupExp>
# → URI Basename: file76f8729a43ad
# • Arrays: "array_1" and "array_2"
# get array_1
arr1 <- grp$get_member("array_1")
# print
arr1
# R6Class: <TileDBArray>
# → URI Basename: array_1
# • Dimensions: "id"
# • Attributes: "model"
Let’s remove array_1 from group (but do not delete it from disk).
# reopen group in WRITE mode
grp$reopen("WRITE")
# remove array
grp$remove("array_1")
# print
grp
# R6Class: <TileDBGroupExp>
# → URI Basename: file76f8729a43ad
# • Arrays: "array_2"
List all TileDB resources at group’s uri path:
# Find all TileDB resources (members and non-members)
grp$walk_group()
# TYPE
# 1 ARRAY
# 2 ARRAY
# URI
# 1 file:///C:/Users/cgiac/AppData/Local/Temp/RtmpqCes68/file76f8729a43ad/array_1
# 2 file:///C:/Users/cgiac/AppData/Local/Temp/RtmpqCes68/file76f8729a43ad/array_2
Checking group folder for non-members:
# check for non-members
grp$has_non_members()
# [1] TRUE
# data.frame with non-members info
grp$non_members()
# TYPE
# 1 ARRAY
# URI
# 1 file:///C:/Users/cgiac/AppData/Local/Temp/RtmpqCes68/file76f8729a43ad/array_1
Now delete group non-members:
# delete non-members
grp$prune_non_members()
# [1] "file:///C:/Users/cgiac/AppData/Local/Temp/RtmpqCes68/file76f8729a43ad/array_1"
# data.frame with non-members info
grp$non_members()
# [1] TYPE URI
# <0 rows> (or 0-length row.names)
You can work with metadata, both for arrays and group, in two ways: 1. using the
OO interface via $get_metadata() and $set_metadata() and 2. using the functional
interface with S3 methods:
# set a single key metadata
metadata(grp, "description") <- "metadata value"
# set multiple metadata
set_metadata(grp, list("a" = 1, "b" = 2))
# get a key metadata
metadata(grp, "a")
# [1] 1
# fetch all metadata
fetch_metadata(grp)
# TileDB GROUP: <R6 Class: TileDBGroupExp>
# Metadata: <key,value> • total 3
# • a: 1
# • b: 2
# • description: 'metadata value'
# fetch a subset of metadata
fetch_metadata(grp, c("a", "b"))
# TileDB GROUP: <R6 Class: TileDBGroupExp>
# Metadata: <key,value> • total 2
# • a: 1
# • b: 2
# delete metadata
metadata(grp, "description") <- NULL
# delete multiple keys
delete_metadata(grp, c("a", "b"))
# fetch all metadata (none)
fetch_metadata(grp)
# TileDB GROUP: <R6 Class: TileDBGroupExp>
# Metadata: <key,value> • total 0
Using either TileDBArray or TileDBArrayExp makes it easier to work with
arrays:
# schema info
arrobj_2$schema_info()
# names types status enum
# 1 Dept ASCII Dim FALSE
# 2 Gender ASCII Dim FALSE
# 3 Admit INT32 Attr TRUE
# 4 Freq FLOAT64 Attr FALSE
# Has factor columns
arrobj_2$has_enumeration()
# Admit Freq
# TRUE FALSE
# fragments
arrobj_2$frag_num()
# [1] 3
# schema version
arrobj_2$schema_version
# [1] 22
You can built queries by using the underlying array object accessed by active
field $object and then using the standard tiledb interface or use the $tiledb_array()
that opens a separate array handle which invokes the tiledb::tiledb_array().
arr <- arrobj_2$object
tiledb::selected_points(arr) <- list(Dept = "A")
tiledb::return_as(arr) <- "data.frame"
arr[]
# Dept Gender Admit Freq
# 1 A Female Rejected 19
# 2 A Female Admitted 89
# 3 A Male Rejected 313
# 4 A Male Admitted 512
Using separate array handle:
arr <- arrobj_2$tiledb_array(selected_points = list(Dept = "A"),
return_as = "data.frame")
arr[]
# Dept Gender Admit Freq
# 1 A Female Rejected 19
# 2 A Female Admitted 89
# 3 A Male Rejected 313
# 4 A Male Admitted 512
R6.tiledb has dedicated R6 object TileDBFragments to work with fragments.
It can be accessed either from TileDBArrayExp ’s fragments_object field
or via its wrapper tdb_fragments().
# fragment object
fobj <- arrobj_2$fragments_object
# or directly
fobj <- tdb_fragments(arrobj_2$uri)
# last i fragments
fobj$get_last_ifragments(1)
# ── FRAGMENT #3 ──────────────────────────────────────────────────────────────────────
# ❯ URI: file:///C:/Users/cgiac/AppData/Local/Temp/RtmpqCes68/file76f8729a43ad/array_2/__fragments/__1777273939473_1777273939473_407e9076598713d27479d8a7f2e2e4cc_22
# ❯ Type: sparse
# ❯ Non-empty domain:
# • Dept: [E, F] (ASCII)
# • Gender: [Female, Male] (ASCII)
# ❯ Size: 5.24 KiB
# ❯ Cell num: 8
# ❯ Timestamp range: [2026-04-27 07:12:19.473 UTC, 2026-04-27 07:12:19.473 UTC]
# ❯ Format version: 22
# ❯ Has consolidated metadata: FALSE
TileDBArrayExp class encapsulates consolidation and vacuum operations, either
stand-alone or combined and with asynchronous variations (provided the mirai
package is found in your system).
# consolidate
arrobj_2$consolidate()
# num fragments
arrobj_2$frag_num()
# [1] 1
# consolidated fragments to be removed
arrobj_2$frag_to_vacuum(trunc_uri = TRUE)
# Fragment start_timestamp end_timestamp
# <char> <POSc> <POSc>
# 1: #1 2026-04-27 07:12:19 2026-04-27 07:12:19
# 2: #2 2026-04-27 07:12:19 2026-04-27 07:12:19
# 3: #3 2026-04-27 07:12:19 2026-04-27 07:12:19
# URI
# <char>
# 1: __1777273939379_1777273939379_73fd5716dc24bce1dda05b5fdb08fa9b_22
# 2: __1777273939430_1777273939430_7e2872403cce876733c460478df7b5b6_22
# 3: __1777273939473_1777273939473_407e9076598713d27479d8a7f2e2e4cc_22
# refresh fragment object
fobj$reload_finfo()
# fragment for clean up (vacuum)
fobj$to_vacuum_num()
# [1] 3
# vacuum
arrobj_2$vacuum()
# consolidated fragments to be removed
arrobj_2$frag_to_vacuum() # none
# [1] Fragment start_timestamp end_timestamp URI
# <0 rows> (or 0-length row.names)
Inspect array directory
arrobj_2$dir_tree()
# C:/Users/cgiac/AppData/Local/Temp/RtmpqCes68/file76f8729a43ad/array_2
# ├── __commits
# │ └── __1777273939379_1777273939473_07f1ddbf115412a34f5e81ae762c4a17_22.wrt
# ├── __fragments
# │ └── __1777273939379_1777273939473_07f1ddbf115412a34f5e81ae762c4a17_22
# │ ├── a0.tdb
# │ ├── a1.tdb
# │ ├── d0.tdb
# │ ├── d0_var.tdb
# │ ├── d1.tdb
# │ ├── d1_var.tdb
# │ ├── t.tdb
# │ └── __fragment_metadata.tdb
# ├── __fragment_meta
# ├── __labels
# ├── __meta
# └── __schema
# ├── __1777273939359_1777273939359_2b1451af1fd1cb9a8a81fb10ba8dcbe7
# └── __enumerations
# └── __2b1451ae8c4d64489db3e28a6e7f5046_0
#
# ❯ directories (6) • total size (6.77 KiB)
Get fragment info
fobj$get_ifragment(1)
# ── FRAGMENT #1 ──────────────────────────────────────────────────────────────────────
# ❯ URI: file:///C:/Users/cgiac/AppData/Local/Temp/RtmpqCes68/file76f8729a43ad/array_2/__fragments/__1777273939379_1777273939473_07f1ddbf115412a34f5e81ae762c4a17_22
# ❯ Type: sparse
# ❯ Non-empty domain:
# • Dept: [A, F] (ASCII)
# • Gender: [Female, Male] (ASCII)
# ❯ Size: 6.36 KiB
# ❯ Cell num: 24
# ❯ Timestamp range: [2026-04-27 07:12:19.378999 UTC, 2026-04-27 07:12:19.473000 UTC]
# ❯ Format version: 22
# ❯ Has consolidated metadata: FALSE