Frequently asked questions about Azure Cosmos DB for Table

APPLIES TO: Table

Comparing Azure Cosmos DB for Table and Azure Table Storage

Where is API for Table not identical with Azure Table storage behavior?

There are some behavior differences that users coming from Azure Table storage who want to create tables with the Azure Cosmos DB for Table should be aware of:

  • Azure Cosmos DB for Table uses a reserved capacity model in order to ensure guaranteed performance but this means that one pays for the capacity as soon as the table is created, even if the capacity isn't being used. With Azure Table storage one only pays for capacity that's used. This helps to explain why API for Table can offer a 10 ms read and 15 ms write SLA at the 99th percentile while Azure Table storage offers a 10-second SLA. But as a consequence, with API for Table tables, even empty tables without any requests, cost money in order to ensure the capacity is available to handle any requests to them at the SLA offered by Azure Cosmos DB.

  • Query results returned by the API for Table aren't sorted in partition key/row key order as they are in Azure Table storage.

  • Row keys can only be up to 255 bytes.

  • Batches can only have up to 2 MBs.

  • CORS isn't currently supported.

  • Table names in Azure Table storage aren't case-sensitive, but they are in Azure Cosmos DB for Table.

  • Some of Azure Cosmos DB's internal formats for encoding information, such as binary fields, are currently not as efficient as one might like. Therefore this can cause unexpected limitations on data size. For example, currently one couldn't use the full one Meg of a table entity to store binary data because the encoding increases the data's size.

  • Azure Cosmos DB reserves the entity property names ID, rid, etag, and ResourceId and they're currently not supported.

  • TableQuery TakeCount isn't limited to 1000.

  • In terms of the REST API, Azure Table storage (but not Azure Cosmos DB for Table) supports the following endpoints/query options:

    Rest Methods Rest Endpoint/Query Option Doc URLs Explanation Supported in Table Storage Supported in API for Table
    GET, PUT /?Restype=service@comp=properties Set Table Service Properties and Get Table Service Properties This endpoint is used to set CORS rules, storage analytics configuration, and logging settings. CORS is currently not supported and analytics and logging are handled differently in Azure Cosmos DB than Azure Storage Tables Yes No
    OPTIONS /<table-resource-name> Preflight CORS table request This is part of CORS which Azure Cosmos DB doesn't currently support. Yes No
    GET /?Restype=service@comp=stats Get Table Service Stats Provides information how quickly data is replicating between primary and secondaries. This isn't needed in Azure Cosmos DB as the replication is part of writes. Yes No
    GET, PUT /mytable?comp=acl Get Table ACL and Set Table ACL This gets and sets the stored access policies used to manage Shared Access Signatures (SAS). Yes No
  • Azure Cosmos DB for Table only supports the JSON format, not ATOM.

  • For the .NET SDK in particular, there are some classes and methods that Azure Cosmos DB doesn't currently support.

    • CloudTableClient class
      • \ServiceProperties
      • \ServiceStats
    • CloudTable class
      • SetPermissions
      • GetPermissions

Other frequently asked questions

Do I need a new SDK to use the API for Table?

No, existing storage SDKs should still work. However, it's recommended that one always gets the latest SDKs for the best support and in many cases superior performance. See the list of available languages in the Introduction to Azure Cosmos DB for Table.

What is the connection string that I need to use to connect to the API for Table?

The connection string is:

DefaultEndpointsProtocol=https;AccountName=<AccountNamefromCosmosDB;AccountKey=<FromKeysPaneofCosmosDB>;TableEndpoint=https://<AccountName>.table.cosmosdb.azure.com

You can get the connection string from the Connection String page in the Azure portal.

How do I override the config settings for the request options in the .NET SDK for the API for Table?

Some settings are handled on the CreateCloudTableClient method and other via the app.config in the appSettings section in the client application. For information about config settings, see Azure Cosmos DB capabilities.

Are there any changes for customers who are using the existing Azure Table storage SDKs?

None. There are no changes for existing or new customers who are using the existing Azure Table storage SDKs.

How do I view table data that's stored in Azure Cosmos DB for use with the API for Table?

You can use the Azure portal to browse the data. You can also use the API for Table code or the tools mentioned in the next answer.

Which tools work with the API for Table?

You can use the Azure Storage Explorer.

Tools with the flexibility to take a connection string in the format specified previously can support the new API for Table. A list of table tools is provided on the Azure Storage Client Tools page.

Is the concurrency on operations controlled?

Yes, optimistic concurrency is provided via the use of the ETag mechanism.

Is the OData query model supported for entities?

Yes, the API for Table supports OData query and LINQ query.

Can I connect to Azure Table Storage and Azure Cosmos DB for Table side by side in the same application?

