SQL: Documentation for LIKE and RLIKE operators (#40623)

(cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)

docs/reference/sql/functions/index.asciidoc

@@ -6,7 +6,27 @@
 {es-sql} provides a comprehensive set of built-in operators and functions:
 
 * <<sql-operators, Operators>>
-* <<sql-functions-aggs, Aggregate>>
+** <<sql-operators-equality>>
+** <<sql-operators-null-safe-equality>>
+** <<sql-operators-inequality>>
+** <<sql-operators-comparison>>
+** <<sql-operators-between>>
+** <<sql-operators-is-null>>
+** <<sql-operators-in>>
+** <<sql-operators-and>>
+** <<sql-operators-or>>
+** <<sql-operators-not>>
+** <<sql-operators-plus>>
+** <<sql-operators-subtract>>
+** <<sql-operators-negate>>
+** <<sql-operators-multiply>>
+** <<sql-operators-divide>>
+** <<sql-operators-remainder>>
+** <<sql-operators-cast-cast>>
+* <<sql-like-rlike-operators>>
+** <<sql-like-operator>>
+** <<sql-rlike-operator>>
+* <<sql-functions-aggs>>
 ** <<sql-functions-aggs-avg>>
 ** <<sql-functions-aggs-count>>
 ** <<sql-functions-aggs-count-all>>
@@ -24,9 +44,10 @@
 ** <<sql-functions-aggs-stddev-pop>>
 ** <<sql-functions-aggs-sum-squares>>
 ** <<sql-functions-aggs-var-pop>>
-* <<sql-functions-grouping, Grouping>>
+* <<sql-functions-grouping>>
 ** <<sql-functions-grouping-histogram>>
-* <<sql-functions-datetime, Date-Time>>
+* <<sql-functions-datetime-interval, Date-Time Operators>>
+* <<sql-functions-current-date, Date-Time Functions>>
 ** <<sql-functions-current-date>>
 ** <<sql-functions-current-timestamp>>
 ** <<sql-functions-datetime-day>>
@@ -47,11 +68,11 @@
 ** <<sql-functions-datetime-week>>
 ** <<sql-functions-datetime-year>>
 ** <<sql-functions-datetime-extract>>
-* <<sql-functions-search, Full-Text Search>>
+* <<sql-functions-search>>
 ** <<sql-functions-search-match>>
 ** <<sql-functions-search-query>>
 ** <<sql-functions-search-score>>
-* <<sql-functions-math, Mathematical>>
+* <<sql-functions-math>>
 ** <<sql-functions-math-abs>>
 ** <<sql-functions-math-cbrt>>
 ** <<sql-functions-math-ceil>>
@@ -80,7 +101,7 @@
 ** <<sql-functions-math-sin>>
 ** <<sql-functions-math-sinh>>
 ** <<sql-functions-math-tan>>
-* <<sql-functions-string, String>>
+* <<sql-functions-string>>
 ** <<sql-functions-string-ascii>>
 ** <<sql-functions-string-bit-length>>
 ** <<sql-functions-string-char>>
@@ -101,10 +122,10 @@
 ** <<sql-functions-string-space>>
 ** <<sql-functions-string-substring>>
 ** <<sql-functions-string-ucase>>
-* <<sql-functions-type-conversion, Type Conversion>>
+* <<sql-functions-type-conversion>>
 ** <<sql-functions-type-conversion-cast>>
 ** <<sql-functions-type-conversion-convert>>
-* <<sql-functions-conditional, Conditional>>
+* <<sql-functions-conditional>>
 ** <<sql-functions-conditional-coalesce>>
 ** <<sql-functions-conditional-greatest>>
 ** <<sql-functions-conditional-ifnull>>
@@ -112,11 +133,12 @@
 ** <<sql-functions-conditional-least>>
 ** <<sql-functions-conditional-nullif>>
 ** <<sql-functions-conditional-nvl>>
-* <<sql-functions-system, System>>
+* <<sql-functions-system>>
 ** <<sql-functions-system-database>>
 ** <<sql-functions-system-user>>
 
 include::operators.asciidoc[]
+include::like-rlike.asciidoc[]
 include::aggs.asciidoc[]
 include::grouping.asciidoc[]
 include::date-time.asciidoc[]

docs/reference/sql/functions/like-rlike.asciidoc

@@ -0,0 +1,102 @@
+[role="xpack"]
+[testenv="basic"]
+[[sql-like-rlike-operators]]
+=== LIKE and RLIKE Operators
+
+`LIKE` and `RLIKE` operators are commonly used to filter data based on string patterns. They usually act on a field placed on the left-hand side of
+the operator, but can also act on a constant (literal) expression. The right-hand side of the operator represents the pattern.
+Both can be used in the `WHERE` clause of the `SELECT` statement, but `LIKE` can also be used in other places, such as defining an
+<<sql-index-patterns, index pattern>> or across various <<sql-commands, SHOW commands>>.
+This section covers only the `SELECT ... WHERE ...` usage.
+
+NOTE: One significant difference between `LIKE`/`RLIKE` and the <<sql-functions-search, full-text search predicates>> is that the former
+act on <<sql-multi-field, exact fields>> while the latter also work on <<text, analyzed>> fields. If the field used with `LIKE`/`RLIKE` doesn't
+have an exact not-normalized sub-field (of <<keyword, keyword>> type) {es-sql} will not be able to run the query. If the field is either exact
+or has an exact sub-field, it will use it as is, or it will automatically use the exact sub-field even if it wasn't explicitly specified in the statement.
+
+[[sql-like-operator]]
+==== `LIKE`
+
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+expression<1> LIKE constant_exp<2>
+--------------------------------------------------
+
+<1> typically a field, or a constant expression
+<2> pattern
+
+.Description:
+
+The SQL `LIKE` operator is used to compare a value to similar values using wildcard operators. There are two wildcards used in conjunction
+with the `LIKE` operator:
+
+* The percent sign (%)
+* The underscore (_)
+
+The percent sign represents zero, one or multiple characters. The underscore represents a single number or character. These symbols can be
+used in combinations.
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs/docs.csv-spec[simpleLike]
+----
+
+There is, also, the possibility of using an escape character if one needs to match the wildcard characters themselves. This can be done
+by using the `ESCAPE [escape_character]` statement after the `LIKE ...` operator:
+
+ SELECT name, author FROM library WHERE name LIKE 'Dune/%' ESCAPE '/';
+
+In the example above `/` is defined as an escape character which needs to be placed before the `%` or `_` characters if one needs to
+match those characters in the pattern specifically. By default, there is no escape character defined.
+
+IMPORTANT: Even though `LIKE` is a valid option when searching or filtering in {es-sql}, full-text search predicates
+`MATCH` and `QUERY` are <<sql-like-prefer-full-text, faster and much more powerful and are the preferred alternative>>.
+
+[[sql-rlike-operator]]
+==== `RLIKE`
+
+.Synopsis:
+[source, sql]
+--------------------------------------------------
+expression<1> RLIKE constant_exp<2>
+--------------------------------------------------
+
+<1> typically a field, or a constant expression
+<2> pattern
+
+.Description:
+
+This operator is similar to `LIKE`, but the user is not limited to search for a string based on a fixed pattern with the percent sign (`%`)
+and underscore (`_`); the pattern in this case is a regular expression which allows the construction of more flexible patterns.
+
+For more details about the regular expressions syntax, https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html[Java's Pattern class javadoc]
+is a good starting point.
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs/docs.csv-spec[simpleRLike]
+----
+
+IMPORTANT: Even though `RLIKE` is a valid option when searching or filtering in {es-sql}, full-text search predicates
+`MATCH` and `QUERY` are <<sql-like-prefer-full-text, faster and much more powerful and are the preferred alternative>>.
+
+[[sql-like-prefer-full-text]]
+==== Prefer full-text search predicates
+
+When using `LIKE`/`RLIKE`, do consider using <<sql-functions-search, full-text search predicates>> which are faster, much more powerful
+and offer the option of sorting by relevancy (results can be returned based on how well they matched).
+
+For example:
+
+[cols="<m,<m"]
+
+|===
+^s|LIKE/RLIKE                    ^s|QUERY/MATCH
+|`foo LIKE 'bar'`                    |`MATCH(foo, 'bar')`
+|`foo LIKE 'bar' AND tar LIKE 'goo'` |`MATCH('foo^2, tar^5', 'bar goo', 'operator=and')`
+|`foo LIKE 'barr'`                   |`QUERY('foo: bar~')`
+|`foo LIKE 'bar' AND tar LIKE 'goo'` |`QUERY('foo: bar AND tar: goo')`
+|`foo RLIKE 'ba.*'`                  |`MATCH(foo, 'ba', 'fuzziness=AUTO:1,5')`
+|`foo RLIKE 'b.{1}r'`                |`MATCH(foo, 'br', 'fuzziness=1')`
+|===

docs/reference/sql/functions/math.asciidoc

@@ -1,7 +1,7 @@
 [role="xpack"]
 [testenv="basic"]
 [[sql-functions-math]]
-=== Math Functions
+=== Mathematical Functions
 
 All math and trigonometric functions require their input (where applicable)
 to be numeric.

docs/reference/sql/functions/operators.asciidoc

@@ -5,14 +5,16 @@
 
 Boolean operator for comparing against one or multiple expressions.
 
-* Equality (`=`)
+[[sql-operators-equality]]
+==== `Equality (=)`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/filter.sql-spec[whereFieldEquality]
 --------------------------------------------------
 
-* Null safe Equality (`<=>`)
+[[sql-operators-null-safe-equality]]
+==== `Null safe Equality (<=>)`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -24,35 +26,40 @@ include-tagged::{sql-specs}/docs/docs.csv-spec[nullEqualsCompareWithNull]
 include-tagged::{sql-specs}/docs/docs.csv-spec[nullEqualsCompareTwoNulls]
 --------------------------------------------------
 
-* Inequality (`<>` or `!=`)
+[[sql-operators-inequality]]
+==== `Inequality (<> or !=)`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/filter.sql-spec[whereFieldNonEquality]
 --------------------------------------------------
 
-* Comparison (`<`, `<=`, `>`, `>=`)
+[[sql-operators-comparison]]
+==== `Comparison (<, <=, >, >=)`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/filter.sql-spec[whereFieldLessThan]
 --------------------------------------------------
 
-* `BETWEEN`
+[[sql-operators-between]]
+==== `BETWEEN`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/filter.sql-spec[whereBetween]
 --------------------------------------------------
 
-* `IS NULL/IS NOT NULL`
+[[sql-operators-is-null]]
+==== `IS NULL/IS NOT NULL`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/filter.sql-spec[whereIsNotNullAndIsNull]
 --------------------------------------------------
 
-* `IN (<value1>, <value2>, ...)`
+[[sql-operators-in]]
+==== `IN (<value1>, <value2>, ...)`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -64,21 +71,24 @@ include-tagged::{sql-specs}/filter.sql-spec[whereWithInAndMultipleValues]
 
 Boolean operator for evaluating one or two expressions.
 
-* `AND`
+[[sql-operators-and]]
+==== `AND`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/filter.sql-spec[whereFieldAndComparison]
 --------------------------------------------------
 
-* `OR`
+[[sql-operators-or]]
+==== `OR`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/filter.sql-spec[whereFieldOrComparison]
 --------------------------------------------------
 
-* `NOT`
+[[sql-operators-not]]
+==== `NOT`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -91,42 +101,48 @@ include-tagged::{sql-specs}/filter.sql-spec[whereFieldEqualityNot]
 Perform mathematical operations affecting one or two values.
 The result is a value of numeric type.
 
-* Add (`+`)
+[[sql-operators-plus]]
+==== `Add (+)`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/arithmetic.sql-spec[plus]
 --------------------------------------------------
 
-* Subtract (infix `-`)
+[[sql-operators-subtract]]
+==== `Subtract (infix -)`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/arithmetic.sql-spec[minus]
 --------------------------------------------------
 
-* Negate (unary `-`)
+[[sql-operators-negate]]
+==== `Negate (unary -)`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/arithmetic.sql-spec[unaryMinus]
 --------------------------------------------------
 
-* Multiply (`*`)
+[[sql-operators-multiply]]
+==== `Multiply (*)`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/arithmetic.sql-spec[multiply]
 --------------------------------------------------
 
-* Divide (`/`)
+[[sql-operators-divide]]
+==== `Divide (/)`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{sql-specs}/arithmetic.sql-spec[divide]
 --------------------------------------------------
 
-* https://en.wikipedia.org/wiki/Modulo_operation[Modulo] or Remainder(`%`)
+[[sql-operators-remainder]]
+==== `Modulo or Remainder(%)`
 
 ["source","sql",subs="attributes,callouts,macros"]
 --------------------------------------------------
@@ -136,7 +152,8 @@ include-tagged::{sql-specs}/arithmetic.sql-spec[mod]
 [[sql-operators-cast]]
 === Cast Operators
 
-* Cast (`::`)
+[[sql-operators-cast-cast]]
+==== `Cast (::)`
 
 `::` provides an alternative syntax to the <<sql-functions-type-conversion-cast>> function.
 

x-pack/plugin/sql/qa/src/main/resources/docs/docs.csv-spec

@@ -2495,3 +2495,25 @@ SELECT first_name, last_name FROM emp WHERE last_name NOT LIKE '%a%' AND first_n
  Anoosh        |Peyn
  Arumugam      |Ossenbruggen
 ;
+
+simpleLikeOperator
+// tag::simpleLike
+SELECT author, name FROM library WHERE name LIKE 'Dune%';
+
+    author     |     name
+---------------+---------------
+Frank Herbert  |Dune
+Frank Herbert  |Dune Messiah
+// end::simpleLike
+;
+
+simpleRLikeOperator
+// tag::simpleRLike
+SELECT author, name FROM library WHERE name RLIKE 'Child.* Dune';
+
+    author     |      name
+---------------+----------------
+Frank Herbert  |Children of Dune
+// end::simpleRLike
+;
+