Start Here!

This page is currently under development and will be updated soon.

In this tutorial you will learn how to:

Sign up / sign in to TileDB Cloud
Access a public array using the TileDB-Py library
Access basic array information using the TileDB Cloud client
View the public array on the TileDB Cloud console
View a task on the TileDB Cloud console
View and edit your profile on the TileDB Cloud console

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 Open Source APIs, with literally a single change: adding your username/password as configuration parameters. In this tutorial we will use TileDB-Py, TileDB-R and TileDB-Java. Let's first install it with:

# Pip:
$ pip install tiledb

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

# Via CRAN
install.packages("tiledb")

// Maven
//Include this in your Maven project:
<dependency>
  <groupId>io.tiledb</groupId>
  <artifactId>tiledb-java</artifactId>
  <version>X.X.X</version>
</dependency>

// Or build from source
$ git clone https://github.com/TileDB-Inc/TileDB-Java.git
$ cd TileDB-Java
$ ./gradlew assemble

To validate the installation, run:

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

$ R
> library(tiledb)
> packageVersion("tiledb")
'x.y.z' # The version will appear here

// Compile and run:
Version version = new Version();
System.out.println(version);

For Python, 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:

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

library(tiledb)

# Set your username and password
config <- tiledb_config()
config["rest.username"] <- 'xxx'
config["rest.password"] <- 'yyy'
ctx <- tiledb_ctx(config)

# This is the array URI format in TileDB Cloud
array_name = "tiledb://TileDB-Inc/quickstart_sparse"

# Open the array
arr <- tiledb_array(array_name, return_as='data.frame')

# Print the array schema
schema(arr)

# This will print:
# tiledb_array_schema(
#     domain=tiledb_domain(c(tiledb_dim(name="rows", domain=c(1L,4L), tile=4L, type="INT32"), tiledb_dim(name="cols", domain=c(1L,4L), tile=4L, type="INT32"))),
#     attrs=c(tiledb_attr(name="a", type="UINT32", ncells=1, nullable=FALSE)),
#     cell_order="ROW_MAJOR", tile_order="ROW_MAJOR", capacity=10000, sparse=TRUE, allows_dups=FALSE,
#     coords_filter_list=tiledb_filter_list(c(tiledb_filter_set_option(tiledb_filter("ZSTD"),"COMPRESSION_LEVEL",-1))),
#     offsets_filter_list=tiledb_filter_list(c(tiledb_filter_set_option(tiledb_filter("ZSTD"),"COMPRESSION_LEVEL",-1))))
    
# Print all the contents of the array
df <- arr[]
df

# This will print
#   rows cols a
# 1    1    1 1
# 2    2    3 3
# 3    2    4 2

# Close the array
tiledb_array_close(arr)

//set the config
Config config = new Config();
config.set("rest.username", "xxx");
config.set("rest.password", "yyy");
Context ctx = new Context(config);

//open the array
Array array = new Array(ctx, "tiledb://TileDB-Inc/quickstart_sparse");

//print the array schema
System.out.println(array.getSchema());

//this will print:
//ArraySchema<TILEDB_SPARSE io.tiledb.java.api.Domain@51462713 Attr<a,TILEDB_UINT32,1>>

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

Access via the TileDB Cloud Client

There are several TileDB Clients that allow 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:

# At your shell prompt
pip install tiledb-cloud

# At your shell prompt
# See https://github.com/TileDB-Inc/TileDB-Cloud-R/releases for latest:
remotes::install_github('TileDB-Inc/TileDB-Cloud-R@v0.0.8')

// Maven
//Include this in your project:
<dependency>
  <groupId>io.tiledb</groupId>
  <artifactId>tiledb-cloud-java</artifactId>
  <version>X.X.X</version>
</dependency>

// Or build from source
$ git clone https://github.com/TileDB-Inc/TileDB-Cloud-Java.git
$ cd TileDB-Cloud-Java
$ ./gradlew assemble

Check that it installed properly as follows:

