Start Here!

In this tutorial you will learn how to:

  1. Sign up / Sign in to TileDB Cloud

  2. Access a public array using the TileDB-Py library

  3. Access basic array information using the TileDB Cloud client

  4. View the public array on the TileDB Cloud console

  5. View a task on the TileDB Cloud console

  6. View and edit your profile on the TileDB Cloud console

Sign Up & Sign In

First, sign up and you will get $10 in free credit. Feel free to contact us if you run out of credits and you are still evaluating TileDB Cloud, we'll be happy to help out with more credits. Then simply sign in with the username and password you created.

Access a Public Array

It is extremely easy to access arrays registered with TileDB Cloud via the core TileDB Embedded APIs, with literally a single change: adding your username/password as configuration parameters. In this tutorial we will use TileDB-Py. Let's first install it with:

# Pip:
$ pip install tiledb
# Or Conda:
$ conda install -c conda-forge tiledb-py

To validate the installation, run:

$ python
>>> import tiledb
>>> tiledb.__version__
'x.y.z' # The version will appear here

Also make sure you have already installed pandas and pyarrow, or alternatively run:

$ conda install pandas
$ conda install -c conda-forge pyarrow

We have added a couple of public arrays that every user on TileDB Cloud can access, under our TileDB-Inc organization. Below we show an example for getting the schema of array tiledb://TileDB-Inc/quickstart_sparse, and slicing its contents:

Python
Python
import tiledb
# Set your username and password
config = tiledb.Config()
config["rest.username"] = "xxx"
config["rest.password"] = "yyy"
# This is the array URI format in TileDB Cloud
array_name = "tiledb://TileDB-Inc/quickstart_sparse"
# Open the array
A = tiledb.open(array_name, 'r', ctx=tiledb.Ctx(config))
# Print the array schema
print(A.schema)
# This will print:
#
# ArraySchema(
# domain=Domain(*[
# Dim(name='rows', domain=(1, 4), tile=4, dtype='int32'),
# Dim(name='cols', domain=(1, 4), tile=4, dtype='int32'),
# ]),
# attrs=[
# Attr(name='a', dtype='uint32', var=False, nullable=False),
# ],
# cell_order='row-major',
# tile_order='row-major',
# capacity=10000,
# sparse=True,
# allows_duplicates=False,
# coords_filters=FilterList([ZstdFilter(level=-1)]),
#)
# Print all the contents of the array
print(A.df[:])
# This will print
#
# rows cols a
# 0 1 1 1
# 1 2 3 3
# 2 2 4 2
# Close the array
A.close()

Congratulations! You just performed your first array query to a public array in TileDB Cloud!

Access via the TileDB Cloud Client

The TileDB Client is a separate Python package that allows you to perform pretty much any kind of task you would otherwise do via the TileDB Cloud online console (also described later in this tutorial). Let's first install it with:

Bash
Bash
pip install tiledb-cloud

Check that it installed properly as follows:

$ python
>>>

Let's get the description of the array we used above:

import tiledb.cloud
# Set your username and password
config = tiledb.Config()
config["rest.username"] = "xxx"
config["rest.password"] = "yyy"
info = tiledb.cloud.info("tiledb://TileDB-Inc/quickstart_sparse")
print(info)
# This prints:
#
# {'access_credentials_name': None,
# 'allowed_actions': ['read', 'read_array_info', 'read_array_schema'],
# 'description': '# Quickstart Sparse Array\n'
# '\n'
# 'This is a very simple 2D sparse array, used to quickly '
# 'demonstrate basic TileDB Cloud functionality.',
# 'file_properties': None,
# 'file_type': None,
# 'id': '69ca9424-2578-44d0-8662-87897d9e2941',
# 'last_accessed': datetime.datetime(2021, 5, 3, 19, 1, 15, tzinfo=tzutc()),
# 'license_id': 'MIT',
# 'license_text': 'MIT License Copyright (c) <year> <copyright holders>\n'
# '\n'
# 'Permission is hereby granted, free of charge, to any person '
# 'obtaining a copy of this software and associated '
# 'documentation files (the "Software"), to deal in the '
# 'Software without restriction, including without limitation '
# 'the rights to use, copy, modify, merge, publish, distribute, '
# 'sublicense, and/or sell copies of the Software, and to '
# 'permit persons to whom the Software is furnished to do so, '
# 'subject to the following conditions:\n'
# '\n'
# 'The above copyright notice and this permission notice '
# '(including the next paragraph) shall be included in all '
# 'copies or substantial portions of the Software.\n'
# '\n'
# 'THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY '
# 'KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE '
# 'WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR '
# 'PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS '
# 'OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR '
# 'OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR '
# 'OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE '
# 'SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.',
# 'logo': None,
# 'name': 'quickstart_sparse',
# 'namespace': 'TileDB-Inc',
# 'namespace_subscribed': False,
# 'pricing': None,
# 'public_share': True,
# 'share_count': 1.0,
# 'size': 903.0,
# 'subscriptions': None,
# 'tags': None,
# 'tiledb_uri': 'tiledb://TileDB-Inc/quickstart_sparse',
# 'type': 'sparse',
# 'uri': None}

Great work! In the following we will see how to view useful information directly through the TileDB Cloud console.

Using the TileDB Cloud Console

You can view the information of public arrays by directly navigating to the array's URL on TileDB Cloud, even if you are not signed in (TileDB Cloud provides "static view" of arrays). For example, you can click directly on https://cloud.tiledb.com/arrays/details/TileDB-Inc/quickstart_sparse/overview, which is the URL of the array we used in the previous sections. Once you do so, you will see:

Click on the Schema tab to see the array schema:

Next, let's sign in and see some activity logs. Click on Tasks on the left-hand side menu, under Assets:

Here you can see the various tasks that you have performed (like slicing an array), along with other information, such as the time, cost, duration, etc. Clicking on a task provides further information (to be coved in other tutorials).

Finally, you can view your profile by clicking on your avatar located on the upper right of the screen, and clicking on Settings:

Here you can edit your personal information, change your password, etc.

Congratulations! You have successfully completed your very first TileDB Cloud tutorial!🎉

What's Next?

Are interested in diving deeper into TileDB Cloud? Here is what we recommend you to do next.

Quick recipes:

Next tutorials: