› ›

SQL JDBC

Драйвер Elasticsearch SQL jdbc — это расширенный, полнофункциональный JDBC-драйвер для Elasticsearch. Это драйвер типа 4, то есть это независимый от платформы, автономный, прямой доступ к базе данных, чисто Java-драйвер, который преобразует вызовы JDBC в Elasticsearch SQL.

Установка

Драйвер JDBC можно получить из:

Специальная страница: elastic.co предоставляет ссылки, как правило, для ручной загрузки.
Зависимость Maven: Совместимые с Maven инструменты могут автоматически извлекать его как зависимость:

<dependency>
  <groupId>org.elasticsearch.plugin</groupId>
  <artifactId>x-pack-sql-jdbc</artifactId>
  <version>8.17.3</version>
</dependency>

из Центрального репозитория Maven, или из artifacts.elastic.co/maven, добавив его в список репозиториев:

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

Совместимость версий

Ваш драйвер должен быть совместим с вашей версией Elasticsearch.

Версия драйвера не может быть новее, чем версия Elasticsearch. Например, версия Elasticsearch 7.10.0 несовместима с драйверами 8.17.3.

Версия Elasticsearch	Совместимые версии драйверов	Пример
8.0.0–8.17.3	Та же версия Любая более ранняя версия 8.x Любая версия 7.x после 7.7.0.	Elasticsearch 8.17.3 совместим с драйверами 8.17.3 и более ранними версиями 8.x. Elasticsearch 8.17.3 также совместим с драйверами 7.7.0 и более поздними версиями 7.x.
7.7.1-7.17	Та же версия Более ранняя версия 7.x, начиная с 7.7.0.	Elasticsearch 7.10.0 совместим с драйверами 7.7.0-7.10.0.
7.7.0 и более ранние версии	Та же версия.	Elasticsearch 7.6.1 совместим только с драйверами 7.6.1.

Настройка

Главный класс драйвера — org.elasticsearch.xpack.sql.jdbc.EsDriver. Обратите внимание, что драйвер реализует механизм JDBC 4.0 Service Provider, что означает, что он регистрируется автоматически, если доступен в classpath.

После регистрации драйвер понимает следующий синтаксис в качестве 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. Пусто по умолчанию. Необязательно.

Драйвер распознает следующие свойства:

Основные

timezone (временная зона JVM по умолчанию): Временная зона, используемая драйвером для каждого соединения, указывается его ID. Настоятельно рекомендуется установить её (например, на UTC), так как временная зона JVM может меняться, является глобальной для всей JVM и её нелегко изменить при работе под управлением диспетчера безопасности.

Сеть

connect.timeout (по умолчанию 30000): Тайм-аут соединения (в миллисекундах). Это максимальное время ожидания для установления соединения с сервером.
network.timeout (по умолчанию 60000): Сетевой тайм-аут (в миллисекундах). Это максимальное время ожидания сети.
page.size (по умолчанию 1000): Размер страницы (в записях). Количество результатов, возвращаемых сервером на каждой странице.
page.timeout (по умолчанию 45000): Тайм-аут страницы (в миллисекундах). Минимальный период хранения для курсора прокрутки на сервере. Запросы, требующие курсора прокрутки с состоянием на стороне сервера, могут завершиться ошибкой после этого тайм-аута. Поэтому при прокрутке больших наборов результатов обработка page.size записей не должна занимать более page.timeout миллисекунд.
query.timeout (по умолчанию 90000): Тайм-аут запроса (в миллисекундах). Это максимальное время ожидания возврата запроса.

Базовая аутентификация

user: Имя пользователя для базовой аутентификации
password: Пароль для базовой аутентификации

SSL

ssl (по умолчанию false): Включить SSL
ssl.keystore.location: Расположение хранилища ключей (если используется)
ssl.keystore.pass: Пароль хранилища ключей
ssl.keystore.type (по умолчанию JKS): Тип хранилища ключей. PKCS12 — распространенный альтернативный формат
ssl.truststore.location: Расположение хранилища доверия
ssl.truststore.pass: Пароль хранилища доверия
ssl.truststore.type (по умолчанию JKS): Тип хранилища доверия. PKCS12 — распространенный альтернативный формат
ssl.protocol(по умолчанию TLS): Используемый протокол SSL

Прокси

proxy.http: Имя хоста прокси-сервера HTTP
proxy.socks: Имя хоста прокси-сервера SOCKS

Сопоставление

field.multi.value.leniency (по умолчанию true): Следует ли быть снисходительным и возвращать первое значение (без каких-либо гарантий того, каким оно будет — обычно первое в естественном порядке возрастания) для полей с несколькими значениями (true) или вызывать исключение.

Индекс

index.include.frozen (по умолчанию false): Следует ли включать замороженные индексы в выполнение запроса или нет (по умолчанию).

Кластер

catalog

Каталог (кластер) по умолчанию для запросов. Если не указано, запросы выполняются только для данных в локальном кластере.

[предварительный просмотр] Эта функция находится в стадии технического предварительного просмотра и может быть изменена или удалена в будущих выпусках. Elastic будет работать над исправлением любых проблем, но функции в техническом предварительном просмотре не подпадают под действие соглашения об уровне обслуживания официальных функций GA. См. поиск по кластерам.

Обработка ошибок

allow.partial.search.results (по умолчанию false): Возвращать ли частичные результаты в случае сбоя шарда или завершать запрос с ошибкой, вызывая основное исключение (по умолчанию).

Устранение неполадок

debug (по умолчанию false): Установка его в true включит отладочное журналирование.
debug.output (по умолчанию err): Назначение отладочных журналов. По умолчанию они отправляются в стандартный поток ошибок. Значение out перенаправит журналирование в стандартный поток вывода. Можно также указать путь к файлу.

Дополнительные параметры

validate.properties (по умолчанию true): Если отключено, будут игнорироваться любые ошибки орфографии или нераспознанные свойства. Если включено, будет выброшено исключение, если предоставленное свойство не может быть распознано.

В итоге, следующий URL:

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

открывает соединение Elasticsearch SQL с server на порту 3456, устанавливая временную зону соединения JDBC в UTC и размер страницы в 250 записей.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/sql-jdbc.html