« SQL CLI SQL ODBC »
Elastic Docs ›Elasticsearch Guide ›SQL

SQL JDBC

edit

SQL JDBC

edit

Elasticsearch 的 SQL jdbc 驱动程序是一个功能丰富、功能齐全的 JDBC 驱动程序，适用于 Elasticsearch。 它是一个 Type 4 驱动程序，这意味着它是一个平台无关的、独立的、直接连接到数据库的纯 Java 驱动程序，用于将 JDBC 调用转换为 Elasticsearch SQL。

安装

edit

JDBC 驱动可以从以下位置获取：

Dedicated page
elastic.co 提供了链接，通常用于手动下载。
Maven dependency
Maven-兼容的工具可以自动将其作为依赖项检索： 
<dependency>
  <groupId>org.elasticsearch.plugin</groupId>
  <artifactId>x-pack-sql-jdbc</artifactId>
  <version>9.0.0-beta1</version>
</dependency>

从 Maven中央仓库， 或者从 artifacts.elastic.co/maven 通过将其添加到仓库列表中：

<repositories>
  <repository>
    <id>elastic.co</id>
    <url>https://artifacts.elastic.co/maven</url>
  </repository>
</repositories>

版本兼容性

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 驱动程序。

设置

edit

驱动程序的主类是 org.elasticsearch.xpack.sql.jdbc.EsDriver。 注意，该驱动程序实现了 JDBC 4.0 Service Provider 机制，这意味着只要它在类路径中可用，它就会自动注册。

一旦注册，驱动程序将理解以下语法作为URL：

jdbc:[es|elasticsearch]://[[http|https]://]?[host[:port]]?/[prefix]?[\?[option=value]&]*
jdbc:[es|elasticsearch]://
前缀。必填。
[[http|https]://]
HTTP 连接的类型。可能的值是 http（默认）或 https。可选。
[host[:port]]
主机（默认为localhost）和端口（默认为9200）。 可选。
[prefix]
前缀（默认为空）。通常在将Elasticsearch托管在特定路径下时使用。可选。
[option=value]
JDBC 驱动的属性。默认为空。 可选。

驱动程序识别了以下属性：

基本
edit
timezone (default JVM timezone)
驱动程序用于每个连接的时区，由其ID指示。 强烈建议设置它（例如，设置为UTC），因为JVM时区可能会有所不同，对于整个JVM是全局的，并且在安全管理器下运行时不容易更改。
网络
edit
connect.timeout (default 30000)
连接超时（以毫秒为单位）。即等待与服务器建立连接的最大时间。
network.timeout (default 60000)
网络超时（以毫秒为单位）。即等待网络的最大时间。
page.size (default 1000)
页面大小（以条目为单位）。服务器每页返回的结果数量。
page.timeout (default 45000)
页面超时（以毫秒为单位）。服务器上滚动游标的最小保留期。需要服务器端有状态滚动游标的查询可能会在此超时后失败。因此，在滚动浏览大型结果集时，处理page.size记录的时间不应超过page.timeout毫秒。
query.timeout (default 90000)
查询超时（以毫秒为单位）。即等待查询返回的最大时间。

基本认证

edit
user
基本身份验证用户名
password
基本身份验证密码

SSL

edit
ssl (default false)
启用 SSL
ssl.keystore.location
密钥库（如果使用）位置
ssl.keystore.pass
密钥库密码
ssl.keystore.type (default JKS)
密钥库类型。PKCS12 是一种常见的替代格式
ssl.truststore.location
信任存储位置
ssl.truststore.pass
信任库密码
ssl.truststore.type (default JKS)
信任存储类型。PKCS12 是一种常见的替代格式
ssl.protocol(default TLS)
要使用的SSL协议

代理

edit
proxy.http
HTTP代理主机名
proxy.socks
SOCKS 代理主机名

映射

edit
field.multi.value.leniency (default true)
是否宽容并返回第一个值（不保证该值是什么 - 通常是自然升序中的第一个）对于具有多个值的字段（true）或抛出异常。

索引

edit
index.include.frozen (default false)
是否在查询执行中包含冻结索引（默认）。

集群

edit
catalog

查询的默认目录（集群）。如果未指定，查询仅在本地集群中的数据上执行。

[预览] 此功能处于技术预览阶段，可能会在未来的版本中进行更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。 请参阅 跨集群搜索。

错误处理

edit
allow.partial.search.results (default false)
是否在分片失败时返回部分结果，或者抛出底层异常并使查询失败（默认）。

故障排除

edit
debug (default false)
将其设置为 true 将启用调试日志记录。
debug.output (default err)
调试日志的目标位置。默认情况下，它们会被发送到标准错误。值 out 会将日志重定向到标准输出。也可以指定一个文件路径。

附加内容

edit
validate.properties (default true)
如果禁用，它将忽略任何拼写错误或无法识别的属性。启用时，如果提供的属性无法识别，将抛出异常。

将所有内容放在一起，以下URL：

jdbc:es://http://server:3456/?timezone=UTC&page.size=250

打开一个到端口3456上的server的Elasticsearch SQL连接，将JDBC连接时区设置为UTC，并将页面大小设置为250条记录。

API 使用

edit

可以通过官方的 java.sql 和 javax.sql 包使用JDBC：

java.sql

edit

前者通过 java.sql.Driver 和 DriverManager：

String address = "jdbc:es://" + elasticsearchAddress;     
Properties connectionProperties = connectionProperties(); 
Connection connection =
    DriverManager.getConnection(address, connectionProperties);

Elasticsearch 监听 HTTP 流量的服务器和端口。端口默认为 9200。

连接到 Elasticsearch 的属性。对于未受保护的 Elasticsearch，空的 Properties 实例是可以的。

javax.sql

edit

可通过 javax.sql.DataSource API 访问：

EsDataSource dataSource = new EsDataSource();
String address = "jdbc:es://" + elasticsearchAddress;     
dataSource.setUrl(address);
Properties connectionProperties = connectionProperties(); 
dataSource.setProperties(connectionProperties);
Connection connection = dataSource.getConnection();

Elasticsearch 监听 HTTP 流量的服务器和端口。默认为 9200。

连接到 Elasticsearch 的属性。对于未受保护的 Elasticsearch，空的 Properties 实例是可以的。

使用哪一个？通常，在URL中提供大多数配置属性的客户端应用程序依赖于DriverManager风格，而DataSource在传递时更受欢迎，因为它可以在一个地方进行配置，消费者只需要调用getConnection，而不必担心任何其他属性。

要连接到安全的Elasticsearch服务器，Properties应如下所示：

Properties properties = new Properties();
properties.put("user", "test_admin");
properties.put("password", "x-pack-test-password");

一旦你建立了连接，你可以像使用其他JDBC连接一样使用它。例如：

try (Statement statement = connection.createStatement();
        ResultSet results = statement.executeQuery(
              " SELECT name, page_count"
            + "    FROM library"
            + " ORDER BY page_count DESC"
            + " LIMIT 1")) {
    assertTrue(results.next());
    assertEquals("Don Quixote", results.getString(1));
    assertEquals(1072, results.getInt(2));
    SQLException e = expectThrows(SQLException.class, () ->
        results.getInt(1));
    assertThat(e.getMessage(), containsString("Unable to convert "
            + "value [Don Quixote] of type [TEXT] to [Integer]"));
    assertFalse(results.next());
}

Elasticsearch SQL 不提供连接池机制，因此 JDBC 驱动程序创建的连接不会被池化。为了实现池化连接，需要第三方连接池机制。配置和设置第三方提供程序不在本文档的范围内。

« SQL CLI SQL ODBC »