OpenSearch/docs/reference/sql/language/indices.asciidoc

[role="xpack"]
[testenv="basic"]
[[sql-index-patterns]]
=== Index patterns

{es-sql} supports two types of patterns for matching multiple indices or tables:

[[sql-index-patterns-multi]]
[float]
==== {es} multi-index

The {es} notation for enumerating, including or excluding <<multi-index,multi-target syntax>>
is supported _as long_ as it is quoted or escaped as a table identifier.

For example:

[source, sql]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[showTablesEsMultiIndex]
----

Notice the pattern is surrounded by double quotes `"`. It enumerated `*` meaning all indices however
it excludes (due to `-`) all indices that start with `l`.
This notation is very convenient and powerful as it allows both inclusion and exclusion, depending on
the target naming convention.

The same kind of patterns can also be used to query multiple indices or tables.

For example:

[source, sql]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[fromTablePatternQuoted]
----

NOTE: There is the restriction that all resolved concrete tables have the exact same mapping.

[[sql-index-patterns-like]]
[float]
==== SQL `LIKE` notation

The common `LIKE` statement (including escaping if needed) to match a wildcard pattern, based on one `_`
or multiple `%` characters.

Using `SHOW TABLES` command again:

[source, sql]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[showTablesLikeWildcard]
----

The pattern matches all tables that start with `emp`. 

This command supports _escaping_ as well, for example:

[source, sql]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[showTablesLikeEscape]
----

Notice how now `emp%` does not match any tables because `%`, which means match zero or more characters,
has been escaped by `!` and thus becomes an regular char. And since there is no table named `emp%`,
an empty table is returned.

In a nutshell, the differences between the two type of patterns are:

[cols="^h,^,^"]
|===
s|Feature
s|Multi index
s|SQL `LIKE`

| Type of quoting    | `"` | `'`
| Inclusion          | Yes | Yes
| Exclusion          | Yes | No
| Enumeration        | Yes | No
| One char pattern   | No  | `_`
| Multi char pattern | `*` | `%`
| Escaping           | No  | `ESCAPE`

|===

Which one to use, is up to you however try to stick to the same one across your queries for consistency.

NOTE: As the query type of quoting between the two patterns is fairly similar (`"` vs `'`), {es-sql} _always_
requires the keyword `LIKE` for SQL `LIKE` pattern.

[[sql-index-frozen]]
=== Frozen Indices

{es} <<frozen-indices, frozen indices>> are a useful and powerful tool for hot/warm architecture introduced in {es} 6.6, 
essentially by trading speed for memory.
{es-sql} supports frozen indices and similar to {es}, due to their performance characteristics, allows searches on them only
when explicitly told so by user - in other words, by default, frozen indices are not included in searches.

One can toggle the use of frozen indices through:

dedicated configuration parameter::
Set to `true` properties `index_include_frozen` in the <<sql-rest>> or `index.include.frozen` in the drivers to include frozen indices.

dedicated keyword::
Explicitly perform the inclusion through the dedicated `FROZEN` keyword in the `FROM` clause or `INCLUDE FROZEN` in the `SHOW` commands:

[source, sql]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[showTablesIncludeFrozen]
----


[source, sql]
----
include-tagged::{sql-specs}/docs/docs.csv-spec[fromTableIncludeFrozen]
----

Unless enabled, frozen indices are completely ignored; it is as if they do not exist and as such, queries ran against them are likely to fail.