Utilities

The TileDB Cloud client offer several useful utilities. To use them, you must have the client installed (see Installation).

Login Sessions

TileDB Cloud allows you to login (with your username/password or API token) in a way such that the session token can be cached to avoid logging in again for every program execution. This is done as follows:

Python
# With username/password
tiledb.cloud.login(username='xxx', password='xxx')
# Or, with token
tiledb.cloud.login(token='xxx')

After logging in for the first time, the TileDB Cloud client will store a session token in configuration file $HOME/.tiledb/cloud.jsoncreated in your home directory.

Helper TileDB Cloud Context / Config

There are two helper functions that allow to easily create a tiledb config or context that has the proper configuration needed for slicing arrays through TileDB Cloud.

Python
# Create a TileDB Config object with `rest.token` set from the login
cfg = tiledb.cloud.Config()
# Create a TileDB Context which has a configuration object with `rest.token` set
# from the login
ctx = tiledb.cloud.Ctx()

Viewing the User Profile

You can see your user profile as follows:

Python
prof = tiledb.cloud.user_profile()
print(prof)

Listing Arrays

You can list arrays from the cloud service, passing a variety of filters:

Python
# List all arrays you have access to, including public ones
# Set `include_public=False` to exclude public arrays
all_arrays = tiledb.cloud.list_arrays(include_public=True)
print(all_arrays)
# List arrays in a specific namespace
tiledb_inc_arrays = tiledb.cloud.list_arrays(namespace="TileDB-Inc"
include_public=True)
print(tiledb_inc_arrays)
# Filter arrays to only those you have read and write permissions to
rw_arrays = tiledb.cloud.list_arrays(permissions=["read", "write"])
print(rw_arrays)
# Combine all filters
arrays = tiledb.cloud.list_arrays(include_public=True,
namespace="TileDB-Inc",
permissions=["read"])
print(arrays)

Getting Basic Array Information

You can run the following to get basic information about the array, such as its description:

Python
info = tiledb.cloud.info("tiledb://TileDB-Inc/quickstart_sparse")
print(info)

Array Activity

Array activity can also be fetched programmatically as follows:

Python
activity = tiledb.cloud.array_activity("tiledb://TileDB-Inc/quickstart_sparse")
print(activity)

Listing Tasks

You can list tasks from the cloud service, passing a variety of filters:

Python
# List all tasks
all_tasks = tiledb.cloud.tasks()
print(all_tasks)
# List only tasks on a specific array
array_tasks = tiledb.cloud.tasks(array="tiledb://TileDB-Inc/quickstart_sparse")
print(array_tasks)
# Lists tasks within a specific time period
import datetime
ninety_days_ago = datetime.datetime.utcnow() - datetime.timedelta(days=90)
datetime_tasks = tiledb.cloud.tasks(array="tiledb://TileDB-Inc/quickstart_sparse",
start=ninety_days_ago)
print(datetime_tasks)
# Filter tasks by status, valid statuses are RUNNING, FAILED, COMPLETED
running_tasks = tiledb.cloud.tasks(status="RUNNING")
print(running_tasks)

For convenience, you can also see the last SQL or UDF task:

Python
# Get last SQL task
tiledb.cloud.last_sql_task()
# Get last UDF task
tiledb.cloud.last_udf_task()

Or you can get a specific task with a given task ID (which can be found on the UI console):

Python
task = tiledb.cloud.task(id='xxx')

Registering an Array

In addition to registering S3-stored TileDB arrays with TileDB cloud via the console, you can also do it programmatically as follows:

Python
tiledb.cloud.register_array(uri="s3://mybucket/myarray",
namespace="user1", # You may register it under your username, or one of your organizations
array_name="myarray",
description=None,
access_credentials_name="myCredentials") # You must have already added your AWS credentials on the console

Deregistering an Array

You can deregister an array as follows (remember, this will not physically delete your array):

Python
tiledb.cloud.deregister_array("tiledb://user1/myarray")

Sharing Arrays

You can programmatically share a registered array, "unshare" a registered array (i.e., revoke access) and list array sharing information as follows:

Python
# Share an array with both read and write permissions with a user
tiledb.cloud.share_array(uri="tiledb://user1/myarray",
namespace="user1", # The user to share the array with
permissions=["read", "write"])
# Revoke access to an array for a particular user
tiledb.cloud.unshare_array(uri="tiledb://user1/myarray", namespace="user1")
# Get sharing information about an array
shared_with = tiledb.cloud.list_shared_with("tiledb://user1/myarray")
print(shared_with)