Azure Storage Docs

Managing Entities in Azure Storage Tables

Azure Table Storage is a NoSQL key-value store that allows you to store large amounts of structured, non-relational data. Entities in Azure Table Storage are represented as collections of properties. This document explains how to manage these entities, including creating, retrieving, updating, and deleting them.

Understanding Entities and Properties

An entity in Azure Table Storage is a collection of properties. Each entity must have at least two properties:

• PartitionKey: A string value that dictates the grouping of entities. Entities with the same PartitionKey are stored together on the same storage node. This is crucial for performance and scalability.
• RowKey: A string value that uniquely identifies an entity within a partition. Together, PartitionKey and RowKey form the entity's primary key.

Other properties can be any name-value pair, where the value can be one of the following data types:

• String
• DateTime
• Boolean
• Int32
• Int64
• Double
• Guid
• Binary (byte array)
• String (UTF-16)

Creating Entities

To create an entity, you need to specify its PartitionKey, RowKey, and any other properties. Here's an example using the Azure SDK for .NET:

using Azure.Data.Tables;

// Assuming you have a table client initialized
TableClient tableClient = new TableClient(connectionString, tableName);
await tableClient.CreateIfNotExistsAsync();

var customerEntity = new TableEntity("Marketing", "987")
{
    { "FullName", "Sarah Lee" },
    { "Email", "sarah.lee@example.com" },
    { "IsActive", true },
    { "CustomerSince", new DateTime(2022, 5, 15) }
};

await tableClient.AddEntityAsync(customerEntity);
                

Retrieving Entities

Entities can be retrieved using their primary key (PartitionKey and RowKey) or by querying the table.

Retrieving by Primary Key

This is the most efficient way to get a single entity.

Response<TableEntity> response = await tableClient.GetEntityAsync<TableEntity>("Marketing", "987");
TableEntity customer = response.Value;

Console.WriteLine($"Customer Name: {customer["FullName"]}");
                

Querying Entities

You can query for entities using OData filter syntax. Filters are applied server-side for efficiency.

// Get all active customers in the 'Marketing' partition
string filter = "PartitionKey eq 'Marketing' and IsActive eq true";
Pageable<TableEntity> queryResults = tableClient.Query<TableEntity>(filter: filter);

foreach (TableEntity entity in queryResults)
{
    Console.WriteLine($"Found: {entity["FullName"]}");
}
                

Updating Entities

You can update an existing entity. If the entity does not exist, an error will occur unless you use an appropriate `SetEntity` method that handles creation.

There are several methods for updating:

• UpdateEntityAsync: Replaces the entire entity.
• MergeEntityAsync: Updates only the specified properties, leaving others untouched.

// Retrieve the entity first
Response<TableEntity> response = await tableClient.GetEntityAsync<TableEntity>("Marketing", "987");
TableEntity customer = response.Value;

// Update a property
customer["Email"] = "sarah.lee.updated@example.com";

// Merge the update
await tableClient.UpdateEntityAsync(customer, customer.GetETag(), TableUpdateMode.Merge);
                

Deleting Entities

Entities can be deleted using their primary key.

await tableClient.DeleteEntityAsync("Marketing", "987");
                

Best Practices

• Choose your PartitionKey carefully to distribute data evenly and optimize read/write operations.
• Use descriptive names for properties.
• Leverage OData filters for efficient querying.
• Understand the difference between UpdateEntityAsync and MergeEntityAsync.
• Consider the ETag for optimistic concurrency control during updates.

By understanding and applying these concepts, you can effectively manage your data within Azure Table Storage.