Object Management

A TileDB "object" is currently either a TileDB array or a TileDB group. This page describes the supported functionality for managing TileDB objects.

Creating TileDB Groups

TileDB allows you to hierarchically organize your arrays in groups. A group is practically a directory with a special (empty) TileDB file __tiledb_group.tdb. 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
C++
Python
R
Java
Go
// ... create context ctx
// Create group
tiledb_group_create(ctx, "my_group");
// ... create context ctx
create_group(ctx, "my_group");
tiledb.group_create("my_group")
# ... create context ctx
tiledb_group_create(ctx, "my_group")
// ... create context ctx
Group group = new Group(ctx, "my_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.

Getting the Object Type

TileDB also allows you to check the object type as follows. If the provided path does not exist or is not a TileDB array or group, it is marked as “invalid”.

C
C++
Python
R
Java
Go
// ... create context ctx
tiledb_object_t type;
tiledb_object_type(ctx, "<path>", &type);
// ... create context ctx
auto obj_type = Object::object(ctx, "<path>").type();
type = tiledb.object_type(path)
# ... create context ctx
type <- tiledb_object_type(ctx, "<path>")
// ... create context ctx
TileDBObjectType obj_type = new Object(ctx, "<path>").getType();
// TODO: Currently not supported in Go
C/C++/Java/Go
Python
R

TileDB Object

Description

TILEDB_INVALID

Invalid object

TILEDB_GROUP

A TileDB group

TILEDB_ARRAY

A TileDB array

TileDB Object

Description

None

Invalid object

"group"

A TileDB group

"array"

A TileDB array

TileDB Object

Description

INVALID

Invalid object

GROUP

A TileDB group

ARRAY

A TileDB array

Listing the Object Hierarchy

TileDB offers various ways to list the contents of a group, even recursively in pre-order or post-order traversal, optionally passing a special callback function that will be invoked for every visited object. This is demonstrated in the code snippet below:

C
C++
Python
R
Java
Go
// Helper function to print a path and its type
int print_path(const char* path, tiledb_object_t type, void* data) {
// Simply print the path and type
(void)data;
printf("%s ", path);
switch (type) {
case TILEDB_ARRAY:
printf("ARRAY");
break;
case TILEDB_GROUP:
printf("GROUP");
break;
default:
printf("INVALID");
}
printf("\n");
// Always iterate till the end
return 1;
}
// ... create context ctx
// List children
tiledb_object_ls(ctx, path, print_path, NULL);
// Walk in a path with a pre-order traversal
tiledb_object_walk(ctx, path, TILEDB_PREORDER, print_path, NULL);
// Walk in a path with a post-order traversal
tiledb_object_walk(ctx, path, TILEDB_POSTORDER, print_path, NULL);
// Helper function to print a path and its type
void print_path(const std::string& path, tiledb::Object::Type type) {
std::cout << path << " ";
switch (type) {
case tiledb::Object::Type::Array:
std::cout << "ARRAY";
break;
case tiledb::Object::Type::Group:
std::cout << "GROUP";
break;
default:
std::cout << "INVALID";
}
std::cout << "\n";
}
// ... create context ctx
// List children
tiledb::ObjectIter obj_iter(ctx, path);
for (const auto& object : obj_iter)
print_path(object.uri(), object.type());
// Walk in a path with a pre--order traversal
obj_iter.set_recursive(); // Default order is TILEDB_POSTORDER
for (const auto& object : obj_iter) {
print_path(object.uri(), object.type());
}
// Walk in a path with a post--order traversal
obj_iter.set_recursive(TILEDB_POSTORDER);
for (const auto& object : obj_iter)
print_path(object.uri(), object.type());
# List children
tiledb.ls(path, lambda obj_path, obj_type: print(obj_path, obj_type))
# Walk in a path with a pre-order traversal
tiledb.walk(path, lambda obj_path, obj_type: print(obj_path, obj_type)) # Default order is "preorder"
# Walk in a path with a pre- and post-order traversal
tiledb.walk(path, lambda obj_path, obj_type: print(obj_path, obj_type), "postorder")
# ... create context ctx
tiledb_object_walk("<uri>", ctx=ctx)
// ... create context ctx
// List children
System.out.println("List children: ");
TileDBObjectIterator obj_iter = new TileDBObjectIterator(ctx, path);
for (TileDBObject object : obj_iter.getAllObjects()) System.out.println(object);
// Walk in a path with a pre- and post-order traversal
System.out.println("\nPreorder traversal: ");
obj_iter.setRecursive(); // Default order is preorder
for (TileDBObject object : obj_iter.getAllObjects()) System.out.println(object);
System.out.println("\nPostorder traversal: ");
obj_iter.setRecursive(TILEDB_POSTORDER);
for (TileDBObject object : obj_iter.getAllObjects()) System.out.println(object);
// TODO: Currently not supported in Go

Move/Remove Objects

TileDB offers functions for renaming and removing TileDB objects. Note that these functions are “safe”, in the sense that they will not have any effect on “invalid” (i.e., non-TileDB) objects.

You can rename TileDB objects as follows:

C
C++
Python
R
Java
Go
// ... create context ctx
tiledb_object_move(ctx, "my_group", "my_group_2");
// ... create context ctx
tiledb::Object::move(ctx, "my_group", "my_group_2");
tiledb.move("my_group", "my_group_2")
# ... create context ctx
tiledb_object_mv("my_group", "my_group_2", ctx=ctx);
// ... create context ctx
TileDBObject.move(ctx, "my_group", "my_group2");
// TODO: Currently not supported in Go

Moving TileDB objects across different storage backends (e.g., from S3 to local storage, or vice-versa) is currently not supported. However, it will be added in a future version.

You can remove TileDB objects as follows:

C
C++
Python
R
Java
Go
// ... create context ctx
tiledb_object_remove(ctx, "my_group_2/dense_array");
// ... create context ctx
tiledb::Object::remove(ctx, "my_group_2/dense_array");
tiledb.remove("my_group_2/dense_array")
# ... create context ctx
tiledb_object_rm("my_group", "my_group_2", ctx=ctx);
// ... create context ctx
TileDBObject.remove(ctx, "my_group2/dense_arrays");
// TODO: Currently not supported in Go