github-mirrors/elasticsearch
1
0
Fork 0
mirror of https://github.com/elastic/elasticsearch.git synced 2025-06-28 17:34:17 -04:00
Code Issues Projects Releases Packages Wiki Activity

[doc] Reorganize and clean Java documentation

Browse source 
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
This commit is contained in:
David Pilato 2015-06-24 23:27:19 +02:00
parent e429b8d190
commit 1e35674eb0
72 changed files with 1477 additions and 1271 deletions
Download patch file Download diff file Expand all files Collapse all files

15
docs/java-api/query-dsl/and-query.asciidoc Normal file
View file

@ -0,0 +1,15 @@
[[java-query-dsl-and-query]]
==== And Query
deprecated[2.0.0, Use the `bool` query instead]
See {ref}/query-dsl-and-query.html[And Query]
[source,java]
--------------------------------------------------
QueryBuilder query = andQuery(
rangeQuery("postDate").from("2010-03-01").to("2010-04-01"), <1>
prefixQuery("name.second", "ba")); <1>
--------------------------------------------------
<1> queries

18
docs/java-api/query-dsl/bool-query.asciidoc Normal file
View file

@ -0,0 +1,18 @@
[[java-query-dsl-bool-query]]
==== Bool Query
See {ref}/query-dsl-bool-query.html[Bool Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = boolQuery()
.must(termQuery("content", "test1")) <1>
.must(termQuery("content", "test4")) <1>
.mustNot(termQuery("content", "test2")) <2>
.should(termQuery("content", "test3")); <3>
--------------------------------------------------
<1> must query
<2> must not query
<3> should query

16
docs/java-api/query-dsl/boosting-query.asciidoc Normal file
View file

@ -0,0 +1,16 @@
[[java-query-dsl-boosting-query]]
==== Boosting Query
See {ref}/query-dsl-boosting-query.html[Boosting Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = boostingQuery()
.positive(termQuery("name","kimchy")) <1>
.negative(termQuery("name","dadoonet")) <2>
.negativeBoost(0.2f); <3>
--------------------------------------------------
<1> query that will promote documents
<2> query that will demote documents
<3> negative boost

12
docs/java-api/query-dsl/common-terms-query.asciidoc Normal file
View file

@ -0,0 +1,12 @@
[[java-query-dsl-common-terms-query]]
==== Common Terms Query
See {ref}/query-dsl-common-terms-query.html[Common Terms Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = commonTermsQuery("name", <1>
"kimchy"); <2>
--------------------------------------------------
<1> field
<2> value

69
docs/java-api/query-dsl/compound-queries.asciidoc Normal file
View file

@ -0,0 +1,69 @@
[[java-compound-queries]]
=== Compound queries
Compound queries wrap other compound or leaf queries, either to combine their
results and scores, to change their behaviour, or to switch from query to
filter context.
The queries in this group are:
<<java-query-dsl-constant-score-query,`constant_score` query>>::
A query which wraps another query, but executes it in filter context. All
matching documents are given the same ``constant'' `_score`.
<<java-query-dsl-bool-query,`bool` query>>::
The default query for combining multiple leaf or compound query clauses, as
`must`, `should`, `must_not`, or `filter` clauses. The `must` and `should`
clauses have their scores combined -- the more matching clauses, the better --
while the `must_not` and `filter` clauses are executed in filter context.
<<java-query-dsl-dis-max-query,`dis_max` query>>::
A query which accepts multiple queries, and returns any documents which match
any of the query clauses. While the `bool` query combines the scores from all
matching queries, the `dis_max` query uses the score of the single best-
matching query clause.
<<java-query-dsl-function-score-query,`function_score` query>>::
Modify the scores returned by the main query with functions to take into
account factors like popularity, recency, distance, or custom algorithms
implemented with scripting.
<<java-query-dsl-boosting-query,`boosting` query>>::
Return documents which match a `positive` query, but reduce the score of
documents which also match a `negative` query.
<<java-query-dsl-indices-query,`indices` query>>::
Execute one query for the specified indices, and another for other indices.
<<java-query-dsl-and-query,`and`>>, <<java-query-dsl-or-query,`or`>>, <<java-query-dsl-not-query,`not`>>::
Synonyms for the `bool` query.
<<java-query-dsl-filtered-query,`filtered` query>>::
Combine a query clause in query context with another in filter context. deprecated[2.0.0,Use the `bool` query instead]
<<java-query-dsl-limit-query,`limit` query>>::
Limits the number of documents examined per shard. deprecated[1.6.0]
include::constant-score-query.asciidoc[]
include::bool-query.asciidoc[]
include::dis-max-query.asciidoc[]
include::function-score-query.asciidoc[]
include::boosting-query.asciidoc[]
include::indices-query.asciidoc[]
include::and-query.asciidoc[]
include::not-query.asciidoc[]
include::or-query.asciidoc[]
include::filtered-query.asciidoc[]
include::limit-query.asciidoc[]

14
docs/java-api/query-dsl/constant-score-query.asciidoc Normal file
View file

@ -0,0 +1,14 @@
[[java-query-dsl-constant-score-query]]
==== Constant Score Query
See {ref}/query-dsl-constant-score-query.html[Constant Score Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = constantScoreQuery(
termQuery("name","kimchy") <1>
)
.boost(2.0f); <2>
--------------------------------------------------
<1> your query
<2> query score

17
docs/java-api/query-dsl/dis-max-query.asciidoc Normal file
View file

@ -0,0 +1,17 @@
[[java-query-dsl-dis-max-query]]
==== Dis Max Query
See {ref}/query-dsl-dis-max-query.html[Dis Max Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = disMaxQuery()
.add(termQuery("name", "kimchy")) <1>
.add(termQuery("name", "elasticsearch")) <2>
.boost(1.2f) <3>
.tieBreaker(0.7f); <4>
--------------------------------------------------
<1> add your queries
<2> add your queries
<3> boost factor
<4> tie breaker

11
docs/java-api/query-dsl/exists-query.asciidoc Normal file
View file

@ -0,0 +1,11 @@
[[java-query-dsl-exists-query]]
==== Exists Query
See {ref}/query-dsl-exists-query.html[Exists Query].
[source,java]
--------------------------------------------------
QueryBuilder qb = existsQuery("name"); <1>
--------------------------------------------------
<1> field

17
docs/java-api/query-dsl/filtered-query.asciidoc Normal file
View file

@ -0,0 +1,17 @@
[[java-query-dsl-filtered-query]]
==== Filtered Query
deprecated[2.0.0, Use the `bool` query instead with a `must` clause for the query and a `filter` clause for the filter]
See {ref}/query-dsl-filtered-query.html[Filtered Query].
[source,java]
--------------------------------------------------
QueryBuilder qb = filteredQuery(
matchQuery("name", "kimchy"), <1>
rangeQuery("dateOfBirth").from("1900").to("2100") <2>
);
--------------------------------------------------
<1> query which will be used for scoring
<2> query which will only be used for filtering the result set

44
docs/java-api/query-dsl/full-text-queries.asciidoc Normal file
View file

@ -0,0 +1,44 @@
[[java-full-text-queries]]
=== Full text queries
The high-level full text queries are usually used for running full text
queries on full text fields like the body of an email. They understand how the
field being queried is analyzed and will apply each field's
`analyzer` (or `search_analyzer`) to the query string before executing.
The queries in this group are:
<<java-query-dsl-match-query,`match` query>>::
The standard query for performing full text queries, including fuzzy matching
and phrase or proximity queries.
<<java-query-dsl-multi-match-query,`multi_match` query>>::
The multi-field version of the `match` query.
<<java-query-dsl-common-terms-query,`common_terms` query>>::
A more specialized query which gives more preference to uncommon words.
<<java-query-dsl-query-string-query,`query_string` query>>::
Supports the compact Lucene query string syntax,
allowing you to specify AND|OR|NOT conditions and multi-field search
within a single query string. For expert users only.
<<java-query-dsl-simple-query-string-query,`simple_query_string`>>::
A simpler, more robust version of the `query_string` syntax suitable
for exposing directly to users.
include::match-query.asciidoc[]
include::multi-match-query.asciidoc[]
include::common-terms-query.asciidoc[]
include::query-string-query.asciidoc[]
include::simple-query-string-query.asciidoc[]

27
docs/java-api/query-dsl/function-score-query.asciidoc Normal file
View file

@ -0,0 +1,27 @@
[[java-query-dsl-function-score-query]]
==== Function Score Query
See {ref}/query-dsl-function-score-query.html[Function Score Query].
To use `ScoreFunctionBuilders` just import them in your class:
[source,java]
--------------------------------------------------
import static org.elasticsearch.index.query.functionscore.ScoreFunctionBuilders.*;
--------------------------------------------------
[source,java]
--------------------------------------------------
QueryBuilder qb = functionScoreQuery()
.add(
matchQuery("name", "kimchy"), <1>
randomFunction("ABCDEF") <2>
)
.add(
exponentialDecayFunction("age", 0L, 1L) <3>
);
--------------------------------------------------
<1> Add a first function based on a query
<2> And randomize the score based on a given seed
<3> Add another function based on the age field

15
docs/java-api/query-dsl/fuzzy-query.asciidoc Normal file
View file

@ -0,0 +1,15 @@
[[java-query-dsl-fuzzy-query]]
==== Fuzzy Query
See {ref}/query-dsl-fuzzy-query.html[Fuzzy Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = fuzzyQuery(
"name", <1>
"kimzhy" <2>
);
--------------------------------------------------
<1> field
<2> text

16
docs/java-api/query-dsl/geo-bounding-box-query.asciidoc Normal file
View file

@ -0,0 +1,16 @@
[[java-query-dsl-geo-bounding-box-query]]
==== Geo Bounding Box Query
See {ref}/query-dsl-geo-bounding-box-query.html[Geo Bounding Box Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = geoBoundingBoxQuery("pin.location") <1>
.topLeft(40.73, -74.1) <2>
.bottomRight(40.717, -73.99); <3>
--------------------------------------------------
<1> field
<2> bounding box top left point
<3> bounding box bottom right point

21
docs/java-api/query-dsl/geo-distance-query.asciidoc Normal file
View file

@ -0,0 +1,21 @@
[[java-query-dsl-geo-distance-query]]
==== Geo Distance Query
See {ref}/query-dsl-geo-distance-query.html[Geo Distance Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = geoDistanceQuery("pin.location") <1>
.point(40, -70) <2>
.distance(200, DistanceUnit.KILOMETERS) <3>
.optimizeBbox("memory") <4>
.geoDistance(GeoDistance.ARC); <5>
--------------------------------------------------
<1> field
<2> center point
<3> distance from center point
<4> optimize bounding box: `memory`, `indexed` or `none`
<5> distance computation mode: `GeoDistance.SLOPPY_ARC` (default), `GeoDistance.ARC` (slightly more precise but
significantly slower) or `GeoDistance.PLANE` (faster, but inaccurate on long distances and close to the poles)

26
docs/java-api/query-dsl/geo-distance-range-query.asciidoc Normal file
View file

@ -0,0 +1,26 @@
[[java-query-dsl-geo-distance-range-query]]
==== Geo Distance Range Query
See {ref}/query-dsl-geo-distance-range-query.html[Geo Distance Range Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = geoDistanceRangeQuery("pin.location") <1>
.point(40, -70) <2>
.from("200km") <3>
.to("400km") <4>
.includeLower(true) <5>
.includeUpper(false) <6>
.optimizeBbox("memory") <7>
.geoDistance(GeoDistance.ARC); <8>
--------------------------------------------------
<1> field
<2> center point
<3> starting distance from center point
<4> ending distance from center point
<5> include lower value means that `from` is `gt` when `false` or `gte` when `true`
<6> include upper value means that `to` is `lt` when `false` or `lte` when `true`
<7> optimize bounding box: `memory`, `indexed` or `none`
<8> distance computation mode: `GeoDistance.SLOPPY_ARC` (default), `GeoDistance.ARC` (slightly more precise but
significantly slower) or `GeoDistance.PLANE` (faster, but inaccurate on long distances and close to the poles)

15
docs/java-api/query-dsl/geo-polygon-query.asciidoc Normal file
View file

@ -0,0 +1,15 @@
[[java-query-dsl-geo-polygon-query]]
==== Geo Polygon Query
See {ref}/query-dsl-geo-polygon-query.html[Geo Polygon Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = geoPolygonQuery("pin.location") <1>
.addPoint(40, -70) <2>
.addPoint(30, -80) <2>
.addPoint(20, -90); <2>
--------------------------------------------------
<1> field
<2> add your polygon of points a document should fall within

49
docs/java-api/query-dsl/geo-queries.asciidoc Normal file
View file

@ -0,0 +1,49 @@
[[java-geo-queries]]
=== Geo queries
Elasticsearch supports two types of geo data:
`geo_point` fields which support lat/lon pairs, and
`geo_shape` fields, which support points, lines, circles, polygons, multi-polygons etc.
The queries in this group are:
<<java-query-dsl-geo-shape-query,`geo_shape`>> query::
Find document with geo-shapes which either intersect, are contained by, or
do not interesect with the specified geo-shape.
<<java-query-dsl-geo-bounding-box-query,`geo_bounding_box`>> query::
Finds documents with geo-points that fall into the specified rectangle.
<<java-query-dsl-geo-distance-query,`geo_distance`>> query::
Finds document with geo-points within the specified distance of a central
point.
<<java-query-dsl-geo-distance-range-query,`geo_distance_range`>> query::
Like the `geo_point` query, but the range starts at a specified distance
from the central point.
<<java-query-dsl-geo-polygon-query,`geo_polygon`>> query::
Find documents with geo-points within the specified polygon.
<<java-query-dsl-geohash-cell-query,`geohash_cell`>> query::
Find geo-points whose geohash intersects with the geohash of the specified
point.
include::geo-shape-query.asciidoc[]
include::geo-bounding-box-query.asciidoc[]
include::geo-distance-query.asciidoc[]
include::geo-distance-range-query.asciidoc[]
include::geo-polygon-query.asciidoc[]
include::geohash-cell-query.asciidoc[]

72
docs/java-api/query-dsl/geo-shape-query.asciidoc Normal file
View file

@ -0,0 +1,72 @@
[[java-query-dsl-geo-shape-query]]
==== GeoShape Query
See {ref}/query-dsl-geo-shape-query.html[Geo Shape Query]
Note: the `geo_shape` type uses `Spatial4J` and `JTS`, both of which are
optional dependencies. Consequently you must add `Spatial4J` and `JTS`
to your classpath in order to use this type:
[source,xml]
-----------------------------------------------
<dependency>
<groupId>com.spatial4j</groupId>
<artifactId>spatial4j</artifactId>
<version>0.4.1</version> <1>
</dependency>
<dependency>
<groupId>com.vividsolutions</groupId>
<artifactId>jts</artifactId>
<version>1.13</version> <2>
<exclusions>
<exclusion>
<groupId>xerces</groupId>
<artifactId>xercesImpl</artifactId>
</exclusion>
</exclusions>
</dependency>
-----------------------------------------------
<1> check for updates in http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.spatial4j%22%20AND%20a%3A%22spatial4j%22[Maven Central]
<2> check for updates in http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.vividsolutions%22%20AND%20a%3A%22jts%22[Maven Central]
[source,java]
--------------------------------------------------
// Import ShapeRelationn and ShapeBuilder
import org.elasticsearch.common.geo.ShapeRelation;
import org.elasticsearch.common.geo.builders.ShapeBuilder;
--------------------------------------------------
[source,java]
--------------------------------------------------
QueryBuilder qb = geoShapeQuery(
"pin.location", <1>
ShapeBuilder.newMultiPoint() <2>
.point(0, 0)
.point(0, 10)
.point(10, 10)
.point(10, 0)
.point(0, 0),
ShapeRelation.WITHIN); <3>
--------------------------------------------------
<1> field
<2> shape
<3> relation can be `ShapeRelation.WITHIN`, `ShapeRelation.INTERSECTS` or `ShapeRelation.DISJOINT`
[source,java]
--------------------------------------------------
// Using pre-indexed shapes
QueryBuilder qb = geoShapeQuery(
"pin.location", <1>
"DEU", <2>
"countries", <3>
ShapeRelation.WITHIN) <4>
.indexedShapeIndex("shapes") <5>
.indexedShapePath("location"); <6>
--------------------------------------------------
<1> field
<2> The ID of the document that containing the pre-indexed shape.
<3> Index type where the pre-indexed shape is.
<4> relation
<5> Name of the index where the pre-indexed shape is. Defaults to 'shapes'.
<6> The field specified as path containing the pre-indexed shape. Defaults to 'shape'.

17
docs/java-api/query-dsl/geohash-cell-query.asciidoc Normal file
View file

@ -0,0 +1,17 @@
[[java-query-dsl-geohash-cell-query]]
==== Geohash Cell Query
See {ref}/query-dsl-geohash-cell-query.html[Geohash Cell Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = geoHashCellQuery("pin.location", <1>
new GeoPoint(13.4080, 52.5186)) <2>
.neighbors(true) <3>
.precision(3); <4>
--------------------------------------------------
<1> field
<2> point. Can also be a hash like `u30`
<3> The `neighbors` option of the filter offers the possibility to filter cells
next to the given cell.
<4> precision level

15
docs/java-api/query-dsl/has-child-query.asciidoc Normal file
View file

@ -0,0 +1,15 @@
[[java-query-dsl-has-child-query]]
==== Has Child Query
See {ref}/query-dsl-has-child-query.html[Has Child Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = hasChildQuery(
"blog_tag", <1>
termQuery("tag","something") <2>
);
--------------------------------------------------
<1> child type to query against
<2> query

14
docs/java-api/query-dsl/has-parent-query.asciidoc Normal file
View file

@ -0,0 +1,14 @@
[[java-query-dsl-has-parent-query]]
==== Has Parent Query
See {ref}/query-dsl-has-parent-query.html[Has Parent]
[source,java]
--------------------------------------------------
QueryBuilder qb = hasParentQuery(
"blog", <1>
termQuery("tag","something") <2>
);
--------------------------------------------------
<1> parent type to query against
<2> query

16
docs/java-api/query-dsl/ids-query.asciidoc Normal file
View file

@ -0,0 +1,16 @@
[[java-query-dsl-ids-query]]
==== Ids Query
See {ref}/query-dsl-ids-query.html[Ids Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = idsQuery("my_type", "type2")
.addIds("1", "4", "100");
QueryBuilder qb = idsQuery() <1>
.addIds("1", "4", "100");
--------------------------------------------------
<1> type is optional

29
docs/java-api/query-dsl/indices-query.asciidoc Normal file
View file

@ -0,0 +1,29 @@
[[java-query-dsl-indices-query]]
==== Indices Query
See {ref}/query-dsl-indices-query.html[Indices Query]
[source,java]
--------------------------------------------------
// Using another query when no match for the main one
QueryBuilder qb = indicesQuery(
termQuery("tag", "wow"), <1>
"index1", "index2" <2>
).noMatchQuery(termQuery("tag", "kow")); <3>
--------------------------------------------------
<1> query to be executed on selected indices
<2> selected indices
<3> query to be executed on non matching indices
[source,java]
--------------------------------------------------
// Using all (match all) or none (match no documents)
QueryBuilder qb = indicesQuery(
termQuery("tag", "wow"), <1>
"index1", "index2" <2>
).noMatchQuery("all"); <3>
--------------------------------------------------
<1> query to be executed on selected indices
<2> selected indices
<3> `none` (to match no documents), and `all` (to match all documents). Defaults to `all`.

28
docs/java-api/query-dsl/joining-queries.asciidoc Normal file
View file

@ -0,0 +1,28 @@
[[java-joining-queries]]
=== Joining queries
Performing full SQL-style joins in a distributed system like Elasticsearch is
prohibitively expensive. Instead, Elasticsearch offers two forms of join
which are designed to scale horizontally.
<<java-query-dsl-nested-query,`nested` query>>::
Documents may contains fields of type `nested`. These
fields are used to index arrays of objects, where each object can be queried
(with the `nested` query) as an independent document.
<<java-query-dsl-has-child-query,`has_child`>> and <<java-query-dsl-has-parent-query,`has_parent`>> queries::
A parent-child relationship can exist between two
document types within a single index. The `has_child` query returns parent
documents whose child documents match the specified query, while the
`has_parent` query returns child documents whose parent document matches the
specified query.
include::nested-query.asciidoc[]
include::has-child-query.asciidoc[]
include::has-parent-query.asciidoc[]

13
docs/java-api/query-dsl/limit-query.asciidoc Normal file
View file

@ -0,0 +1,13 @@
[[java-query-dsl-limit-query]]
==== Limit Query
deprecated[1.6.0, Use <<java-search-terminate-after,terminateAfter()>> instead]
See {ref}/query-dsl-limit-query.html[Limit Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = limitQuery(100); <1>
--------------------------------------------------
<1> number of documents per shard

9
docs/java-api/query-dsl/match-all-query.asciidoc Normal file
View file

@ -0,0 +1,9 @@
[[java-query-dsl-match-all-query]]
=== Match All Query
See {ref}/query-dsl-match-all-query.html[Match All Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = matchAllQuery();
--------------------------------------------------

15
docs/java-api/query-dsl/match-query.asciidoc Normal file
View file

@ -0,0 +1,15 @@
[[java-query-dsl-match-query]]
==== Match Query
See {ref}/query-dsl-match-query.html[Match Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = matchQuery(
"name", <1>
"kimchy elasticsearch" <2>
);
--------------------------------------------------
<1> field
<2> text

15
docs/java-api/query-dsl/missing-query.asciidoc Normal file
View file

@ -0,0 +1,15 @@
[[java-query-dsl-missing-query]]
==== Missing Query
See {ref}/query-dsl-missing-query.html[Missing Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = missingQuery("user"); <1>
.existence(true) <2>
.nullValue(true); <3>
--------------------------------------------------
<1> field
<2> find missing field that doesn’t exist
<3> find missing field with an explicit `null` value

17
docs/java-api/query-dsl/mlt-query.asciidoc Normal file
View file

@ -0,0 +1,17 @@
[[java-query-dsl-mlt-query]]
==== More Like This Query (mlt)
See:
* {ref}/query-dsl-mlt-query.html[More Like This Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = moreLikeThisQuery("name.first", "name.last") <1>
.like("text like this one") <2>
.minTermFreq(1) <3>
.maxQueryTerms(12); <4>
--------------------------------------------------
<1> fields
<2> text
<3> ignore threshold
<4> max num of Terms in generated queries

14
docs/java-api/query-dsl/multi-match-query.asciidoc Normal file
View file

@ -0,0 +1,14 @@
[[java-query-dsl-multi-match-query]]
==== Multi Match Query
See {ref}/query-dsl-multi-match-query.html[Multi Match Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = multiMatchQuery(
"kimchy elasticsearch", <1>
"user", "message" <2>
);
--------------------------------------------------
<1> text
<2> fields

18
docs/java-api/query-dsl/nested-query.asciidoc Normal file
View file

@ -0,0 +1,18 @@
[[java-query-dsl-nested-query]]
==== Nested Query
See {ref}/query-dsl-nested-query.html[Nested Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = nestedQuery(
"obj1", <1>
boolQuery() <2>
.must(matchQuery("obj1.name", "blue"))
.must(rangeQuery("obj1.count").gt(5))
)
.scoreMode("avg"); <3>
--------------------------------------------------
<1> path to nested document
<2> your query. Any fields referenced inside the query must use the complete path (fully qualified).
<3> score mode could be `max`, `total`, `avg` (default) or `none`

15
docs/java-api/query-dsl/not-query.asciidoc Normal file
View file

@ -0,0 +1,15 @@
[[java-query-dsl-not-query]]
==== Not Query
See {ref}/query-dsl-not-query.html[Not Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = notQuery(
rangeQuery("price").from("1").to("2") <1>
);
--------------------------------------------------
<1> query

16
docs/java-api/query-dsl/or-query.asciidoc Normal file
View file

@ -0,0 +1,16 @@
[[java-query-dsl-or-query]]
==== Or Query
deprecated[2.0.0, Use the `bool` query instead]
See {ref}/query-dsl-or-query.html[Or Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = orQuery(
rangeQuery("price").from(1).to(2), <1>
matchQuery("name", "joe") <1>
);
--------------------------------------------------
<1> queries

16
docs/java-api/query-dsl/prefix-query.asciidoc Normal file
View file

@ -0,0 +1,16 @@
[[java-query-dsl-prefix-query]]
==== Prefix Query
See {ref}/query-dsl-prefix-query.html[Prefix Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = prefixQuery(
"brand", <1>
"heine" <2>
);
--------------------------------------------------
<1> field
<2> prefix

10
docs/java-api/query-dsl/query-string-query.asciidoc Normal file
View file

@ -0,0 +1,10 @@
[[java-query-dsl-query-string-query]]
==== Query String Query
See {ref}/query-dsl-query-string-query.html[Query String Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = queryStringQuery("+kimchy -elasticsearch"); <1>
--------------------------------------------------
<1> text

29
docs/java-api/query-dsl/range-query.asciidoc Normal file
View file

@ -0,0 +1,29 @@
[[java-query-dsl-range-query]]
==== Range Query
See {ref}/query-dsl-range-query.html[Range Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = rangeQuery("price") <1>
.from(5) <2>
.to(10) <3>
.includeLower(true) <4>
.includeUpper(false); <5>
--------------------------------------------------
<1> field
<2> from
<3> to
<4> include lower value means that `from` is `gt` when `false` or `gte` when `true`
<5> include upper value means that `to` is `lt` when `false` or `lte` when `true`
[source,java]
--------------------------------------------------
// A simplified form using gte, gt, lt or lte
QueryBuilder qb = rangeQuery("age") <1>
.gte("10") <2>
.lt("20"); <3>
--------------------------------------------------
<1> field
<2> set `from` to 10 and `includeLower` to `true`
<3> set `to` to 20 and `includeUpper` to `false`

13
docs/java-api/query-dsl/regexp-query.asciidoc Normal file
View file

@ -0,0 +1,13 @@
[[java-query-dsl-regexp-query]]
==== Regexp Query
See {ref}/query-dsl-regexp-query.html[Regexp Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = regexpQuery(
"name.first", <1>
"s.*y"); <2>
--------------------------------------------------
<1> field
<2> regexp

39
docs/java-api/query-dsl/script-query.asciidoc Normal file
View file

@ -0,0 +1,39 @@
[[java-query-dsl-script-query]]
==== Script Query
See {ref}/query-dsl-script-query.html[Script Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = scriptQuery(
new Script("doc['num1'].value > 1") <1>
);
--------------------------------------------------
<1> inlined script
If you have stored on each data node a script named `mygroovyscript.groovy` with:
[source,groovy]
--------------------------------------------------
doc['num1'].value > param1
--------------------------------------------------
You can use it then with:
[source,java]
--------------------------------------------------
QueryBuilder qb = scriptQuery(
new Script(
"mygroovyscript", <1>
ScriptService.ScriptType.FILE, <2>
"groovy", <3>
ImmutableMap.of("param1", 5)) <4>
);
--------------------------------------------------
<1> Script name
<2> Script type: either `ScriptType.FILE`, `ScriptType.INLINE` or `ScriptType.INDEXED`
<3> Scripting engine
<4> Parameters as a `Map` of `<String, Object>`
æ

10
docs/java-api/query-dsl/simple-query-string-query.asciidoc Normal file
View file

@ -0,0 +1,10 @@
[[java-query-dsl-simple-query-string-query]]
==== Simple Query String Query
See {ref}/query-dsl-simple-query-string-query.html[Simple Query String Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = simpleQueryStringQuery("+kimchy -elasticsearch"); <1>
--------------------------------------------------
<1> text

19
docs/java-api/query-dsl/span-containing-query.asciidoc Normal file
View file

@ -0,0 +1,19 @@
[[java-query-dsl-span-containing-query]]
==== Span Containing Query
See {ref}/query-dsl-span-containing-query.html[Span Containing Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanContainingQuery()
.little(spanTermQuery("field1","foo")) <1>
.big(spanNearQuery() <2>
.clause(spanTermQuery("field1","bar"))
.clause(spanTermQuery("field1","baz"))
.slop(5)
.inOrder(true)
);
--------------------------------------------------
<1> `little` part
<2> `big` part

15
docs/java-api/query-dsl/span-first-query.asciidoc Normal file
View file

@ -0,0 +1,15 @@
[[java-query-dsl-span-first-query]]
==== Span First Query
See {ref}/query-dsl-span-first-query.html[Span First Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanFirstQuery(
spanTermQuery("user", "kimchy"), <1>
3 <2>
);
--------------------------------------------------
<1> query
<2> max end position

14
docs/java-api/query-dsl/span-multi-term-query.asciidoc Normal file
View file

@ -0,0 +1,14 @@
[[java-query-dsl-span-multi-term-query]]
==== Span Multi Term Query
See {ref}/query-dsl-span-multi-term-query.html[Span Multi Term Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanMultiTermQueryBuilder(
prefixQuery("user", "ki") <1>
);
--------------------------------------------------
<1> Can be any builder extending the `MultiTermQueryBuilder` class. For example: `FuzzyQueryBuilder`,
`PrefixQueryBuilder`, `RangeQueryBuilder`, `RegexpQueryBuilder` or `WildcardQueryBuilder`.

20
docs/java-api/query-dsl/span-near-query.asciidoc Normal file
View file

@ -0,0 +1,20 @@
[[java-query-dsl-span-near-query]]
==== Span Near Query
See {ref}/query-dsl-span-near-query.html[Span Near Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanNearQuery()
.clause(spanTermQuery("field","value1")) <1>
.clause(spanTermQuery("field","value2")) <1>
.clause(spanTermQuery("field","value3")) <1>
.slop(12) <2>
.inOrder(false) <3>
.collectPayloads(false); <4>
--------------------------------------------------
<1> span term queries
<2> slop factor: the maximum number of intervening unmatched positions
<3> whether matches are required to be in-order
<4> collect payloads or not

14
docs/java-api/query-dsl/span-not-query.asciidoc Normal file
View file

@ -0,0 +1,14 @@
[[java-query-dsl-span-not-query]]
==== Span Not Query
See {ref}/query-dsl-span-not-query.html[Span Not Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanNotQuery()
.include(spanTermQuery("field","value1")) <1>
.exclude(spanTermQuery("field","value2")); <2>
--------------------------------------------------
<1> span query whose matches are filtered
<2> span query whose matches must not overlap those returned

14
docs/java-api/query-dsl/span-or-query.asciidoc Normal file
View file

@ -0,0 +1,14 @@
[[java-query-dsl-span-or-query]]
==== Span Or Query
See {ref}/query-dsl-span-or-query.html[Span Or Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanOrQuery()
.clause(spanTermQuery("field","value1")) <1>
.clause(spanTermQuery("field","value2")) <1>
.clause(spanTermQuery("field","value3")); <1>
--------------------------------------------------
<1> span term queries

65
docs/java-api/query-dsl/span-queries.asciidoc Normal file
View file

@ -0,0 +1,65 @@
[[java-span-queries]]
=== Span queries
Span queries are low-level positional queries which provide expert control
over the order and proximity of the specified terms. These are typically used
to implement very specific queries on legal documents or patents.
Span queries cannot be mixed with non-span queries (with the exception of the `span_multi` query).
The queries in this group are:
<<java-query-dsl-span-term-query,`span_term` query>>::
The equivalent of the <<java-query-dsl-term-query,`term` query>> but for use with
other span queries.
<<java-query-dsl-span-multi-term-query,`span_multi` query>>::
Wraps a <<java-query-dsl-term-query,`term`>>, <<java-query-dsl-range-query,`range`>>,
<<java-query-dsl-prefix-query,`prefix`>>, <<java-query-dsl-wildcard-query,`wildcard`>>,
<<java-query-dsl-regexp-query,`regexp`>>, or <<java-query-dsl-fuzzy-query,`fuzzy`>> query.
<<java-query-dsl-span-first-query,`span_first` query>>::
Accepts another span query whose matches must appear within the first N
positions of the field.
<<java-query-dsl-span-near-query,`span_near` query>>::
Accepts multiple span queries whose matches must be within the specified distance of each other, and possibly in the same order.
<<java-query-dsl-span-or-query,`span_or` query>>::
Combines multiple span queries -- returns documents which match any of the
specified queries.
<<java-query-dsl-span-not-query,`span_not` query>>::
Wraps another span query, and excludes any documents which match that query.
<<java-query-dsl-span-containing-query,`span_containing` query>>::
Accepts a list of span queries, but only returns those spans which also match a second span query.
<<java-query-dsl-span-within-query,`span_within` query>>::
The result from a single span query is returned as long is its span falls
within the spans returned by a list of other span queries.
include::span-term-query.asciidoc[]
include::span-multi-term-query.asciidoc[]
include::span-first-query.asciidoc[]
include::span-near-query.asciidoc[]
include::span-or-query.asciidoc[]
include::span-not-query.asciidoc[]
include::span-containing-query.asciidoc[]
include::span-within-query.asciidoc[]

15
docs/java-api/query-dsl/span-term-query.asciidoc Normal file
View file

@ -0,0 +1,15 @@
[[java-query-dsl-span-term-query]]
==== Span Term Query
See {ref}/query-dsl-span-term-query.html[Span Term Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanTermQuery(
"user", <1>
"kimchy" <2>
);
--------------------------------------------------
<1> field
<2> value

18
docs/java-api/query-dsl/span-within-query.asciidoc Normal file
View file

@ -0,0 +1,18 @@
[[java-query-dsl-span-within-query]]
==== Span Within Query
See {ref}/query-dsl-span-within-query.html[Span Within Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanWithinQuery()
.little(spanTermQuery("field1", "foo")) <1>
.big(spanNearQuery() <2>
.clause(spanTermQuery("field1", "bar"))
.clause(spanTermQuery("field1", "baz"))
.slop(5)
.inOrder(true)
);
--------------------------------------------------
<1> `little` part
<2> `big` part

29
docs/java-api/query-dsl/special-queries.asciidoc Normal file
View file

@ -0,0 +1,29 @@
[[java-specialized-queries]]
=== Specialized queries
This group contains queries which do not fit into the other groups:
<<java-query-dsl-mlt-query,`more_like_this` query>>::
This query finds documents which are similar to the specified text, document,
or collection of documents.
<<java-query-dsl-template-query,`template` query>>::
The `template` query accepts a Mustache template (either inline, indexed, or
from a file), and a map of parameters, and combines the two to generate the
final query to execute.
<<java-query-dsl-script-query,`script` query>>::
This query allows a script to act as a filter. Also see the
<<java-query-dsl-function-score-query,`function_score` query>>.
include::mlt-query.asciidoc[]
include::template-query.asciidoc[]
include::script-query.asciidoc[]

71
docs/java-api/query-dsl/template-query.asciidoc Normal file
View file

@ -0,0 +1,71 @@
[[java-query-dsl-template-query]]
==== Template Query
See {ref}/search-template.html[Search Template] documentation
Define your template parameters as a `Map<String,Object>`:
[source,java]
--------------------------------------------------
Map<String, Object> template_params = new HashMap<>();
template_params.put("param_gender", "male");
--------------------------------------------------
You can use your stored search templates in `config/scripts`.
For example, if you have a file named `config/scripts/template_gender.mustache` containing:
[source,js]
--------------------------------------------------
{
"template" : {
"query" : {
"match" : {
"gender" : "{{param_gender}}"
}
}
}
}
--------------------------------------------------
Define your template query:
[source,java]
--------------------------------------------------
QueryBuilder qb = templateQuery(
"gender_template", <1>
ScriptService.ScriptType.FILE, <2>
template_params); <3>
--------------------------------------------------
<1> template name
<2> template stored on disk in `gender_template.mustache`
<3> parameters
You can also store your template in a special index named `.scripts`:
[source,java]
--------------------------------------------------
client.preparePutIndexedScript("mustache", "template_gender",
"{\n" +
" \"template\" : {\n" +
" \"query\" : {\n" +
" \"match\" : {\n" +
" \"gender\" : \"{{param_gender}}\"\n" +
" }\n" +
" }\n" +
" }\n" +
"}").get();
--------------------------------------------------
To execute an indexed templates, use `ScriptService.ScriptType.INDEXED`:
[source,java]
--------------------------------------------------
QueryBuilder qb = templateQuery(
"gender_template", <1>
ScriptService.ScriptType.INDEXED, <2>
template_params); <3>
--------------------------------------------------
<1> template name
<2> template stored in an index
<3> parameters

93
docs/java-api/query-dsl/term-level-queries.asciidoc Normal file
View file

@ -0,0 +1,93 @@
[[java-term-level-queries]]
=== Term level queries
While the <<java-full-text-queries,full text queries>> will analyze the query
string before executing, the _term-level queries_ operate on the exact terms
that are stored in the inverted index.
These queries are usually used for structured data like numbers, dates, and
enums, rather than full text fields. Alternatively, they allow you to craft
low-level queries, foregoing the analysis process.
The queries in this group are:
<<java-query-dsl-term-query,`term` query>>::
Find documents which contain the exact term specified in the field
specified.
<<java-query-dsl-terms-query,`terms` query>>::
Find documents which contain any of the exact terms specified in the field
specified.
<<java-query-dsl-range-query,`range` query>>::
Find documents where the field specified contains values (dates, numbers,
or strings) in the range specified.
<<java-query-dsl-exists-query,`exists` query>>::
Find documents where the field specified contains any non-null value.
<<java-query-dsl-missing-query,`missing` query>>::
Find documents where the field specified does is missing or contains only
`null` values.
<<java-query-dsl-prefix-query,`prefix` query>>::
Find documents where the field specified contains terms which being with
the exact prefix specified.
<<java-query-dsl-wildcard-query,`wildcard` query>>::
Find documents where the field specified contains terms which match the
pattern specified, where the pattern supports single character wildcards
(`?`) and multi-character wildcards (`*`)
<<java-query-dsl-regexp-query,`regexp` query>>::
Find documents where the field specified contains terms which match the
regular expression specified.
<<java-query-dsl-fuzzy-query,`fuzzy` query>>::
Find documents where the field specified contains terms which are fuzzily
similar to the specified term. Fuzziness is measured as a
http://en.wikipedia.org/wiki/Damerau%E2%80%93Levenshtein_distance[Levenshtein edit distance]
of 1 or 2.
<<java-query-dsl-type-query,`type` query>>::
Find documents of the specified type.
<<java-query-dsl-ids-query,`ids` query>>::
Find documents with the specified type and IDs.
include::term-query.asciidoc[]
include::terms-query.asciidoc[]
include::range-query.asciidoc[]
include::exists-query.asciidoc[]
include::missing-query.asciidoc[]
include::prefix-query.asciidoc[]
include::wildcard-query.asciidoc[]
include::regexp-query.asciidoc[]
include::fuzzy-query.asciidoc[]
include::type-query.asciidoc[]
include::ids-query.asciidoc[]

15
docs/java-api/query-dsl/term-query.asciidoc Normal file
View file

@ -0,0 +1,15 @@
[[java-query-dsl-term-query]]
==== Term Query
See {ref}/query-dsl-term-query.html[Term Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = term(
"name", <1>
"kimchy" <2>
);
--------------------------------------------------
<1> field
<2> text

12
docs/java-api/query-dsl/terms-query.asciidoc Normal file
View file

@ -0,0 +1,12 @@
[[java-query-dsl-terms-query]]
==== Terms Query
See {ref}/query-dsl-terms-query.html[Terms Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = termsQuery("tags", <1>
"blue", "pill"); <2>
--------------------------------------------------
<1> field
<2> values

10
docs/java-api/query-dsl/type-query.asciidoc Normal file
View file

@ -0,0 +1,10 @@
[[java-query-dsl-type-query]]
==== Type Query
See {ref}/query-dsl-type-query.html[Type Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = typeQuery("my_type"); <1>
--------------------------------------------------
<1> type

10
docs/java-api/query-dsl/wildcard-query.asciidoc Normal file
View file

@ -0,0 +1,10 @@
[[java-query-dsl-wildcard-query]]
==== Wildcard Query
See {ref}/query-dsl-wildcard-query.html[Wildcard Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = wildcardQuery("user", "k?mc*");
--------------------------------------------------