elasticsearch/docs/java-api/query-dsl-filters.asciidoc

[[query-dsl-filters]]
== Query DSL - Filters

elasticsearch provides a full Java query dsl in a similar manner to the
REST link:{ref}/query-dsl.html[Query DSL]. The factory for filter
builders is `FilterBuilders`.

Once your query is ready, you can use the <<search,Search API>>.

See also how to build <<query-dsl-queries,Queries>>.

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 link:{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 <<query-dsl-filters-caching>>.


=== Bool Filter

See link:{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 <<query-dsl-filters-caching>>.


=== Exists Filter

See link:{ref}/query-dsl-exists-filter.html[Exists Filter].


[source,java]
--------------------------------------------------
FilterBuilders.existsFilter("user");
--------------------------------------------------


=== Ids Filter

See link:{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 link:{ref}/query-dsl-limit-filter.html[Limit Filter]


[source,java]
--------------------------------------------------
FilterBuilders.limitFilter(100);
--------------------------------------------------


=== Type Filter

See link:{ref}/query-dsl-type-filter.html[Type Filter]


[source,java]
--------------------------------------------------
FilterBuilders.typeFilter("my_type");
--------------------------------------------------


=== Geo Bounding Box Filter

See link:{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
<<query-dsl-filters-caching>>.


=== GeoDistance Filter

See link:{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
<<query-dsl-filters-caching>>.


=== Geo Distance Range Filter

See link:{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
<<query-dsl-filters-caching>>.


=== Geo Polygon Filter

See link:{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
<<query-dsl-filters-caching>>.


=== Geo Shape Filter

See link:{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]
-----------------------------------------------
<dependency>
    <groupId>com.spatial4j</groupId>
    <artifactId>spatial4j</artifactId>
    <version>0.3</version>
</dependency>

<dependency>
    <groupId>com.vividsolutions</groupId>
    <artifactId>jts</artifactId>
    <version>1.12</version>
    <exclusions>
        <exclusion>
            <groupId>xerces</groupId>
            <artifactId>xercesImpl</artifactId>
        </exclusion>
    </exclusions>
</dependency>
-----------------------------------------------

[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: 
 * link:{ref}/query-dsl-has-child-filter.html[Has Child Filter]
 * link:{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 link:{ref}/query-dsl-match-all-filter.html[Match All Filter]

[source,java]
--------------------------------------------------
FilterBuilders.matchAllFilter();
--------------------------------------------------


=== Missing Filter

See link:{ref}/query-dsl-missing-filter.html[Missing Filter]


[source,java]
--------------------------------------------------
FilterBuilders.missingFilter("user")
    .existence(true)
    .nullValue(true);
--------------------------------------------------


=== Not Filter

See link:{ref}/query-dsl-not-filter.html[Not Filter]


[source,java]
--------------------------------------------------
FilterBuilders.notFilter(
    FilterBuilders.rangeFilter("price").from("1").to("2"));
--------------------------------------------------


=== Numeric Range Filter

See link:{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
<<query-dsl-filters-caching>>.


=== Or Filter

See link:{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 <<query-dsl-filters-caching>>.


=== Prefix Filter

See link:{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-dsl-filters-caching>>.


=== Query Filter

See link:{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 <<query-dsl-filters-caching>>.


=== Range Filter

See link:{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 <<query-dsl-filters-caching>>.


=== Script Filter

See link:{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 <<query-dsl-filters-caching>>.


=== Term Filter

See link:{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 <<query-dsl-filters-caching>>.


=== Terms Filter

See link:{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 <<query-dsl-filters-caching>>.


=== Nested Filter

See link:{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>>.

[[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);
--------------------------------------------------