Como o MATCH e TO_TEXT habilitam a busca de texto completo em qualquer expressão ES|QL

Vamos começar com uma consulta que era impossível no Elasticsearch 9.4, que usa o comando EVAL:

Neste exemplo, resumo não possui mapeamento ou configuração de analisador. Também não está associado a nenhum índice invertido. Ele existe apenas durante a vida útil dessa consulta, mas agora você pode buscar mesmo assim. Duas adições fazem isso funcionar.

Primeiro, MATCH agora aceita qualquer expressão como seu primeiro argumento, não apenas um campo mapeado. Isso inclui colunas produzidas pelo EVAL e resultados de funções usados em linha. Também inclui campos não mapeados carregados diretamente do documento original. Além disso, todos os tipos de dados normalmente aceitos pelo MATCH são suportados neste novo caso de uso.

A segunda parte disso é a nova função TO_TEXT, que é a primeira função de conversão ES|QL que produz saída do tipo texto. Até agora, colunas de texto só podiam vir de campos mapeados indexados, e todas as strings produzidas pelas expressões ES|QL eram valores de palavras-chave em vez de texto. A distinção importa porque o MATCH trata os dois de forma diferente: os valores do texto são analisados, enquanto os valores das palavras-chave são comparados exatamente, espelhando como uma consulta MATCH em um campo indexado se reescreve para uma consulta de termo. TO_TEXT(x) é como você diz ao ES|QL: trate essa sequência como texto completo.

Este é incluído como uma prévia técnica no Elasticsearch 9.5 e, por isso, possui algumas limitações:

• No momento, funciona apenas para filtragem. Um MATCH em uma expressão ainda não contribui para a pontuação de relevância; apenas correspondências em campos indexados afetam a pontuação.

• Opções de consulta como fuzziness e outras ainda não são suportadas ao combinar uma expressão.

• O texto em tempo de execução é analisado com o analisador padrão. Isso ainda não é configurável.

Trabalhos estão em andamento para abordar essas limitações.

Por que usar a busca em texto completo em vez de LIKE ou RLIKE no ES|QL?

ES|QL já tinha duas formas de buscar strings sem índice: LIKE (padrões curinga) e RLIKE (expressões regulares). Ambos funcionam em qualquer expressão de string, então é justo perguntar o que o MATCH adiciona. A resposta é análise, uma forma mais avançada de busca que utiliza técnicas como stemming e sinônimos. Também utiliza o tratamento de stopwords.

LIKE é simples correspondência de substrings, sem qualquer compreensão das palavras que compõem uma string. Digamos, por exemplo, que você esteja procurando mensagens de log sobre uma raposa:

Isso perde "Fox avistado perto do galinheiro" devido à capitalização, ao mesmo tempo em que iguala "Outfoxed pela competição", que não tem nada a ver com uma raposa. Ele falha em ambas as direções, com falsos negativos devido à capitalização e falsos positivos em substrings contidas em outras palavras.

Expressões regulares podem corrigir o problema do caso, mas o problema da fronteira de palavras fica feio rapidamente. Algo como:

E nem isso está certo ainda. Ele deixa de encontrar "fox" no final de uma frase seguida de ! ou ?, e não considera tabulações, aspas ou parênteses. Cada correção faz o padrão mais longo, e a próxima pessoa que ler a consulta precisa fazer engenharia reversa do que ele realmente está fazendo.

MATCH faz o problema desaparecer, pois executa tanto a consulta quanto o valor por um analisador, que tokeniza texto em termos minúsculos e então faz a correspondência termo contra termo:

Essa consulta corresponderá a valores como "A rápida raposa marrom" e "FOX avistada perto do galinheiro", mas não a "Enganada pela concorrência" ou "protocolo FOXTROT ativado", independentemente de qualquer pontuação ao redor das palavras. Claro, tudo isso funciona para consultas de múltiplos termos, como MATCH(TO_TEXT(message), "brown fox"), exatamente do jeito que você esperaria.

Estão em andamento trabalhos para viabilizar o uso dos 36 analisadores de linguagem dedicados, com suporte para linguagens naturais em dados que nunca foram indexados ou mapeados.

Casos de uso de busca de texto completo para dados não indexados e não mapeados

Os exemplos acima pesquisaram valores calculados a partir de campos mapeados. Os casos de uso mais interessantes do ES|QL MATCH em expressões envolvem dados que nunca foram pesquisáveis. Vamos examinar alguns.

Como buscar campos não mapeados no ES|QL sem adicionar um mapeamento

Às vezes, você deliberadamente deixa um campo fora dos seus mapeamentos, como um rastreamento de pilha verboso ou uma carga útil da requisição bruta. Você pode até mesmo omitir um blob para depuração. Indexar um desses consumiria espaço em disco e na heap em cada documento e não valeria a pena para um campo que você pode consultar uma vez por trimestre.

Essa decisão sempre foi final, porque campos não mapeados eram totalmente invisíveis para consultas. No Elasticsearch 9.5, você pode usar SET unmapped_fields="load" para fazer o ES|QL carregar campos não mapeados diretamente do documento de origem como palavras-chave. Em seguida, envolva isso em TO_TEXT, e agora você pode executar uma busca de texto completo:

Aqui, stack_trace nunca foi mapeado. Cada valor é obtido dos documentos originais e analisado em tempo real. Eles são combinados linha por linha. Isso dá trabalho de verdade e nunca será tão rápido quanto uma pesquisa por índice invertido. Mas agora, aquele campo que você não indexou pode ser pesquisado. Você pode manter o mapeamento pequeno para o caso do dia a dia e ainda responder à pergunta uma vez por trimestre quando importa.

Busca de texto completo em um campo de palavra-chave sem reindexação

Os campos de palavras-chave podem fazer muito. Eles oferecem correspondência exata, agregações rápidas e ordenação, por isso tantos campos acabam mapeados dessa forma. Mas os mapeamentos são decididos quando os dados chegam, e é fácil acabar em uma situação em que você queira fazer algo diferente do que pretendia originalmente com seus dados. Talvez product_name tenha sido mapeado como palavra-chave porque os dashboards fazem agregações com ele e, depois de receber um ano de dados de produto, alguém queira poder buscar valores dentro de product_name.

A resposta antiga era mudar o mapeamento para texto (ou adicionar um multicampo) e reindexar tudo. Isso pode ser demorado e caro, e em muitos casos, os usuários simplesmente não vão querer se preocupar com isso. A nova resposta é uma chamada de função:

TO_TEXT converte os valores das palavras-chave em texto em tempo real, então o MATCH os analisa em vez de compará-los exatamente. Isso permite consultar um campo de palavra-chave sem criar um mapeamento ou reindexar o documento de origem. Se a busca se tornar uma consulta diária, indexar o campo como texto ainda é a melhor opção a longo prazo, mas TO_TEXT lhe dá uma resposta hoje, sem nenhum esforço extra.

Buscar no mesmo campo entre índices com mapeamentos diferentes

ES|QL pode abranger muitos índices, e o mesmo campo não precisa ser sempre igual em todos eles. Quando o mesmo campo tem tipos diferentes em índices distintos, ES|QL o trata como um tipo de união, e uma função de conversão resolve o conflito. Vamos considerar um exemplo em que o campo mensagem é do tipo texto no modelo de índice deste ano, mas era uma palavra-chave no do ano passado:

Cada valor é analisado no momento da consulta, seja do índice de texto ou do índice de palavras-chave. Os valores das palavras-chave dos índices antigos são tokenizados e em minúsculas como todo o resto, então "connection reset" encontra "Connection RESET by peer", não importa em qual índice esteja.

Outro caso interessante é quando um campo é mapeado em apenas um índice, mas também presente (e não mapeado) no outro:

Há uma nuance que vale a pena destacar aqui. Se error_details estiver mapeado em logs-2026, mas não em logs-2025, o Elasticsearch não pode enviar essa consulta para Lucene, porque os índices onde o campo não está mapeado retornariam silenciosamente nenhuma correspondência. Em vez disso, o planejador percebe que o campo pode não estar mapeado e avalia toda a MATCH linha por linha, de onde quer que as linhas tenham vindo. Você não precisa saber quais índices têm o campo mapeado; a consulta apenas responde à questão.

Como ES|QL analisa texto no momento da consulta sem um índice invertido

Quando o ES|QL planeja uma correspondência (match) contra uma expressão, ele analisa a string de consulta uma vez, no início, em um conjunto de termos. A forma como cada linha é então avaliada depende do tipo da expressão:

Tipo de expressão

Processamento

Comportamento de correspondência

texto (via TO_TEXT)

O analisador divide o valor em termos minúsculos

Comparação token-contra-token; uma linha corresponde se qualquer token for igual a qualquer termo de consulta (semântica OU)

palavra-chave, IP, data, numérico

Sem análise; constante de consulta convertida uma vez para o tipo nativo

Comparação exata por linha

Ambos os caminhos ignoram completamente o Lucene e avaliam os valores linha por linha. O caminho não textual reflete exatamente o que uma consulta match faz quando executada no Lucene para esses tipos de campo, de modo que a semântica permanece consistente independentemente de a sua consulta atingir ou não um índice.

Uma consulta de índice invertido faz seu trabalho no momento da ingestão e nunca acessa documentos que não correspondem no momento da consulta. Um match em tempo de execução faz essa análise no momento da consulta, para cada linha que a alcança. Uma é rápida porque o trabalho já aconteceu; a outra é flexível porque os dados não precisam ter sido indexados de forma alguma.

O que vem a seguir para a busca de texto completo no ES|QL

Tudo o que está neste post é a primeira parte de um esforço maior para fazer a busca no ES|QL funcionar em qualquer coisa, não apenas no que você indexou antes. As limitações mencionadas anteriormente estão sendo trabalhadas ativamente, e o roadmap vai além:

• Pontuação. Correspondências em tempo de execução contribuem para _score, então você pode ordenar por relevância mesmo quando os dados nunca foram indexados.

• MATCH_PHRASE em expressões. Já disponível no Elastic Cloud Serverless, e chegando ao Elastic Stack na versão 9.6.

• Analisadores configuráveis. Suporte a analisadores para MATCH e MATCH_PHRASE em expressões, permitindo analisadores de linguagem, derivação (stemming) e sinônimos no momento da consulta.

• Opções do MATCH. Opções como fuzziness e operador para correspondências em tempo real.

• Busca vetorial. Gerando vetores de incorporação por linha e executando k-nearest neighbors (kNN) em expressões dense_vector em tempo de execução, trazendo também a pesquisa semântica para dados não indexados.

Experimente hoje a busca de texto completo do ES|QL em expressões

Você pode experimentar a busca em tempo de execução hoje mesmo. Já está disponível no Elastic Cloud Serverless, onde as novas capacidades do ES|QL são lançadas primeiro, e ele é disponibilizado como uma prévia técnica no Elasticsearch 9.5. Comece consultando a referência das funções de pesquisa e verifique a página de limitações do ES|QL para conhecer os limites atuais. É uma prévia técnica porque queremos seu feedback: se você buscar algo que nunca foi indexado e isso o surpreender, seja positiva ou negativamente, gostaríamos muito de saber.

Novidades na criação do dashboard de IA do Kibana

Capacidade

Prévia técnica (9.4)

GA (9,5)

Tratamento de erros

Sem nova tentativa em consultas ES|QL

Tenta novamente automaticamente até três vezes, com inspeção e ajuste da consulta

Custo de geração ES|QL

Todas as consultas são roteadas pelo modelo primário

Roteamento em camadas de modelos, até 5 vezes mais barato

Intervalo de tempo

Janela padrão fixa

Seleção automática baseada na distribuição temporal dos dados

Controles de filtro

Sem suporte

Adicionado automaticamente para os campos mais relevantes

Gráficos Vega-Lite

Sem suporte

Criação em linguagem natural, incluindo diagramas de dispersão, diagramas de caixa, formatação condicional e dicas de ferramenta personalizadas

Edição de gráficos

Sem suporte

Editar painéis existentes do Vega-Lite usando linguagem natural

Recuperação automática de erros para geração de dashboards por IA

Na prévia técnica, o agente não tentou novamente as consultas ES|QL com falha. Na versão 9.5, ele detecta erros de consulta e tenta até três vezes, inspecionando cada erro e ajustando a consulta antes de desistir. Na prática, isso elimina a maioria dos problemas de painéis vazios e produz dashboards que renderizam corretamente na primeira tentativa.

Por que a criação de dashboards de IA é mais barata no Elastic 9.5?

