Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add website documentation for queries #223

Merged
merged 7 commits into from
May 22, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions docs/overview/queries/elastic_query_bool.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
id: elastic_query_bool
title: "Boolean Query"
---

The query that matches documents matching boolean combinations of other queries. It is built using one or more boolean clauses (queries):
- `filter`: The clause (query) must appear in matching documents. However, unlike `must` the score of the query will be ignored.
- `must`: the clause (query) must appear in matching documents and will contribute to the score.
- `must not`: the clause (query) must not appear in the matching documents.
- `should`: the clause (query) should appear in the matching document.

In order to use the `Bool` query import the following:
```scala
import zio.elasticsearch.query.BoolQuery
import zio.elasticsearch.ElasticQuery._
```

The `Bool` query can be created with `filter`, `must`, `mustNot` or `should` method:
```scala
val filterQuery: BoolQuery = filter(contains(field = Document.name, value = "a"), startsWith(field = Document.id, value = "b"))
val mustQuery: BoolQuery = must(contains(field = Document.name, value = "a"), startsWith(field = Document.id, value = "b"))
val mustNotQuery: BoolQuery = mustNot(contains(field = Document.name, value = "a"))
val shouldQuery: BoolQuery = should(startsWith(field = Document.name, value = "a"))
```

Once the `Bool` query is created, you can call `filter`, `must`, `mustNot`, `should`, `boost` and `minimumShouldMatch` methods on it.

If you want to add `Filter` query to `Bool` query, you can use `filter` method (you can also call `filter` method on `Bool` query that is created with `filter` method):
```scala
val filterQuery: BoolQuery = filter(contains(field = Document.name, value = "a")).filter(contains(field = Document.name, value = "c"))
```

If you want to add `Must` query to the `Bool` query, you can use `must` method:
```scala
val boolQuery: BoolQuery = filter(contains(field = Document.name, value = "a")).must(contains(field = Document.name, value = "c"))
```

If you want to add `MustNot` query to the `Bool` query, you can use `mustNot` method:
```scala
val boolQuery: BoolQuery = filter(contains(field = Document.name, value = "a")).mustNot(contains(field = Document.name, value = "c"))
```

If you want to add `Should` query to the `Bool` query, you can use `should` method:
```scala
val boolQuery: BoolQuery = filter(contains(field = Document.name, value = "a")).should(contains(field = Document.name, value = "c"))
```

If you want to change the `_score` parameter, you can use the `boost` method:
```scala
val queryWithBoost: BoolQuery = filter(contains(field = Document.name, value = "a")).boost(1.2)
```

If you want to change the `minimum_should_match` parameter, you can use the `minimumShouldMatch` method:
```scala
val queryWithMinimumShouldMatch: BoolQuery = should(contains(field = Document.name, value = "a")).minimumShouldMatch(2)
```

You can find more information about Boolean Query [here](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/query-dsl-bool-query.html).
6 changes: 0 additions & 6 deletions docs/overview/queries/elastic_query_contains.md

This file was deleted.

20 changes: 19 additions & 1 deletion docs/overview/queries/elastic_query_exists.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,22 @@ id: elastic_query_exists
title: "Exists Query"
---

TBD
The `Exists` query is used for returning documents that contain an indexed value for a field.

In order to use the `Exists` query import the following:
```scala
import zio.elasticsearch.query.ExistsQuery
import zio.elasticsearch.ElasticQuery._
```

You can create an `Exists` query using the `exists` method this way:
```scala
val query: ExistsQuery = exists(field = "name")
```

