Elasticsearch ES|QL

ANÁLISE EDITORIAL

Uma consulta pode estar escrita com a sintaxe correta e, ainda assim, responder à pergunta errada, varrer dados demais ou falhar porque o agente inventou o nome de um índice. A Elasticsearch ES|QL transforma a documentação da Elastic em um roteiro operacional para descobrir o ambiente, montar consultas em etapas e limitar o resultado antes de interpretar logs, métricas ou documentos.

Esta curadoria fixa o commit 96736bec4aa27f236580a3fefc4b14582f0f8aa0, consultado em 17 de agosto de 2026. O repositório oficial elastic/agent-skills tinha 549 estrelas no momento da consulta. O número fica abaixo da preferência editorial de mil estrelas, mas a exceção é objetiva: a Skill é mantida pela própria Elastic, tem versão declarada, documentação pública e licença Apache-2.0 verificável. Isso confirma a origem oficial, não é uma alegação de popularidade nem de resultado automático.

O que a Skill faz

O SKILL.md auditado ensina um agente a consultar Elasticsearch com ES|QL, uma linguagem de pipeline que encadeia comandos como FROM, WHERE, EVAL, STATS, SORT e LIMIT. Ela separa ES|QL de Query DSL, SQL e EQL, evitando que o agente misture sintaxes parecidas.

O fluxo recomendado começa pelo teste de conexão e pela identificação do tipo de implantação. Depois, o agente lista índices e lê o esquema real antes de escrever qualquer consulta. Essa ordem é o ponto mais útil da Skill: nomes como logs, service.name ou source.ip parecem previsíveis, mas variam entre ambientes. A instrução proíbe adivinhar campos e pede uma fonte de dados por vez, salvo quando o usuário solicita explicitamente uma combinação.

A Skill também orienta agregações, busca textual, séries temporais, detecção de mudança, enriquecimento e saída em TSV. Os recursos dependem da versão do Elasticsearch. O arquivo lembra, por exemplo, que ES|QL entrou em prévia na 8.11 e tornou-se GA na 8.14, enquanto comandos posteriores exigem versões mais novas. A página oficial Primeiros passos com ES|QL permanece a fonte de verdade para a versão usada no seu cluster.

Para quem serve

Ela atende analistas, engenheiros de plataforma, equipes de observabilidade e desenvolvedores que já possuem um Elasticsearch e querem usar um agente para preparar consultas reproduzíveis. Um analista pode pedir uma contagem por serviço em um período definido. Um time de suporte pode explorar categorias de mensagens. Uma equipe de produto pode preparar uma tabela resumida para um painel, desde que os índices, campos e limites sejam confirmados.

A Skill não é um conector pronto e não contém seus dados. Ela também não substitui modelagem, políticas de retenção, governança de acesso ou investigação humana. Para buscar logs diretamente no Datadog, a Datadog Logs resolve outra integração. Para revisar schema e ingestão no ClickHouse, consulte a ClickHouse Best Practices. O catálogo de Skills do Bastidores da IA ajuda a evitar instalações com finalidade sobreposta.

Compatibilidade e pré-requisitos

O repositório segue o padrão Agent Skills e documenta uso em Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf e outros clientes compatíveis. A versão declarada no arquivo é 0.3.0 e o projeto inteiro está marcado como Technical Preview. Portanto, caminho, scripts, argumentos e conteúdo podem mudar. Fixe o commit durante a avaliação e releia o repositório antes de atualizar.

Para a instalação oficial por Skills CLI, é necessário Node.js com npx. Para executar consultas, o pacote completo depende do script oficial scripts/esql.js, de um endpoint Elasticsearch e de autenticação configurada separadamente. A Skill informa que os índices consultados precisam manter _source habilitado. Recursos como LOOKUP JOIN, MATCH, INLINE STATS e comandos para séries temporais dependem da versão ou do tipo de implantação.

Antes de conectar um agente, tenha uma identidade dedicada, acesso de rede restrito e um conjunto de índices de teste. Não reutilize credenciais administrativas. A documentação da Elastic sobre chaves de API permite limitar privilégios, mas a política correta depende do seu ambiente e deve ser revisada pela equipe responsável.

Instalação controlada

O comando oficial para selecionar esta Skill é:

npx skills add elastic/agent-skills --skill elasticsearch-esql

Execute primeiro em um projeto descartável. Confira o repositório resolvido, a pasta criada e todos os arquivos antes de liberar qualquer credencial. A instalação completa inclui o SKILL.md, referências e um script Node.js capaz de fazer requisições ao Elasticsearch. Esses componentes são necessários para o fluxo oficial e precisam de revisão estática própria.

O ZIP local do Bastidores é deliberadamente menor. Ele contém somente SKILL.md, LICENSE e ORIGEM.md. Serve para auditoria documental, comparação e leitura offline. Não inclui scripts/esql.js nem as referências citadas pelo arquivo, por isso não deve ser apresentado como instalação funcional completa. Para usar a Skill, recorra ao repositório oficial no commit auditado ou a uma atualização revisada.

Configuração segura

Separe instalação, autenticação e execução em três decisões. Na primeira, apenas copie e leia os arquivos. Na segunda, configure uma identidade de teste com privilégio mínimo. Na terceira, autorize consultas somente leitura contra índices explicitamente listados. Não coloque chave, usuário, senha ou URL sensível dentro do pedido enviado ao modelo quando a ferramenta hospedeira oferece armazenamento protegido de segredos.