Nem toda etapa na geração de dashboards exige o mesmo nível de raciocínio. Na 9.5, ES|QL passa por um modelo mais leve por padrão e retorna ao modelo primário apenas quando necessário. Se seu conector usa o Claude Opus 4.8 da Anthropic, isso significa que a geração de ES|QL em todos os painéis fica 5 vezes mais barata.

Seleção automática do intervalo de tempo com base nos seus dados

Dashboards só são úteis quando mostram o intervalo de dados correto. Agora, o agente aplica uma lógica aprimorada para escolher um intervalo de tempo que faça sentido para os dados que está consultando, a menos que o usuário solicite um intervalo de tempo específico. Ele considera a distribuição temporal dos dados e ajusta o intervalo de acordo, seja para a última hora em um incidente em andamento ou para os últimos 90 dias em uma análise de tendências, em vez de recorrer a uma janela fixa.

Controles automáticos de filtro em dashboards gerados por IA

A criação de dashboards agora oferece suporte a controles; ou seja, filtros interativos que permitem aos usuários filtrar um dashboard pelos valores dos campos sem editar as consultas subjacentes. Ao gerar um dashboard, o agente adiciona automaticamente controles na parte superior para os campos mais relevantes para filtragem.

Gráficos Vega-Lite a partir da linguagem natural: tipos de gráficos e formatação além dos padrões

Vega e Vega-Lite suportam uma ampla variedade de tipos de gráficos e personalizações no Kibana. Com a versão 9.5, você pode criá-los a partir de uma linguagem natural em vez de escrever o código você mesmo. 

Diagramas de dispersão, diagramas de caixa e mais tipos de gráficos Vega-Lite

Diagramas de dispersão, gráficos de caixa, múltiplos pequenos facetados, gráficos de bolhas e gráficos de composição (como combinar histogramas com mapas de calor), entre muitos outros, são suportados pelo Vega-Lite. Um prompt como Mostre-me um gráfico de dispersão entre tempo de resposta e tamanho da requisição, colorido pelo nome do serviço, gera um painel Vega-Lite com os mapeamentos de dados corretos. Usam as paletas de cores padrão do Kibana para se misturar com o restante do dashboard.

Formatação condicional, dicas de ferramentas personalizadas e rótulos em gráficos padrão

Mesmo para tipos de gráficos que já são nativos de dashboards, como barra, linha ou área, às vezes você precisa de mais controle do que as capacidades padrão oferecem. O Vega-Lite via chat preenche essa lacuna. Alguns exemplos incluem:

• Formatação condicional de cores: colorir pontos de dados acima de um limiar de forma diferente; por exemplo, tornar vermelhos os pontos de dados em uma linha ou barras quando algum indicador ultrapassa seu objetivo de nível de serviço (SLO). Peça ao agente algo como pinte de vermelho qualquer ponto acima de 500ms no meu gráfico de linhas.

  

• Marcas e etiquetas personalizadas: adicione emojis, símbolos ou etiquetas de texto em linha aos pontos de dados para indicadores de status de fácil visualização.

  

• Dicas de ferramentas personalizadas: enriqueça as dicas exibidas ao passar o cursor com mais métricas, contexto ou valores calculados que não fazem parte dos eixos do gráfico. Peça algo como Adicionar uma dica de ferramenta que mostre o total de registros e a % por barra.

  

Isso também funciona para editar gráficos Vega existentes. Se você tem um painel Vega-Lite que precisa de ajustes, como alterar uma escala de cores, ajustar um eixo ou mudar o tipo de marca, descreva a mudança no bate-papo em vez de se aprofundar no código JSON.

Como construímos a geração em linguagem natural do Vega-Lite no Kibana

Gerar um gráfico Vega-Lite a partir de uma frase não consiste em fazer um único prompt para o modelo gerar o JSON. Construímos um pequeno pipeline autônomo que transforma a intenção em linguagem natural em um gráfico validado e respaldado por dados.

Quando um pedido chega, o agente primeiro determina se o Vega-Lite é a opção adequada. Para requisições Vega-Lite, a visualização se baseia em uma consulta ES|QL real no Elasticsearch e então usa um modelo para gerar o código Vega-Lite. Antes da renderização, o resultado passa por uma camada de normalização que corrige o esquema e vincula a consulta canônica. Também aplica transformações para segurança na renderização.

Algumas escolhas de design tornam esse fluxo de trabalho confiável:

• Chamada tipada de ferramenta: a criação de gráficos é uma invocação de ferramenta estruturada, em vez de um código Vega-Lite de formato livre colado na conversa.

• Geração restrita: o modelo gera código Vega-Lite dentro de um esquema definido, tornando a saída mais previsível e fácil de validar.

• Exemplos selecionados: padrões estruturais, como facetas, marcas em camadas e mapas de calor, fornecem orientação sem copiar os dados subjacentes.

• Loops de execução e verificação: as consultas são executadas antes da criação do gráfico e as falhas de validação acionam novas tentativas corretivas para a geração de ES|QL.

Experimente a criação de dashboards por IA e gráficos Vega-Lite em Kibana

Para experimentar a criação de dashboards em linguagem natural e os gráficos Vega-Lite, atualize para o Elastic 9.5 (ou inicie um teste gratuito) e abra o chat no Kibana. Depois, peça para ele criar um dashboard a partir dos seus dados. Para Vega-Lite, tente pedir um tipo de gráfico que você sempre quis, mas nunca construiu, como um gráfico de dispersão ou um gráfico de bolhas. Se o resultado não estiver totalmente certo, diga ao agente o que mudar. Ele itera com você.

Isso requer uma licença empresarial. Comece agora mesmo.

O lançamento e o cronograma de quaisquer recursos ou funcionalidades descritos neste artigo permanecem a exclusivo critério da Elastic. Os recursos ou funcionalidades não disponíveis no momento poderão não ser entregues no prazo previsto ou sequer serem disponibilizados.

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.

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<T> retorna IAsyncEnumerable<T>. 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:

Como funciona? Uma breve revisão sobre o LINQ

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

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

Quando você chama o mesmo método em um IQueryable<T>, o compilador C# envolve o lambda em um Expression<Func<Product, bool>> 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.

A interface IQueryProvider é o ponto de extensão. Qualquer provedor pode implementar CreateQuery<T> e Execute<T> 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<Product> 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<T>, a infraestrutura padrão do LINQ constrói uma árvore de expressões. EsqlQueryable<T> implementa IQueryable<T> 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<T> ou IAsyncEnumerable<T>.

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.

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:

Projeções

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

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:

PESQUISAR ENTRAR

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

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:

Consultas assíncronas do lado do servidor

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

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<T>(...)

IEnumerable<T>

Execução síncrona

QueryAsync<T>(...)

IAsyncEnumerable<T>

Streaming assíncrono

CreateQuery<T>()

IEsqlQueryable<T>

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

SubmitAsyncQueryAsync<T>(...)

EsqlAsyncQuery<T>

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.

Por que isso é importante

A maioria dos fluxos de trabalho analíticos típicos acaba se resumindo ao agrupamento de dados. Seja calculando a média de bytes por host, contando eventos por usuário ou agregando métricas entre dimensões, a operação principal é a mesma: mapear chaves para grupos e atualizar agregados em execução.

Em pequena escala, praticamente qualquer tabela hash razoável funciona bem. Em grande escala (centenas de milhões de documentos e milhões de grupos distintos), os detalhes começam a importar. Fatores de carregamento, estratégia de sondagem, layout da memória e comportamento do cache podem fazer a diferença entre um desempenho linear e uma série de falhas de cache.

O Elasticsearch oferece suporte a essas cargas de trabalho há anos, mas estamos sempre buscando oportunidades para modernizar os algoritmos principais. Assim, avaliamos uma abordagem mais recente inspirada nas Swiss Tables e a aplicamos à maneira como o ES|QL calcula as estatísticas.

Afinal, o que são Swiss Tables?

As Swiss Tables são uma família de tabelas de hash modernas popularizadas pelo SwissTable do Google e posteriormente adotadas na Abseil e em outras bibliotecas.

Tabelas hash tradicionais gastam muito tempo atrás de ponteiros ou carregando chaves apenas para descobrir que não correspondem. O principal recurso das Swiss Tables é a capacidade de rejeitar a maioria das sondagens usando uma pequena estrutura de matriz residente em cache, armazenada separadamente das chaves e valores, chamada de bytes de controle, para reduzir drasticamente o tráfego de memória.

Cada byte de controle representa um único slot e, em nosso caso, codifica duas coisas: se o slot está vazio e uma pequena impressão digital derivada do hash. Esses bytes de controle são dispostos de maneira contígua na memória, geralmente em grupos de 16, tornando-os ideais para processamento de instrução única e dados múltiplos (SIMD).

Em vez de sondar um slot de cada vez, as Swiss Tables analisam um bloco inteiro de controle de bytes usando instruções vetoriais. Em uma única operação, a CPU compara a impressão digital da chave de entrada com 16 slots e retira as entradas vazias. Somente os poucos candidatos que sobrevivem a esse processo rápido precisam ser carregados e comparados às chaves reais.

Esse design troca uma pequena quantidade extra de metadados por uma melhor localidade de cache e muito menos carregamentos aleatórios. À medida que a tabela cresce e as cadeias de sondagem se alongam, essas propriedades tornam-se cada vez mais valiosas.

SIMD no centro

A verdadeira estrela do espetáculo é o SIMD.

Bytes de controle não são apenas compactos, eles também são explicitamente projetados para serem processados com instruções vetoriais. Uma única comparação SIMD pode verificar 16 impressões digitais de uma vez, transformando o que normalmente seria um loop em algumas operações amplas. Por exemplo:

Na prática, isso significa:

• Menos ramificações.

• Cadeias de sondagem mais curtas.

• Menos carregamentos da memória de chave e valor.

• Utilização muito melhor das unidades de execução da CPU.

A maioria das pesquisas nunca passa da verificação do byte de controle. Quando isso acontece, o restante do trabalho é focado e previsível. Esse é exatamente o tipo de carga de trabalho que CPUs modernas fazem bem.

SIMD nos bastidores

Para os leitores que gostam de espiar os bastidores, aqui está o que acontece ao inserir uma nova chave na tabela. Usamos a Panama Vector API com vetores de 128 bits, operando assim em 16 bytes de controle em paralelo.

O trecho a seguir mostra o código gerado em um Intel Rocket Lake com AVX-512. Embora as instruções reflitam esse ambiente, o design não depende do AVX-512. As mesmas operações vetoriais de alto nível são emitidas em outras plataformas usando instruções equivalentes (por exemplo, AVX2, SSE ou NEON).

Cada instrução tem um papel claro no processo de inserção:

• vmovdqu: Carrega 16 bytes de controle consecutivos no registrador xmm0 de 128 bits.

• vpbroadcastb: Replica a impressão digital de 7 bits da nova chave em todas as faixas do registrador xmm1.

• vpcmpeqb: Compara cada byte de controle com a impressão digital transmitida, produzindo uma máscara de possíveis correspondências.

• kmovq + test: Move a máscara para um registrador de uso geral e verifica rapidamente se existe uma correspondência.

Finalmente, decidimos sondar grupos de 16 bytes de controle por vez, pois o benchmarking mostrou que a expansão para 32 ou 64 bytes com registros mais amplos não oferecia nenhum benefício mensurável de desempenho.

Integração em ES|QL

Adotar o hashing com a técnica de Swiss Tables no Elasticsearch não foi uma simples substituição. O ES|QL tem requisitos rigorosos em relação à contabilidade de memória, segurança e integração com o restante do motor de computação.

Integramos a nova tabela hash de maneira precisa com o gerenciamento de memória do Elasticsearch, incluindo o reciclador de páginas e a contabilização de mecanismos de interrupção, garantindo que as alocações permaneçam visíveis e limitadas. As agregações do Elasticsearch são armazenadas densamente e indexadas por uma ID de grupo, mantendo o layout da memória compacto e rápido para iterações, além de possibilitar certas otimizações de desempenho ao permitir acesso aleatório.

Para chaves de bytes de comprimento variável, armazenamos em cache o hash completo junto com a ID do grupo. Isso evita o recálculo de códigos hash caros durante a sondagem e melhora a localidade do cache ao manter os metadados relacionados próximos uns dos outros. Durante o rehashing, podemos confiar no hash e bytes de controle em cache sem inspecionar os próprios valores, mantendo os custos de redimensionamento baixos.

