Utilities

The TileDB Cloud client offers 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
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.
Retry Settings
The TileDB Cloud clients have the ability to retry failed HTTP requests automatically. By default this is enabled for retrying when TileDB Cloud indicates there is not enough capacity for the request (HTTP 503 errors). For convenience we also offer the ability to disable retries or to enable more forceful retry settings.
Built in modes
Python
Python
# Set default retry for only retrying "not enough capacity" responses
tiledb.cloud.client.client.retry_mode("default")
​
# Set do not retry any requests
tiledb.cloud.client.client.retry_mode("disabled")
​
# Retry for a large number of scenarios
tiledb.cloud.client.client.retry_mode("forceful")
​
In "forceful" mode it is possible that the client might retry requests which will always fail, such as when there is a syntax error in a SQL query. This mode should be used with care to avoid increased costs from retrying.
All built in modes (besides disabled) will retry a request up to 10 times.
Custom Retry Logic
It is also possible to manually set retry conditions to suite your needs.
Python
Python
from urllib3 import Retry
​
# Set the retries to a urllib3 retry object
tiledb.cloud.config.config.retries=Retry(
        total=10,
        backoff_factor=0.25,
        status_forcelist=[400, 500, 501, 502, 503],
        allowed_methods=["HEAD","GET","PUT","DELETE","OPTIONS","TRACE","POST","PATCH",],
        raise_on_status=False,
        remove_headers_on_redirect=[],
    )
    
# After updating the config make sure to update the package level clients
tiledb.cloud.client.client.update_clients()
Context and 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
Python
# Create a TileDB Config object with `rest.token` set from the login
cfg = tiledb.cloud.Config()
​
# Create a TileDB Context which has a config with `rest.token` set from the login
ctx = tiledb.cloud.Ctx()
Viewing the User Profile
You can see your user profile as follows:
Python
Python
prof = tiledb.cloud.user_profile()
print(prof)
Listing Arrays
You can list arrays from the cloud service, passing a variety of filters: 
Python
Python
# List all arrays you own
owned_arrays = tiledb.cloud.list_arrays()
print(owned_arrays)
​
# List all arrays that are shared with you
shared_arrays = tiledb.cloud.list_shared_arrays()
print(shared_arrays)
​
# List all public arrays
public_arrays = tiledb.cloud.list_public_arrays()
print(public_arrays)
​
# List arrays in a specific namespace
tiledb_inc_arrays = tiledb.cloud.list_arrays(namespace="TileDB-Inc")
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)
​
# You can combine filters
arrays = tiledb.cloud.list_arrays(namespace="TileDB-Inc", permissions=["read"])
print(arrays)
Getting Array Information
You can run the following to get basic information about the array, such as its description:
Python
Python
info = tiledb.cloud.info("tiledb://TileDB-Inc/quickstart_sparse")
print(info)
Array Activity
Array activity can be fetched programmatically as follows:
Python
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
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
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
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
Python
tiledb.cloud.register_array(uri="s3://mybucket/myarray",
                namespace="user1", # Optional, you may register it under your username, or one of your organizations
                array_name="myarray",
                description=None,  # Optional 
                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: 
Python
Python
tiledb.cloud.deregister_array("tiledb://user1/myarray")
Deregistering an array will not physically delete it.
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
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)
Automatic Region Redirection
While automatic compute region direction is in beta you will need to manually enable it for a query or request. Below is two examples of setting the server address to the redirection domain https://multi-region.api.tiledb.com .
Python - Array Access
Python - Array UDF
Python - Array Access
import tiledb, tiledb.sql
import pandas
​
# Create the configuration parameters
config = tiledb.Config()
config["rest.username"] = "xxx"
config["rest.password"] = "yyy"
# or, more preferably, config["rest.token"] = "my_token"
​
# Manually set the server address to the redirection URL
config["rest.server_address"] = "https://multi-region.api.tiledb.com"
​
# This is the array URI format in TileDB Cloud
array_name = "tiledb://TileDB-Inc/quickstart_sparse-eu-west-2"
​
# Write code exactly as in TileDB Embedded
with tiledb.open(array_name, 'r', ctx=tiledb.Ctx(config)) as A:
    print (A.df[:])
    
