explain how to use the option "from" in SQL to bind an unknown number of parameters (#46)

Co-authored-by: Grégory PLANCHAT <gplanchat@users.noreply.github.com>

Author: clemzarch

content/connectivity/sql/_index.en.md

@@ -19,6 +19,7 @@ weight: 9
     - [Building a ConditionalLoader](#building-a-conditionalloader)
 - [Advanced usage](#advanced-usage)
     - [Using params in your queries](#using-params-in-your-queries)
+    - [Using an unknown number of parameters](#using-an-unknown-number-of-parameters)
     - [Creating before and after queries](#creating-before-and-after-queries)
 
 ---
@@ -237,6 +238,43 @@ sql:
   # ... 
 ```
 
+### Using an unknown number of parameters
+
+In some cases, you may not know in advance how many parameters you will need to enter,
+for example if you are searching using an `IN` with many values.
+
+Using `from` instead of `value` will bind as many parameters as there are values in the path.
+
+And use [the expression `inSql(path, parameter_name)`](../../feature/expression-language/satellite-expression-functions/#list-of-available-functions) to prepare the values in the query.
+
+```yaml
+sql:
+  loader: 
+    query: '@="SELECT * FROM category WHERE id " ~ inSql(input["codes_list"], "identifier") ~ "'
+    parameters:
+      identifier:
+        from: '@=input["codes_list"]'
+  # ...
+```
+
+If at runtime there are 4 values under `[codes_list]`, this would be equivalent to writing:
+
+```yaml
+sql:
+  loader: 
+    query: 'SELECT * FROM category WHERE id IN (:identifier_0, :identifier_1, :identifier_2, :identifier_3)'
+    parameters:
+      identifier_0:
+        value: '@=input["codes_list"][0]'
+      identifier_1:
+        value: '@=input["codes_list"][1]'
+      identifier_2:
+        value: '@=input["codes_list"][2]'
+      identifier_3:
+        value: '@=input["codes_list"][3]'
+  # ...
+```
+
 ### Creating before and after queries
 
 In some cases, you may need to run queries in order to best prepare for the execution of your pipeline.

content/feature/expression-language/satellite-expression-functions/_index.en.md

@@ -38,10 +38,11 @@ foo: '@=env("MY_ENVIRONMENT_VARIABLE")'
 
 ## List of available functions
 
-| Name                                               | Description                                         |
-|----------------------------------------------------|-----------------------------------------------------|
-| env(`string` name): `string`|`false`          | Gets the value of an environment variable           |
-| envAsFile(`string` name): `string`                 | Create a file whose name is an environment variable |
-| file(`string` name): `string`                      | Create a file                                       |
-| base64Decode(`string` name): `string`|`false` | Decodes data encoded with Base64                    |
-| temporaryFile(`string` name): `resource`           | Create a temporary file                             |
+| Name                                                  | Description                                                                                                                                                                                                                                                                          |
+|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| env(`string` name): `string|false`                    | Gets the value of an environment variable                                                                                                                                                                                                                                            |
+| envAsFile(`string` name): `string`                    | Create a file whose name is an environment variable                                                                                                                                                                                                                                  |
+| file(`string` name): `string`                         | Create a file                                                                                                                                                                                                                                                                        |
+| base64Decode(`string` name): `string|false`           | Decodes data encoded with Base64                                                                                                                                                                                                                                                     |
+| temporaryFile(`string` name): `resource`              | Create a temporary file                                                                                                                                                                                                                                                              |
+| inSql(`array` path, `string` parameterName): `string` | Writes "IN (...)" with as many parameters as there are values under `path`, in the format: `:parameterName_0`, `:parameterName_1`... To be used in a SQL query [when searching among an unknown number of values](../../../connectivity/sql/#using-an-unknown-number-of-parameters). |