Uma simplificação importante em nossa implementação é que as entradas nunca são excluídas. Isso elimina a necessidade de lápides (marcadores para identificar slots ocupados anteriormente) e permite que os slots vazios permaneçam realmente vazios, o que melhora ainda mais o comportamento da sondagem e mantém a eficiência das varreduras dos bytes de controle.

O resultado é um design que se encaixa naturalmente no modelo de execução do Elasticsearch, preservando as características de desempenho que tornam as Swiss Tables interessantes.

Qual é o desempenho?

Em pequenas cardinalidades, as Swiss Tables apresentam desempenho aproximadamente equivalente à implementação existente. Isso é esperado: quando as tabelas são pequenas, os efeitos de cache dominam menos e há pouca sondagem para otimizar.

À medida que a cardinalidade aumenta, o cenário logo muda.

O heatmap acima mostra fatores de melhoria de tempo para diferentes tamanhos de chave (8, 32, 64 e 128 bytes) entre cardinalidades de 1.000 a 10.000.000 de grupos. À medida que a cardinalidade aumenta, o fator de melhoria aumenta constantemente, chegando a 2 a 3 vezes para distribuições uniformes.

Essa tendência é exatamente o que o design prevê. Uma maior cardinalidade leva a cadeias de sondagem mais longas em tabelas hash tradicionais, enquanto a sondagem com a técnica Swiss Tables continua resolvendo a maioria das pesquisas em blocos de bytes de controle compatíveis com SIMD.

O comportamento do cache conta a história

Para entender melhor as acelerações, executamos os mesmos benchmarks JMH sob o Linux perf e capturamos cache e estatísticas do TLB.

Em comparação com a implementação original, a versão Swiss Tables realiza cerca de 60% menos referências de cache no geral. Os carregamentos de cache no último nível caem mais de 4 vezes, e as falhas de carregamento da LLC caem mais de 6 vezes. Como as falhas de LLC costumam se traduzir diretamente em acessos à memória principal, essa redução sozinha explica grande parte da melhoria de ponta a ponta.

Mais próximo da CPU, observamos menos falhas de cache de dados L1 e quase 6 vezes menos falhas de dados TLB, indicando uma localidade espacial mais precisa e padrões de acesso à memória mais previsíveis.

Esse é o benefício prático dos bytes de controle compatíveis com SIMD. Em vez de carregar repetidamente chaves e valores de locais de memória dispersos, a maioria das sondagens é resolvida analisando uma estrutura compacta residente no cache. Menos memória acessada significa menos falhas, e menos falhas significam consultas mais rápidas.

Conclusão

Ao adotar um design de tabela hash com a técnica Swiss Tables e apostar fortemente na sondagem compatível com SIMD, alcançamos uma aceleração de 2 a 3 vezes para cargas de trabalho de estatísticas ES|QL de alta cardinalidade, além de um desempenho mais estável e previsível.

Este trabalho destaca como estruturas de dados modernas conscientes da CPU podem desbloquear ganhos substanciais, mesmo para problemas já conhecidos, como tabelas hash. Há mais espaço para explorar aqui, como especializações adicionais de tipos primitivos e uso em outros caminhos de alta cardinalidade, como joins, todos eles apenas parte do esforço mais amplo e contínuo para modernizar continuamente os internos do Elasticsearch.

Se você tiver interesse nos detalhes ou quiser acompanhar o trabalho, confira o rastreamento de progresso de pull request e meta issue no Github.

Boa sorte com o hashing!

Recentemente, contribuímos para o projeto open source Google MCP Toolbox for Databases, adicionando suporte ao Elasticsearch como banco de dados.

Com esse novo recurso, agora você pode usar o Google MCP Toolbox para se conectar ao Elasticsearch e "conversar" diretamente com seus dados.

Elasticsearch

Precisamos ter uma instância do Elasticsearch em execução. Você pode ativar uma avaliação gratuita no Elastic Cloud ou instalá-lo localmente usando o script start-local:

Isso instalará o Elasticsearch e o Kibana no seu computador e gerará uma chave API para ser usada na configuração do Google MCP Toolbox.

A chave API será mostrada como saída do comando anterior e armazenada em um arquivo .env na pasta elastic-start-local.

Instale o conjunto de dados de exemplo

Após a instalação, você pode fazer login no Kibana usando o nome do usuário elastic e a senha gerada pelo script start-local (armazenada em um arquivo .env).

Você pode instalar o conjunto de dados de pedidos de comércio eletrônico disponível no Kibana. Inclui um único índice chamado kibana_sample_data_ecommerce contendo informações sobre 4.675 pedidos de um website de comércio eletrônico. Para cada pedido, temos as seguintes informações:

• Informações do cliente (nome, ID, data de nascimento, e-mail, etc.)

• Data do pedido

• ID do pedido

• Produtos (lista de todos os produtos com preço, quantidade, ID, categoria, desconto, etc.)

• SKU

• Preço total (sem impostos, com impostos)

• Quantidade total

• Informações geográficas (cidade, país, continente, localização, região)

Para instalar os dados de exemplo, abra a página Integrações no Kibana (busque por “Integração” na barra de busca superior) e instale os “Dados de Exemplo”. Confira os detalhes na documentação aqui: https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana.

O objetivo deste artigo é mostrar como é fácil configurar o Google MCP Toolbox para se conectar ao Elasticsearch e interagir com o índice kibana_sample_data_ecommerce usando linguagem natural.

Google MCP Toolbox

O Google MCP Toolbox é um servidor MCP open source projetado para facilitar a interação de aplicações e agentes de IA com bancos de dados de forma segura e eficiente. Antes chamado de "GenAI Toolbox for Databases", o projeto foi renomeado após adotar total compatibilidade com o Protocolo de Contexto de Modelo (MCP). Seu objetivo é eliminar o trabalho pesado tradicionalmente exigido ao conectar agentes a bancos de dados, lidando com agrupamento de conexões, autenticação, observabilidade e outras preocupações operacionais nos bastidores.

Essencialmente, o Toolbox permite que desenvolvedores definam ferramentas reutilizáveis e de alto nível que encapsulam interações com bancos de dados. Essas ferramentas podem então ser invocadas por qualquer cliente que cumpra o MCP — como um agente de IA — sem exigir que o cliente implemente consultas SQL de baixo nível ou gerencie conexões de banco de dados. Essa abordagem reduz drasticamente a quantidade de código padrão necessário para construir agentes conscientes de banco de dados, tornando possível integrar operações avançadas de dados em apenas algumas linhas de lógica de aplicação. Uma vez definida uma ferramenta, ela pode ser compartilhada entre vários agentes, frameworks ou linguagens (Figura 1).

Uma grande vantagem de usar o Toolbox é o modelo de segurança integrado. Fluxos de autenticação, como OAuth2 e OIDC, são aceitos de forma nativa, permitindo que os desenvolvedores evitem manipular ou armazenar credenciais confidenciais de bancos de dados em agentes. A plataforma também fornece recursos de observabilidade, incluindo métricas e rastreamento, no OpenTelemetry, que é essencial para depuração, monitoramento e implantações de produção. No geral, o MCP Toolbox serve como uma interface unificada, segura e extensível para interagir com seus dados de qualquer sistema habilitado pelo MCP.

Como instalar o MCP Toolbox

Você pode instalar o servidor MCP Toolbox no Linux usando o seguinte comando:

Para instalá-lo no macOS ou Windows, siga as instruções detalhadas aqui.

Configure o Toolbox para Elasticsearch

Para configurar o MCP Toolbox para Elasticsearch, precisamos criar um arquivo tools.yaml , conforme segue:

Você precisa trocar o valor <insert-here-api-key> por uma chave API válida do Elasticsearch. Se você estiver rodando o Elasticsearch localmente usando o start-local, pode encontrar a chave API no arquivo .env gerado pelo start-local, sob a variável ES_LOCAL_API_KEY . Se você estiver usando o Elastic Cloud, poderá gerar uma chave de API seguindo o procedimento descrito aqui.

As ferramentas anteriores contêm a seguinte consulta ES|QL para Elasticsearch:

Se você não conhece o ES|QL, é uma linguagem de consulta desenvolvida pela Elastic, semelhante ao SQL, que pode ser usada para buscar em um ou mais índices. Saiba mais sobre ES|QL na documentação oficial aqui.

A consulta acima busca todos os pedidos armazenados no índice kibana_sample_data_ecommerce que contêm o nome do cliente especificado, usando o parâmetro ?name (o ponto de interrogação indica um parâmetro).

O nome do cliente é definido na configuração YAML anterior usando a string de tipo e a descrição "O nome do cliente".

Essa ferramenta pode ser usada para responder a perguntas sobre os pedidos de um cliente - por exemplo: Quantos pedidos o cliente Foo fez em outubro de 2025?

As descrições das ferramentas e seus parâmetros são essenciais para extrair as informações relevantes da solicitação em linguagem natural do usuário. Essa extração é realizada usando o recurso de chamada de função de um modelo de linguagem grande (LLM). Na prática, um LLM pode determinar qual função (ferramenta) precisa ser executada para obter as informações necessárias, juntamente com os parâmetros apropriados para essa função.

Para saber mais sobre chamadas de função, sugerimos o artigo Chamadas de função do OpenAI com Elasticsearch, de Ashish Tiwari.

Execute o servidor Toolbox

Você pode executar o MCP Toolbox usando o arquivo tools.yaml anterior com o seguinte comando:

O parâmetro –ui executa uma aplicação web em http://127.0.0.1:5000/ui (Figura 2).

Você pode selecionar Ferramentas > customer-orders e inserir o nome do cliente no campo Nome do parâmetro (por exemplo, Gwen Sanders) e clicar no botão Executar. Você deve ver uma resposta JSON conforme a Figura 3.

A configuração está concluída, e o MCP Toolbox pode executar a ferramenta customer-orders para se comunicar com o Elasticsearch, rodando o ES|QL.

Usando o MCP Toolbox com Gemini CLI

Podemos usar qualquer cliente MCP para nos comunicar com o MCP Toolbox for Databases. Por exemplo, podemos usar o Gemini CLI, uma ferramenta de linha de comando, para usar o Gemini. Você pode instalar o Gemini CLI seguindo as instruções descritas aqui.

Gemini CLI oferece uma extensão pré-configurada para MCP Toolbox, disponível em gemini-cli-extensions/mcp-toolbox. Você pode instalar esta extensão executando o seguinte comando:

Após a instalação, você precisa ir para o diretório em que armazenou o arquivo de configuração tools.yaml do MCP Toolbox e executar a CLI do Gemini da seguinte forma (essa etapa é necessária para que a CLI do Gemini seja configurada automaticamente com o MCP Toolbox):

Você deve ver uma saída conforme a Figura 4.

Você pode verificar se a MCP Toolbox está conectada usando o seguinte comando:

Você deve ver a mcp_toolbox com as ferramentas de pedidos de clientes listadas (Figura 5).

Se o MCP Toolbox estiver conectado à interface de comando Gemini, agora podemos tentar fazer algumas perguntas, como: "Me dê os pedidos da cliente Gwen Sanders." A CLI Gemini então solicitará permissão para executar a ferramenta de pedidos do cliente ao servidor mcp_toolbox (veja a Figura 6).

Após a confirmação, a CLI Gemini executará a solicitação para a MCP Toolbox, recebendo uma resposta JSON como resultado e usando para formatar a resposta (Figura 7).

A resposta da Gemini CLI emitirá um relatório indicando que Gewn Sanders fez apenas um pedido de 2 produtos, totalizando 132 euros.

SDKs do MCP Toolbox

O Google MCP Toolbox também oferece um SDK para acessar todas as funcionalidades de um programa escrito em Go, Python e Javascript.

Por exemplo, o Python SDK está disponível no Github na seguinte página: https://github.com/googleapis/mcp-toolbox-sdk-python.

Precisamos criar um agente simples para conectar à MCP Toolbox. Precisamos instalar os seguintes pacotes:

E crie um novo projeto de agente usando o comando a seguir:

Isso criará um novo diretório chamado my_agent com um arquivo agent.py.

Atualize my_agent/agent.py com o seguinte conteúdo para conectar ao Toolbox:

Crie um arquivo .env com sua chave API do Google:

Por fim, podemos executar o agente e observar os resultados. Para executar o agente, você pode executar o seguinte comando:

Ou pode servi-lo por meio de uma interface web:

Em ambos os casos, você pode interagir com a MCP Toolbox usando uma interface de perguntas e respostas. Por exemplo, você pode fazer a pergunta anterior: Me dê os pedidos da cliente Gwen Sanders.

