How to Use the Table Service from Node.js

This guide shows you how to perform common scenarios using the Windows Azure Table service. The samples are written written using the Node.js API. The scenarios covered include creating and deleting a table, inserting and querying entities in a table. For more information on tables, see the Next Steps section.

Table of Contents

• What is the Table Service?
• Concepts
• Create a Windows Azure Storage Account
• Create a Node.js Application
• Configure your Application to Access Storage
• Setup a Windows Azure Storage Connection
• How To: Create a Table
• How To: Add an Entity to a Table
• How To: Update an Entity
• How to: Work with Groups of Entities
• How to: Query for an Entity
• How to: Query a Set of Entities
• How To: Query a Subset of Entity Properties
• How To: Delete an Entity
• How To: Delete a Table
• Next Steps

What is the Table Service?

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

• Storing a huge amount of structured data (many TB) that is automatically scaled to meet throughput demands
• Storing datasets that don’t require complex joins, foreign keys, or stored procedures and can be denormalized for fast access
• Quickly querying data such as user profiles using a clustered index

You can use the Table service to store and query huge sets of structured, non-relational data, and your tables scale when volume increases.

Concepts

The Table service contains the following components:

• URL format: Code addresses tables in an account using this address format:
  http://storageaccount.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 Windows Azure Storage is done through a storage account. The total size of blob, table, and queue contents in a storage account cannot exceed 100TB.

• Table: A table is an unlimited 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. An account can contain many tables.

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

Create a Windows Azure Storage Account

To use storage operations, you need a Windows Azure storage account. You can create a storage account by following these steps. (You can also create a storage account using the REST API.)

1. Log into the Windows Azure Management Portal.

2. At the bottom of the navigation pane, click +NEW.

   

3. Click Storage Account, and then click Quick Create.

   

4. In URL, type a subdomain name to use in the URI for the storage account. The entry can contain from 3-24 lowercase letters and numbers. This value becomes the host name within the URI that is used to address Blob, Queue, or Table resources for the subscription.

5. Choose a Region/Affinity Group in which to locate the storage. If you will be using storage from your Windows Azure application, select the same region where you will deploy your application.

6. Click Create Storage Account.

Create a Node.js Application

Create a blank Node.js application. For instructions creating a Node.js application, see Create and deploy a Node.js application to a Windows Azure Web Site, Node.js Cloud Service (using Windows PowerShell), or Web Site with WebMatrix.

Configure Your Application to Access Storage

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

Use Node Package Manager (NPM) to obtain the package

1. Use a command-line interface such as PowerShell (Windows,) Terminal (Mac,) or Bash (Unix), navigate to the folder where you created your sample application.

2. Type npm install azure in the command window, which should result in the following output:

   azure@0.6.0 ./node_modules/azure
   ├── easy-table@0.0.1
   ├── dateformat@1.0.2-1.2.3
   ├── xmlbuilder@0.3.1
   ├── eyes@0.1.7
   ├── colors@0.6.0-1
   ├── mime@1.2.5
   ├── log@1.3.0
   ├── commander@0.6.1
   ├── node-uuid@1.2.0
   ├── xml2js@0.1.14
   ├── async@0.1.22
   ├── tunnel@0.0.1
   ├── underscore@1.3.3
   ├── qs@0.5.0
   ├── underscore.string@2.2.0rc
   ├── sax@0.4.0
   ├── streamline@0.2.4
   └── winston@0.6.1 (cycle@1.0.0, stack-trace@0.0.6, pkginfo@0.2.3, request@2.9.202)

3. You can manually run the ls command to verify that a node_modules folder was created. Inside that folder you will find the azure package, which contains the libraries you need to access storage.

Import the package

Using Notepad or another text editor, add the following to the top the server.js file of the application where you intend to use storage:

var azure = require('azure');

Setup a Windows 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 Windows Azure storage account. If these environment variables are not set, you must specify the account information when calling TableService.

For an example of setting the environment variables in a configuration file for a Windows Azure Cloud Service, see Node.js Cloud Service with Storage.

For an example of setting the environment variables in the management portal for a Windows Azure Web Site, see Node.js Web Application with Storage

How to Create a Table

The following code creates a TableService object and uses it to create a new table. Add the following near the top of server.js.

var tableService = azure.createTableService();

The call to createTableIfNotExists will return the specified table if it exists or create a new table with the specified name if it does not already exist. The following example creates a new table named 'mytable' if it does not already exist:

tableService.createTableIfNotExists('mytable', function(error){
    if(!error){
        // Table exists or created
    }
});

How to Add an Entity to a Table

