```markdown
# ES|QL: The Elasticsearch Query Language

## Overview

**ES|QL** (Elasticsearch Query Language) is a modern, piped query language designed for filtering, transforming, and analyzing data stored in Elasticsearch. It is intended to be intuitive and accessible for a wide range of users, including SRE teams, application developers, administrators, and end users. ES|QL enables users to author queries for event detection, statistical analysis, and data visualization, supporting a rich set of commands and functions for complex data operations.

## Key Features

- **Piped Syntax:** ES|QL uses the pipe character (`|`) to chain commands, allowing users to build queries as a sequence of operations. Each command processes the output of the previous one, enabling step-by-step data transformation.
- **Wide Command Support:** Includes commands for filtering (`WHERE`), aggregation (`STATS`), enrichment (`ENRICH`, `LOOKUP JOIN`), sorting (`SORT`), column management (`KEEP`, `DROP`, `RENAME`), and more.
- **Functionality:** Supports statistical analysis, time-series operations, pattern matching, and data enrichment.
- **Extensibility:** Designed to work with Elasticsearch and, in the future, other runtimes.

## Example ES|QL Query

```esql
FROM logs-*
| WHERE @timestamp >= NOW() - 1 day
| STATS event_count = COUNT(*) BY event.code
| SORT event_count DESC
| LIMIT 10
```

## Using ES|QL via the REST API

ES|QL queries can be executed using the Elasticsearch REST API. The endpoint is `POST /_query`, and the query is provided in the request body.

**Example:**

```http
POST /_query
{
  "query": """
    FROM employees
    | WHERE hire_date >= "2020-01-01"
    | STATS avg_salary = AVG(salary) BY department
    | SORT avg_salary DESC
    | LIMIT 5
  """
}
```

**Notes:**
- You can use triple quotes (`"""`) for multi-line queries.
- Parameters can be passed for dynamic queries.
- The API returns results as a table, with each row representing a document and each column a field.

## ES|QL in Kibana

- **Editor Shortcuts:** The ES|QL editor in Kibana supports keyboard shortcuts for running queries and commenting lines.
- **Visualization:** Queries in Discover automatically generate visualizations (e.g., bar charts, histograms) based on the query output. If your indices do not have a `@timestamp` field, you can specify a custom time field.
- **Dashboards:** ES|QL queries can be used to create panels in Kibana dashboards. You can save and edit visualizations directly from the dashboard interface.
- **Enrich Policies:** Before using the `ENRICH` command, you must create and execute an enrich policy. Kibana provides UI support for policy creation.
- **Alerting:** ES|QL queries can be used to create alerting rules in Discover.

**Important Kibana Limitations:**
- Filtering via the UI is disabled in ES|QL mode; use the `WHERE` command in your query.
- Discover displays a maximum of 10,000 rows and 50 columns per query.
- CSV export is limited to 10,000 rows.
- Querying many indices without filters may result in errors due to large response sizes; use `DROP` or `KEEP` to limit fields.

## Cross-Cluster Querying

ES|QL supports querying across multiple clusters, indices, data streams, or aliases. To query remote clusters, use the format `<cluster_name>:<index_pattern>`.

**Example:**

```esql
FROM cluster_one:employees-00001,cluster_two:other-employees-*
```

**Notes:**
- All underlying indices and shards must be active; queries will fail if any are unassigned or paused.
- Field type mismatches across indices must be resolved using type conversion functions (e.g., `TO_IP`, `TO_STRING`).
- Time series data streams (TSDS) are not supported.
- Union types are in technical preview; ambiguous fields must be explicitly converted to a single type.

## Known Limitations

- **Result Set Size:** By default, queries return up to 1,000 rows; the maximum is 10,000 rows, configurable via cluster settings. Larger result sets increase memory and processing requirements.
- **Field Types:** Only certain field types are supported (e.g., `boolean`, `date`, `double`, `ip`, `keyword`, `long`, `text`). Unsupported types return errors or `null` values.
- **Full-Text Search:** Full-text functions (`MATCH`, `QSTR`, `KQL`) must be used directly after the `FROM` command. Disjunctions (`OR`) in `WHERE` clauses are limited.
- **Text Fields:** Queries on `text` fields behave as if they are `keyword` fields (case-sensitive, full-string match) unless using full-text functions.
- **Source Field:** ES|QL does not support indices with the `_source` field disabled.
- **Date Math:** Date math expressions must have the datetime on the left; subtracting two datetimes is not supported.
- **Multivalue Fields:** Functions generally return `null` for multivalued fields unless documented otherwise; use multivalue functions to convert to single values.
- **Timezone:** Only UTC is supported.
- **Sorting:** Spatial types are not supported in `SORT` commands.
- **Index Metadata:** Use the `METADATA` directive to include index information in results.
- **Known Issues:** A bug in the `STATS` command may yield incorrect results when grouping by two high-cardinality keyword fields (fixed in recent releases).

## Summary

ES|QL is a flexible, high-performance query language for Elasticsearch, supporting advanced data analysis and transformation. It is accessible via REST API, integrates with Kibana for visualization and alerting, and supports cross-cluster querying with some limitations. Users should be aware of result size limits, field type support, and specific behaviors in Kibana and multi-index scenarios.
```
