Share via

TableClient Class

  • Reference

A client to interact with a specific Table in an Azure Tables account.

Create TableClient from a Credential.

Inheritance
azure.data.tables._base_client.TablesBaseClient
TableClient

Constructor

TableClient(endpoint: str, table_name: str, *, credential: AzureSasCredential | AzureNamedKeyCredential | TokenCredential | None = None, api_version: str | None = None, **kwargs: Any)

Parameters

Name Description
endpoint
Required
str

A URL to an Azure Tables account.
table_name
Required
str

The table name.

Keyword-Only Parameters

Name Description
credential
AzureNamedKeyCredential or AzureSasCredential or TokenCredential or None

The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be one of AzureNamedKeyCredential (azure-core), AzureSasCredential (azure-core), or a TokenCredential implementation from azure-identity.
api_version
str or None

Specifies the version of the operation to use for this request. Default value is "2019-02-02".

Variables

Name Description
account_name
str

The name of the Tables account.
table_name
str

The name of the table.
scheme
str

The scheme component in the full URL to the Tables account.
url
str

The full endpoint URL to this entity, including SAS token if used.
api_version
str

The version of the Storage API used for requests.
credential
AzureNamedKeyCredential or AzureSasCredential or TokenCredential or None

The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be one of AzureNamedKeyCredential (azure-core), AzureSasCredential (azure-core), or a TokenCredential implementation from azure-identity.

Methods

close

This method is to close the sockets opened by the client. It need not be used when using with a context manager.
create_entity

Inserts entity in a table.
create_table

Creates a new table under the current account.
delete_entity
delete_table

Deletes the table under the current account. No error will be raised if the table does not exist.
from_connection_string

Create TableClient from a Connection String.
from_table_url

A client to interact with a specific Table.
get_entity

Gets a single entity in a table.
get_table_access_policy

Retrieves details about any stored access policies specified on the table that may be used with Shared Access Signatures.
list_entities

Lists entities in a table.
query_entities

Queries entities in a table.
set_table_access_policy

Sets stored access policies for the table that may be used with Shared Access Signatures.
submit_transaction

Commits a list of operations as a single transaction.

If any one of these operations fails, the entire transaction will be rejected.
update_entity

Updates an entity in a table.
upsert_entity

Updates (merge or replace) an entity into a table.

close

This method is to close the sockets opened by the client. It need not be used when using with a context manager.

close() -> None

create_entity

Inserts entity in a table.

create_entity(entity: TableEntity | Mapping[str, Any], **kwargs) -> Dict[str, Any]

Parameters

Name Description
entity
Required
Union[TableEntity, Mapping[str, Any]]

The properties for the table entity.

Returns

Type Description
dict[str, Any]

Dictionary mapping operation metadata returned from the service.

Exceptions

Type Description
ResourceExistsError

If the entity already exists

Examples

Creating and adding an entity to a Table


   try:
       resp = table_client.create_entity(entity=self.entity)
       print(resp)
   except ResourceExistsError:
       print("Entity already exists")

create_table

Creates a new table under the current account.

create_table(**kwargs) -> TableItem

Returns

Type Description
TableItem

A TableItem representing the created table.

Exceptions

Type Description
ResourceExistsError

If the entity already exists

Examples

Creating a table from the TableClient object.


   with TableClient.from_connection_string(
       conn_str=self.connection_string, table_name=self.table_name
   ) as table_client:
       try:
           table_item = table_client.create_table()
           print(f"Created table {table_item.name}!")
       except ResourceExistsError:
           print("Table already exists")

delete_entity 

delete_entity(partition_key: str, row_key: str, *, etag: str | None = None, match_condition: MatchConditions | None = None, **kwargs: Any) -> None

delete_table

Deletes the table under the current account. No error will be raised if the table does not exist.

delete_table(**kwargs) -> None

Returns

Type Description

None

Exceptions

Type Description
HttpResponseError

Examples

Deleting a table from the TableClient object.


   with TableClient.from_connection_string(
       conn_str=self.connection_string, table_name=self.table_name
   ) as table_client:
       table_client.delete_table()
       print(f"Deleted table {table_client.table_name}!")

from_connection_string

Create TableClient from a Connection String.

from_connection_string(conn_str: str, table_name: str, **kwargs: Any) -> TableClient

Parameters

Name Description
conn_str
Required
str

A connection string to an Azure Tables account.
table_name
Required
str

The table name.

Returns

Type Description
TableClient

A table client.

Examples

Authenticating a TableServiceClient from a connection_string


   from azure.data.tables import TableClient

   with TableClient.from_connection_string(
       conn_str=self.connection_string, table_name="tableName"
   ) as table_client:
       print(f"Table name: {table_client.table_name}")

from_table_url

A client to interact with a specific Table.

from_table_url(table_url: str, *, credential: AzureNamedKeyCredential | AzureSasCredential | None = None, **kwargs: Any) -> TableClient

Parameters

Name Description
table_url
Required
str

The full URI to the table, including SAS token if used.

