SQL: Add ODBC proxy support documentation (#73263)

This documents how to configure the proxy support for ODBC.
It also removes the documentation of the connection string values, these
are now all covered by the GUI settings.

Co-authored-by: Andrei Stefan <astefan@users.noreply.github.com>

docs/reference/sql/endpoints/odbc/configuration.asciidoc

@@ -83,6 +83,7 @@ image:images/sql/odbc/dsn_editor_basic.png[]
 This new window has three tabs, each responsible for a set of configuration parameters, as follows.
 
 [discrete]
+[[connection_parameters]]
 ===== 2.2 Connection parameters
 This tab allows configuration for the following items:
 
@@ -181,74 +182,155 @@ will be considered by default. Choose _All Files (\*.*)_ from the drop down, if
 image:images/sql/odbc/dsn_editor_security_cert.png[]
 
 [discrete]
-===== 2.4 Connection parameters
+===== 2.4 Proxy parameters
+If connecting to the {es} node needs to go through a proxy, the following parameters need to be configured:
+
+* Type
++
+What kind of protocol to use when connecting to the proxy host. This also mandates how the {es} node you want to connect to over the proxy needs to be specified under <<connection_parameters>>:
++
+** HTTP, SOCKS4A, SOCKS5H: either IP address or host name is accepted; the proxy will resolve the DNS name;
+** SOCKS4, SOCKS5: {es} node location needs to be provided as an IP address;
++
+* Port
++
+The TCP port the proxy is listening for connections on.
+* Username
++
+The user part of the credentials used to authenticate to the proxy.
+* Password
++
+The password part of the credentials for the proxy.
+
+
+[[dsn_editor_proxy]]
+.Proxy parameters
+image:images/sql/odbc/dsn_editor_proxy.png[]
+
+[discrete]
+===== 2.5 Connection parameters
 The connection configuration can further be tweaked by the following parameters.
 
 * Request timeout (s)
 +
-The maximum number of seconds for a request to the server. The value 0 disables the timeout.
-This corresponds to the `Timeout` setting in <<odbc-cfg-dsnparams>>.
+The maximum time (in seconds) a request to the server can take. This can be
+overridden by a larger statement-level timeout setting. The value 0 means no
+timeout.
 +
 * Max page size (rows)
 +
-The maximum number of rows that Elasticsearch SQL server should send the driver for one page.
-This corresponds to the `MaxFetchSize` setting in <<odbc-cfg-dsnparams>>.
+The maximum number of rows that {es-sql} server should send the driver for one
+page. This corresponds to {es-sql}'s request parameter `fetch_size` (see
+<<sql-rest-fields>>). The value 0 means server default.
 +
 * Max page length (MB)
 +
-The maximum number of megabytes that the driver will accept for one page.
-This corresponds to the `MaxBodySizeMB` setting in <<odbc-cfg-dsnparams>>.
+The maximum size (in megabytes) that an answer can grow to, before being
+rejected as too large by the driver.
+This is concerning the HTTP answer body of one page, not the cumulated data
+volume that a query might generate.
 +
 * Varchar limit
 +
-The maximum character length of the string type columns.
-this correspeonds to the `VarcharLimit` setting in <<odbc-cfg-dsnparams>>.
+The maximum width of the string columns.
+If this setting is greater than zero, the driver will advertise all the string
+type columns as having a maximum character length equal to this value and will
+truncate any longer string to it. The string types are textual fields
+(TEXT, KEYWORD etc.) and some specialized fields (IP, the GEOs etc.). Note that
+no interpretation of the value is performed before truncation, which can lead
+to invalid values if the limit is set too low.
+This is required for those applications that do not support column lengths as
+large as {es} fields can be.
 +
 * Floats format
 +
-How should the floating point numbers be printed, when these are converted to string by the driver.
-This corresponds to the `ScientificFloats` setting in <<odbc-cfg-dsnparams>>.
+Controls how the floating point numbers will be printed, when these are
+converted to string by the driver. Possible values given to this parameter:
++
+** `scientific`: the exponential notation (ex.: 1.23E01);
+
+** `default`: the default notation (ex.: 12.3);
+
+** `auto`: the driver will choose one of the above depending on the value to be
+printed.
+Note that the number of decimals is dependent on the precision (or ODBC scale)
+of the value being printed and varies with the different floating point types
+supported by {es-sql}.
+This setting is not effective when the application fetches from the driver the
+values as numbers and then does the conversion subsequently itself.
 +
 * Data encoding
 +
-How should the data between the server and the driver be encoded as.
-This corresponds to the `Packing` setting in <<odbc-cfg-dsnparams>>.
+This value controls which data format to encode the REST content in. Possible
+values are:
++
+** `CBOR`: use the Concise Binary Object Representation format. This is the
+preferred encoding, given its more compact format.
+
+** `JSON`: use the JavaScript Object Notation format. This format is more
+verbose, but easier to read, especially useful if troubleshooting.
 +
 * Data compression
 +
