[[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 `FilterBuilders` just import them in your class: [source,java] -------------------------------------------------- import org.elasticsearch.index.query.FilterBuilders.*; -------------------------------------------------- Note that you can easily print (aka debug) JSON generated queries using `toString()` method on `FilterBuilder` object. === And Filter 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") ); -------------------------------------------------- Note that you can cache the result using `AndFilterBuilder#cache(boolean)` method. See <>. === Bool Filter 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")); -------------------------------------------------- Note that you can cache the result using `BoolFilterBuilder#cache(boolean)` method. See <>. === Exists Filter See {ref}/query-dsl-exists-filter.html[Exists Filter]. [source,java] -------------------------------------------------- FilterBuilders.existsFilter("user"); -------------------------------------------------- === Ids Filter See {ref}/query-dsl-ids-filter.html[IDs Filter] [source,java] -------------------------------------------------- FilterBuilders.idsFilter("my_type", "type2").addIds("1", "4", "100"); // Type is optional FilterBuilders.idsFilter().addIds("1", "4", "100"); -------------------------------------------------- === Limit Filter See {ref}/query-dsl-limit-filter.html[Limit Filter] [source,java] -------------------------------------------------- FilterBuilders.limitFilter(100); -------------------------------------------------- === Type Filter See {ref}/query-dsl-type-filter.html[Type Filter] [source,java] -------------------------------------------------- FilterBuilders.typeFilter("my_type"); -------------------------------------------------- === Geo Bounding Box Filter See {ref}/query-dsl-geo-bounding-box-filter.html[Geo Bounding Box Filter] [source,java] -------------------------------------------------- FilterBuilders.geoBoundingBoxFilter("pin.location") .topLeft(40.73, -74.1) .bottomRight(40.717, -73.99); -------------------------------------------------- Note that you can cache the result using `GeoBoundingBoxFilterBuilder#cache(boolean)` method. See <>. === GeoDistance Filter See {ref}/query-dsl-geo-distance-filter.html[Geo 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 -------------------------------------------------- Note that you can cache the result using `GeoDistanceFilterBuilder#cache(boolean)` method. See <>. === Geo Distance Range Filter See {ref}/query-dsl-geo-distance-range-filter.html[Geo 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 -------------------------------------------------- Note that you can cache the result using `GeoDistanceRangeFilterBuilder#cache(boolean)` method. See <>. === Geo Polygon Filter See {ref}/query-dsl-geo-polygon-filter.html[Geo Polygon Filter] [source,java] -------------------------------------------------- FilterBuilders.geoPolygonFilter("pin.location") .addPoint(40, -70) .addPoint(30, -80) .addPoint(20, -90); -------------------------------------------------- Note that you can cache the result using `GeoPolygonFilterBuilder#cache(boolean)` method. See <>. === 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.3 com.vividsolutions jts 1.12 xerces xercesImpl ----------------------------------------------- [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 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); -------------------------------------------------- === 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 QFilterBuilders.hasChildFilter("blog_tag", QueryBuilders.termQuery("tag", "something")); // Has Parent QFilterBuilders.hasParentFilter("blog", QueryBuilders.termQuery("tag", "something")); -------------------------------------------------- === Match All Filter See {ref}/query-dsl-match-all-filter.html[Match All Filter] [source,java] -------------------------------------------------- FilterBuilders.matchAllFilter(); -------------------------------------------------- === Missing Filter See {ref}/query-dsl-missing-filter.html[Missing Filter] [source,java] -------------------------------------------------- FilterBuilders.missingFilter("user") .existence(true) .nullValue(true); -------------------------------------------------- === Not Filter See {ref}/query-dsl-not-filter.html[Not Filter] [source,java] -------------------------------------------------- FilterBuilders.notFilter( FilterBuilders.rangeFilter("price").from("1").to("2")); -------------------------------------------------- === Numeric Range Filter See {ref}/query-dsl-numeric-range-filter.html[Numeric Range Filter] [source,java] -------------------------------------------------- FilterBuilders.numericRangeFilter("age") .from(10) .to(20) .includeLower(true) .includeUpper(false); -------------------------------------------------- Note that you can cache the result using `NumericRangeFilterBuilder#cache(boolean)` method. See <>. === Or Filter See {ref}/query-dsl-or-filter.html[Or Filter] [source,java] -------------------------------------------------- FilterBuilders.orFilter( FilterBuilders.termFilter("name.second", "banon"), FilterBuilders.termFilter("name.nick", "kimchy") ); -------------------------------------------------- Note that you can cache the result using `OrFilterBuilder#cache(boolean)` method. See <>. === Prefix Filter See {ref}/query-dsl-prefix-filter.html[Prefix Filter] [source,java] -------------------------------------------------- FilterBuilders.prefixFilter("user", "ki"); -------------------------------------------------- Note that you can cache the result using `PrefixFilterBuilder#cache(boolean)` method. See <>. === Query Filter See {ref}/query-dsl-query-filter.html[Query Filter] [source,java] -------------------------------------------------- FilterBuilders.queryFilter( QueryBuilders.queryString("this AND that OR thus") ); -------------------------------------------------- Note that you can cache the result using `QueryFilterBuilder#cache(boolean)` method. See <>. === Range Filter 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"); -------------------------------------------------- Note that you can ask not to cache the result using `RangeFilterBuilder#cache(boolean)` method. See <>. === Script Filter See {ref}/query-dsl-script-filter.html[Script Filter] [source,java] -------------------------------------------------- FilterBuilder filter = FilterBuilders.scriptFilter( "doc['age'].value > param1" ).addParam("param1", 10); -------------------------------------------------- Note that you can cache the result using `ScriptFilterBuilder#cache(boolean)` method. See <>. === Term Filter See {ref}/query-dsl-term-filter.html[Term Filter] [source,java] -------------------------------------------------- FilterBuilders.termFilter("user", "kimchy"); -------------------------------------------------- Note that you can ask not to cache the result using `TermFilterBuilder#cache(boolean)` method. See <>. === Terms Filter See {ref}/query-dsl-terms-filter.html[Terms Filter] [source,java] -------------------------------------------------- FilterBuilders.termsFilter("user", "kimchy", "elasticsearch") .execution("plain"); // Optional, can be also "bool", "and" or "or" // 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 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)) ); -------------------------------------------------- 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 = FilterBuilders.andFilter( FilterBuilders.rangeFilter("postDate").from("2010-03-01").to("2010-04-01"), FilterBuilders.prefixFilter("name.second", "ba") ) .cache(true); --------------------------------------------------