« SQL JDBC SQL Client Applications »
Elastic Docs ›Elasticsearch Guide ›SQL

SQL ODBC

edit

SQL ODBC

edit

概述

edit

Elasticsearch SQL ODBC 驱动程序是一个符合 3.80 标准的 ODBC 驱动程序，适用于 Elasticsearch。 它是一个核心级别的驱动程序，通过 Elasticsearch 的 SQL API 公开所有功能，将 ODBC 调用转换为 Elasticsearch SQL。

为了使用该驱动程序，服务器必须安装并运行带有有效许可证的Elasticsearch SQL。

驱动安装

edit

Elasticsearch SQL ODBC 驱动程序可以通过 MSI 包安装在 Microsoft Windows 上。安装过程简单，由标准的 MSI 向导步骤组成。

安装先决条件

edit

推荐的安装平台是Windows 10 64位或Windows Server 2016 64位。

在安装 Elasticsearch SQL ODBC 驱动程序之前，您需要满足以下先决条件；

如果你未能满足任何先决条件，安装程序将显示错误消息并中止安装。

使用MSI进行就地升级是不可能的。为了升级，您首先需要卸载旧驱动程序，然后安装新驱动程序。

在安装 MSI 时，Windows Defender SmartScreen 可能会警告正在运行一个未识别的应用程序。如果 MSI 是从 Elastic 的网站下载的，可以安全地通过允许安装继续来确认该消息（仍然运行）。

版本兼容性

edit

您的驱动程序必须与您的 Elasticsearch 版本兼容。

驱动程序版本不能比 Elasticsearch 版本更新。 例如，Elasticsearch 版本 7.10.0 与 9.0.0-beta1 驱动程序不兼容。

Elasticsearch version Compatible driver versions Example

7.7.0 及更早版本
  • 相同版本。

Elasticsearch 7.6.1 仅兼容 7.6.1 驱动程序。

下载 .msi 安装包

edit

下载 Elasticsearch SQL ODBC Driver 9.0.0-beta1 的 .msi 安装包，地址为： https://www.elastic.co/downloads/odbc-client

有两个版本的安装程序可供选择：

  • 32位驱动程序（x86） 用于与Microsoft Office 2016套件应用程序一起使用；特别是Microsoft Excel和Microsoft Access以及其他基于32位的程序。
  • 64位驱动程序（x64） 推荐用于与其他所有应用程序一起使用。

用户应考虑下载并安装32位和64位驱动程序，以确保其系统上安装的应用程序具有最大的兼容性。

使用图形用户界面 (GUI) 进行安装

edit

双击下载的 .msi 包以启动一个图形界面向导，该向导将引导您完成安装过程。

您将首先看到一个欢迎屏幕：

Installer Welcome Screen

点击下一步将显示最终用户许可协议。您需要接受许可协议才能继续安装。

Installer EULA Screen

以下屏幕允许您自定义Elasticsearch ODBC驱动程序文件的安装路径。

默认安装路径的格式为：%ProgramFiles%\Elastic\ODBCDriver\9.0.0-beta1

Installer Driver Path

您现在可以安装驱动程序了。

您需要提升的权限（管理员）进行安装。

Installer Begin

假设安装过程没有错误，您应该会看到进度屏幕，随后是完成屏幕：

Installer Installing

在完成屏幕上，您可以通过勾选对话框复选框来启动ODBC数据源管理屏幕。这将自动在关闭时（32位或64位）启动配置屏幕，您可以在其中配置DSN。

Installer Complete

与任何MSI安装包一样，安装过程的日志文件可以在%TEMP%目录中找到，文件名随机生成，符合MSI.LOG格式。

如果在安装过程中遇到错误，我们鼓励您打开一个issue https://github.com/elastic/elasticsearch-sql-odbc/issues，附上您的安装日志文件并提供更多详细信息，以便我们进行调查。

使用命令行进行安装

edit

下面给出的示例适用于安装64位MSI包。要使用32位MSI包实现相同的结果，您需要使用文件名后缀windows-x86.msi

可以通过命令行安装 .msi。使用与图形用户界面相同的默认值进行最简单的安装，首先导航到下载目录，然后运行：

msiexec.exe /i esodbc-9.0.0-beta1-windows-x86_64.msi /qn

默认情况下，msiexec.exe 不会等待安装过程完成，因为它在 Windows 子系统中运行。为了等待进程完成并确保 %ERRORLEVEL% 被相应设置，建议使用 start /wait 来创建一个进程并等待它退出：

start /wait msiexec.exe /i esodbc-9.0.0-beta1-windows-x86_64.msi /qn

与任何MSI安装包一样，安装过程的日志文件可以在%TEMP%目录中找到，文件名是随机生成的，符合MSI.LOG格式。可以使用/l命令行参数提供日志文件的路径。