-Should the data between the server and the driver be compressed?
-This corresponds to the `Compression` setting in <<odbc-cfg-dsnparams>>.
+This setting controls if and when the REST content - encoded in one of the above
+formats -  is going to be compressed. The possible values are:
+
+** `on`: enables the compression;
+
+** `off`: disables the compression;
+
+** `auto`: enables the compression, except for the case when the data flows
+through a secure connection; since in this case the encryption layer employs
+its own data compression and there can be security implications when an
+additional compression is enabled, the setting should be kept to this value.
 +
 * Follow HTTP redirects
 +
 Should the driver follow HTTP redirects of the requests to the server?
-This corresponds to the `Follow` setting in <<odbc-cfg-dsnparams>>.
 +
 * Use local timezone
 +
-Should the driver use machine's local timezone? The default is UTC.
-This corresponds to the `ApplyTZ` setting in <<odbc-cfg-dsnparams>>.
+This setting controlls the timezone of:
++
+** the context in which the query will execute (especially relevant for functions dealing with timestamp components);
+
+** the timestamps received from / sent to the server.
++
+If disabled, the UTC timezone will apply; otherwise, the local machine's set
+timezone.
 +
 * Auto-escape PVAs
 +
-Should the driver auto-escape the pattern-value arguments?
-This corresponds to the `AutoEscapePVA` setting in <<odbc-cfg-dsnparams>>.
+The pattern-value arguments make use of `_` and `%` as special characters to
+build patern matching values. Some applications however use these chars as
+regular ones, which can lead to {es-sql} returning more data than the app
+intended. With the auto escaping, the driver will inspect the arguments and
+will escape these special characters if not already done by the application.
 +
 * Multi value field lenient
 +
-Should the server return one value out of a multi-value field (instead of rejecting the request)?
-This corresponds to the `MultiFieldLenient` setting in <<odbc-cfg-dsnparams>>.
+This setting controls the behavior of the server in case a
+multi-value field is queried. In case this is set and the server encounters
+such a field, it will pick a value in the set - without any guarantees of what
+that will be, but typically the first in natural ascending order - and return
+it as the value for the column. If not set, the server will return an error.
+This corresponds to {es-sql}'s request parameter `field_multi_value_leniency`
+(see <<sql-rest-fields>>).
 +
 * Include frozen indices
 +
-Should the server consider the frozen indices when servicing a request?
-This corresponds to the `IndexIncludeFrozen` setting in <<odbc-cfg-dsnparams>>.
+If this parameter is `true`, the server will include the frozen indices in the
+query execution.
+This corresponds to {es-sql}'s request parameter `index_include_frozen`
 +
 * Early query execution
 +
-Should the driver execute a non-parameterized query as soon as it's submitted
-for preparation?
-This corresponds to the `EarlyExecution` setting in <<odbc-cfg-dsnparams>>.
+If this configuration is set, the driver will execute a statement as soon as the
+application submits it for preparation - i.e. early - and is functionally
+equivalent to a direct execution. This will only happen if the query lacks
+parameters. Early execution is useful with those applications that inspect the
+result before actually executing the query. {es-sql} lacks a preparation API,
+so early execution is required for interoperability with these applications.
 
 
 [[dsn_editor_misc]]
@@ -256,7 +338,7 @@ This corresponds to the `EarlyExecution` setting in <<odbc-cfg-dsnparams>>.
 image:images/sql/odbc/dsn_editor_misc.png[]
 
 [discrete]
-===== 2.5 Logging parameters
+===== 2.6 Logging parameters
 For troubleshooting purposes, the {odbc} offers functionality to log the API calls that an application makes; this is enabled in the Administrator application:
 
 [[administrator_tracing]]
@@ -291,7 +373,7 @@ instructed so and preferably only when fetching low volumes of data.
 
 [discrete]
 [[connection_testing]]
-===== 2.5 Testing the connection
+===== 2.7 Testing the connection
 Once the _Hostname_, the _Port_ (if different from implicit default) and the SSL options are configured, you can test if the provided
 parameters are correct by pressing the _Test Connection_ button. This will instruct the driver to connect to the {es} instance and perform
 a simple SQL test query. (This will thus require a running {es} instance with the SQL plugin enabled.)
@@ -350,136 +432,3 @@ Both ways of configuring the logging can coexist and both can use the same
 destination logging directory. However, one logging message will only be logged
 once, the connection logging taking precedence over the environment variable
 logging.