# Using embedded SQL, you need to pass the username/password 
# as config parameters as well as the server address in `init_command`
db = tiledb.sql.connect(db="test",
        init_command="set mytile_tiledb_config='rest.username=xxx,rest.password=xxx,rest.server_address=https://multi-region.api.tiledb.com'")
pandas.read_sql(sql="select * from `tiledb://TileDB-Inc/quickstart_sparse-eu-west-2`", con=db)
Python - Array UDF
import tiledb, tiledb.cloud, numpy
​
def median(numpy_ordered_dictionary):
  return numpy.median(numpy_ordered_dictionary["a"])
​
tiledb.cloud.login(username="xxx", password="yyy", host="https://multi-region.api.tiledb.com")
# or tiledb.cloud.login(token="my_token", host="https://multi-region.api.tiledb.com")
​
with tiledb.open("tiledb://TileDB-Inc/quickstart_sparse-eu-west-2", ctx=tiledb.cloud.Ctx()) as A:
    # apply on subarray [1,2]x[1,2]
    res = A.apply(median, [(1,2), (1,2)], attrs = ["a"])
    print(res)
Direct Region Access
A compute region can be access directly bypassing automatic redirection. This is helpful if you want to avoid the slight increase in latency that the redirection adds.
To access a region directly the domain is of the scheme: <region>.aws.api.tiledb.com
The four domains we currently support are:
us-east-1.aws.api.tiledb.com
us-west-2.aws.api.tiledb.com
eu-west-2.aws.api.tiledb.com
ap-southeast-1.aws.api.tiledb.com
You can manually set the domain to send a request directly to a region as follows:
Python - Array Access
Python - Array UDF
Python - Array Access
import tiledb, tiledb.sql
import pandas
​
# Create the configuration parameters
config = tiledb.Config()
config["rest.username"] = "xxx"
config["rest.password"] = "yyy"
# or, more preferably, config["rest.token"] = "my_token"
​
# Manually set the server address to the redirection URL
config["rest.server_address"] = "https://eu-west-2.aws.api.tiledb.com"
​
# This is the array URI format in TileDB Cloud
array_name = "tiledb://TileDB-Inc/quickstart_sparse-eu-west-2"
​
# Write code exactly as in TileDB Developer
with tiledb.open(array_name, 'r', ctx=tiledb.Ctx(config)) as A:
    print (A.df[:])
    
# Using embedded SQL, you need to pass the username/password 
# as config parameters as well as the server address in `init_command`
db = tiledb.sql.connect(db="test",
        init_command="set mytile_tiledb_config='rest.username=xxx,rest.password=xxx,rest.server_address=https://eu-west-2.aws.api.tiledb.com'")
pandas.read_sql(sql="select * from `tiledb://TileDB-Inc/quickstart_sparse-eu-west-2`", con=db)
Python - Array UDF
import tiledb, tiledb.cloud, numpy
​
def median(numpy_ordered_dictionary):
  return numpy.median(numpy_ordered_dictionary["a"])
​
tiledb.cloud.login(username="xxx", password="yyy", host="https://eu-west-2.aws.api.tiledb.com")
# or tiledb.cloud.login(token="my_token", host="https://eu-west-2.aws.api.tiledb.com")
​
with tiledb.open("tiledb://TileDB-Inc/quickstart_sparse-eu-west-2", ctx=tiledb.cloud.Ctx()) as A:
    # apply on subarray [1,2]x[1,2]
    res = A.apply(median, [(1,2), (1,2)], attrs = ["a"])
    print(res)
API Reference - Previous
Task Graphs
Last updated 4 months ago