Yes, you can connect by creating two separate instances of the CloudTableClient, each pointing to its own URI via the connection string.

How do I migrate an existing Azure Table storage application to this offering?

AzCopy is supported.

How is expansion of the storage size done for this service if, for example, I start with 'n' GB of data and my data will grow to 1 TB over time?

Azure Cosmos DB is designed to provide unlimited storage via the use of horizontal scaling. The service can monitor and effectively increase your storage.

How do I monitor the API for Table offering?

You can use the API for Table Metrics pane to monitor requests and storage usage.

How do I calculate the throughput I require?

You can use the capacity estimator to calculate the TableThroughput that's required for the operations. For more information, see Estimate Request Units and Data Storage. In general, you can show your entity as JSON and provide the numbers for your operations.

Can I use the API for Table SDK locally with the emulator?

Not at this time.

Can my existing application work with the API for Table?

Yes, the same API is supported.

Do I need to migrate my existing Azure Table storage applications to the SDK if I don't want to use the API for Table features?

No, you can create and use existing Azure Table storage assets without interruption of any kind. However, if you don't use the API for Table, you can't benefit from the automatic index, the extra consistency option, or global distribution.

How do I add replication of the data in the API for Table across more than one region of Azure?

You can use the Azure Cosmos DB portal's global replication settings to add regions that are suitable for your application. To develop a globally distributed application, you should also add your application with the PreferredLocation information set to the local region for providing low read latency.

How do I change the primary write region for the account in the API for Table?

You can use the Azure Cosmos DB global replication portal pane to add a region and then fail over to the required region. For instructions, see Developing with multi-region Azure Cosmos DB accounts.

How do I configure my preferred read regions for low latency when I distribute my data?

To help read from the local location, use the PreferredLocation key in the app.config file. For existing applications, the API for Table throws an error if LocationMode is set. Remove that code, because the API for Table picks up this information from the app.config file.

How should I think about consistency levels in the API for Table?

Azure Cosmos DB provides well-reasoned trade-offs between consistency, availability, and latency. Azure Cosmos DB offers five consistency levels to API for Table developers, so you can choose the right consistency model at the table level and make individual requests while querying the data. When a client connects, it can specify a consistency level. You can change the level via the consistencyLevel argument of CreateCloudTableClient.

The API for Table provides low-latency reads with "Read your own writes," with Bounded-staleness consistency as the default. For more information, see Consistency levels.

By default, Azure Table storage provides Strong consistency within a region and Eventual consistency in the secondary locations.

Does Azure Cosmos DB for Table offer more consistency levels than Azure Table storage?

Yes, for information about how to benefit from the distributed nature of Azure Cosmos DB, see Consistency levels. Because guarantees are provided for the consistency levels, you can use them with confidence.

When global distribution is enabled, how long does it take to replicate the data?

Azure Cosmos DB commits the data durably in the local region and pushes the data to other regions immediately in a matter of milliseconds. This replication is dependent only on the round-trip time (RTT) of the datacenter. To learn more about the global-distribution capability of Azure Cosmos DB, see Azure Cosmos DB: A globally distributed database service on Azure.

Can the read request consistency level be changed?

With Azure Cosmos DB, you can set the consistency level at the container level (on the table). By using the .NET SDK, you can change the level by providing the value for TableConsistencyLevel key in the app.config file. The possible values are: Strong, Bounded Staleness, Session, Consistent Prefix, and Eventual. For more information, see Tunable data consistency levels in Azure Cosmos DB. The key idea is that you can't set the request consistency level at more than the setting for the table. For example, you can't set the consistency level for the table at Eventual and the request consistency level at Strong.

How does the API for Table handle failover if a region goes down?

The API for Table uses the globally distributed platform of Azure Cosmos DB. To ensure that your application can tolerate datacenter downtime, enable at least one more region for the account in the Azure Cosmos DB portal Developing with multi-region Azure Cosmos DB accounts. You can set the priority of the region by using the portal Developing with multi-region Azure Cosmos DB accounts.

You can add as many regions as you want for the account and control where it can fail over to by providing a failover priority. To use the database, you need to provide an application there too. When you do so, your customers won't experience downtime. The latest .NET client SDK is auto homing but the other SDKs aren't. That is, it can detect the region that's down and automatically fail over to the new region.

Is the API for Table enabled for backups?

Yes, the API for Table uses the platform of Azure Cosmos DB for backups. Backups are made automatically. For more information, see Online backup and restore with Azure Cosmos DB.

Does the API for Table index all attributes of an entity by default?

Yes, all attributes of an entity are indexed by default. For more information, see Azure Cosmos DB: Indexing policies.

Does this mean I don't have to create more than one index to satisfy the queries?

