```markdown
# Elasticsearch Query Language (ES|QL)

The Elasticsearch Query Language (ES|QL) is a powerful and intuitive language designed to filter, transform, and analyze data stored in Elasticsearch. It is built to be user-friendly and accessible to a wide range of users, including end users, SRE teams, application developers, and administrators. ES|QL enables users to perform complex data operations such as filtering, aggregation, and time-series analysis, as well as generate visualizations and statistical insights.

## Key Features of ES|QL

- **Pipe-based Syntax**: ES|QL uses a pipe (`|`) syntax to chain operations, where the output of one operation becomes the input for the next. This step-by-step approach simplifies complex data transformations and analysis.
- **Rich Command Set**: ES|QL supports a wide range of commands and functions for data manipulation, including filtering, aggregation, enrichment, and statistical analysis.
- **Ease of Use**: Designed to be easy to learn and use, ES|QL is suitable for both technical and non-technical users.
- **Integration with Elasticsearch**: ES|QL queries are executed directly within Elasticsearch, leveraging its compute engine for high performance and scalability.

---

## Known Limitations of ES|QL

While ES|QL is a powerful tool, it has some limitations to be aware of:

### Result Set Size
- By default, ES|QL queries return up to 1,000 rows. This can be increased to a maximum of 10,000 rows using the `LIMIT` command. This upper limit is configurable but comes with trade-offs such as increased memory usage and processing time.

### Field Types
- ES|QL supports a wide range of field types, including `boolean`, `date`, `keyword`, `text`, `long`, and `double`. However, some field types, such as `binary`, `nested`, and `histogram`, are not yet supported.
- When querying multiple indices, fields with conflicting types must be explicitly converted to a single type using type conversion functions.

### Full-Text Search
- Full-text search is in technical preview and has limitations. For example, full-text search functions like `MATCH` must be used directly after the `FROM` command or close to it. Additionally, disjunctions (`OR`) in `WHERE` clauses are restricted unless all clauses use full-text functions.

### Time Series Data Streams
- ES|QL does not currently support querying time series data streams (TSDS).

### Date Math
- Date math expressions are limited. For example, subtracting two datetime values or using parentheses in date math expressions is not supported.

### Multivalued Fields
- Functions generally return `null` when applied to multivalued fields unless explicitly documented otherwise. Use multivalue functions to handle such fields.

### Timezone Support
- ES|QL only supports the UTC timezone.

### Kibana Integration
- The Discover interface in Kibana has a 10,000-row limit for displayed results and a 50-column limit for displayed fields. These limits apply only to the UI and not to the underlying query execution.

---

## Using ES|QL in Kibana

ES|QL is integrated into Kibana, allowing users to query and visualize data directly from the Discover interface. Key points for using ES|QL in Kibana include:

- **Enablement**: ES|QL is enabled by default in Kibana but can be disabled via the `enableESQL` setting in Advanced Settings.
- **Query Bar**: The query bar in Discover supports ES|QL syntax, with features like auto-complete and query history for ease of use.
- **Visualization**: ES|QL queries can be used to create visualizations, which can be saved to dashboards or used for alerting.
- **Time Filtering**: Use the standard time filter or custom time parameters (`?_tstart` and `?_tend`) to filter data by time range.

### Example Query in Kibana
```esql
FROM kibana_sample_data_logs
| WHERE @timestamp > NOW() - 1 day
| STATS total_bytes = SUM(bytes) BY geo.dest
| SORT total_bytes DESC
| LIMIT 5
```

This query retrieves the top 5 destinations by total bytes in the last 24 hours.

---

## Cross-Cluster Querying with ES|QL

ES|QL supports querying across multiple clusters, enabling users to analyze data stored in different Elasticsearch clusters. To query remote clusters, use the format `<remote_cluster_name>:<index_pattern>` in the `FROM` command.

### Example Cross-Cluster Query
```esql
FROM cluster_one:employees,cluster_two:other-employees-*
| STATS avg_salary = AVG(salary) BY department
| SORT avg_salary DESC
```

This query retrieves the average salary by department across two clusters and sorts the results in descending order.

---

## Using the ES|QL REST API

The ES|QL REST API allows users to execute ES|QL queries programmatically. Queries are sent as HTTP POST requests to the `_query` endpoint.

### Example REST API Request
```json
POST /_query
{
  "query": "FROM employees | WHERE salary > 50000 | SORT salary DESC | LIMIT 10"
}
```

### Key Points
- The `query` field contains the ES|QL query as a string.
- Use the `params` field to pass query parameters dynamically.
- The API returns results in JSON format, making it easy to integrate with other applications.

---

## Summary

ES|QL is a versatile and user-friendly query language for Elasticsearch, offering powerful capabilities for data analysis and transformation. While it has some limitations, its integration with Kibana and support for cross-cluster querying make it a valuable tool for a wide range of use cases. Whether you're analyzing logs, building dashboards, or creating alerts, ES|QL provides the flexibility and performance needed to work with Elasticsearch data effectively.
```
