Inserting Entities into Azure Storage Tables

This document outlines the methods for inserting entities into Azure Storage Tables using various SDKs and REST APIs.

Understanding Entities and Operations

An entity in Azure Table Storage is a collection of properties. Each entity must have at least two properties: PartitionKey and RowKey. These two properties together form the unique identifier for an entity within a table. The Timestamp property is automatically managed by the service.

Insert Operations

Azure Table Storage supports several operations for inserting entities:

Insert Entity: Inserts a single entity. If an entity with the same PartitionKey and RowKey already exists, the operation fails with an HTTP 409 (Conflict) error.
Insert Entity With Merge: Inserts a single entity. If an entity with the same PartitionKey and RowKey exists, it is merged with the existing entity. Properties not present in the new entity are preserved from the existing entity.
Batch Insert Entities: Inserts multiple entities in a single batch operation. This operation is transactional and requires all entities to belong to the same PartitionKey.

Inserting a Single Entity

This is the most common operation for adding new data. You can use the Azure Storage SDKs for your preferred language or the REST API.

Using the Azure SDK for Python

Here's an example using the Azure SDK for Python to insert a single entity:

Python Example


from azure.data.tables import TableServiceClient
from azure.core.exceptions import ResourceExistsError

# Replace with your actual connection string
connection_string = "YOUR_AZURE_STORAGE_CONNECTION_STRING"
table_name = "MySampleTable"

try:
    table_service_client = TableServiceClient.from_connection_string(connection_string)
    table_client = table_service_client.get_table_client(table_name=table_name)

    entity = {
        "PartitionKey": "Customers",
        "RowKey": "user123",
        "Name": "Alice Wonderland",
        "Email": "alice@example.com",
        "Age": 30
    }

    # Insert the entity
    created_entity = table_client.create_entity(entity)
    print(f"Entity inserted successfully: {created_entity}")

except ResourceExistsError:
    print("Entity with the same PartitionKey and RowKey already exists.")
except Exception as e:
    print(f"An error occurred: {e}")

Using the Azure SDK for .NET

Here's an example using the Azure SDK for .NET:

C# Example


using Azure.Data.Tables;
using System;

// Replace with your actual connection string
string connectionString = "YOUR_AZURE_STORAGE_CONNECTION_STRING";
string tableName = "MySampleTable";

try
{
    var tableServiceClient = new TableServiceClient(connectionString);
    TableClient tableClient = tableServiceClient.GetTableClient(tableName);

    var entity = new Dictionary<string, object>
    {
        { "PartitionKey", "Customers" },
        { "RowKey", "user456" },
        { "Name", "Bob The Builder" },
        { "Email", "bob@example.com" },
        { "Age", 42 }
    };

    // Insert the entity
    var response = await tableClient.UpsertEntityAsync(entity, TableUpdateMode.Replace); // UpsertEntity can also be used with TableUpdateMode.Merge
    Console.WriteLine($"Entity inserted/updated successfully. Status: {response.Status}");
}
catch (RequestFailedException ex) when (ex.Status == 409)
{
    Console.WriteLine("Entity with the same PartitionKey and RowKey already exists.");
}
catch (Exception ex)
{
    Console.WriteLine($"An error occurred: {ex.Message}");
}

Batch Insert Entities

Batch operations allow you to send multiple insert, update, or delete operations for entities that share the same PartitionKey in a single HTTP request. This is more efficient than performing individual operations.

Important Note: A batch operation is only allowed for entities within the same PartitionKey.

Using the Azure SDK for Java

Here's an example using the Azure SDK for Java to perform a batch insert:

Java Example


import com.azure.data.tables.TableClient;
import com.azure.data.tables.TableServiceClient;
import com.azure.data.tables.TableServiceClientBuilder;
import com.azure.data.tables.models.TableEntity;
import com.azure.data.tables.models.TableTransactionAction;
import com.azure.data.tables.models.TableTransactionActionType;
import com.azure.core.util.Context;
import com.azure.core.exception. bất kỳ exception; // Assuming a generic exception for simplicity

// Replace with your actual connection string
String connectionString = "YOUR_AZURE_STORAGE_CONNECTION_STRING";
String tableName = "MySampleTable";

try {
    TableServiceClient tableServiceClient = new TableServiceClientBuilder()
            .connectionString(connectionString)
            .buildClient();
    TableClient tableClient = tableServiceClient.getTableClient(tableName);

    // Create entities for the same PartitionKey
    TableEntity entity1 = new TableEntity("Products", "sku001")
            .addProperty("Name", "Laptop")
            .addProperty("Price", 1200.00);

    TableEntity entity2 = new TableEntity("Products", "sku002")
            .addProperty("Name", "Mouse")
            .addProperty("Price", 25.50);

    // Create transaction actions for inserts
    TableTransactionAction insertAction1 = new TableTransactionAction(TableTransactionActionType.CREATE, entity1);
    TableTransactionAction insertAction2 = new TableTransactionAction(TableTransactionActionType.CREATE, entity2);

    // Submit the batch
    var response = tableClient.submitTransaction(Arrays.asList(insertAction1, insertAction2), Context.NONE);

    System.out.println("Batch insert completed. Status codes: " + response.stream()
            .map(transactionResponse -> Integer.toString(transactionResponse.getStatusCode()))
            .collect(Collectors.joining(", ")));

} catch ( bất kỳ exception e) {
    System.err.println("An error occurred during batch insert: " + e.getMessage());
    e.printStackTrace();
}

Common Properties for Entities

PartitionKey (string, required): Defines the partition for the entity. Entities with the same PartitionKey are colocated within the storage service, improving query performance for entities within the same partition.
RowKey (string, required): Defines the entity within a partition. It must be unique for each entity within a given PartitionKey.
Timestamp (DateTimeOffset, read-only): Automatically generated by the Azure Storage service and represents the last modified time of the entity.

Custom Properties

You can add any number of custom properties to an entity. Each property consists of a name (string) and a value. The value can be of various supported data types, including String, Int32, Int64, Double, Boolean, DateTime, Guid, Binary, Double, etc.

Tip: Choose your PartitionKey and RowKey carefully. A well-designed partitioning strategy is crucial for efficient querying and scaling.

REST API Endpoint for Inserting Entities

You can also insert entities directly using the Azure Table Storage REST API.

Request

Method: POST

URI: https://{accountName}.table.core.windows.net/{tableName}

Headers:

Header	Description
`Authorization`	SharedKey or SAS token for authentication.
`Accept`	`application/json;odata=minimalmetadata`
`Content-Type`	`application/json;odata=minimalmetadata`

Request Body (JSON):

JSON Example


{
    "PartitionKey": { "String": "Sensors" },
    "RowKey": { "String": "sensor-101" },
    "Temperature": { "Double": 25.5 },
    "Humidity": { "Int32": 60 },
    "ReadingTime": { "DateTime": "2023-10-27T10:30:00Z" }
}

Conclusion

Inserting entities is a fundamental operation when working with Azure Table Storage. By understanding the different insertion methods and the structure of entities, you can efficiently manage your data.

For more detailed information, please refer to the official Azure Table Storage REST API documentation.