How to use Azure Table Storage and the Azure Cosmos DB for Table with Ruby

APPLIES TO: Table

This article shows you how to create tables, store your data, and perform CRUD operations on the data. Choose either the Azure Table service or the Azure Cosmos DB for Table. The samples described in this article are written in Ruby and uses the Azure Storage Table Client Library for Ruby. The scenarios covered include create a table, delete a table, insert entities, and query entities from the table.

Create an Azure service account

You can work with tables using the Azure Table storage or the Azure Cosmos DB. To learn more about the differences between table offerings in these two services, see the API for Table overview. You'll need to create an account for the service you're going to use. The following sections show how to create both Azure Table storage and the Azure Cosmos DB account, however you can just use one of them.

Create an Azure storage account

The easiest way to create an 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 or Azure CLI.

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 an Azure Cosmos DB account

For instructions on creating an Azure Cosmos DB for Table account, see Create a database account.

Add access to Azure storage or Azure Cosmos DB

To use Azure Storage or Azure Cosmos DB, you must download and use the Ruby Azure package that includes a set of convenience libraries that communicate with the Table 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-storage-table 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/storage/table"

Add your connection string

You can either connect to the Azure storage account or the Azure Cosmos DB for Table account. Get the connection string based on the type of account you are using.

Add an Azure Storage connection

The Azure Storage module reads 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::Storage::Table::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.

Add an Azure Cosmos DB connection

To connect to Azure Cosmos DB, copy your primary connection string from the Azure portal, and create a Client object using your copied connection string. You can pass the Client object when you create a TableService object:

common_client = Azure::Storage::Common::Client.create(storage_account_name:'myaccount', storage_access_key:'mykey', storage_table_host:'mycosmosdb_endpoint')
table_client = Azure::Storage::Table::TableService.new(client: common_client)

Create a table

The Azure::Storage::Table::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::Storage::Table::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 want 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)

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. Pass in the name of the table that contains the entity, the PartitionKey, and the 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

• Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, macOS, and Linux.
• Ruby Developer Center
• Azure Storage Table Client Library for Ruby