Share via

TableClient class

Package:
@azure/data-tables

A TableClient represents a Client to the Azure Tables service allowing you to perform operations on a single table.

Constructors

TableClient(string, string, NamedKeyCredential, TableServiceClientOptions)

Creates a new instance of the TableClient class.
TableClient(string, string, SASCredential, TableServiceClientOptions)

Creates a new instance of the TableClient class.
TableClient(string, string, TableServiceClientOptions)

Creates an instance of TableClient.
TableClient(string, string, TokenCredential, TableServiceClientOptions)

Creates a new instance of the TableClient class.

Properties

pipeline

Represents a pipeline for making a HTTP request to a URL. Pipelines can have multiple policies to manage manipulating each request before and after it is made to the server.
tableName

Name of the table to perform operations on.
url

Table Account URL

Methods

createEntity<T>(TableEntity<T>, OperationOptions)

Insert entity in the table.
createTable(OperationOptions)

Creates a table with the tableName passed to the client constructor
deleteEntity(string, string, DeleteTableEntityOptions)

Deletes the specified entity in the table.
deleteTable(OperationOptions)

Permanently deletes the current table with all of its entities.
fromConnectionString(string, string, TableServiceClientOptions)

Creates an instance of TableClient from connection string.
getAccessPolicy(OperationOptions)

Retrieves details about any stored access policies specified on the table that may be used with Shared Access Signatures.
getEntity<T>(string, string, GetTableEntityOptions)

Returns a single entity in the table.
listEntities<T>(ListTableEntitiesOptions)

Queries entities in a table.
setAccessPolicy(SignedIdentifier[], OperationOptions)

Sets stored access policies for the table that may be used with Shared Access Signatures.
submitTransaction(TransactionAction[], OperationOptions)

Submits a Transaction which is composed of a set of actions. You can provide the actions as a list or you can use TableTransaction to help building the transaction.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient, TransactionAction } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

const actions: TransactionAction[] = [
  ["create", { partitionKey: "p1", rowKey: "1", data: "test1" }],
  ["delete", { partitionKey: "p1", rowKey: "2" }],
  ["update", { partitionKey: "p1", rowKey: "3", data: "newTest" }, "Merge"],
];
const result = await client.submitTransaction(actions);

Example usage with TableTransaction:

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient, TableTransaction } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

const transaction = new TableTransaction();

// Call the available action in the TableTransaction object
transaction.createEntity({ partitionKey: "p1", rowKey: "1", data: "test1" });
transaction.deleteEntity("p1", "2");
transaction.updateEntity({ partitionKey: "p1", rowKey: "3", data: "newTest" }, "Merge");

// submitTransaction with the actions list on the transaction.
const result = await client.submitTransaction(transaction.actions);
updateEntity<T>(TableEntity<T>, UpdateMode, UpdateTableEntityOptions)

Update an entity in the table.
upsertEntity<T>(TableEntity<T>, UpdateMode, OperationOptions)

Upsert an entity in the table.

Constructor Details

TableClient(string, string, NamedKeyCredential, TableServiceClientOptions)

Creates a new instance of the TableClient class.

new TableClient(url: string, tableName: string, credential: NamedKeyCredential, options?: TableServiceClientOptions)

Parameters

url

string

The URL of the service account that is the target of the desired operation, such as "https://myaccount.table.core.windows.net".

tableName

string

the name of the table

credential
NamedKeyCredential

NamedKeyCredential used to authenticate requests. Only Supported for Node

options
TableServiceClientOptions

Optional. Options to configure the HTTP pipeline.

Example using an account name/key:

import { AzureNamedKeyCredential, TableClient } from "@azure/data-tables";

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

// Use AzureNamedKeyCredential with storage account and account key
// AzureNamedKeyCredential is only available in Node.js runtime, not in browsers
const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

TableClient(string, string, SASCredential, TableServiceClientOptions)

Creates a new instance of the TableClient class.

new TableClient(url: string, tableName: string, credential: SASCredential, options?: TableServiceClientOptions)

Parameters

url

string

The URL of the service account that is the target of the desired operation, such as "https://myaccount.table.core.windows.net".

tableName

string

the name of the table

credential
SASCredential

SASCredential used to authenticate requests

options
TableServiceClientOptions

Optional. Options to configure the HTTP pipeline.

Example using a SAS Token:

import { TableClient, AzureSASCredential } from "@azure/data-tables";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const tableName = "<tableName>";

const clientWithSAS = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  new AzureSASCredential(sas),
);

TableClient(string, string, TableServiceClientOptions)

Creates an instance of TableClient.

new TableClient(url: string, tableName: string, options?: TableServiceClientOptions)

Parameters

url

string

A Client string pointing to Azure Storage table service, such as "https://myaccount.table.core.windows.net". You can append a SAS, such as "https://myaccount.table.core.windows.net?sasString".

tableName

string

the name of the table

options
TableServiceClientOptions

Options to configure the HTTP pipeline.

Example appending a SAS token:

import { TableClient } from "@azure/data-tables";

