honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Docs: java add static imports for query and filter builders 

Also move and add inline comments to references

Closes #6920.
This commit is contained in:
David Pilato 2014-09-23 12:39:57 +02:00
parent 68c5206e50
commit cdd4d00f46
2 changed files with 480 additions and 253 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

296
docs/java-api/query-dsl-filters.asciidoc
View File

@ -9,11 +9,12 @@ Once your query is ready, you can use the <<search,Search API>>.
See also how to build <<query-dsl-queries,Queries>>. See also how to build <<query-dsl-queries,Queries>>.
To use `FilterBuilders` just import them in your class: To use `QueryBuilders` or `FilterBuilders` just import them in your class:
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
import org.elasticsearch.index.query.FilterBuilders.*; import static org.elasticsearch.index.query.QueryBuilders.*;
import static org.elasticsearch.index.query.FilterBuilders.*;
-------------------------------------------------- --------------------------------------------------
Note that you can easily print (aka debug) JSON generated queries using Note that you can easily print (aka debug) JSON generated queries using
@ -25,14 +26,13 @@ Note that you can easily print (aka debug) JSON generated queries using
See {ref}/query-dsl-and-filter.html[And Filter] See {ref}/query-dsl-and-filter.html[And Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.andFilter( FilterBuilder filter = andFilter(
FilterBuilders.rangeFilter("postDate").from("2010-03-01").to("2010-04-01"), rangeFilter("postDate").from("2010-03-01").to("2010-04-01"), <1>
FilterBuilders.prefixFilter("name.second", "ba") prefixFilter("name.second", "ba")); <1>
);
-------------------------------------------------- --------------------------------------------------
<1> filters
Note that you can cache the result using Note that you can cache the result using
`AndFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>. `AndFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@ -43,15 +43,17 @@ Note that you can cache the result using
See {ref}/query-dsl-bool-filter.html[Bool Filter] See {ref}/query-dsl-bool-filter.html[Bool Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.boolFilter() FilterBuilder filter = boolFilter()
.must(FilterBuilders.termFilter("tag", "wow")) .must(termFilter("tag", "wow")) <1>
.mustNot(FilterBuilders.rangeFilter("age").from("10").to("20")) .mustNot(rangeFilter("age").from("10").to("20")) <2>
.should(FilterBuilders.termFilter("tag", "sometag")) .should(termFilter("tag", "sometag")) <3>
.should(FilterBuilders.termFilter("tag", "sometagtag")); .should(termFilter("tag", "sometagtag")); <3>
-------------------------------------------------- --------------------------------------------------
<1> must filter
<2> must not filter
<3> should filter
Note that you can cache the result using Note that you can cache the result using
`BoolFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>. `BoolFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@ -62,11 +64,11 @@ Note that you can cache the result using
See {ref}/query-dsl-exists-filter.html[Exists Filter]. See {ref}/query-dsl-exists-filter.html[Exists Filter].
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.existsFilter("user"); FilterBuilder filter = existsFilter("user"); <1>
-------------------------------------------------- --------------------------------------------------
<1> field
[[ids-filter]] [[ids-filter]]
@ -74,14 +76,15 @@ FilterBuilders.existsFilter("user");
See {ref}/query-dsl-ids-filter.html[IDs Filter] See {ref}/query-dsl-ids-filter.html[IDs Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.idsFilter("my_type", "type2").addIds("1", "4", "100"); FilterBuilder filter = idsFilter("my_type", "type2")
.addIds("1", "4", "100");
// Type is optional FilterBuilder filter = idsFilter() <1>
FilterBuilders.idsFilter().addIds("1", "4", "100"); .addIds("1", "4", "100");
-------------------------------------------------- --------------------------------------------------
<1> type is optional
[[limit-filter]] [[limit-filter]]
@ -89,11 +92,11 @@ FilterBuilders.idsFilter().addIds("1", "4", "100");
See {ref}/query-dsl-limit-filter.html[Limit Filter] See {ref}/query-dsl-limit-filter.html[Limit Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.limitFilter(100); FilterBuilder filter = limitFilter(100); <1>
-------------------------------------------------- --------------------------------------------------
<1> number of documents per shard
[[type-filter]] [[type-filter]]
@ -101,11 +104,11 @@ FilterBuilders.limitFilter(100);
See {ref}/query-dsl-type-filter.html[Type Filter] See {ref}/query-dsl-type-filter.html[Type Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.typeFilter("my_type"); FilterBuilder filter = typeFilter("my_type"); <1>
-------------------------------------------------- --------------------------------------------------
<1> type
[[geo-bbox-filter]] [[geo-bbox-filter]]
@ -116,10 +119,13 @@ Bounding Box Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.geoBoundingBoxFilter("pin.location") FilterBuilder filter = geoBoundingBoxFilter("pin.location") <1>
.topLeft(40.73, -74.1) .topLeft(40.73, -74.1) <2>
.bottomRight(40.717, -73.99); .bottomRight(40.717, -73.99); <3>
-------------------------------------------------- --------------------------------------------------
<1> field
<2> bounding box top left point
<3> bounding box bottom right point
Note that you can cache the result using Note that you can cache the result using
`GeoBoundingBoxFilterBuilder#cache(boolean)` method. See `GeoBoundingBoxFilterBuilder#cache(boolean)` method. See
@ -134,12 +140,18 @@ Distance Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.geoDistanceFilter("pin.location") FilterBuilder filter = geoDistanceFilter("pin.location") <1>
.point(40, -70) .point(40, -70) <2>
.distance(200, DistanceUnit.KILOMETERS) .distance(200, DistanceUnit.KILOMETERS) <3>
.optimizeBbox("memory") // Can be also "indexed" or "none" .optimizeBbox("memory") <4>
.geoDistance(GeoDistance.ARC); // Or GeoDistance.PLANE .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` (slighly more precise but
significantly slower) or `GeoDistance.PLANE` (faster, but inaccurate on long distances and close to the poles)
Note that you can cache the result using Note that you can cache the result using
`GeoDistanceFilterBuilder#cache(boolean)` method. See `GeoDistanceFilterBuilder#cache(boolean)` method. See
@ -154,15 +166,24 @@ Distance Range Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.geoDistanceRangeFilter("pin.location") FilterBuilder filter = geoDistanceRangeFilter("pin.location") <1>
.point(40, -70) .point(40, -70) <2>
.from("200km") .from("200km") <3>
.to("400km") .to("400km") <4>
.includeLower(true) .includeLower(true) <5>
.includeUpper(false) .includeUpper(false) <6>
.optimizeBbox("memory") // Can be also "indexed" or "none" .optimizeBbox("memory") <7>
.geoDistance(GeoDistance.ARC); // Or GeoDistance.PLANE .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` (slighly more precise but
significantly slower) or `GeoDistance.PLANE` (faster, but inaccurate on long distances and close to the poles)
Note that you can cache the result using Note that you can cache the result using
`GeoDistanceRangeFilterBuilder#cache(boolean)` method. See `GeoDistanceRangeFilterBuilder#cache(boolean)` method. See
@ -177,11 +198,13 @@ Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.geoPolygonFilter("pin.location") FilterBuilder filter = geoPolygonFilter("pin.location") <1>
.addPoint(40, -70) .addPoint(40, -70) <2>
.addPoint(30, -80) .addPoint(30, -80) <2>
.addPoint(20, -90); .addPoint(20, -90); <2>
-------------------------------------------------- --------------------------------------------------
<1> field
<2> add your polygon of points a document should fall within
Note that you can cache the result using Note that you can cache the result using
`GeoPolygonFilterBuilder#cache(boolean)` method. See `GeoPolygonFilterBuilder#cache(boolean)` method. See
@ -203,13 +226,13 @@ to your classpath in order to use this type:
<dependency> <dependency>
<groupId>com.spatial4j</groupId> <groupId>com.spatial4j</groupId>
<artifactId>spatial4j</artifactId> <artifactId>spatial4j</artifactId>
<version>0.3</version> <version>0.4.1</version> <1>
</dependency> </dependency>
<dependency> <dependency>
<groupId>com.vividsolutions</groupId> <groupId>com.vividsolutions</groupId>
<artifactId>jts</artifactId> <artifactId>jts</artifactId>
<version>1.12</version> <version>1.13</version> <2>
<exclusions> <exclusions>
<exclusion> <exclusion>
<groupId>xerces</groupId> <groupId>xerces</groupId>
@ -218,6 +241,8 @@ to your classpath in order to use this type:
</exclusions> </exclusions>
</dependency> </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] [source,java]
-------------------------------------------------- --------------------------------------------------
@ -233,19 +258,42 @@ import org.elasticsearch.common.geo.ShapeRelation;
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
// Shape within another // Shape within another
filter = FilterBuilders.geoShapeFilter("location", FilterBuilder filter = geoShapeFilter(
new RectangleImpl(0,10,0,10,SpatialContext.GEO)) "location", <1>
.relation(ShapeRelation.WITHIN); new RectangleImpl(0,10,0,10,SpatialContext.GEO) <2>
)
// Intersect shapes .relation(ShapeRelation.WITHIN); <3>
filter = FilterBuilders.geoShapeFilter("location",
new PointImpl(0, 0, SpatialContext.GEO))
.relation(ShapeRelation.INTERSECTS);
// Using pre-indexed shapes
filter = FilterBuilders.geoShapeFilter("location", "New Zealand", "countries")
.relation(ShapeRelation.DISJOINT);
-------------------------------------------------- --------------------------------------------------
<1> field
<2> shape
<3> relation
[source,java]
--------------------------------------------------
// Intersect shapes
FilterBuilder filter = geoShapeFilter(
"location", <1>
new PointImpl(0, 0, SpatialContext.GEO) <2>
)
.relation(ShapeRelation.INTERSECTS); <3>
--------------------------------------------------
<1> field
<2> shape
<3> relation
[source,java]
--------------------------------------------------
// Using pre-indexed shapes
FilterBuilder filter = geoShapeFilter(
"location", <1>
"New Zealand", <2>
"countries") <3>
.relation(ShapeRelation.DISJOINT); <4>
--------------------------------------------------
<1> field
<2> indexed shape id
<3> index type of the indexed shapes
<4> relation
[[has-child-parent-filter]] [[has-child-parent-filter]]
@ -258,13 +306,24 @@ See:
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
// Has Child // Has Child
FilterBuilders.hasChildFilter("blog_tag", QueryBuilder qb = hasChildFilter(
QueryBuilders.termQuery("tag", "something")); "blog_tag", <1>
termFilter("tag","something") <2>
// Has Parent );
FilterBuilders.hasParentFilter("blog",
QueryBuilders.termQuery("tag", "something"));
-------------------------------------------------- --------------------------------------------------
<1> child type to query against
<2> filter (could be also a query)
[source,java]
--------------------------------------------------
// Has Parent
QueryBuilder qb = hasParentFilter(
"blog", <1>
termFilter("tag","something") <2>
);
--------------------------------------------------
<1> parent type to query against
<2> filter (could be also a query)
[[match-all-filter]] [[match-all-filter]]
@ -274,7 +333,7 @@ See {ref}/query-dsl-match-all-filter.html[Match All Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.matchAllFilter(); FilterBuilder filter = matchAllFilter();
-------------------------------------------------- --------------------------------------------------
@ -286,11 +345,13 @@ See {ref}/query-dsl-missing-filter.html[Missing Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.missingFilter("user") FilterBuilder filter = missingFilter("user") <1>
.existence(true) .existence(true) <2>
.nullValue(true); .nullValue(true); <3>
-------------------------------------------------- --------------------------------------------------
<1> field
<2> find missing field that doesn’t exist
<3> find missing field with an explicit `null` value
[[not-filter]] [[not-filter]]
=== Not Filter === Not Filter
@ -300,9 +361,11 @@ See {ref}/query-dsl-not-filter.html[Not Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.notFilter( FilterBuilder filter = notFilter(
FilterBuilders.rangeFilter("price").from("1").to("2")); rangeFilter("price").from("1").to("2") <1>
);
-------------------------------------------------- --------------------------------------------------
<1> filter
[[or-filter]] [[or-filter]]
@ -313,11 +376,12 @@ See {ref}/query-dsl-or-filter.html[Or Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.orFilter( FilterBuilder filter = orFilter(
FilterBuilders.termFilter("name.second", "banon"), termFilter("name.second", "banon"), <1>
FilterBuilders.termFilter("name.nick", "kimchy") termFilter("name.nick", "kimchy") <1>
); );
-------------------------------------------------- --------------------------------------------------
<1> filters
Note that you can cache the result using Note that you can cache the result using
`OrFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>. `OrFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@ -331,8 +395,13 @@ See {ref}/query-dsl-prefix-filter.html[Prefix Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.prefixFilter("user", "ki"); FilterBuilder filter = prefixFilter(
"user", <1>
"ki" <2>
);
-------------------------------------------------- --------------------------------------------------
<1> field
<2> prefix
Note that you can cache the result using Note that you can cache the result using
`PrefixFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>. `PrefixFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@ -346,10 +415,11 @@ See {ref}/query-dsl-query-filter.html[Query Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.queryFilter( FilterBuilder filter = queryFilter(
QueryBuilders.queryString("this AND that OR thus") queryString("this AND that OR thus") <1>
); );
-------------------------------------------------- --------------------------------------------------
<1> query you want to wrap as a filter
Note that you can cache the result using Note that you can cache the result using
`QueryFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>. `QueryFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@ -363,17 +433,28 @@ See {ref}/query-dsl-range-filter.html[Range Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.rangeFilter("age") FilterBuilder filter = rangeFilter("age") <1>
.from("10") .from("10") <2>
.to("20") .to("20") <3>
.includeLower(true) .includeLower(true) <4>
.includeUpper(false); .includeUpper(false); <5>
// A simplified form using gte, gt, lt or lte
FilterBuilders.rangeFilter("age")
.gte("10")
.lt("20");
-------------------------------------------------- --------------------------------------------------
<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
FilterBuilder filter = rangeFilter("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
Note that you can ask not to cache the result using Note that you can ask not to cache the result using
`RangeFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>. `RangeFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@ -387,10 +468,12 @@ See {ref}/query-dsl-script-filter.html[Script Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilder filter = FilterBuilders.scriptFilter( FilterBuilder filter = scriptFilter(
"doc['age'].value > param1" "doc['age'].value > param1" <1>
).addParam("param1", 10); ).addParam("param1", 10); <2>
-------------------------------------------------- --------------------------------------------------
<1> script to execute
<2> parameters
Note that you can cache the result using Note that you can cache the result using
`ScriptFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>. `ScriptFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@ -404,8 +487,13 @@ See {ref}/query-dsl-term-filter.html[Term Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.termFilter("user", "kimchy"); FilterBuilder filter = termFilter(
"user", <1>
"kimchy" <2>
);
-------------------------------------------------- --------------------------------------------------
<1> field
<2> value
Note that you can ask not to cache the result using Note that you can ask not to cache the result using
`TermFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>. `TermFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@ -419,10 +507,17 @@ See {ref}/query-dsl-terms-filter.html[Terms Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.termsFilter("user", "kimchy", "elasticsearch") FilterBuilder filter = termsFilter(
"user", <1>
"kimchy", <2>
"elasticsearch" <2>
)
.execution("plain"); // Optional, can be also "bool", "and" or "or" .execution("plain"); // Optional, can be also "bool", "and" or "or"
// or "bool_nocache", "and_nocache" or "or_nocache" // or "bool_nocache", "and_nocache" or "or_nocache"
-------------------------------------------------- --------------------------------------------------
<1> field
<2> terms
<3> execution mode: could be `plain`, `fielddata`, `bool`, `and`, `or`, `bool_nocache`, `and_nocache` or `or_nocache`
Note that you can ask not to cache the result using Note that you can ask not to cache the result using
`TermsFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>. `TermsFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@ -436,12 +531,14 @@ See {ref}/query-dsl-nested-filter.html[Nested Filter]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilders.nestedFilter("obj1", FilterBuilder filter = nestedFilter("obj1", <1>
QueryBuilders.boolQuery() boolFilter() <2>
.must(QueryBuilders.matchQuery("obj1.name", "blue")) .must(termFilter("obj1.name", "blue"))
.must(QueryBuilders.rangeQuery("obj1.count").gt(5)) .must(rangeFilter("obj1.count").gt(5))
); );
-------------------------------------------------- --------------------------------------------------
<1> path to nested document
<2> filter
Note that you can ask not to cache the result using Note that you can ask not to cache the result using
`NestedFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>. `NestedFilterBuilder#cache(boolean)` method. See <<query-dsl-filters-caching>>.
@ -454,9 +551,10 @@ tuning control using `cache(boolean)` method when exists. For example:
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
FilterBuilder filter = FilterBuilders.andFilter( FilterBuilder filter = andFilter(
FilterBuilders.rangeFilter("postDate").from("2010-03-01").to("2010-04-01"), rangeFilter("postDate").from("2010-03-01").to("2010-04-01"),
FilterBuilders.prefixFilter("name.second", "ba") prefixFilter("name.second", "ba")
) )
.cache(true); .cache(true); <1>
-------------------------------------------------- --------------------------------------------------
<1> force caching filter

427
docs/java-api/query-dsl-queries.asciidoc
View File

@ -8,11 +8,12 @@ builders is `QueryBuilders`. Once your query is ready, you can use the
See also how to build <<query-dsl-filters,Filters>> See also how to build <<query-dsl-filters,Filters>>
To use `QueryBuilders` just import them in your class: To use `QueryBuilders` or `FilterBuilders` just import them in your class:
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
import org.elasticsearch.index.query.QueryBuilders.*; import static org.elasticsearch.index.query.QueryBuilders.*;
import static org.elasticsearch.index.query.FilterBuilders.*;
-------------------------------------------------- --------------------------------------------------
Note that you can easily print (aka debug) JSON generated queries using Note that you can easily print (aka debug) JSON generated queries using
@ -27,11 +28,15 @@ such as `count` and `search`.
See {ref}/query-dsl-match-query.html[Match Query] See {ref}/query-dsl-match-query.html[Match Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilder qb = QueryBuilders.matchQuery("name", "kimchy elasticsearch"); QueryBuilder qb = matchQuery(
"name", <1>
"kimchy elasticsearch" <2>
);
-------------------------------------------------- --------------------------------------------------
<1> field
<2> text
[[multimatch]] [[multimatch]]
@ -42,11 +47,13 @@ Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilder qb = QueryBuilders.multiMatchQuery( QueryBuilder qb = multiMatchQuery(
"kimchy elasticsearch", // Text you are looking for "kimchy elasticsearch", <1>
"user", "message" // Fields you query on "user", "message" <2>
); );
-------------------------------------------------- --------------------------------------------------
<1> text
<2> fields
[[bool]] [[bool]]
@ -54,16 +61,17 @@ QueryBuilder qb = QueryBuilders.multiMatchQuery(
See {ref}/query-dsl-bool-query.html[Boolean Query] See {ref}/query-dsl-bool-query.html[Boolean Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilder qb = QueryBuilders QueryBuilder qb = boolQuery()
.boolQuery() .must(termQuery("content", "test1")) <1>
.must(termQuery("content", "test1")) .must(termQuery("content", "test4")) <1>
.must(termQuery("content", "test4")) .mustNot(termQuery("content", "test2")) <2>
.mustNot(termQuery("content", "test2")) .should(termQuery("content", "test3")); <3>
.should(termQuery("content", "test3"));
-------------------------------------------------- --------------------------------------------------
<1> must query
<2> must not query
<3> should query
[[boosting]] [[boosting]]
@ -71,26 +79,27 @@ QueryBuilder qb = QueryBuilders
See {ref}/query-dsl-boosting-query.html[Boosting Query] See {ref}/query-dsl-boosting-query.html[Boosting Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilders.boostingQuery() QueryBuilder qb = boostingQuery()
.positive(QueryBuilders.termQuery("name","kimchy")) .positive(termQuery("name","kimchy")) <1>
.negative(QueryBuilders.termQuery("name","dadoonet")) .negative(termQuery("name","dadoonet")) <2>
.negativeBoost(0.2f); .negativeBoost(0.2f); <3>
-------------------------------------------------- --------------------------------------------------
<1> query that will promote documents
<2> query that will demote documents
<3> negative boost
[[ids]] [[ids]]
=== IDs Query === IDs Query
See {ref}/query-dsl-ids-query.html[IDs Query] See {ref}/query-dsl-ids-query.html[IDs Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilders.idsQuery().ids("1", "2"); QueryBuilder qb = idsQuery().ids("1", "2"); <1>
-------------------------------------------------- --------------------------------------------------
<1> document ids
[[constant-score]] [[constant-score]]
=== Constant Score Query === Constant Score Query
@ -100,15 +109,23 @@ Score Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
// Using with Filters QueryBuilder qb = constantScoreQuery(
QueryBuilders.constantScoreQuery(FilterBuilders.termFilter("name","kimchy")) termFilter("name","kimchy") <1>
.boost(2.0f); )
.boost(2.0f); <2>
// With Queries
QueryBuilders.constantScoreQuery(QueryBuilders.termQuery("name","kimchy"))
.boost(2.0f);
-------------------------------------------------- --------------------------------------------------
<1> you can use a filter
<2> filter score
[source,java]
--------------------------------------------------
QueryBuilder qb = constantScoreQuery(
termQuery("name","kimchy") <1>
)
.boost(2.0f); <2>
--------------------------------------------------
<1> you can use a query
<2> query score
[[dismax]] [[dismax]]
=== Disjunction Max Query === Disjunction Max Query
@ -118,12 +135,16 @@ Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilders.disMaxQuery() QueryBuilder qb = disMaxQuery()
.add(QueryBuilders.termQuery("name","kimchy")) // Your queries .add(termQuery("name","kimchy")) <1>
.add(QueryBuilders.termQuery("name","elasticsearch")) // Your queries .add(termQuery("name","elasticsearch")) <2>
.boost(1.2f) .boost(1.2f) <3>
.tieBreaker(0.7f); .tieBreaker(0.7f); <4>
-------------------------------------------------- --------------------------------------------------
<1> add your queries
<2> add your queries
<3> boost factor
<4> tie breaker
[[flt]] [[flt]]
@ -135,17 +156,23 @@ See:
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
// flt Query QueryBuilder qb = fuzzyLikeThisQuery("name.first", "name.last") <1>
QueryBuilders.fuzzyLikeThisQuery("name.first", "name.last") // Fields .likeText("text like this one") <2>
.likeText("text like this one") // Text .maxQueryTerms(12); <3>
.maxQueryTerms(12); // Max num of Terms
// in generated queries
// flt_field Query
QueryBuilders.fuzzyLikeThisFieldQuery("name.first") // Only on single field
.likeText("text like this one")
.maxQueryTerms(12);
-------------------------------------------------- --------------------------------------------------
<1> fields
<2> text
<3> max num of Terms in generated queries
[source,java]
--------------------------------------------------
QueryBuilder qb = fuzzyLikeThisFieldQuery("name.first") <1>
.likeText("text like this one") <2>
.maxQueryTerms(12); <3>
--------------------------------------------------
<1> field
<2> text
<3> max num of Terms in generated queries
[[fuzzy]] [[fuzzy]]
@ -153,11 +180,15 @@ QueryBuilders.fuzzyLikeThisFieldQuery("name.first") // Only on singl
See {ref}/query-dsl-fuzzy-query.html[Fuzzy Query] See {ref}/query-dsl-fuzzy-query.html[Fuzzy Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilder qb = QueryBuilders.fuzzyQuery("name", "kimzhy"); QueryBuilder qb = fuzzyQuery(
"name", <1>
"kimzhy" <2>
);
-------------------------------------------------- --------------------------------------------------
<1> field
<2> text
[[has-child-parent]] [[has-child-parent]]
@ -170,13 +201,24 @@ See:
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
// Has Child // Has Child
QueryBuilders.hasChildQuery("blog_tag", QueryBuilder qb = hasChildQuery(
QueryBuilders.termQuery("tag","something")) "blog_tag", <1>
termQuery("tag","something") <2>
);
--------------------------------------------------
<1> child type to query against
<2> query (could be also a filter)
// Has Parent // Has Parent
QueryBuilders.hasParentQuery("blog", [source,java]
QueryBuilders.termQuery("tag","something"));
-------------------------------------------------- --------------------------------------------------
QueryBuilder qb = hasParentQuery(
"blog", <1>
termQuery("tag","something") <2>
);
--------------------------------------------------
<1> parent type to query against
<2> query (could be also a filter)
[[match-all]] [[match-all]]
@ -187,7 +229,7 @@ Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilder qb = QueryBuilders.matchAllQuery(); QueryBuilder qb = matchAllQuery();
-------------------------------------------------- --------------------------------------------------
@ -201,18 +243,28 @@ See:
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
// mlt Query // mlt Query
QueryBuilders.moreLikeThisQuery("name.first", "name.last") // Fields QueryBuilder qb = moreLikeThisQuery("name.first", "name.last") <1>
.likeText("text like this one") // Text .likeText("text like this one") <2>
.minTermFreq(1) // Ignore Threshold .minTermFreq(1) <3>
.maxQueryTerms(12); // Max num of Terms .maxQueryTerms(12); <4>
// in generated queries
// mlt_field Query
QueryBuilders.moreLikeThisFieldQuery("name.first") // Only on single field
.likeText("text like this one")
.minTermFreq(1)
.maxQueryTerms(12);
-------------------------------------------------- --------------------------------------------------
<1> fields
<2> text
<3> ignore threshold
<4> max num of Terms in generated queries
[source,java]
--------------------------------------------------
// mlt_field Query
QueryBuilder qb = moreLikeThisFieldQuery("name.first") <1>
.likeText("text like this one") <2>
.minTermFreq(1) <3>
.maxQueryTerms(12); <4>
--------------------------------------------------
<1> field
<2> text
<3> ignore threshold
<4> max num of Terms in generated queries
[[prefix]] [[prefix]]
@ -222,8 +274,13 @@ See {ref}/query-dsl-prefix-query.html[Prefix Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilders.prefixQuery("brand", "heine"); QueryBuilder qb = prefixQuery(
"brand", <1>
"heine" <2>
);
-------------------------------------------------- --------------------------------------------------
<1> field
<2> prefix
[[query-string]] [[query-string]]
@ -233,8 +290,9 @@ See {ref}/query-dsl-query-string-query.html[QueryString Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilder qb = QueryBuilders.queryString("+kimchy -elasticsearch"); QueryBuilder qb = queryString("+kimchy -elasticsearch"); <1>
-------------------------------------------------- --------------------------------------------------
<1> text
[[java-range]] [[java-range]]
@ -244,55 +302,85 @@ See {ref}/query-dsl-range-query.html[Range Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilder qb = QueryBuilders QueryBuilder qb = rangeQuery("price") <1>
.rangeQuery("price") .from(5) <2>
.from(5) .to(10) <3>
.to(10) .includeLower(true) <4>
.includeLower(true) .includeUpper(false); <5>
.includeUpper(false);
-------------------------------------------------- --------------------------------------------------
<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`
=== Span Queries (first, near, not, or, term) === Span Queries (first, near, not, or, term)
See: See:
* {ref}/query-dsl-span-term-query.html[Span Term Query]
* {ref}/query-dsl-span-first-query.html[Span First Query] * {ref}/query-dsl-span-first-query.html[Span First Query]
* {ref}/query-dsl-span-near-query.html[Span Near Query] * {ref}/query-dsl-span-near-query.html[Span Near Query]
* {ref}/query-dsl-span-not-query.html[Span Not Query] * {ref}/query-dsl-span-not-query.html[Span Not Query]
* {ref}/query-dsl-span-or-query.html[Span Or Query] * {ref}/query-dsl-span-or-query.html[Span Or Query]
* {ref}/query-dsl-span-term-query.html[Span Term Query]
[source,java]
--------------------------------------------------
// Span Term
QueryBuilder qb = spanTermQuery(
"user", <1>
"kimchy" <2>
);
--------------------------------------------------
<1> field
<2> value
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
// Span First // Span First
QueryBuilders.spanFirstQuery( QueryBuilder qb = spanFirstQuery(
QueryBuilders.spanTermQuery("user", "kimchy"), // Query spanTermQuery("user", "kimchy"), <1>
3 // Max End position 3 <2>
); );
// Span Near
QueryBuilders.spanNearQuery()
.clause(QueryBuilders.spanTermQuery("field","value1")) // Span Term Queries
.clause(QueryBuilders.spanTermQuery("field","value2"))
.clause(QueryBuilders.spanTermQuery("field","value3"))
.slop(12) // Slop factor
.inOrder(false)
.collectPayloads(false);
// Span Not
QueryBuilders.spanNotQuery()
.include(QueryBuilders.spanTermQuery("field","value1"))
.exclude(QueryBuilders.spanTermQuery("field","value2"));
// Span Or
QueryBuilders.spanOrQuery()
.clause(QueryBuilders.spanTermQuery("field","value1"))
.clause(QueryBuilders.spanTermQuery("field","value2"))
.clause(QueryBuilders.spanTermQuery("field","value3"));
// Span Term
QueryBuilders.spanTermQuery("user","kimchy");
-------------------------------------------------- --------------------------------------------------
<1> query
<2> max end position
[source,java]
--------------------------------------------------
// Span Near
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
[source,java]
--------------------------------------------------
// Span Not
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
[source,java]
--------------------------------------------------
// Span Or
QueryBuilder qb = spanOrQuery()
.clause(spanTermQuery("field","value1")) <1>
.clause(spanTermQuery("field","value2")) <1>
.clause(spanTermQuery("field","value3")); <1>
--------------------------------------------------
<1> span term queries
[[term]] [[term]]
@ -302,9 +390,12 @@ See {ref}/query-dsl-term-query.html[Term Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilder qb = QueryBuilders.termQuery("name", "kimchy"); QueryBuilder qb = termQuery(
"name", <1>
"kimchy"); <2>
-------------------------------------------------- --------------------------------------------------
<1> field
<2> value
[[java-terms]] [[java-terms]]
=== Terms Query === Terms Query
@ -313,11 +404,13 @@ See {ref}/query-dsl-terms-query.html[Terms Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilders.termsQuery("tags", // field QueryBuilder qb = termsQuery("tags", <1>
"blue", "pill") // values "blue", "pill") <2>
.minimumMatch(1); // How many terms must match .minimumMatch(1); <3>
-------------------------------------------------- --------------------------------------------------
<1> field
<2> values
<3> how many terms must match at least
[[top-children]] [[top-children]]
=== Top Children Query === Top Children Query
@ -326,68 +419,80 @@ See {ref}/query-dsl-top-children-query.html[Top Children Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilders.topChildrenQuery( QueryBuilder qb = topChildrenQuery(
"blog_tag", // field "blog_tag", <1>
QueryBuilders.termQuery("tag", "something") // Query termQuery("tag", "something") <2>
) )
.score("max") // max, sum or avg .score("max") <3>
.factor(5) .factor(5) <4>
.incrementalFactor(2); .incrementalFactor(2); <5>
-------------------------------------------------- --------------------------------------------------
<1> field
<2> query
<3> `max`, `sum` or `avg`
<4> how many hits are asked for in the first child query run (defaults to 5)
<5> if not enough parents are found, and there are still more child docs to query, then the child search hits are
expanded by multiplying by the incremental_factor (defaults to 2).
[[wildcard]] [[wildcard]]
=== Wildcard Query === Wildcard Query
See {ref}/query-dsl-wildcard-query.html[Wildcard Query] See {ref}/query-dsl-wildcard-query.html[Wildcard Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilders.wildcardQuery("user", "k?mc*"); QueryBuilder qb = wildcardQuery("user", "k?mc*");
-------------------------------------------------- --------------------------------------------------
[[nested]] [[nested]]
=== Nested Query === Nested Query
See {ref}/query-dsl-nested-query.html[Nested Query] See {ref}/query-dsl-nested-query.html[Nested Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
QueryBuilders.nestedQuery("obj1", // Path QueryBuilder qb = nestedQuery(
QueryBuilders.boolQuery() // Your query "obj1", <1>
.must(QueryBuilders.matchQuery("obj1.name", "blue")) boolQuery() <2>
.must(QueryBuilders.rangeQuery("obj1.count").gt(5)) .must(matchQuery("obj1.name", "blue"))
.must(rangeQuery("obj1.count").gt(5))
) )
.scoreMode("avg"); // max, total, avg or none .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`
[[indices]] [[indices]]
=== Indices Query === Indices Query
See {ref}/query-dsl-indices-query.html[Indices Query] See {ref}/query-dsl-indices-query.html[Indices Query]
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
// Using another query when no match for the main one // Using another query when no match for the main one
QueryBuilders.indicesQuery( QueryBuilder qb = indicesQuery(
QueryBuilders.termQuery("tag", "wow"), termQuery("tag", "wow"), <1>
"index1", "index2" "index1", "index2" <2>
) )
.noMatchQuery(QueryBuilders.termQuery("tag", "kow")); .noMatchQuery(termQuery("tag", "kow")); <3>
// Using all (match all) or none (match no documents)
QueryBuilders.indicesQuery(
QueryBuilders.termQuery("tag", "wow"),
"index1", "index2"
)
.noMatchQuery("all"); // all or none
-------------------------------------------------- --------------------------------------------------
<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`.
[[geo-shape]] [[geo-shape]]
@ -395,23 +500,22 @@ QueryBuilders.indicesQuery(
See {ref}/query-dsl-geo-shape-query.html[GeoShape Query] See {ref}/query-dsl-geo-shape-query.html[GeoShape Query]
Note: the `geo_shape` type uses `Spatial4J` and `JTS`, both of which are Note: the `geo_shape` type uses `Spatial4J` and `JTS`, both of which are
optional dependencies. Consequently you must add `Spatial4J` and `JTS` optional dependencies. Consequently you must add `Spatial4J` and `JTS`
to your classpath in order to use this type: to your classpath in order to use this type:
[source,java] [source,xml]
-------------------------------------------------- --------------------------------------------------
<dependency> <dependency>
<groupId>com.spatial4j</groupId> <groupId>com.spatial4j</groupId>
<artifactId>spatial4j</artifactId> <artifactId>spatial4j</artifactId>
<version>0.3</version> <version>0.4.1</version> <1>
</dependency> </dependency>
<dependency> <dependency>
<groupId>com.vividsolutions</groupId> <groupId>com.vividsolutions</groupId>
<artifactId>jts</artifactId> <artifactId>jts</artifactId>
<version>1.12</version> <version>1.13</version> <2>
<exclusions> <exclusions>
<exclusion> <exclusion>
<groupId>xerces</groupId> <groupId>xerces</groupId>
@ -420,6 +524,8 @@ to your classpath in order to use this type:
</exclusions> </exclusions>
</dependency> </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] [source,java]
-------------------------------------------------- --------------------------------------------------
@ -435,16 +541,39 @@ import org.elasticsearch.common.geo.ShapeRelation;
[source,java] [source,java]
-------------------------------------------------- --------------------------------------------------
// Shape within another // Shape within another
QueryBuilders.geoShapeQuery("location", QueryBuilder qb = geoShapeQuery(
new RectangleImpl(0,10,0,10,SpatialContext.GEO)) "location", <1>
.relation(ShapeRelation.WITHIN); new RectangleImpl(0,10,0,10,SpatialContext.GEO) <2>
)
// Intersect shapes .relation(ShapeRelation.WITHIN); <3>
QueryBuilders.geoShapeQuery("location",
new PointImpl(0, 0, SpatialContext.GEO))
.relation(ShapeRelation.INTERSECTS);
// Using pre-indexed shapes
QueryBuilders.geoShapeQuery("location", "New Zealand", "countries")
.relation(ShapeRelation.DISJOINT);
-------------------------------------------------- --------------------------------------------------
<1> field
<2> shape
<3> relation
[source,java]
--------------------------------------------------
// Intersect shapes
QueryBuilder qb = geoShapeQuery(
"location", <1>
new PointImpl(0, 0, SpatialContext.GEO) <2>
)
.relation(ShapeRelation.INTERSECTS); <3>
--------------------------------------------------
<1> field
<2> shape
<3> relation
[source,java]
--------------------------------------------------
// Using pre-indexed shapes
QueryBuilder qb = geoShapeQuery(
"location", <1>
"New Zealand", <2>
"countries") <3>
.relation(ShapeRelation.DISJOINT); <4>
--------------------------------------------------
<1> field
<2> indexed shape id
<3> index type of the indexed shapes
<4> relation