From cdd4d00f468336bb9f43aa05a17f9177df20c4c8 Mon Sep 17 00:00:00 2001 From: David Pilato Date: Tue, 23 Sep 2014 12:39:57 +0200 Subject: [PATCH] Docs: java add static imports for query and filter builders Also move and add inline comments to references Closes #6920. --- docs/java-api/query-dsl-filters.asciidoc | 298 ++++++++++------ docs/java-api/query-dsl-queries.asciidoc | 435 +++++++++++++++-------- 2 files changed, 480 insertions(+), 253 deletions(-) diff --git a/docs/java-api/query-dsl-filters.asciidoc b/docs/java-api/query-dsl-filters.asciidoc index 60ded5ef182..b472a2dba1b 100644 --- a/docs/java-api/query-dsl-filters.asciidoc +++ b/docs/java-api/query-dsl-filters.asciidoc @@ -9,11 +9,12 @@ Once your query is ready, you can use the <>. See also how to build <>. -To use `FilterBuilders` just import them in your class: +To use `QueryBuilders` or `FilterBuilders` just import them in your class: [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 @@ -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] - [source,java] -------------------------------------------------- -FilterBuilders.andFilter( - FilterBuilders.rangeFilter("postDate").from("2010-03-01").to("2010-04-01"), - FilterBuilders.prefixFilter("name.second", "ba") - ); +FilterBuilder filter = andFilter( + rangeFilter("postDate").from("2010-03-01").to("2010-04-01"), <1> + prefixFilter("name.second", "ba")); <1> -------------------------------------------------- +<1> filters Note that you can cache the result using `AndFilterBuilder#cache(boolean)` method. See <>. @@ -43,15 +43,17 @@ Note that you can cache the result using See {ref}/query-dsl-bool-filter.html[Bool Filter] - [source,java] -------------------------------------------------- -FilterBuilders.boolFilter() - .must(FilterBuilders.termFilter("tag", "wow")) - .mustNot(FilterBuilders.rangeFilter("age").from("10").to("20")) - .should(FilterBuilders.termFilter("tag", "sometag")) - .should(FilterBuilders.termFilter("tag", "sometagtag")); +FilterBuilder filter = boolFilter() + .must(termFilter("tag", "wow")) <1> + .mustNot(rangeFilter("age").from("10").to("20")) <2> + .should(termFilter("tag", "sometag")) <3> + .should(termFilter("tag", "sometagtag")); <3> -------------------------------------------------- +<1> must filter +<2> must not filter +<3> should filter Note that you can cache the result using `BoolFilterBuilder#cache(boolean)` method. See <>. @@ -62,11 +64,11 @@ Note that you can cache the result using See {ref}/query-dsl-exists-filter.html[Exists Filter]. - [source,java] -------------------------------------------------- -FilterBuilders.existsFilter("user"); +FilterBuilder filter = existsFilter("user"); <1> -------------------------------------------------- +<1> field [[ids-filter]] @@ -74,14 +76,15 @@ FilterBuilders.existsFilter("user"); See {ref}/query-dsl-ids-filter.html[IDs Filter] - [source,java] -------------------------------------------------- -FilterBuilders.idsFilter("my_type", "type2").addIds("1", "4", "100"); +FilterBuilder filter = idsFilter("my_type", "type2") + .addIds("1", "4", "100"); -// Type is optional -FilterBuilders.idsFilter().addIds("1", "4", "100"); +FilterBuilder filter = idsFilter() <1> + .addIds("1", "4", "100"); -------------------------------------------------- +<1> type is optional [[limit-filter]] @@ -89,11 +92,11 @@ FilterBuilders.idsFilter().addIds("1", "4", "100"); See {ref}/query-dsl-limit-filter.html[Limit Filter] - [source,java] -------------------------------------------------- -FilterBuilders.limitFilter(100); +FilterBuilder filter = limitFilter(100); <1> -------------------------------------------------- +<1> number of documents per shard [[type-filter]] @@ -101,11 +104,11 @@ FilterBuilders.limitFilter(100); See {ref}/query-dsl-type-filter.html[Type Filter] - [source,java] -------------------------------------------------- -FilterBuilders.typeFilter("my_type"); +FilterBuilder filter = typeFilter("my_type"); <1> -------------------------------------------------- +<1> type [[geo-bbox-filter]] @@ -116,10 +119,13 @@ Bounding Box Filter] [source,java] -------------------------------------------------- -FilterBuilders.geoBoundingBoxFilter("pin.location") - .topLeft(40.73, -74.1) - .bottomRight(40.717, -73.99); +FilterBuilder filter = geoBoundingBoxFilter("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 Note that you can cache the result using `GeoBoundingBoxFilterBuilder#cache(boolean)` method. See @@ -134,12 +140,18 @@ Distance Filter] [source,java] -------------------------------------------------- -FilterBuilders.geoDistanceFilter("pin.location") - .point(40, -70) - .distance(200, DistanceUnit.KILOMETERS) - .optimizeBbox("memory") // Can be also "indexed" or "none" - .geoDistance(GeoDistance.ARC); // Or GeoDistance.PLANE +FilterBuilder filter = geoDistanceFilter("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` (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 `GeoDistanceFilterBuilder#cache(boolean)` method. See @@ -154,15 +166,24 @@ Distance Range Filter] [source,java] -------------------------------------------------- -FilterBuilders.geoDistanceRangeFilter("pin.location") - .point(40, -70) - .from("200km") - .to("400km") - .includeLower(true) - .includeUpper(false) - .optimizeBbox("memory") // Can be also "indexed" or "none" - .geoDistance(GeoDistance.ARC); // Or GeoDistance.PLANE +FilterBuilder filter = geoDistanceRangeFilter("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` (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 `GeoDistanceRangeFilterBuilder#cache(boolean)` method. See @@ -177,11 +198,13 @@ Filter] [source,java] -------------------------------------------------- -FilterBuilders.geoPolygonFilter("pin.location") - .addPoint(40, -70) - .addPoint(30, -80) - .addPoint(20, -90); +FilterBuilder filter = geoPolygonFilter("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 Note that you can cache the result using `GeoPolygonFilterBuilder#cache(boolean)` method. See @@ -203,13 +226,13 @@ to your classpath in order to use this type: com.spatial4j spatial4j - 0.3 + 0.4.1 <1> com.vividsolutions jts - 1.12 + 1.13 <2> xerces @@ -218,6 +241,8 @@ to your classpath in order to use this type: ----------------------------------------------- +<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] -------------------------------------------------- @@ -233,19 +258,42 @@ import org.elasticsearch.common.geo.ShapeRelation; [source,java] -------------------------------------------------- // Shape within another -filter = FilterBuilders.geoShapeFilter("location", - new RectangleImpl(0,10,0,10,SpatialContext.GEO)) - .relation(ShapeRelation.WITHIN); - -// Intersect shapes -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); +FilterBuilder filter = geoShapeFilter( + "location", <1> + new RectangleImpl(0,10,0,10,SpatialContext.GEO) <2> + ) + .relation(ShapeRelation.WITHIN); <3> -------------------------------------------------- +<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]] @@ -258,13 +306,24 @@ See: [source,java] -------------------------------------------------- // Has Child -FilterBuilders.hasChildFilter("blog_tag", - QueryBuilders.termQuery("tag", "something")); - -// Has Parent -FilterBuilders.hasParentFilter("blog", - QueryBuilders.termQuery("tag", "something")); +QueryBuilder qb = hasChildFilter( + "blog_tag", <1> + termFilter("tag","something") <2> +); -------------------------------------------------- +<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]] @@ -274,7 +333,7 @@ See {ref}/query-dsl-match-all-filter.html[Match All Filter] [source,java] -------------------------------------------------- -FilterBuilders.matchAllFilter(); +FilterBuilder filter = matchAllFilter(); -------------------------------------------------- @@ -286,11 +345,13 @@ See {ref}/query-dsl-missing-filter.html[Missing Filter] [source,java] -------------------------------------------------- -FilterBuilders.missingFilter("user") - .existence(true) - .nullValue(true); +FilterBuilder filter = missingFilter("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 [[not-filter]] === Not Filter @@ -300,9 +361,11 @@ See {ref}/query-dsl-not-filter.html[Not Filter] [source,java] -------------------------------------------------- -FilterBuilders.notFilter( - FilterBuilders.rangeFilter("price").from("1").to("2")); +FilterBuilder filter = notFilter( + rangeFilter("price").from("1").to("2") <1> +); -------------------------------------------------- +<1> filter [[or-filter]] @@ -313,11 +376,12 @@ See {ref}/query-dsl-or-filter.html[Or Filter] [source,java] -------------------------------------------------- -FilterBuilders.orFilter( - FilterBuilders.termFilter("name.second", "banon"), - FilterBuilders.termFilter("name.nick", "kimchy") +FilterBuilder filter = orFilter( + termFilter("name.second", "banon"), <1> + termFilter("name.nick", "kimchy") <1> ); -------------------------------------------------- +<1> filters Note that you can cache the result using `OrFilterBuilder#cache(boolean)` method. See <>. @@ -331,8 +395,13 @@ See {ref}/query-dsl-prefix-filter.html[Prefix Filter] [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 `PrefixFilterBuilder#cache(boolean)` method. See <>. @@ -346,10 +415,11 @@ See {ref}/query-dsl-query-filter.html[Query Filter] [source,java] -------------------------------------------------- -FilterBuilders.queryFilter( - QueryBuilders.queryString("this AND that OR thus") +FilterBuilder filter = queryFilter( + queryString("this AND that OR thus") <1> ); -------------------------------------------------- +<1> query you want to wrap as a filter Note that you can cache the result using `QueryFilterBuilder#cache(boolean)` method. See <>. @@ -363,17 +433,28 @@ See {ref}/query-dsl-range-filter.html[Range Filter] [source,java] -------------------------------------------------- -FilterBuilders.rangeFilter("age") - .from("10") - .to("20") - .includeLower(true) - .includeUpper(false); - -// A simplified form using gte, gt, lt or lte -FilterBuilders.rangeFilter("age") - .gte("10") - .lt("20"); +FilterBuilder filter = rangeFilter("age") <1> + .from("10") <2> + .to("20") <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 +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 `RangeFilterBuilder#cache(boolean)` method. See <>. @@ -387,10 +468,12 @@ See {ref}/query-dsl-script-filter.html[Script Filter] [source,java] -------------------------------------------------- -FilterBuilder filter = FilterBuilders.scriptFilter( - "doc['age'].value > param1" - ).addParam("param1", 10); +FilterBuilder filter = scriptFilter( + "doc['age'].value > param1" <1> + ).addParam("param1", 10); <2> -------------------------------------------------- +<1> script to execute +<2> parameters Note that you can cache the result using `ScriptFilterBuilder#cache(boolean)` method. See <>. @@ -404,8 +487,13 @@ See {ref}/query-dsl-term-filter.html[Term Filter] [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 `TermFilterBuilder#cache(boolean)` method. See <>. @@ -419,10 +507,17 @@ See {ref}/query-dsl-terms-filter.html[Terms Filter] [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" // 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 `TermsFilterBuilder#cache(boolean)` method. See <>. @@ -436,12 +531,14 @@ See {ref}/query-dsl-nested-filter.html[Nested Filter] [source,java] -------------------------------------------------- -FilterBuilders.nestedFilter("obj1", - QueryBuilders.boolQuery() - .must(QueryBuilders.matchQuery("obj1.name", "blue")) - .must(QueryBuilders.rangeQuery("obj1.count").gt(5)) +FilterBuilder filter = nestedFilter("obj1", <1> + boolFilter() <2> + .must(termFilter("obj1.name", "blue")) + .must(rangeFilter("obj1.count").gt(5)) ); -------------------------------------------------- +<1> path to nested document +<2> filter Note that you can ask not to cache the result using `NestedFilterBuilder#cache(boolean)` method. See <>. @@ -454,9 +551,10 @@ tuning control using `cache(boolean)` method when exists. For example: [source,java] -------------------------------------------------- -FilterBuilder filter = FilterBuilders.andFilter( - FilterBuilders.rangeFilter("postDate").from("2010-03-01").to("2010-04-01"), - FilterBuilders.prefixFilter("name.second", "ba") - ) - .cache(true); +FilterBuilder filter = andFilter( + rangeFilter("postDate").from("2010-03-01").to("2010-04-01"), + prefixFilter("name.second", "ba") + ) + .cache(true); <1> -------------------------------------------------- +<1> force caching filter diff --git a/docs/java-api/query-dsl-queries.asciidoc b/docs/java-api/query-dsl-queries.asciidoc index 57607532617..2fb6c240524 100644 --- a/docs/java-api/query-dsl-queries.asciidoc +++ b/docs/java-api/query-dsl-queries.asciidoc @@ -8,11 +8,12 @@ builders is `QueryBuilders`. Once your query is ready, you can use the See also how to build <> -To use `QueryBuilders` just import them in your class: +To use `QueryBuilders` or `FilterBuilders` just import them in your class: [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 @@ -27,11 +28,15 @@ such as `count` and `search`. See {ref}/query-dsl-match-query.html[Match Query] - [source,java] -------------------------------------------------- -QueryBuilder qb = QueryBuilders.matchQuery("name", "kimchy elasticsearch"); +QueryBuilder qb = matchQuery( + "name", <1> + "kimchy elasticsearch" <2> +); -------------------------------------------------- +<1> field +<2> text [[multimatch]] @@ -42,11 +47,13 @@ Query] [source,java] -------------------------------------------------- -QueryBuilder qb = QueryBuilders.multiMatchQuery( - "kimchy elasticsearch", // Text you are looking for - "user", "message" // Fields you query on - ); +QueryBuilder qb = multiMatchQuery( + "kimchy elasticsearch", <1> + "user", "message" <2> +); -------------------------------------------------- +<1> text +<2> fields [[bool]] @@ -54,16 +61,17 @@ QueryBuilder qb = QueryBuilders.multiMatchQuery( See {ref}/query-dsl-bool-query.html[Boolean Query] - [source,java] -------------------------------------------------- -QueryBuilder qb = QueryBuilders - .boolQuery() - .must(termQuery("content", "test1")) - .must(termQuery("content", "test4")) - .mustNot(termQuery("content", "test2")) - .should(termQuery("content", "test3")); +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 [[boosting]] @@ -71,26 +79,27 @@ QueryBuilder qb = QueryBuilders See {ref}/query-dsl-boosting-query.html[Boosting Query] - [source,java] -------------------------------------------------- -QueryBuilders.boostingQuery() - .positive(QueryBuilders.termQuery("name","kimchy")) - .negative(QueryBuilders.termQuery("name","dadoonet")) - .negativeBoost(0.2f); +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 [[ids]] === IDs Query See {ref}/query-dsl-ids-query.html[IDs Query] - [source,java] -------------------------------------------------- -QueryBuilders.idsQuery().ids("1", "2"); +QueryBuilder qb = idsQuery().ids("1", "2"); <1> -------------------------------------------------- +<1> document ids [[constant-score]] === Constant Score Query @@ -100,15 +109,23 @@ Score Query] [source,java] -------------------------------------------------- -// Using with Filters -QueryBuilders.constantScoreQuery(FilterBuilders.termFilter("name","kimchy")) - .boost(2.0f); - -// With Queries -QueryBuilders.constantScoreQuery(QueryBuilders.termQuery("name","kimchy")) - .boost(2.0f); +QueryBuilder qb = constantScoreQuery( + termFilter("name","kimchy") <1> + ) + .boost(2.0f); <2> -------------------------------------------------- +<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]] === Disjunction Max Query @@ -118,12 +135,16 @@ Query] [source,java] -------------------------------------------------- -QueryBuilders.disMaxQuery() - .add(QueryBuilders.termQuery("name","kimchy")) // Your queries - .add(QueryBuilders.termQuery("name","elasticsearch")) // Your queries - .boost(1.2f) - .tieBreaker(0.7f); +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 [[flt]] @@ -135,17 +156,23 @@ See: [source,java] -------------------------------------------------- -// flt Query -QueryBuilders.fuzzyLikeThisQuery("name.first", "name.last") // Fields - .likeText("text like this one") // Text - .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); +QueryBuilder qb = fuzzyLikeThisQuery("name.first", "name.last") <1> + .likeText("text like this one") <2> + .maxQueryTerms(12); <3> -------------------------------------------------- +<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]] @@ -153,11 +180,15 @@ QueryBuilders.fuzzyLikeThisFieldQuery("name.first") // Only on singl See {ref}/query-dsl-fuzzy-query.html[Fuzzy Query] - [source,java] -------------------------------------------------- -QueryBuilder qb = QueryBuilders.fuzzyQuery("name", "kimzhy"); +QueryBuilder qb = fuzzyQuery( + "name", <1> + "kimzhy" <2> +); -------------------------------------------------- +<1> field +<2> text [[has-child-parent]] @@ -170,13 +201,24 @@ See: [source,java] -------------------------------------------------- // Has Child -QueryBuilders.hasChildQuery("blog_tag", - QueryBuilders.termQuery("tag","something")) +QueryBuilder qb = hasChildQuery( + "blog_tag", <1> + termQuery("tag","something") <2> +); +-------------------------------------------------- +<1> child type to query against +<2> query (could be also a filter) // Has Parent -QueryBuilders.hasParentQuery("blog", - QueryBuilders.termQuery("tag","something")); +[source,java] -------------------------------------------------- +QueryBuilder qb = hasParentQuery( + "blog", <1> + termQuery("tag","something") <2> +); +-------------------------------------------------- +<1> parent type to query against +<2> query (could be also a filter) [[match-all]] @@ -187,7 +229,7 @@ Query] [source,java] -------------------------------------------------- -QueryBuilder qb = QueryBuilders.matchAllQuery(); +QueryBuilder qb = matchAllQuery(); -------------------------------------------------- @@ -201,18 +243,28 @@ See: [source,java] -------------------------------------------------- // mlt Query -QueryBuilders.moreLikeThisQuery("name.first", "name.last") // Fields - .likeText("text like this one") // Text - .minTermFreq(1) // Ignore Threshold - .maxQueryTerms(12); // Max num of Terms - // in generated queries - -// mlt_field Query -QueryBuilders.moreLikeThisFieldQuery("name.first") // Only on single field - .likeText("text like this one") - .minTermFreq(1) - .maxQueryTerms(12); +QueryBuilder qb = moreLikeThisQuery("name.first", "name.last") <1> + .likeText("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 + +[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]] @@ -222,8 +274,13 @@ See {ref}/query-dsl-prefix-query.html[Prefix Query] [source,java] -------------------------------------------------- -QueryBuilders.prefixQuery("brand", "heine"); +QueryBuilder qb = prefixQuery( + "brand", <1> + "heine" <2> +); -------------------------------------------------- +<1> field +<2> prefix [[query-string]] @@ -233,8 +290,9 @@ See {ref}/query-dsl-query-string-query.html[QueryString Query] [source,java] -------------------------------------------------- -QueryBuilder qb = QueryBuilders.queryString("+kimchy -elasticsearch"); +QueryBuilder qb = queryString("+kimchy -elasticsearch"); <1> -------------------------------------------------- +<1> text [[java-range]] @@ -244,55 +302,85 @@ See {ref}/query-dsl-range-query.html[Range Query] [source,java] -------------------------------------------------- -QueryBuilder qb = QueryBuilders - .rangeQuery("price") - .from(5) - .to(10) - .includeLower(true) - .includeUpper(false); +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` === Span Queries (first, near, not, or, term) 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-near-query.html[Span Near 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-term-query.html[Span Term Query] + +[source,java] +-------------------------------------------------- +// Span Term +QueryBuilder qb = spanTermQuery( + "user", <1> + "kimchy" <2> +); +-------------------------------------------------- +<1> field +<2> value [source,java] -------------------------------------------------- // Span First -QueryBuilders.spanFirstQuery( - QueryBuilders.spanTermQuery("user", "kimchy"), // Query - 3 // Max End position - ); - -// 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"); +QueryBuilder qb = spanFirstQuery( + spanTermQuery("user", "kimchy"), <1> + 3 <2> +); -------------------------------------------------- +<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]] @@ -302,9 +390,12 @@ See {ref}/query-dsl-term-query.html[Term Query] [source,java] -------------------------------------------------- -QueryBuilder qb = QueryBuilders.termQuery("name", "kimchy"); +QueryBuilder qb = termQuery( + "name", <1> + "kimchy"); <2> -------------------------------------------------- - +<1> field +<2> value [[java-terms]] === Terms Query @@ -313,11 +404,13 @@ See {ref}/query-dsl-terms-query.html[Terms Query] [source,java] -------------------------------------------------- -QueryBuilders.termsQuery("tags", // field - "blue", "pill") // values - .minimumMatch(1); // How many terms must match +QueryBuilder qb = termsQuery("tags", <1> + "blue", "pill") <2> + .minimumMatch(1); <3> -------------------------------------------------- - +<1> field +<2> values +<3> how many terms must match at least [[top-children]] === Top Children Query @@ -326,68 +419,80 @@ See {ref}/query-dsl-top-children-query.html[Top Children Query] [source,java] -------------------------------------------------- -QueryBuilders.topChildrenQuery( - "blog_tag", // field - QueryBuilders.termQuery("tag", "something") // Query +QueryBuilder qb = topChildrenQuery( + "blog_tag", <1> + termQuery("tag", "something") <2> ) - .score("max") // max, sum or avg - .factor(5) - .incrementalFactor(2); + .score("max") <3> + .factor(5) <4> + .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 Query See {ref}/query-dsl-wildcard-query.html[Wildcard Query] - [source,java] -------------------------------------------------- -QueryBuilders.wildcardQuery("user", "k?mc*"); +QueryBuilder qb = wildcardQuery("user", "k?mc*"); -------------------------------------------------- - [[nested]] === Nested Query See {ref}/query-dsl-nested-query.html[Nested Query] - [source,java] -------------------------------------------------- -QueryBuilders.nestedQuery("obj1", // Path - QueryBuilders.boolQuery() // Your query - .must(QueryBuilders.matchQuery("obj1.name", "blue")) - .must(QueryBuilders.rangeQuery("obj1.count").gt(5)) - ) - .scoreMode("avg"); // max, total, avg or none +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` [[indices]] === Indices Query See {ref}/query-dsl-indices-query.html[Indices Query] - [source,java] -------------------------------------------------- // Using another query when no match for the main one -QueryBuilders.indicesQuery( - QueryBuilders.termQuery("tag", "wow"), - "index1", "index2" - ) - .noMatchQuery(QueryBuilders.termQuery("tag", "kow")); - -// Using all (match all) or none (match no documents) -QueryBuilders.indicesQuery( - QueryBuilders.termQuery("tag", "wow"), - "index1", "index2" - ) - .noMatchQuery("all"); // all or none +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`. [[geo-shape]] @@ -395,23 +500,22 @@ QueryBuilders.indicesQuery( See {ref}/query-dsl-geo-shape-query.html[GeoShape 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,java] +[source,xml] -------------------------------------------------- com.spatial4j spatial4j - 0.3 + 0.4.1 <1> com.vividsolutions jts - 1.12 + 1.13 <2> xerces @@ -420,6 +524,8 @@ to your classpath in order to use this type: -------------------------------------------------- +<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] -------------------------------------------------- @@ -435,16 +541,39 @@ import org.elasticsearch.common.geo.ShapeRelation; [source,java] -------------------------------------------------- // Shape within another -QueryBuilders.geoShapeQuery("location", - new RectangleImpl(0,10,0,10,SpatialContext.GEO)) - .relation(ShapeRelation.WITHIN); - -// Intersect shapes -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); +QueryBuilder qb = geoShapeQuery( + "location", <1> + new RectangleImpl(0,10,0,10,SpatialContext.GEO) <2> + ) + .relation(ShapeRelation.WITHIN); <3> -------------------------------------------------- +<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