mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-26 06:46:10 +00:00
076a68007c
For cases where fields can have multi values, allow the behavior to be customized through a dedicated configuration field. By default this will be enabled on the drivers so that existing datasets work instead of throwing an exception. For regular SQL usage, the behavior is false so that the user is aware of the underlying data. Fix #39700 (cherry picked from commit 2b351571961f172fd59290ee079126bbd081ceaf)
194 lines
6.2 KiB
Plaintext
194 lines
6.2 KiB
Plaintext
[role="xpack"]
|
|
[testenv="platinum"]
|
|
[[sql-jdbc]]
|
|
== SQL JDBC
|
|
|
|
{es}'s SQL jdbc driver is a rich, fully featured JDBC driver for {es}.
|
|
It is Type 4 driver, meaning it is a platform independent, stand-alone, Direct to Database,
|
|
pure Java driver that converts JDBC calls to {es-sql}.
|
|
|
|
[[sql-jdbc-installation]]
|
|
[float]
|
|
=== Installation
|
|
|
|
The JDBC driver can be obtained from:
|
|
|
|
Dedicated page::
|
|
https://www.elastic.co/downloads/jdbc-client[elastic.co] provides links, typically for manual downloads.
|
|
Maven dependency::
|
|
http://maven.apache.org/[Maven]-compatible tools can retrieve it automatically as a dependency:
|
|
|
|
["source","xml",subs="attributes"]
|
|
----
|
|
<dependency>
|
|
<groupId>org.elasticsearch.plugin</groupId>
|
|
<artifactId>x-pack-sql-jdbc</artifactId>
|
|
<version>{version}</version>
|
|
</dependency>
|
|
----
|
|
|
|
from `artifacts.elastic.co/maven` by adding it to the repositories list:
|
|
|
|
["source","xml",subs="attributes"]
|
|
----
|
|
<repositories>
|
|
<repository>
|
|
<id>elastic.co</id>
|
|
<url>https://artifacts.elastic.co/maven</url>
|
|
</repository>
|
|
</repositories>
|
|
----
|
|
|
|
[[jdbc-setup]]
|
|
[float]
|
|
=== Setup
|
|
|
|
The 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:
|
|
|
|
["source","text",subs="attributes"]
|
|
----
|
|
jdbc:es://<1>[[http|https]://]*<2>[host[:port]]*<3>/[prefix]*<4>[?[option=value]&<5>]*
|
|
----
|
|
|
|
<1> `jdbc:es://` prefix. Mandatory.
|
|
<2> type of HTTP connection to make - `http` (default) or `https`. Optional.
|
|
<3> host (`localhost` by default) and port (`9200` by default). Optional.
|
|
<4> prefix (empty by default). Typically used when hosting {es} under a certain path. Optional.
|
|
<5> Properties for the JDBC driver. Empty by default. Optional.
|
|
|
|
The driver recognized the following properties:
|
|
|
|
[[jdbc-cfg]]
|
|
[float]
|
|
===== Essential
|
|
|
|
`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.
|
|
|
|
[[jdbc-cfg-network]]
|
|
[float]
|
|
===== Network
|
|
|
|
`connect.timeout` (default 30s)::
|
|
Connection timeout (in seconds). That is the maximum amount of time waiting to make a connection to the server.
|
|
|
|
`network.timeout` (default 60s)::
|
|
Network timeout (in seconds). That is the maximum amount of time waiting for the network.
|
|
|
|
`page.timeout` (default 45s)::
|
|
Page timeout (in seconds). That is the maximum amount of time waiting for a page.
|
|
|
|
`page.size` (default 1000)::
|
|
Page size (in entries). The number of results returned per page by the server.
|
|
|
|
`query.timeout` (default 90s)::
|
|
Query timeout (in seconds). That is the maximum amount of time waiting for a query to return.
|
|
|
|
[[jdbc-cfg-auth]]
|
|
[float]
|
|
==== Basic Authentication
|
|
|
|
`user`:: Basic Authentication user name
|
|
|
|
`password`:: Basic Authentication password
|
|
|
|
[[jdbc-cfg-ssl]]
|
|
[float]
|
|
==== SSL
|
|
|
|
`ssl` (default false):: Enable SSL
|
|
|
|
`ssl.keystore.location`:: key store (if used) location
|
|
|
|
`ssl.keystore.pass`:: key store password
|
|
|
|
`ssl.keystore.type` (default `JKS`):: key store type. `PKCS12` is a common, alternative format
|
|
|
|
`ssl.truststore.location`:: trust store location
|
|
|
|
`ssl.truststore.pass`:: trust store password
|
|
|
|
`ssl.protocol`(default `TLS`):: SSL protocol to be used
|
|
|
|
[float]
|
|
==== Proxy
|
|
|
|
`proxy.http`:: Http proxy host name
|
|
|
|
`proxy.socks`:: SOCKS proxy host name
|
|
|
|
[float]
|
|
==== Mapping
|
|
`field.multi.value.leniency` (default `true`):: Whether to be lenient and return the first value for fields with multiple values (true) or throw an exception.
|
|
|
|
[float]
|
|
==== Additional
|
|
|
|
`validate.properties` (default true):: 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:
|
|
|
|
["source","text"]
|
|
----
|
|
jdbc:es://http://server:3456/?timezone=UTC&page.size=250
|
|
----
|
|
|
|
Opens up a {es-sql} connection to `server` on port `3456`, setting the JDBC connection timezone to `UTC` and its pagesize to `250` entries.
|
|
|
|
=== API usage
|
|
|
|
One can use JDBC through the official `java.sql` and `javax.sql` packages:
|
|
|
|
==== `java.sql`
|
|
The former through `java.sql.Driver` and `DriverManager`:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{jdbc-tests}/JdbcIntegrationTestCase.java[connect-dm]
|
|
--------------------------------------------------
|
|
<1> The server and port on which Elasticsearch is listening for
|
|
HTTP traffic. The port is by default 9200.
|
|
<2> Properties for connecting to Elasticsearch. An empty `Properties`
|
|
instance is fine for unsecured Elasticsearch.
|
|
|
|
==== `javax.sql`
|
|
|
|
Accessible through the `javax.sql.DataSource` API:
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{jdbc-tests}/JdbcIntegrationTestCase.java[connect-ds]
|
|
--------------------------------------------------
|
|
<1> The server and port on which Elasticsearch is listening for
|
|
HTTP traffic. By default 9200.
|
|
<2> Properties for connecting to Elasticsearch. An empty `Properties`
|
|
instance is fine for unsecured Elasticsearch.
|
|
|
|
Which one to use? Typically client applications that provide most
|
|
configuration properties in the URL rely on the `DriverManager`-style
|
|
while `DataSource` is preferred when being _passed_ around since it can be
|
|
configured in one place and the consumer only has to call `getConnection`
|
|
without having to worry about any other properties.
|
|
|
|
To connect to a secured Elasticsearch server the `Properties`
|
|
should look like:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{security-tests}/JdbcSecurityIT.java[admin_properties]
|
|
--------------------------------------------------
|
|
|
|
Once you have the connection you can use it like any other JDBC
|
|
connection. For example:
|
|
|
|
["source","java",subs="attributes,callouts,macros"]
|
|
--------------------------------------------------
|
|
include-tagged::{jdbc-tests}/SimpleExampleTestCase.java[simple_example]
|
|
--------------------------------------------------
|