Elastic.Clients.Esql 0.12.0

Elastic.Clients.Esql

Execute ES|QL queries against Elasticsearch with LINQ. This package connects the Elastic.Esql translation engine to a real cluster via Elastic.Transport. Pair it with a source-generated JsonSerializerContext for a fully AOT-compatible query pipeline from LINQ expression to typed results.

Why?

Elastic.Esql translates LINQ to ES|QL strings. This package adds the HTTP layer to actually run them -- connection pooling, authentication, error handling, async queries, and result materialization into typed C# objects.

Quick Start

using var client = new EsqlClient(new Uri("https://my-cluster:9200"));

// LINQ query -- translates and executes in one step
var errors = await client.CreateQuery<LogEntry>()
    .From("logs-*")
    .Where(l => l.Level == "ERROR")
    .OrderByDescending(l => l.Timestamp)
    .Take(10)
    .ToListAsync();

Configuration

// Simple -- just a URI
using var client = new EsqlClient(new Uri("https://localhost:9200"));

// With authentication and a source-generated JSON context
[JsonSerializable(typeof(LogEntry))]
public partial class MyContext : JsonSerializerContext;

var transport = new DistributedTransport(
    new TransportConfiguration(new Uri(url), new ApiKey(apiKey)));

var settings = new EsqlClientSettings(transport)
{
    JsonSerializerContext = MyContext.Default,
    Defaults = new EsqlQueryDefaults
    {
        TimeZone = "America/New_York",
        Locale = "en-US"
    }
};
using var client = new EsqlClient(settings);

Query Patterns

LINQ fluent syntax

var topBrands = await client.CreateQuery<Product>()
    .From("products")
    .Where(p => p.InStock)
    .GroupBy(p => p.Brand)
    .Select(g => new { Brand = g.Key, Avg = g.Average(p => p.Price), Count = g.Count() })
    .OrderByDescending(x => x.Avg)
    .Take(5)
    .ToListAsync();

LINQ query syntax

var results = await (
    from log in client.CreateQuery<LogEntry>().From("logs-*")
    where log.Level == "ERROR"
    where log.Duration > 500
    orderby log.Timestamp descending
    select new { log.Message, log.Duration }
).ToListAsync();

Lambda expression

var results = await client.QueryAsync<LogEntry>(q =>
    q.From("logs-*").Where(l => l.Level == "ERROR").Take(10));

Raw ES|QL fragments

Use RawEsql() to append expert-level ES|QL fragments directly into a LINQ pipeline:

var results = client.Query<LogEntry>(q => q
	.From("logs-*")
	.RawEsql("WHERE log.level == \"ERROR\"")
	.RawEsql("| LIMIT 10"));

You can also switch the downstream materialization type:

var rows = client.Query<LogEntry, LogProjection>(q => q
	.From("logs-*")
	.RawEsql<LogEntry, LogProjection>("KEEP message, statusCode"));

For Native AOT, ensure the target materialization type (for example LogProjection) is included in your source-generated JsonSerializerContext.

Inspect the generated query

Every queryable's .ToString() returns the ES|QL without executing:

var query = client.CreateQuery<Product>()
    .Where(p => p.Price > 100)
    .OrderBy(p => p.Name);

Console.WriteLine(query.ToString());
// FROM products
// | WHERE price > 100
// | SORT name

Async Queries

For long-running queries, use the async query API. Results auto-delete from the cluster on dispose:

await using var asyncQuery = await client.SubmitAsyncQueryAsync<LogEntry>(
    q => q.From("logs-*").Where(l => l.Level == "ERROR"),
    new EsqlAsyncQueryOptions
    {
        WaitForCompletionTimeout = TimeSpan.FromSeconds(5),
        KeepAlive = TimeSpan.FromMinutes(10)
    });

if (asyncQuery.IsRunning)
    Console.WriteLine($"Query {asyncQuery.QueryId} still running...");

var results = await asyncQuery.ToListAsync();  // Polls until complete
// Query automatically deleted from cluster when disposed

Raw response formats

Get the server-formatted bytes (Csv, Tsv, Txt, Json, Arrow, Smile, Cbor, Yaml) instead of materialised rows:

using var stream = await client.CreateQuery<LogEntry>()
    .From("logs-*")
    .Where(l => l.Level == "ERROR")
    .ToStreamAsync(EsqlFormat.Csv);

await stream.CopyToAsync(File.Create("errors.csv"));

Server-side async with Apache Arrow. The query is best-effort DELETEd on disposal:

await using var q = await client.CreateQuery<LogEntry>()
    .From("logs-*")
    .Where(l => l.Level == "ERROR")
    .ToAsyncQueryAsync(EsqlFormat.Arrow);

await q.WaitForCompletionAsync();

using var stream = q.GetResponseStream();
using var reader = new ArrowStreamReader(stream); // Apache.Arrow.Ipc — separate NuGet
while (await reader.ReadNextRecordBatchAsync() is { } batch)
    Console.WriteLine($"Batch: {batch.Length} rows, {batch.ColumnCount} cols");

A ToPipeReaderAsync(format) overload is available on .NET 10+ for zero-copy consumers.

Per-query options

Configure defaults globally through EsqlClientSettings.Defaults. Override them on individual queries with .WithOptions():

var results = await client.CreateQuery<LogEntry>()
    .WithOptions(new EsqlQueryOptions { TimeZone = "America/New_York", Locale = "en-US" })
    .From("logs-*")
    .Where(l => l.Level == "ERROR")
    .ToListAsync();

Use RequestConfiguration for transport-level overrides (timeouts, authentication, headers):

var results = await client.CreateQuery<LogEntry>()
    .WithOptions(new EsqlQueryOptions
    {
        RequestConfiguration = new RequestConfiguration { RequestTimeout = TimeSpan.FromSeconds(120) }
    })
    .From("logs-*")
    .ToListAsync();

For async queries, combine it with EsqlAsyncQueryOptions:

await using var asyncQuery = await client.CreateQuery<LogEntry>()
    .WithOptions(new EsqlQueryOptions { TimeZone = "UTC" })
    .From("logs-*")
    .Where(l => l.Level == "ERROR")
    .ToAsyncQueryAsync(new EsqlAsyncQueryOptions
    {
        WaitForCompletionTimeout = TimeSpan.FromSeconds(5),
        KeepAlive = TimeSpan.FromMinutes(10)
    });

Testing

Generate ES|QL strings without an Elasticsearch connection:

var provider = new EsqlQueryProvider(MyContext.Default);
var esql = new EsqlQueryable<Product>(provider)
    .From("products")
    .Where(p => p.InStock && p.Price < 50)
    .OrderBy(p => p.Name)
    .ToString();

Assert.Equal("""
    FROM products
    | WHERE (in_stock == true AND price < 50)
    | SORT name
    """, esql);

AOT Compatible

The full pipeline is AOT ready when used with a source-generated JsonSerializerContext:

• Query translation (Elastic.Esql) -- pure expression tree walking, no reflection-based serialization
• Field resolution (System.Text.Json metadata) -- source-generated context aligned with your JSON contracts
• HTTP transport (Elastic.Transport) -- AOT-compatible HTTP client

Use a source-generated JsonSerializerContext so field names, JSON serialization, and ES|QL queries all derive from the same compile-time source of truth.

Architecture

Elastic.Clients.Esql          -- This package: EsqlClient, transport, execution
  references:
    Elastic.Esql               -- LINQ-to-ES|QL translation (no HTTP dependency)
    Elastic.Transport          -- Low-level HTTP client for Elasticsearch

If you only need ES|QL string generation (no execution), depend on Elastic.Esql directly.