Imported Upstream version 1.0.3upstream/1.0.3

1 files changed, 450 insertions, 0 deletions

diff --git a/docs/java-api/query-dsl-queries.asciidoc b/docs/java-api/query-dsl-queries.asciidoc
new file mode 100644
index 0000000..5760753
--- /dev/null
+++ b/docs/java-api/query-dsl-queries.asciidoc
@@ -0,0 +1,450 @@
+[[query-dsl-queries]]
+== Query DSL - Queries
+
+elasticsearch provides a full Java query dsl in a similar manner to the
+REST {ref}/query-dsl.html[Query DSL]. The factory for query
+builders is `QueryBuilders`. Once your query is ready, you can use the
+<<search,Search API>>.
+
+See also how to build <<query-dsl-filters,Filters>>
+
+To use `QueryBuilders` just import them in your class:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.index.query.QueryBuilders.*;
+--------------------------------------------------
+
+Note that you can easily print (aka debug) JSON generated queries using
+`toString()` method on `QueryBuilder` object.
+
+The `QueryBuilder` can then be used with any API that accepts a query,
+such as `count` and `search`.
+
+
+[[match]]
+=== Match Query
+
+See {ref}/query-dsl-match-query.html[Match Query]
+
+
+[source,java]
+--------------------------------------------------
+QueryBuilder qb = QueryBuilders.matchQuery("name", "kimchy elasticsearch");
+--------------------------------------------------
+
+
+[[multimatch]]
+=== MultiMatch Query
+
+See {ref}/query-dsl-multi-match-query.html[MultiMatch
+Query]
+
+[source,java]
+--------------------------------------------------
+QueryBuilder qb = QueryBuilders.multiMatchQuery(
+    "kimchy elasticsearch",     // Text you are looking for
+    "user", "message"           // Fields you query on
+    );
+--------------------------------------------------
+
+
+[[bool]]
+=== Boolean Query
+
+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"));
+--------------------------------------------------
+
+
+[[boosting]]
+=== Boosting Query
+
+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);
+--------------------------------------------------
+
+
+[[ids]]
+=== IDs Query
+
+See {ref}/query-dsl-ids-query.html[IDs Query]
+
+
+[source,java]
+--------------------------------------------------
+QueryBuilders.idsQuery().ids("1", "2");
+--------------------------------------------------
+
+[[constant-score]]
+=== Constant Score Query
+
+See {ref}/query-dsl-constant-score-query.html[Constant
+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);
+--------------------------------------------------
+
+
+[[dismax]]
+=== Disjunction Max Query
+
+See {ref}/query-dsl-dis-max-query.html[Disjunction Max
+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);
+--------------------------------------------------
+
+
+[[flt]]
+=== Fuzzy Like This (Field) Query (flt and flt_field)
+
+See:
+ * {ref}/query-dsl-flt-query.html[Fuzzy Like This Query]
+ * {ref}/query-dsl-flt-field-query.html[Fuzzy Like This Field Query]
+
+[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);
+--------------------------------------------------
+
+
+[[fuzzy]]
+=== FuzzyQuery
+
+See {ref}/query-dsl-fuzzy-query.html[Fuzzy Query]
+
+
+[source,java]
+--------------------------------------------------
+QueryBuilder qb = QueryBuilders.fuzzyQuery("name", "kimzhy");
+--------------------------------------------------
+
+
+[[has-child-parent]]
+=== Has Child / Has Parent
+
+See:
+ * {ref}/query-dsl-has-child-query.html[Has Child Query]
+ * {ref}/query-dsl-has-parent-query.html[Has Parent]
+
+[source,java]
+--------------------------------------------------
+// Has Child
+QueryBuilders.hasChildQuery("blog_tag",
+                QueryBuilders.termQuery("tag","something"))
+
+// Has Parent
+QueryBuilders.hasParentQuery("blog",
+                QueryBuilders.termQuery("tag","something"));
+--------------------------------------------------
+
+
+[[match-all]]
+=== MatchAll Query
+
+See {ref}/query-dsl-match-all-query.html[Match All
+Query]
+
+[source,java]
+--------------------------------------------------
+QueryBuilder qb = QueryBuilders.matchAllQuery();
+--------------------------------------------------
+
+
+[[mlt]]
+=== More Like This (Field) Query (mlt and mlt_field)
+
+See:
+ * {ref}/query-dsl-mlt-query.html[More Like This Query]
+ * {ref}/query-dsl-mlt-field-query.html[More Like This Field Query]
+
+[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);
+--------------------------------------------------
+
+
+[[prefix]]
+=== Prefix Query
+
+See {ref}/query-dsl-prefix-query.html[Prefix Query]
+
+[source,java]
+--------------------------------------------------
+QueryBuilders.prefixQuery("brand", "heine");
+--------------------------------------------------
+
+
+[[query-string]]
+=== QueryString Query
+
+See {ref}/query-dsl-query-string-query.html[QueryString Query]
+
+[source,java]
+--------------------------------------------------
+QueryBuilder qb = QueryBuilders.queryString("+kimchy -elasticsearch");
+--------------------------------------------------
+
+
+[[java-range]]
+=== Range Query
+
+See {ref}/query-dsl-range-query.html[Range Query]
+
+[source,java]
+--------------------------------------------------
+QueryBuilder qb = QueryBuilders
+                    .rangeQuery("price")
+                    .from(5)
+                    .to(10)
+                    .includeLower(true)
+                    .includeUpper(false);
+--------------------------------------------------
+
+
+=== Span Queries (first, near, not, or, term)
+
+See:
+ * {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 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");
+--------------------------------------------------
+
+
+[[term]]
+=== Term Query
+
+See {ref}/query-dsl-term-query.html[Term Query]
+
+[source,java]
+--------------------------------------------------
+QueryBuilder qb = QueryBuilders.termQuery("name", "kimchy");
+--------------------------------------------------
+
+
+[[java-terms]]
+=== Terms Query
+
+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
+--------------------------------------------------
+
+
+[[top-children]]
+=== Top Children Query
+
+See {ref}/query-dsl-top-children-query.html[Top Children Query]
+
+[source,java]
+--------------------------------------------------
+QueryBuilders.topChildrenQuery(
+        "blog_tag",                                 // field
+        QueryBuilders.termQuery("tag", "something") // Query
+    )
+    .score("max")                                   // max, sum or avg
+    .factor(5)
+    .incrementalFactor(2);
+--------------------------------------------------
+
+
+[[wildcard]]
+=== Wildcard Query
+
+See {ref}/query-dsl-wildcard-query.html[Wildcard Query]
+
+
+[source,java]
+--------------------------------------------------
+QueryBuilders.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
+--------------------------------------------------
+
+
+
+[[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
+--------------------------------------------------
+
+
+[[geo-shape]]
+=== GeoShape Query
+
+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]
+--------------------------------------------------
+<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
+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);
+--------------------------------------------------