honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #14189 from MaineC/doc-fix/13800 

Updates java query dsl documentation
This commit is contained in:
Isabel Drost-Fromm 2015-10-20 10:56:43 +02:00
parent d2867c5d96 dac88c0281
commit 4338ffc8a7
24 changed files with 473 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

393
core/src/test/java/org/elasticsearch/index/query/QueryDSLDocumentationTests.java Normal file
View File

@ -0,0 +1,393 @@
/*
* Licensed to Elasticsearch under one or more contributor
* license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright
* ownership. Elasticsearch licenses this file to you under
* the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.elasticsearch.index.query;
import org.apache.lucene.search.join.ScoreMode;
import org.elasticsearch.common.geo.GeoDistance;
import org.elasticsearch.common.geo.GeoPoint;
import org.elasticsearch.common.geo.ShapeRelation;
import org.elasticsearch.common.geo.builders.ShapeBuilder;
import org.elasticsearch.common.unit.DistanceUnit;
import org.elasticsearch.index.query.MoreLikeThisQueryBuilder.Item;
import org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder;
import org.elasticsearch.index.query.functionscore.FunctionScoreQueryBuilder.FilterFunctionBuilder;
import org.elasticsearch.script.Script;
import org.elasticsearch.script.ScriptService.ScriptType;
import org.junit.Test;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import static org.elasticsearch.index.query.QueryBuilders.*;
import static org.elasticsearch.index.query.functionscore.ScoreFunctionBuilders.*;
/**
* If one of the following tests doesn't compile make sure to not only fix the compilation error here
* but also the documentation under ./docs/java-api/query-dsl/bool-query.asciidoc
*
* There are no assertions here on purpose - all of these tests ((ideally) should) equal to what is
* documented in the java api query dsl part of our reference guide.
* */
public class QueryDSLDocumentationTests {
@Test
public void testBool() {
boolQuery()
.must(termQuery("content", "test1"))
.must(termQuery("content", "test4"))
.mustNot(termQuery("content", "test2"))
.should(termQuery("content", "test3"))
.filter(termQuery("content", "test5"));
}
@Test
public void testBoosting() {
boostingQuery(termQuery("name","kimchy"), termQuery("name","dadoonet"))
.negativeBoost(0.2f);
}
@Test
public void testCommonTerms() {
commonTermsQuery("name", "kimchy");
}
@Test
public void testConstantScore() {
constantScoreQuery(termQuery("name","kimchy"))
.boost(2.0f);
}
@Test
public void testDisMax() {
disMaxQuery()
.add(termQuery("name", "kimchy"))
.add(termQuery("name", "elasticsearch"))
.boost(1.2f)
.tieBreaker(0.7f);
}
@Test
public void testExists() {
existsQuery("name");
}
@Test
public void testFunctionScore() {
FilterFunctionBuilder[] functions = {
new FunctionScoreQueryBuilder.FilterFunctionBuilder(
matchQuery("name", "kimchy"),
randomFunction("ABCDEF")),
new FunctionScoreQueryBuilder.FilterFunctionBuilder(
exponentialDecayFunction("age", 0L, 1L))
};
functionScoreQuery(functions);
}
@Test
public void testFuzzy() {
fuzzyQuery("name", "kimchy");
}
@Test
public void testGeoBoundingBox() {
geoBoundingBoxQuery("pin.location").setCorners(40.73, -74.1, 40.717, -73.99);
}
@Test
public void testGeoDistance() {
geoDistanceQuery("pin.location")
.point(40, -70)
.distance(200, DistanceUnit.KILOMETERS)
.optimizeBbox("memory") // TODO switch to geoexectype see also bounding box
.geoDistance(GeoDistance.ARC);
}
@Test
public void testGeoDistanceRange() {
geoDistanceRangeQuery("pin.location", new GeoPoint(40, -70)) // TODO check why I need the point here but not above
.from("200km")
.to("400km")
.includeLower(true)
.includeUpper(false)
.optimizeBbox("memory")
.geoDistance(GeoDistance.ARC);
}
@Test
public void testGeoPolygon() {
List<GeoPoint> points = new ArrayList<GeoPoint>();
points.add(new GeoPoint(40, -70));
points.add(new GeoPoint(30, -80));
points.add(new GeoPoint(20, -90));
geoPolygonQuery("pin.location", points);
}
@Test
public void testGeoShape() throws IOException {
GeoShapeQueryBuilder qb = geoShapeQuery(
"pin.location",
ShapeBuilder.newMultiPoint()
.point(0, 0)
.point(0, 10)
.point(10, 10)
.point(10, 0)
.point(0, 0));
qb.relation(ShapeRelation.WITHIN);
qb = geoShapeQuery(
"pin.location",
"DEU",
"countries");
qb.relation(ShapeRelation.WITHIN)
.indexedShapeIndex("shapes")
.indexedShapePath("location");
}
@Test
public void testGeoHashCell() {
geoHashCellQuery("pin.location",
new GeoPoint(13.4080, 52.5186))
.neighbors(true)
.precision(3);
}
@Test
public void testHasChild() {
hasChildQuery(
"blog_tag",
termQuery("tag","something")
);
}
@Test
public void testHasParent() {
hasParentQuery(
"blog",
termQuery("tag","something")
);
}
@Test
public void testIds() {
idsQuery("my_type", "type2")
.addIds("1", "4", "100");
idsQuery().addIds("1", "4", "100");
}
@Test
public void testIndices() {
indicesQuery(
termQuery("tag", "wow"),
"index1", "index2"
).noMatchQuery(termQuery("tag", "kow"));
indicesQuery(
termQuery("tag", "wow"),
"index1", "index2"
).noMatchQuery("all");
}
@Test
public void testMatchAll() {
matchAllQuery();
}
@Test
public void testMatch() {
matchQuery("name", "kimchy elasticsearch");
}
@Test
public void testMissing() {
missingQuery("user", true, true);
}
@Test
public void testMLT() {
String[] fields = {"name.first", "name.last"};
String[] texts = {"text like this one"};
Item[] items = null;
moreLikeThisQuery(fields, texts, items)
.minTermFreq(1)
.maxQueryTerms(12);
}
@Test
public void testMultiMatch() {
multiMatchQuery("kimchy elasticsearch", "user", "message");
}
@Test
public void testNested() {
nestedQuery(
"obj1",
boolQuery()
.must(matchQuery("obj1.name", "blue"))
.must(rangeQuery("obj1.count").gt(5))
)
.scoreMode(ScoreMode.Avg);
}
@Test
public void testNot() {
notQuery(rangeQuery("price").from("1").to("2"));
}
@Test
public void testPrefix() {
prefixQuery("brand", "heine");
}
@Test
public void testQueryString() {
queryStringQuery("+kimchy -elasticsearch");
}
@Test
public void testRange() {
rangeQuery("price")
.from(5)
.to(10)
.includeLower(true)
.includeUpper(false);
rangeQuery("age")
.gte("10")
.lt("20");
}
@Test
public void testRegExp() {
regexpQuery("name.first", "s.*y");
}
@Test
public void testScript() {
scriptQuery(
new Script("doc['num1'].value > 1")
);
Map<String, Integer> parameters = new HashMap<>();
parameters.put("param1", 5);
scriptQuery(
new Script(
"mygroovyscript",
ScriptType.FILE,
"groovy",
parameters)
);
}
@Test
public void testSimpleQueryString() {
simpleQueryStringQuery("+kimchy -elasticsearch");
}
@Test
public void testSpanContaining() {
spanContainingQuery(
spanNearQuery(spanTermQuery("field1","bar"), 5)
.clause(spanTermQuery("field1","baz"))
.inOrder(true),
spanTermQuery("field1","foo"));
}
@Test
public void testSpanFirst() {
spanFirstQuery(
spanTermQuery("user", "kimchy"),
3
);
}
@Test
public void testSpanMultiTerm() {
spanMultiTermQueryBuilder(prefixQuery("user", "ki"));
}
@Test
public void testSpanNear() {
spanNearQuery(spanTermQuery("field","value1"), 12)
.clause(spanTermQuery("field","value2"))
.clause(spanTermQuery("field","value3"))
.inOrder(false)
.collectPayloads(false);
}
@Test
public void testSpanNot() {
spanNotQuery(spanTermQuery("field","value1"),
spanTermQuery("field","value2"));
}
@Test
public void testSpanOr() {
spanOrQuery(spanTermQuery("field","value1"))
.clause(spanTermQuery("field","value2"))
.clause(spanTermQuery("field","value3"));
}
@Test
public void testSpanTerm() {
spanTermQuery("user", "kimchy");
}
@Test
public void testSpanWithin() {
spanWithinQuery(
spanNearQuery(spanTermQuery("field1", "bar"), 5)
.clause(spanTermQuery("field1", "baz"))
.inOrder(true),
spanTermQuery("field1", "foo"));
}
@Test
public void testTemplate() {
templateQuery(
"gender_template",
ScriptType.INDEXED,
new HashMap<>());
}
@Test
public void testTerm() {
termQuery("name", "kimchy");
}
@Test
public void testTerms() {
termsQuery("tags", "blue", "pill");
}
@Test
public void testType() {
typeQuery("my_type");
}
@Test
public void testWildcard() {
wildcardQuery("user", "k?mch*");
}
}

