az-storage-entity

Insert an entity into a table

$ az storage entity insert [[-e|--entity]] [space_separated_key_value_pairs] [[-t|--table-name]] [table_name] --account-name [storage_account_name] --account-key [storage_account_key]

$ az storage entity delete --partition-key [partition_key] --row-key [row_key] [[-t|--table-name]] [table_name] --account-name [storage_account_name] --account-key [storage_account_key]

$ az storage entity merge [[-e|--entity]] [space_separated_key_value_pairs] [[-t|--table-name]] [table_name] --account-name [storage_account_name] --account-key [storage_account_key]

$ az storage entity query --filter [query_filter] [[-t|--table-name]] [table_name] --account-name [storage_account_name] --account-key [storage_account_key]

$ az storage entity show --partition-key [partition_key] --row-key [row_key] [[-t|--table-name]] [table_name] --account-name [storage_account_name] --account-key [storage_account_key]

The az storage entity command acts as a group for various subcommands. The general form is:

az storage entity <SUBCOMMAND> [OPTIONS]

Common subcommands include:
query: Query entities in a table.
insert: Insert a new entity into a table.
update: Update an existing entity in a table (replaces entire entity).
merge: Merge properties into an existing entity in a table.
delete: Delete an entity from a table.
show: Alias for query specific entity using partition and row key.

Example syntax for querying a specific entity:
az storage entity query --table-name myTable --partition-key myPartition --row-key myRow --connection-string "DefaultEndpointsProtocol=..."

Example syntax for inserting a new entity:
az storage entity insert --table-name myTable --entity "{'PartitionKey': 'p1', 'RowKey': 'r1', 'Name': 'Item1'}" --account-name myaccount --account-key mykey

--table-name <name> or -t <name>
    Mandatory. The name of the table to operate on.

--partition-key <key> or -p <key>
    The partition key of the entity. Required for operations on specific entities (e.g., query, insert, update, delete).

--row-key <key> or -r <key>
    The row key of the entity. Required for operations on specific entities.

--entity <json>
    A JSON string representing the entity's properties. Required for insert, update, or merge operations.

--connection-string <string>
    The Azure Storage connection string. A common method for authentication and specifying the storage account.

--account-name <name>
    The name of the Azure Storage account. Used in conjunction with --account-key or --sas-token for authentication, or relies on default CLI credentials.

--account-key <key>
    The Azure Storage account key. Used with --account-name for authentication.

--sas-token <token>
    A Shared Access Signature (SAS) token. Used with --account-name for authentication, providing limited permissions.

--filter <odata_expression>
    An OData filter string to narrow down results for query operations (e.g., 'PropertyName eq 'Value'').

--select <properties>
    A comma-separated list of properties to return for query operations, reducing payload size.

--num-results <count>
    Maximum number of entities to return from a query operation. Defaults to 1000.

The az storage entity command is a powerful subcommand within the Azure Command-Line Interface (Azure CLI) that enables you to manage individual entities (rows) within Azure Storage tables. It provides comprehensive capabilities for performing Create, Read, Update, and Delete (CRUD) operations on structured data stored in a NoSQL key-value store fashion.

This command allows you to insert new entities, query existing ones, update or merge properties of entities, and delete them from specific tables. It supports various authentication methods, including connection strings, shared access signatures (SAS), and Azure Active Directory (Azure AD) authentication. az storage entity is essential for scripting and automating data management tasks within Azure Storage tables, providing a command-line alternative to graphical tools or SDKs.

Caveats and limitations:

• Requires the Azure CLI to be installed and configured on your system.
• An authenticated Azure session via az login or explicit authentication parameters (--connection-string, --account-name/--account-key/--sas-token) are mandatory.
• Proper permissions on the target Azure Storage account and table are necessary for all operations.
• Entities within a table are schema-less, but PartitionKey and RowKey are mandatory for every entity and together form its unique identifier.
• OData query syntax for --filter and --select can be complex and requires understanding of the OData protocol.
• Operations like update perform a full replacement of the entity, while merge updates specific properties. Choose carefully.

az storage entity supports multiple authentication methods. The most common are providing an Azure Storage connection string, or separately providing the account name and either an account key or a Shared Access Signature (SAS) token. Alternatively, if logged into Azure CLI via az login, it can use Azure Active Directory (Azure AD) for authentication, provided the user or service principal has the necessary RBAC roles (e.g., "Storage Table Data Contributor").

Every entity in an Azure Table Storage table must have a PartitionKey and a RowKey. These two properties together form the unique identifier for an entity within a table. PartitionKey helps organize entities into partitions for scalability and query performance, while RowKey uniquely identifies an entity within its specific partition. These keys are crucial for efficient data retrieval and transactional consistency.

The command will output detailed error messages to stderr if operations fail due to reasons such as incorrect table names, invalid keys, permission issues, or malformed JSON entity data. It's important to check the exit code (e.g., $? in bash) for scripting purposes to ensure command success or failure.

The az storage entity command is an integral part of the Azure CLI, developed and maintained by Microsoft. It has evolved alongside the Azure Storage Tables service capabilities, with updates typically released as part of broader Azure CLI updates. Its development focus has been on providing robust, scriptable interfaces for managing NoSQL table data, mirroring the functionality available in SDKs and the Azure portal. Continuous integration and improvements are driven by user feedback and the evolution of Azure services.

az storage table, az storage account, az login, az logout