OpenSearch/docs/java-api/query-dsl-queries.asciidoc

[[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` 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 `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 = matchQuery(
    "name",                  <1>
    "kimchy elasticsearch"   <2>
);
--------------------------------------------------
<1> field
<2> text


[[multimatch]]
=== MultiMatch Query

See {ref}/query-dsl-multi-match-query.html[MultiMatch
Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = multiMatchQuery(
    "kimchy elasticsearch", <1>
    "user", "message"       <2>
);
--------------------------------------------------
<1> text
<2> fields


[[bool]]
=== Boolean Query

See {ref}/query-dsl-bool-query.html[Boolean Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = boolQuery()
    .must(termQuery("content", "test1"))    <1>
    .must(termQuery("content", "test4"))    <1>
    .mustNot(termQuery("content", "test2")) <2>
    .should(termQuery("content", "test3")); <3>
--------------------------------------------------
<1> must query
<2> must not query
<3> should query


[[boosting]]
=== Boosting Query

See {ref}/query-dsl-boosting-query.html[Boosting Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = boostingQuery()
    .positive(termQuery("name","kimchy"))   <1>
    .negative(termQuery("name","dadoonet")) <2>
    .negativeBoost(0.2f);                   <3>
--------------------------------------------------
<1> query that will promote documents
<2> query that will demote documents
<3> negative boost

[[ids]]
=== IDs Query

See {ref}/query-dsl-ids-query.html[IDs Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = idsQuery().ids("1", "2"); <1>
--------------------------------------------------
<1> document ids

[[constant-score]]
=== Constant Score Query

See {ref}/query-dsl-constant-score-query.html[Constant
Score Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = constantScoreQuery(
        termFilter("name","kimchy")     <1>
    )
    .boost(2.0f);                       <2>
--------------------------------------------------
<1> you can use a filter
<2> filter score

[source,java]
--------------------------------------------------
QueryBuilder qb = constantScoreQuery(
        termQuery("name","kimchy")      <1>
    )
    .boost(2.0f);                       <2>
--------------------------------------------------
<1> you can use a query
<2> query score

[[dismax]]
=== Disjunction Max Query

See {ref}/query-dsl-dis-max-query.html[Disjunction Max
Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = disMaxQuery()
    .add(termQuery("name","kimchy"))        <1>
    .add(termQuery("name","elasticsearch")) <2>
    .boost(1.2f)                            <3>
    .tieBreaker(0.7f);                      <4>
--------------------------------------------------
<1> add your queries
<2> add your queries
<3> boost factor
<4> tie breaker


[[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]
--------------------------------------------------
QueryBuilder qb = fuzzyLikeThisQuery("name.first", "name.last") <1>
    .likeText("text like this one")                             <2>
    .maxQueryTerms(12);                                         <3>
--------------------------------------------------
<1> fields
<2> text
<3> max num of Terms in generated queries

[source,java]
--------------------------------------------------
QueryBuilder qb = fuzzyLikeThisFieldQuery("name.first")         <1>
                .likeText("text like this one")                 <2>
                .maxQueryTerms(12);                             <3>
--------------------------------------------------
<1> field
<2> text
<3> max num of Terms in generated queries


[[fuzzy]]
=== FuzzyQuery

See {ref}/query-dsl-fuzzy-query.html[Fuzzy Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = fuzzyQuery(
    "name",     <1>
    "kimzhy"    <2>
);
--------------------------------------------------
<1> field
<2> text


[[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
QueryBuilder qb = hasChildQuery(
    "blog_tag",                     <1>
    termQuery("tag","something")    <2>
);
--------------------------------------------------
<1> child type to query against
<2> query (could be also a filter)

// Has Parent
[source,java]
--------------------------------------------------
QueryBuilder qb = hasParentQuery(
    "blog",                         <1>
    termQuery("tag","something")    <2>
);
--------------------------------------------------
<1> parent type to query against
<2> query (could be also a filter)


[[match-all]]
=== MatchAll Query

See {ref}/query-dsl-match-all-query.html[Match All
Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = matchAllQuery();
--------------------------------------------------


[[mlt]]
=== More Like This (Field) Query (mlt and mlt_field)

See:
 * {ref}/query-dsl-mlt-query.html[More Like This Query]

[source,java]
--------------------------------------------------
// mlt Query
QueryBuilder qb = moreLikeThisQuery("name.first", "name.last")  <1>
    .likeText("text like this one")                             <2>
    .minTermFreq(1)                                             <3>
    .maxQueryTerms(12);                                         <4>
--------------------------------------------------
<1> fields
<2> text
<3> ignore threshold
<4> max num of Terms in generated queries

[[prefix]]
=== Prefix Query

See {ref}/query-dsl-prefix-query.html[Prefix Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = prefixQuery(
    "brand",    <1>
    "heine"     <2>
);
--------------------------------------------------
<1> field
<2> prefix


[[query-string]]
=== QueryString Query

See {ref}/query-dsl-query-string-query.html[QueryString Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = queryStringQuery("+kimchy -elasticsearch");    <1>
--------------------------------------------------
<1> text


[[java-range]]
=== Range Query

See {ref}/query-dsl-range-query.html[Range Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = rangeQuery("price")   <1>
    .from(5)                            <2>
    .to(10)                             <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`


=== Span Queries (first, near, not, or, term)

See:
 * {ref}/query-dsl-span-term-query.html[Span Term Query]
 * {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]

[source,java]
--------------------------------------------------
// Span Term
QueryBuilder qb = spanTermQuery(
    "user",                                     <1>
    "kimchy"                                    <2>
);
--------------------------------------------------
<1> field
<2> value

[source,java]
--------------------------------------------------
// Span First
QueryBuilder qb = spanFirstQuery(
    spanTermQuery("user", "kimchy"),            <1>
    3                                           <2>
);
--------------------------------------------------
<1> query
<2> max end position

[source,java]
--------------------------------------------------
// Span Near
QueryBuilder qb = spanNearQuery()
    .clause(spanTermQuery("field","value1"))    <1>
    .clause(spanTermQuery("field","value2"))    <1>
    .clause(spanTermQuery("field","value3"))    <1>
    .slop(12)                                   <2>
    .inOrder(false)                             <3>
    .collectPayloads(false);                    <4>
--------------------------------------------------
<1> span term queries
<2> slop factor: the maximum number of intervening unmatched positions
<3> whether matches are required to be in-order
<4> collect payloads or not

[source,java]
--------------------------------------------------
// Span Not
QueryBuilder qb = spanNotQuery()
    .include(spanTermQuery("field","value1"))   <1>
    .exclude(spanTermQuery("field","value2"));  <2>
--------------------------------------------------
<1> span query whose matches are filtered
<2> span query whose matches must not overlap those returned

[source,java]
--------------------------------------------------
// Span Or
QueryBuilder qb = spanOrQuery()
    .clause(spanTermQuery("field","value1"))    <1>
    .clause(spanTermQuery("field","value2"))    <1>
    .clause(spanTermQuery("field","value3"));   <1>
--------------------------------------------------
<1> span term queries


[[term]]
=== Term Query

See {ref}/query-dsl-term-query.html[Term Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = termQuery(
    "name",     <1>
    "kimchy");  <2>
--------------------------------------------------
<1> field
<2> value

[[java-terms]]
=== Terms Query

See {ref}/query-dsl-terms-query.html[Terms Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = termsQuery("tags",    <1>
    "blue", "pill")                 <2>
    .minimumMatch(1);               <3>
--------------------------------------------------
<1> field
<2> values
<3> how many terms must match at least

[[top-children]]
=== Top Children Query

See {ref}/query-dsl-top-children-query.html[Top Children Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = topChildrenQuery(
        "blog_tag",                   <1>
        termQuery("tag", "something") <2>
    )
    .score("max")                     <3>
    .factor(5)                        <4>
    .incrementalFactor(2);            <5>
--------------------------------------------------
<1> field
<2> query
<3> `max`, `sum` or `avg`
<4> how many hits are asked for in the first child query run (defaults to 5)
<5> if not enough parents are found, and there are still more child docs to query, then the child search hits are
    expanded by multiplying by the incremental_factor (defaults to 2).

[[wildcard]]
=== Wildcard Query

See {ref}/query-dsl-wildcard-query.html[Wildcard Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = wildcardQuery("user", "k?mc*");
--------------------------------------------------

[[nested]]
=== Nested Query

See {ref}/query-dsl-nested-query.html[Nested Query]

[source,java]
--------------------------------------------------
QueryBuilder qb = nestedQuery(
        "obj1",               <1>
        boolQuery()           <2>
                .must(matchQuery("obj1.name", "blue"))
                .must(rangeQuery("obj1.count").gt(5))
    )
    .scoreMode("avg");        <3>
--------------------------------------------------
<1> path to nested document
<2> your query. Any fields referenced inside the query must use the complete path (fully qualified).
<3> score mode could be `max`, `total`, `avg` (default) 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
QueryBuilder qb = indicesQuery(
        termQuery("tag", "wow"),            <1>
        "index1", "index2"                  <2>
    )
    .noMatchQuery(termQuery("tag", "kow")); <3>
--------------------------------------------------
<1> query to be executed on selected indices
<2> selected indices
<3> query to be executed on non matching indices

[source,java]
--------------------------------------------------
// Using all (match all) or none (match no documents)
QueryBuilder qb = indicesQuery(
        termQuery("tag", "wow"),            <1>
        "index1", "index2"                  <2>
    )
    .noMatchQuery("all");                   <3>
--------------------------------------------------
<1> query to be executed on selected indices
<2> selected indices
<3> `none` (to match no documents), and `all` (to match all documents). Defaults to `all`.


[[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,xml]
--------------------------------------------------
<dependency>
    <groupId>com.spatial4j</groupId>
    <artifactId>spatial4j</artifactId>
    <version>0.4.1</version>                        <1>
</dependency>

<dependency>
    <groupId>com.vividsolutions</groupId>
    <artifactId>jts</artifactId>
    <version>1.13</version>                         <2>
    <exclusions>
        <exclusion>
            <groupId>xerces</groupId>
            <artifactId>xercesImpl</artifactId>
        </exclusion>
    </exclusions>
</dependency>
--------------------------------------------------
<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
QueryBuilder qb = geoShapeQuery(
        "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
QueryBuilder qb = geoShapeQuery(
        "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
QueryBuilder qb = geoShapeQuery(
        "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