Para saber mais sobre os diferentes SDKs, consulte esta página de documentação.

Conclusão

Neste artigo, demonstramos a integração com o Elasticsearch para o Google MCP Toolbox for Databases. Usando um arquivo de configuração YAML simples, podemos definir um conjunto de ferramentas que traduzem perguntas de linguagem natural em consultas do Elasticsearch usando a linguagem ES|QL.

Mostramos como interagir com os conjuntos de dados kibana_sample_data_ecommerce, que contém pedidos de um website de e-commerce. Com esse arquivo de configuração, basta executar o servidor MCP Toolbox e conectar a ele a partir de qualquer cliente MCP.

Por fim, demonstramos como usar o Gemini CLI como cliente para conectar-se ao MCP Toolbox for Databases e consultar os dados de comércio eletrônico armazenados no Elasticsearch. Executamos uma consulta em linguagem natural para obter informações sobre pedidos de um cliente específico identificado pelo nome.

À medida que o ecossistema MCP continua crescendo, esse padrão — definições leves de ferramentas apoiadas por uma infraestrutura segura e pronta para produção — gera novas oportunidades para criar agentes cada vez mais capazes e com reconhecimento de dados com o mínimo esforço. Seja experimentando localmente com os conjuntos de dados de amostra da Elastic ou integrando capacidades de buscar em uma aplicação maior, o MCP Toolbox tem uma base confiável e extensível para interagir com os dados do Elasticsearch usando linguagem natural.

Para saber mais sobre o desenvolvimento de aplicações de IA agêntica, leia o artigo Criando fluxos de trabalho de IA agêntica com Elasticsearch, de Anish Mathur e Dana Juratoni.

Para saber mais informações sobre o Google MCP Toolbox, visite https://googleapis.github.io/genai-toolbox/getting-started/introduction/.

Aqui está uma visão dos recursos do Elasticsearch 9.2 que transformarão seus fluxos de trabalho de análise de dados com o ES|QL.

Revolucionando a correlação de dados: um Lookup Join mais inteligente, rápido e flexível

O comando LOOKUP JOIN no ES|QL passou por uma transformação significativa no Elasticsearch 9.2, tornando-se dramaticamente mais eficiente e versátil. O comando LOOKUP JOIN combina dados da sua tabela de resultados da consulta ES|QL com registros correspondentes de um índice de modo de consulta especificado. Ele adiciona campos do índice de pesquisa como novas colunas à sua tabela de resultados com base em valores correspondentes no campo de join. Anteriormente, a junção de dados estava limitada a um único campo e igualdade simples. Não mais! Essas melhorias capacitam você a lidar com cenários complexos de correlação de dados de forma fácil.

Os principais aprimoramentos do Lookup Join incluem:

• Joins de múltiplos campos: crie joins facilmente em múltiplos campos. Por exemplo, para unir application_logs com service_registry em service_name, environment e version:

• Liberando predicados de joins complexos com expressões (prévia técnica):

Você não está mais limitado à simples igualdade. O LOOKUP JOIN agora permite especificar múltiplos critérios para correlação e incorporar uma variedade de operadores binários, incluindo ==, !=, <, >, <=, e >=. Isso significa que você pode criar condições de join altamente nuançadas, permitindo que você faça perguntas muito mais sofisticadas sobre seus dados.

Exemplo 1: encontrando métricas de aplicação com limite de SLA por serviço

Exemplo 2: esta consulta calcula o valor devido com base em políticas regionais de precificação que mudam ao longo do tempo. Ele une três conjuntos de dados baseados em condições complexas de intervalo de datas e igualdade para calcular um due_amount final. A segunda busca usa o campo measurement_date do índice meter_readings e o campo region_id do índice customers para se juntar ao índice pricing_policies e encontrar a política de precificação correta para o region e measurement_date específicos.

• Ganhos massivos de desempenho para joins filtrados:

Melhoramos o desempenho para "joins expansivos" que são filtrados usando condições de tabela de consulta. Os joins expansivos produzem múltiplas correspondências por linha de entrada, o que pode criar grandes conjuntos intermediários de resultados. Isso piora quando muitas dessas linhas são descartadas por um filtro subsequente. Na versão 9.2, otimizamos esses joins filtrando linhas desnecessárias quando um filtro é aplicado aos dados de consulta, evitando processar linhas que seriam descartadas. Em alguns cenários, esses joins podem ser até 1000 vezes mais rápidos!

Essa otimização é crucial ao lidar com joins em expansão, onde uma pesquisa pode inicialmente gerar muitas correspondências potenciais. Ao aplicar filtros de forma inteligente, apenas os dados relevantes são processados, reduzindo drasticamente o tempo de execução da consulta e permitindo a análise em tempo real em grandes conjuntos de dados. Isso significa que você obtém seus insights muito mais rapidamente, mesmo com operações de join muito grandes ou complexas.

Compatibilidade do Lookup Join Cross-Cluster Search (CCS):

Quando o Lookup Join foi lançado como GA nas versões 8.19 e 9.1, ele não era compatível com Pesquisa entre clusters (CCS). Para organizações que operam em vários clusters, o LOOKUP JOIN agora se integra perfeitamente ao CCS na versão 9.2. Basta colocar seu índice de pesquisa em todos os clusters remotos onde você deseja realizar um join, e o ES|QL aproveitará automaticamente esses índices de pesquisa remota para unir seus dados remotos. Isso simplifica a análise distribuída de dados e garante um enriquecimento consistente em toda a sua implantação do Elasticsearch.

Essas melhorias significam que você pode correlacionar conjuntos de dados diversos com precisão, rapidez e facilidade sem precedentes, revelando insights mais profundos e acionáveis sem soluções complexas ou etapas de pré-processamento.

Enriqueça seus dados com facilidade: Kibana Discover UX para Lookup Indices

O enriquecimento de dados deve ser simples, não um obstáculo. Introduzimos uma experiência fantástica de usuário no Discover do Kibana para criar e gerenciar índices de lookup.

Fluxo de trabalho intuitivo: o preenchimento automático abrangente do Discover guiará você pelo processo, sugerindo índices de pesquisa e campos de união no editor ES|QL, tornando incrivelmente fácil conectar seus dados carregados aos índices existentes. Digite o nome de um índice de consulta que não exista e obtenha acesso direto ao editor de pesquisa com um clique para criar o índice. Digite o nome de um índice de consulta existente e sugeriremos uma opção para editá-lo:

Gestão em linha (CRUD): mantenha seus conjuntos de dados de referência atualizados com capacidades de edição em linha (Criar, Ler, Atualizar, Excluir) diretamente no Discover.

Upload de arquivos sem esforço: Agora você pode carregar arquivos diretamente, como CSVs, no Discover e usá-los instantaneamente nos seus LOOKUP JOIN. Chega de alternar entre diferentes áreas do Kibana!

Seja no mapeamento de IDs de usuário a nomes, adicionando metadados empresariais ou unindo arquivos de referência estáticos, este recurso democratiza o enriquecimento de dados, colocando a capacidade de melhorar com os joins diretamente nas mãos de cada usuário – rápido, simples e tudo em um só lugar.

Mantenha seu contexto: Apresentando INLINE STATS (prévia técnica)

Agregar dados é fundamental, mas às vezes você precisa ver os agregados junto com os dados originais. Temos o prazer de apresentar INLINE STATS como um recurso de visualização técnica.

Ao contrário do comando STATS, que substitui seus campos de entrada pela saída agregada, INLINE STATS preserva todos os campos de entrada originais e simplesmente adiciona os novos campos agregados. Isso permite que você execute outras operações nos campos de entrada originais após a agregação, proporcionando um fluxo de trabalho de análise mais contínuo e flexível.

Por exemplo, para calcular a distância média de voo mantendo as linhas individuais de voo:

Nessa consulta, avgDist é adicionado a cada linha com a Dest(inação) correspondente pela qual agrupamos e, como ainda temos as colunas de informações do voo, podemos filtrar os resultados para os voos com uma distância maior que a média.

Compatível com séries temporais no ES|QL (prévia técnica)

O Elasticsearch utiliza fluxos de dados de séries temporais para armazenar métricas. Estamos adicionando suporte para agregações de séries temporais no ES|QL, através do comando TS source. Isso está disponível no Elastic Cloud Serverless e na versão 9.2 básica como uma prévia técnica.

A análise de séries temporais é amplamente baseada em consultas de agregação que resumem os valores das métricas em buckets de tempo, divididos por uma ou mais dimensões de filtragem. A maioria das consultas de agregação depende do processamento em duas etapas, com (a) uma função de agregação interna resumindo valores por série temporal e (b) uma função de agregação externa, combinando os resultados de (a) em todas as séries temporais.

O comando TS source, combinado com STATS, fornece uma forma concisa, porém eficaz, de expressar tais consultas ao longo de séries temporais. Mais concretamente, considere o seguinte exemplo para calcular a taxa total de solicitações por host e por hora:

Nesse caso, a função de agregação de séries temporais RATE é avaliada primeiro por série temporal e hora. Os agregados parciais produzidos são então combinados usando SUM para calcular os valores agregados finais por hospedado e por hora.

Você pode conferir a lista de funções de agregação de séries temporais disponíveis aqui. A taxa de contador agora é compatível, provavelmente a função de agregação mais importante para processar contadores.

O comando TS source é projetado para ser combinado com STATS, com execução ajustada para ser compatível com agregações de séries temporais de forma eficiente. Por exemplo, os dados são ordenados antes de serem inseridos no STATS. Comandos de processamento que possam enriquecer ou alterar os dados de série temporal ou sua ordem, como FORK ou INLINE STATS, atualmente não são permitidos entre TS e STATS. Essa limitação pode ser eliminada no futuro.

A saída tabular STATS pode ser processada ainda com qualquer comando aplicável. Por exemplo, a consulta a seguir calcula a razão entre a média cpu_usage por host e hora para o valor máximo por host:

Os dados de série temporal são armazenados em nosso mecanismo de armazenamento colunar subjacente, que é alimentado pelos valores de documento do Lucene. O comando TS adiciona execução vetorizada de consultas através do mecanismo de computação ES|QL. O desempenho das consultas geralmente é melhorado em mais de uma ordem de magnitude, em comparação com consultas DSL equivalentes, e está em pé de igualdade com sistemas estabelecidos e específicos para métricas. No futuro, forneceremos uma análise detalhada de arquitetura e desempenho, então fique ligado.

Expandindo seu conjunto de ferramentas: novas funções ES|QL

Para aprimorar ainda mais a utilidade e a versatilidade do ES|QL, adicionamos um conjunto de novas funções:

Manipulação de string: CONTAINS, MV_CONTAINS, URL_ENCODE, URL_ENCODE_COMPONENT, URL_DECODE para processamento mais robusto de texto e URL.

Séries temporais e geoespaciais: TBUCKET para buckets flexíveis de tempo, TO_DENSE_VECTOR para operações vetoriais e um conjunto abrangente de funções geoespaciais como ST_GEOHASH, ST_GEOTILE, ST_GEOHEX, TO_GEOHASH, TO_GEOTILE, TO_GEOHEX para análise avançada baseada em localização.

Formatação de datas: DAY_NAME, MONTH_NAME para representações de data mais legíveis.

Essas funções oferecem um conjunto mais rico de ferramentas para manipular e analisar seus dados diretamente dentro do ES|QL.

Sob o capô: mais desempenho e eficiência

Além dos recursos destacados, o Elasticsearch 9.2 inclui diversas otimizações de desempenho em todo o ES|QL. Aceleramos RLIKE (LIST) com pushdown nos casos em que a função substitui várias consultas RLIKE semelhantes. Com RLIKE (LIST), podemos unir essas consultas em um único autômato e aplicar um autômato em vez de vários. Também temos carregamento mais rápido dos campos de palavras-chave com ordenação de índice e otimizações gerais de consultas – essas melhorias garantem que suas consultas ES|QL sejam executadas de forma mais eficiente do que nunca.

Comece hoje mesmo!

Elasticsearch 9.2 representa um salto significativo para o ES|QL, trazendo uma melhoria e flexibilidade sem precedentes para seus fluxos de trabalho de análise de dados. Incentivamos você a explorar esses novos recursos e experimentar a diferença que eles fazem.

Para uma lista abrangente de todas as mudanças e aprimoramentos no Elasticsearch 9.2, consulte as notas de lançamento oficiais. Boas consultas!

Neste blog, exploraremos a experiência do desenvolvedor com o Editor ES|QL no Elasticsearch 9.1, comparando-a com o PPL no Analisador de Eventos (PPL, na sigla em inglês) do OpenSearch 3.2.

