mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-17 02:14:54 +00:00
[Docs] Add documentation for search queries in high-level rest client (#25984)
This commit is contained in:
Tanguy Leroux
GitHub
parent
e2d25c3c89
commit
69f8641568
@ -35,8 +35,11 @@ import org.elasticsearch.action.support.WriteRequest;
|
||||
import org.elasticsearch.client.ESRestHighLevelClientTestCase;
|
||||
import org.elasticsearch.client.RestHighLevelClient;
|
||||
import org.elasticsearch.common.text.Text;
|
||||
import org.elasticsearch.common.unit.Fuzziness;
|
||||
import org.elasticsearch.common.unit.TimeValue;
|
||||
import org.elasticsearch.common.xcontent.XContentType;
|
||||
import org.elasticsearch.index.query.MatchQueryBuilder;
|
||||
import org.elasticsearch.index.query.QueryBuilder;
|
||||
import org.elasticsearch.index.query.QueryBuilders;
|
||||
import org.elasticsearch.rest.RestStatus;
|
||||
import org.elasticsearch.search.Scroll;
|
||||
@ -238,6 +241,33 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase {
|
||||
}
|
||||
}
|
||||
|
||||
@SuppressWarnings("unused")
|
||||
public void testBuildingSearchQueries() {
|
||||
RestHighLevelClient client = highLevelClient();
|
||||
{
|
||||
// tag::search-query-builder-ctor
|
||||
MatchQueryBuilder matchQueryBuilder = new MatchQueryBuilder("user", "kimchy"); // <1>
|
||||
// end::search-query-builder-ctor
|
||||
// tag::search-query-builder-options
|
||||
matchQueryBuilder.fuzziness(Fuzziness.AUTO); // <1>
|
||||
matchQueryBuilder.prefixLength(3); // <2>
|
||||
matchQueryBuilder.maxExpansions(10); // <3>
|
||||
// end::search-query-builder-options
|
||||
}
|
||||
{
|
||||
// tag::search-query-builders
|
||||
QueryBuilder matchQueryBuilder = QueryBuilders.matchQuery("user", "kimchy")
|
||||
.fuzziness(Fuzziness.AUTO)
|
||||
.prefixLength(3)
|
||||
.maxExpansions(10);
|
||||
// end::search-query-builders
|
||||
SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
|
||||
// tag::search-query-setter
|
||||
searchSourceBuilder.query(matchQueryBuilder);
|
||||
// end::search-query-setter
|
||||
}
|
||||
}
|
||||
|
||||
@SuppressWarnings({ "unused" })
|
||||
public void testSearchRequestAggregations() throws IOException {
|
||||
RestHighLevelClient client = highLevelClient();
|
||||
|
||||
@ -32,6 +32,8 @@ ifeval::["{release-state}"=="unreleased"]
|
||||
:rest-client-sniffer-javadoc: https://snapshots.elastic.co/javadoc/org/elasticsearch/client/elasticsearch-rest-client-sniffer/{version}-SNAPSHOT
|
||||
:rest-high-level-client-javadoc: https://snapshots.elastic.co/javadoc/org/elasticsearch/client/elasticsearch-rest-high-level-client/{version}-SNAPSHOT
|
||||
:painless-javadoc: https://snapshots.elastic.co/javadoc/org/elasticsearch/painless/lang-painless/{version}-SNAPSHOT
|
||||
:parent-join-client-javadoc: https://snapshots.elastic.co/javadoc/org/elasticsearch/plugin/parent-join-client/{version}-SNAPSHOT
|
||||
:percolator-client-javadoc: https://snapshots.elastic.co/javadoc/org/elasticsearch/plugin/percolator-client/{version}-SNAPSHOT
|
||||
endif::[]
|
||||
|
||||
ifeval::["{release-state}"!="unreleased"]
|
||||
@ -41,6 +43,8 @@ ifeval::["{release-state}"!="unreleased"]
|
||||
:rest-client-sniffer-javadoc: https://artifacts.elastic.co/javadoc/org/elasticsearch/client/elasticsearch-rest-client-sniffer/{version}
|
||||
:rest-high-level-client-javadoc: https://artifacts.elastic.co/javadoc/org/elasticsearch/client/elasticsearch-rest-high-level-client/{version}
|
||||
:painless-javadoc: https://artifacts.elastic.co/javadoc/org/elasticsearch/painless/lang-painless/{version}
|
||||
:parent-join-client-javadoc: https://artifacts.elastic.co/javadoc/org/elasticsearch/plugin/parent-join-client/{version}
|
||||
:percolator-client-javadoc: https://artifacts.elastic.co/javadoc/org/elasticsearch/plugin/percolator-client/{version}
|
||||
endif::[]
|
||||
|
||||
///////
|
||||
|
||||
@ -6,3 +6,4 @@ include::bulk.asciidoc[]
|
||||
include::search.asciidoc[]
|
||||
include::scroll.asciidoc[]
|
||||
include::main.asciidoc[]
|
||||
include::queries.asciidoc[]
|
||||
|
||||
100
docs/java-rest/high-level/apis/queries.asciidoc
Normal file
100
docs/java-rest/high-level/apis/queries.asciidoc
Normal file
@ -0,0 +1,100 @@
|
||||
[[java-rest-high-search-queries]]
|
||||
=== Search Queries
|
||||
|
||||
This page lists all the available search queries with their corresponding `QueryBuilder` class name and helper method name in the
|
||||
`QueryBuilders` utility class.
|
||||
|
||||
:query-ref: {elasticsearch-javadoc}/org/elasticsearch/index/query
|
||||
:parentjoin-ref: {parent-join-client-javadoc}/org/elasticsearch/join/query
|
||||
:percolate-ref: {percolator-client-javadoc}/org/elasticsearch/percolator
|
||||
|
||||
==== Match All Query
|
||||
[options="header"]
|
||||
|======
|
||||
| Search Query | QueryBuilder Class | Method in QueryBuilders
|
||||
| {ref}/query-dsl-match-all-query.html[Match All] | {query-ref}/MatchAllQueryBuilder.html[MatchAllQueryBuilder] | {query-ref}/QueryBuilders.html#matchAllQuery--[QueryBuilders.matchAllQuery()]
|
||||
|======
|
||||
|
||||
==== Full Text Queries
|
||||
[options="header"]
|
||||
|======
|
||||
| Search Query | QueryBuilder Class | Method in QueryBuilders
|
||||
| {ref}/query-dsl-match-query.html[Match] | {query-ref}/MatchQueryBuilder.html[MatchQueryBuilder] | {query-ref}/QueryBuilders.html#matchQuery-java.lang.String-java.lang.Object-[QueryBuilders.matchQuery()]
|
||||
| {ref}/query-dsl-match-query-phrase.html[Match Phrase] | {query-ref}/MatchPhraseQueryBuilder.html[MatchPhraseQueryBuilder] | {query-ref}/QueryBuilders.html#matchPhraseQuery-java.lang.String-java.lang.Object-[QueryBuilders.matchPhraseQuery()]
|
||||
| {ref}/query-dsl-match-query-phrase-prefix.html[Match Phrase Prefix] | {query-ref}/MatchPhrasePrefixQueryBuilder.html[MatchPhrasePrefixQueryBuilder] | {query-ref}/QueryBuilders.html#matchPhrasePrefixQuery-java.lang.String-java.lang.Object-[QueryBuilders.matchPhrasePrefixQuery()]
|
||||
| {ref}/query-dsl-multi-match-query.html[Multi Match] | {query-ref}/MultiMatchQueryBuilder.html[MultiMatchQueryBuilder] | {query-ref}/QueryBuilders.html#multiMatchQuery-java.lang.Object-java.lang.String\…-[QueryBuilders.multiMatchQuery()]
|
||||
| {ref}/query-dsl-common-terms-query.html[Common Terms] | {query-ref}/CommonTermsQueryBuilder.html[CommonTermsQueryBuilder] | {query-ref}/QueryBuilders.html#commonTermsQuery-java.lang.String-java.lang.Object-[QueryBuilders.commonTermsQuery()]
|
||||
| {ref}/query-dsl-query-string-query.html[Query String] | {query-ref}/QueryStringQueryBuilder.html[QueryStringQueryBuilder] | {query-ref}/QueryBuilders.html#queryStringQuery-java.lang.String-[QueryBuilders.queryStringQuery()]
|
||||
| {ref}/query-dsl-simple-query-string-query.html[Simple Query String] | {query-ref}/SimpleQueryStringBuilder.html[SimpleQueryStringBuilder] | {query-ref}/QueryBuilders.html#simpleQueryStringQuery-java.lang.String-[QueryBuilders.simpleQueryStringQuery()]
|
||||
|======
|
||||
|
||||
==== Term level queries
|
||||
[options="header"]
|
||||
|======
|
||||
| Search Query | QueryBuilder Class | Method in QueryBuilders
|
||||
| {ref}/query-dsl-term-query.html[Term] | {query-ref}/TermQueryBuilder.html[TermQueryBuilder] | {query-ref}/QueryBuilders.html#termQuery-java.lang.String-java.lang.String-[QueryBuilders.termQuery()]
|
||||
| {ref}/query-dsl-terms-query.html[Terms] | {query-ref}/TermsQueryBuilder.html[TermsQueryBuilder] | {query-ref}/QueryBuilders.html#termsQuery-java.lang.String-java.util.Collection-[QueryBuilders.termsQuery()]
|
||||
| {ref}/query-dsl-range-query.html[Range] | {query-ref}/RangeQueryBuilder.html[RangeQueryBuilder] | {query-ref}/QueryBuilders.html#rangeQuery-java.lang.String-[QueryBuilders.rangeQuery()]
|
||||
| {ref}/query-dsl-exists-query.html[Exists] | {query-ref}/ExistsQueryBuilder.html[ExistsQueryBuilder] | {query-ref}/QueryBuilders.html#existsQuery-java.lang.String-[QueryBuilders.existsQuery()]
|
||||
| {ref}/query-dsl-prefix-query.html[Prefix] | {query-ref}/PrefixQueryBuilder.html[PrefixQueryBuilder] | {query-ref}/QueryBuilders.html#prefixQuery-java.lang.String-java.lang.String-[QueryBuilders.prefixQuery()]
|
||||
| {ref}/query-dsl-wildcard-query.html[Wildcard] | {query-ref}/WildcardQueryBuilder.html[WildcardQueryBuilder] | {query-ref}/QueryBuilders.html#wildcardQuery-java.lang.String-java.lang.String-[QueryBuilders.wildcardQuery()]
|
||||
| {ref}/query-dsl-regexp-query.html[Regexp] | {query-ref}/RegexpQueryBuilder.html[RegexpQueryBuilder] | {query-ref}/QueryBuilders.html#regexpQuery-java.lang.String-java.lang.String-[QueryBuilders.regexpQuery()]
|
||||
| {ref}/query-dsl-fuzzy-query.html[Fuzzy] | {query-ref}/FuzzyQueryBuilder.html[FuzzyQueryBuilder] | {query-ref}/QueryBuilders.html#fuzzyQuery-java.lang.String-java.lang.String-[QueryBuilders.fuzzyQuery()]
|
||||
| {ref}/query-dsl-type-query.html[Type] | {query-ref}/TypeQueryBuilder.html[TypeQueryBuilder] | {query-ref}/QueryBuilders.html#typeQuery-java.lang.String-[QueryBuilders.typeQuery()]
|
||||
| {ref}/query-dsl-ids-query.html[Ids] | {query-ref}/IdsQueryBuilder.html[IdsQueryBuilder] | {query-ref}/QueryBuilders.html#idsQuery--[QueryBuilders.idsQuery()]
|
||||
|======
|
||||
|
||||
==== Compound queries
|
||||
[options="header"]
|
||||
|======
|
||||
| Search Query | QueryBuilder Class | Method in QueryBuilders
|
||||
| {ref}/query-dsl-constant-score-query.html[Constant Score] | {query-ref}/ConstantScoreQueryBuilder.html[ConstantScoreQueryBuilder] | {query-ref}/QueryBuilders.html#constantScoreQuery-org.elasticsearch.index.query.QueryBuilder-[QueryBuilders.constantScoreQuery()]
|
||||
| {ref}/query-dsl-bool-query.html[Bool] | {query-ref}/BoolQueryBuilder.html[BoolQueryBuilder] | {query-ref}/QueryBuilders.html#boolQuery--[QueryBuilders.boolQuery()]
|
||||
| {ref}/query-dsl-dis-max-query.html[Dis Max] | {query-ref}/DisMaxQueryBuilder.html[DisMaxQueryBuilder] | {query-ref}/QueryBuilders.html#disMaxQuery--[QueryBuilders.disMaxQuery()]
|
||||
| {ref}/query-dsl-function-score-query.html[Function Score] | {query-ref}/functionscore/FunctionScoreQueryBuilder.html[FunctionScoreQueryBuilder] | {query-ref}/QueryBuilders.html#functionScoreQuery-org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder.FilterFunctionBuilder:A-[QueryBuilders.functionScoreQuery()]
|
||||
| {ref}/query-dsl-boosting-query.html[Boosting] | {query-ref}/BoostingQueryBuilder.html[BoostingQueryBuilder] | {query-ref}/QueryBuilders.html#boostingQuery-org.elasticsearch.index.query.QueryBuilder-org.elasticsearch.index.query.QueryBuilder-[QueryBuilders.boostingQuery()]
|
||||
|======
|
||||
|
||||
==== Joining queries
|
||||
[options="header"]
|
||||
|======
|
||||
| Search Query | QueryBuilder Class | Method in QueryBuilders
|
||||
| {ref}/query-dsl-nested-query.html[Nested] | {query-ref}/NestedQueryBuilder.html[NestedQueryBuilder] | {query-ref}/QueryBuilders.html#nestedQuery-java.lang.String-org.elasticsearch.index.query.QueryBuilder-org.apache.lucene.search.join.ScoreMode-[QueryBuilders.nestedQuery()]
|
||||
| {ref}/query-dsl-has-child-query.html[Has Child] | {parentjoin-ref}/HasChildQueryBuilder.html[HasChildQueryBuilder] |
|
||||
| {ref}/query-dsl-has-parent-query.html[Has Parent] | {parentjoin-ref}/HasParentQueryBuilder.html[HasParentQueryBuilder] |
|
||||
| {ref}/query-dsl-parent-id-query.html[Parent Id] | {parentjoin-ref}/ParentIdQueryBuilder.html[ParentIdQueryBuilder] |
|
||||
|======
|
||||
|
||||
==== Geo queries
|
||||
[options="header"]
|
||||
|======
|
||||
| Search Query | QueryBuilder Class | Method in QueryBuilders
|
||||
| {ref}/query-dsl-geo-shape-query.html[GeoShape] | {query-ref}/GeoShapeQueryBuilder.html[GeoShapeQueryBuilder] | {query-ref}/QueryBuilders.html#geoShapeQuery-java.lang.String-java.lang.String-java.lang.String-[QueryBuilders.geoShapeQuery()]
|
||||
| {ref}/query-dsl-geo-bounding-box-query.html[Geo Bounding Box] | {query-ref}/GeoBoundingBoxQueryBuilder.html[GeoBoundingBoxQueryBuilder] | {query-ref}/QueryBuilders.html#geoBoundingBoxQuery-java.lang.String-[QueryBuilders.geoBoundingBoxQuery()]
|
||||
| {ref}/query-dsl-geo-distance-query.html[Geo Distance] | {query-ref}/GeoDistanceQueryBuilder.html[GeoDistanceQueryBuilder] | {query-ref}/QueryBuilders.html#geoDistanceQuery-java.lang.String-[QueryBuilders.geoDistanceQuery()]
|
||||
| {ref}/query-dsl-geo-polygon-query.html[Geo Polygon] | {query-ref}/GeoPolygonQueryBuilder.html[GeoPolygonQueryBuilder] | {query-ref}/QueryBuilders.html#geoPolygonQuery-java.lang.String-java.util.List-[QueryBuilders.geoPolygonQuery()]
|
||||
|======
|
||||
|
||||
==== Specialized queries
|
||||
[options="header"]
|
||||
|======
|
||||
| Search Query | QueryBuilder Class | Method in QueryBuilders
|
||||
| {ref}/query-dsl-mlt-query.html[More Like This] | {query-ref}/MoreLikeThisQueryBuilder.html[MoreLikeThisQueryBuilder] | {query-ref}/QueryBuilders.html#moreLikeThisQuery-org.elasticsearch.index.query.MoreLikeThisQueryBuilder.Item:A-[QueryBuilders.moreLikeThisQuery()]
|
||||
| {ref}/query-dsl-script-query.html[Script] | {query-ref}/ScriptQueryBuilder.html[ScriptQueryBuilder] | {query-ref}/QueryBuilders.html#scriptQuery-org.elasticsearch.script.Script-[QueryBuilders.scriptQuery()]
|
||||
| {ref}/query-dsl-percolate-query.html[Percolate] | {percolate-ref}/PercolateQueryBuilder.html[PercolateQueryBuilder] |
|
||||
|======
|
||||
|
||||
==== Span queries
|
||||
[options="header"]
|
||||
|======
|
||||
| Search Query | QueryBuilder Class | Method in QueryBuilders
|
||||
| {ref}/query-dsl-span-term-query.html[Span Term] | {query-ref}/SpanTermQueryBuilder.html[SpanTermQueryBuilder] | {query-ref}/QueryBuilders.html#spanTermQuery-java.lang.String-double-[QueryBuilders.spanTermQuery()]
|
||||
| {ref}/query-dsl-span-multi-term-query.html[Span Multi Term] | {query-ref}/SpanMultiTermQueryBuilder.html[SpanMultiTermQueryBuilder] | {query-ref}/QueryBuilders.html#spanMultiTermQueryBuilder-org.elasticsearch.index.query.MultiTermQueryBuilder-[QueryBuilders.spanMultiTermQueryBuilder()]
|
||||
| {ref}/query-dsl-span-first-query.html[Span First] | {query-ref}/SpanFirstQueryBuilder.html[SpanFirstQueryBuilder] | {query-ref}/QueryBuilders.html#spanFirstQuery-org.elasticsearch.index.query.SpanQueryBuilder-int-[QueryBuilders.spanFirstQuery()]
|
||||
| {ref}/query-dsl-span-near-query.html[Span Near] | {query-ref}/SpanNearQueryBuilder.html[SpanNearQueryBuilder] | {query-ref}/QueryBuilders.html#spanNearQuery-org.elasticsearch.index.query.SpanQueryBuilder-int-[QueryBuilders.spanNearQuery()]
|
||||
| {ref}/query-dsl-span-or-query.html[Span Or] | {query-ref}/SpanOrQueryBuilder.html[SpanOrQueryBuilder] | {query-ref}/QueryBuilders.html#spanOrQuery-org.elasticsearch.index.query.SpanQueryBuilder-[QueryBuilders.spanOrQuery()]
|
||||
| {ref}/query-dsl-span-not-query.html[Span Not] | {query-ref}/SpanNotQueryBuilder.html[SpanNotQueryBuilder] | {query-ref}/QueryBuilders.html#spanNotQuery-org.elasticsearch.index.query.SpanQueryBuilder-org.elasticsearch.index.query.SpanQueryBuilder-[QueryBuilders.spanNotQuery()]
|
||||
| {ref}/query-dsl-span-containing-query.html[Span Containing] | {query-ref}/SpanContainingQueryBuilder.html[SpanContainingQueryBuilder] | {query-ref}/QueryBuilders.html#spanContainingQuery-org.elasticsearch.index.query.SpanQueryBuilder-org.elasticsearch.index.query.SpanQueryBuilder-[QueryBuilders.spanContainingQuery()]
|
||||
| {ref}/query-dsl-span-within-query.html[Span Within] | {query-ref}/SpanWithinQueryBuilder.html[SpanWithinQueryBuilder] | {query-ref}/QueryBuilders.html#spanWithinQuery-org.elasticsearch.index.query.SpanQueryBuilder-org.elasticsearch.index.query.SpanQueryBuilder-[QueryBuilders.spanWithinQuery()]
|
||||
| {ref}/query-dsl-span-field-masking-query.html[Span Field Masking] | {query-ref}/FieldMaskingSpanQueryBuilder.html[FieldMaskingSpanQueryBuilder] | {query-ref}/QueryBuilders.html#fieldMaskingSpanQuery-org.elasticsearch.index.query.SpanQueryBuilder-java.lang.String-[QueryBuilders.fieldMaskingSpanQuery()]
|
||||
|======
|
||||
@ -82,8 +82,54 @@ After this, the `SearchSourceBuilder` only needs to be added to the
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-source-setter]
|
||||
--------------------------------------------------
|
||||
|
||||
===== Specifying Sorting
|
||||
===== Building queries
|
||||
|
||||
Search queries are created using `QueryBuilder` objects. A `QueryBuilder` exists
|
||||
for every search query type supported by Elasticsearch's {ref}/query-dsl.html[Query DSL].
|
||||
|
||||
A `QueryBuilder` can be created using its constructor:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-builder-ctor]
|
||||
--------------------------------------------------
|
||||
<1> Create a full text {ref}/query-dsl-match-query.html[Match Query] that matches
|
||||
the text "kimchy" over the field "user".
|
||||
|
||||
Once created, the `QueryBuilder` object provides methods to configure the options
|
||||
of the search query it creates:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-builder-options]
|
||||
--------------------------------------------------
|
||||
<1> Enable fuzzy matching on the match query
|
||||
<2> Set the prefix length option on the match query
|
||||
<3> Set the max expansion options to control the fuzzy
|
||||
process of the query
|
||||
|
||||
`QueryBuilder` objects can also be created using the `QueryBuilders` utility class.
|
||||
This class provides helper methods that can be used to create `QueryBuilder` objects
|
||||
using a fluent programming style:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-builders]
|
||||
--------------------------------------------------
|
||||
|
||||
Whatever the method used to create it, the `QueryBuilder` object must be added
|
||||
to the `SearchSourceBuilder` as follows:
|
||||
|
||||
["source","java",subs="attributes,callouts,macros"]
|
||||
--------------------------------------------------
|
||||
include-tagged::{doc-tests}/SearchDocumentationIT.java[search-query-setter]
|
||||
--------------------------------------------------
|
||||
|
||||
The <<java-rest-high-search-queries, Search Queries>> page gives a list of all available search queries with
|
||||
their corresponding `QueryBuilder` objects and `QueryBuilders` helper methods.
|
||||
|
||||
|
||||
===== Specifying Sorting
|
||||
|
||||
The `SearchSourceBuilder` allows to add one or more `SortBuilder` instances. There are four special implementations (Field-, Score-, GeoDistance- and ScriptSortBuilder).
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user