$ python
>>> import tiledb.cloud

$ R
> library(tiledbcloud)

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

library(tiledbcloud)

# Set your username and password
config <- tiledb_config()
config["rest.username"] <- 'xxx'
config["rest.password"] <- 'yyy'
ctx <- tiledb_ctx(config)

info <- tiledbcloud::array_info(
  namespace="TileDB-Inc",
  arrayname="quickstart_dense"))

str(info)

# This prints:
# List of 14
#  $ id                  : chr "2d6e7def-851e-4832-ae92-202af1f6940d"
#  $ namespace           : chr "TileDB-Inc"
#  $ size                : int 835
#  $ last_accessed       : chr "2022-02-28T17:39:48Z"
#  $ description         : chr "# Quickstart Dense Array\n\nThis array is the results of running the quickstart dense example program. This arr"| __truncated__
#  $ name                : chr "quickstart_dense"
#  $ type                : chr "dense"
#  $ share_count         : int 1
#  $ public_share        : logi TRUE
#  $ namespace_subscribed: logi FALSE
#  $ tiledb_uri          : chr "tiledb://TileDB-Inc/quickstart_dense"
#  $ tags                : list()
#  $ license_id          : chr "MIT"
#  $ license_text        : chr "MIT License Copyright (c) <year> <copyright holders>\n\nPermission is hereby granted, free of charge, to any pe"| __truncated__

ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.tiledb.com/v1");

// Configure HTTP basic authorization: BasicAuth
HttpBasicAuth BasicAuth = (HttpBasicAuth) defaultClient.getAuthentication("BasicAuth");
BasicAuth.setUsername("xxx");
BasicAuth.setPassword("yyy");

ArrayApi apiInstance = new ArrayApi(defaultClient);

String namespace = "TileDB-Inc"; // String | namespace array is in (an organization name or user's username)
String array = "quickstart_sparse"; // String | name/uri of array that is url-encoded
try {
    ArrayInfo result = apiInstance.getArrayMetadata(namespace, array);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ArrayApi#getArrayMetadata");
    System.err.println("Status code: " + e.getCode());
    System.err.println("Reason: " + e.getResponseBody());
    System.err.println("Response headers: " + e.getResponseHeaders());
    e.printStackTrace();
}

//this prints:
//class ArrayInfo {
//  id: 69ca9424-2578-44d0-8662-87897d9e2941
//  fileType: null
//  fileProperties: null
//  uri: null
//  namespace: TileDB-Inc
//  size: 903
//  lastAccessed: 2022-06-01T15:01:16Z
//  description: # Quickstart Sparse Array  
//  This is a very simple 2D sparse array, used to quickly demonstrate basic TileDB Cloud functionality.
//  name: quickstart_sparse
//  allowedActions: [read, read_array_info, read_array_schema]
//  pricing: null
//  subscriptions: null
//  logo: null
//  accessCredentialsName: null
//  type: sparse
//  shareCount: 1
//  publicShare: true
//  namespaceSubscribed: false
//  tiledbUri: tiledb://TileDB-Inc/quickstart_sparse
//  tags: [one, three, two]
//  licenseId: MIT
//  licenseText: MIT License Copyright (c) <year> <copyright holders>  
//  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:
//  The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.  
//  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.
//  readOnly: false
//  isFavorite: null
//}

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 Activity 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 covered in other tutorials).

Finally, you can view your profile information by clicking Profileon the left-hand side menu

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:

Create API tokens for faster programmatic login.
Set up AWS credentials so that you can access and share your arrays through TileDB Cloud.
Add billing info, so that you can use the service once you run out of credits.

Next tutorials:

Get a console walkthrough
Start learning about serverless compute
Familiarize yourself with the power of task graphs
Learn to use TileDB Cloud in specific use cases

PreviousWelcome to TileDB Cloud!NextProduct Tour

Last updated 8 months ago

Sign Up & Sign In

Access a Public Array

Access via the TileDB Cloud Client

Using the TileDB Cloud Console

What's Next?