TableClient Class

Reference

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

Inheritance: azure.data.tables._base_client.TablesBaseClient

TableClient

Constructor

TableClient(endpoint: str, table_name: str, **kwargs: Any)

Parameters

endpoint

table_name

Variables

account_name: str

The name of the Tables account.

table_name: str

The name of the table.

url: str

The full URL to the Tables account.

Methods

create_entity	Insert entity in a table.
create_table	Creates a new table under the current account.
delete_entity	Deletes the specified entity in a table. No error will be raised if the entity or PartitionKey-RowKey pairing is not found.
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	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.

create_entity

Insert entity in a table.

create_entity(entity: Union[azure.data.tables._entity.TableEntity, Mapping[str, Any]], **kwargs: Any) -> Dict[str, str]

Parameters

entity: <xref:Union>[TableEntity, <xref:Mapping>[str, <xref:Any>]]

Required

The properties for the table entity.

Returns

Dictionary mapping operation metadata returned from the service

Return type

<xref:Dict>[<xref:str,str>]

Exceptions

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: Any) -> azure.data.tables._models.TableItem

Returns

A TableItem representing the created table.

Return type

TableItem

Exceptions

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="myTable") as table_client:
       try:
           table_client.create_table()
           print("Created table {}!".format(table_client.table_name))
       except ResourceExistsError:
           print("Table already exists")

delete_entity

Deletes the specified entity in a table. No error will be raised if the entity or PartitionKey-RowKey pairing is not found.

delete_entity(partition_key, row_key, **kwargs)

Parameters

partition_key: str

Required

The partition key of the entity.

row_key: str

Required

The row key of the entity.

entity: <xref:Union>[TableEntity, <xref:Mapping>[str, str]]

Required

The entity to delete

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

None

Return type

None

Exceptions

HttpResponseError

Examples

Deleting an entity of a Table


   table_client.delete_entity(row_key=self.entity["RowKey"], partition_key=self.entity["PartitionKey"])
   print("Successfully deleted!")

delete_table

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

delete_table(**kwargs: Any) -> None

Returns

None

Return type

None

Exceptions

HttpResponseError

Examples

Deleting a table from the TableClient object


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

from_connection_string

Create TableClient from a Connection String.

from_connection_string(conn_str: str, table_name: str, **kwargs: Any) -> azure.data.tables._table_client.TableClient

Parameters

conn_str: str

Required

A connection string to an Azure Tables account.

table_name: str

Required

The table name.

table_name

Required

Returns

A table client.

Return type

TableClient

Exceptions

HttpResponseError

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("Table name: {}".format(table_client.table_name))

from_table_url

A client to interact with a specific Table.

from_table_url(table_url: str, **kwargs: Any) -> azure.data.tables._table_client.TableClient

Parameters

table_url: str

Required

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

credential: AzureNamedKeyCredential or AzureSasCredential

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 or AzureSasCredential from azure-core.

Returns

A table client.

Return type

TableClient

Exceptions

HttpResponseError

get_entity

Get a single entity in a table.

get_entity(partition_key: str, row_key: str, **kwargs: Any) -> azure.data.tables._entity.TableEntity

Parameters

partition_key: str

Required

The partition key of the entity.

row_key: str

Required

The row key of the entity.

select: str or <xref:List>[str]

Specify desired properties of an entity to return.

Returns

Dictionary mapping operation metadata returned from the service

Return type

TableEntity

Exceptions

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("Received entity: {}".format(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: Any) -> Dict[str, Optional[azure.data.tables._models.TableAccessPolicy]]

Returns

Dictionary of SignedIdentifiers

Return type

<xref:Dict>[str, <xref:Optional>[TableAccessPolicy]]

Exceptions

HttpResponseError

list_entities

Lists entities in a table.

list_entities(**kwargs: Any) -> azure.core.paging.ItemPaged[azure.data.tables._entity.TableEntity]

Parameters

results_per_page: int

Number of entities returned per service request.

select: str or <xref:List>[str]

Specify desired properties of an entity to return.

Returns

ItemPaged[TableEntity]

Return type

ItemPaged

Exceptions

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("Entity #{}: {}".format(entity, i))

query_entities

Lists entities in a table.

query_entities(query_filter: str, **kwargs: Dict[str, Any]) -> azure.core.paging.ItemPaged[azure.data.tables._entity.TableEntity]

Parameters

query_filter: str

Required

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

results_per_page: int

Number of entities returned per service request.

select: str or <xref:List>[str]

Specify desired properties of an entity to return.

parameters: <xref:Dict>[str, <xref:Any>]

Dictionary for formatting query with additional, user defined parameters

Returns

ItemPaged[TableEntity]

Return type

ItemPaged

Exceptions

HttpResponseError

Examples

Query entities held within a table


   with TableClient.from_connection_string(self.connection_string, self.table_name) as table_client:
       try:
           parameters = {"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)

       except HttpResponseError as e:
           print(e.message)

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, Optional[azure.data.tables._models.TableAccessPolicy]], **kwargs) -> None

Parameters

signed_identifiers: <xref:Dict>[str, <xref:Optional>[TableAccessPolicy]]

Required

Access policies to set for the table

Returns

None

Return type

None

Exceptions

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[Union[Tuple[Union[azure.data.tables._models.TransactionOperation, str], Union[azure.data.tables._entity.TableEntity, Mapping[str, Any]]], Tuple[Union[azure.data.tables._models.TransactionOperation, str], Union[azure.data.tables._entity.TableEntity, Mapping[str, Any]], Mapping[str, Any]]]], **kwargs: Any) -> List[Mapping[str, Any]]

Parameters

operations: <xref:Iterable>[<xref:Tuple>[str, TableEntity, <xref:Mapping>[str, <xref:Any>]]]

Required

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

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

Return type

<xref:List>[<xref:Mapping>[str, <xref:Any>]]

Exceptions

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 = [
       ("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(e)

update_entity

Update entity in a table.

update_entity(entity: Union[azure.data.tables._entity.TableEntity, Mapping[str, Any]], mode: azure.data.tables._models.UpdateMode = <UpdateMode.MERGE: 'merge'>, **kwargs: Any) -> Dict[str, str]

Parameters

entity: TableEntity or <xref:Dict>[<xref:str,str>]

Required

The properties for the table entity.

mode: UpdateMode

Required

Merge or Replace entity

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

Dictionary mapping operation metadata returned from the service

Return type

<xref:Dict>[<xref:str,str>]

Exceptions

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=created["PartitionKey"], row_key=created["RowKey"])
   print("Replaced entity: {}".format(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=replaced["PartitionKey"], row_key=replaced["RowKey"])
   print("Merged entity: {}".format(merged))

upsert_entity

Update/Merge or Insert entity into table.

upsert_entity(entity: Union[azure.data.tables._entity.TableEntity, Mapping[str, Any]], mode: azure.data.tables._models.UpdateMode = <UpdateMode.MERGE: 'merge'>, **kwargs: Any) -> Dict[str, str]

Parameters

entity: TableEntity or <xref:Dict>[<xref:str,str>]

Required

The properties for the table entity.

mode: UpdateMode

Required

Merge or Replace entity

Returns

Dictionary mapping operation metadata returned from the service

Return type

<xref:Dict>[<xref:str,str>]

Exceptions

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("Inserted entity: {}".format(insert_entity))

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