(dsl): Support intervalQuery

docs/overview/elastic_interval_query.md

@@ -0,0 +1,67 @@
+---
+id: elastic_interval_query
+title: "Overview"
+---
+The `Intervals` query allows for advanced search queries based on intervals between words in specific fields.
+This query provides flexibility for conditions.
+
+To use the `Intervals` query, import the following:
+```scala
+import zio.elasticsearch.query.IntervalQuery
+import zio.elasticsearch.ElasticQuery._
+```
+
+You can create a basic `Intervals` query` using the `intervals` method:
+```scala
+val query: IntervalQuery[Any] = intervals(field = "content", rule = intervalMatch("targetWord"))
+```
+
+If you want to specify which fields should be searched, you can use the `useField` method:
+```scala
+val queryWithField: IntervalQuery[Document] =
+  intervals(field = "content", rule = intervalMatch("targetWord").useField(Document.stringField))
+```
+
+To define `field` in a type-safe manner, use the overloaded `useField` method with field definitions from your document:
+```scala
+val queryWithSafeField: IntervalQuery[Document] =
+  intervals(field = Document.stringField, rule = intervalMatch("targetWord"))
+```
+
+Alternatively, you can pass a `Field` object directly:
+```scala
+val queryWithFieldObject: IntervalQuery[Document] =
+  intervals(field = "content", rule = intervalMatch("targetWord").useField(Document.stringField))
+```
+
+If you want to define the `maxGaps` parameter, use the `maxGaps` method:
+```scala
+val queryWithMaxGaps: IntervalQuery[Document] =
+  intervals(field = "content", rule = intervalMatch("targetWord").maxGaps(2))
+```
+
+If you want to specify the word order requirement, use the `orderedOn` method:
+```scala
+val queryWithOrder: IntervalQuery[Document] =
+  intervals(field = "content", rule = intervalMatch("targetWord").orderedOn())
+```
+
+You can also apply additional filters to the query:
+```scala
+val queryWithFilter: IntervalQuery[Document] =
+  intervals(field = "content", rule = intervalMatch("targetWord").filter(IntervalFilter.someFilter))
+```
+
+Alternatively, you can construct the query manually with all parameters:
+```scala
+val queryManually: IntervalQuery[Document] =
+  IntervalQuery(
+    field = "content",
+    rule = intervalMatch("targetWord")
+      .maxGaps(2)
+      .orderedOn()
+      .filter(IntervalFilter.someFilter)
+      .analyzer("standard")
+  )
+```
+

modules/integration/src/test/scala/zio/elasticsearch/HttpExecutorSpec.scala

@@ -1,31 +1,16 @@
-/*
- * Copyright 2022 LambdaWorks
- *
- * Licensed 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 zio.elasticsearch
 
 import zio.Chunk
 import zio.elasticsearch.ElasticAggregation._
 import zio.elasticsearch.ElasticHighlight.highlight
-import zio.elasticsearch.ElasticQuery.{script => _, _}
+import zio.elasticsearch.ElasticQuery.{contains => _, _}
 import zio.elasticsearch.ElasticSort.sortBy
 import zio.elasticsearch.aggregation.AggregationOrder
 import zio.elasticsearch.data.GeoPoint
 import zio.elasticsearch.domain.{PartialTestDocument, TestDocument, TestSubDocument}
 import zio.elasticsearch.executor.Executor
 import zio.elasticsearch.query.DistanceUnit.Kilometers
+import zio.elasticsearch.query.ElasticIntervalQuery.intervalMatch
 import zio.elasticsearch.query.FunctionScoreFunction.randomScoreFunction
 import zio.elasticsearch.query.MultiMatchType._
 import zio.elasticsearch.query.sort.SortMode.Max
@@ -189,7 +174,8 @@ object HttpExecutorSpec extends IntegrationSpec {
                            )
                            .refreshTrue
                        )
-                  query       = term(field = TestDocument.stringField, value = secondDocumentUpdated.stringField.toLowerCase)
+                  query =
+                    term(field = TestDocument.stringField, value = secondDocumentUpdated.stringField.toLowerCase)
                   aggregation =
                     filterAggregation(name = "aggregation", query = query).withSubAgg(
                       maxAggregation("subAggregation", TestDocument.intField)
@@ -2771,6 +2757,69 @@ object HttpExecutorSpec extends IntegrationSpec {
             }
           } @@ after(Executor.execute(ElasticRequest.deleteIndex(geoPolygonIndex)).orDie)
         ),
+        suite("interval-match query")(
+          test("intervalMatch returns only matching document") {
+            checkOnce(genDocumentId, genTestDocument, Gen.alphaNumericString, genDocumentId, genTestDocument) {
+              (idMatch, docMatch, targetWord, idNoMatch, docNoMatch) =>
+                val docShouldMatch    = docMatch.copy(stringField = s"prefix $targetWord suffix")
+                val docShouldNotMatch = docNoMatch.copy(stringField = "completely unrelated text")
+                val field             = TestDocument.stringField.toString
+                val query             = intervals(field, intervalMatch(targetWord))
+
+                for {
+                  _ <- Executor.execute(ElasticRequest.deleteByQuery(firstSearchIndex, matchAll))
+                  _ <- Executor.execute(ElasticRequest.upsert(firstSearchIndex, idMatch, docShouldMatch))
+                  _ <- Executor.execute(
+                         ElasticRequest.upsert(firstSearchIndex, idNoMatch, docShouldNotMatch).refreshTrue
+                       )
+                  res <- Executor.execute(ElasticRequest.search(firstSearchIndex, query)).documentAs[TestDocument]
+                } yield assert(res)(
+                  Assertion.contains(docShouldMatch) &&
+                    Assertion.not(Assertion.contains(docShouldNotMatch))
+                )
+            }
+          } @@ around(
+            Executor.execute(ElasticRequest.createIndex(firstSearchIndex)),
+            Executor.execute(ElasticRequest.deleteIndex(firstSearchIndex)).orDie
+          ),
+          test("intervalMatch query finds document with exact matching term") {
+            checkOnce(genDocumentId, genTestDocument) { (docId, doc) =>
+              val term        = "apple"
+              val docWithTerm = doc.copy(stringField = s"$term banana orange")
+
+              val query = intervals(
+                "stringField",
+                intervalMatch(term)
+              )
+
+              for {
+                _   <- Executor.execute(ElasticRequest.upsert(firstSearchIndex, docId, docWithTerm))
+                _   <- Executor.execute(ElasticRequest.refresh(firstSearchIndex))
+                res <- Executor.execute(ElasticRequest.search(firstSearchIndex, query)).documentAs[TestDocument]
+              } yield assert(res)(Assertion.contains(docWithTerm))
+            }
+          } @@ around(
+            Executor.execute(ElasticRequest.createIndex(firstSearchIndex)),
+            Executor.execute(ElasticRequest.deleteIndex(firstSearchIndex)).orDie
+          ),
+          test("intervalMatch query does not find document if term is absent") {
+            checkOnce(genDocumentId, genTestDocument) { (docId, doc) =>
+              val query = intervals(
+                "stringField",
+                intervalMatch("nonexistentterm")
+              )
+
+              for {
+                _   <- Executor.execute(ElasticRequest.upsert(firstSearchIndex, docId, doc))
+                _   <- Executor.execute(ElasticRequest.refresh(firstSearchIndex))
+                res <- Executor.execute(ElasticRequest.search(firstSearchIndex, query)).documentAs[TestDocument]
+              } yield assert(res)(Assertion.isEmpty)
+            }
+          } @@ around(
+            Executor.execute(ElasticRequest.createIndex(firstSearchIndex)),
+            Executor.execute(ElasticRequest.deleteIndex(firstSearchIndex)).orDie
+          )
+        ),
         suite("search for documents using FunctionScore query")(
           test("using randomScore function") {
             checkOnce(genTestDocument, genTestDocument) { (firstDocument, secondDocument) =>

modules/library/src/main/scala/zio/elasticsearch/ElasticQuery.scala

@@ -42,6 +42,7 @@ object ElasticQuery {
    * @return
    *   an instance of [[zio.elasticsearch.query.BoostingQuery]] that represents the boost query to be performed.
    */
+
   final def boosting[S: Schema](
     negativeBoost: Float,
     negativeQuery: ElasticQuery[S],
@@ -548,6 +549,37 @@ object ElasticQuery {
   final def ids(value: String, values: String*): IdsQuery[Any] =
     Ids(values = Chunk.fromIterable(value +: values))
 
+  /**
+   * Constructs a type-safe intervals query by combining a field and an interval rule.
+   *
+   * The resulting query wraps the specified interval query under the given type-safe field in the intervals query
+   * structure.
+   *
+   * @param field
+   *   the type-safe field on which the query is executed
+   * @param rule
+   *   an instance of [[zio.elasticsearch.query.IntervalRule]] representing the interval query rule
+   * @tparam S
+   *   the document type for which the query is defined
+   * @return
+   *   an [[zio.elasticsearch.ElasticQuery]] instance representing the intervals query.
+   */
+  final def intervals[S](field: Field[S, _], rule: IntervalRule): ElasticQuery[S] = Intervals(field.toString, rule)
+
+  /**
+   * Constructs an intervals query by combining a field and an interval query.
+   *
+   * The resulting query wraps the specified interval query under the given field in the intervals query structure.
+   *
+   * @param field
+   *   the name of the field to be queried
+   * @param rule
+   *   an instance of [[zio.elasticsearch.query.IntervalRule]] representing the interval query rule
+   * @return
+   *   an [[zio.elasticsearch.ElasticQuery]] instance representing the intervals query.
+   */
+  final def intervals(field: String, rule: IntervalRule): ElasticQuery[Any] = Intervals(field = field, rule = rule)
+
   /**
    * Constructs a type-safe instance of [[zio.elasticsearch.query.KNNQuery]] using the specified parameters.
    * [[zio.elasticsearch.query.KNNQuery]] is used to perform a k-nearest neighbor (kNN) search and returns the matching