ES|QL queries to TypeScript types with the Elasticsearch JavaScript client

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!