|
| 1 | +--- |
| 2 | +mapped_pages: |
| 3 | + - https://www.elastic.co/guide/en/elasticsearch/reference/current/_api_usage.html |
| 4 | +applies_to: |
| 5 | + stack: ga |
| 6 | + serverless: ga |
| 7 | +products: |
| 8 | + - id: elasticsearch |
| 9 | +--- |
| 10 | + |
| 11 | +# API usage [_api_usage] |
| 12 | + |
| 13 | +One can use JDBC through the official `java.sql` and `javax.sql` packages: |
| 14 | + |
| 15 | +## `java.sql` [java-sql] |
| 16 | + |
| 17 | +The former through `java.sql.Driver` and `DriverManager`: |
| 18 | + |
| 19 | +```java |
| 20 | +String address = "jdbc:es://" + elasticsearchAddress; <1> |
| 21 | +Properties connectionProperties = connectionProperties(); <2> |
| 22 | +Connection connection = |
| 23 | + DriverManager.getConnection(address, connectionProperties); |
| 24 | +``` |
| 25 | + |
| 26 | +1. The server and port on which Elasticsearch is listening for HTTP traffic. The port is by default 9200. |
| 27 | +2. Properties for connecting to Elasticsearch. An empty `Properties` instance is fine for unsecured Elasticsearch. |
| 28 | + |
| 29 | + |
| 30 | + |
| 31 | +## `javax.sql` [javax-sql] |
| 32 | + |
| 33 | +Accessible through the `javax.sql.DataSource` API: |
| 34 | + |
| 35 | +```java |
| 36 | +EsDataSource dataSource = new EsDataSource(); |
| 37 | +String address = "jdbc:es://" + elasticsearchAddress; <1> |
| 38 | +dataSource.setUrl(address); |
| 39 | +Properties connectionProperties = connectionProperties(); <2> |
| 40 | +dataSource.setProperties(connectionProperties); |
| 41 | +Connection connection = dataSource.getConnection(); |
| 42 | +``` |
| 43 | + |
| 44 | +1. The server and port on which Elasticsearch is listening for HTTP traffic. By default 9200. |
| 45 | +2. Properties for connecting to Elasticsearch. An empty `Properties` instance is fine for unsecured Elasticsearch. |
| 46 | + |
| 47 | + |
| 48 | +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. |
| 49 | + |
| 50 | +To connect to a secured Elasticsearch server the `Properties` should look like: |
| 51 | + |
| 52 | +```java |
| 53 | +Properties properties = new Properties(); |
| 54 | +properties.put("user", "test_admin"); |
| 55 | +properties.put("password", "x-pack-test-password"); |
| 56 | +``` |
| 57 | + |
| 58 | +Once you have the connection you can use it like any other JDBC connection. For example: |
| 59 | + |
| 60 | +```java |
| 61 | +try (Statement statement = connection.createStatement(); |
| 62 | + ResultSet results = statement.executeQuery( |
| 63 | + " SELECT name, page_count" |
| 64 | + + " FROM library" |
| 65 | + + " ORDER BY page_count DESC" |
| 66 | + + " LIMIT 1")) { |
| 67 | + assertTrue(results.next()); |
| 68 | + assertEquals("Don Quixote", results.getString(1)); |
| 69 | + assertEquals(1072, results.getInt(2)); |
| 70 | + SQLException e = expectThrows(SQLException.class, () -> |
| 71 | + results.getInt(1)); |
| 72 | + assertThat(e.getMessage(), containsString("Unable to convert " |
| 73 | + + "value [Don Quixote] of type [TEXT] to [Integer]")); |
| 74 | + assertFalse(results.next()); |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +::::{note} |
| 79 | +Elasticsearch SQL doesn’t provide a connection pooling mechanism, thus the connections the JDBC driver creates are not pooled. In order to achieve pooled connections, a third-party connection pooling mechanism is required. Configuring and setting up the third-party provider is outside the scope of this documentation. |
| 80 | +:::: |
| 81 | + |
| 82 | + |
| 83 | + |
0 commit comments