As diferenças tornam-se rapidamente evidentes: o Editor ES|QL oferece preenchimento automático inteligente, ajuda contextual, consultas recomendadas e suporte a consultas entre clusters, capacitando não apenas usuários iniciantes, mas também usuários de nível especialista. O design cuidadoso para a criação de ES|QL também se reflete na inspeção integrada de consultas e na integração holística por meio de fluxos de trabalho do Kibana, por exemplo, com as Consultas Recentes.

Em contrapartida, o PPL carece de suporte comparável para autocompletar, orientação contextual e consultas distribuídas, criando uma curva de aprendizado mais acentuada e exigindo mais tentativas e erros.

Tornando o ES|QL mais fácil de aprender e usar.

Começar a usar uma nova linguagem de consulta pode muitas vezes parecer algo assustador. O editor ES|QL, integrado diretamente ao Kibana Discover, foi projetado para facilitar esse processo, oferecendo suporte não apenas à criação e depuração de consultas, mas também acelerando a sua familiarização e o seu domínio da linguagem. À medida que o editor ajuda a reduzir o atrito nas tarefas diárias, você pode mudar o foco da sintaxe e da tentativa e erro para a busca de soluções. Você pode ler mais sobre esses princípios e como os integramos ao editor aqui.

Essa experiência de edição não se limita ao Discover; trata-se de um módulo de código reutilizável que estamos trabalhando para integrar a outras partes do Kibana, como Dashboards, alertas do Kibana e mapas do Kibana.

Preenchimento automático inteligente: acelerando a criação de suas consultas.

O recurso de autocompletar do ES|QL Editor é abrangente, oferecendo sugestões de funções, argumentos, literais e até mesmo funções aninhadas compatíveis, uma funcionalidade notavelmente ausente no PPL. Na verdade, foi reconstruído do zero, conforme descrito aqui.

A validação é executada enquanto o usuário digita, conforme descrito aqui, e sugerirá campos, além de notificar o usuário sobre erros. Isso reduz a carga mental dos usuários e ajuda a prevenir erros logo no início do processo de criação de consultas.

Exemplo: Campos e funções compatíveis são sugeridos neste aninhamento:

Algo que a PPL não suporta:

Mesmo com o recurso de autocompletar inteligente guiando você pelas funções, argumentos e funções aninhadas compatíveis, você ainda pode querer uma compreensão mais profunda das opções disponíveis. É exatamente aí que a ajuda contextual do ES|QL Editor se torna indispensável, oferecendo assistência imediata dentro do próprio editor para esclarecer e aprimorar o desenvolvimento de suas consultas.

Ajuda contextual ao seu alcance

Informações adicionais sobre um comando gerado pelo recurso de autocompletar podem ser acessadas com um clique Ctrl+Espaço. Um painel aparece imediatamente com detalhes sobre a função, o argumento ou o campo em questão. Essa interação simplificada mantém os desenvolvedores focados, fornecendo orientação imediata sem obrigá-los a sair do editor ou a procurar documentação externa. Isso reduz o tempo gasto em pesquisas de sintaxe e ajuda a evitar erros comuns antes que eles ocorram.

Veja como funciona na prática:

O PPL não possui esse nível de orientação integrada, deixando os usuários dependentes de documentação externa ou do método de tentativa e erro. Essa ausência não é apenas uma característica faltante; ela evidencia uma disparidade mais ampla na filosofia de design. ES|QL prioriza uma experiência ponderada e contextualizada que se adapta aos dados e ao fluxo de trabalho do usuário. Essa diferença torna-se mais acentuada à medida que as consultas aumentam em complexidade, fazendo do ES|QL Editor um ambiente mais eficiente e confiável tanto para aprendizado quanto para uso em produção.

Consultas recomendadas que levam em consideração o contexto dos dados.

O Editor ES|QL fornece consultas recomendadas que são automaticamente adaptadas aos dados com os quais você está trabalhando, como registros. Em vez de apresentar um editor em branco, ele destaca os pontos de partida mais relevantes para casos de uso comuns. Selecionar uma Consulta Recomendada gera uma consulta canônica que pode ser usada imediatamente e refinada conforme necessário. Essa abordagem acelera o desenvolvimento de consultas, especialmente para novos usuários que ainda não conhecem toda a sintaxe.

Aqui está um exemplo em que um usuário seleciona a consulta “Detectar Ponto de Mudança”:

Compare isso com a experiência do PPL:

Em contrapartida, o PPL oferece apenas o preenchimento automático básico, deixando você responsável por montar consultas sem contexto ou estrutura. Essa falta de orientação pode levar à frustração e à tentativa e erro. Com as Consultas Recomendadas que levam em consideração os dados do Editor ES|QL, você pode evitar começar do zero ou memorizar a sintaxe para tarefas rotineiras. O editor reduz a carga cognitiva, ajuda a prevenir erros e permite que você se concentre na resolução de problemas e em objetivos mais amplos, como executar pesquisas entre clusters, em vez de se preocupar com a construção de consultas.

Consultas intuitivas entre clusters

O recurso de autocompletar do editor ES|QL continua sendo superior, mesmo ao trabalhar com vários clusters remotos com o CCS. Eis o motivo:

O editor ES|QL oferece preenchimento automático contínuo, mesmo em clusters diferentes.

O recurso de autocompletar no editor ES|QL suporta não apenas nomes de clusters, mas também índices locais e remotos. Conforme explicado aqui, isso funciona graças a uma arquitetura de nó coordenador, que ajuda a validar e gerar o plano de consulta a ser enviado aos nós locais, executar a consulta e agregar os resultados antes de enviá-los de volta ao usuário. Sem precisar digitar o nome completo do cluster remoto, digitar “:” inicia o processo de autocompletar para o índice remoto. E você não está limitado ao prefixo.

Isso facilita a descoberta e a consulta em conjuntos de dados distribuídos sem a necessidade de memorizar convenções de nomenclatura ou alternar entre contextos.

Aqui está um exemplo em que o usuário digita apenas “clu:g” para localizar um índice remoto:

Em nítido contraste, a PPL fornece apenas preenchimento básico para índices locais, com sugestões restritas a correspondências de prefixos. Os clusters remotos devem ser digitados manualmente, o que aumenta a probabilidade de erros e torna a criação de consultas mais lenta.

O PPL fornece preenchimento automático apenas para índices locais e as sugestões são restritas ao prefixo:

O ES|QL vai além, permitindo exclusões diretamente usando um sinal negativo, oferecendo controle preciso sobre quais clusters participam da sua exploração. Essa funcionalidade é particularmente valiosa ao trabalhar com ambientes híbridos, onde pode ser necessário incluir ou omitir conjuntos de dados específicos durante investigações entre clusters.

Essas melhorias refletem o foco mais amplo do Elasticsearch em reduzir o atrito na busca entre clusters. Ao facilitar a construção e o gerenciamento de consultas distribuídas, o ES|QL Editor permite que analistas e desenvolvedores se concentrem em insights em vez de sintaxe, enquanto o PPL deixa grande parte dessa responsabilidade para o usuário. Assim como o ES|QL Editor simplifica a criação de consultas entre clusters, ele também fornece ferramentas para inspecionar como essas consultas são executadas, garantindo transparência e monitoramento de desempenho em vários clusters.

Utilizando a ferramenta Inspection para analisar detalhes da pesquisa entre clusters.

A ferramenta Inspect, acessível a partir do Editor ES|QL, foi projetada para fornecer metadados com informações explícitas sobre a execução da consulta em todos os clusters. Essa funcionalidade está habilitada no Kibana Discover e pode ser acessada diretamente no inspetor de consultas, permitindo analisar o progresso e os detalhes da pesquisa, o que é particularmente crucial para a Pesquisa entre Clusters (CCS). Essa funcionalidade ajuda você a monitorar o progresso da pesquisa e a entender o desempenho das consultas em conjuntos de dados distribuídos.

Essa visibilidade detalhada da execução de consultas, especialmente para pesquisas distribuídas complexas, permite garantir o desempenho ideal e a resolução de problemas.

Além de compreender a mecânica das consultas individuais, o ES|QL Editor aprimora ainda mais a experiência do usuário, incorporando funcionalidades essenciais em toda a plataforma Kibana, promovendo um fluxo de trabalho contínuo e sem interrupções.

Experiência de consulta unificada com ES|QL e Kibana

Uma das fontes mais comuns de atrito na análise orientada por consultas é a troca de contexto. Muitas vezes você precisa relembrar perguntas que já escreveu. Cada interrupção quebra o foco e atrasa as investigações. O ES|QL Editor resolve isso integrando o histórico de consultas em todo o Kibana.

Consultas recentes

O recurso Consultas Recentes no Editor ES|QL ajuda você a manter o fluxo de trabalho, tornando o trabalho anterior instantaneamente acessível. No editor ES|QL do Discover, você pode visualizar, executar novamente e marcar com estrela suas últimas 20 consultas, garantindo que as consultas mais usadas ou complexas estejam a apenas um clique de distância. Essas consultas salvas também são transferidas para o Kibana, integrando-se a painéis, visualizações, alertas e mapas, para que você não precise sair da tela atual nem digitar os comandos novamente. Isso reduz o trabalho repetitivo, acelera as investigações e minimiza o risco de erros.

Por exemplo, um usuário pode utilizar as Consultas Recentes no Editor ES|QL do Discover (e marcá-las com uma estrela):

As consultas recentes estão integradas no painel de controle:

O PPL não oferece nenhuma funcionalidade comparável, obrigando os usuários a recorrerem à cópia e colagem manual ou a anotações externas para reutilizar consultas. A diferença vai além da conveniência; ela reflete a estratégia da Elastic de construir o ES|QL como uma linguagem verdadeiramente integrada ao ecossistema Kibana. Com recursos como Consultas Recentes, o ES|QL Editor não apenas simplifica os fluxos de trabalho diários, mas também estabelece as bases para funcionalidades mais avançadas, agora em versão prévia técnica, garantindo que a experiência continue a evoluir.

Conclusão

ES|QL é mais do que uma sintaxe; reflete a estratégia da Elastic para melhorar a forma como os usuários pesquisam, exploram e analisam dados. Com autocompletar inteligente, consultas recomendadas sensíveis ao contexto, orientações integradas ao editor e ferramentas como o Inspect, o ES|QL Editor acelera o aprendizado, reduz erros e simplifica fluxos de trabalho complexos, como a análise entre clusters. Integrado ao Kibana, ele conecta consultas perfeitamente a painéis, alertas e visualizações, garantindo um fluxo de trabalho ininterrupto.

Em resumo, ES|QL não é apenas mais uma linguagem de encaminhamento; é um mecanismo de consulta cuidadosamente projetado, aliado a uma interface de usuário intuitiva, que redefine fundamentalmente a forma como você interage com seus dados, oferecendo uma experiência integrada, inteligente e em constante evolução, que contrasta fortemente com a natureza frequentemente sequencial e menos guiada do OpenSearch PPL.

O que vem a seguir?

Este blog apenas aborda superficialmente o ES|QL. As próximas publicações aprofundarão as comparações com o OpenSearch PPL e explorarão recursos geoespaciais, de visualização e funcionalidades futuras do editor, como Controles (já disponíveis em Painéis), guias de exploração de múltiplos dados, pesquisa em segundo plano, histórico de consultas mais completo e FUSE.

Experimente o ES|QL hoje mesmo

Você pode experimentar o ES|QL em projetos Elasticsearch Serverless totalmente gerenciados com um período de avaliação gratuito. Também está disponível em versões a partir da 8.11, mas a melhor experiência é obtida nas versões 8.19 e 9.1.

Comece em minutos no seu ambiente local com um único comando:

ESQL:

Rubi:

Instalação

A gem pode ser instalada a partir do RubyGems com o seguinte comando:

Ou pode ser adicionado ao Gemfile de um projeto:

Uso

Você pode construir uma consulta completa de uma só vez ou criar um objeto de consulta com um comando de origem como from ou row e, em seguida, encadear métodos ES|QL para construí-lo.

A gem traduz o código para ES|QL no método to_s , portanto, retorna a consulta ES|QL quando é impressa ou convertida em uma String:

Você pode instanciar um objeto de consulta e modificar seu estado inicial usando os equivalentes ! de cada função:

A ferramenta fornece maneiras convenientes de encadear etapas extras a uma função ES|QL, como enrich e sort. Depois de chamar enrich em um objeto Elastic::ESQL , você pode encadear on e with a ele:

