Notebooks

Manage your TileDB Cloud Notebooks programmatically with the TileDB Cloud Python API

The TileDB Cloud Python API provides tools to access, manage, and share notebooks stored in the TileDB Cloud service.

Before accessing notebooks, you’ll need to log in to TileDB Cloud:

import tiledb.cloud
tiledb.cloud.login(username=..., password=...)
# or tiledb.cloud.login(token=...)

Accessing notebook contents

Uploading notebooks

The TileDB Cloud Python API provides two ways to upload notebooks: you can provide a filename to upload, or you can provide the notebook’s contents as a string.

from tiledb.cloud import notebook

# Upload a notebook from a file on disk:
notebook.upload_notebook_from_file(
    "./spectrograph-analysis.ipynb",
    namespace="rosalind-f",
    array_name="spectrographs",
    storage_path=None,  # To use the default storage path
    storage_credential_name=None,  # ...and the default credential
)
# The notebook will be available at tiledb://rosalind-f/spectrographs
# and at cloud/owned/rosalind-f/spectrographs.ipynb in TileDB Cloud Notebooks.

# Upload a notebook from a string:
notebook.upload_notebook_from_file(
    nb_json_data,  # The raw data from a .ipynb file.
    namespace="curiem",
    array_name="radium",
    # An alternate storage path and credential can be specified.
    # This will store the notebook at
    # s3://curie-labs-data/notebooks/radium
    # using the credential named "personal-cred".
    storage_path="s3://cure-labs-data/notebooks",
    storage_credential_name="personal-cred",
)
# This notebook will be available at tiledb://curiem/radium
# and at cloud/owned/curiem/radium.ipynb in TileDB Cloud Notebooks.

Downloading notebooks

Likewise, notebooks can be downloaded and either saved as a file or kept as a string in memory:

from tiledb.cloud import notebook

# Save a notebook to a file:
notebook.download_notebook_to_file(
    # Note the TileDB URI has *no extension*. There is no ".ipynb" on the end.
    tiledb_uri="tiledb://lamarr/mobile-reception",
    ipynb_file_name="./mobile-reception.ipynb",
)

# Download the JSON contents of a notebook as a string:
nb_json = notebook.download_notebook_contents("tiledb://fnight/triage-analysis")

Sharing notebooks

Notebooks are stored as TileDB arrays, so sharing can be managed just like any other array.

Listing users with access to a notebook

Use array.list_shared_with to see who has what kind of access to a notebook:

>>> from tiledb.cloud import array
>>> array.list_shared_with("tiledb://hopper/flowmatic")
[{'actions': ['read', 'read_array_info', 'read_array_schema'],
  'namespace': 'dod',
  'namespace_type': 'organization'},
 {'actions': ['read', 'write', 'read_array_info', 'read_array_schema'],
  'namespace': 'howard-aiken',
  'namespace_type': 'user'}]

Sharing with another user

To share a notebook with another user, share the array. In most cases, you will want to provide a user or organization with read or write access to the array:

from tiledb.cloud import array

array.share_array(
    "tiledb://lovelace/bernoulli",
    namespace="babbage-org",
    permissions=["read", "write"],
)
# babbage-org can now read and write to this notebook.

Revoking access to a notebook

Use unshare_array to revoke access (“unshare”) a notebook from a user or namespace:

from tiledb.cloud import array

array.unshare_array(
    "tiledb://manhattan/yield-calculator",
    namespace="greenglass",
)
# greenglass no longer has access to this notebook.

Making a notebook public

To make a notebook public, share it with the special public namespace:

from tiledb.cloud import array

array.share_array(
    "tiledb://jonas/vaccine-dev",
    namespace="public",
    permissions=["read"],
)
# Any TileDB Cloud user can now access this notebook.

To make a public notebook private again, revoke access from the public namespace:

array.unshare_array(
    "tiledb://jonas/vaccine-dev",
    namespace="public",
)
# This array is now accessible to only selected TileDB Cloud users.