start /wait msiexec.exe /i esodbc-9.0.0-beta1-windows-x86_64.msi /qn /l install.log

支持的 Windows Installer 命令行参数可以使用以下方式查看：

msiexec.exe /help

…​或者通过查阅Windows Installer SDK 命令行选项。

命令行选项

edit

在GUI中公开的所有设置也可以作为命令行参数（在Windows Installer文档中称为属性）传递给msiexec.exe：

INSTALLDIR

安装目录。 默认为 %ProgramFiles%\Elastic\ODBCDriver\9.0.0-beta1。

要传递一个值，只需使用格式 ="" 将属性名称和值附加到安装命令中。例如，要使用与默认目录不同的安装目录：

start /wait msiexec.exe /i esodbc-9.0.0-beta1-windows-x86_64.msi /qn INSTALLDIR="c:\CustomDirectory"

请参阅Windows Installer SDK 命令行选项 以了解与包含引号的值相关的其他规则。

使用添加/删除程序进行卸载

edit

The .msi 包处理作为安装一部分添加的所有目录和文件的卸载。

卸载将删除作为安装一部分创建的所有内容。

已安装的程序可以通过按下Windows键并输入添加或删除程序来打开系统设置进行卸载。

打开后，在已安装应用程序列表中找到Elasticsearch ODBC驱动程序，点击并选择卸载：

uninstall

使用命令行卸载

edit

卸载也可以通过导航到包含 .msi 包的目录并运行以下命令来从命令行执行：

start /wait msiexec.exe /x esodbc-9.0.0-beta1-windows-x86_64.msi /qn

与安装过程类似，可以使用 /l 命令行参数传递卸载过程的日志文件路径。

start /wait msiexec.exe /x esodbc-9.0.0-beta1-windows-x86_64.msi /qn /l uninstall.log

配置

edit

一旦驱动程序安装完成，为了让应用程序能够通过ODBC连接到Elasticsearch，必须向驱动程序提供一组配置参数。根据应用程序的不同，通常有三种方式来提供这些参数：

  • 通过连接字符串；
  • 使用用户DSN或系统DSN；
  • 通过文件DSN。

DSN（数据源名称）是分配给一组参数的通用名称，ODBC驱动程序需要这些参数来连接到数据库。

我们将这些参数称为连接参数或DSN（尽管其中一些参数配置了驱动程序其他功能的一些方面；例如，日志记录、缓冲区大小……​）。

使用DSN是最广泛使用、最简单且最安全的驱动配置方式。另一方面，构建连接字符串是最原始的方式，因此也是最不常见的方法。

我们将只关注DSN的使用。

1. 启动ODBC数据源管理器

edit

对于DSN管理，ODBC提供了ODBC 数据源管理器应用程序，该应用程序已预装在所有最新的桌面Windows操作系统上。

  • 32位版本的Odbcad32.exe文件位于%systemdrive%\Windows\SysWoW64文件夹中。
  • 64位版本的Odbcad32.exe文件位于%systemdrive%\Windows\System32文件夹中。

要启动它，打开搜索菜单 - Win + S - 并输入 "ODBC 数据源 (64 位)" 或 "ODBC 数据源 (32 位)" 然后按 Enter：

启动ODBC数据源管理器启动管理器

一旦启动，您可以通过点击ODBC数据源管理器中的驱动程序选项卡，并检查Elasticsearch驱动程序是否出现在已安装驱动程序列表中，来验证驱动程序是否已正确安装。

您还应该看到已安装驱动的版本号。

驱动程序选项卡管理员驱动程序

2. 配置DSN

edit

下一步是配置一个DSN。您可以在管理员应用程序的前三个选项卡上选择以下选项：

  • 用户 DSN

    在此选项卡下配置的连接仅对当前登录的用户可用。这些DSN中的每一个都由一个选定的任意名称（通常是主机或集群名称）引用。

    构成DSN的实际参数集通过驱动程序存储在系统注册表中。因此，用户以后只需向应用程序提供DSN名称即可连接到配置的Elasticsearch实例。

  • 系统DSN

    类似于用户DSN，不同之处在于在此选项卡下配置的连接将对系统上配置的所有用户可用。

  • 文件 DSN

    此选项卡包含的功能将允许将一组连接参数写入文件，而不是注册表。

    这样的文件可以在多个系统之间共享，用户需要指定其路径，以便应用程序连接到配置的Elasticsearch实例。

所有上述点的配置步骤都是相似的。以下是配置系统DSN的示例。

2.1 启动 Elasticsearch SQL ODBC 驱动程序 DSN 编辑器
edit

点击系统DSN标签，然后点击添加…​按钮：

添加一个新的DSN管理员系统添加