const account = "<account name>";
const sasToken = "<SAS token>";
const tableName = "<tableName>";

const clientWithSAS = new TableClient(
  `https://${account}.table.core.windows.net?${sasToken}`,
  tableName,
);

TableClient(string, string, TokenCredential, TableServiceClientOptions)

Creates a new instance of the TableClient class.

new TableClient(url: string, tableName: string, credential: TokenCredential, options?: TableServiceClientOptions)

Parameters

url

string

The URL of the service account that is the target of the desired operation, such as "https://myaccount.table.core.windows.net".

tableName

string

the name of the table

credential
TokenCredential

Azure Active Directory credential used to authenticate requests

options
TableServiceClientOptions

Optional. Options to configure the HTTP pipeline.

Example using an Azure Active Directory credential:

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient } from "@azure/data-tables";

const credential = new DefaultAzureCredential();
const account = "<account name>";
const tableName = "<tableName>";

const clientWithAAD = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  credential,
);

Property Details

pipeline

Represents a pipeline for making a HTTP request to a URL. Pipelines can have multiple policies to manage manipulating each request before and after it is made to the server.

pipeline: Pipeline

Property Value

Pipeline

tableName

Name of the table to perform operations on.

tableName: string

Property Value

string

url

Table Account URL

url: string

Property Value

string

Method Details

createEntity<T>(TableEntity<T>, OperationOptions)

Insert entity in the table.

function createEntity<T>(entity: TableEntity<T>, options?: OperationOptions): Promise<TableInsertEntityHeaders>

Parameters

entity

TableEntity<T>

The properties for the table entity.

options
OperationOptions

The options parameters.

Example creating an entity

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

const testEntity = {
  partitionKey: "P1",
  rowKey: "R1",
  foo: "foo",
  bar: 123,
};
await client.createEntity(testEntity);

Returns

Promise<TableInsertEntityHeaders>

createTable(OperationOptions)

Creates a table with the tableName passed to the client constructor

function createTable(options?: OperationOptions): Promise<void>

Parameters

options
OperationOptions

The options parameters.

Example creating a table

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

// If the table 'newTable' already exists, createTable doesn't throw
await client.createTable();

Returns

Promise<void>

deleteEntity(string, string, DeleteTableEntityOptions)

Deletes the specified entity in the table.

function deleteEntity(partitionKey: string, rowKey: string, options?: DeleteTableEntityOptions): Promise<TableDeleteEntityHeaders>

Parameters

partitionKey

string

The partition key of the entity.

rowKey

string

The row key of the entity.

options
DeleteTableEntityOptions

The options parameters.

Example deleting an entity

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

// deleteEntity deletes the entity that matches exactly the partitionKey and rowKey
await client.deleteEntity("<partitionKey>", "<rowKey>");

Returns

Promise<TableDeleteEntityHeaders>

deleteTable(OperationOptions)

Permanently deletes the current table with all of its entities.

function deleteTable(options?: OperationOptions): Promise<void>

Parameters

options
OperationOptions

The options parameters.

Example deleting a table

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

await client.deleteTable();

Returns

Promise<void>

fromConnectionString(string, string, TableServiceClientOptions)

Creates an instance of TableClient from connection string.

static function fromConnectionString(connectionString: string, tableName: string, options?: TableServiceClientOptions): TableClient

Parameters

connectionString

string

Account connection string or a SAS connection string of an Azure storage account. [ Note - Account connection string can only be used in NODE.JS runtime. ] Account connection string example - DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=accountKey;EndpointSuffix=core.windows.net SAS connection string example - BlobEndpoint=https://myaccount.table.core.windows.net/;QueueEndpoint=https://myaccount.queue.core.windows.net/;FileEndpoint=https://myaccount.file.core.windows.net/;TableEndpoint=https://myaccount.table.core.windows.net/;SharedAccessSignature=sasString

tableName

string

options
TableServiceClientOptions

Options to configure the HTTP pipeline.

Returns

TableClient

A new TableClient from the given connection string.

getAccessPolicy(OperationOptions)

Retrieves details about any stored access policies specified on the table that may be used with Shared Access Signatures.

function getAccessPolicy(options?: OperationOptions): Promise<GetAccessPolicyResponse>

Parameters

options
OperationOptions

The options parameters.

Returns

Promise<GetAccessPolicyResponse>

getEntity<T>(string, string, GetTableEntityOptions)

Returns a single entity in the table.

function getEntity<T>(partitionKey: string, rowKey: string, options?: GetTableEntityOptions): Promise<GetTableEntityResponse<TableEntityResult<T>>>

Parameters

partitionKey

string

The partition key of the entity.

rowKey

string

The row key of the entity.

options
GetTableEntityOptions

The options parameters.

Example getting an entity

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

const entity = await client.getEntity("<partitionKey>", "<rowKey>");
console.log(`Entity: PartitionKey: ${entity.partitionKey} RowKey: ${entity.rowKey}`);

Returns

Promise<GetTableEntityResponse<TableEntityResult<T>>>