Keyword-Only Parameters

Name Description
credential
AzureNamedKeyCredential or AzureSasCredential or None

The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be one of AzureNamedKeyCredential (azure-core), AzureSasCredential (azure-core), or a TokenCredential implementation from azure-identity.

Returns

Type Description
TableClient

A table client.

get_entity

Gets a single entity in a table.

get_entity(partition_key: str, row_key: str, *, select: str | List[str] | None = None, **kwargs) -> TableEntity

Parameters

Name Description
partition_key
Required
str

The partition key of the entity.
row_key
Required
str

The row key of the entity.

Keyword-Only Parameters

Name Description
select
str or list[str] or None

Specify desired properties of an entity to return.

Returns

Type Description
TableEntity

Dictionary mapping operation metadata returned from the service.

Exceptions

Type Description
HttpResponseError

Examples

Getting an entity with PartitionKey and RowKey from a table


   # Get Entity by partition and row key
   got_entity = table.get_entity(partition_key=my_entity["PartitionKey"], row_key=my_entity["RowKey"])
   print(f"Received entity: {got_entity}")

get_table_access_policy

Retrieves details about any stored access policies specified on the table that may be used with Shared Access Signatures.

get_table_access_policy(**kwargs) -> Dict[str, TableAccessPolicy | None]

Returns

Type Description
dict[str, TableAccessPolicy],
dict[str, None]

Dictionary of SignedIdentifiers.

Exceptions

Type Description
HttpResponseError

list_entities

Lists entities in a table.

list_entities(*, results_per_page: int | None = None, select: str | List[str] | None = None, **kwargs) -> ItemPaged[TableEntity]

Keyword-Only Parameters

Name Description
results_per_page
int or None

Number of entities returned per service request.
select
str or list[str] or None

Specify desired properties of an entity to return.

Returns

Type Description
ItemPaged[TableEntity]

An iterator of TableEntity

Exceptions

Type Description
HttpResponseError

Examples

Listing all entities held within a table


   # Query the entities in the table
   entities = list(table.list_entities())
   for i, entity in enumerate(entities):
       print(f"Entity #{entity}: {i}")

query_entities

Queries entities in a table.

query_entities(query_filter: str, *, results_per_page: int | None = None, select: str | List[str] | None = None, parameters: Dict[str, Any] | None = None, **kwargs) -> ItemPaged[TableEntity]

Parameters

Name Description
query_filter
Required
str

Specify a filter to return certain entities. For more information on filter formatting, see the samples documentation.

Keyword-Only Parameters

Name Description
results_per_page
int or None

Number of entities returned per service request.
select
str or list[str] or None

Specify desired properties of an entity to return.
parameters
dict[str, Any] or None

Dictionary for formatting query with additional, user defined parameters

Returns

Type Description
ItemPaged[TableEntity]

An iterator of TableEntity

Exceptions

Type Description
HttpResponseError

Examples

Querying entities held within a table


   with TableClient.from_connection_string(self.connection_string, self.table_name) as table_client:
       try:
           print("Basic sample:")
           print("Entities with name: marker")
           parameters: Dict[str, Any] = {"name": "marker"}
           name_filter = "Name eq @name"
           queried_entities = table_client.query_entities(
               query_filter=name_filter, select=["Brand", "Color"], parameters=parameters
           )

           for entity_chosen in queried_entities:
               print(entity_chosen)

           print("Sample for querying entities with multiple params:")
           print("Entities with name: marker and brand: Crayola")
           parameters = {"name": "marker", "brand": "Crayola"}
           name_filter = "Name eq @name and Brand eq @brand"
           queried_entities = table_client.query_entities(
               query_filter=name_filter, select=["Brand", "Color"], parameters=parameters
           )
           for entity_chosen in queried_entities:
               print(entity_chosen)

           print("Sample for querying entities' values:")
           print("Entities with 25 < Value < 50")
           parameters = {"lower": 25, "upper": 50}
           name_filter = "Value gt @lower and Value lt @upper"
           queried_entities = table_client.query_entities(
               query_filter=name_filter, select=["Value"], parameters=parameters
           )
           for entity_chosen in queried_entities:
               print(entity_chosen)
       except HttpResponseError as e:
           raise

set_table_access_policy

Sets stored access policies for the table that may be used with Shared Access Signatures.

set_table_access_policy(signed_identifiers: Mapping[str, TableAccessPolicy | None], **kwargs) -> None

Parameters

Name Description
signed_identifiers
Required
Mapping[str, Optional[TableAccessPolicy]]

Access policies to set for the table.

Returns

Type Description

None

Exceptions

Type Description
HttpResponseError

submit_transaction

Commits a list of operations as a single transaction.

If any one of these operations fails, the entire transaction will be rejected.

submit_transaction(operations: Iterable[Tuple[TransactionOperation | str, TableEntity | Mapping[str, Any]] | Tuple[TransactionOperation | str, TableEntity | Mapping[str, Any], Mapping[str, Any]]], **kwargs) -> List[Mapping[str, Any]]

