How to use Azure Table Storage from Ruby

Tip

Try the Microsoft Azure Storage Explorer

Microsoft Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, OS X, and Linux.

Overview

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 the Table Service

The Azure Table storage service 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 the Table service 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 the Table service to store and query huge sets of structured, non-relational data, and your tables will scale as demand increases.

Table Service Concepts

The Table service contains the following components:

Table1

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

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

  • 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 3 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.

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

  1. Log in to the Azure classic portal.
  2. Navigate to the storage account you want to use.
  3. Click MANAGE ACCESS KEYS at the bottom of the navigation pane.
  4. In the pop-up dialog, you'll see the storage account name, primary access key and secondary access key. For access key, you can use either the primary one or the secondary one.
  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 = Azure::TableService.new
begin
    azure_table_service.create_table("testtable")
rescue
    puts $!
end

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 = Azure::TableService.new
batch = Azure::Storage::Table::Batch.new("testtable",
    "test-partition-key") do
    insert "2", { "content" => "new content 2" }
    insert "3", { "content" => "new content 3" }
end
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",
    "1")

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)
Note

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.

azure_table_service.delete_table("testtable")

Next steps

To learn about more complex storage tasks, follow these links: