LINQ para Elasticsearch ES|QL: escreva Consultas em C# e Consulte o Elasticsearch

Florian Bernd,Martijn Laarman — Wed, 01 Apr 2026 00:00:00 GMT

A partir das versões 9.3.4 e 8.19.18, o cliente Elasticsearch .NET inclui um provedor de Consulta Integrada em Linguagem (LINQ) que traduz expressões LINQ em C# para a Linguagem de Consulta Elasticsearch (ES|QL) em tempo de execução. Em vez de escrever manualmente as strings ES|QL, você compõe consultas usando Where, Select, OrderBy, GroupBy e outros operadores padrão. O provedor cuida da tradução, parametrização e desserialização dos resultados, inclusive o streaming por linha que mantém o uso da memória constante, independentemente do tamanho do conjunto de resultados.

Sua primeira consulta

Comece definindo um objeto CLR simples (POCO) que mapeia para o seu índice Elasticsearch. Os nomes das propriedades são resolvidos para nomes de coluna ES|QL via atributos System.Text.Json padrão, como [JsonPropertyName], ou via JsonNamingPolicy configurado. As mesmas regras de serialização de origem que se aplicam ao restante do cliente também se aplicam aqui.

using System.Text.Json.Serialization; public class Product { [JsonPropertyName("product_id")] public string Id { get; set; } public string Name { get; set; } public string Brand { get; set; } [JsonPropertyName("price_usd")] public double Price { get; set; } [JsonPropertyName("in_stock")] public bool InStock { get; set; } }

Com o tipo definido, uma consulta fica assim:

O provedor traduz isso para o seguinte ES|QL:

Há alguns detalhes a serem observados:

Resolução do nome da propriedade: p.Price se torna price_usd por causa do atributo [JsonPropertyName], e p.Brand se torna brand seguindo a política de nomenclatura padrão camelCase.
Captura de parâmetros: As variáveis C# minPrice e brand são capturadas como parâmetros nomeados (?minPrice, ?brand). Eles são enviados separadamente da string de consulta na carga JSON, o que evita injeções e permite o armazenamento em cache do plano de consulta no lado do servidor.
Streaming: QueryAsync retorna IAsyncEnumerable. As linhas são materializadas uma de cada vez à medida que chegam do Elasticsearch.

Você também pode inspecionar a consulta gerada e seus parâmetros sem executá-la:

var query = client.Esql.CreateQuery() .Where(p => p.InStock && p.Price >= minPrice && p.Brand == brand) .OrderByDescending(p => p.Price) .Take(10); Console.WriteLine(query.ToEsqlString()); // FROM products | WHERE (in_stock == true AND price_usd >= 100) | SORT price_usd DESC | LIMIT 10 Console.WriteLine(query.ToEsqlString(inlineParameters: false)); // FROM products | WHERE (in_stock == true AND price_usd >= ?minPrice AND brand == ?brand) | SORT price_usd DESC | LIMIT 10 var parameters = query.GetParameters(); // { "minPrice": 100.0, "brand": "TechCorp" }

Como funciona? Uma breve revisão sobre o LINQ

O mecanismo que torna possíveis os provedores LINQ é a distinção entre IEnumerable e IQueryable.

Quando você chama .Where(p => p.Price > 100) em um IEnumerable, o lambda compila para um Func, um delegado regular que o runtime executa em processo. Isto é LINQ-to-Objects.

Quando você chama o mesmo método em um IQueryable, o compilador C# envolve o lambda em um Expression> em vez disso. Essa é uma estrutura de dados que representa a estrutura do código em vez de sua forma executável. A árvore de expressões pode ser inspecionada, analisada e traduzida para outra linguagem em tempo de execução.

// IEnumerable: the lambda is a compiled delegate IEnumerable local = products.Where(p => p.Price > 100); // IQueryable: the lambda is an expression tree, a data structure IQueryable remote = queryable.Where(p => p.Price > 100);

A interface IQueryProvider é o ponto de extensão. Qualquer provedor pode implementar CreateQuery e Execute para traduzir essas árvores de expressão para um idioma de destino. O Entity Framework usa isso para emitir SQL. O provedor LINQ to ES|QL o usa para emitir ES|QL.

A árvore de expressões para a consulta acima fica assim:

Árvore de expressões para a consulta de exemplo.

A árvore é aninhada do avesso: Take envolve OrderByDescending, que envolve Where, que envolve From, que envolve a raiz EsqlQueryable constante. O predicado Where é ele próprio uma subárvore de BinaryExpression nós para os operadores &&, >= e ==, com folhas MemberExpression para acessos a propriedades e capturas de fechamento para as variáveis minPrice e brand. Essa é a estrutura de dados que o provedor percorre para produzir o ES|QL final.

Nos bastidores: O pipeline de tradução

O caminho de uma expressão LINQ até os resultados da consulta segue um pipeline de seis estágios:

Visão geral do pipeline de tradução.

1. Captura da árvore de expressão

Quando você encadeia .Where(), .OrderBy(), .Take() e outros operadores em um IQueryable, a infraestrutura padrão do LINQ constrói uma árvore de expressões. EsqlQueryable implementa IQueryable e delega para EsqlQueryProvider.

2. Tradução

Quando a consulta é executada (enumerando, chamando ToList() ou usando await foreach)), o EsqlExpressionVisitor percorre a árvore de expressões de dentro para fora. Ele despacha cada chamada de método LINQ para um visitante especializado:

Visitante

Traduz

Para

WhereClauseVisitor

.Where(predicate)

Condição ONDE

SelectProjectionVisitor

.Select(selector)

EVAL + KEEP + RENOMEAR

GroupByVisitor

.GroupBy().Select()

ESTATÍSTICAS ... POR

OrderByVisitor

.OrderBy() / .ThenBy()

Campo SORT [ASC\|DESC]

EsqlFunctionTranslator

EsqlFunctions.*, Math.*, métodos de string

80+ funções ES|QL

Durante a tradução, as variáveis C# referenciadas em expressões são capturadas como parâmetros nomeados.

3. Modelo de consulta

Os visitantes não produzem diretamente as strings. Em vez disso, produzem QueryCommand objetos, uma representação intermediária imutável. Um FromCommand, um WhereCommand, um SortCommand, e um LimitCommand, cada um representando um comando de processamento ES|QL. Eles são coletados para um modelo EsqlQuery.

Modelo de consulta e padrão de comando.

Esse modelo intermediário é desacoplado tanto da árvore de expressão quanto do formato de saída. Ele pode ser inspecionado, interceptado (via IEsqlQueryInterceptor) ou modificado antes da formatação.

4. Formatação

EsqlFormatter visita cada QueryCommand em ordem e gera a string final do ES|QL. Cada comando se transforma em uma linha, separada pelo operador pipe (|), que o ES|QL utiliza para encadear comandos de processamento. Identificadores que contêm caracteres especiais são automaticamente escapados com backticks.

5. Execução

A string ES|QL formatada e os parâmetros capturados são enviados para o endpoint /_query do Elasticsearch no corpo da requisição, como JSON. A interface IEsqlQueryExecutor abstrai a camada de transporte, e é aí que a arquitetura de pacotes em camadas se aplica.

6. Materialização

EsqlResponseReader transmite a resposta JSON sem armazenar todo o conjunto de resultados na memória. Uma árvore ColumnLayout , pré-computada uma vez por consulta, mapeia ES|QL nomes de colunas (como address.street, address.city) para propriedades aninhadas do POCO. Cada linha é montada em uma instância T e gerada uma de cada vez via IEnumerable ou IAsyncEnumerable.

A arquitetura em camadas

A funcionalidade LINQ para ES|QL é dividida em três pacotes:

Arquitetura de pacotes. Elastic.Esql é o motor de tradução puro. Ele não tem dependência HTTP e contém os visitantes de expressões, o modelo de consulta, o formatador e o leitor de resposta. Você pode usá-lo de forma independente para criar e inspecionar consultas ES|QL sem nenhuma conexão com o Elasticsearch. Isso é útil para testes, logging de consultas ou para criar a sua camada de execução.

// Translation-only: no Elasticsearch connection needed var provider = new EsqlQueryProvider(); var query = new EsqlQueryable(provider) .From("products") .Where(p => p.InStock) .OrderByDescending(p => p.Price); Console.WriteLine(query.ToEsqlString()); // FROM products | WHERE in_stock == true | SORT price_usd DESC

Elastic.Clients.Esql é um cliente ES|QL leve e independente. Ele adiciona a execução HTTP além de Elastic.Esql via Elastic.Transport. Se sua aplicação só precisa do ES|QL e nenhuma das outras APIs do Elasticsearch, essa é a opção de dependência mínima.

Elastic.Clients.Elasticsearch é o cliente completo do Elasticsearch .NET. Também se baseia em Elastic.Esql e expõe o provedor LINQ via espaço de nome client.Esql. Esse é o ponto de entrada recomendado para a maioria das aplicações.

Ambos os pacotes da camada de execução fornecem a própria implementação do IEsqlQueryExecutor, a interface estratégica que conecta tradução e transporte.

Todos os três pacotes são compatíveis com o Native AOT quando usados com um JsonSerializerContext gerado por fonte. Para as informações completas sobre o cliente, consulte a documentação do Native AOT.

