| title | description | ms.topic | ms.date | ms.devlang | ms.custom | zone_pivot_groups |
|---|---|---|---|---|---|---|
Azure Tables input bindings for Azure Functions | Understand how to use Azure Tables input bindings in Azure Functions. | reference | 11/11/2022 | csharp | devx-track-csharp, devx-track-python, devx-track-extended-java, devx-track-js, devx-track-ts | programming-languages-set-functions |
Use the Azure Tables input binding to read a table in Azure Cosmos DB for Table or Azure Table Storage.
For information on setup and configuration details, see the overview.
::: zone pivot="programming-language-javascript,programming-language-typescript" [!INCLUDE functions-nodejs-model-tabs-description] ::: zone-end
::: zone pivot="programming-language-csharp"
The usage of the binding depends on the extension package version and the C# modality used in your function app, which can be one of the following:
An isolated worker process class library compiled C# function runs in a process isolated from the runtime.
[!INCLUDE functions-in-process-model-retirement-note]
An in-process class library is a compiled C# function runs in the same process as the Functions runtime.
Choose a version to see examples for the mode and version.
The following example shows a C# function that reads a single table row. For every message sent to the queue, the function will be triggered.
The row key value {queueTrigger} binds the row key to the message metadata, which is the message string.
publicclassTableStorage{publicclassMyPoco:Azure.Data.Tables.ITableEntity{publicstringText{get;set;}publicstringPartitionKey{get;set;}publicstringRowKey{get;set;}publicDateTimeOffset?Timestamp{get;set;}publicETagETag{get;set;}}[FunctionName("TableInput")]publicstaticvoidTableInput([QueueTrigger("table-items")]stringinput,[Table("MyTable","MyPartition","{queueTrigger}")]MyPocopoco,ILoggerlog){log.LogInformation($"PK={poco.PartitionKey}, RK={poco.RowKey}, Text={poco.Text}");}}Use a TableClient method parameter to read the table by using the Azure SDK. Here's an example of a function that queries an Azure Functions log table:
usingMicrosoft.Azure.WebJobs;usingMicrosoft.Extensions.Logging;usingAzure.Data.Tables;usingSystem;usingSystem.Threading.Tasks;usingAzure;namespaceFunctionAppCloudTable2{publicclassLogEntity:ITableEntity{publicstringOriginalName{get;set;}publicstringPartitionKey{get;set;}publicstringRowKey{get;set;}publicDateTimeOffset?Timestamp{get;set;}publicETagETag{get;set;}}publicstaticclassCloudTableDemo{[FunctionName("CloudTableDemo")]publicstaticasyncTaskRun([TimerTrigger("0 */1 * * * *")]TimerInfomyTimer,[Table("AzureWebJobsHostLogscommon")]TableClienttableClient,ILoggerlog){log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");AsyncPageable<LogEntity>queryResults=tableClient.QueryAsync<LogEntity>(filter:$"PartitionKey eq 'FD2' and RowKey gt 't'");awaitforeach(LogEntityentityinqueryResults){log.LogInformation($"{entity.PartitionKey}\t{entity.RowKey}\t{entity.Timestamp}\t{entity.OriginalName}");}}}}For more information about how to use TableClient, see the Azure.Data.Tables API Reference.
The following example shows a C# function that reads a single table row. For every message sent to the queue, the function will be triggered.
The row key value {queueTrigger} binds the row key to the message metadata, which is the message string.
publicclassTableStorage{publicclassMyPoco{publicstringPartitionKey{get;set;}publicstringRowKey{get;set;}publicstringText{get;set;}}[FunctionName("TableInput")]publicstaticvoidTableInput([QueueTrigger("table-items")]stringinput,[Table("MyTable","MyPartition","{queueTrigger}")]MyPocopoco,ILoggerlog){log.LogInformation($"PK={poco.PartitionKey}, RK={poco.RowKey}, Text={poco.Text}");}}Use a CloudTable method parameter to read the table by using the Azure Storage SDK. Here's an example of a function that queries an Azure Functions log table:
usingMicrosoft.Azure.WebJobs;usingMicrosoft.Azure.WebJobs.Host;usingMicrosoft.Extensions.Logging;usingMicrosoft.Azure.Cosmos.Table;usingSystem;usingSystem.Threading.Tasks;namespaceFunctionAppCloudTable2{publicclassLogEntity:TableEntity{publicstringOriginalName{get;set;}}publicstaticclassCloudTableDemo{[FunctionName("CloudTableDemo")]publicstaticasyncTaskRun([TimerTrigger("0 */1 * * * *")]TimerInfomyTimer,[Table("AzureWebJobsHostLogscommon")]CloudTablecloudTable,ILoggerlog){log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");TableQuery<LogEntity>rangeQuery=newTableQuery<LogEntity>().Where(TableQuery.CombineFilters(TableQuery.GenerateFilterCondition("PartitionKey",QueryComparisons.Equal,"FD2"),TableOperators.And,TableQuery.GenerateFilterCondition("RowKey",QueryComparisons.GreaterThan,"t")));// Execute the query and loop through the resultsforeach(LogEntityentityinawaitcloudTable.ExecuteQuerySegmentedAsync(rangeQuery,null)){log.LogInformation($"{entity.PartitionKey}\t{entity.RowKey}\t{entity.Timestamp}\t{entity.OriginalName}");}}}}For more information about how to use CloudTable, see Get started with Azure Table storage.
If you try to bind to CloudTable and get an error message, make sure that you have a reference to the correct Storage SDK version.
The following example shows a C# function that reads a single table row. For every message sent to the queue, the function will be triggered.
The row key value {queueTrigger} binds the row key to the message metadata, which is the message string.
publicclassTableStorage{publicclassMyPoco{publicstringPartitionKey{get;set;}publicstringRowKey{get;set;}publicstringText{get;set;}}[FunctionName("TableInput")]publicstaticvoidTableInput([QueueTrigger("table-items")]stringinput,[Table("MyTable","MyPartition","{queueTrigger}")]MyPocopoco,ILoggerlog){log.LogInformation($"PK={poco.PartitionKey}, RK={poco.RowKey}, Text={poco.Text}");}}The following example shows a C# function that reads multiple table rows where the MyPoco class derives from TableEntity.
publicclassTableStorage{publicclassMyPoco:TableEntity{publicstringText{get;set;}}[FunctionName("TableInput")]publicstaticvoidTableInput([QueueTrigger("table-items")]stringinput,[Table("MyTable","MyPartition")]IQueryable<MyPoco>pocos,ILoggerlog){foreach(MyPocopocoinpocos){log.LogInformation($"PK={poco.PartitionKey}, RK={poco.RowKey}, Text={poco.Text}");}}}The following MyTableData class represents a row of data in the table:
publicclassMyTableData:Azure.Data.Tables.ITableEntity{publicstringText{get;set;}publicstringPartitionKey{get;set;}publicstringRowKey{get;set;}publicDateTimeOffset?Timestamp{get;set;}publicETagETag{get;set;}}The following function, which is started by a Queue Storage trigger, reads a row key from the queue, which is used to get the row from the input table. The expression {queueTrigger} binds the row key to the message metadata, which is the message string.
[Function("TableFunction")][TableOutput("OutputTable",Connection="AzureWebJobsStorage")]publicstaticMyTableDataRun([QueueTrigger("table-items")]stringinput,[TableInput("MyTable","<PartitionKey>","{queueTrigger}")]MyTableDatatableInput,FunctionContextcontext){varlogger=context.GetLogger("TableFunction");logger.LogInformation($"PK={tableInput.PartitionKey}, RK={tableInput.RowKey}, Text={tableInput.Text}");returnnewMyTableData(){PartitionKey="queue",RowKey=Guid.NewGuid().ToString(),Text=$"Output record with rowkey {input} created at {DateTime.Now}"};}The following Queue-triggered function returns the first 5 entities as an IEnumerable<T>, with the partition key value set as the queue message.
[Function("TestFunction")]publicstaticvoidRun([QueueTrigger("myqueue",Connection="AzureWebJobsStorage")]stringpartition,[TableInput("inTable","{queueTrigger}",Take=5,Filter="Text eq 'test'",Connection="AzureWebJobsStorage")]IEnumerable<MyTableData>tableInputs,FunctionContextcontext){varlogger=context.GetLogger("TestFunction");logger.LogInformation(partition);foreach(MyTableDatatableInputintableInputs){logger.LogInformation($"PK={tableInput.PartitionKey}, RK={tableInput.RowKey}, Text={tableInput.Text}");}}The Filter and Take properties are used to limit the number of entities returned.
The following MyTableData class represents a row of data in the table:
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/Table/TableFunction.cs" range="31-38" :::
The following function, which is started by a Queue Storage trigger, reads a row key from the queue, which is used to get the row from the input table. The expression {queueTrigger} binds the row key to the message metadata, which is the message string.
:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/Table/TableFunction.cs" range="12-29" :::
The following Queue-triggered function returns the first 5 entities as an IEnumerable<T>, with the partition key value set as the queue message.
[Function("TestFunction")]publicstaticvoidRun([QueueTrigger("myqueue",Connection="AzureWebJobsStorage")]stringpartition,[TableInput("inTable","{queueTrigger}",Take=5,Filter="Text eq 'test'",Connection="AzureWebJobsStorage")]IEnumerable<MyTableData>tableInputs,FunctionContextcontext){varlogger=context.GetLogger("TestFunction");logger.LogInformation(partition);foreach(MyTableDatatableInputintableInputs){logger.LogInformation($"PK={tableInput.PartitionKey}, RK={tableInput.RowKey}, Text={tableInput.Text}");}}The Filter and Take properties are used to limit the number of entities returned.
Functions version 1.x doesn't support isolated worker process.
::: zone-end ::: zone pivot="programming-language-java"
The following example shows an HTTP triggered function which returns a list of person objects who are in a specified partition in Table storage. In the example, the partition key is extracted from the http route, and the tableName and connection are from the function settings.
publicclassPerson { privateStringPartitionKey; privateStringRowKey; privateStringName; publicStringgetPartitionKey() { returnthis.PartitionKey; } publicvoidsetPartitionKey(Stringkey) { this.PartitionKey = key; } publicStringgetRowKey() { returnthis.RowKey; } publicvoidsetRowKey(Stringkey) { this.RowKey = key; } publicStringgetName() { returnthis.Name; } publicvoidsetName(Stringname) { this.Name = name; } } @FunctionName("getPersonsByPartitionKey") publicPerson[] get( @HttpTrigger(name = "getPersons", methods = {HttpMethod.GET}, authLevel = AuthorizationLevel.FUNCTION, route="persons/{partitionKey}") HttpRequestMessage<Optional<String>> request, @BindingName("partitionKey") StringpartitionKey, @TableInput(name="persons", partitionKey="{partitionKey}", tableName="%MyTableName%", connection="MyConnectionString") Person[] persons, finalExecutionContextcontext) { context.getLogger().info("Got query for person related to persons with partition key: " + partitionKey); returnpersons; }The TableInput annotation can also extract the bindings from the json body of the request, like the following example shows.
@FunctionName("GetPersonsByKeysFromRequest") publicHttpResponseMessageget( @HttpTrigger(name = "getPerson", methods = {HttpMethod.GET}, authLevel = AuthorizationLevel.FUNCTION, route="query") HttpRequestMessage<Optional<String>> request, @TableInput(name="persons", partitionKey="{partitionKey}", rowKey = "{rowKey}", tableName="%MyTableName%", connection="MyConnectionString") Personperson, finalExecutionContextcontext) { if (person == null) { returnrequest.createResponseBuilder(HttpStatus.NOT_FOUND) .body("Person not found.") .build(); } returnrequest.createResponseBuilder(HttpStatus.OK) .header("Content-Type", "application/json") .body(person) .build(); }The following example uses a filter to query for persons with a specific name in an Azure Table, and limits the number of possible matches to 10 results.
@FunctionName("getPersonsByName") publicPerson[] get( @HttpTrigger(name = "getPersons", methods = {HttpMethod.GET}, authLevel = AuthorizationLevel.FUNCTION, route="filter/{name}") HttpRequestMessage<Optional<String>> request, @BindingName("name") Stringname, @TableInput(name="persons", filter="Name eq '{name}'", take = "10", tableName="%MyTableName%", connection="MyConnectionString") Person[] persons, finalExecutionContextcontext) { context.getLogger().info("Got query for person related to persons with name: " + name); returnpersons; }::: zone-end
::: zone pivot="programming-language-javascript,programming-language-typescript"
The following example shows a table input binding that uses a queue trigger to read a single table row. The binding specifies a partitionKey and a rowKey. The rowKey value "{queueTrigger}" indicates that the row key comes from the queue message string.
::: zone-end ::: zone pivot="programming-language-typescript"
:::code language="typescript" source="~/azure-functions-nodejs-v4/ts/src/functions/tableInput1.ts" :::
TypeScript samples are not documented for model v3.
::: zone-end ::: zone pivot="programming-language-javascript"
:::code language="javascript" source="~/azure-functions-nodejs-v4/js/src/functions/tableInput1.js" :::
{ "bindings": [ { "queueName": "myqueue-items", "connection": "MyStorageConnectionAppSetting", "name": "myQueueItem", "type": "queueTrigger", "direction": "in" }, { "name": "personEntity", "type": "table", "tableName": "Person", "partitionKey": "Test", "rowKey": "{queueTrigger}", "connection": "MyStorageConnectionAppSetting", "direction": "in" } ], "disabled": false }The configuration section explains these properties.
Here's the JavaScript code:
module.exports=asyncfunction(context,myQueueItem){context.log('Node.js queue trigger function processed work item',myQueueItem);context.log('Person entity name: '+context.bindings.personEntity.Name);};::: zone-end
::: zone pivot="programming-language-powershell"
The following function uses a queue trigger to read a single table row as input to a function.
In this example, the binding configuration specifies an explicit value for the table's partitionKey and uses an expression to pass to the rowKey. The rowKey expression, {queueTrigger}, indicates that the row key comes from the queue message string.
Binding configuration in function.json:
{ "bindings": [ { "queueName": "myqueue-items", "connection": "MyStorageConnectionAppSetting", "name": "MyQueueItem", "type": "queueTrigger", "direction": "in" }, { "name": "PersonEntity", "type": "table", "tableName": "Person", "partitionKey": "Test", "rowKey": "{queueTrigger}", "connection": "MyStorageConnectionAppSetting", "direction": "in" } ], "disabled": false }PowerShell code in run.ps1:
param($MyQueueItem,$PersonEntity,$TriggerMetadata) Write-Host"PowerShell queue trigger function processed work item: $MyQueueItem"Write-Host"Person entity name: $($PersonEntity.Name)"::: zone-end
::: zone pivot="programming-language-python"
The following function uses an HTTP trigger to read a single table row as input to a function.
In this example, binding configuration specifies an explicit value for the table's partitionKey and uses an expression to pass to the rowKey. The rowKey expression, {id} indicates that the row key comes from the {id} part of the route in the request.
Binding configuration in the function.json file:
{ "scriptFile": "__init__.py", "bindings": [ { "name": "messageJSON", "type": "table", "tableName": "messages", "partitionKey": "message", "rowKey": "{id}", "connection": "AzureWebJobsStorage", "direction": "in" }, { "authLevel": "function", "type": "httpTrigger", "direction": "in", "name": "req", "methods": [ "get", "post" ], "route": "messages/{id}" }, { "type": "http", "direction": "out", "name": "$return" } ], "disabled": false }Python code in the __init__.py file:
importjsonimportazure.functionsasfuncdefmain(req: func.HttpRequest, messageJSON) ->func.HttpResponse: message=json.loads(messageJSON) returnfunc.HttpResponse(f"Table row: {messageJSON}")With this simple binding, you can't programmatically handle a case in which no row that has a row key ID is found. For more fine-grained data selection, use the storage SDK.
::: zone-end
::: zone pivot="programming-language-csharp"
Both in-process and isolated worker process C# libraries use attributes to define the function. C# script instead uses a function.json configuration file as described in the C# scripting guide.
In C# class libraries, the TableInputAttribute supports the following properties:
| Attribute property | Description |
|---|---|
| TableName | The name of the table. |
| PartitionKey | Optional. The partition key of the table entity to read. |
| RowKey | Optional. The row key of the table entity to read. |
| Take | Optional. The maximum number of entities to read into an IEnumerable<T>. Can't be used with RowKey. |
| Filter | Optional. An OData filter expression for entities to read into an IEnumerable<T>. Can't be used with RowKey. |
| Connection | The name of an app setting or setting collection that specifies how to connect to the table service. See Connections. |
In C# class libraries, the TableAttribute supports the following properties:
| Attribute property | Description |
|---|---|
| TableName | The name of the table. |
| PartitionKey | Optional. The partition key of the table entity to read. See the usage section for guidance on how to use this property. |
| RowKey | Optional. The row key of a single table entity to read. Can't be used with Take or Filter. |
| Take | Optional. The maximum number of entities to return. Can't be used with RowKey. |
| Filter | Optional. An OData filter expression for the entities to return from the table. Can't be used with RowKey. |
| Connection | The name of an app setting or setting collection that specifies how to connect to the table service. See Connections. |
The attribute's constructor takes the table name, partition key, and row key, as shown in the following example:
[FunctionName("TableInput")]publicstaticvoidRun([QueueTrigger("table-items")]stringinput,[Table("MyTable","Http","{queueTrigger}")]MyPocopoco,ILoggerlog){ ...}You can set the Connection property to specify the connection to the table service, as shown in the following example:
[FunctionName("TableInput")]publicstaticvoidRun([QueueTrigger("table-items")]stringinput,[Table("MyTable","Http","{queueTrigger}",Connection="StorageConnectionAppSetting")]MyPocopoco,ILoggerlog){ ...}[!INCLUDE functions-bindings-storage-attribute]
::: zone-end
::: zone pivot="programming-language-java"
In the Java functions runtime library, use the @TableInput annotation on parameters whose value would come from Table storage. This annotation can be used with native Java types, POJOs, or nullable values using Optional<T>. This annotation supports the following elements:
| Element | Description |
|---|---|
| name | The name of the variable that represents the table or entity in function code. |
| tableName | The name of the table. |
| partitionKey | Optional. The partition key of the table entity to read. |
| rowKey | Optional. The row key of the table entity to read. |
| take | Optional. The maximum number of entities to read. |
| filter | Optional. An OData filter expression for table input. |
| connection | The name of an app setting or setting collection that specifies how to connect to the table service. See Connections. |
::: zone-end
::: zone pivot="programming-language-javascript,programming-language-typescript"
The following table explains the properties that you can set on the options object passed to the input.table() method.
| Property | Description |
|---|---|
| tableName | The name of the table. |
| partitionKey | Optional. The partition key of the table entity to read. |
| rowKey | Optional. The row key of the table entity to read. Can't be used with take or filter. |
| take | Optional. The maximum number of entities to return. Can't be used with rowKey. |
| filter | Optional. An OData filter expression for the entities to return from the table. Can't be used with rowKey. |
| connection | The name of an app setting or setting collection that specifies how to connect to the table service. See Connections. |
The following table explains the binding configuration properties that you set in the function.json file.
| Property | Description |
|---|---|
| type | Must be set to table. This property is set automatically when you create the binding in the Azure portal. |
| direction | Must be set to in. This property is set automatically when you create the binding in the Azure portal. |
| name | The name of the variable that represents the table or entity in function code. |
| tableName | The name of the table. |
| partitionKey | Optional. The partition key of the table entity to read. |
| rowKey | Optional. The row key of the table entity to read. Can't be used with take or filter. |
| take | Optional. The maximum number of entities to return. Can't be used with rowKey. |
| filter | Optional. An OData filter expression for the entities to return from the table. Can't be used with rowKey. |
| connection | The name of an app setting or setting collection that specifies how to connect to the table service. See Connections. |
::: zone-end ::: zone pivot="programming-language-powershell,programming-language-python"
The following table explains the binding configuration properties that you set in the function.json file.
| function.json property | Description |
|---|---|
| type | Must be set to table. This property is set automatically when you create the binding in the Azure portal. |
| direction | Must be set to in. This property is set automatically when you create the binding in the Azure portal. |
| name | The name of the variable that represents the table or entity in function code. |
| tableName | The name of the table. |
| partitionKey | Optional. The partition key of the table entity to read. |
| rowKey | Optional. The row key of the table entity to read. Can't be used with take or filter. |
| take | Optional. The maximum number of entities to return. Can't be used with rowKey. |
| filter | Optional. An OData filter expression for the entities to return from the table. Can't be used with rowKey. |
| connection | The name of an app setting or setting collection that specifies how to connect to the table service. See Connections. |
::: zone-end
[!INCLUDE app settings to local.settings.json]
[!INCLUDE functions-table-connections]
::: zone pivot="programming-language-csharp"
The usage of the binding depends on the extension package version, and the C# modality used in your function app, which can be one of the following:
An isolated worker process class library compiled C# function runs in a process isolated from the runtime.
An in-process class library is a compiled C# function that runs in the same process as the Functions runtime.
Choose a version to see usage details for the mode and version.
To return a specific entity by key, use a binding parameter that derives from TableEntity.
To execute queries that return multiple entities, bind to a [TableClient] object. You can then use this object to create and execute queries against the bound table. Note that [TableClient] and related APIs belong to the Azure.Data.Tables namespace.
To return a specific entity by key, use a binding parameter that derives from TableEntity.
To execute queries that return multiple entities, bind to a CloudTable object. You can then use this object to create and execute queries against the bound table. Note that CloudTable and related APIs belong to the Microsoft.Azure.Cosmos.Table namespace.
To return a specific entity by key, use a binding parameter that derives from TableEntity. The specific TableName, PartitionKey, and RowKey are used to try and get a specific entity from the table.
To execute queries that return multiple entities, bind to an IQueryable<T> of a type that inherits from TableEntity.
[!INCLUDE functions-bindings-table-input-dotnet-isolated-types]
To return a specific entity by key, use a plain-old CLR object (POCO). The specific TableName, PartitionKey, and RowKey are used to try and get a specific entity from the table.
When returning multiple entities as an IEnumerable<T>, you can instead use Take and Filter properties to restrict the result set.
Functions version 1.x doesn't support isolated worker process.
::: zone-end
::: zone pivot="programming-language-java" The TableInput attribute gives you access to the table row that triggered the function. ::: zone-end
::: zone pivot="programming-language-javascript,programming-language-typescript"
Get the input row data by using context.extraInputs.get().
Get the input row data by using context.bindings.<name> where <name> is the value specified in the name property of function.json.
::: zone-end ::: zone pivot="programming-language-powershell"
Data is passed to the input parameter as specified by the name key in the function.json file. Specifying The partitionKey and rowKey allows you to filter to specific records. ::: zone-end
::: zone pivot="programming-language-python"
Table data is passed to the function as a JSON string. De-serialize the message by calling json.loads as shown in the input example. ::: zone-end
For specific usage details, see Example.