Você também pode encadear desc, asc, nulls_first e nulls_last à sua consulta após usar sort:

Também oferece suporte a strings personalizadas, caso você queira escrever a consulta ES|QL por conta própria ou usar um recurso que ainda não foi adicionado à biblioteca. custom irá unir as strings no final da consulta. Isso os adicionará conforme forem enviados para a função, sem adicionar nenhum caractere de barra vertical. Eles serão combinados ao restante da consulta por um caractere de espaço.

Você também pode encadear funções custom :

Utilizando o Construtor de Consultas ES|QL com o cliente Ruby

Você pode usar o construtor de consultas diretamente com elasticsearch-ruby e a API esql.query enviando o objeto de consulta:

Você também pode usá-lo com o auxiliar ES|QL do cliente Ruby do Elasticsearch. Saiba mais:

Como uma ferramenta independente

A gem foi projetada como uma ferramenta independente para construir consultas ES|QL de forma idiomática. Não possui dependências de tempo de execução; você pode usá-lo com o cliente oficial do Elasticsearch para Ruby ou de forma independente.

A consulta gerada pode ser usada com a API esql.query de qualquer forma que um aplicativo interaja com a API do Elasticsearch (Ruby ou não). Uma vez que uma consulta é construída com elastic-esql, a String gerada pode ser enviada para a API como o parâmetro query no corpo da solicitação.

Anteriormente, escrevi sobre como usar o Elasticsearch com ferramentas populares do Ruby. Esta gem pode ser usada com qualquer uma das ferramentas populares do Ruby para consultar o Elasticsearch com ES|QL.

Conclusão

Esta biblioteca está em desenvolvimento ativo e a API final ainda não foi concluída. Atualmente, está disponível em versão de pré-visualização técnica. Se você tiver algum comentário sobre a API atual ou sobre o uso em geral, não hesite em abrir uma nova solicitação. Consulte o arquivo README para saber mais sobre o construtor de consultas Ruby ES|QL.

Importando dados geoespaciais usando o Kibana

Os dados que usamos nos exemplos do blog anterior foram baseados em dados que usamos internamente para testes de integração. Para sua conveniência, incluímos aqui algumas informações em formato CSV que podem ser facilmente importadas usando o Kibana. Os dados são uma mistura de aeroportos, cidades e limites urbanos. Você pode baixar os dados de:

• aeroportos.csv

  • Este arquivo contém uma fusão de três conjuntos de dados:

    • Aeroportos (nomes, localizações e dados relacionados) do Natural Earth

    • Localização de cidades a partir do SimpleMaps

    • Altitudes de aeroportos do banco de dados global de aeroportos

• limites_cidade_aeroporto.csv

  • Esta seção contém uma fusão dos nomes de aeroportos e cidades mencionados acima com uma nova fonte:

    • Limites da cidade do OpenStreetMap

Como você pode imaginar, dedicamos algum tempo a combinar essas fontes de dados nos dois arquivos acima, com o objetivo de poder testar os recursos geoespaciais do ES|QL. Isso pode não ser exatamente o que você precisa em termos de dados, mas espero que lhe dê uma ideia do que é possível. Em particular, queremos demonstrar algumas coisas interessantes:

• Importação de dados com campos geoespaciais juntamente com outros dados indexáveis.

• Importar dados geo_point e geo_shape e usá-los em conjunto em consultas

• Importar dados para dois índices que podem ser unidos usando uma relação espacial.

• Criar um pipeline de ingestão para facilitar importações futuras (além do Kibana)

• Alguns exemplos de processadores de ingestão, como csv, convert e split

Embora neste blog abordemos o trabalho com dados CSV, é importante entender que existem várias maneiras de adicionar dados geográficos usando o Kibana. No aplicativo Mapa, você pode carregar dados delimitados, como CSV, GeoJSON e ESRI ShapeFiles, e também pode desenhar formas diretamente no mapa. Neste blog, vamos nos concentrar na importação de arquivos CSV da página inicial do Kibana.

Importando os aeroportos

O primeiro arquivo, airports.csv, Possui algumas peculiaridades interessantes com as quais precisamos lidar. Em primeiro lugar, as colunas possuem espaços em branco adicionais entre si, o que não é típico de arquivos CSV. Em segundo lugar, o campo type é um campo de múltiplos valores, que precisamos dividir em campos separados. Por fim, alguns campos não são strings e precisam ser convertidos para o tipo correto. Tudo isso pode ser feito usando o recurso de importação de CSV do Kibana.

Comece pela página inicial do Kibana. Existe uma seção chamada "Comece adicionando integrações", que possui um link chamado "Carregar um arquivo":

Clique neste link e você será redirecionado para a página "Enviar arquivo". Aqui você pode arrastar e soltar o arquivo airports.csv , e o Kibana analisará o arquivo e apresentará uma pré-visualização dos dados. Deveria ter detectado automaticamente o delimitador como uma vírgula e a primeira linha como a linha de cabeçalho. No entanto, provavelmente não removeu o espaço em branco extra entre as colunas, nem determinou os tipos dos campos, assumindo que todos os campos são text ou keyword. Precisamos resolver isso.

Clique em Override settings e marque a caixa de seleção para Should trim fields e Apply para fechar as configurações. Agora precisamos corrigir os tipos dos campos. Isso está disponível na próxima página, então clique em Import.

Primeiro escolha um nome de índice e, em seguida, selecione Advanced para acessar os mapeamentos de campo e a página do processador de ingestão.

Aqui precisamos fazer alterações tanto no mapeamento de campos do índice quanto no pipeline de ingestão para importar os dados. Em primeiro lugar, embora o Kibana provavelmente tenha detectado automaticamente o campo scalerank como long, ele erroneamente percebeu os campos location e city_location como keyword. Edite-os para geo_point, resultando em mapeamentos que se parecem com algo assim:

Você tem alguma flexibilidade aqui, mas observe que o tipo escolhido afetará a forma como o campo é indexado e os tipos de consultas possíveis. Por exemplo, se você deixar location como keyword não poderá realizar nenhuma consulta de pesquisa geoespacial nele. Da mesma forma, se você deixar elevation como text não poderá executar consultas de intervalo numérico nele.

Agora é hora de corrigir o pipeline de ingestão. Se o Kibana detectou automaticamente scalerank como long acima, ele também terá adicionado um processador para converter o campo em long. Precisamos adicionar um processador semelhante para o campo elevation , desta vez convertendo-o em double. Edite o pipeline para garantir que essa conversão esteja implementada. Antes de salvar isso, queremos mais uma conversão, para dividir o campo type em vários campos. Adicione um processador split ao pipeline, com a seguinte configuração:

O pipeline de ingestão final deve ter a seguinte aparência:

Observe que não adicionamos um processador de conversão para os campos location e city_location . Isso ocorre porque o tipo geo_point no mapeamento de campo já entende o formato WKT dos dados nesses campos. O tipo geo_point pode entender uma variedade de formatos, incluindo WKT, GeoJSON e outros. Se tivéssemos, por exemplo, duas colunas no arquivo CSV para latitude e longitude, precisaríamos adicionar um processador script ou set para combiná-las em um único campo geo_point (por exemplo, "set": {"field": "location", "value": "{{lat}},{{lon}}"}).

Agora estamos prontos para importar o arquivo. Clique em Import e os dados serão importados para o índice com os mapeamentos e o pipeline de ingestão que acabamos de definir. Caso ocorram erros na ingestão dos dados, o Kibana os reportará aqui, para que você possa editar os dados de origem ou o pipeline de ingestão e tentar novamente.

Observe que um novo pipeline de ingestão foi criado. Isso pode ser visualizado indo para a seção Stack Management do Kibana e selecionando Ingest pipelines. Aqui você pode ver o pipeline que acabamos de criar e editá-lo, se necessário. Na verdade, a seção Ingest pipelines pode ser usada para criar e testar pipelines de ingestão, um recurso muito útil se você planeja fazer ingestões ainda mais complexas.

Se você deseja explorar esses dados imediatamente, pule para as seções posteriores, mas se também deseja importar os limites da cidade, continue lendo.

Importando os limites da cidade

O arquivo de limites da cidade disponível em airport_city_boundaries.csv é um pouco mais simples de importar do que o exemplo anterior. Contém um campo city_boundary que é uma representação WKT do limite da cidade como um POLYGON e um campo city_location que é uma representação geo_point da localização da cidade. Podemos importar esses dados de forma semelhante aos dados dos aeroportos, mas com algumas diferenças:

• Precisávamos selecionar a configuração de substituição Has header row pois ela não foi detectada automaticamente.

• Não foi necessário remover espaços em branco dos campos, pois os dados já estavam livres de espaços desnecessários.

• Não foi necessário editar o pipeline de ingestão, pois todos os tipos eram de string ou espaciais.

• No entanto, tivemos que editar os mapeamentos de campo para definir o campo city_boundary como geo_shape e o campo city_location como . geo_point

Nossos mapeamentos de campo finais ficaram assim:

Assim como na importação airports.csv anterior, basta clicar em Import para importar os dados para o índice. Os dados serão importados com os mapeamentos que editamos e o pipeline de ingestão definido pelo Kibana.

Explorando dados geoespaciais com ferramentas de desenvolvimento

No Kibana, é comum explorar os dados indexados com a opção "Descobrir". No entanto, se sua intenção é escrever seu próprio aplicativo usando consultas ES|QL, pode ser mais interessante tentar acessar a API Elasticsearch diretamente. O Kibana possui um console prático para experimentar a escrita de consultas. Isso é chamado de console Dev Tools e pode ser encontrado na barra lateral do Kibana. Este console se comunica diretamente com o cluster Elasticsearch e pode ser usado para executar consultas, criar índices e muito mais.

Experimente o seguinte:

Isso deverá produzir os seguintes resultados:

distância

abreviar

nome

Local

país

cidade

elevação

273418.05776847183

PRESUNTO

Hamburgo

PONTO (10,005647830925 53,6320011640866)

Alemanha

Norderstedt

17.0

337534,653466062

TXL

Aeroporto Internacional de Berlim-Tegel

PONTO (13.2903090925074 52.5544287044101)

Alemanha

Hohen Neuendorf

38,0

483713.15032266214

OSL

Oslo Gardermoen

PONTO (11.0991032762581 60.1935783171386)

Noruega

Oslo

208,0

522538.03148094116

BMA

Broma

PONTO (17,9456175406145 59,3555902065112)

Suécia

Estocolmo

15.0

522538.03148094116

ARN

Arlanda

PONTO (17,9307299016916 59,6511203397372)

Suécia

Estocolmo

38,0

624274,8274399083

DUS

Aeroporto Internacional de Düsseldorf

PONTO (6,76494446612174 51,2781820420774)

Alemanha

Düsseldorf

45,0

633388,6966435644

PRG

Ruzyn

PONTO (14,2674849854076 50,1076511703671)

República Tcheca

Praga

381,0

635911.1873311149

AMS

Schiphol

PONTO (4,76437693232812 52,3089323889822)

Países Baixos

Hoofddorp

-3,0

670864.137958866

FRA

Frankfurt Internacional

PONTO (8,57182286907608 50,0506770895207)

Alemanha

Frankfurt

111.0

683239,2529970079

UAU

Okecie Int'l

PONTO (20,9727263383587 52,171026749259)

Polônia

Piaseczno

111.0

Visualizando dados geoespaciais com o Kibana Maps

O Kibana Maps é uma ferramenta poderosa para visualizar dados geoespaciais. Pode ser usado para criar mapas com múltiplas camadas, cada camada representando um conjunto de dados diferente. Os dados podem ser filtrados, agregados e formatados de diversas maneiras. Nesta seção, mostraremos como criar um mapa no Kibana Maps usando os dados que importamos na seção anterior.

No menu do Kibana, navegue até Analytics->Maps para abrir uma nova visualização do mapa. Clique em Add Layer e selecione Documents, escolhendo a visualização de dados airports e editando o estilo da camada para colorir os marcadores usando o campo elevation , para que possamos ver facilmente a altitude de cada aeroporto.

Clique em "Manter alterações" para salvar o mapa:

Agora adicione uma segunda camada, desta vez selecionando a visualização de dados airport_city_boundaries . Desta vez, usaremos o campo city_boundary para estilizar a camada e definiremos a cor de preenchimento para um azul claro. Isso mostrará os limites da cidade no mapa. Certifique-se de reordenar as camadas para garantir que os marcadores do aeroporto fiquem por cima.