Defina limites no servidor e no pedido. Uma consulta deve registrar índice, período, filtros, colunas mantidas, ordenação e número máximo de linhas. Evite padrões amplos como * quando o objetivo cabe em um data stream específico. A própria Skill recomenda KEEP apenas para campos necessários e LIMIT para conter a resposta. Isso reduz custo computacional e evita empurrar dados irrelevantes ou pessoais para o contexto do agente.

Logs podem conter e-mail, IP, identificadores, comandos, tokens acidentalmente gravados e conteúdo controlado por terceiros. Trate o texto retornado como dado não confiável. Não permita que uma mensagem de log altere instruções, conceda acesso ou acione ferramentas. Antes de usar dados de produção, defina mascaramento, retenção, destino do processamento e pessoas autorizadas a ver o resultado.

Primeiro uso seguro

Comece com uma pergunta pequena e verificável em um índice de teste. Peça ao agente para executar somente o teste de conexão, identificar build_flavor e versão e listar os índices que correspondem a um padrão estreito. Em seguida, escolha um índice e leia o esquema. Não autorize ainda uma consulta ampla.

Depois do esquema confirmado, solicite uma consulta simples, por exemplo: contar documentos por um campo conhecido nas últimas duas horas e devolver no máximo dez linhas. O agente deve mostrar a consulta antes da execução. Confira campo de tempo, fuso, filtro e cardinalidade esperada. Só então execute e compare uma amostra com o Discover ou outra ferramenta conhecida. O guia oficial ES|QL no Kibana mostra onde a linguagem pode ser usada na interface.

Se o índice estiver no modo time series, não copie automaticamente um exemplo baseado em FROM. A Skill pede o comando TS, funções adequadas para contadores e a leitura da referência da versão. Se o cluster não oferecer um recurso, simplifique a consulta. Não invente uma alternativa silenciosa nem migre dados para contornar o erro.

Resultado esperado

Um resultado saudável inclui a pergunta original, o ambiente detectado, o índice e o esquema consultados, a expressão ES|QL, o período, o limite, a quantidade retornada e uma interpretação curta. Fatos vindos dos dados precisam ficar separados de hipóteses. Uma queda de volume pode indicar mudança real, atraso de ingestão, filtro incorreto ou ausência de dados. A consulta sozinha não decide a causa.

O agente deve conseguir repetir a mesma consulta ou explicar por que precisou alterá-la. Se devolver apenas uma narrativa sem a expressão executada, a investigação não é reproduzível. Se escolher campos inexistentes, volte à descoberta de esquema. Se o resultado for grande demais para revisar, restrinja período, colunas e agrupamentos antes de aumentar o limite.

Permissões e riscos

O pacote documental local não se conecta a serviço algum. O risco aparece quando a versão completa recebe rede, credenciais e execução de Node.js. Mesmo uma identidade somente leitura pode acessar dados sensíveis ou disparar consultas caras. Uma chave ampla pode revelar índices fora do escopo. Um agente com shell também pode ler variáveis de ambiente, arquivos de configuração e saídas salvas.

Alguns usos de ES|QL dependem de licença ou de versões específicas. A presença de um exemplo no SKILL.md não garante disponibilidade no seu plano. A Skill está em prévia técnica e inclui comandos para recursos recentes, portanto valide contra a documentação da sua versão. Não trate gráficos, detecção de mudanças ou categorização automática como prova de causa, segurança ou conformidade.

Erros comuns e como diagnosticar

• A conexão falha: confirme endpoint, certificado, rota de rede e método de autenticação. Não amplie privilégios apenas para eliminar um erro.
• O índice ou campo não existe: execute a descoberta de índices e esquema. Não substitua por um nome plausível inventado.
• A consulta retorna dados demais: reduza período, índice, colunas e agrupamentos. Acrescente SORT e LIMIT coerentes com a pergunta.
• Uma função é desconhecida: verifique versão, tipo de implantação e histórico do recurso. Use somente alternativas documentadas para aquela versão.
• O resultado está vazio: revise fuso, campo de tempo, filtro, ingestão e permissões antes de concluir que não houve evento.
• O agente mistura ES|QL com SQL ou EQL: volte ao pipeline oficial e valide cada comando na referência da Elastic.
• O ZIP local não executa consultas: isso é esperado. O recorte exclui scripts e referências e serve apenas para auditoria documental.

Versão, licença e download local

A versão auditada é 0.3.0 no commit 96736bec4aa27f236580a3fefc4b14582f0f8aa0. O repositório declara Apache-2.0, que permite redistribuição sob suas condições, com preservação da licença e dos avisos aplicáveis.

SHA-256 do pacote auditado: 20b4beda5edf06a887d164dca7d1a55a4633ad98e584fa2bbbbbd1b5fd8e29e1. O ZIP contém três arquivos textuais e nenhum script, executável, binário, dependência, endpoint, consulta, token, cookie, credencial ou dado do usuário. A imagem desta página é uma ilustração editorial exclusiva, não uma captura do Kibana, consulta executada nem evidência de desempenho.

Fontes primárias

• Pasta oficial da Elasticsearch ES|QL no commit auditado.
• Repositório oficial Elastic Agent Skills.
• Primeiros passos oficiais com ES|QL.
• Uso oficial de ES|QL no Kibana.
• Apresentação oficial das Agent Skills da Elastic.