Groups

Creating TileDB Groups

TileDB allows you to hierarchically organize your arrays in groups. A group is a directory with a __tiledb_group.tdb marker file and additional folders containing metadata and group-member URIs; see here for further description of the contents and layout. This offers an intuitive and familiar way to store your various TileDB objects in persistent storage. You can create a group simply as follows:

C

// ... create context ctx

// Create group
tiledb_group_create(ctx, "my_group");

C++

// ... create context ctx

create_group(ctx, "my_group");

Python

tiledb.group_create("my_group")

R

# All TileDB-supported URIs (local, cloud, ...) work
uri <- "my_group"
tiledb_group_create(uri)

Java

// ... create context ctx
Group.create(ctx, "test_group");

Go

// ... create context ctx

// Create group
tiledb.GroupCreate(ctx, "my_group");

You can hierarchically organize TileDB groups similar to your filesystem directories, i.e., groups can be arbitrarily nested in other groups.

Using Group Metadata

Python

# open the group for reading
with tiledb.Group(URI) as g:
    # g.meta is a dictionary
    # get value:
    g.meta[key] # -> value

# open the group for writing
with tiledb.Group(URI, "w") as g:
    # set value:
    g.meta[key] = value
    
    del g.meta[key]

R

grp <- tiledb_group(uri, "WRITE")
# insert metadata (and assign boolean result to local variable)
rc <- tiledb_group_put_metadata(grp, "key1", 42L)
rc <- tiledb_group_put_metadata(grp, "key2", 1.2345)
rc <- tiledb_group_put_metadata(grp, "key3", "the quick brown fox")

# close group and reopen to read
grp <- tiledb_group_close(grp)
grp <- tiledb_group_open(grp, "READ")

# metadata can be checked
true_value <- tiledb_group_has_metadata(grp, "key1")
false_value <- tiledb_group_has_metadata(grp, "missing_key")
# number of objects can be retrieved
n <- tiledb_group_metadata_num(grp)
# and values can be accessed by name or position (zero-indexed)
val1 <- tiledb_group_get_metadata(grp, "key1")
val2 <- tiledb_group_get_metadata_from_index(grp, 1)

Java

// Add metadata
Group.create(ctx, "test_group");

Group group = new Group(ctx, "test_group", TILEDB_WRITE);

NativeArray intArray = new NativeArray(ctx, new int[] {7, 1, 3, 2}, Datatype.TILEDB_INT32);
NativeArray stringArray = new NativeArray(ctx, "test", Datatype.TILEDB_STRING_ASCII);

group.putMetadata("key1", intArray);
group.putMetadata("key2", stringArray);

// close group and reopen in read mode
group.reopen(ctx, TILEDB_READ);

// Get metadata number
BigInteger num = group.getMetadataNum();

// Read metadata
NativeArray metadataIntArray = group.getMetadata("key1", Datatype.TILEDB_INT32);
NativeArray metadataStringArray = group.getMetadata("key2", Datatype.TILEDB_STRING_ASCII);
    
int[] key1Values = (int[]) metadataIntArray.toJavaArray();
byte[] key2Values = (byte[]) metadataStringArray.toJavaArray();

// Vacuum/Consolidate metadata
group.consolidateMetadata(ctx.getConfig());
group.vacuumMetadata(ctx.getConfig());

Add/Remove Members

TileDB Arrays act like group members. They can be added or removed in the following way:

Java

// Create some test members
arrayCreate("array1");
arrayWrite("array1");

arrayCreate("array2");
arrayWrite("array2");

arrayCreate("array3");
arrayWrite("array3");

// Create a group and open in WRITE mode
Group.create(ctx, "test_group");
Group group = new Group(ctx, "test_group", TILEDB_WRITE);

// Add members
group.addMember("array1", false, "array1Name");
group.addMember("array2", false, "array2Name");
group.addMember("array3", false, "array3Name");

// Remove members
group.removeMember("array2");
group.removeMember("array3Name");

// Reopen group in READ mode
group.reopen(ctx, QueryType.TILEDB_READ);
long members = group.getMemberCount();

R

# Arrays can be added (or removed) as group members
# Here we create four (very simple) arrays at four URIs
uri1 <- file.path(uri, "arr1")
uri2 <- file.path(uri, "arr2")
uri3 <- file.path(uri, "arr3")
uri4 <- file.path(uri, "arr4")
fromDataFrame(data.frame(val=seq(100, 200, by=10)), uri1)
fromDataFrame(data.frame(letters=letters), uri2)
fromDataFrame(data.frame(dat=c(1.1, 2.2, 3.3)), uri3)
fromDataFrame(data.frame(txt=c("the","quick","brown","fox")), uri4)

grp <- tiledb_group_close(grp)
grp <- tiledb_group_open(grp, "WRITE")
# Add using absolute URL uri1
grp <- tiledb_group_add_member(grp, uri1, FALSE)
# Add using relative URL, with optional name
grp <- tiledb_group_add_member(grp, "arr2", TRUE)
grp <- tiledb_group_add_member(grp, "arr3", TRUE, "array_three")
grp <- tiledb_group_add_member(grp, "arr4", TRUE)
# Remove members
grp <- tiledb_group_close(grp)
grp <- tiledb_group_open(grp, "MODIFY_EXCLUSIVE")

tiledb_group_remove_member(grp, uri1)            # remove by absolute URI
tiledb_group_remove_member(grp, "arr2")          # remove by relative URI
tiledb_group_remove_member(grp, "array_three")   # remove /by name (if given)
grp <- tiledb_group_close(grp)

# open again to read, now 
grp <- tiledb_group_open(grp, "READ")
n <- tiledb_group_member_count(grp)
n

Get Members

Java

// Get the URI of a member of a group by name
String uri = group.getMemberByName("array")

R

# Get member by number (now index zero as only one element remains
# The indexing is zero based for consistency with the C++ API
# Returns vector with elements type, uri and optional name (or empty string)
vec <- tiledb_group_member(grp, 0)