Imported Upstream version 1.0.3upstream/1.0.3

1 files changed, 462 insertions, 0 deletions

diff --git a/docs/java-api/query-dsl-filters.asciidoc b/docs/java-api/query-dsl-filters.asciidoc
new file mode 100644
index 0000000..2164ee8
--- /dev/null
+++ b/docs/java-api/query-dsl-filters.asciidoc
@@ -0,0 +1,462 @@
+[[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 <<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]]
+=== 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 <<query-dsl-filters-caching>>.
+
+
+[[bool-filter]]
+=== 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 <<query-dsl-filters-caching>>.
+
+
+[[exists-filter]]
+=== Exists Filter
+
+See {ref}/query-dsl-exists-filter.html[Exists Filter].
+
+
+[source,java]
+--------------------------------------------------
+FilterBuilders.existsFilter("user");
+--------------------------------------------------
+
+
+[[ids-filter]]
+=== 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]]
+=== Limit Filter
+
+See {ref}/query-dsl-limit-filter.html[Limit Filter]
+
+
+[source,java]
+--------------------------------------------------
+FilterBuilders.limitFilter(100);
+--------------------------------------------------
+
+
+[[type-filter]]
+=== Type Filter
+
+See {ref}/query-dsl-type-filter.html[Type Filter]
+
+
+[source,java]
+--------------------------------------------------
+FilterBuilders.typeFilter("my_type");
+--------------------------------------------------
+
+
+[[geo-bbox-filter]]
+=== 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
+<<query-dsl-filters-caching>>.
+
+
+[[geo-distance-filter]]
+=== 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
+<<query-dsl-filters-caching>>.
+
+
+[[geo-distance-range-filter]]
+=== 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
+<<query-dsl-filters-caching>>.
+
+
+[[geo-poly-filter]]
+=== 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
+<<query-dsl-filters-caching>>.
+
+
+[[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]
+-----------------------------------------------
+<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-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
+QFilterBuilders.hasChildFilter("blog_tag",
+    QueryBuilders.termQuery("tag", "something"));
+
+// Has Parent
+QFilterBuilders.hasParentFilter("blog",
+    QueryBuilders.termQuery("tag", "something"));
+--------------------------------------------------
+
+
+[[match-all-filter]]
+=== Match All Filter
+
+See {ref}/query-dsl-match-all-filter.html[Match All Filter]
+
+[source,java]
+--------------------------------------------------
+FilterBuilders.matchAllFilter();
+--------------------------------------------------
+
+
+[[missing-filter]]
+=== Missing Filter
+
+See {ref}/query-dsl-missing-filter.html[Missing Filter]
+
+
+[source,java]
+--------------------------------------------------
+FilterBuilders.missingFilter("user")
+    .existence(true)
+    .nullValue(true);
+--------------------------------------------------
+
+
+[[not-filter]]
+=== Not Filter
+
+See {ref}/query-dsl-not-filter.html[Not Filter]
+
+
+[source,java]
+--------------------------------------------------
+FilterBuilders.notFilter(
+    FilterBuilders.rangeFilter("price").from("1").to("2"));
+--------------------------------------------------
+
+
+[[or-filter]]
+=== 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 <<query-dsl-filters-caching>>.
+
+
+[[prefix-filter]]
+=== 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-dsl-filters-caching>>.
+
+
+[[query-filter]]
+=== 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 <<query-dsl-filters-caching>>.
+
+
+[[range-filter]]
+=== 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 <<query-dsl-filters-caching>>.
+
+
+[[script-filter]]
+=== 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 <<query-dsl-filters-caching>>.
+
+
+[[term-filter]]
+=== 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 <<query-dsl-filters-caching>>.
+
+
+[[terms-filter]]
+=== 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 <<query-dsl-filters-caching>>.
+
+
+[[nested-filter]]
+=== 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>>.
+
+[[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);
+--------------------------------------------------