Also, you can create a [type-safe](https://lambdaworks.github.io/zio-elasticsearch/overview/overview_zio_prelude_schema) `Exists` query using the `exists` method this way:
```scala
val query: ExistsQuery = exists(field = Document.name)
```

You can find more information about Exists query [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-exists-query.html#query-dsl-exists-query).
6 changes: 0 additions & 6 deletions docs/overview/queries/elastic_query_filter.md

This file was deleted.

60 changes: 60 additions & 0 deletions docs/overview/queries/elastic_query_geo_distance.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
id: elastic_query_geo_distance
title: "Geo-distance Query"
---

The `GeoDistance` query matches [geo_point](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/geo-point.html) and [geo_shape](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/geo-shape.html) values within a given distance of a geopoint.

In order to use the `GeoDistance` query import the following:
```scala
import zio.elasticsearch.query.GeoDistanceQuery
import zio.elasticsearch.ElasticQuery._
```

You can create a `GeoDistance` query using the `geoDistance` method with latitude and longitude in the following manner:
```scala
val query: GeoDistanceQuery = geoDistance(field = "location", latitude = 20.0, longitude = 20.0)
```

You can create a [type-safe](https://lambdaworks.github.io/zio-elasticsearch/overview/overview_zio_prelude_schema) `GeoDistance` query using the `geoDistance` method with latitude and longitude in the following manner:
```scala
val query: GeoDistanceQuery = geoDistance(field = Document.location, latitude = 20.0, longitude = 20.0)
```

You can create a `GeoDistance` query using the `geoDistance` method with coordinates in the following manner:
```scala
val query: GeoDistanceQuery = geoDistance(field = "location", coordinates = "40,31")
```

You can create a [type-safe](https://lambdaworks.github.io/zio-elasticsearch/overview/overview_zio_prelude_schema) `GeoDistance` query using the `geoDistance` method with coordinates in the following manner:
```scala
val query: GeoDistanceQuery = geoDistance(field = Document.location, coordinates = "40,31")
```

If you want to change the `distance`, you can use `distance` method:
```scala
import zio.elasticsearch.query.DistanceUnit

val queryWithDistance: GeoDistanceQuery = geoDistance(field = "location", coordinates = "40,31").distance(value = 20.0, unit = DistanceUnit.Kilometers)
```

If you want to change the `distance_type`, you can use `distanceType` method:
```scala
import zio.elasticsearch.query.DistanceType

val queryWithDistanceType: GeoDistanceQuery = geoDistance(field = "location", coordinates = "40,31").distanceType(value = DistanceType.Plane)
```

If you want to change the `_name`, you can use `name` method:
```scala
val queryWithName: GeoDistanceQuery = geoDistance(field = "location", coordinates = "40,31").name("name")
```

If you want to change the `validation_method`, you can use `validationMethod` method:
```scala
import zio.elasticsearch.query.ValidationMethod

val queryWithValidationMethod: GeoDistanceQuery = geoDistance(field = "location", coordinates = "40,31").validationMethod(value = ValidationMethod.IgnoreMalformed)
```

You can find more information about `GeoDistance` query [here](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/query-dsl-geo-distance-query.html#query-dsl-geo-distance-query).
41 changes: 40 additions & 1 deletion docs/overview/queries/elastic_query_has_child.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,43 @@ id: elastic_query_has_child
title: "Has Child Query"
---

TBD
The `HasChild` query returns parent documents whose child documents match a provided query.

To create a `HasChild` query do the following:
```scala
import zio.elasticsearch.query.HasChildQuery
import zio.elasticsearch.ElasticQuery._

val query: HasChildQuery = hasChild(childType = "child", query = matches(Document.stringField, "test"))
```

If you want to change `ignore_unmapped`, you can use `ignoreUnmapped` method:
```scala
val queryWithIgnoreUnmapped: HasChildQuery = hasChild(childType = "child", query = matches(Document.stringField, "test")).ignoreUnmapped(true)
```

If you want to change `inner_hits`, you can use `innerHits` method:
```scala
import zio.elasticsearch.query.InnerHits

val queryWithInnerHits: HasChildQuery = hasChild(childType = "child", query = matches(Document.stringField, "test")).innerHits(innerHits = InnerHits.from(5))
```

If you want to change `max_children`, you can use `maxChildren` method:
```scala
val queryWithMaxChildren: HasChildQuery = hasChild(childType = "child", query = matches(Document.stringField, "test")).maxChildren(5)
```

If you want to change `min_children`, you can use `minChildren` method:
```scala
val queryWithMinChildren: HasChildQuery = hasChild(childType = "child", query = matches(Document.stringField, "test")).minChildren(2)
```

If you want to change `score_mode`, you can use `scoreMode` method:
```scala
import zio.elasticsearch.query.ScoreMode

val queryWithScoreMode: HasChildQuery = hasChild(childType = "child", query = matches(Document.stringField, "test")).scoreMode(ScoreMode.Max)
```

You can find more information about `HasChild` query [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-has-child-query.html).
31 changes: 30 additions & 1 deletion docs/overview/queries/elastic_query_has_parent.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,33 @@ id: elastic_query_has_parent
title: "Has Parent Query"
---

TBD
The `HasParent` query returns child documents whose parent document matches a provided query.

To create a `HasParent` query do the following:
```scala
import zio.elasticsearch.query.HasParentQuery
import zio.elasticsearch.ElasticQuery._

val query: HasParentQuery = hasParent(parentType = "parent", query = matches(Document.stringField, "test"))
```

If you want to change `ignore_unmapped`, you can use `ignoreUnmapped` method:
```scala
val queryWithIgnoreUnmapped: HasParentQuery = hasParent(parentType = "parent", query = matches(Document.stringField, "test")).ignoreUnmapped(true)
```

If you want to change `inner_hits`, you can use `innerHits` method:
```scala
import zio.elasticsearch.query.InnerHits

val queryWithInnerHits: HasParentQuery = hasParent(parentType = "parent", query = matches(Document.stringField, "test")).innerHits(innerHits = InnerHits.from(5))
```

If you want to change `score`, you can use `withScore`, `withScoreFalse` or `withScoreTrue` method:
```scala
val queryWithScore: HasParentQuery = hasParent(parentType = "parent", query = matches(Document.intField, "test")).withScore(true)
val queryWithScoreFalse: HasParentQuery = hasParent(parentType = "parent", query = matches(Document.intField, "test")).withScoreFalse
val queryWithScoreTrue: HasParentQuery = hasParent(parentType = "parent", query = matches(Document.intField, "test")).withScoreTrue
```

You can find more information about `HasParent` query [here](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/query-dsl-has-parent-query.html).
26 changes: 26 additions & 0 deletions docs/overview/queries/elastic_query_match.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
id: elastic_query_match
title: "Match Query"
---

The `Match` query is a type of query that searches for a provided text, number, date or boolean value.
This is the standard query for performing a full-text search, including options for fuzzy matching.

In order to use the `Match` query import the following:

```scala
import zio.elasticsearch.query.MatchQuery
import zio.elasticsearch.ElasticQuery._
```

You can create a `Match` query using the `matches` method in the following manner:
```scala
val query: MatchQuery = matches(field = "message", value = "this is a test")
```

You can create a [type-safe](https://lambdaworks.github.io/zio-elasticsearch/overview/overview_zio_prelude_schema) `Match` query using the `matches` method in the following manner:
```scala
val query: MatchQuery = matches(field = Document.message, value = "this is a test")
```

You can find more information about `Match` query [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query.html#query-dsl-match-query).
8 changes: 4 additions & 4 deletions docs/overview/queries/elastic_query_match_all.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,19 @@ id: elastic_query_match_all
title: "Match All Query"
---

The most simple query, which matches all documents, giving them all a `_score` of `1.0`.
The most simple query, which matches all documents, giving them all a `score` of `1.0`.

To create a `MatchAll` query do the following:

```scala
import zio.elasticsearch.query.MatchAllQuery
import zio.elasticsearch.ElasticQuery._

val query: MatchAllQuery = matchAll
```

If you want to change the `_score`, you can use the `boost` method:

If you want to change the `boost`, you can use the `boost` method:
```scala
val queryWithBoost: MatchAllQuery = matchAll.boost(1.2)
```

You can find more information about `MatchAll` query [here](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/query-dsl-match-all-query.html).
20 changes: 19 additions & 1 deletion docs/overview/queries/elastic_query_match_phrase.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,22 @@ id: elastic_query_match_phrase
title: "Match Phrase Query"
---

TBD
The `MatchPhrase` query analyzes the text and creates a `phrase` query out of the analyzed text.

In order to use the `MatchPhrase` query import the following:
```scala
import zio.elasticsearch.query.MatchPhraseQuery
import zio.elasticsearch.ElasticQuery._
```

You can create a `MatchPhrase` query using the `matchPhrase` method this way:
```scala
val query: MatchPhraseQuery = matchPhrase(field = "stringField", value = "test")
```

You can create a [type-safe](https://lambdaworks.github.io/zio-elasticsearch/overview/overview_zio_prelude_schema) `MatchPhrase` query using the `matchPhrase` method this way:
```scala
val query: MatchPhraseQuery = matchPhrase(field = Document.stringField, value = "test")
```

You can find more information about `MatchPhrase` query [here](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/query-dsl-match-query-phrase.html).
6 changes: 0 additions & 6 deletions docs/overview/queries/elastic_query_matches.md

This file was deleted.

6 changes: 0 additions & 6 deletions docs/overview/queries/elastic_query_must.md

This file was deleted.

6 changes: 0 additions & 6 deletions docs/overview/queries/elastic_query_must_not.md

This file was deleted.

39 changes: 38 additions & 1 deletion docs/overview/queries/elastic_query_nested.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,41 @@ id: elastic_query_nested
title: "Nested Query"
---

TBD
The `Nested` query searches nested field objects as if they were indexed as separate documents. If an object matches the search, the Nested query returns the root parent document.

In order to use the `Nested` query import the following:
```scala
import zio.elasticsearch.query.NestedQuery
import zio.elasticsearch.ElasticQuery._
```

You can create a `Nested` query using the `nested` method in the following manner:
```scala
val query: NestedQuery = nested(path = "testField", query = matchAll)
```

You can create a [type-safe](https://lambdaworks.github.io/zio-elasticsearch/overview/overview_zio_prelude_schema) `Nested` query using the `nested` method in the following manner:
```scala
val query: NestedQuery = nested(path = Document.subDocumentList, query = matchAll)
```

If you want to change the `ignore_unmapped`, you can use `ignoreUnmapped` method:
```scala
val queryWithIgnoreUnmapped: NestedQuery = nested(path = Document.subDocumentList, query = matchAll).ignoreUnmapped(true)
```

If you want to change the `inner_hits`, you can use `innerHits` method:
```scala
import zio.elasticsearch.query.InnerHits

val queryWithInnerHits: NestedQuery = nested(path = Document.subDocumentList, query = matchAll).innerHits(innerHits = InnerHits.from(5))
```

If you want to change the `score_mode`, you can use `scoreMode` method:
```scala
import zio.elasticsearch.query.ScoreMode

val queryWithScoreMode: NestedQuery = nested(path = Document.subDocumentList, query = matchAll).scoreMode(ScoreMode.Avg)
```

You can find more information about `Nested` query [here](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/query-dsl-nested-query.html).
Loading