配置
编辑配置
编辑安装驱动程序后，为了使应用程序能够通过 ODBC 连接到 Elasticsearch，必须向驱动程序提供一组配置参数。根据应用程序的不同，通常有三种提供这些参数的方法：
- 通过连接字符串；
- 使用用户 DSN 或系统 DSN；
- 通过文件 DSN。
DSN（数据源名称）是 ODBC 驱动程序连接到数据库所需的一组参数的通用名称。
我们将这些参数称为连接参数或DSN（尽管其中一些参数配置了驱动程序功能的其他方面；例如日志记录、缓冲区大小等）。
使用 DSN 是执行驱动程序配置最广泛使用、最简单和最安全的方法。另一方面，构建连接字符串是最粗略的方法，因此也是最不常见的方法。
我们将只关注 DSN 的使用。
1. 启动 ODBC 数据源管理员
编辑对于 DSN 管理，ODBC 提供了ODBC 数据源管理员应用程序，该应用程序已预先安装在所有最新的桌面 Windows 操作系统上。
- Odbcad32.exe 文件的 32 位版本位于
%systemdrive%\Windows\SysWoW64文件夹中。 - Odbcad32.exe 文件的 64 位版本位于
%systemdrive%\Windows\System32文件夹中。
要启动它，请打开搜索菜单 - Win + S - 并键入“ODBC 数据源 (64 位)”或“ODBC 数据源 (32 位)”，然后按Enter键。
启动后，您可以通过单击 ODBC 数据源管理员的驱动程序选项卡并检查Elasticsearch 驱动程序是否出现在已安装驱动程序列表中来验证驱动程序是否已正确安装。
您还应该看到已安装驱动程序的版本号。
2. 配置 DSN
编辑下一步是配置 DSN。您可以选择以下选项，这些选项映射到管理员应用程序的前三个选项卡上：
-
用户 DSN
在此选项卡下配置的连接仅对当前登录的用户可用。每个 DSN 都由一个选定的任意名称（通常是主机或集群名称）来引用。
构成 DSN 的实际参数集通过驱动程序存储在系统注册表中。因此，用户以后只需要向应用程序提供 DSN 名称即可连接到配置的 Elasticsearch 实例。
-
系统 DSN
类似于用户 DSN，只是在此选项卡下配置的连接将对系统上配置的所有用户可用。
-
文件 DSN
此选项卡包含允许将一组连接参数写入文件而不是注册表的功能。
然后可以在多个系统之间共享此文件，用户需要指定其路径，以便应用程序连接到配置的 Elasticsearch 实例。
所有上述步骤的配置步骤都类似。以下是配置系统 DSN 的示例。
2.1 启动 Elasticsearch SQL ODBC 驱动程序 DSN 编辑器
编辑单击系统 DSN选项卡，然后单击添加…按钮
将打开一个新窗口，列出所有可用的已安装驱动程序。单击Elasticsearch 驱动程序以突出显示它，然后单击完成按钮
此操作将关闭先前打开的第二个窗口并改为打开一个新的窗口，即 Elasticsearch SQL ODBC 驱动程序的 DSN 编辑器。
Elasticsearch SQL ODBC 驱动程序 DSN 编辑器
此新窗口包含三个选项卡，每个选项卡负责一组配置参数，如下所示。
2.2 连接参数
编辑此选项卡允许配置以下项目：
-
名称
这是 DSN 将被引用的名称。
此字段可用的字符仅限于注册表密钥允许的字符集。
示例：localhost
-
描述
此字段允许任意文本；通常用于有关配置连接的简短注释。
示例：到本地 [::1]:9200 的明文连接。
-
云 ID
云 ID是一个字符串，在连接到 Elastic 的云 Elasticsearch 服务时可以简化配置；它是在每个 Elasticsearch 集群的云控制台中获取的，并对该集群的连接参数进行编码。
当此字段已配置时，主机名、端口和安全设置也将被配置，并且其各自的输入将被禁用。
-
主机名
此字段需要驱动程序将连接到的 Elasticsearch 实例的 IP 地址或可解析的 DNS 名称。
示例：::1
-
端口
Elasticsearch 监听的端口。
如果留空，将使用默认的9200端口号。
-
用户名、密码
如果启用了安全性，则这些字段需要包含访问用户的凭据。
在保存 DSN 之前，至少必须配置名称和主机名字段。
默认情况下启用连接加密。如果连接到没有加密的 Elasticsearch 节点，则需要更改此设置。
2.3 加密参数
编辑可以选择以下 SSL 选项之一：
-
禁用。所有通信未加密。
驱动程序和 Elasticsearch 实例之间的通信通过明文连接执行。
此设置可能会将访问凭据暴露给拦截网络流量的第三方，因此不建议使用。
-
启用。证书未验证。
连接加密已启用，但服务器的证书未验证。
这是当前的默认设置。
此设置允许第三方轻松地充当中间人，从而拦截所有通信。
-
启用。证书已验证；主机名未验证。
连接加密已启用，并且驱动程序验证服务器的证书有效，但它不验证证书是否在它所属的服务器上运行。
此设置允许访问服务器证书的第三方充当中间人，从而拦截所有通信。
-
启用。证书已验证；主机名已验证。
连接加密已启用，并且驱动程序验证证书有效，以及它是否部署在证书所属的服务器上。
-
启用。证书标识链已验证。
此设置等同于前一个设置，但额外检查了证书的吊销。这提供了最强大的安全选项，并且是生产部署的推荐设置。
-
证书文件
如果服务器使用不属于 PKI 的证书，例如使用自签名证书，则可以配置指向 X.509 证书文件的路径，该文件将由驱动程序用于验证服务器提供的证书。
驱动程序仅在尝试连接之前读取文件内容。请参阅2.7 测试连接部分，了解如何检查所提供参数的有效性。
证书文件不能捆绑或受密码保护，因为驱动程序不会提示输入密码。
如果使用文件浏览器查找证书 - 通过按浏览…按钮 - 默认情况下，只有扩展名为.pem和.der的文件会被考虑。如果您的文件以其他扩展名结尾，请从下拉列表中选择所有文件（*.*）
2.4 代理参数
编辑如果连接到 Elasticsearch 节点需要通过代理，则需要配置以下参数：
-
类型
连接到代理主机时要使用哪种协议。这也强制要求您必须在2.2 连接参数下指定您要通过代理连接到的 Elasticsearch 节点。
- HTTP、SOCKS4A、SOCKS5H：接受 IP 地址或主机名；代理将解析 DNS 名称；
- SOCKS4、SOCKS5：Elasticsearch 节点位置需要作为 IP 地址提供；
-
端口
代理正在监听连接的 TCP 端口。
-
用户名
用于对代理进行身份验证的凭据的用户部分。
-
密码
代理凭据的密码部分。
2.5 连接参数
编辑可以通过以下参数进一步调整连接配置。
-
请求超时（秒）
对服务器的请求可以花费的最大时间（以秒为单位）。这可以被更大的语句级超时设置覆盖。值 0 表示没有超时。
-
最大页面大小（行）
Elasticsearch SQL 服务器应为一页发送给驱动程序的最大行数。这对应于 SQL 搜索 API 的
fetch_size参数。0值表示服务器默认值。 -
最大页面长度（MB）
答案可以增长到的最大大小（以兆字节为单位），在被驱动程序拒绝为过大之前。这是关于一页的 HTTP 答案正文，而不是查询可能生成的累积数据量。
-
VARCHAR 限制
字符串列的最大宽度。如果此设置大于零，则驱动程序将宣传所有字符串类型列的最大字符长度等于此值，并将任何更长的字符串截断为它。字符串类型是文本字段（TEXT、KEYWORD 等）和一些专门字段（IP、GEO 等）。请注意，在截断之前不会对值进行任何解释，如果限制设置得太低，可能会导致无效值。这对于那些不支持与 Elasticsearch 字段一样长的列长度的应用程序是必需的。
-
浮点数格式
控制驱动程序将浮点数转换为字符串时如何打印它们。此参数可以使用的可能值：
-
scientific：指数表示法（例如：1.23E01）； -
default：默认表示法（例如：12.3）； -
auto：驱动程序将根据要打印的值选择上述值之一。请注意，小数位数取决于要打印的值的精度（或 ODBC 比例），并且随 Elasticsearch SQL 支持的不同浮点数类型而异。当应用程序从驱动程序获取值作为数字，然后随后自行执行转换时，此设置无效。
-
-
数据编码
此值控制以哪种数据格式对 REST 内容进行编码。可能的值为
-
CBOR：使用简洁二进制对象表示格式。鉴于其更紧凑的格式，这是首选编码。 -
JSON：使用 JavaScript 对象表示法格式。此格式更冗长，但更易于阅读，尤其是在进行故障排除时非常有用。
-
-
数据压缩
此设置控制是否以及何时压缩 REST 内容（以上述格式之一进行编码）。可能的值为
-
on：启用压缩； -
off：禁用压缩； -
auto：启用压缩，但数据通过安全连接传输的情况除外；因为在这种情况下，加密层使用其自身的数据压缩，并且启用额外压缩可能会存在安全隐患，因此应将设置保留为此值。
-
-
遵循 HTTP 重定向
驱动程序是否应遵循对服务器的请求的 HTTP 重定向？
-
使用本地时区
此设置控制
- 查询将执行的上下文中的时区（尤其与处理时间戳组件的函数相关）；
-
从服务器接收/发送到服务器的时间戳。
如果禁用，则将应用 UTC 时区；否则，将应用本地机器设置的时区。
-
自动转义 PVA
模式值参数使用
_和%作为特殊字符来构建模式匹配值。但是，某些应用程序将这些字符用作常规字符，这可能导致 Elasticsearch SQL 返回比应用程序预期更多的数据。通过自动转义，驱动程序将检查参数，如果应用程序尚未完成，则将转义这些特殊字符。 -
多值字段宽松
此设置控制服务器在查询多值字段时的行为。如果设置了此选项并且服务器遇到此类字段，它将从集合中选择一个值——没有任何保证会是什么值，但通常是自然升序中的第一个值——并将其作为该列的值返回。如果未设置，则服务器将返回错误。这对应于 SQL 搜索 API 的
field_multi_value_leniency参数。 -
包含冻结索引
如果此参数为
true，则服务器将在查询执行中包含冻结索引。这对应于 Elasticsearch SQL 的请求参数index_include_frozen -
早期查询执行
如果设置了此配置，则驱动程序将在应用程序提交语句以进行准备（即早期）时立即执行该语句，并且在功能上等效于直接执行。这只有在查询缺少参数时才会发生。对于在实际执行查询之前检查结果的那些应用程序，早期执行很有用。Elasticsearch SQL 缺少准备 API，因此早期执行对于与这些应用程序的互操作性是必需的。
2.6 日志记录参数
编辑出于故障排除目的，Elasticsearch SQL ODBC 驱动程序提供了记录应用程序发出的 API 调用的功能；这在管理员应用程序中启用
但是，这仅将应用程序在驱动程序管理器中发出的 ODBC API 调用记录到日志中，而不会记录驱动程序管理器本身在驱动程序中发出的调用。要启用驱动程序接收的调用的日志记录以及内部驱动程序处理事件，您可以在编辑器的“日志记录”选项卡上启用驱动程序的日志记录
调试日志记录可能很快会导致创建许多非常大的文件并产生大量的处理开销。仅在得到指示时启用，最好是在获取少量数据时启用。
2.7 测试连接
编辑配置完主机名、端口（如果与隐式默认值不同）和 SSL 选项后，您可以通过按下测试连接按钮来测试提供的参数是否正确。这将指示驱动程序连接到 Elasticsearch 实例并执行简单的 SQL 测试查询。（因此，这需要一个启用了 SQL 插件的正在运行的 Elasticsearch 实例。）
在进行连接测试时，将考虑所有配置的参数，包括日志记录配置。这将允许尽早检测潜在的文件/目录访问权限冲突。
有关配置日志记录的替代方法，请参阅替代日志记录配置部分。
3. DSN 可用
编辑一切就绪后，按下保存按钮将配置存储到选定的目标（注册表或文件）中。
保存 DSN 配置之前，将验证所提供的文件/目录路径在当前系统上是否有效。但是，DSN 编辑器不会以任何方式验证配置的主机名：端口的有效性或可达性。有关详尽的检查，请参阅2.7 测试连接。
如果一切正确，新创建的 DSN 的名称将被列出，可用作
替代日志记录配置
编辑由于 ODBC API 的规范，驱动程序仅在调用连接 API（例如SQLConnect或SQLDriverConnect）后才会接收配置的 DSN 参数（包括日志记录参数）。但是，驱动程序管理器将在尝试建立连接之前始终对驱动程序进行一组 API 调用。要捕获这些调用，需要以替代方式传递日志记录配置参数。Elasticsearch SQL ODBC 驱动程序将为此目的使用环境变量。
配置环境变量是特定于操作系统的，本指南中未详细介绍。变量应在系统范围内配置还是用户范围内配置取决于 ODBC 启用应用程序的运行方式以及日志记录是否仅影响当前用户。
环境变量的定义需要按如下方式进行
- 名称：ESODBC_LOG_DIR
-
值：[path](?[level])，其中
[path]是将日志文件写入的目录的路径；
[level]是可选的，可以取以下值之一：debug、info、warn、error；如果未提供，则假定为debug。
通过环境变量启用日志记录时，驱动程序将为每个进程创建一个日志文件。
两种配置日志记录的方式可以共存，并且两者都可以使用相同的目标日志记录目录。但是，每个日志消息仅记录一次，连接日志记录优先于环境变量日志记录。