-
-[[odbc-cfg-dsnparams]]
-[discrete]
-==== Connection string parameters
-
-The following is a list of additional parameters that can be configured for a
-particular connection, in case the default behavior of the driver is not
-suitable. For earlier versions of the driver, this needs to be done within the
-client application, in a manner particular to that application, generally in a
-free text input box (sometimes named "Connection string", "String extras", or
-similar). The format of the string is `Attribute1=Value1`. Multiple attributes
-can be specified, separated by a semicolon
-`Attribute1=Value1;Attribute2=Value2;`. The attribute names are given below.
-
-`Timeout` (default: `0`)::
-The maximum time (in seconds) a request to the server can take. This can be
-overridden by a larger statement-level timeout setting. The value 0 means no
-timeout.
-
-
-`Follow` (default: `yes`)::
-A boolean value (`yes`|`no` / `true`|`false` / `0`|`1`) controlling if the
-driver will follow HTTP redirects.
-
-
-`Packing` (default: `CBOR`)::
-This value controls which data format to encode the REST content in. Possible
-values are:
-
-* `CBOR`: use the Concise Binary Object Representation format. This is the
-preferred encoding, given its more compact format.
-
-* `JSON`: use the JavaScript Object Notation format. This format is more
-verbose, but easier to read, useful in debugging cases.
-
-
-`Compression` (default: `auto`)::
-This value controls if and when the REST content - encoded in one of the above
-formats -  is going to be compressed. The possible values are:
-
-* `on`: enables the compression;
-
-* `off`: disables the compression;
-
-* `auto`: enables the compression, except for the case when the data flows
-through a secure connection; since in this case the encryption layer employs
-its own data compression and there can be security implications when an
-additional compression is enabled, the setting should be kept to this value.
-
-
-`MaxFetchSize` (default: `0`)::
-The maximum number of rows that {es-sql} server should send the driver for one
-page. This corresponds to {es-sql}'s request parameter `fetch_size` (see
-<<sql-rest-fields>>). The value 0 means server default.
-
-
-`MaxBodySizeMB` (default: `100`)::
-The maximum size (in megabytes) that an answer can grow to, before being
-rejected as too large by the driver.
-This is concerning the HTTP answer body of one page, not the cumulated data
-volume that a query might generate.
-
-
-`VarcharLimit` (default: `0`)::
-The maximum width of the string columns.
-If this setting is greater than zero, the driver will advertise all the string
-type columns as having a maximum character length equal to this value and will
-truncate any longer string to it. The string types are textual fields
-(TEXT, KEYWORD etc.) and some specialized fields (IP, the GEOs etc.). Note that
-no interpretation of the value is performed before trunctation, which can lead
-to invalid values if the limit is set too low.
-This is required for those applications that do not support column lengths as
-large as {es} fields can be.
-
-
-`ApplyTZ` (default: `no`)::
-A boolean value controlling the timezone of:
-
-* the context in which the query will execute (especially relevant for functions dealing with timestamp components);
-
-* the timestamps received from / sent to the server.
-If disabled, the UTC timezone will apply; otherwise, the local machine's set
-timezone.
-
-
-`ScientificFloats` (default: `default`)::
-Controls how the floating point numbers will be printed, when these are
-converted to string by the driver. Possible values given to this parameter:
-
-* `scientific`: the exponential notation (ex.: 1.23E01);
-
-* `default`: the default notation (ex.: 12.3);
-
-* `auto`: the driver will choose one of the above depending on the value to be
-printed.
-Note that the number of decimals is dependent on the precision (or ODBC scale)
-of the value being printed and varies with the different floating point types
-supported by {es-sql}.
-This setting is not effective when the application fetches from the driver the
-values as numbers and then does the conversion subsequently itself.
-
-
-`MultiFieldLenient` (default: `true`)::
-This boolean parameter controls the behavior of the server in case a
-multi-value field is queried. In case this is set and the server encounters
-such a field, it will pick a value in the set - without any guarantees of what
-that will be, but typically the first in natural ascending order - and return
-it as the value for the column. If not set, the server will return an error.
-This corresponds to {es-sql}'s request parameter `field_multi_value_leniency`
-(see <<sql-rest-fields>>).
-
-
-`AutoEscapePVA` (default: `true`)::
-The pattern-value arguments make use of `_` and `%` as special characters to
-build patern matching values. Some applications however use these chars as
-regular ones, which can lead to {es-sql} returning more data than the app
-intended. With the auto escaping, the driver will inspect the arguments and
-will escape these special characters if not already done by the application.
-
-
-`IndexIncludeFrozen` (default: `false`)::
-If this parameter is `true`, the server will include the frozen indices in the
-query execution.
-This corresponds to {es-sql}'s request parameter `index_include_frozen`
-
-
-`EarlyExecution` (default: `true`)::
-If this parameter is `true`, the driver will execute a statement as soon as the
-application submits it for preparation, i.e. early and is functionally
-equivalent to a direct execution. This will only happen if the query lacks
-parameters. Early execution is useful with those applications that inspect the
-result before actually executing the query. {es-sql} lacks a preparation API,
-so early execution is required for interoperability with these applications.