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

// ... 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

# ... create context ctx

tiledb_group_create(ctx, "my_group")

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.

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

// ... create context ctx

tiledb_object_t type;
tiledb_object_type(ctx, "<path>", &type);

C++

// ... create context ctx

auto obj_type = Object::object(ctx, "<path>").type();

Python

type = tiledb.object_type(path)

R

# ... create context ctx

type <- tiledb_object_type(ctx, "<path>")

Java

// ... create context ctx

TileDBObjectType obj_type = new Object(ctx, "<path>").getType();

Go

	// ... create context ctx
	objType, _ := ObjectType(context, "<path>")

C/C++/Java/Go

TileDB Object	Description
TILEDB_INVALID	Invalid object
TILEDB_GROUP	A TileDB group
TILEDB_ARRAY	A TileDB array

Python

TileDB Object	Description
None	Invalid object
"group"	A TileDB group
"array"	A TileDB array

R

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

// 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);

C++

// 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());

Python

# 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")

R

# List arrays (defaults to default "PREORDER" traversal)
tiledb_object_ls(uri)

# Walk arrays (with "POSTORDER" traversal) returning a data.frame
res <- tiledb_object_walk("<uri>", "POSTORDER")

# Show the content
print(res)

Java

// ... 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);

Go

// ... create context ctx

GroupCreate(context, "groupPath")
GroupCreate(context, "groupPath/arrays")
NewArray(context, "groupPath/arrays/array1")

// List children
oL, _ = ObjectLs(context, "groupPath")
// oL[0].objectType == TILEDB_GROUP
// oL[0].path == "groupPath/arrays"

// Walk in a path with a pre-order traversal
oL, _ := ObjectWalk(context, "groupPath", TILEDB_PREORDER)
// len(oL) == 2
// oL[0].objectType == TILEDB_GROUP
// oL[1].objectType == TILEDB_ARRAY

// Walk in a path with a post-order traversal
oL, _ := ObjectWalk(context, "groupPath", TILEDB_POSTORDER)

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

// ... create context ctx

tiledb_object_move(ctx, "my_group", "my_group_2");

C++

// ... create context ctx

tiledb::Object::move(ctx, "my_group", "my_group_2");

Python

tiledb.move("my_group", "my_group_2")

R

# ... create context ctx

tiledb_object_mv("my_group", "my_group_2", ctx=ctx);

Java

// ... create context ctx
TileDBObject.move(ctx, "my_group", "my_group2");

Go

// ... create context ctx
ObjectMove(context, "my_group", "my_group_2")

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

// ... create context ctx

tiledb_object_remove(ctx, "my_group_2/dense_array");

C++

// ... create context ctx

tiledb::Object::remove(ctx, "my_group_2/dense_array");

Python

tiledb.remove("my_group_2/dense_array")

R

# ... create context ctx

tiledb_object_rm("my_group", "my_group_2", ctx=ctx);

Java

// ... create context ctx
TileDBObject.remove(ctx, "my_group2/dense_arrays");

Go

// ... create context ctx
ObjectRemove(context, "my_group_2/dense_array")