Azure Tables client library for Python

Azure Tables is a NoSQL data storage service that can be accessed from anywhere in the world via authenticated calls using HTTP or HTTPS. Tables scales as needed to support the amount of data inserted, and allow for the storing of data with non-complex accessing. The Azure Tables client can be used to access Azure Storage or Cosmos accounts. This document covers [azure-data-tables][Tables_pypi].

Please note, this package is a replacement for azure-cosmosdb-tables which is now deprecated. See the [migration guide][migration_guide] for more details.

[Source code][source_code] | [Package (PyPI)][Tables_pypi] | Package (Conda) | [API reference documentation][Tables_ref_docs] | [Samples][Tables_samples]

Getting started

The Azure Tables SDK can access an Azure Storage or CosmosDB account.

Prerequisites

Python 3.9 or later is required to use this package.
You must have an [Azure subscription][azure_subscription] and either
- an [Azure Storage account][azure_storage_account] or
- an [Azure Cosmos Account][azure_cosmos_account].

Create account

To create a new storage account, you can use [Azure Portal][azure_portal_create_account], [Azure PowerShell][azure_powershell_create_account], or [Azure CLI][azure_cli_create_account]:
To create a new cosmos storage account, you can use the [Azure CLI][azure_cli_create_cosmos] or [Azure Portal][azure_portal_create_cosmos].

Install the package

Install the Azure Tables client library for Python with [pip][pip_link]:

pip install azure-data-tables

Create the client

The Azure Tables library allows you to interact with two types of resources:

the tables in your account
the entities within those tables. Interaction with these resources starts with an instance of a client. To create a client object, you will need the account's table service endpoint URL and a credential that allows you to access the account. The endpoint can be found on the page for your storage account in the [Azure Portal][azure_portal_account_url] under the "Access Keys" section or by running the following Azure CLI command:

# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Once you have the account URL, it can be used to create the service client:

from azure.data.tables import TableServiceClient
service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net/", credential=credential)

For more information about table service URL's and how to configure custom domain names for Azure Storage check out the [official documentation][azure_portal_account_url]

Types of credentials

The credential parameter may be provided in a number of different forms, depending on the type of authorization you wish to use. The Tables library supports the following authorizations:

Shared Key
Connection String
Shared Access Signature Token
TokenCredential (Microsoft Entra ID)(Supported on Storage)

Creating the client from a shared key

To use an account [shared key][azure_shared_key] (aka account key or access key), provide the key as a string. This can be found in your storage account in the [Azure Portal][azure_portal_account_url] under the "Access Keys" section or by running the following Azure CLI command:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Use the key as the credential parameter to authenticate the client:

from azure.data.tables import TableServiceClient
from azure.core.credentials import AzureNamedKeyCredential

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")
with TableServiceClient(
    endpoint="https://<my_account_name>.table.core.windows.net", credential=credential
) as table_service_client:
    properties = table_service_client.get_service_properties()
    print(f"{properties}")

Creating the client from a connection string

Depending on your use case and authorization method, you may prefer to initialize a client instance with a connection string instead of providing the account URL and credential separately. To do this, pass the connection string to the client's from_connection_string class method. If the connection string does not specify a fully qualified endpoint URL ("TableEndpoint"), or URL suffix ("EndpointSuffix"), the endpoint will be assumed to be an Azure Storage account, and the URL automatically formatted accordingly.

For Tables Storage, the connection string can be found in your storage account in the [Azure Portal][azure_portal_account_url] under the "Access Keys" section or with the following Azure CLI command:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

For Tables Cosmos, the connection string can be found in your cosmos account in the [Azure Portal][azure_portal_account_url] under the "Connection Strings" section or with the following Azure CLI command:

az cosmosdb list-connection-strings -g MyResourceGroup -n MyCosmosAccount

Create a client from a connection string:

from azure.data.tables import TableServiceClient

connection_string = "AccountName=<my_account_name>;AccountKey=<my_account_key>;EndpointSuffix=<endpoint_suffix>"
with TableServiceClient.from_connection_string(conn_str=connection_string) as table_service_client:
    properties = table_service_client.get_service_properties()
    print(f"{properties}")

Creating the client from a SAS token

To use a [shared access signature (SAS) token][azure_sas_token], provide the token as a string. If your account URL includes the SAS token, omit the credential parameter. You can generate a SAS token from the Azure Portal under Shared access signature or use one of the generate_*_sas() functions to create a sas token for the account or table:

from datetime import datetime, timedelta
from azure.data.tables import TableServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions
from azure.core.credentials import AzureNamedKeyCredential, AzureSasCredential

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")
# Create a SAS token to use for authentication of a client
sas_token = generate_account_sas(
    credential,
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1),
)

with TableServiceClient(
    endpoint="https://<my_account_name>.table.core.windows.net", credential=AzureSasCredential(sas_token)
) as table_service_client:
    properties = table_service_client.get_service_properties()
    print(f"{properties}")

Creating the client from a TokenCredential

Azure Tables provides integration with Microsoft Entra ID for identity-based authentication of requests to the Table service when targeting a Storage endpoint. With Microsoft Entra ID, you can use role-based access control (RBAC) to grant access to your Azure Table resources to users, groups, or applications.

To access a table resource with a TokenCredential, the authenticated identity should have either the "Storage Table Data Contributor" or "Storage Table Data Reader" role.

With the azure-identity package, you can seamlessly authorize requests in both development and production environments. To learn more about Microsoft Entra ID integration in Azure Storage, see the azure-identity README

from azure.data.tables import TableServiceClient
from azure.identity import DefaultAzureCredential

with TableServiceClient(
    endpoint="https://<my_account_name>.table.core.windows.net", credential=DefaultAzureCredential()
) as table_service_client:
    properties = table_service_client.get_service_properties()
    print(f"{properties}")

Configure client for an Azure sovereign cloud

When TokenCredential authentication is used, all clients are configured to use the Azure public cloud by default. To configure a client for a sovereign cloud, you should provide the correct audience keyword argument when creating the client. The following table lists some known audiences:

Cloud	Audience
Azure Public	https://storage.azure.com / https://cosmos.azure.com
Azure US Government	https://storage.azure.us / https://cosmos.azure.us
Azure China	https://storage.chinacloudapi.cn / https://cosmos.chinacloudapi.cn

The following example shows how to configure the TableServiceClient to connect to Azure US Government:

from azure.data.tables import TableServiceClient
from azure.identity import AzureAuthorityHosts, DefaultAzureCredential

# Authority can also be set via the AZURE_AUTHORITY_HOST environment variable.
credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

table_service_client = TableServiceClient(
    endpoint="https://<my_account_name>.table.core.usgovcloudapi.net",
    credential=credential,
    audience="https://storage.azure.us"
)

Key concepts

Common uses of the Table service included:

Storing TBs of structured data capable of serving web scale applications
Storing datasets that do not require complex joins, foreign keys, or stored procedures and can be de-normalized for fast access
Quickly querying data using a clustered index
Accessing data using the OData protocol and LINQ filter expressions

The following components make up the Azure Tables Service:

The account
A table within the account, which contains a set of entities
An entity withi

azure-data-tables

Description