Junções espaciais

ES|QL não suporta comandos JOIN , mas você pode realizar um caso especial de junção usando o comando ENRICH . Este comando funciona de forma semelhante a uma 'junção à esquerda' em SQL, permitindo enriquecer os resultados de um índice com dados de outro índice com base em uma relação espacial entre os dois conjuntos de dados.

Por exemplo, vamos enriquecer os resultados de uma tabela de aeroportos com informações adicionais sobre a cidade que eles atendem, encontrando o limite da cidade que contém a localização do aeroporto e, em seguida, realizar algumas análises estatísticas dos resultados:

Se você executar essa consulta sem primeiro preparar o índice de enriquecimento, receberá uma mensagem de erro como esta:

Isso ocorre porque, como mencionamos anteriormente, o ES|QL não suporta comandos JOIN verdadeiros. Um motivo importante para isso é que o Elasticsearch é um sistema distribuído, e as junções são operações custosas e difíceis de escalar. No entanto, o comando ENRICH pode ser bastante eficiente, porque utiliza índices enriquecidos especialmente preparados que são duplicados em todo o cluster, permitindo que junções locais sejam realizadas em cada nó.

Para melhor compreender isso, vamos nos concentrar no comando ENRICH na consulta acima:

Este comando instrui o Elasticsearch a enriquecer os resultados recuperados do índice airports e a realizar uma junção intersects entre o campo city_location do índice original e o campo city_boundary do índice airport_city_boundaries , que usamos em alguns exemplos anteriores. Mas algumas dessas informações não estão claramente visíveis nesta consulta. O que vemos é o nome de uma política de enriquecimento city_boundaries e a informação em falta está encapsulada na definição dessa política.

Aqui podemos ver que ele executará uma consulta geo_match (intersects é o padrão), o campo para comparar é city_boundary e os enrich_fields são os campos que queremos adicionar ao documento original. Um desses campos, o region foi na verdade usado como chave de agrupamento para o comando STATS , algo que não poderíamos ter feito sem essa capacidade de 'junção à esquerda'. Para obter mais informações sobre políticas de enriquecimento, consulte a documentação de enriquecimento.

Os índices e políticas de enriquecimento no Elasticsearch foram originalmente projetados para enriquecer dados no momento da indexação, usando dados de outro índice de enriquecimento já preparado. Em ES|QL, no entanto, o comando ENRICH funciona no momento da consulta e não requer o uso de pipelines de ingestão. Isso efetivamente o torna bastante semelhante a um SQL LEFT JOIN, exceto que você não pode unir quaisquer dois índices, apenas um índice normal à esquerda com um índice enriquecido especialmente preparado à direita.

Em ambos os casos, seja para pipelines de ingestão ou para uso no ES|QL, é necessário executar algumas etapas preparatórias para configurar o índice e a política de enriquecimento. Já importamos o índice airport_city_boundaries acima, mas este não é diretamente utilizável como um índice de enriquecimento no comando ENRICH . Primeiro, precisamos realizar duas etapas:

• Crie a política de enriquecimento descrita acima para definir o índice de origem, o campo no índice de origem a ser comparado e os campos a serem retornados após a correspondência.

• Execute esta política para criar o índice de enriquecimento. Isso criará um índice interno especial, lendo o índice de origem original para uma estrutura de dados mais eficiente, que será copiada em todo o cluster.

A política de enriquecimento pode ser criada usando o seguinte comando:

E a política pode ser executada usando o seguinte comando:

Observe que, se você alterar o conteúdo do índice airport_city_boundaries , precisará executar esta política novamente para ver as alterações refletidas no índice enriquecido. Agora, vamos executar a consulta ES|QL original novamente:

Isso retorna as 5 principais regiões com o maior número de aeroportos, juntamente com o centroide de todos os aeroportos que possuem regiões correspondentes e o intervalo de comprimento da representação WKT dos limites das cidades dentro dessas regiões:

centroide

Contagem

região

PONTO (-12.139086859300733 31.024386116624648)

126

nulo

PONTO (-83.10398317873478 42.300230911932886)

3

Detroit

PONTO (39,74537850357592 47,21613017376512)

3

городской округ Батайск

PONTO (-156,80986787192523 20,476673701778054)

3

Havaí

PONTO (-73,94515332765877 40,70366442203522)

3

Cidade de Nova York

PONTO (-83.10398317873478 42.300230911932886)

3

Detroit

PONTO (-76,66873019188643 24.306286952923983)

2

Nova Providência

PONTO (-3,0252167768776417 51,39245774131268)

2

Cardiff

PONTO (-115,40993484668434 32,73126147687435)

2

Município de Mexicali

PONTO (41,790108773857355 50,302146775648)

2

Área Central

PONTO (-73,88902732171118 45.57078813901171)

2

Montreal

Você também pode notar que a região mais comumente encontrada foi null. O que isso poderia implicar? Lembre-se de que comparei este comando a um 'left join' em SQL, o que significa que se nenhum limite de cidade correspondente for encontrado para um aeroporto, o aeroporto ainda será retornado, mas com valores null para os campos do índice airport_city_boundaries . Descobriu-se que havia 125 aeroportos que não encontraram nenhum city_boundary correspondente e um aeroporto com uma correspondência onde o campo region era null. Isso levou a uma contagem de 126 aeroportos sem nenhum region nos resultados. Se o seu caso de uso exigir que todos os aeroportos possam ser associados aos limites de uma cidade, isso exigirá a obtenção de dados adicionais para preencher as lacunas. Seria necessário determinar duas coisas:

• quais registros no índice airport_city_boundaries não possuem campos city_boundary

• quais registros no índice airports não correspondem usando o comando ENRICH (ou seja, não se cruzam)

Utilizando ES|QL para dados geoespaciais em mapas do Kibana

O Kibana adicionou suporte para Spatial ES|QL no aplicativo Maps. Isso significa que agora você pode usar o ES|QL para pesquisar dados geoespaciais no Elasticsearch e visualizar os resultados em um mapa.

Existe uma nova opção de camada no menu "Adicionar camadas", chamada "ES|QL". Assim como todos os recursos geoespaciais descritos até agora, este está em "prévia técnica". Selecionar esta opção permite adicionar uma camada ao mapa com base nos resultados de uma consulta ES|QL. Por exemplo, você poderia adicionar uma camada ao mapa que mostrasse todos os aeroportos do mundo.

Ou você poderia adicionar uma camada que mostre os polígonos do índice airport_city_boundaries , ou ainda melhor, que tal aquela consulta complexa ENRICH acima que gera estatísticas de quantos aeroportos existem em cada região?

O que vem a seguir?

O blog anterior sobre pesquisa geoespacial focou no uso de funções como ST_INTERSECTS para realizar pesquisas, disponíveis no Elasticsearch desde a versão 8.14. E este blog mostra como importar os dados que usamos nessas pesquisas. No entanto, o Elasticsearch 8.15 trouxe uma função particularmente interessante: ST_DISTANCE que pode ser usada para realizar pesquisas eficientes de distância espacial, e este será o tema do próximo blog!

O Elasticsearch 8.12 e 8.13 trouxeram suporte básico para tipos geoespaciais ao ES|QL. Isso foi significativamente aprimorado com a adição de recursos de busca geoespacial na versão 8.14. Mais importante ainda, esse suporte foi projetado para estar em estrita conformidade com o padrão Simple Feature Access do Open Geospatial Consortium (OGC), usado por outros bancos de dados espaciais como o PostGIS, tornando-o muito mais fácil de usar para especialistas em SIG familiarizados com esses padrões.

Neste blog, mostraremos como usar o ES|QL para realizar buscas geoespaciais e como ele se compara aos seus equivalentes em SQL e Query DSL. Também mostraremos como usar o ES|QL para realizar junções espaciais e como visualizar os resultados no Kibana Maps. Note que todos os recursos descritos aqui estão em "prévia técnica" e gostaríamos muito de receber seu feedback sobre como podemos melhorá-los.

Pesquisa de dados geoespaciais

Vamos começar com um exemplo de consulta:

Esta função realiza uma busca por quaisquer polígonos de limites urbanos que se intersectem com um polígono de busca retangular ao redor do Aeroporto Internacional de Sanya Phoenix (SYX).

Em um conjunto de dados de exemplo contendo aeroportos, cidades e limites urbanos, esta busca encontra o polígono de interseção e retorna os campos desejados do documento correspondente:

abreviar

aeroporto

região

cidade

localização da cidade

SYX

Sanya Phoenix Int'l

天涯区

Sanya

PONTO(109,5036 18,2533)

Isso foi fácil! Agora compare isso com a DSL de consulta clássica do Elasticsearch para a mesma consulta:

Ambas as consultas são razoavelmente claras em sua intenção, mas a consulta ES|QL se assemelha bastante ao SQL. A mesma consulta no PostGIS se parece com isto:

Relembre o exemplo em ES|QL. São muito parecidos, não é?

Constatamos que os usuários existentes da API Elasticsearch consideram o ES|QL muito mais fácil de usar. Agora, esperamos que os usuários atuais de SQL, especialmente os usuários de SQL Espacial, achem o ES|QL muito familiar ao que já estão acostumados a ver.

Por que não usar SQL?

E quanto ao Elasticsearch SQL? Já existe há algum tempo e possui algumas funcionalidades geoespaciais. No entanto, o Elasticsearch SQL foi escrito como um wrapper sobre a API de consulta original, o que significa que apenas as consultas que podiam ser transpiladas para a API original eram suportadas. ES|QL não possui essa limitação. Por ser uma pilha de tecnologias completamente nova, permite muitas otimizações que não eram possíveis em SQL. Nossos testes de desempenho mostram que o ES|QL é frequentemente mais rápido que a API de consulta, principalmente em operações de agregação!

Diferenças em relação ao SQL

Claramente, pelo exemplo anterior, o ES|QL é de certa forma semelhante ao SQL, mas existem algumas diferenças importantes. Por exemplo, ES|QL é uma linguagem de consulta encadeada, começando com um comando de origem como FROM e, em seguida, encadeando todos os comandos subsequentes com o caractere pipe |. Isso torna muito fácil entender como cada comando recebe uma tabela de dados e realiza alguma ação nessa tabela, como filtrar com WHERE, adicionar colunas com EVAL ou realizar agregações com STATS. Em vez de começar com SELECT para definir as colunas de saída finais, pode haver um ou mais comandos KEEP , com o último especificando os resultados de saída finais. Essa estrutura simplifica o raciocínio sobre a consulta.

Analisando o comando WHERE no exemplo acima, podemos ver que ele é bastante semelhante ao exemplo do PostGIS:

ES|QL

PostGIS

Além da diferença nos caracteres de aspas da string, a maior diferença está em como convertemos a string para um tipo espacial. No PostGIS, usamos o sufixo ::geometry , enquanto no ES|QL, usamos o sufixo ::geo_shape . Isso ocorre porque o ES|QL é executado dentro do Elasticsearch e o operador de conversão de tipo :: pode ser usado para converter uma string em qualquer um dos tipos ES|QL suportados, neste caso, um geo_shape. Além disso, os tipos geo_shape e geo_point no Elasticsearch implicam o sistema de coordenadas espaciais conhecido como WGS84, mais comumente referido usando o número SRID 4326. No PostGIS, isso precisa ser explícito, daí o uso do prefixo SRID=4326; na string WKT. Se esse prefixo for removido, o SRID será definido como 0, que é mais parecido com os tipos do Elasticsearch cartesian_point e cartesian_shape, que não estão vinculados a nenhum sistema de coordenadas específico.

Tanto o ES|QL quanto o PostGIS também fornecem sintaxe para funções de conversão de tipo:

ES|QL

PostGIS

Funções OGC

O Elasticsearch 8.14 introduz as seguintes quatro funções de pesquisa espacial OGC:

ES|QL

PostGIS

Descrição

ST_INTERSETOS

ST_Interseções

Retorna verdadeiro se duas geometrias se intersectam e falso caso contrário.

ST_DISJOINT

ST_Disjunto

Retorna verdadeiro se as duas geometrias não se intersectarem e falso caso contrário. O inverso de ST_INTERSETOS.

ST_CONTÉM

ST_Contém

Retorna verdadeiro se uma geometria contém outra, e falso caso contrário.

ST_DENTRO

ST_Dentro

Retorna verdadeiro se uma geometria estiver dentro de outra, e falso caso contrário. O inverso de ST_CONTAINS.