15
docs/java-api/query-dsl/and-query.asciidoc
View File

@ -1,15 +0,0 @@
[[java-query-dsl-and-query]]
==== And Query
deprecated[2.0.0, Use the `bool` query instead]
See {ref}/query-dsl-and-query.html[And Query]
[source,java]
--------------------------------------------------
QueryBuilder query = andQuery(
rangeQuery("postDate").from("2010-03-01").to("2010-04-01"), <1>
prefixQuery("name.second", "ba")); <1>
--------------------------------------------------
<1> queries

5
docs/java-api/query-dsl/bool-query.asciidoc
View File

@ -9,10 +9,11 @@ QueryBuilder qb = boolQuery()
.must(termQuery("content", "test1")) <1>
.must(termQuery("content", "test4")) <1>
.mustNot(termQuery("content", "test2")) <2>
.should(termQuery("content", "test3")); <3>
.should(termQuery("content", "test3")) <3>
.filter(termQuery("content", "test5")); <4>
--------------------------------------------------
<1> must query
<2> must not query
<3> should query
<4> a query that must appear in the matching documents but doesn't contribute to scoring.

6
docs/java-api/query-dsl/boosting-query.asciidoc
View File

@ -5,9 +5,9 @@ See {ref}/query-dsl-boosting-query.html[Boosting Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = boostingQuery()
.positive(termQuery("name","kimchy")) <1>
.negative(termQuery("name","dadoonet")) <2>
QueryBuilder qb = boostingQuery(
termQuery("name","kimchy"), <1>
termQuery("name","dadoonet")) <2>
.negativeBoost(0.2f); <3>
--------------------------------------------------
<1> query that will promote documents

15
docs/java-api/query-dsl/compound-queries.asciidoc
View File

@ -41,18 +41,6 @@ documents which also match a `negative` query.
Execute one query for the specified indices, and another for other indices.
<<java-query-dsl-and-query,`and`>>, <<java-query-dsl-or-query,`or`>>, <<java-query-dsl-not-query,`not`>>::
Synonyms for the `bool` query.
<<java-query-dsl-filtered-query,`filtered` query>>::
Combine a query clause in query context with another in filter context. deprecated[2.0.0,Use the `bool` query instead]
<<java-query-dsl-limit-query,`limit` query>>::
Limits the number of documents examined per shard.
include::constant-score-query.asciidoc[]
include::bool-query.asciidoc[]
@ -60,10 +48,7 @@ include::dis-max-query.asciidoc[]
include::function-score-query.asciidoc[]
include::boosting-query.asciidoc[]
include::indices-query.asciidoc[]
include::and-query.asciidoc[]
include::not-query.asciidoc[]
include::or-query.asciidoc[]
include::filtered-query.asciidoc[]
include::limit-query.asciidoc[]

17
docs/java-api/query-dsl/filtered-query.asciidoc
View File

@ -1,17 +0,0 @@
[[java-query-dsl-filtered-query]]
==== Filtered Query
deprecated[2.0.0, Use the `bool` query instead with a `must` clause for the query and a `filter` clause for the filter]
See {ref}/query-dsl-filtered-query.html[Filtered Query].
[source,java]
--------------------------------------------------
QueryBuilder qb = filteredQuery(
matchQuery("name", "kimchy"), <1>
rangeQuery("dateOfBirth").from("1900").to("2100") <2>
);
--------------------------------------------------
<1> query which will be used for scoring
<2> query which will only be used for filtering the result set

13
docs/java-api/query-dsl/function-score-query.asciidoc
View File

@ -12,14 +12,13 @@ import static org.elasticsearch.index.query.functionscore.ScoreFunctionBuilders.
[source,java]
--------------------------------------------------
QueryBuilder qb = functionScoreQuery()
.add(
FilterFunctionBuilder[] functions = {
new FunctionScoreQueryBuilder.FilterFunctionBuilder(
matchQuery("name", "kimchy"), <1>
randomFunction("ABCDEF") <2>
)
.add(
exponentialDecayFunction("age", 0L, 1L) <3>
);
randomFunction("ABCDEF")), <2>
new FunctionScoreQueryBuilder.FilterFunctionBuilder(
exponentialDecayFunction("age", 0L, 1L)) <3>
};
--------------------------------------------------
<1> Add a first function based on a query
<2> And randomize the score based on a given seed

4
docs/java-api/query-dsl/geo-bounding-box-query.asciidoc
View File

@ -6,8 +6,8 @@ See {ref}/query-dsl-geo-bounding-box-query.html[Geo Bounding Box Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = geoBoundingBoxQuery("pin.location") <1>
.topLeft(40.73, -74.1) <2>
.bottomRight(40.717, -73.99); <3>
.setCorners(40.73, -74.1, <2>
40.717, -73.99); <3>
--------------------------------------------------
<1> field
<2> bounding box top left point

4
docs/java-api/query-dsl/geo-distance-range-query.asciidoc
View File

@ -5,8 +5,8 @@ See {ref}/query-dsl-geo-distance-range-query.html[Geo Distance Range Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = geoDistanceRangeQuery("pin.location") <1>
.point(40, -70) <2>
QueryBuilder qb = geoDistanceRangeQuery("pin.location", <1>
new GeoPoint(40, -70)) <2>
.from("200km") <3>
.to("400km") <4>
.includeLower(true) <5>

17
docs/java-api/query-dsl/geo-polygon-query.asciidoc
View File

@ -5,11 +5,14 @@ See {ref}/query-dsl-geo-polygon-query.html[Geo Polygon Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = geoPolygonQuery("pin.location") <1>
.addPoint(40, -70) <2>
.addPoint(30, -80) <2>
.addPoint(20, -90); <2>
--------------------------------------------------
<1> field
<2> add your polygon of points a document should fall within
List<GeoPoint> points = new ArrayList<GeoPoint>(); <1>
points.add(new GeoPoint(40, -70));
points.add(new GeoPoint(30, -80));
points.add(new GeoPoint(20, -90));
QueryBuilder qb =
geoPolygonQuery("pin.location", points); <2>
--------------------------------------------------
<1> add your polygon of points a document should fall within
<2> initialise the query with field and points

13
docs/java-api/query-dsl/geo-shape-query.asciidoc
View File

@ -39,15 +39,16 @@ import org.elasticsearch.common.geo.builders.ShapeBuilder;
[source,java]
--------------------------------------------------
QueryBuilder qb = geoShapeQuery(
GeoShapeQueryBuilder qb = geoShapeQuery(
"pin.location", <1>
ShapeBuilder.newMultiPoint() <2>
.point(0, 0)
.point(0, 10)
.point(10, 10)
.point(10, 0)
.point(0, 0),
ShapeRelation.WITHIN); <3>
.point(0, 0));
qb.relation(ShapeRelation.WITHIN); <3>
--------------------------------------------------
<1> field
<2> shape
@ -56,11 +57,11 @@ QueryBuilder qb = geoShapeQuery(
[source,java]
--------------------------------------------------
// Using pre-indexed shapes
QueryBuilder qb = geoShapeQuery(
GeoShapeQueryBuilder qb = geoShapeQuery(
"pin.location", <1>
"DEU", <2>
"countries", <3>
ShapeRelation.WITHIN) <4>
"countries"); <3>
qb.relation(ShapeRelation.WITHIN)) <4>
.indexedShapeIndex("shapes") <5>
.indexedShapePath("location"); <6>
--------------------------------------------------

11
docs/java-api/query-dsl/limit-query.asciidoc
View File

@ -1,11 +0,0 @@
[[java-query-dsl-limit-query]]
==== Limit Query
See {ref}/query-dsl-limit-query.html[Limit Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = limitQuery(100); <1>
--------------------------------------------------
<1> number of documents per shard

11
docs/java-api/query-dsl/missing-query.asciidoc
View File

@ -5,11 +5,10 @@ See {ref}/query-dsl-missing-query.html[Missing Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = missingQuery("user"); <1>
.existence(true) <2>
.nullValue(true); <3>
QueryBuilder qb = missingQuery("user", <1>
true, <2>
true); <3>
--------------------------------------------------
<1> field
<2> find missing field that doesn’t exist
<3> find missing field with an explicit `null` value
<2> find missing field with an explicit `null` value
<3> find missing field that doesn’t exist

7
docs/java-api/query-dsl/mlt-query.asciidoc
View File

@ -6,8 +6,11 @@ See:
[source,java]
--------------------------------------------------
QueryBuilder qb = moreLikeThisQuery("name.first", "name.last") <1>
.like("text like this one") <2>
String[] fields = {"name.first", "name.last"}; <1>
String[] texts = {"text like this one"}; <2>
Item[] items = null;
QueryBuilder qb = moreLikeThisQuery(fields, texts, items)
.minTermFreq(1) <3>
.maxQueryTerms(12); <4>
--------------------------------------------------

2
docs/java-api/query-dsl/nested-query.asciidoc
View File

@ -11,7 +11,7 @@ QueryBuilder qb = nestedQuery(
.must(matchQuery("obj1.name", "blue"))
.must(rangeQuery("obj1.count").gt(5))
)
.scoreMode("avg"); <3>
.scoreMode(ScoreMode.Avg); <3>
--------------------------------------------------
<1> path to nested document
<2> your query. Any fields referenced inside the query must use the complete path (fully qualified).

16
docs/java-api/query-dsl/or-query.asciidoc
View File

@ -1,16 +0,0 @@
[[java-query-dsl-or-query]]
==== Or Query
deprecated[2.0.0, Use the `bool` query instead]
See {ref}/query-dsl-or-query.html[Or Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = orQuery(
rangeQuery("price").from(1).to(2), <1>
matchQuery("name", "joe") <1>
);
--------------------------------------------------
<1> queries

4
docs/java-api/query-dsl/script-query.asciidoc
View File

@ -26,7 +26,7 @@ You can use it then with:
QueryBuilder qb = scriptQuery(
new Script(
"mygroovyscript", <1>
ScriptService.ScriptType.FILE, <2>
ScriptType.FILE, <2>
"groovy", <3>
ImmutableMap.of("param1", 5)) <4>
);
@ -36,4 +36,4 @@ QueryBuilder qb = scriptQuery(
<3> Scripting engine
<4> Parameters as a `Map` of `<String, Object>`
æ

15
docs/java-api/query-dsl/span-containing-query.asciidoc
View File

@ -5,15 +5,12 @@ See {ref}/query-dsl-span-containing-query.html[Span Containing Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanContainingQuery()
.little(spanTermQuery("field1","foo")) <1>
.big(spanNearQuery() <2>
.clause(spanTermQuery("field1","bar"))
QueryBuilder qb = spanContainingQuery(
spanNearQuery(spanTermQuery("field1","bar"), 5) <1>
.clause(spanTermQuery("field1","baz"))
.slop(5)
.inOrder(true)
);
.inOrder(true),
spanTermQuery("field1","foo")); <2>
--------------------------------------------------
<1> `little` part
<2> `big` part
<1> `big` part
<2> `little` part

6
docs/java-api/query-dsl/span-near-query.asciidoc
View File

@ -5,11 +5,11 @@ See {ref}/query-dsl-span-near-query.html[Span Near Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanNearQuery()
.clause(spanTermQuery("field","value1")) <1>
QueryBuilder qb = spanNearQuery(
spanTermQuery("field","value1"), <1>
12) <2>
.clause(spanTermQuery("field","value2")) <1>
.clause(spanTermQuery("field","value3")) <1>
.slop(12) <2>
.inOrder(false) <3>
.collectPayloads(false); <4>
--------------------------------------------------

6
docs/java-api/query-dsl/span-not-query.asciidoc
View File

@ -5,9 +5,9 @@ See {ref}/query-dsl-span-not-query.html[Span Not Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanNotQuery()
.include(spanTermQuery("field","value1")) <1>
.exclude(spanTermQuery("field","value2")); <2>
QueryBuilder qb = spanNotQuery(
spanTermQuery("field","value1"), <1>
spanTermQuery("field","value2")); <2>
--------------------------------------------------
<1> span query whose matches are filtered
<2> span query whose matches must not overlap those returned

4
docs/java-api/query-dsl/span-or-query.asciidoc
View File

@ -5,8 +5,8 @@ See {ref}/query-dsl-span-or-query.html[Span Or Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanOrQuery()
.clause(spanTermQuery("field","value1")) <1>
QueryBuilder qb = spanOrQuery(
spanTermQuery("field","value1")) <1>
.clause(spanTermQuery("field","value2")) <1>
.clause(spanTermQuery("field","value3")); <1>
--------------------------------------------------

15
docs/java-api/query-dsl/span-within-query.asciidoc
View File

@ -5,14 +5,11 @@ See {ref}/query-dsl-span-within-query.html[Span Within Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = spanWithinQuery()
.little(spanTermQuery("field1", "foo")) <1>
.big(spanNearQuery() <2>
.clause(spanTermQuery("field1", "bar"))
QueryBuilder qb = spanWithinQuery(
spanNearQuery(spanTermQuery("field1", "bar"), 5) <1>
.clause(spanTermQuery("field1", "baz"))
.slop(5)
.inOrder(true)
);
.inOrder(true),
spanTermQuery("field1", "foo")); <2>
--------------------------------------------------
<1> `little` part
<2> `big` part
<1> `big` part
<2> `little` part

2
docs/java-api/query-dsl/template-query.asciidoc
View File

@ -62,7 +62,7 @@ To execute an indexed templates, use `ScriptService.ScriptType.INDEXED`:
--------------------------------------------------
QueryBuilder qb = templateQuery(
"gender_template", <1>
ScriptService.ScriptType.INDEXED, <2>
ScriptType.INDEXED, <2>
template_params); <3>
--------------------------------------------------
<1> template name

2
docs/java-api/query-dsl/term-query.asciidoc
View File

@ -5,7 +5,7 @@ See {ref}/query-dsl-term-query.html[Term Query]
[source,java]
--------------------------------------------------
QueryBuilder qb = term(
QueryBuilder qb = termQuery(
"name", <1>
"kimchy" <2>
);