Table storage

Azure Table storage is the key-value table service inside a storage account (https://<acct>.table.core.windows.net). Cosmos DB for Table speaks the same API with other limits; this page covers Table storage.

Limits of the data model (fixed, documented)

Timestamp is set by the server and ignored on writes. Queries are fast only on PartitionKey (and RowKey within it); any other filter scans.

Access from TypeScript with Entra ID

Grant Storage Table Data Contributor (or Reader) on the account or the table; Owner and Contributor don't read data (reference/storage/access-models.md). Then:

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient, odata, type TransactionAction } from "@azure/data-tables";
import { RestError } from "@azure/core-rest-pipeline";

// Needs Storage Table Data Contributor on the account or table.
const client = new TableClient(
  `https://${process.env.STORAGE_ACCOUNT}.table.core.windows.net`,
  "orders",
  new DefaultAzureCredential(),
);

// The service code is in details.errorCode (single operations) or e.code (transactions).
export function tableErrorCode(e: unknown): string | undefined {
  if (!(e instanceof RestError)) return undefined;
  const d = e.details as { errorCode?: string } | undefined;
  return d?.errorCode ?? e.code;
}

export async function main(): Promise<void> {
  await client.createTable(); // no error if it already exists

  await client.upsertEntity({ partitionKey: "cust-42", rowKey: "order-1001", total: 12.5 }, "Merge");

  // Build filters with odata`` so values are quoted and escaped.
  const customer = "cust-42";
  for await (const e of client.listEntities<{ total: number }>({
    queryOptions: { filter: odata`PartitionKey eq ${customer} and total gt ${10}` },
  })) {
    console.log(e.rowKey, e.total);
  }

  // A transaction: one partition, at most 100 actions, at most 4 MiB, each entity once.
  const actions: TransactionAction[] = [];
  for (let i = 0; i < 250; i++) {
    actions.push(["upsert", { partitionKey: customer, rowKey: `line-${i}`, qty: i }]);
  }
  for (let i = 0; i < actions.length; i += 100) {
    try {
      await client.submitTransaction(actions.slice(i, i + 100));
    } catch (e) {
      // The message starts with the zero-based index of the failed action, e.g. "3:…"; the whole batch rolled back.
      console.error(tableErrorCode(e), (e as Error).message);
      throw e;
    }
  }

  try {
    await client.createEntity({ partitionKey: customer, rowKey: "order-1001" });
  } catch (e) {
    if (tableErrorCode(e) !== "EntityAlreadyExists") throw e;
  }
}

Where the code is: for a single operation, @azure/data-tables 13.3.2 leaves RestError.code undefined and puts the service code in e.details.errorCode (and e.details.odataError.code); for a failed transaction it sets e.code. Match on both, as above.

Transactions: all actions share one PartitionKey; at most 100 actions and 4 MiB; an entity appears once; actions are create, update, upsert or delete, not queries. They're atomic: one failure rolls back the rest, and its message starts with the failed action's zero-based index.

Error codes

Messages are the REST table's wording; the service appends RequestId: and Time: lines.