将打开一个新窗口，列出所有可用的已安装驱动程序。点击Elasticsearch驱动程序以突出显示它，然后点击完成按钮：

启动DSN编辑器管理员启动编辑器

此操作关闭之前打开的第二个窗口，并打开一个新的窗口，Elasticsearch SQL ODBC Driver 的 DSN 编辑器：

Elasticsearch SQL ODBC 驱动程序 DSN 编辑器dsn editor basic

这个新窗口有三个标签页，每个标签页负责一组配置参数，如下所示。

2.2 连接参数
edit

此选项卡允许配置以下项目：

  • 名称

    这是DSN将被引用的名称。

    此字段可用的字符仅限于注册表键允许的字符集。

    示例: 本地主机

  • 描述

    此字段允许输入任意文本；通常用于记录有关配置连接的简短说明。

    示例: 明文连接到本地 [::1]:9200。

  • 云ID

    Cloud ID 是一个字符串，简化了连接到 Elastic 的 Cloud Elasticsearch 服务时的配置；它从每个 Elasticsearch 集群的 Cloud 控制台中获取，并编码了连接到该集群的参数。

    当此字段被配置时，主机名、端口和安全设置也会被配置，并且它们各自对应的输入项将被禁用。

  • 主机名

    此字段需要一个IP地址或可解析的DNS名称，即驱动程序将连接到的Elasticsearch实例。

    示例: ::1

  • 端口

    Elasticsearch 监听的端口。

    如果留空，将使用默认的9200端口号。

  • 用户名, 密码

    如果启用了安全性，这些字段将需要包含访问用户的凭据。

至少，在保存DSN之前，必须配置名称和主机名字段。

连接加密默认是启用的。如果连接到没有加密的Elasticsearch节点，则需要更改此设置。

2.3 加密参数
edit

可以选择以下SSL选项之一：

  • 已禁用。所有通信均为未加密。

    驱动程序与 Elasticsearch 实例之间的通信是通过明文连接进行的。

    此设置可能会将访问凭据暴露给拦截网络流量的第三方，因此不推荐使用。

  • 已启用。证书未验证。

    连接加密已启用，但未验证服务器的证书。

    这是当前的默认设置。

    此设置允许第三方轻松充当中间人，从而拦截所有通信。

  • 已启用。证书已验证；主机名未验证。

    连接加密已启用，驱动程序验证服务器的证书是否有效，但它不验证证书是否运行在其预期的服务器上。

    此设置允许第三方访问服务器的证书，从而充当中间人并拦截所有通信。

  • 已启用。证书已验证；主机名已验证。

    连接加密已启用，驱动程序验证证书是否有效，以及是否部署在证书所针对的服务器上。

  • 已启用。证书身份链已验证。

    此设置等同于前一个设置，但增加了一项针对证书吊销的额外检查。这提供了最强的安全选项，是生产部署的推荐设置。

  • 证书文件

    如果服务器使用的证书不是PKI的一部分，例如使用自签名证书，您可以配置X.509证书文件的路径，该文件将由驱动程序用于验证服务器提供的证书。

    驱动程序只会在尝试连接之前读取文件的内容。请参阅2.7 测试连接部分，了解如何检查所提供参数的有效性。

    证书文件不能被打包或受密码保护，因为驱动程序不会提示输入密码。

    如果使用文件浏览器来定位证书 - 通过按下浏览…​按钮 - 默认情况下只会考虑扩展名为.pem和.der的文件。如果你的文件以不同的扩展名结尾，请从下拉菜单中选择所有文件 (*.*)：

    证书文件浏览器dsn editor security cert

2.4 代理参数
edit

如果连接到 Elasticsearch 节点需要通过代理，则需要配置以下参数：

  • 类型

    连接到代理主机时使用哪种协议。这也规定了在通过代理连接到您想要连接的Elasticsearch节点时，需要在2.2 连接参数下如何指定该节点：

    • HTTP, SOCKS4A, SOCKS5H: 接受IP地址或主机名；代理将解析DNS名称；
    • SOCKS4, SOCKS5: Elasticsearch节点位置需要提供为IP地址；

  • 端口

    代理正在监听连接的TCP端口。

  • 用户名

    用于向代理进行身份验证的凭据的用户部分。

  • 密码

    代理凭证的密码部分。

代理参数dsn editor proxy

2.5 连接参数
edit