Essas funções se comportam de maneira semelhante às suas contrapartes no PostGIS e são usadas da mesma forma. Por exemplo, ST_INTERSECTS retorna verdadeiro se duas geometrias se intersectam e falso caso contrário. Se você seguir os links de documentação na tabela acima, poderá notar que todos os exemplos ES|QL estão dentro de uma cláusula WHERE após uma cláusula FROM , enquanto todos os exemplos PostGIS estão usando geometrias literais. Na verdade, ambas as plataformas suportam o uso das funções em qualquer parte da consulta onde façam sentido.

O primeiro exemplo na documentação do PostGIS para ST_INTERSECTS é:

O equivalente em ES|QL seria:

Observe que não especificamos o SRID no exemplo do PostGIS. Isso ocorre porque no PostGIS, ao usar o tipo geometry , todos os cálculos são feitos em um sistema de coordenadas planas e, portanto, se ambas as geometrias tiverem o mesmo SRID, não importa qual seja o SRID. No Elasticsearch, isso também é verdade para a maioria das funções, no entanto, existem exceções onde geo_shape e geo_point usam cálculos esféricos, como veremos no próximo blog sobre pesquisa de distância espacial.

Versatilidade ES|QL

Então, vimos exemplos acima de uso de funções espaciais em cláusulas WHERE e em comandos ROW . Em que outro lugar fariam sentido? Um local muito útil é no comando EVAL . Este comando permite avaliar uma expressão e retornar o resultado. Por exemplo, vamos determinar se os centroides de todos os aeroportos agrupados por seus nomes de país estão dentro de um limite que delimita o país:

Os resultados são os esperados: o centroide dos aeroportos do Reino Unido está dentro das fronteiras do Reino Unido, e não dentro das fronteiras da Islândia, e vice-versa.

centroide

Contagem

no Reino Unido

na Islândia

dentro do Reino Unido

dentro da Islândia

PONTO (-21,946634463965893 64.13187285885215)

1

falso

verdadeiro

falso

verdadeiro

PONTO (-2,597342072712148 54,33551226578214)

17

verdadeiro

falso

verdadeiro

falso

PONTO (0,04453958108176276 23,74658354606057)

873

falso

falso

falso

falso

Na verdade, essas funções podem ser usadas em qualquer parte da consulta onde sua assinatura faça sentido. Todas elas recebem dois argumentos, que podem ser um objeto espacial literal ou um campo de um tipo espacial, e todas retornam um valor booleano. Uma consideração importante é que o sistema de referência de coordenadas (SRC) das geometrias deve coincidir, caso contrário, será retornado um erro. Isso significa que você não pode misturar os tipos geo_shape e cartesian_shape na mesma chamada de função. Você pode, no entanto, misturar os tipos geo_point e geo_shape , já que o tipo geo_point é um caso especial do tipo geo_shape e ambos compartilham o mesmo sistema de referência de coordenadas. A documentação de cada uma das funções definidas acima lista as combinações de tipos suportadas.

Além disso, qualquer um dos argumentos pode ser um literal espacial ou um campo, em qualquer ordem. Você pode até especificar dois campos, dois literais, um campo e um literal, ou um literal e um campo. O único requisito é que os tipos sejam compatíveis. Por exemplo, esta consulta compara dois campos no mesmo índice:

A consulta basicamente pergunta se a localização da cidade está dentro dos limites da cidade, o que geralmente deve ser verdade, mas sempre há exceções:

cardinalidade

Contagem

na cidade

alguns

29

falso

muitos

740

verdadeiro

Uma questão muito mais interessante seria saber se a localização do aeroporto está dentro dos limites da cidade que ele serve. No entanto, a localização do aeroporto reside em um índice diferente daquele que contém os limites da cidade. Isso requer um método para consultar e correlacionar dados de forma eficaz a partir desses dois índices separados.

Junções espaciais

ES|QL não suporta comandos JOIN , mas você pode obter um caso especial de junção usando o comando ENRICH , que se comporta de forma semelhante a uma 'junção esquerda' em SQL. Este comando funciona de forma semelhante a uma 'junção à esquerda' em SQL, permitindo enriquecer os resultados de um índice com dados de outro índice com base em uma relação espacial entre os dois conjuntos de dados.

Por exemplo, vamos enriquecer os resultados de uma tabela de aeroportos com informações adicionais sobre a cidade que eles atendem, encontrando o limite da cidade que contém a localização do aeroporto e, em seguida, realizar algumas análises estatísticas dos resultados:

Isso retorna as 5 principais regiões com o maior número de aeroportos, juntamente com o centroide de todos os aeroportos que possuem regiões correspondentes e o intervalo de comprimento da representação WKT dos limites das cidades dentro dessas regiões:

centroide

Contagem

min_wkt

max_wkt

região

PONTO (-32,56093470960719 32,598117914802714)

90

207

207

nulo

PONTO (-73,94515332765877 40,70366442203522)

9

438

438

Cidade de Nova York

PONTO (-83.10398317873478 42.300230911932886)

9

473

473

Detroit

PONTO (-156.3020245861262 20,176383580081165)

5

307

803

Havaí

PONTO (-73,88902732171118 45.57078813901171)

4

837

837

Montreal

Então, o que realmente aconteceu aqui? Onde ocorreu o suposto JOIN ? O ponto crucial da questão reside no comando ENRICH :

Este comando instrui o Elasticsearch a enriquecer os resultados recuperados do índice airports e a realizar uma junção intersects entre o campo city_location do índice original e o campo city_boundary do índice airport_city_boundaries , que usamos em alguns exemplos anteriores. Mas algumas dessas informações não estão claramente visíveis nesta consulta. O que vemos é o nome de uma política de enriquecimento city_boundaries e a informação em falta está encapsulada na definição dessa política.

Aqui podemos ver que ele executará uma consulta geo_match (intersects é o padrão), o campo para comparar é city_boundary e os enrich_fields são os campos que queremos adicionar ao documento original. Um desses campos, o region foi na verdade usado como chave de agrupamento para o comando STATS , algo que não poderíamos ter feito sem essa capacidade de 'junção à esquerda'. Para obter mais informações sobre políticas de enriquecimento, consulte a documentação de enriquecimento. Ao ler esses documentos, você notará que eles descrevem o uso de índices de enriquecimento para enriquecer dados no momento da indexação, configurando pipelines de ingestão. Isso não é necessário para ES|QL, pois o comando ENRICH funciona no momento da consulta. Basta preparar o índice de enriquecimento com os dados necessários e a política de enriquecimento e, em seguida, usar o comando ENRICH em suas consultas ES|QL.

Você também pode notar que a região mais comumente encontrada foi null. O que isso poderia implicar? Lembre-se de que comparei este comando a um 'left join' em SQL, o que significa que se nenhum limite de cidade correspondente for encontrado para um aeroporto, o aeroporto ainda será retornado, mas com valores null para os campos do índice airport_city_boundaries . Descobriu-se que havia 89 aeroportos que não encontraram nenhum city_boundary correspondente e um aeroporto com uma correspondência onde o campo region era null. Isso levou a uma contagem de 90 aeroportos sem nenhum region nos resultados. Outro detalhe interessante é a necessidade do comando MV_EXPAND . Isso é necessário porque o comando ENRICH pode retornar vários resultados para cada linha de entrada e MV_EXPAND ajuda a separar esses resultados em várias linhas, uma para cada resultado. Isso também esclarece por que "Havaí" mostra resultados diferentes min_wkt e max_wkt : havia várias regiões com o mesmo nome, mas limites diferentes.

Mapas do Kibana

O Kibana adicionou suporte para Spatial ES|QL no aplicativo Maps. Isso significa que agora você pode usar o ES|QL para pesquisar dados geoespaciais no Elasticsearch e visualizar os resultados em um mapa.

Existe uma nova opção de camada no menu "Adicionar camadas", chamada "ES|QL". Assim como todos os recursos geoespaciais descritos até agora, este está em "prévia técnica". Selecionar esta opção permite adicionar uma camada ao mapa com base nos resultados de uma consulta ES|QL. Por exemplo, você poderia adicionar uma camada ao mapa que mostrasse todos os aeroportos do mundo.

Ou você poderia adicionar uma camada que mostre os polígonos do índice airport_city_boundaries , ou ainda melhor, que tal aquela consulta complexa ENRICH acima que gera estatísticas de quantos aeroportos existem em cada região?

O que vem a seguir?

Você deve ter notado que em dois dos exemplos acima incluímos mais uma função espacial ST_CENTROID_AGG. Esta é uma função de agregação usada no comando STATS e a primeira de muitas funcionalidades de análise espacial que planejamos adicionar ao ES|QL. Vamos publicar um artigo sobre isso quando tivermos mais informações para mostrar!

Antes disso, gostaríamos de falar mais sobre um recurso particularmente interessante no qual trabalhamos: a capacidade de realizar buscas por distância espacial, um dos recursos de busca espacial mais utilizados do Elasticsearch. Você consegue imaginar como seria a sintaxe para buscas por distância? Talvez semelhante a uma função OGC? Fique ligado(a) no próximo post desta série para descobrir!

Alerta de spoiler: o Elasticsearch 8.15 acaba de ser lançado e inclui pesquisa por distância espacial com ES|QL!

ES|QL

ES|QL é uma nova linguagem de consulta do Elasticsearch introduzida na versão 8.11.0. Neste momento, está disponível em versão de pré-visualização técnica. Ele oferece uma maneira poderosa de filtrar, transformar e analisar dados armazenados no Elasticsearch.

Ele utiliza "pipes" (|) para manipular e transformar dados passo a passo. Essa abordagem permite aos usuários compor uma série de operações, onde o resultado de uma operação se torna a entrada para a próxima, possibilitando transformações e análises de dados complexas.

Por exemplo, a seguinte consulta retorna os 3 primeiros documentos (linhas) do índice sample_data :

Caso de uso: recursos ES|QL no cliente PHP oficial

Para ilustrar os recursos do ES|QL desenvolvidos no cliente PHP oficial, armazenamos no Elasticsearch um arquivo CSV com 81.828 livros (54,4 MB) contendo as seguintes informações:

Extraímos esta lista do conjunto de dados público de avaliações de livros da Amazon.

Criamos um índice books com os seguintes mapeamentos do Elasticsearch:

O valor rating é a média das classificações das avaliações extraídas do arquivo Books_rating.csv de 2,9 GB.

Aqui você encontra o script PHP que usamos para importar todos os livros em massa para o Elasticsearch. A operação em lote levou 7 segundos e consumiu 28 MB de RAM usando o PHP 8.2.17. Com o mapeamento proposto, o tamanho do índice no Elasticsearch é de aproximadamente 62 MB.

Mapear resultados ES|QL para um objeto PHP ou classe personalizada

Podemos executar uma consulta ES|QL em PHP usando o endpoint esql()->query() . O resultado desta consulta é uma estrutura de dados em forma de tabela. Isso é expresso em JSON usando os campos columns e values . No campo columns temos a definição name e type .

Aqui está um exemplo de consulta ES|QL para recuperar os 10 melhores livros escritos por Stephen King, ordenados pela classificação das avaliações dos usuários:

O resultado JSON do Elasticsearch tem a seguinte aparência:

Neste exemplo, temos 6 propriedades (autor, descrição, editora, classificação, título, ano) relacionadas a um livro e 10 resultados, todos livros de Stephen King.

Uma lista de todos os tipos suportados em ES|QL é apresentada aqui.

O objeto de resposta $result pode ser acessado como uma matriz, uma string ou como um objeto (veja aqui para mais informações).

Utilizando a interface de objeto, podemos acessar os valores por meio de propriedades e índices. Por exemplo, $result->values[0][4] retorna o título (4) do primeiro livro (0) da lista, $result->values[1][3] retorna a pontuação de classificação (3) do segundo livro (1), etc. Lembre-se, o índice de um array em PHP começa em zero.

Essa interface pode ser suficiente para alguns casos de uso, mas na maioria das vezes preferimos obter um array de objetos como resultado.

Para mapear o resultado em uma matriz de objetos, podemos usar o novo recurso mapTo() do elasticsearch-php.

Essa função está disponível diretamente no objeto de resposta do Elasticsearch. Isso significa que você pode acessá-lo da seguinte forma:

Se você tiver uma classe Book personalizada, poderá mapear o resultado usando-a, da seguinte forma:

Se sua classe tiver outras propriedades além das incluídas no resultado ES|QL, isso também funcionará. A função mapTo() usará apenas as propriedades retornadas como colunas do resultado ES|QL.

Você pode baixar todos os exemplos relatados neste artigo aqui.