Parameters

Name Description
operations
Required
Iterable[Tuple[str, TableEntity, Mapping[str, Any]]]

The list of operations to commit in a transaction. This should be an iterable of tuples containing an operation name, the entity on which to operate, and optionally, a dict of additional kwargs for that operation. For example:


   - ('upsert', {'PartitionKey': 'A', 'RowKey': 'B'})
   - ('upsert', {'PartitionKey': 'A', 'RowKey': 'B'}, {'mode': UpdateMode.REPLACE})

Returns

Type Description
list[Mapping[str, Any]]

A list of mappings with response metadata for each operation in the transaction.

Exceptions

Type Description
TableTransactionError

Examples

Using transactions to send multiple requests at once


   from azure.data.tables import TableClient, TableTransactionError
   from azure.core.exceptions import ResourceExistsError

   entity1 = {"PartitionKey": "pk001", "RowKey": "rk001", "Value": 4, "day": "Monday", "float": 4.003}
   entity2 = {"PartitionKey": "pk001", "RowKey": "rk002", "Value": 4, "day": "Tuesday", "float": 4.003}
   entity3 = {"PartitionKey": "pk001", "RowKey": "rk003", "Value": 4, "day": "Wednesday", "float": 4.003}
   entity4 = {"PartitionKey": "pk001", "RowKey": "rk004", "Value": 4, "day": "Thursday", "float": 4.003}

   # Instantiate a TableClient using a connection string
   with TableClient.from_connection_string(
       conn_str=self.connection_string, table_name=self.table_name
   ) as table_client:

       try:
           table_client.create_table()
           print("Created table")
       except ResourceExistsError:
           print("Table already exists")

       table_client.upsert_entity(entity2)
       table_client.upsert_entity(entity3)
       table_client.upsert_entity(entity4)

       operations: List[TransactionOperationType] = [
           ("create", entity1),
           ("delete", entity2),
           ("upsert", entity3),
           ("update", entity4, {"mode": "replace"}),
       ]
       try:
           table_client.submit_transaction(operations)
       except TableTransactionError as e:
           print("There was an error with the transaction operation")
           print(f"Error: {e}")

update_entity

Updates an entity in a table.

update_entity(entity: TableEntity | Mapping[str, Any], mode: UpdateMode = UpdateMode.MERGE, *, etag: str | None = None, match_condition: MatchConditions | None = None, **kwargs) -> Dict[str, Any]

Parameters

Name Description
entity
Required
TableEntity or dict[str, Any]

The properties for the table entity.
mode
Required
UpdateMode

Merge or Replace entity.

Keyword-Only Parameters

Name Description
etag
str or None

Etag of the entity.
match_condition
MatchConditions or None

The condition under which to perform the operation. Supported values include: MatchConditions.IfNotModified, MatchConditions.Unconditionally.

Returns

Type Description
dict[str, Any]

Dictionary mapping operation metadata returned from the service.

Exceptions

Type Description
HttpResponseError

Examples

Updating an already existing entity in a Table


   # Update the entity
   created["text"] = "NewMarker"
   table.update_entity(mode=UpdateMode.REPLACE, entity=created)

   # Get the replaced entity
   replaced = table.get_entity(partition_key=str(created["PartitionKey"]), row_key=str(created["RowKey"]))
   print(f"Replaced entity: {replaced}")

   # Merge the entity
   replaced["color"] = "Blue"
   table.update_entity(mode=UpdateMode.MERGE, entity=replaced)

   # Get the merged entity
   merged = table.get_entity(partition_key=str(replaced["PartitionKey"]), row_key=str(replaced["RowKey"]))
   print(f"Merged entity: {merged}")

upsert_entity

Updates (merge or replace) an entity into a table.

upsert_entity(entity: TableEntity | Mapping[str, Any], mode: UpdateMode = UpdateMode.MERGE, **kwargs) -> Dict[str, Any]

Parameters

Name Description
entity
Required
TableEntity or dict[str, Any]

The properties for the table entity.
mode
Required
UpdateMode

Merge or Replace entity.

Returns

Type Description
dict[str, Any]

Dictionary mapping operation metadata returned from the service.

Exceptions

Type Description
HttpResponseError

Examples

Replacing/Merging or Inserting an entity into a table


   # Try Replace and insert on fail
   insert_entity = table.upsert_entity(mode=UpdateMode.REPLACE, entity=entity1)
   print(f"Inserted entity: {insert_entity}")

   created["text"] = "NewMarker"
   merged_entity = table.upsert_entity(mode=UpdateMode.MERGE, entity=entity)
   print(f"Merged entity: {merged_entity}")

Attributes

api_version

The version of the Storage API used for requests.

Returns

Type Description

The Storage API version.

url

The full endpoint URL to this entity, including SAS token if used.

This could be either the primary endpoint, or the secondary endpoint depending on the current <xref:azure.data.tables.location_mode>.

Returns

Type Description
str

The full endpoint URL including SAS token if used.