OpenSearch/docs/java-api/index.asciidoc

149 lines
4.8 KiB
Plaintext
Raw Normal View History

= Java API
include::../Versions.asciidoc[]
[[java-api]]
[preface]
== Preface
deprecated[7.0.0, The `TransportClient` is deprecated in favour of the {java-rest}/java-rest-high.html[Java High Level REST Client] and will be removed in Elasticsearch 8.0. The {java-rest}/java-rest-high-level-migration.html[migration guide] describes all the steps needed to migrate.]
This section describes the Java API that Elasticsearch provides. All
Elasticsearch operations are executed using a
<<client,Client>> object. All
operations are completely asynchronous in nature (either accepts a
listener, or returns a future).
Additionally, operations on a client may be accumulated and executed in
[doc] Reorganize and clean Java documentation This commit reorganizes the docs to make Java API docs looking more like the REST docs. Also, with 2.0.0, FilterBuilders don't exist anymore but only QueryBuilders. Also, all docs api move now to docs/java-api/docs dir as for REST doc. Remove removed queries/filters ----- * Remove Constant Score Query with filter * Remove Fuzzy Like This (Field) Query (flt and flt_field) * Remove FilterBuilders Move filters to queries ----- * Move And Filter to And Query * Move Bool Filter to Bool Query * Move Exists Filter to Exists Query * Move Geo Bounding Box Filter to Geo Bounding Box Query * Move Geo Distance Filter to Geo Distance Query * Move Geo Distance Range Filter to Geo Distance Range Query * Move Geo Polygon Filter to Geo Polygon Query * Move Geo Shape Filter to Geo Shape Query * Move Has Child Filter by Has Child Query * Move Has Parent Filter by Has Parent Query * Move Ids Filter by Ids Query * Move Limit Filter to Limit Query * Move MatchAll Filter to MatchAll Query * Move Missing Filter to Missing Query * Move Nested Filter to Nested Query * Move Not Filter to Not Query * Move Or Filter to Or Query * Move Range Filter to Range Query * Move Ids Filter to Ids Query * Move Term Filter to Term Query * Move Terms Filter to Terms Query * Move Type Filter to Type Query Add missing queries ----- * Add Common Terms Query * Add Filtered Query * Add Function Score Query * Add Geohash Cell Query * Add Regexp Query * Add Script Query * Add Simple Query String Query * Add Span Containing Query * Add Span Multi Term Query * Add Span Within Query Reorganize the documentation ----- * Organize by full text queries * Organize by term level queries * Organize by compound queries * Organize by joining queries * Organize by geo queries * Organize by specialized queries * Organize by span queries * Move Boosting Query * Move DisMax Query * Move Fuzzy Query * Move Indices Query * Move Match Query * Move Mlt Query * Move Multi Match Query * Move Prefix Query * Move Query String Query * Move Span First Query * Move Span Near Query * Move Span Not Query * Move Span Or Query * Move Span Term Query * Move Template Query * Move Wildcard Query Add some missing pages ---- * Add multi get API * Add indexed-scripts link Also closes #7826 Related to https://github.com/elastic/elasticsearch/pull/11477#issuecomment-114745934
2015-06-24 17:27:19 -04:00
<<java-docs-bulk,Bulk>>.
Note, all the APIs are exposed through the
Java API (actually, the Java API is used internally to execute them).
== Javadoc
The javadoc for the transport client can be found at {transport-client-javadoc}/index.html.
== Maven Repository
Elasticsearch is hosted on
http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.elasticsearch.client%22[Maven
Central].
For example, you can define the latest version in your `pom.xml` file:
["source","xml",subs="attributes"]
--------------------------------------------------
<dependency>
<groupId>org.elasticsearch.client</groupId>
<artifactId>transport</artifactId>
<version>{version}</version>
</dependency>
--------------------------------------------------
Document how to import Lucene Snapshot libs when elasticsearch clients (#26113) When using the High Level Rest Client 6.0.0-beta1, we are missing some transitive dependencies for Lucene as Lucene 7 has not been released yet. See the following `pom.xml`: ```xml <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-client</artifactId> <version>6.0.0-beta1</version> </dependency> <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>6.0.0-beta1</version> </dependency> ``` It gives: ``` [ERROR] Failed to execute goal on project fscrawler: Could not resolve dependencies for project fr.pilato.elasticsearch.crawler:fscrawler:jar:2.4-SNAPSHOT: The following artifacts could not be resolved: org.apache.lucene:lucene-analyzers-common:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-backward-codecs:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-grouping:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-highlighter:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-join:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-memory:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-misc:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-queries:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-queryparser:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-sandbox:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial-extras:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial3d:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-suggest:jar:7.0.0-snapshot-00142c9: Failure to find org.apache.lucene:lucene-analyzers-common:jar:7.0.0-snapshot-00142c9 in https://artifacts.elastic.co/maven/ was cached in the local repository, resolution will not be reattempted until the update interval of elastic-download-service has elapsed or updates are forced - ``` We need to add some temporary documentation on how to add the missing repository to a gradle or maven project: ```xml <repository> <id>elastic-lucene-snapshots</id> <name>Elastic Lucene Snapshots</name> <url>http://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>false</enabled></snapshots> </repository> ``` This also applies to the transport client. Closes #26106.
2017-08-10 08:54:07 -04:00
[[java-transport-usage-maven-lucene]]
=== Lucene Snapshot repository
Document how to import Lucene Snapshot libs when elasticsearch clients (#26113) When using the High Level Rest Client 6.0.0-beta1, we are missing some transitive dependencies for Lucene as Lucene 7 has not been released yet. See the following `pom.xml`: ```xml <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-client</artifactId> <version>6.0.0-beta1</version> </dependency> <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>6.0.0-beta1</version> </dependency> ``` It gives: ``` [ERROR] Failed to execute goal on project fscrawler: Could not resolve dependencies for project fr.pilato.elasticsearch.crawler:fscrawler:jar:2.4-SNAPSHOT: The following artifacts could not be resolved: org.apache.lucene:lucene-analyzers-common:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-backward-codecs:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-grouping:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-highlighter:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-join:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-memory:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-misc:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-queries:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-queryparser:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-sandbox:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial-extras:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial3d:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-suggest:jar:7.0.0-snapshot-00142c9: Failure to find org.apache.lucene:lucene-analyzers-common:jar:7.0.0-snapshot-00142c9 in https://artifacts.elastic.co/maven/ was cached in the local repository, resolution will not be reattempted until the update interval of elastic-download-service has elapsed or updates are forced - ``` We need to add some temporary documentation on how to add the missing repository to a gradle or maven project: ```xml <repository> <id>elastic-lucene-snapshots</id> <name>Elastic Lucene Snapshots</name> <url>http://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>false</enabled></snapshots> </repository> ``` This also applies to the transport client. Closes #26106.
2017-08-10 08:54:07 -04:00
The very first releases of any major version (like a beta), might have been built on top of a Lucene Snapshot version.
In such a case you will be unable to resolve the Lucene dependencies of the client.
For example, if you want to use the `6.0.0-beta1` version which depends on Lucene `7.0.0-snapshot-00142c9`, you must
define the following repository.
For Maven:
["source","xml",subs="attributes"]
--------------------------------------------------
<repository>
<id>elastic-lucene-snapshots</id>
<name>Elastic Lucene Snapshots</name>
<url>https://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9</url>
Document how to import Lucene Snapshot libs when elasticsearch clients (#26113) When using the High Level Rest Client 6.0.0-beta1, we are missing some transitive dependencies for Lucene as Lucene 7 has not been released yet. See the following `pom.xml`: ```xml <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-client</artifactId> <version>6.0.0-beta1</version> </dependency> <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>6.0.0-beta1</version> </dependency> ``` It gives: ``` [ERROR] Failed to execute goal on project fscrawler: Could not resolve dependencies for project fr.pilato.elasticsearch.crawler:fscrawler:jar:2.4-SNAPSHOT: The following artifacts could not be resolved: org.apache.lucene:lucene-analyzers-common:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-backward-codecs:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-grouping:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-highlighter:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-join:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-memory:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-misc:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-queries:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-queryparser:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-sandbox:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial-extras:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial3d:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-suggest:jar:7.0.0-snapshot-00142c9: Failure to find org.apache.lucene:lucene-analyzers-common:jar:7.0.0-snapshot-00142c9 in https://artifacts.elastic.co/maven/ was cached in the local repository, resolution will not be reattempted until the update interval of elastic-download-service has elapsed or updates are forced - ``` We need to add some temporary documentation on how to add the missing repository to a gradle or maven project: ```xml <repository> <id>elastic-lucene-snapshots</id> <name>Elastic Lucene Snapshots</name> <url>http://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>false</enabled></snapshots> </repository> ``` This also applies to the transport client. Closes #26106.
2017-08-10 08:54:07 -04:00
<releases><enabled>true</enabled></releases>
<snapshots><enabled>false</enabled></snapshots>
</repository>
--------------------------------------------------
For Gradle:
["source","groovy",subs="attributes"]
--------------------------------------------------
maven {
url 'https://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9'
Document how to import Lucene Snapshot libs when elasticsearch clients (#26113) When using the High Level Rest Client 6.0.0-beta1, we are missing some transitive dependencies for Lucene as Lucene 7 has not been released yet. See the following `pom.xml`: ```xml <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-client</artifactId> <version>6.0.0-beta1</version> </dependency> <dependency> <groupId>org.elasticsearch.client</groupId> <artifactId>elasticsearch-rest-high-level-client</artifactId> <version>6.0.0-beta1</version> </dependency> ``` It gives: ``` [ERROR] Failed to execute goal on project fscrawler: Could not resolve dependencies for project fr.pilato.elasticsearch.crawler:fscrawler:jar:2.4-SNAPSHOT: The following artifacts could not be resolved: org.apache.lucene:lucene-analyzers-common:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-backward-codecs:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-grouping:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-highlighter:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-join:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-memory:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-misc:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-queries:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-queryparser:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-sandbox:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial-extras:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-spatial3d:jar:7.0.0-snapshot-00142c9, org.apache.lucene:lucene-suggest:jar:7.0.0-snapshot-00142c9: Failure to find org.apache.lucene:lucene-analyzers-common:jar:7.0.0-snapshot-00142c9 in https://artifacts.elastic.co/maven/ was cached in the local repository, resolution will not be reattempted until the update interval of elastic-download-service has elapsed or updates are forced - ``` We need to add some temporary documentation on how to add the missing repository to a gradle or maven project: ```xml <repository> <id>elastic-lucene-snapshots</id> <name>Elastic Lucene Snapshots</name> <url>http://s3.amazonaws.com/download.elasticsearch.org/lucenesnapshots/00142c9</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>false</enabled></snapshots> </repository> ``` This also applies to the transport client. Closes #26106.
2017-08-10 08:54:07 -04:00
}
--------------------------------------------------
=== Log4j 2 Logger
You need to also include Log4j 2 dependencies:
["source","xml",subs="attributes"]
--------------------------------------------------
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-core</artifactId>
<version>2.11.1</version>
</dependency>
--------------------------------------------------
And also provide a Log4j 2 configuration file in your classpath.
For example, you can add in your `src/main/resources` project dir a `log4j2.properties` file like:
["source","properties",subs="attributes"]
--------------------------------------------------
appender.console.type = Console
appender.console.name = console
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = [%d{ISO8601}][%-5p][%-25c] %marker%m%n
rootLogger.level = info
rootLogger.appenderRef.console.ref = console
--------------------------------------------------
=== Using another Logger
If you want to use another logger than Log4j 2, you can use http://www.slf4j.org/[SLF4J] bridge to do that:
["source","xml",subs="attributes"]
--------------------------------------------------
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-to-slf4j</artifactId>
<version>2.11.1</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>1.7.24</version>
</dependency>
--------------------------------------------------
http://www.slf4j.org/manual.html[This page] lists implementations you can use. Pick your favorite logger
and add it as a dependency. As an example, we will use the `slf4j-simple` logger:
["source","xml",subs="attributes"]
--------------------------------------------------
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>1.7.21</version>
</dependency>
--------------------------------------------------
:client-tests: {docdir}/../../server/src/test/java/org/elasticsearch/client/documentation
:hlrc-tests: {docdir}/../../client/rest-high-level/src/test/java/org/elasticsearch/client
:client-reindex-tests: {docdir}/../../modules/reindex/src/test/java/org/elasticsearch/client/documentation
include::client.asciidoc[]
[doc] Reorganize and clean Java documentation This commit reorganizes the docs to make Java API docs looking more like the REST docs. Also, with 2.0.0, FilterBuilders don't exist anymore but only QueryBuilders. Also, all docs api move now to docs/java-api/docs dir as for REST doc. Remove removed queries/filters ----- * Remove Constant Score Query with filter * Remove Fuzzy Like This (Field) Query (flt and flt_field) * Remove FilterBuilders Move filters to queries ----- * Move And Filter to And Query * Move Bool Filter to Bool Query * Move Exists Filter to Exists Query * Move Geo Bounding Box Filter to Geo Bounding Box Query * Move Geo Distance Filter to Geo Distance Query * Move Geo Distance Range Filter to Geo Distance Range Query * Move Geo Polygon Filter to Geo Polygon Query * Move Geo Shape Filter to Geo Shape Query * Move Has Child Filter by Has Child Query * Move Has Parent Filter by Has Parent Query * Move Ids Filter by Ids Query * Move Limit Filter to Limit Query * Move MatchAll Filter to MatchAll Query * Move Missing Filter to Missing Query * Move Nested Filter to Nested Query * Move Not Filter to Not Query * Move Or Filter to Or Query * Move Range Filter to Range Query * Move Ids Filter to Ids Query * Move Term Filter to Term Query * Move Terms Filter to Terms Query * Move Type Filter to Type Query Add missing queries ----- * Add Common Terms Query * Add Filtered Query * Add Function Score Query * Add Geohash Cell Query * Add Regexp Query * Add Script Query * Add Simple Query String Query * Add Span Containing Query * Add Span Multi Term Query * Add Span Within Query Reorganize the documentation ----- * Organize by full text queries * Organize by term level queries * Organize by compound queries * Organize by joining queries * Organize by geo queries * Organize by specialized queries * Organize by span queries * Move Boosting Query * Move DisMax Query * Move Fuzzy Query * Move Indices Query * Move Match Query * Move Mlt Query * Move Multi Match Query * Move Prefix Query * Move Query String Query * Move Span First Query * Move Span Near Query * Move Span Not Query * Move Span Or Query * Move Span Term Query * Move Template Query * Move Wildcard Query Add some missing pages ---- * Add multi get API * Add indexed-scripts link Also closes #7826 Related to https://github.com/elastic/elasticsearch/pull/11477#issuecomment-114745934
2015-06-24 17:27:19 -04:00
include::docs.asciidoc[]
include::search.asciidoc[]
include::aggs.asciidoc[]
[doc] Reorganize and clean Java documentation This commit reorganizes the docs to make Java API docs looking more like the REST docs. Also, with 2.0.0, FilterBuilders don't exist anymore but only QueryBuilders. Also, all docs api move now to docs/java-api/docs dir as for REST doc. Remove removed queries/filters ----- * Remove Constant Score Query with filter * Remove Fuzzy Like This (Field) Query (flt and flt_field) * Remove FilterBuilders Move filters to queries ----- * Move And Filter to And Query * Move Bool Filter to Bool Query * Move Exists Filter to Exists Query * Move Geo Bounding Box Filter to Geo Bounding Box Query * Move Geo Distance Filter to Geo Distance Query * Move Geo Distance Range Filter to Geo Distance Range Query * Move Geo Polygon Filter to Geo Polygon Query * Move Geo Shape Filter to Geo Shape Query * Move Has Child Filter by Has Child Query * Move Has Parent Filter by Has Parent Query * Move Ids Filter by Ids Query * Move Limit Filter to Limit Query * Move MatchAll Filter to MatchAll Query * Move Missing Filter to Missing Query * Move Nested Filter to Nested Query * Move Not Filter to Not Query * Move Or Filter to Or Query * Move Range Filter to Range Query * Move Ids Filter to Ids Query * Move Term Filter to Term Query * Move Terms Filter to Terms Query * Move Type Filter to Type Query Add missing queries ----- * Add Common Terms Query * Add Filtered Query * Add Function Score Query * Add Geohash Cell Query * Add Regexp Query * Add Script Query * Add Simple Query String Query * Add Span Containing Query * Add Span Multi Term Query * Add Span Within Query Reorganize the documentation ----- * Organize by full text queries * Organize by term level queries * Organize by compound queries * Organize by joining queries * Organize by geo queries * Organize by specialized queries * Organize by span queries * Move Boosting Query * Move DisMax Query * Move Fuzzy Query * Move Indices Query * Move Match Query * Move Mlt Query * Move Multi Match Query * Move Prefix Query * Move Query String Query * Move Span First Query * Move Span Near Query * Move Span Not Query * Move Span Or Query * Move Span Term Query * Move Template Query * Move Wildcard Query Add some missing pages ---- * Add multi get API * Add indexed-scripts link Also closes #7826 Related to https://github.com/elastic/elasticsearch/pull/11477#issuecomment-114745934
2015-06-24 17:27:19 -04:00
include::query-dsl.asciidoc[]
include::admin/index.asciidoc[]