Além do básico

O exemplo acima abordou filtragem, classificação e paginação. O provedor aceita um conjunto mais amplo de operações.

Agregações

GroupBy, combinado com funções agregadas em Select, traduz-se em ES|QL STATS ... BY:

var stats = client.Esql.Query(q => q .GroupBy(p => p.Brand) .Select(g => new { Brand = g.Key, Count = g.Count(), AvgPrice = g.Average(p => p.Price), MaxPrice = g.Max(p => p.Price) })); // -> FROM products | STATS COUNT(*), AVG(price_usd), MAX(price_usd) BY brand

Projeções

Select, com tipos anônimos gera os comandos EVAL, KEEP e RENAME:

var query = client.Esql.CreateQuery() .Select(p => new { ProductName = p.Name, p.Price, p.InStock }); // -> FROM products | KEEP name, price_usd, in_stock | RENAME name AS ProductName

Biblioteca repleta de funções

Mais de 80 funções ES|QL estão disponíveis via classe EsqlFunctions, cobrindo data/hora, string, matemática, IP, correspondência de padrões e pontuação. Métodos Math.* padrão e string.* também são traduzidos:

.Where(p => p.Name.Contains("Pro")) // -> WHERE name LIKE "*Pro*" .Where(p => EsqlFunctions.CidrMatch( // -> WHERE CIDR_MATCH(ip, "10.0.0.0/8") p.IpAddress, "10.0.0.0/8"))

PESQUISAR ENTRAR

Consultas cruzadas de índice traduzem-se para ES|QL LOOKUP JOIN:

var enriched = client.Esql.Query(q => q .LookupJoin( "category-lookup-index", product => product.Id, category => category.CategoryId, (product, category) => new { product.Name, category!.CategoryLabel }));

Acesso direto ao ES|QL bruto

Para recursos do ES|QL que ainda não são cobertos pelo provedor LINQ, você pode adicionar fragmentos brutos:

var results = client.Esql.Query(q => q .Where(p => p.InStock) .RawEsql("| EVAL discounted = price_usd * 0.9"));

Consultas assíncronas do lado do servidor

Para consultas de longa duração, envie-as para processamento em segundo plano no servidor:

await using var asyncQuery = await client.Esql.SubmitAsyncQueryAsync( q => q.Where(p => p.InStock), asyncQueryOptions: new EsqlAsyncQueryOptions { WaitForCompletionTimeout = TimeSpan.FromSeconds(5), KeepAlive = TimeSpan.FromMinutes(10) }); await asyncQuery.WaitForCompletionAsync(); await foreach (var product in asyncQuery.AsAsyncEnumerable()) Console.WriteLine(product.Name);

Consultas assíncronas do lado do servidor são úteis principalmente em consultas analíticas de longa duração/processamento de grandes conjuntos de dados que podem exceder os tempos-limite típicos, ou em ambientes sensíveis a tempo-limite com balanceadores de carga, gateways de API ou proxies que impõem tempos-limite de HTTP rigorosos. Consultas assíncronas evitam quedas de conexão ao separar o envio da obtenção dos resultados.

Para começar

LINQ to ES|QL está disponível a partir de:

Elastic.Clients.Elasticsearch v9.3.4 (9.x branch)
Elastic.Clients.Elasticsearch v8.19.18 (8.x branch)

Instale do NuGet:

dotnet add package Elastic.Clients.Elasticsearch

Os pontos de entrada estão em client.Esql:

Método

Returns

Caso de uso

Query(...)

IEnumerable

Execução síncrona

QueryAsync(...)

IAsyncEnumerable

Streaming assíncrono

CreateQuery()

IEsqlQueryable

Composição avançada e inspeção

SubmitAsyncQueryAsync(...)

EsqlAsyncQuery

Consultas de longa duração no servidor

Para obter a referência completa de recursos, incluindo opções de consulta, acesso a vários campos, objetos aninhados e tratamento de campos de vários valores, consulte a documentação do LINQ to ES|QL.

Conclusão

Do LINQ para ES|QL traz toda a expressividade do C# LINQ para a linguagem de consulta ES|QL do Elasticsearch, para que você escreva consultas componíveis e com tipagem forte sem precisar criar manualmente as strings de consulta. Com captura automática de parâmetros, materialização em streaming e arquitetura de pacotes em camadas que se adapta de traduções independentes ao cliente completo do Elasticsearch, ele se integra naturalmente a aplicações .NET de qualquer tamanho. Instale o cliente mais recente, direcione suas expressões LINQ para um índice e deixe o provedor cuidar do resto.

Martijn Laarman - Elasticsearch Labs