Azure Storage Tables REST API Reference

Introduction to Tables

Azure Table Storage is a NoSQL key-attribute store that accepts authenticated calls from Azure Resource Manager. Table Storage is designed to store large amounts of structured, non-relational data. You can access your data from anywhere in the world by using authenticated calls to the Azure Storage REST API. Table Storage is a NoSQL datastore that allows you to store and query massive amounts of entities. It's a great choice for applications that need a flexible schema and high scalability.

This document provides a comprehensive reference for the Azure Storage Tables REST API, detailing the various operations you can perform on your tables and entities.

Learn more about REST API

REST API Overview

The Azure Storage Tables REST API allows you to interact with your Table Storage data programmatically. It uses standard HTTP verbs (GET, POST, PUT, DELETE) and conventions to perform operations.

The base URI for the Tables REST API is:

https://{accountname}.table.core.windows.net/{tablename}

Where:

All requests must be authenticated using Shared Key or Shared Access Signatures (SAS).

Table Operations

The following table lists the primary operations available for managing tables within Azure Table Storage:

Operation HTTP Method URL Description
Create Table POST /Tables Creates a new table in the storage account. Requires a request body specifying the table name.
List Tables GET /Tables Retrieves a list of all tables within the storage account. Supports OData query options for filtering and pagination.
Query Tables GET /Tables?$filter=TableName eq '{table_name}' Retrieves a specific table by name.
Delete Table DELETE /Tables('{table_name}') Deletes a specified table from the storage account.

Entity Operations

Entities are the basic units of data in Azure Table Storage. Each entity is a collection of properties, which are essentially name-value pairs. Entities are structured using the PartitionKey and RowKey for efficient retrieval.

The following table lists the primary operations available for managing entities within a table:

Operation HTTP Method URL Description
Insert Entity POST /{tablename} Inserts a single entity into a table. Requires a request body containing the entity's properties, including PartitionKey and RowKey.
Batch Insert Entities POST /$batch Inserts multiple entities in a single batch operation, improving efficiency.
Query Entities GET /{tablename}(PartitionKey='{pk}',RowKey='{rk}') Retrieves a specific entity using its PartitionKey and RowKey.
Query Entities (with OData) GET /{tablename}?$filter=... Queries entities within a table using OData filter expressions for flexible data retrieval.
Update Entity (Insert or Replace) PUT /{tablename}(PartitionKey='{pk}',RowKey='{rk}') Inserts an entity if it doesn't exist, or replaces it entirely if it does.
Update Entity (Merge) MERGE /{tablename}(PartitionKey='{pk}',RowKey='{rk}') Merges an existing entity with new property values. Properties not included in the request remain unchanged.
Delete Entity DELETE /{tablename}(PartitionKey='{pk}',RowKey='{rk}') Deletes a specific entity from a table.

Entity Structure and Properties

An entity in Azure Table Storage is a collection of properties. Each property consists of a name and a value. The value has a specific data type. Every entity must have the following system properties:

Custom properties can be of various data types, including:

Entities can have up to 252 custom properties, in addition to the three system properties.

Querying Entities with OData

The Tables REST API supports OData (Open Data Protocol) for powerful querying capabilities. You can filter, order, select specific properties, and paginate results.

Key OData query parameters:

Example Filter: Retrieving entities with Age > 30

GET https://{accountname}.table.core.windows.net/{tablename}?$filter=Age gt 30

Example Select and OrderBy: Retrieving Name and Email, ordered by Name

GET https://{accountname}.table.core.windows.net/{tablename}?$select=Name,Email&$orderby=Name asc

Batch Operations

To improve performance and reduce the number of HTTP requests, you can perform multiple table or entity operations in a single batch request.

A batch request is sent as a POST request to the /$batch endpoint. The request body must adhere to the MIME multipart format, with each part representing an individual operation.

Batch Request Structure (Simplified)

POST /$batch HTTP/1.1
Content-Type: multipart/mixed; boundary=batch_boundary

--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

GET /Tables?$filter=TableName eq 'MyTable'

--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /MyTable
Content-Type: application/json

{
  "PartitionKey": "group1",
  "RowKey": "item1",
  "Description": "First item"
}

--batch_boundary--
Learn more about entity operations

Authentication

All requests to the Azure Storage Tables API must be authenticated. The primary methods are:

It is recommended to use SAS tokens for client-side access to limit the potential impact of compromised credentials.

Azure Storage Authentication Details