How to use Azure Table storage with Ruby


The content in this article applies to Azure Table storage. However, there is now a premium offering for table storage, the Azure Cosmos DB Table API that offers throughput-optimized tables, global distribution, and automatic secondary indexes. To learn more and try out the premium experience, please check out Azure Cosmos DB Table API. This article's programming language is not yet supported in the premium offering, but will be added in the future.


This guide shows you how to perform common scenarios using the Azure Table service. The samples are written using the Ruby API. The scenarios covered include creating and deleting a table, inserting and querying entities in a table.

What is Table storage

Azure Table storage stores large amounts of structured data. The service is a NoSQL datastore which accepts authenticated calls from inside and outside the Azure cloud. Azure tables are ideal for storing structured, non-relational data. Common uses of Table storage include:

  • Storing TBs of structured data capable of serving web scale applications
  • Storing datasets that don't require complex joins, foreign keys, or stored procedures and can be denormalized for fast access
  • Quickly querying data using a clustered index
  • Accessing data using the OData protocol and LINQ queries with WCF Data Service .NET Libraries

You can use Table storage to store and query huge sets of structured, non-relational data, and your tables will scale as demand increases.

Table storage concepts

Table storage contains the following components:

Tables storage component diagram

  • URL format: Code addresses tables in an account using this address format:
    http://<storage account><table>

    You can address Azure tables directly using this address with the OData protocol. For more information, see

  • Storage Account: All access to Azure Storage is done through a storage account. See Azure Storage Scalability and Performance Targets for details about storage account capacity.
  • Table: A table is a collection of entities. Tables don't enforce a schema on entities, which means a single table can contain entities that have different sets of properties. The number of tables that a storage account can contain is limited only by the storage account capacity limit.
  • Entity: An entity is a set of properties, similar to a database row. An entity can be up to 1MB in size.
  • Properties: A property is a name-value pair. Each entity can include up to 252 properties to store data. Each entity also has three system properties that specify a partition key, a row key, and a timestamp. Entities with the same partition key can be queried more quickly, and inserted/updated in atomic operations. An entity's row key is its unique identifier within a partition.

For details about naming tables and properties, see Understanding the Table Service Data Model.

Create an Azure storage account

The easiest way to create your first Azure storage account is by using the Azure portal. To learn more, see Create a storage account.

You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Storage Resource Provider Client Library for .NET.

If you prefer not to create a storage account at this time, you can also use the Azure storage emulator to run and test your code in a local environment. For more information, see Use the Azure Storage Emulator for Development and Testing.

Create a Ruby application

For instructions how to create a Ruby application, see Ruby on Rails Web application on an Azure VM.

Configure your application to access Storage

To use Azure Storage, you need to download and use the Ruby azure package which includes a set of convenience libraries that communicate with the Storage REST services.

Use RubyGems to obtain the package

  1. Use a command-line interface such as PowerShell (Windows), Terminal (Mac), or Bash (Unix).
  2. Type gem install azure in the command window to install the gem and dependencies.

Import the package

Use your favorite text editor, add the following to the top of the Ruby file where you intend to use Storage:

require "azure"

Set up an Azure Storage connection

The azure module will read the environment variables AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_ACCESS_KEY for information required to connect to your Azure Storage account. If these environment variables are not set, you must specify the account information before using Azure::TableService with the following code:

Azure.config.storage_account_name = "<your azure storage account>"
Azure.config.storage_access_key = "<your azure storage access key>"

To obtain these values from a classic or Resource Manager storage account in the Azure portal:

  1. Log in to the Azure portal.
  2. Navigate to the storage account you want to use.
  3. In the Settings blade on the right, click Access Keys.
  4. In the Access keys blade that appears, you'll see the access key 1 and access key 2. You can use either of these.
  5. Click the copy icon to copy the key to the clipboard.

Create a table

The Azure::TableService object lets you work with tables and entities. To create a table, use the create_table() method. The following example creates a table or prints the error if there is any.

azure_table_service =
    puts $!

Add an entity to a table

To add an entity, first create a hash object that defines your entity properties. Note that for every entity you must specify a PartitionKey and RowKey. These are the unique identifiers of your entities, and are values that can be queried much faster than your other properties. Azure Storage uses PartitionKey to automatically distribute the table's entities over many storage nodes. Entities with the same PartitionKey are stored on the same node. The RowKey is the unique ID of the entity within the partition it belongs to.

entity = { "content" => "test entity",
    :PartitionKey => "test-partition-key", :RowKey => "1" }
azure_table_service.insert_entity("testtable", entity)

Update an entity

There are multiple methods available to update an existing entity:

  • update_entity(): Update an existing entity by replacing it.
  • merge_entity(): Updates an existing entity by merging new property values into the existing entity.
  • insert_or_merge_entity(): Updates an existing entity by replacing it. If no entity exists, a new one will be inserted:
  • insert_or_replace_entity(): Updates an existing entity by merging new property values into the existing entity. If no entity exists, a new one will be inserted.

The following example demonstrates updating an entity using update_entity():

entity = { "content" => "test entity with updated content",
    :PartitionKey => "test-partition-key", :RowKey => "1" }
azure_table_service.update_entity("testtable", entity)

With update_entity() and merge_entity(), if the entity that you are updating doesn't exist then the update operation will fail. Therefore if you wish to store an entity regardless of whether it already exists, you should instead use insert_or_replace_entity() or insert_or_merge_entity().

Work with groups of entities

Sometimes it makes sense to submit multiple operations together in a batch to ensure atomic processing by the server. To accomplish that, you first create a Batch object and then use the execute_batch() method on TableService. The following example demonstrates submitting two entities with RowKey 2 and 3 in a batch. Notice that it only works for entities with the same PartitionKey.

azure_table_service =
batch ="testtable",
    "test-partition-key") do
    insert "2", { "content" => "new content 2" }
    insert "3", { "content" => "new content 3" }
results = azure_table_service.execute_batch(batch)

Query for an entity

To query an entity in a table, use the get_entity() method, by passing the table name, PartitionKey and RowKey.

result = azure_table_service.get_entity("testtable", "test-partition-key",

Query a set of entities

To query a set of entities in a table, create a query hash object and use the query_entities() method. The following example demonstrates getting all the entities with the same PartitionKey:

query = { :filter => "PartitionKey eq 'test-partition-key'" }
result, token = azure_table_service.query_entities("testtable", query)


If the result set is too large for a single query to return, a continuation token will be returned which you can use to retrieve subsequent pages.

Query a subset of entity properties

A query to a table can retrieve just a few properties from an entity. This technique, called "projection", reduces bandwidth and can improve query performance, especially for large entities. Use the select clause and pass the names of the properties you would like to bring over to the client.

query = { :filter => "PartitionKey eq 'test-partition-key'",
    :select => ["content"] }
result, token = azure_table_service.query_entities("testtable", query)

Delete an entity

To delete an entity, use the delete_entity() method. You need to pass in the name of the table which contains the entity, the PartitionKey and RowKey of the entity.

azure_table_service.delete_entity("testtable", "test-partition-key", "1")

Delete a table

To delete a table, use the delete_table() method and pass in the name of the table you want to delete.


Next steps