Yes, Azure Cosmos DB for Table provides automatic indexing of all attributes without any schema definition. This automation frees developers to focus on the application rather than on index creation and management. For more information, see Azure Cosmos DB: Indexing policies.

Can I change the indexing policy?

Yes, you can change the indexing policy by providing the index definition. You need to properly encode and escape the settings.

The indexing policy can only be set in the portal at Data Explorer, navigate to the specific table you want to change and then go to the Scale & Settings->Indexing Policy, make the desired change and then Save.

Azure Cosmos DB as a platform seems to have lot of capabilities, such as sorting, aggregates, hierarchy, and other functionality. Will you be adding these capabilities to the API for Table?

The API for Table provides the same query functionality as Azure Table storage. Azure Cosmos DB also supports sorting, aggregates, geospatial query, hierarchy, and a wide range of built-in functions. For more information, see SQL queries.

When should I change TableThroughput for the API for Table?

You should change TableThroughput when either of the following conditions applies:

  • You're performing an extract, transform, and load (ETL) of data, or you want to upload numerous data in short amount of time.
  • You need more throughput from the container or from a set of containers at the back end. For example, you see that the used throughput is more than the provisioned throughput, and you're getting throttled. For more information, see Set throughput for Azure Cosmos DB containers.

Can I scale up or scale down the throughput of my API for Table table?

Yes, you can use the Azure Cosmos DB portal's scale pane to scale the throughput. For more information, see Set throughput.

Is a default TableThroughput set for newly provisioned tables?

Yes, if you don't override the TableThroughput via app.config and don't use a precreated container in Azure Cosmos DB, the service creates a table with throughput of 400.

Is there any change of pricing for existing customers of the Azure Table storage service?

None. There's no change in price for existing Azure Table storage customers.

How is the price calculated for the API for Table?

The price depends on the allocated TableThroughput.

How do I handle any rate limiting on the tables in API for Table offering?

If the request rate is more than the capacity of the provisioned throughput for the underlying container or a set of containers, you get an error, and the SDK retries the call by applying the retry policy.

Why do I need to choose a throughput apart from PartitionKey and RowKey to take advantage of the API for Table offering of Azure Cosmos DB?

Azure Cosmos DB sets a default throughput for your container if you don't provide one in the app.config file or via the portal.

Azure Cosmos DB provides guarantees for performance and latency, with upper bounds on operation. This guarantee is possible when the engine can enforce governance on the tenant's operations. Setting TableThroughput ensures that you get the guaranteed throughput and latency, because the platform reserves this capacity and guarantees operational success.

By using the throughput specification, you can elastically change it to benefit from the seasonality of your application, meet the throughput needs, and save costs.

Azure Table storage has been inexpensive for me, because I pay only to store the data, and I rarely query. The Azure Cosmos DB for Table offering seems to be charging me even though I haven't performed a single transaction or stored anything. Can you explain?

Azure Cosmos DB is designed to be a globally distributed, SLA-based system with guarantees for availability, latency, and throughput. When you reserve throughput in Azure Cosmos DB, it's guaranteed, unlike the throughput of other systems. Azure Cosmos DB provides more capabilities that customers have requested, such as secondary indexes and global distribution.

I never get a quota full" notification (indicating that a partition is full) when I ingest data into Azure Table storage. With the API for Table, I do get this message. Is this offering limiting me and forcing me to change my existing application?

Azure Cosmos DB is an SLA-based system that provides unlimited scale, with guarantees for latency, throughput, availability, and consistency. To ensure guaranteed premium performance, make sure that your data size and index are manageable and scalable. The 20-GB limit on the number of entities or items per partition key is to ensure that we provide great lookup and query performance. To ensure that your application scales well, even for Azure Storage, we recommend that you not create a hot partition by storing all information in one partition and querying it.

So PartitionKey and RowKey are still required with the API for Table?

Yes. Because the surface area of the API for Table is similar to that of the Azure Table storage SDK, the partition key provides an efficient way to distribute the data. The row key is unique within that partition. The row key needs to be present and can't be null as in the standard SDK. The length of RowKey is 255 bytes and the length of PartitionKey is 1 KB.

What are the error messages for the API for Table?

Azure Table storage and Azure Cosmos DB for Table use the same SDKs so most of the errors are the same.

Why do I get throttled when I try to create lot of tables one after another in the API for Table?

Azure Cosmos DB is an SLA-based system that provides latency, throughput, availability, and consistency guarantees. Because it's a provisioned system, it reserves resources to guarantee these requirements. The rapid rate of creation of tables is detected and throttled. We recommend that you look at the rate of creation of tables and lower it to less than 5 per minute. Remember that the API for Table is a provisioned system. The moment you provision it, you begin to pay for it.

How do I provide feedback about the SDK or bugs?

You can share your feedback in any of the following ways: