client
client.client
TileDB client and supporting methods, such as login()
Examples
Login and configure a client session from a named profile.
>>> tiledb.client.login(profile_name=PROFILE_NAME)Classes
| Name | Description |
|---|---|
| Client | TileDB Client. |
| ClientError | Raise for client-related errors |
| ConfigurationError | Raise for errors during configuration |
| LoginError | Raise for errors during login |
| Workspace | The relationship between a user and workspace. |
Client
client.client.Client(pool_threads=None, retry_mode=RetryMode.DEFAULT)TileDB Client.
:param pool_threads: Number of threads to use for http requests :param retry_mode: Retry mode [“default”, “forceful”, “disabled”]
Methods
| Name | Description |
|---|---|
| build | Builds an API client with the given config. |
| retry_mode | Sets how we should retry requests and updates API instances. |
| set_threads | Updates the number of threads in the async thread pool. |
build
client.client.Client.build(builder)Builds an API client with the given config.
retry_mode
client.client.Client.retry_mode(mode=RetryMode.DEFAULT)Sets how we should retry requests and updates API instances.
set_threads
client.client.Client.set_threads(threads=None)Updates the number of threads in the async thread pool.
ClientError
client.client.ClientError()Raise for client-related errors
ConfigurationError
client.client.ConfigurationError()Raise for errors during configuration
LoginError
client.client.LoginError()Raise for errors during login
Workspace
client.client.Workspace()The relationship between a user and workspace.
To access more details about the user’s role, such as when it was updated, and by whom, use workspaces.get_workspace_user().
Attributes
| Name | Type | Description |
|---|---|---|
| workspace_id | str | The unique id of the workspace. |
| name | str | The name of the workspace. |
| description | str | A description of the workspace. |
| created_at | datetime | When the workspace was created. |
| updated_at | datetime | When the workspace was last updated. |
| created_by | WorkspaceUser | The user and action that created the user-workspace relationship. |
| workspace_role | WorkspaceRole | The user’s role in the workspace. |
Functions
| Name | Description |
|---|---|
| Config | Builds a tiledb config setting the login parameters that exist for the cloud service |
| Ctx | Builds a TileDB Context that has the tiledb config parameters |
| build | The standard low-level API client builder. |
| configure | Store TileDB credentials in a profile for later use. |
| default_user | Get the currently logged-in user. |
| get_self_user | Get the currently logged-in user and related workspaces. |
| get_user | The current session’s deployment user. |
| get_user_workspaces | a list of relationships between the session user and workspaces. |
| get_workspace | Get the current session’s workspace. |
| get_workspace_id | Get the current session’s workspace id. |
| login | Login and configure a TileDB client session using stored credentials. |
Config
client.client.Config(cfg_dict=None)Builds a tiledb config setting the login parameters that exist for the cloud service :return: tiledb.Config
Ctx
client.client.Ctx(config=None)Builds a TileDB Context that has the tiledb config parameters for tiledb cloud set from stored login :return: tiledb.Ctx
build
client.client.build(builder)The standard low-level API client builder.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| builder | Callable[[rest_api.ApiClient], _T] | An API instance, such as tiledb.client._commmon.api_v4.AssetsApi. |
required |
Returns
| Name | Type | Description |
|---|---|---|
| ApiClient |
Notes
This function is mostly for internal use in assets.py, files.py, etc.
configure
client.client.configure(
token=None,
username=None,
password=None,
workspace=None,
host=None,
verify_ssl=None,
ca_file=None,
profile_name=None,
profile_dir=None,
overwrite=False,
)Store TileDB credentials in a profile for later use.
This method handles credential storage and profile management, allowing you to save authentication details to disk for use in subsequent sessions. After configuring credentials, you can use login() to load and activate them for the current session.
Note
If both token and username/password are provided, only the token will be stored in the profile. The username and password parameters will be ignored when a token is present, as token-based authentication takes priority.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| token | str | API token for authentication. This token may be one that identifies a workspace. | None |
| username | str | A TileDB account username. | None |
| password | str | A TileDB account password. | None |
| workspace | str | A TileDB workspace name or id. | None |
| host | str | The TileDB server address. | None |
| verify_ssl | bool | Enable strict SSL verification. | None |
| ca_file | str | Path to a certificate authority bundle file. | None |
| profile_name | str | The name to assign to the profile. Defaults to “default”. | None |
| profile_dir | str | The directory where the profiles file is stored. Defaults to None, which means the home directory of the user. | None |
| overwrite | bool | Whether to overwrite an existing profile. Defaults to False. | False |
Raises
| Name | Type | Description |
|---|---|---|
| ConfigurationError | If the configuration fails due to missing or invalid parameters. | |
| Examples | ||
| Configure credentials using username and password: | ||
| >>> tiledb.client.configure( | ||
| … username="myuser", | ||
| … password="mypass", | ||
| … workspace="myworkspace", | ||
| … host="myhost.com" | ||
| … ) | ||
| Configure credentials using an API token: | ||
| >>> tiledb.client.configure( | ||
| … token="my-api-token", | ||
| … workspace="myworkspace", | ||
| … host="myhost.com" | ||
| … ) | ||
| Configure credentials to a named profile: | ||
| >>> tiledb.client.configure( | ||
| … token="my-token", | ||
| … workspace="myworkspace", | ||
| … host="myhost.com", | ||
| … profile_name="production" | ||
| … ) | ||
| Overwrite an existing profile: | ||
| >>> tiledb.client.configure( | ||
| … token="my-token", | ||
| … workspace="myworkspace", | ||
| … host="myhost.com", | ||
| … overwrite=True | ||
| … ) |
default_user
client.client.default_user()Get the currently logged-in user.
Returns
| Name | Type | Description |
|---|---|---|
| User |
get_self_user
client.client.get_self_user()Get the currently logged-in user and related workspaces.
Returns
| Name | Type | Description |
|---|---|---|
| tuple[User, UserSelfWorkspace] |
get_user
client.client.get_user()The current session’s deployment user.
The role attribute of the User class describes the user’s role in the TileDB deployment. Values are “owner”, “admin”, or “member”.
This function can also be used to diagnose a defective profile. If a description of the current session’s deployment user can not be retrieved, it’s likely that the profile host is mis-identified.
Returns
| Name | Type | Description |
|---|---|---|
| User |
Raises
| Name | Type | Description |
|---|---|---|
| ClientError | When the user can not be retrieved. |
get_user_workspaces
client.client.get_user_workspaces()a list of relationships between the session user and workspaces.
Returns
| Name | Type | Description |
|---|---|---|
| list[UserWorkspace] |
Raises
| Name | Type | Description |
|---|---|---|
| ClientError | When the user-workspace relationships can not be retrieved. |
get_workspace
client.client.get_workspace()Get the current session’s workspace.
This function can also be used to diagnose a defective profile. If a description of the current session’s workspace can not be retrieved, it’s likely that the profile host is mis-identified.
Returns
| Name | Type | Description |
|---|---|---|
| Workspace |
Raises
| Name | Type | Description |
|---|---|---|
| ClientError | When the workspace can not be retrieved. |
get_workspace_id
client.client.get_workspace_id()Get the current session’s workspace id.
login
client.client.login(profile_name=None, profile_dir=None, threads=None)Login and configure a TileDB client session using stored credentials.
This method loads credentials from a TileDB profile that was previously saved using configure(). It does not store or modify credentials; it only loads them from disk to establish a session.
To store credentials for the first time, use configure() first, then call login() to activate them.
You may call this function multiple times within a Python interpreter session to switch between TileDB profiles and configure new client sessions.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| profile_name | Optional[str] | Name of the configuration profile to use. If not specified, the default profile will be used if it exists. | None |
| profile_dir | Optional[str] | The directory where the profiles file is stored. Defaults to None, which means the home directory of the user. | None |
| threads | Optional[int] | Number of threads to enable for concurrent requests, default to None (determined by library). | None |
Raises
| Name | Type | Description |
|---|---|---|
| LoginError | If the login fails due to missing configuration parameters or if no valid profile can be found. |
Examples
Login using the default profile:
>>> tiledb.client.login()Login using a named profile:
>>> tiledb.client.login(profile_name="production")