listEntities<T>(ListTableEntitiesOptions)

Queries entities in a table.

function listEntities<T>(options?: ListTableEntitiesOptions): PagedAsyncIterableIterator<TableEntityResult<T>, TableEntityResultPage<T>, PageSettings>

Parameters

options
ListTableEntitiesOptions

The options parameters.

Example listing entities

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

let i = 0;
const entities = client.listEntities();
for await (const entity of entities) {
  console.log(`Entity${++i}: PartitionKey: ${entity.partitionKey} RowKey: ${entity.rowKey}`);
}

Returns

PagedAsyncIterableIterator<TableEntityResult<T>, TableEntityResultPage<T>, PageSettings>

setAccessPolicy(SignedIdentifier[], OperationOptions)

Sets stored access policies for the table that may be used with Shared Access Signatures.

function setAccessPolicy(tableAcl: SignedIdentifier[], options?: OperationOptions): Promise<TableSetAccessPolicyHeaders>

Parameters

tableAcl

SignedIdentifier[]

The Access Control List for the table.

options
OperationOptions

The options parameters.

Returns

Promise<TableSetAccessPolicyHeaders>

submitTransaction(TransactionAction[], OperationOptions)

Submits a Transaction which is composed of a set of actions. You can provide the actions as a list or you can use TableTransaction to help building the transaction.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient, TransactionAction } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

const actions: TransactionAction[] = [
  ["create", { partitionKey: "p1", rowKey: "1", data: "test1" }],
  ["delete", { partitionKey: "p1", rowKey: "2" }],
  ["update", { partitionKey: "p1", rowKey: "3", data: "newTest" }, "Merge"],
];
const result = await client.submitTransaction(actions);

Example usage with TableTransaction:

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient, TableTransaction } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

const transaction = new TableTransaction();

// Call the available action in the TableTransaction object
transaction.createEntity({ partitionKey: "p1", rowKey: "1", data: "test1" });
transaction.deleteEntity("p1", "2");
transaction.updateEntity({ partitionKey: "p1", rowKey: "3", data: "newTest" }, "Merge");

// submitTransaction with the actions list on the transaction.
const result = await client.submitTransaction(transaction.actions);

function submitTransaction(actions: TransactionAction[], options?: OperationOptions): Promise<TableTransactionResponse>

Parameters

actions

TransactionAction[]

tuple that contains the action to perform, and the entity to perform the action with

options
OperationOptions

Options for the request.

Returns

Promise<TableTransactionResponse>

updateEntity<T>(TableEntity<T>, UpdateMode, UpdateTableEntityOptions)

Update an entity in the table.

function updateEntity<T>(entity: TableEntity<T>, mode?: UpdateMode, options?: UpdateTableEntityOptions): Promise<TableUpdateEntityHeaders>

Parameters

entity

TableEntity<T>

The properties of the entity to be updated.

mode
UpdateMode

The different modes for updating the entity: - Merge: Updates an entity by updating the entity's properties without replacing the existing entity. - Replace: Updates an existing entity by replacing the entire entity.

options
UpdateTableEntityOptions

The options parameters.

Example updating an entity

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

const entity = { partitionKey: "p1", rowKey: "r1", bar: "updatedBar" };

// Update uses update mode "Merge" as default
// merge means that update will match a stored entity
// that has the same partitionKey and rowKey as the entity
// passed to the method and then will only update the properties present in it.
// Any other properties that are not defined in the entity passed to updateEntity
// will remain as they are in the service
await client.updateEntity(entity);

// We can also set the update mode to Replace, which will match the entity passed
// to updateEntity with one stored in the service and replace with the new one.
// If there are any missing properties in the entity passed to updateEntity, they
// will be removed from the entity stored in the service
await client.updateEntity(entity, "Replace");

Returns

Promise<TableUpdateEntityHeaders>

upsertEntity<T>(TableEntity<T>, UpdateMode, OperationOptions)

Upsert an entity in the table.

function upsertEntity<T>(entity: TableEntity<T>, mode?: UpdateMode, options?: OperationOptions): Promise<TableMergeEntityHeaders>

Parameters

entity

TableEntity<T>

The properties for the table entity.

mode
UpdateMode

The different modes for updating the entity: - Merge: Updates an entity by updating the entity's properties without replacing the existing entity. - Replace: Updates an existing entity by replacing the entire entity.

options
OperationOptions

The options parameters.

Example upserting an entity

import { DefaultAzureCredential } from "@azure/identity";
import { TableClient } from "@azure/data-tables";

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new DefaultAzureCredential();
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

const entity = { partitionKey: "p1", rowKey: "r1", bar: "updatedBar" };

// Upsert uses update mode "Merge" as default.
// This behaves similarly to update but creates the entity
// if it doesn't exist in the service
await client.upsertEntity(entity);

// We can also set the update mode to Replace.
// This behaves similarly to update but creates the entity
// if it doesn't exist in the service
await client.upsertEntity(entity, "Replace");

Returns

Promise<TableMergeEntityHeaders>