SQL JDBC
editSQL JDBC
editElasticsearch’s SQL jdbc driver is a rich, fully featured JDBC driver for Elasticsearch. It is Type 4 driver, meaning it is a platform independent, stand-alone, Direct to Database, pure Java driver that converts JDBC calls to Elasticsearch SQL.
Installation
editThe JDBC driver can be obtained from:
- Dedicated page
- elastic.co provides links, typically for manual downloads.
- Maven dependency
- Maven-compatible tools can retrieve it automatically as a dependency:
<dependency> <groupId>org.elasticsearch.plugin</groupId> <artifactId>x-pack-sql-jdbc</artifactId> <version>8.15.2</version> </dependency>
from Maven Central Repository,
or from artifacts.elastic.co/maven
by adding it to the repositories list:
<repositories> <repository> <id>elastic.co</id> <url>https://artifacts.elastic.co/maven</url> </repository> </repositories>
Version compatibility
editYour driver must be compatible with your Elasticsearch version.
The driver version cannot be newer than the Elasticsearch version. For example, Elasticsearch version 7.10.0 is not compatible with 8.15.2 drivers.
Elasticsearch version | Compatible driver versions | Example |
---|---|---|
8.0.0–8.15.2 |
|
Elasticsearch 8.15.2 is compatible with 8.15.2 and earlier 8.x drivers. Elasticsearch 8.15.2 is also compatible with 7.7.0 and later 7.x drivers. |
7.7.1-7.17 |
|
Elasticsearch 7.10.0 is compatible with 7.7.0-7.10.0 drivers. |
7.7.0 and earlier versions |
|
Elasticsearch 7.6.1 is only compatible with 7.6.1 drivers. |
Setup
editThe driver main class is org.elasticsearch.xpack.sql.jdbc.EsDriver
.
Note the driver implements the JDBC 4.0 Service Provider
mechanism meaning it is registered automatically
as long as it is available in the classpath.
Once registered, the driver understands the following syntax as an URL:
jdbc:[es|elasticsearch]://[[http|https]://]?[host[:port]]?/[prefix]?[\?[option=value]&]*
-
jdbc:[es|elasticsearch]://
- Prefix. Mandatory.
-
[[http|https]://]
-
Type of HTTP connection to make. Possible values are
http
(default) orhttps
. Optional. -
[host[:port]]
-
Host (
localhost
by default) and port (9200
by default). Optional. -
[prefix]
- Prefix (empty by default). Typically used when hosting Elasticsearch under a certain path. Optional.
-
[option=value]
- Properties for the JDBC driver. Empty by default. Optional.
The driver recognized the following properties:
Essential
edit-
timezone
(default JVM timezone) -
Timezone used by the driver per connection indicated by its
ID
. Highly recommended to set it (to, say,UTC
) as the JVM timezone can vary, is global for the entire JVM and can’t be changed easily when running under a security manager.
Network
edit-
connect.timeout
(default30000
) - Connection timeout (in milliseconds). That is the maximum amount of time waiting to make a connection to the server.
-
network.timeout
(default60000
) - Network timeout (in milliseconds). That is the maximum amount of time waiting for the network.
-
page.size
(default1000
) - Page size (in entries). The number of results returned per page by the server.
-
page.timeout
(default45000
) -
Page timeout (in milliseconds). Minimum retention period for the scroll cursor on the server. Queries that require
a stateful scroll cursor on the server side might fail after this timeout. Hence, when scrolling through large result sets,
processing
page.size
records should not take longer thanpage.timeout
milliseconds. -
query.timeout
(default90000
) - Query timeout (in milliseconds). That is the maximum amount of time waiting for a query to return.
Basic Authentication
edit-
user
- Basic Authentication user name
-
password
- Basic Authentication password
SSL
edit-
ssl
(defaultfalse
) - Enable SSL
-
ssl.keystore.location
- key store (if used) location
-
ssl.keystore.pass
- key store password
-
ssl.keystore.type
(defaultJKS
) -
key store type.
PKCS12
is a common, alternative format -
ssl.truststore.location
- trust store location
-
ssl.truststore.pass
- trust store password
-
ssl.truststore.type
(defaultJKS
) -
trust store type.
PKCS12
is a common, alternative format -
ssl.protocol
(defaultTLS
) - SSL protocol to be used
Proxy
edit-
proxy.http
- Http proxy host name
-
proxy.socks
- SOCKS proxy host name
Mapping
edit-
field.multi.value.leniency
(defaulttrue
) - Whether to be lenient and return the first value (without any guarantees of what that will be - typically the first in natural ascending order) for fields with multiple values (true) or throw an exception.
Index
edit-
index.include.frozen
(defaultfalse
) - Whether to include frozen indices in the query execution or not (default).
Cluster
edit-
catalog
-
Default catalog (cluster) for queries. If unspecified, the queries execute on the data in the local cluster only.
[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. See cross-cluster search.
Error handling
edit-
allow.partial.search.results
(defaultfalse
) - Whether to return partial results in case of shard failure or fail the query throwing the underlying exception (default).
Troubleshooting
edit-
debug
(defaultfalse
) -
Setting it to
true
will enable the debug logging. -
debug.output
(defaulterr
) -
The destination of the debug logs. By default, they are sent to standard error. Value
out
will redirect the logging to standard output. A file path can also be specified.
Additional
edit-
validate.properties
(defaulttrue
) - If disabled, it will ignore any misspellings or unrecognizable properties. When enabled, an exception will be thrown if the provided property cannot be recognized.
To put all of it together, the following URL:
jdbc:es://http://server:3456/?timezone=UTC&page.size=250
opens up a Elasticsearch SQL connection to server
on port 3456
, setting the JDBC connection timezone to UTC
and its pagesize to 250
entries.