From d2186881cac8336d8ec4d24dfc91fb0fafed09c2 Mon Sep 17 00:00:00 2001 From: Charles Gagnon Date: Wed, 16 Aug 2023 16:10:34 -0700 Subject: [PATCH 1/2] Add Output binding column requirements to known issues --- README.md | 2 ++ docs/BindingsOverview.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/README.md b/README.md index e019f9928..0f5d8f986 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ - [Known Issues](#known-issues) - [Output Bindings](#output-bindings) - [Telemetry](#telemetry) + - [Privacy Statement](#privacy-statement) - [Trademarks](#trademarks) ## Introduction @@ -57,6 +58,7 @@ Databases on SQL Server, Azure SQL Database, or Azure SQL Managed Instance which - Have multiple functions, with dependent functions being triggered by the initial functions (through a trigger binding or other such method) - Use [dynamic (imperative)](https://learn.microsoft.com/azure/azure-functions/functions-bindings-expressions-patterns#binding-at-runtime) bindings (.NET only) - Use [IAsyncCollector](https://learn.microsoft.com/azure/azure-functions/functions-dotnet-class-library?tabs=v2%2Ccmd#writing-multiple-output-values) and call `FlushAsync` in the order desired (.NET only) +- **By Design:** Output bindings require that their payloads contain ALL columns defined in every execution, even optional ones. See [BindingsOverview.md#output-binding-columns](https://github.com/Azure/azure-functions-sql-extension/blob/main/docs/BindingsOverview.md#output-binding-columns) for more details - **Planned for Future Support:** For PowerShell Functions that use hashtables must use the `[ordered]@` for the request query or request body assertion in order to upsert the data to the SQL table properly. An example can be found [here](https://github.com/Azure/azure-functions-sql-extension/blob/main/samples/samples-powershell/AddProductsWithIdentityColumnArray/run.ps1). - **Planned for Future Support:** Java, PowerShell, and Python Functions using Output bindings cannot pass in null or empty values via the query string. - Java: Issue is tracked [here](https://github.com/Azure/azure-functions-java-worker/issues/683). diff --git a/docs/BindingsOverview.md b/docs/BindingsOverview.md index 9f2374553..95be40b49 100644 --- a/docs/BindingsOverview.md +++ b/docs/BindingsOverview.md @@ -33,6 +33,8 @@ When generating the queries used to upsert values into the database, the binding The result is that the binding expects all objects to have every column defined - even optional columns. If this is not the case then it will likely result in some column values being ignored if they aren't included in the first item in the row. Optional columns should pass a null value (or the language equivalent) in rows that don't have a value for that column. +Failure to do this may result in unexpected behavior, such as columns in requests being ignored or Exceptions being thrown. + ### Primary Key Special Cases Typically Output Bindings require two things : From 7f6984170488b8be9c95cf64feac6dec4925f8c1 Mon Sep 17 00:00:00 2001 From: Charles Gagnon Date: Wed, 16 Aug 2023 16:13:35 -0700 Subject: [PATCH 2/2] Update section title --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0f5d8f986..4937fcd57 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ - [Table of Contents](#table-of-contents) - [Introduction](#introduction) - [Supported SQL Server Versions](#supported-sql-server-versions) - - [Known Issues](#known-issues) + - [Known/By Design Issues](#knownby-design-issues) - [Output Bindings](#output-bindings) - [Telemetry](#telemetry) - [Privacy Statement](#privacy-statement) @@ -39,9 +39,11 @@ This extension uses the [OPENJSON](https://learn.microsoft.com/sql/t-sql/functio Databases on SQL Server, Azure SQL Database, or Azure SQL Managed Instance which meet the compatibility level requirement above are supported. -## Known Issues +## Known/By Design Issues -> **Note:** While we are actively working on resolving these issues, some may not be supported at this time. We appreciate your patience as we work to improve the Azure Functions SQL Extension. +Below is a list of common issues that users may run into when using the SQL Bindings extension. + +> **Note:** While we are actively working on resolving the known issues, some may not be supported at this time. We appreciate your patience as we work to improve the Azure Functions SQL Extension. - **By Design:** The table used by a SQL binding cannot contain two columns that only differ by casing (Ex. 'Name' and 'name'). - **By Design:** Non-CSharp functions using SQL bindings against tables with columns of data types `BINARY` or `VARBINARY` need to map those columns to a string type. Input bindings will return the binary value as a base64 encoded string. Output bindings require the value upserted to binary columns to be a base64 encoded string.