[[query-dsl-filters]] == Query DSL - Filters elasticsearch provides a full Java query DSL in a similar manner to the REST {ref}/query-dsl.html[Query DSL]. The factory for filter builders is `FilterBuilders`. Once your query is ready, you can use the <>. See also how to build <>. To use `QueryBuilders` or `FilterBuilders` just import them in your class: [source,java] -------------------------------------------------- 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 `toString()` method on `FilterBuilder` object. [[and-filter]] === And Filter See {ref}/query-dsl-and-filter.html[And Filter] [source,java] -------------------------------------------------- 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 <>. [[bool-filter]] === Bool Filter See {ref}/query-dsl-bool-filter.html[Bool Filter] [source,java] -------------------------------------------------- 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 <>. [[exists-filter]] === Exists Filter See {ref}/query-dsl-exists-filter.html[Exists Filter]. [source,java] -------------------------------------------------- FilterBuilder filter = existsFilter("user"); <1> -------------------------------------------------- <1> field [[ids-filter]] === Ids Filter See {ref}/query-dsl-ids-filter.html[IDs Filter] [source,java] -------------------------------------------------- FilterBuilder filter = idsFilter("my_type", "type2") .addIds("1", "4", "100"); FilterBuilder filter = idsFilter() <1> .addIds("1", "4", "100"); -------------------------------------------------- <1> type is optional [[limit-filter]] === Limit Filter See {ref}/query-dsl-limit-filter.html[Limit Filter] [source,java] -------------------------------------------------- FilterBuilder filter = limitFilter(100); <1> -------------------------------------------------- <1> number of documents per shard [[type-filter]] === Type Filter See {ref}/query-dsl-type-filter.html[Type Filter] [source,java] -------------------------------------------------- FilterBuilder filter = typeFilter("my_type"); <1> -------------------------------------------------- <1> type [[geo-bbox-filter]] === Geo Bounding Box Filter See {ref}/query-dsl-geo-bounding-box-filter.html[Geo Bounding Box Filter] [source,java] -------------------------------------------------- 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 <>. [[geo-distance-filter]] === GeoDistance Filter See {ref}/query-dsl-geo-distance-filter.html[Geo Distance Filter] [source,java] -------------------------------------------------- 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` (slightly 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 <>. [[geo-distance-range-filter]] === Geo Distance Range Filter See {ref}/query-dsl-geo-distance-range-filter.html[Geo Distance Range Filter] [source,java] -------------------------------------------------- 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` (slightly 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 <>. [[geo-poly-filter]] === Geo Polygon Filter See {ref}/query-dsl-geo-polygon-filter.html[Geo Polygon Filter] [source,java] -------------------------------------------------- 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 <>. [[geo-shape-filter]] === Geo Shape Filter See {ref}/query-dsl-geo-shape-filter.html[Geo Shape Filter] 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] ----------------------------------------------- com.spatial4j spatial4j 0.4.1 <1> com.vividsolutions jts 1.13 <2> xerces xercesImpl ----------------------------------------------- <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 Spatial4J shapes import com.spatial4j.core.context.SpatialContext; import com.spatial4j.core.shape.Shape; import com.spatial4j.core.shape.impl.RectangleImpl; // Also import ShapeRelation import org.elasticsearch.common.geo.ShapeRelation; -------------------------------------------------- [source,java] -------------------------------------------------- // Shape within another 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]] === Has Child / Has Parent Filters See: * {ref}/query-dsl-has-child-filter.html[Has Child Filter] * {ref}/query-dsl-has-parent-filter.html[Has Parent Filter] [source,java] -------------------------------------------------- // Has Child 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]] === Match All Filter See {ref}/query-dsl-match-all-filter.html[Match All Filter] [source,java] -------------------------------------------------- FilterBuilder filter = matchAllFilter(); -------------------------------------------------- [[missing-filter]] === Missing Filter See {ref}/query-dsl-missing-filter.html[Missing Filter] [source,java] -------------------------------------------------- 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 See {ref}/query-dsl-not-filter.html[Not Filter] [source,java] -------------------------------------------------- FilterBuilder filter = notFilter( rangeFilter("price").from("1").to("2") <1> ); -------------------------------------------------- <1> filter [[or-filter]] === Or Filter See {ref}/query-dsl-or-filter.html[Or Filter] [source,java] -------------------------------------------------- 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 <>. [[prefix-filter]] === Prefix Filter See {ref}/query-dsl-prefix-filter.html[Prefix Filter] [source,java] -------------------------------------------------- FilterBuilder filter = prefixFilter( "user", <1> "ki" <2> ); -------------------------------------------------- <1> field <2> prefix Note that you can cache the result using `PrefixFilterBuilder#cache(boolean)` method. See <>. [[query-filter]] === Query Filter See {ref}/query-dsl-query-filter.html[Query Filter] [source,java] -------------------------------------------------- FilterBuilder filter = queryFilter( queryStringQuery("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 <>. [[range-filter]] === Range Filter See {ref}/query-dsl-range-filter.html[Range Filter] [source,java] -------------------------------------------------- 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 <>. [[script-filter]] === Script Filter See {ref}/query-dsl-script-filter.html[Script Filter] [source,java] -------------------------------------------------- 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 <>. [[term-filter]] === Term Filter See {ref}/query-dsl-term-filter.html[Term Filter] [source,java] -------------------------------------------------- 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 <>. [[terms-filter]] === Terms Filter See {ref}/query-dsl-terms-filter.html[Terms Filter] [source,java] -------------------------------------------------- FilterBuilder filter = termsFilter( "user", <1> "kimchy", <2> "elasticsearch" <2> ) .execution("plain"); <3> -------------------------------------------------- <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 <>. [[nested-filter]] === Nested Filter See {ref}/query-dsl-nested-filter.html[Nested Filter] [source,java] -------------------------------------------------- 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 <>. [[query-dsl-filters-caching]] === Caching By default, some filters are cached or not cached. You can have a fine tuning control using `cache(boolean)` method when exists. For example: [source,java] -------------------------------------------------- FilterBuilder filter = andFilter( rangeFilter("postDate").from("2010-03-01").to("2010-04-01"), prefixFilter("name.second", "ba") ) .cache(true); <1> -------------------------------------------------- <1> force caching filter