Table Storage Entities

This document provides a detailed explanation of entities within Azure Table Storage, covering their structure, properties, and best practices.

What is an Entity?

In Azure Table Storage, an entity is the fundamental unit of data. It's similar to a row in a relational database, but with a more flexible schema. Each entity is stored in a table and is identified by a unique PartitionKey and RowKey.

Entity Structure

Every entity in Azure Table Storage has the following mandatory properties:

• PartitionKey (String): A string that logically groups entities. Entities with the same PartitionKey are guaranteed to be stored on the same storage node, which improves query performance when filtering by PartitionKey.
• RowKey (String): A string that uniquely identifies an entity within a given PartitionKey. The combination of PartitionKey and RowKey must be unique for each entity in a table.

In addition to the mandatory properties, an entity can contain up to 252 custom properties. These properties can be of various data types, including:

• String
• Int32
• Int64
• Boolean
• DateTime
• Double
• Guid
• Binary (Byte array)
• Complex types can be serialized into strings or byte arrays.

Entity Limits

Be aware of the following limits when working with entities:

• An entity can have a maximum of 255 properties (including PartitionKey and RowKey).
• The maximum size of an entity is 1 MB.
• Property names must be between 1 and 63 characters.
• Property names cannot start with a reserved system character (e.g., `odata.`).

Working with Entities

You can perform various operations on entities using the Azure SDKs or REST API:

• Insert Entity: Adds a new entity to a table.
• Update Entity: Modifies an existing entity. This can be a complete replacement or a merge.
• Delete Entity: Removes an entity from a table.
• Query Entities: Retrieves entities based on specified filters.

Example: Creating an Entity

Here's a conceptual example of creating an entity representing a user profile. In a real-world scenario, you would use an Azure SDK (e.g., .NET, Python, Java).

// Conceptual Example (using pseudocode)
let userEntity = {
    PartitionKey: "users",
    RowKey: "user123",
    Email: "john.doe@example.com",
    DisplayName: "John Doe",
    RegistrationDate: new Date("2023-10-27T10:00:00Z"),
    IsActive: true,
    LoginCount: 42
};

// Call an Azure SDK function to insert this entity into a table
// insertEntity("userTable", userEntity);
            

Entity Querying Considerations

When querying entities, leverage the PartitionKey and RowKey for efficient retrieval:

• Queries that filter on the PartitionKey are highly efficient as they target specific partitions.
• Queries that filter on both PartitionKey and RowKey are the most performant, directly identifying a single entity.
• Wildcard queries without PartitionKey filters can be less performant and may require scanning multiple partitions.

Data Types and Conversions

Azure Table Storage stores property values as primitive data types. When using the SDKs, you'll typically work with native language types which are then converted appropriately.

Supported Primitive Data Types

.NET Type	JSON Type	Description
string	String	Textual data.
sbyte, byte, short, ushort, int, uint, long, ulong	Number	Integer values.
float, double, decimal	Number	Floating-point numbers.
bool	Boolean	true or false.
DateTime	String (ISO 8601 format)	Date and time values.
Guid	String	Globally unique identifiers.
byte[]	String (Base64 encoded)	Binary data.

Next Steps

Now that you understand Azure Table Storage entities, you can explore how to query them efficiently or learn more about performance considerations.

• Querying Table Storage
• Optimizing Table Storage Performance