---

name: esql-query-builder description: "Guide the Elasticsearch Python ES|QL builder, safe parameterized queries, sync/async execution, functions, and tabular response conversion." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

ES|QL query builder

Use this route for ES|QL source/processing commands, Python expressions, parameterized user input, client.esql.query(), or ES|QL table results. The builder is technical preview at this source snapshot; check the target client and server versions before relying on it.

Fast route

1. Build a source with ESQL.from_(...), ESQL.row(...), ESQL.show("INFO"), ESQL.ts(...), or ESQL.branch().
2. Chain processing commands such as .where(...), .keep(...), .eval(...), .sort(...), .stats(...), .limit(...), .metadata(...), and other methods on the returned ESQLBase object.
3. Render with str(query) or query.render() and review the result offline.
4. Pass the builder to client.esql.query(query=query, params=[...]); await the call for AsyncElasticsearch. Keep untrusted values in params, not in concatenated query strings.

Read api-reference.md for sources, expressions, and execution parameters; workflows.md for safe recipes; pandas-integration.md for tabular conversion; and troubleshooting.md for preview, syntax, optional-dependency, and response issues. Run scripts/esql_query_smoke.py for offline checks.

Offline example

from elasticsearch.esql import E, ESQL

query = (
    ESQL.from_("employees")
    .keep("first_name", "last_name")
    .where(E("first_name") == E("?"))
    .limit(10)
)
print(query.render())
# client.esql.query(query=query, params=[name])  # requires a live cluster

Do not treat rendering as server validation. Check index names, privileges, ES|QL feature availability, response columns/values, and server version when executing.