To add an entity, first create an object that defines your entity properties and their data types. 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. The system 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. To add an entity to your table, pass the entity object to the insertEntity method.

var task = {
    PartitionKey : 'hometasks'
    , RowKey : '1'
    , Description : 'Take out the trash'
    , DueDate: new Date(2012, 6, 20)
};
tableService.insertEntity('mytable', task, function(error){
    if(!error){
        // Entity inserted
    }
});

How to Update an Entity

There are multiple methods available to update an existing entity:

• updateEntity - Updates an existing entity by replacing it.

• mergeEntity - Updates an existing entity by merging new property values into the existing entity.

• insertOrReplaceEntity - Updates an existing entity by replacing it. If no entity exists, a new one will be inserted.

• insertOrMergeEntity - Updates an existing entity by merging new property values into the existing. If no entity exists, a new one will be inserted.

The following example demonstrates updating an entity using updateEntity:

var task = {
    PartitionKey : 'hometasks'
    , RowKey : '1'
    , Description : 'Wash Dishes'
}
tableService.updateEntity('mytable', task, function(error){
    if(!error){
        // Entity has been updated
    }
});

With updateEntity and mergeEntity, if the entity that is being updated 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 insertOrReplaceEntity or insertOrMergeEntity.

How to 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 use the beginBatch method on TableService and then call the series of operations as usual. The difference is that the callback functions of these operators will indicate that the operation was batched, not submitted to the server. When you do want to submit the batch, you call commitBatch. The callback supplied to that method will indicate if the entire batch was submitted successfully. The following example demonstrates submitting two entities in a batch:

var tasks=[
    {
        PartitionKey : 'hometasks'
        , RowKey : '1'
        , Description : 'Take out the trash.'
        , DueDate : new Date(2012, 6, 20)
    }
    , {
        PartitionKey : 'hometasks'
        , RowKey : '2'
        , Description : 'Wash the dishes.'
        , DueDate : new Date(2012, 6, 20)
    }
]
tableService.beginBatch();
var async=require('async');

async.forEach(tasks
    , function taskIterator(task, callback){
        tableService.insertEntity('mytable', task, function(error){
            if(!error){
                // Entity inserted
                callback(null);
            } else {
                callback(error);
            }
        });
    }
    , function(error){
        if(!error){
            // All inserts completed
            tableService.commitBatch(function(error){
                if(!error){
                    // Batch successfully commited
                }
            });
        }
    });

How to Query for an Entity

To query an entity in a table, use the queryEntity method, by passing the PartitionKey and RowKey.

tableService.queryEntity('mytable'
    , 'hometasks'
    , '1'
    , function(error, entity){
        if(!error){
            // entity contains the returned entity
        }
    });

How to Query a Set of Entities

To query a table, use the TableQuery object to build up a query expression using clauses such as select, from, where (including convenience clauses such as wherePartitionKey, whereRowKey, whereNextPartitionKey, and whereNextRowKey), and, or, orderBy, and top. Then pass the query expression to the queryEntities method. You can use the results in a for loop inside the callback.

This example finds all tasks in Seattle based on the PartitionKey.

var query = azure.TableQuery
    .select()
    .from('mytable')
    .where('PartitionKey eq ?', 'hometasks');
tableService.queryEntities(query, function(error, entities){
    if(!error){
        //entities contains an array of entities
    }
});

How to 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.

The query in the following code only returns the Descriptions of entities in the table, note that in the program output, the DueDate will show as undefined because it was not sent by the server.

var query = azure.TableQuery
    .select('Description')
    .from('mytable')
    .where('PartitionKey eq ?', 'hometasks');
tableService.queryEntities(query, function(error, entities){
    if(!error){
        //entities contains an array of entities
    }
});

How to Delete an Entity

You can delete an entity using its partition and row keys. In this example, the task1 object contains the RowKey and PartitionKey values of the entity to be deleted. Then the object is passed to the deleteEntity method.

tableService.deleteEntity('mytable'
    , {
        PartitionKey : 'hometasks'
        , RowKey : '1'
    }
    , function(error){
        if(!error){
            // Entity deleted
        }
    });

How to Delete a Table

The following code deletes a table from a storage account.

tableService.deleteTable('mytable', function(error){
    if(!error){
        // Table deleted
    }
});

Next Steps

Now that you’ve learned the basics of table storage, follow these links to learn how to do more complex storage tasks.

• See the MSDN Reference: Storing and Accessing Data in Windows Azure.
• Visit the Windows Azure Storage Team Blog.
• Visit the Azure SDK for Node repository on GitHub.