连接配置可以通过以下参数进一步调整。

  • 请求超时（秒）

    请求服务器可以花费的最大时间（以秒为单位）。这可以通过更大的语句级超时设置来覆盖。值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时区；否则，将应用本地机器设置的时区。

  • 自动转义 PVAs

    模式值参数使用 _ 和 % 作为特殊字符来构建模式匹配值。然而，某些应用程序将这些字符用作常规字符，这可能导致 Elasticsearch SQL 返回比应用程序预期更多的数据。通过自动转义，驱动程序将检查参数并在应用程序尚未完成时转义这些特殊字符。

  • 多值字段宽松

    此设置控制服务器在查询多值字段时的行为。如果设置了此选项且服务器遇到此类字段，它将从中选择一个值——不保证具体是哪个值，但通常是自然升序中的第一个——并将其作为列的值返回。如果未设置，服务器将返回错误。这对应于SQL搜索API的field_multi_value_leniency参数。

  • 包含冻结索引

    如果此参数为true，服务器将在查询执行中包含冻结的索引。 这对应于Elasticsearch SQL的请求参数index_include_frozen

  • 早期查询执行

    如果设置了此配置，驱动程序将在应用程序提交准备时立即执行语句，即早期执行，并且在功能上等同于直接执行。这仅在查询缺少参数时发生。早期执行对于那些在实际执行查询之前检查结果的应用程序非常有用。Elasticsearch SQL 缺少准备 API，因此需要早期执行以与这些应用程序进行互操作。

连接参数dsn editor misc

2.6 日志参数
edit

为了故障排除的目的，Elasticsearch SQL ODBC驱动程序提供了记录应用程序所做API调用的功能；此功能在管理员应用程序中启用：

启用应用程序 ODBC API 日志记录管理员跟踪

然而，这仅记录应用程序对驱动管理器进行的ODBC API调用，而不记录驱动管理器对驱动程序本身的调用。要启用对驱动程序接收到的调用以及内部驱动程序处理事件的日志记录，您可以在编辑器的日志记录选项卡上启用驱动程序的日志记录：

  • 启用日志记录？

    勾选此项将启用驱动程序的日志记录。当启用此选项时，日志目录也是强制性的（请参见下一个选项）。 但是，即使日志记录被禁用，指定的日志目录也会保存在DSN中（如果提供）。

  • 日志目录

    这里是指定将日志文件写入哪个目录。

    驱动程序将为每个生成日志消息的连接创建一个日志文件。

  • 日志级别

    配置日志的详细程度。

    启用驱动程序日志记录dsn editor logging

    当启用身份验证时，密码将从日志中被隐藏。

调试日志记录可能会迅速导致创建许多非常大的文件，并产生显著的处理开销。只有在被指示时才启用，并且最好仅在获取低量数据时启用。

2.7 测试连接
edit

一旦配置了主机名、端口（如果与隐式默认值不同）和SSL选项，您可以通过按下测试连接按钮来测试所提供的参数是否正确。这将指示驱动程序连接到Elasticsearch实例并执行一个简单的SQL测试查询。（因此，这将需要一个运行中的Elasticsearch实例，并且启用了SQL插件。）

连接测试dsn editor conntest

在进行连接测试时，所有配置的参数都会被考虑在内，包括日志配置。这将允许早期检测潜在的文件/目录访问权限冲突。

请参阅替代日志配置部分，了解另一种配置日志的方法。

3. DSN 可用

edit

一旦所有内容都准备就绪，按下保存按钮将会将配置存储到所选的目标位置（注册表或文件）。

在保存DSN配置之前，提供的文件/目录路径会在当前系统上进行验证以确保其有效性。然而，DSN编辑器不会以任何方式验证配置的主机名 : 端口的有效性或可达性。请参阅2.7 测试连接以进行全面检查。

如果一切正确，新创建的DSN名称将会列出并可供使用：

连接已添加管理员系统已添加

替代日志配置

edit

由于ODBC API的规范，驱动程序只有在调用连接API（如SQLConnect或SQLDriverConnect）时才会接收到配置的DSN参数——包括日志记录参数。然而，驱动程序管理器在尝试建立连接之前，总是会向驱动程序发出一组API调用。为了捕获这些调用，需要以另一种方式传递日志记录配置参数。Elasticsearch SQL ODBC驱动程序将为此目的使用环境变量。

配置环境变量是操作系统特定的，本指南中不做详细说明。变量是应该在系统范围内配置还是用户特定配置，取决于ODBC启用应用程序的运行方式以及日志记录是否应该仅影响当前用户。

环境变量的定义需要按照以下方式进行：

  • 名称: ESODBC_LOG_DIR

  • 值: [路径](?[级别])，其中:

    [路径] 是日志文件将被写入的目录路径；

    [级别] 是可选的，可以取以下值之一：调试、信息、警告、错误；如果未提供，则默认值为 调试。

日志环境变量env var log

当通过环境变量启用日志记录时，驱动程序将为每个进程创建一个日志文件。

配置日志的两种方式可以共存，并且两者都可以使用相同的日志目录。然而，一条日志消息只会被记录一次，连接日志优先于环境变量日志。

« SQL JDBC SQL Client Applications »