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 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	Insert 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. AzureSasCredential (azure-core), or a TokenCredential implementation from azure-identity. :paramtype credential: ~azure.core.credentials.AzureNamedKeyCredential or ~azure.core.credentials.AzureSasCredential or None
get_entity	Get 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	Lists 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	Commit a list of operations as a single transaction. If any one of these operations fails, the entire transaction will be rejected.
update_entity	Update entity in a table.
upsert_entity	Update/Merge or Insert entity into 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

Insert 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
HttpResponseError

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.

AzureSasCredential (azure-core), or a TokenCredential implementation from azure-identity. :paramtype credential:

~azure.core.credentials.AzureNamedKeyCredential or ~azure.core.credentials.AzureSasCredential or None

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

Parameters

Name	Description
table_url Required

Keyword-Only Parameters

Name	Description
credential Required

Returns

Type	Description
TableClient	A table client.

get_entity

Get 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] 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

Get a single entity 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 Number of entities returned per service request.
select	str or list[str] Specify desired properties of an entity to return.

Returns

Type	Description
ItemPaged[TableEntity]	An iterator of TableEntity

Exceptions

Type	Description
HttpResponseError

Examples

List 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

Lists 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 Number of entities returned per service request.
select	str or list[str] Specify desired properties of an entity to return.
parameters	dict[str, Any] Dictionary for formatting query with additional, user defined parameters

Returns

Type	Description
ItemPaged[TableEntity]	An iterator of TableEntity

Exceptions

Type	Description
HttpResponseError

Examples

Query 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: Dict[str, TableAccessPolicy | None], **kwargs) -> None

Parameters

Name	Description
signed_identifiers Required	dict[str, TableAccessPolicy] or dict[str, None] Access policies to set for the table

Returns

Type	Description
	None

Exceptions

Type	Description
HttpResponseError

submit_transaction

Commit 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

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})`

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

   self.table_client = TableClient.from_connection_string(
       conn_str=self.connection_string, table_name=self.table_name
   )

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

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

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

update_entity

Update 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 Etag of the entity
match_condition	MatchConditions The condition under which to perform the operation. Supported values include: MatchConditions.IfNotModified, MatchConditions.Unconditionally. The default value is Unconditionally.

Returns

Type	Description
dict[str, Any]	Dictionary mapping operation metadata returned from the service

Exceptions

Type	Description
HttpResponseError

Examples

Updating an already exiting 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

Update/Merge or Insert entity into 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

Update/merge or insert 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.

TableClient Class

Constructor

Parameters

Keyword-Only Parameters

Variables

Methods

close

create_entity

Parameters

Returns

Exceptions

Examples

create_table

Returns

Exceptions

Examples

delete_entity

delete_table

Returns

Exceptions

Examples

from_connection_string

Parameters

Returns

Examples

from_table_url

Parameters

Keyword-Only Parameters

Returns

get_entity

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

get_table_access_policy

Returns

Exceptions

list_entities

Keyword-Only Parameters

Returns

Exceptions

Examples

query_entities

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

set_table_access_policy

Parameters

Returns

Exceptions

submit_transaction

Parameters

Returns

Exceptions

Examples

update_entity

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

upsert_entity

Parameters

Returns

Exceptions

Examples

Attributes

api_version

Returns

url

Returns

Feedback

Additional resources