SQL: Documentation for LIKE and RLIKE operators (#40623)
(cherry picked from commit 9536c5f7b7fecda4592f6b169adef180eadbba54)
This commit is contained in:
Andrei Stefan
Andrei Stefan
parent
8cd96ee160
commit
f8d3d685e5
|
|
@ -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[]
|
||||
|
|
|
|||
|
|
@ -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')`
|
||||
|===
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
;
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue