Azure Storage Tables REST API Reference

Overview

The Azure Storage Tables service provides a NoSQL key-value store that can be accessed from any cloud application or client. It stores data as a collection of entities, where each entity is a set of properties. The Tables service is schema-less, allowing you to store data of various structures within the same table.

This reference details the REST API for interacting with Azure Storage Tables. It covers operations for managing tables and entities, including creating, querying, updating, and deleting them.

Tables REST API

Core Operations

The Tables REST API exposes a set of operations that allow you to manage tables and entities. These operations are typically performed via HTTP requests.

Operation HTTP Verb Path Description
Create Table POST /Tables Creates a new table within the storage account.
Query Tables GET /Tables Queries for tables within the storage account.
Delete Table DELETE /Tables('TableName') Deletes a table from the storage account.
Insert Entity POST /TableName Inserts a new entity into a table.
Query Entities GET /TableName Queries for entities within a table.
Update Entity PUT /TableName(PartitionKey='PK',RowKey='RK') Updates an existing entity completely.
Merge Entity MERGE /TableName(PartitionKey='PK',RowKey='RK') Updates an existing entity by merging properties.
Delete Entity DELETE /TableName(PartitionKey='PK',RowKey='RK') Deletes an entity from a table.
Batch Operations POST /$batch Performs multiple operations as a single batch request.

Authentication

All requests to the Azure Storage Tables API must be authenticated. Common methods include:

  • Shared Key authentication
  • Shared Access Signatures (SAS)
  • Azure Active Directory (Azure AD) integration
For detailed authentication methods, refer to the Azure Storage authentication documentation.

Data Model

The core concepts in Azure Storage Tables are:

  • Account: The top-level container for your storage data.
  • Table: A collection of entities. Tables are schema-less.
  • Entity: A record within a table, analogous to a row in a database. An entity can contain up to 252 properties.
  • Property: A name-value pair within an entity. Each property has a name, a data type, and a value.

Every entity must include the following system properties:

  • PartitionKey (String): Used for partitioning data.
  • RowKey (GUID, Integer, or String): Uniquely identifies an entity within a partition.
  • Timestamp (DateTime): Automatically managed by the service.

Table Operations

Create Table

Use the POST /Tables operation to create a new table.

POST https://.table.core.windows.net/Tables
Content-Type: application/json
Accept: application/json
Authorization: SharedKey :

{
    "TableName": "MyNewTable"
}

Query Tables

Use the GET /Tables operation to query for tables.

GET https://.table.core.windows.net/Tables?$filter=TableName eq 'MyTable'
Accept: application/json
Authorization: SharedKey :

You can use OData query options like $filter, $top, and $select.

Delete Table

Use the DELETE /Tables('TableName') operation to delete a table.

DELETE https://.table.core.windows.net/Tables('MyTable')
Authorization: SharedKey :

Entity Operations

Insert Entity

Use the POST /TableName operation to insert an entity.

POST https://.table.core.windows.net/MyTable
Content-Type: application/json
Accept: application/json
Authorization: SharedKey :

{
    "PartitionKey": "Customers",
    "RowKey": "123",
    "Name": "John Doe",
    "Email": "john.doe@example.com",
    "Age": 30,
    "IsVip": true,
    "RegistrationDate": "2023-01-15T10:00:00Z"
}
Property names cannot begin with a forward slash (/), a colon (:), a dollar sign ($), or the letter #.

Query Entities

Use the GET /TableName operation to query entities. Use OData filter expressions for powerful querying.

GET https://.table.core.windows.net/MyTable?$filter=PartitionKey eq 'Customers' and Age gt 25
Accept: application/json
Authorization: SharedKey :

Supported query operators include:

  • Comparison: eq, ne, gt, ge, lt, le
  • Logical: and, or, not
  • Arithmetic: add, sub, mul, div, mod
  • String functions: concat, length, substringof, tolower, toupper, trim, replace
  • Date functions: year, month, day, hour, minute, second, date, time, now

Update Entity

Use the PUT /TableName(PartitionKey='PK',RowKey='RK') operation to update an entity. This replaces the entire entity.

PUT https://.table.core.windows.net/MyTable(PartitionKey='Customers',RowKey='123')
Content-Type: application/json
Accept: application/json
Authorization: SharedKey :

{
    "Name": "Johnathan Doe",
    "Email": "john.d@example.com",
    "Age": 31,
    "IsVip": false,
    "Address": "123 Main St"
}

Merge Entity

Use the MERGE /TableName(PartitionKey='PK',RowKey='RK') operation to merge properties into an existing entity. Properties not included in the request are retained.

MERGE https://.table.core.windows.net/MyTable(PartitionKey='Customers',RowKey='123')
Content-Type: application/json
Accept: application/json
Authorization: SharedKey :

{
    "Age": 32,
    "City": "Metropolis"
}

Delete Entity

Use the DELETE /TableName(PartitionKey='PK',RowKey='RK') operation to delete an entity.

DELETE https://.table.core.windows.net/MyTable(PartitionKey='Customers',RowKey='123')
Authorization: SharedKey :

Batch Operations

Execute multiple operations atomically using the POST /$batch endpoint.

POST https://.table.core.windows.net/$batch
Content-Type: multipart/mixed; boundary=batch_boundary
Accept: application/json
Authorization: SharedKey :

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

POST MyTable HTTP/1.1
Content-Type: application/json
Accept: application/json

{
    "PartitionKey": "Orders",
    "RowKey": "Order1001",
    "CustomerId": "123",
    "OrderDate": "2023-10-27T14:30:00Z",
    "TotalAmount": 150.75
}

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

POST MyTable HTTP/1.1
Content-Type: application/json
Accept: application/json

{
    "PartitionKey": "Orders",
    "RowKey": "Order1002",
    "CustomerId": "456",
    "OrderDate": "2023-10-27T15:00:00Z",
    "TotalAmount": 210.00
}

--batch_boundary--

Supported Properties

The Azure Storage Tables service supports the following primitive data types for properties:

  • Edm.String
  • Edm.Int32
  • Edm.Int64
  • Edm.Double
  • Edm.Boolean
  • Edm.DateTime (UTC)
  • Edm.Guid
  • Edm.Binary (byte array)
  • Edm.Decimal
  • Edm.Single

Note that the Timestamp system property is always Edm.DateTime.

Data Formats

The Tables API supports different data formats for requests and responses:

  • JSON (application/json): The most common and recommended format.
  • AtomPub (application/atom+xml): An older format, still supported but JSON is preferred for new development.

Use the Accept header to specify the desired response format and the Content-Type header for request payloads.

Error Handling

Azure Storage returns standard HTTP status codes for API requests. Error responses typically include a JSON or XML payload with details about the error.

Common HTTP Status Codes:

  • 200 OK: Request successful.
  • 201 Created: Resource successfully created.
  • 204 No Content: Request successful, but no response body.
  • 400 Bad Request: The request was invalid.
  • 401 Unauthorized: Authentication failed.
  • 403 Forbidden: Access denied.
  • 404 Not Found: The requested resource could not be found.
  • 409 Conflict: The request could not be completed due to a conflict.
  • 500 Internal Server Error: An unexpected error occurred on the server.

Error response example (JSON):

{
    "error": {
        "code": "BadRequest",
        "message": "The requested query syntax is invalid.\nRequestId:...",
        "details": [...]
    }
}
🚀 Try the Azure Portal or Storage Explorer to visualize and manage your tables!
© 2023 Microsoft Corporation. All rights reserved.