Introduction
In a recent article, Laura highlighted how to use the Java Elasticsearch client to craft ES|QL queries and parse their results as native Java objects. Similar functionality, with TypeScript support, will be available in the JavaScript client in the upcoming 8.14.0 release. This blog explains how to use the Elasticsearch JavaScript client and TypeScript support to craft ES|QL queries and handle their results as native JavaScript objects.
Implementation: ES|QL queries to TypeScript types with the Elasticsearch JavaScript client
First, let's use the bulk helper to index some data:
const client = new Client({
node: "http://localhost:9200",
const client = new Client({
node: elasticsearchEndpoint,
auth: {
apiKey: elasticsearchApiKey
}
});
})
await client.helpers.bulk({
datasource: [
{ name: "Revelation Space", author: "Alastair Reynolds", release_date: "2000-03-15", page_count: 585 },
{ name: "1984", author: "George Orwell", release_date: "1985-06-01", page_count: 328 },
{ name: "Fahrenheit 451", author: "Ray Bradbury", release_date: "1953-10-15", page_count: 227 },
{ name: "Brave New World", author: "Aldous Huxley", release_date: "1932-06-01", page_count: 268 },
],
onDocument(_doc) {
return { index: { _index: "books" } }
},
})Now, let's use a very basic ES|QL query to look at these newly indexed documents:
const response = await client.esql.query({ query: 'FROM books' })
/*
Returns:
{
columns: {
{ name: "name", type: "keyword" },
{ name: "author", type: "keyword" },
{ name: "release_date", type: "date" },
{ name: "page_count", type: "integer" },
},
values: [
[ "Revelation Space", "Alastair Reynolds", "2000-03-15", 585 ],
[ "1984", "George Orwell", "1985-06-01", 328 ],
[ "Fahrenheit 451", "Ray Bradbury", "1953-10-15", 227 ],
[ "Brave New World", "Aldous Huxley", "1932-06-01", 268 ],
],
}
*/Returning each row as an array of values is a simple default that's useful in many cases. Still, if you wanted an array of records instead—a standard structure in JavaScript applications—extra effort is necessary to convert the data.
Fortunately, in 8.14.0, the JavaScript client will include a new ES|QL helper to do this for you:
const { records } = await client.helpers.esql({ query: 'FROM books' }).toRecords()
/*
Returns:
[
{ name: "Revelation Space", author: "Alastair Reynolds", release_date: "2000-03-15", page_count: 585 },
{ name: "1984", author: "George Orwell", release_date: "1985-06-01", page_count: 328 },
{ name: "Fahrenheit 451", author: "Ray Bradbury", release_date: "1953-10-15", page_count: 227 },
{ name: "Brave New World", author: "Aldous Huxley", release_date: "1932-06-01", page_count: 268 },
]
*/If you're using TypeScript, you can declare the type of the results inline:
type Book = {
name: string,
author: string,
release_date: string,
page_count: number,
}
// Returns `records` as `Book[]`
const { records } = await client.helpers.esql({ query: 'FROM books' }).toRecords<Book>()In another situation, you might need to declare a type that doesn't perfectly match the query results. Maybe the keys and columns don't have the same names, or the returned documents have columns that don't exist in your type. In this case, we can use the ES|QL RENAME and KEEP processing commands to modify our results to better fit your type:
type Book = {
name: string,
author: string,
released: string,
}
const query = `FROM books | DROP page_count | RENAME release_date AS released`
const { records } = await client.helpers.esql({ query }).toRecords<Book>()Conclusion
These are relatively simple examples that highlight how to use the new ES|QL helper in the JavaScript client, so check out the docs for full details. Future releases of the JavaScript client will likely include more ES|QL helpers, like pagination over large result sets using generators, and support for Apache Arrow.
All of our official clients have plans to include similar helpers and tools to make working with ES|QL queries as simple as possible. Check the changelog for your preferred client in the coming weeks and months!
Ready to try this out on your own? Start a free trial.
Want to get Elastic certified? Find out when the next Elasticsearch Engineer training is running!
Related content
April 15, 2025
ES|QL Joins Are Here! Yes, Joins!
Elasticsearch 8.18 includes ES|QL’s LOOKUP JOIN command, our first SQL-style JOIN.
April 15, 2025
Native joins available in Elasticsearch 8.18
Exploring LOOKUP JOIN, a new ES|QL command available in tech preview in Elasticsearch 8.18.
December 31, 2024
Improving the ES|QL editor experience in Kibana
With the new ES|QL language becoming GA, a new editor experience has been developed in Kibana to help users write faster and better queries. Features like live validation, improved autocomplete and quick fixes will streamline the ES|QL experience.
How to use the ES|QL Helper in the Elasticsearch Ruby Client
Learn how to use the Elasticsearch Ruby client to craft ES|QL queries and handle their results.
From ES|QL to native Pandas dataframes in Python
Learn how to export ES|QL queries as native Pandas dataframes in Python through practical examples.