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:
// ... create context ctx
// Create group
tiledb_group_create(ctx, "my_group");
// ... create context ctx
create_group(ctx, "my_group");
tiledb.group_create("my_group")
# All TileDB-supported URIs (local, cloud, ...) work
uri <- "my_group"
tiledb_group_create(uri)
// ... create context ctx
Group.create(ctx, "test_group");
// ... 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
# 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]
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)
// 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:
// 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();
# 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
// Get the URI of a member of a group by name
String uri = group.getMemberByName("array")
# 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)
Last updated