Enrico Zimuel - Elasticsearch Labs

Mastra와 Elasticsearch로 에이전틱 AI 애플리케이션을 구축하는 방법

Enrico Zimuel — Wed, 08 Apr 2026 00:00:00 GMT

이 글에서는 Mastra TypeScript 프레임워크를 사용해 Elasticsearch와 상호 작용하는 에이전틱 애플리케이션을 구축하는 방법을 자세히 살펴보겠습니다.

Elastic은 최근에 Elasticsearch를 벡터 데이터베이스로 지원하도록 추가하여 mastra-ai/mastra 오픈 소스 프로젝트에 기여했습니다. 이 새로운 기능을 통해 Mastra에서 Elasticsearch를 네이티브로 사용하여 임베딩을 저장할 수 있습니다. 벡터 기능 외에도 Elasticsearch는 컨텍스트 엔지니어링 요구 사항을 충족하기 위한 다양한 고급 기능을 제공합니다. (예: 하이브리드 검색 및 순위 재지정)

이 글에서는 Elasticsearch를 사용하여 Retrieval-Augmented Generation(RAG) 아키텍처를 구현하는 에이전트 생성 과정을 자세히 설명합니다. Elasticsearch에 저장된 SF 영화 데이터 코퍼스와 상호 작용하는 에이전틱 접근법을 사용하는 데모 프로젝트를 선보일 것입니다. 이 프로젝트는 elastic/mastra-elasticsearch-example에서 확인할 수 있습니다.

Mastra

Mastra는 에이전틱 AI 애플리케이션을 생성하기 위한 TypeScript 프레임워크입니다.

Mastra의 프로젝트 구조는 다음과 같습니다:

src/ ├── mastra/ │ ├── agents/ │ │ └── weather-agent.ts │ ├── tools/ │ │ └── weather-tool.ts │ ├── workflows/ │ │ └── weather-workflow.ts │ ├── scorers/ │ │ └── weather-scorer.ts │ └── index.ts ├── .env.example ├── package.json └── tsconfig.json

Mastra에서는 에이전트, 도구, 워크플로우 및 점수를 구축할 수 있습니다.

에이전트는 메시지를 입력으로 받아들이고 응답을 출력으로 생성하는 클래스입니다. 에이전트는 도구, 대형 언어 모델 (LLM), 메모리를 사용할 수 있습니다(그림 1).

에이전트의 도구를 사용하면 웹 API와 통신하거나 Elasticsearch 쿼리와 같은 내부 작업을 수행하는 등 '외부 세계'와 상호 작용할 수 있습니다. 메모리 구성 요소는 과거 입력과 출력을 포함하여 대화 기록을 저장하는 데 중요한 역할을 합니다. 이렇게 저장된 컨텍스트를 통해 에이전트는 과거 상호 작용을 활용하여 향후 질문에 대해 더 정보에 입각하고 정확도 높은 응답을 제공할 수 있습니다.

워크플로우를 사용하면 단일 에이전트의 추론에 의존하는 대신 명확하고 구조화된 단계를 통해 복잡한 작업 순서를 정의할 수 있습니다(그림 2). 이를 통해 작업을 어떻게 세분화하는지, 데이터가 작업 간에 어떻게 이동하는지, 그리고 언제 무엇이 실행되는지를 완벽하게 제어할 수 있습니다. 워크플로우는 기본적으로 내장된 실행 엔진을 사용하여 실행되거나 워크플로우 러너에 배포할 수 있습니다.

Mastra에서는 모델 등급, 규칙 기반 및 통계적 방법을 사용하여 에이전트 출력을 평가하는 자동화된 테스트인 점수를 정의할 수 있습니다. 채점기는 점수를 반환합니다. 이 점수는 출력물이 평가 기준을 얼마나 잘 충족하는지를 정량화한 수치 값(일반적으로 0에서 1 사이)입니다. 이러한 점수를 통해 성능을 객관적으로 추적하고, 다양한 접근 방식을 비교하며, AI 시스템에서 개선이 필요한 영역을 식별할 수 있습니다. 채점기는 자신만의 프롬프트와 점수 매기기 기능으로 사용자 지정할 수 있습니다.

Elasticsearch

데모 프로젝트를 실행하려면 Elasticsearch 인스턴스가 실행 중이어야 합니다. Elastic Cloud에서 무료 체험을 활성화하거나 start-local 스크립트를 사용해 로컬에 설치할 수 있습니다.

curl -fsSL https://elastic.co/start-local | sh

이렇게 하면 컴퓨터에 Elasticsearch와 Kibana가 설치되고 Mastra 통합 구성에 사용할 API 키가 생성됩니다.

API 키는 이전 명령어의 출력 결과로 표시되며, elastic-start-local 폴더 안에 있는 .env 파일에 저장됩니다.

데모 설치 및 구성

데모 프로젝트의 소스 코드가 포함된 elastic/mastra-elasticsearch-example 리포지토리를 생성했습니다. 리포지토리에 기재된 예제는 Elasticsearch에서 문서를 검색하기 위한 RAG 아키텍처를 구현하는 에이전트를 Mastra에서 생성하는 방법을 보여 줍니다.

Elastic은 데모를 위해 SF 영화에 대한 데이터 세트를 제공했습니다. Kaggle의 IMDb 데이터 세트에서 500개의 영화를 추출했습니다.

첫 번째 단계는 다음 명령어를 사용하여 npm으로 프로젝트의 의존성을 설치하는 것입니다.

npm install

그런 다음 설정 정보가 담길 .env 파일을 구성해야 합니다. 다음 명령을 사용하여 .env.example 파일에서 구조를 복사하여 이 파일을 생성할 수 있습니다.

cp .env.example .env

이제 누락된 정보를 추가하여 .env 파일을 편집할 수 있습니다.

OPENAI_API_KEY= ELASTICSEARCH_URL= ELASTICSEARCH_API_KEY= ELASTICSEARCH_INDEX_NAME=scifi-movies

Elasticsearch 인덱스의 이름은 scifi-movies입니다. 원한다면 env 변수 ELASTICSEARCH_INDEX_NAME을(를) 사용하여 변경할 수 있습니다.

OpenAI를 임베딩 서비스로 사용했으므로 OPENAI_API_KEY env 변수에 OpenAI용 API 키를 제공해야 합니다.

이 예시에서 사용된 임베딩 모델은 openai/text-embedding-3-small이며, 임베딩 차원은 1,536입니다.

최종 답변 생성을 위해 비용을 절감할 수 있는 openai/gpt-5-nano 모델을 사용했습니다.

RAG 아키텍처를 사용하면 답변의 근거를 찾는 무거운 작업을 검색 구성 요소(이 경우 Elasticsearch)가 처리하기 때문에, 상대적으로 성능이 낮고(따라서 저렴한) 최종 LLM 모델을 사용할 수 있습니다.

소형 LLM은 두 가지 주요 작업만 담당합니다.

쿼리 재구성/임베딩: 사용자의 자연어 질문을 의미론적 검색이 가능하도록 벡터 임베딩으로 변환합니다.
답변 합성: 정확도가 높고 검색된 컨텍스트 덩어리(문서/동영상)를 가져와서 제공된 프롬프트 지침에 따라 일관성 있고 사람이 읽을 수 있는 최종 답변으로 합성합니다.

RAG 프로세스는 답변에 필요한 정확한 사실적 컨텍스트를 제공하므로 최종 LLM은 거대하거나 매우 복잡할 필요가 없으며, 자체 매개변수 내에서 필요한 지식을 모두 보유할 필요도 없습니다.(이는 보통 크고 비싼 모델들이 맡는 잘하는 것입니다.) 본질적으로 모델은 자체가 거대한 지식 기반 역할을 하는 것이 아니라, Elasticsearch가 제공한 정보를 바탕으로 정교하게 요약하고 형식을 지정하는 역할을 수행하는 것입니다. 이렇게 하면 비용 및 지연 최적화에 gpt-5-nano 같은 모델을 사용할 수 있습니다.

.env 파일 설정을 마친 후, 다음 명령어를 사용하여 영화 데이터를 Elasticsearch으로 수집할 수 있습니다.

npx tsx src/utility/store.ts

다음과 같은 출력 내용이 나타나야 합니다.

SF 영화 인덱스의 매핑에는 다음 필드가 포함되어 있습니다.

임베딩, 1,536 차원의 dense_vector, 코사인 유사도.
설명, 영화에 대한 설명이 포함된 텍스트.
감독, 감독의 이름이 포함된 텍스트.
제목, 영화의 제목이 포함된 텍스트.

제목과 설명을 사용하여 임베딩을 생성했습니다. 제목과 설명은 별개의 필드이지만, 이 둘을 연결함으로써 생성된 임베딩 벡터가 영화의 고유한 정체성(제목)과 풍부한 서술적 컨텍스트(설명)을 모두 포착할 수 있게 됩니다. 결과적으로 더욱 정확하고 포괄적인 의미론적 검색이 가능해집니다. 이렇게 결합된 입력은 임베딩 모델에 유사도 매칭을 위한 문서 내용의 더 나은 단일 표현을 제공합니다.

데모를 실행하십시오

다음 명령어를 사용하여 데모를 실행할 수 있습니다.

npm run dev

이 명령어를 실행하면 Mastra Studio에 접속할 수 있는 웹 애플리케이션이 localhost:4111에서 시작됩니다(그림 3).

Mastra Studio는 에이전트를 구축하고 테스트할 수 있는 대화형 UI를 제공하며, Mastra 애플리케이션을 로컬 서비스로 활용할 수 있도록 REST API도 함께 지원합니다. 이를 통해 통합에 대한 걱정 없이 즉시 구축을 시작할 수 있습니다.

Elasticsearch Agent를 제공했으며, 이는 Elasticsearch를 사용하여 의미 검색을 실행하는 도구로 Mastra의 createVectorQueryTool을 사용합니다. 이 에이전트는 RAG 접근법을 사용하여 사용자 질문에 답하기 위한 관련 문서(즉, 영화)를 검색합니다.

이 에이전트는 다음 프롬프트를 사용합니다.

You are a helpful assistant that answers questions based on the provided context. Follow these steps for each response: 1. First, carefully analyze the retrieved context chunks and identify key information. 2. Break down your thinking process about how the retrieved information relates to the query. 3. Draw conclusions based only on the evidence in the retrieved context. 4. If the retrieved chunks don't contain enough information, explicitly state what's missing. Format your response as: THOUGHT PROCESS: - Step 1: [Initial analysis of retrieved chunks] - Step 2: [Reasoning based on chunks] FINAL ANSWER: [Your concise answer based on the retrieved context] Important: When asked to answer a question, please base your answer only on the context provided in the tool. If the context doesn't contain enough information to fully answer the question, please state that explicitly and stop it. Do not add more information than what is present in the retrieved chunks. Remember: Explain how you're using the retrieved information to reach your conclusions.

Mastra Studio > Agents 메뉴를 클릭하고 Elasticsearch Agent를 선택하면, 채팅 시스템을 통해 에이전트를 테스트할 수 있습니다. 예를 들어, 다음과 같은 질문으로 SF 영화에 관한 정보를 요청할 수 있습니다.

UFO에 관한 영화 또는 TV 시리즈 5편을 찾아 줘.

에이전트가 vectorQueryTool을 실행하는 것을 확인할 수 있습니다. 실행된 도구를 클릭하여 입력과 출력을 확인할 수 있습니다. 실행이 완료되면 LLM은 Elasticsearch의 SF 영화 인덱스에서 제공된 맥락을 바탕으로 질문에 답변을 제공합니다(그림 4).

Mastra는 내부적으로 다음 단계를 실행합니다.

벡터 변환: 사용자의 질문인 UFO에 관한 영화 또는 TV 시리즈 5편을 찾아 줘는 OpenAI의 openai/text-embedding-3-small 모델을 사용하여 벡터 임베딩으로 변환됩니다.
벡터 검색: 이 임베딩은 벡터 검색을 통해 Elasticsearch를 쿼리하는 데 사용됩니다.
결과 검색: Elasticsearch는 쿼리와 관련성이 높은(즉, 사용자의 쿼리 벡터와 가장 가까운 벡터를 가진) 10편의 영화를 반환합니다.
답변 생성: 검색된 영화와 원래 사용자 질문은 LLM, 구체적으로openai/gpt-5-nano에 전송됩니다. LLM은 이 정보를 처리하여 최종 답변을 생성하며, 이때 결과를 5개 보여달라는 사용자의 요청 사항이 정확히 반영되도록 합니다.

The Elasticsearch Agent

여기에서는 Elasticsearch Agent의 소스 코드를 기재했습니다.

import { Agent } from "@mastra/core/agent"; import { ElasticSearchVector } from '@mastra/elasticsearch'; import { createVectorQueryTool } from '@mastra/rag'; import { ModelRouterEmbeddingModel } from "@mastra/core/llm"; import { Memory } from "@mastra/memory"; const es_url = process.env.ELASTICSEARCH_URL; const es_apikey = process.env.ELASTICSEARCH_API_KEY; const es_index_name = process.env.ELASTICSEARCH_INDEX_NAME; const prompt = 'insert here the previous prompt'; const esVector = new ElasticSearchVector({ id: 'elasticsearch-vector', url: es_url, auth: { apiKey : es_apikey } }); const vectorQueryTool = createVectorQueryTool({ vectorStore: esVector, indexName: es_index_name, model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small") }); export const elasticsearchAgent = new Agent({ id: "elasticsearch-agent", name: "Elasticsearch Agent", instructions: prompt, model: 'openai/gpt-5-nano', tools: { vectorQueryTool }, memory: new Memory(), });

vectorQueryTool은 RAG 예시의 검색 부분을 구현하기 위해 호출되는 도구입니다. Elastic 측에서 Mastra에 기여한 ElasticSearchVector 구현을 사용합니다.

에이전트는 VectorQueryTool, 프롬프트, 메모리를 사용하는 에이전트 클래스의 객체입니다. 보시다시피, Elasticsearch를 에이전트에 연결하기 위해 필요한 코드는 매우 간결합니다.

결론

이 글에서는 Mastra 프레임워크와 Elasticsearch를 통합하여 정교한 에이전트형 AI 애플리케이션을 구축하는 과정이 얼마나 단순하고 강력한지 살펴보았습니다. 특히, Elasticsearch에 인덱싱된 SF 영화 데이터 코퍼스에 대해 의미 검색을 수행할 수 있는 RAG 에이전트를 만드는 방법을 자세히 살펴보았습니다.

핵심적인 특징은 Elastic이 Mastra 오픈소스 프로젝트에 직접 기여했다는 점이며, 이를 통해 Elasticsearch를 벡터 저장소로 사용하는 네이티브 지원이 가능해졌습니다. 이러한 통합은 Elasticsearch Agent 소스 코드에서 확인할 수 있듯이 진입 장벽을 크게 낮춥니다. ElasticSearchVector 및 createVectorQueryTool(을)를 사용하면, 최소한의 구성 코드 몇 줄로 Elasticsearch를 에이전트에 연결하기 위한 전체 설정이 완료됩니다.

Elasticsearch는 결과의 정확도를 향상하고자 여러 고급 기능을 제공합니다. 예를 들어, 하이브리드 검색은 어휘 검색과 벡터 검색을 결합하여 정확도를 크게 향상합니다. 또 다른 흥미로운 기능은 하이브리드 검색의 마지막 단계에 적용할 수 있는 최신 Jina 모델을 활용한 순위 재지정입니다. 이러한 기술에 대해 자세히 알아보려면 Elasticsearch Labs의 다음 글을 참조하세요.

Elasticsearch 하이브리드 검색, 발렌틴 크레타즈(Valentin Crettaz) 저
Jina 모델, 그 기능 및 Elasticsearch에서의 사용법에 대한 소개, 스콧 마르텐스(Scott Martens) 저

제공된 예시를 살펴보고 Mastra 및 Elasticsearch로 자신만의 데이터 기반 에이전트를 구축해 보시기 바랍니다. Mastra에 대한 더 자세한 정보는 여기에서 공식 문서를 통해 확인하실 수 있습니다.

Elasticsearch용 Gemini CLI 확장 프로그램(도구 및 기술 포함)

Walter Rafelsberger,Enrico Zimuel — Tue, 17 Mar 2026 00:00:00 GMT

Elasticsearch와 Elastic Agent Builder의 모든 기능을 AI 개발 워크플로우에 직접 통합할 수 있는 Google Gemini CLI용 Elastic 확장 기능을 출시합니다. 이 확장 프로그램은 Elasticsearch와 상호 작용하기 위한 최근 개발된 몇 가지 에이전트 스킬도 제공합니다.

확장 프로그램은 여기에서 오픈 소스 프로젝트로 제공됩니다.

Gemini CLI 소개 및 설치 방법

Gemini CLI는 Google의 Gemini 모델을 명령줄로 직접 가져오는 오픈 소스 AI 에이전트입니다. 개발자가 터미널을 통해 AI와 상호 작용하여 코드 생성, 파일 편집, 셸 명령 실행, 웹 정보 검색 등의 작업을 수행할 수 있습니다.

Gemini CLI는 일반적인 채팅 인터페이스와 달리 로컬 개발 환경과 통합되어 프로젝트 컨텍스트를 이해하고, 파일을 수정하고, 빌드나 테스트를 실행하고, 워크플로우를 터미널 내에서 직접 자동화할 수 있습니다. 이러한 특징 덕분에 개발자, 사이트 신뢰성 엔지니어(SRE)뿐만 아니라 명령줄 워크플로우를 벗어나지 않고 AI 기반 코딩 및 자동화를 원하는 엔지니어에게 유용합니다.

Gemini CLI는 여러 패키지 관리자를 사용하여 설치할 수 있습니다. 가장 일반적인 방법은 npm을 사용하는 것입니다:

npm install -g @google/gemini-cli

다른 설치 옵션을 알고 싶다면 공식 설치 페이지를 참조하세요.

설치 후, 다음 명령어로 CLI를 실행하세요.

gemini

그림 1과 같은 화면이 표시됩니다.

Elasticsearch를 구성합니다

Elasticsearch 인스턴스가 실행 중이어야 합니다. 모델 컨텍스트 프로토콜(MCP) 서버를 사용하려면 Kibana 9.3+ 버전이 설치되어 있어야 합니다. 아래 설명된 Elasticsearch 쿼리 언어(ES|QL) 스킬(esql)을 사용하려면 Kibana가 없어도 됩니다.

Elastic Cloud에서 무료 체험을 활성화하거나 start-local 스크립트를 사용해 로컬에 설치할 수 있습니다.

curl -fsSL https://elastic.co/start-local | sh

이 명령을 실행하면 컴퓨터에 Elasticsearch와 Kibana가 설치되고 Gemini CLI 설정에 사용할 API 키가 생성됩니다.

API 키는 이전 명령의 출력 결과로 표시되며 .env 파일로 elastic-start-local 폴더에 저장됩니다.

온프레미스 Elasticsearch를 사용 중인 경우(예: start-local 사용), Elastic Agent Builder를 MCP와 함께 사용하려면 대규모 언어 모델(LLM)을 연결해야 합니다. 이 문서 페이지를 읽으면 다양한 옵션을 파악할 수 있습니다.

Elastic Cloud(또는 서버리스)를 사용하는 경우 이미 사전 구축된 LLM 연결이 제공됩니다.

Elasticsearch 확장 프로그램 설치

Elasticsearch 확장 프로그램을 Gemini CLI에 설치하려면 다음 명령어를 사용하세요.

gemini extensions install https://github.com/elastic/gemini-cli-elasticsearch

Gemini를 열고 다음 명령어를 실행하면 확장 프로그램이 성공적으로 설치되었는지 확인할 수 있습니다.

/extensions list

Elasticsearch 확장 프로그램을 사용할 수 있는지 확인할 수 있습니다.

MCP 통합을 사용하려면 Elasticsearch 9.3 이상 버전이 설치되어 있어야 합니다. Kibana에서 가져온 MCP 서버 URL이 필요합니다.

에이전트에서 MCP 서버 URL 가져오기 > 모든 도구 보기 > MCP 관리 > MCP 서버 URL 복사
표시되는 URL: https://your-kibana-instance/api/agent_builder/mcp

Elasticsearch 엔드포인트 URL이 필요합니다. 일반적으로 이것은 Kibana Elasticsearch 페이지 상단에 보고됩니다. start-local로 Elasticsearch를 실행 중인 경우, start-local .env 파일의 ES_LOCAL_URL 키에 이미 엔드포인트가 있습니다.

API 키도 필요합니다. Elasticsearch를 start-local로 실행 중인 경우, 이미 ES_LOCAL_API_KEY가 start-local.env 파일에 있습니다. 그렇지 않은 경우, 여기에 설명된 대로 Kibana 인터페이스를 사용하여 API 키를 생성할 수 있습니다.

Kibana: Stack Management > Security > API 키 > API 키 생성
API 키에 대해 읽기 권한만 설정하여 여기에 보고된 대로 feature_agentBuilder.read 권한을 활성화할 것을 권장합니다.
인코딩된 API 키 값을 복사합니다.

셸에서 필요한 환경 변수를 설정하세요.

export ELASTIC_URL="your-elasticsearch-url" export ELASTIC_MCP_URL="your-elasticsearch-mcp-url" export ELASTIC_API_KEY="your-encoded-api-key"

예제 데이터 세트 설치하기

Kibana에서 제공되는 eCommerce orders 데이터 세트를 설치할 수 있습니다. 이 데이터 세트에는 kibana_sample_data_ecommerce라는 단일 인덱스가 포함되어 있으며 전자상거래 웹사이트의 4,675개 주문 정보를 담고 있습니다. 각 주문에는 다음과 같은 정보가 포함되어 있습니다.

고객 정보(이름, ID, 생년월일, 이메일 등)
주문 날짜
주문 ID
제품(가격, 수량, ID, 카테고리, 할인, 기타 정보를 포함한 전체 제품 목록)
SKU.
총액(세전, 세후)
총 수량
지리 정보(도시, 국가, 대륙, 위치, 지역).

샘플 데이터를 설치하려면 Kibana의 통합 페이지를 열고(상단 검색창에서 '통합'을 검색) "Sample Data"를 설치하세요. 자세한 내용은 여기 설명서를 확인하세요.

이 글의 목표는 Gemini CLI를 설정해 Elasticsearch에 연결하고 kibana_sample_data_ecommerce 인덱스와 손쉽게 상호작용하는 방법을 보여주는 것입니다.

Elasticsearch MCP를 사용하는 방법

Gemini에서 다음 명령을 사용하여 연결을 확인할 수 있습니다:

/mcp list

그림 2와 같이 elastic-agent-builder가 활성화된 것을 확인할 수 있습니다.

Elasticsearch는 기본 도구 세트를 제공합니다. 여기에서 설명을 참조하세요.

이 도구로 Elasticsearch와 상호 작용하며 다음과 같은 질문을 할 수 있습니다.

Give me the list of all the indexes available in Elasticsearch.
How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

질문에 따라 Gemini는 하나 이상의 도구를 사용하여 답변을 시도합니다.

/elastic 명령어

Gemini CLI의 Elasticsearch 확장 프로그램에서/elastic 명령어를 추가했습니다.

/help 명령을 실행하면 사용 가능한 모든 /elastic 옵션이 표시됩니다(그림 3).

이 명령어들은 elastic-agent-builder MCP 서버의 특정 도구를 직접 실행하고자 할 때 유용할 수 있습니다. 예를 들어 다음 명령어를 사용하면 kibana_sample_data_ecommerce의 매핑을 얻을 수 있습니다.

/elastic:get-mapping kibana_sample_data_ecommerce

이러한 명령은 Gemini 모델에 의존하여 실행할 도구를 결정하는 대신, 특정 도구를 실행하는 바로가기 역할을 합니다.

Elasticsearch 스킬 사용 방법

이 확장 기능에는 ES|QL용 에이전트 기술과 Elasticsearch에서 사용할 수 있는 Elasticsearch 쿼리 언어가 함께 제공됩니다. Agent Skills는 Gemini CLI와 같은 AI 코딩 에이전트에 특정 작업에 대한 사용자 지정 지침을 제공하는 개방형 형식입니다. 점진적 공개라는 개념을 사용하여 초기 시스템 프롬프트에 스킬에 대한 간략한 설명만 추가합니다. 에이전트에게 Elasticsearch 쿼리와 같은 작업을 수행하도록 요청하면 에이전트는 해당 요청을 관련 스킬과 연결하고 자세한 지침을 동적으로 불러옵니다. 이는 토큰 예산을 관리하면서 AI에 필요한 컨텍스트를 정확하게 제공하는 효율적인 방법입니다.

esql 스킬은 Gemini CLI가 클러스터에 직접 ES|QL 쿼리를 작성하고 실행할 수 있도록 설계되었습니다. ES|QL은 데이터 탐색, 로그 분석 및 집계를 매우 직관적으로 수행할 수 있는 강력한 파이프 쿼리 언어입니다. 이 스킬을 활성화하면 ES|QL 구문을 찾아볼 필요가 없습니다. Gemini CLI에 데이터에 대한 자연어 질문을 입력하기만 하면, 에이전트가 나머지 작업을 처리합니다.

실행은 터미널에서 실행되는 간단한 curl 명령어를 사용하여 수행됩니다. 이것이 가능한 것은 Elasticsearch가 어떤 아키텍처에도 쉽게 통합할 수 있는 풍부한 REST API 세트를 제공하기 때문입니다.

esql 스킬 제공 내용:

인덱스 및 스키마 검색: 에이전트가 스킬의 기본 제공 도구를 사용하여 사용 가능한 인덱스를 나열하고 필드 매핑을 가져올 수 있습니다. 예를 들어 전자상거래 데이터세트에 대한 쿼리를 작성하기 전에 에이전트가 kibana_sample_data_ecommerce 스키마 검사를 실행해서 사용 가능한 필드(예: taxful_total_price 또는 category)를 파악할 수 있습니다.
원활한 자연어 번역: 이 스킬은 에이전트에 단순한 참조 매뉴얼을 넘어 사용자 의도를 해석할 수 있는 구체적인 가이드를 제공합니다. '서비스별 평균 응답 시간 표시'와 같은 자연어 요청을 입력하면 에이전트가 스킬에 내장된 패턴 매칭 기능을 사용하여 사용자가 입력한 내용을 올바른 ES|QL 집계, 필터 및 명령으로 즉시 변환합니다.
자체 수정: 만일 타입 불일치 또는 구문 오류로 인해 쿼리가 실패하면, 스킬은 생성된 쿼리와 정확한 Elasticsearch 오류 메시지를 반환하여 에이전트가 즉시 쿼리를 수정하고 사용자가 개입하지 않아도 다시 시도할 수 있게 됩니다.

esql 스킬은 elastic-agent-builder MCP 서버에서도 도구로 제공되므로 이 서버를 잠시 비활성화해야 합니다. 다음 명령어를 사용하여 비활성화할 수 있습니다.

/mcp disable elastic-agent-builder

그런 다음 Gemini CLI에 다음과 같은 프롬프트를 입력하기만 하면 됩니다.

Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index

에이전트가 수행하는 작업:

esql 스킬의 필요성을 인식해야 합니다.
kibana_sample_data_ecommerce 스키마를 확인하세요.
FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5 등 ES|QL 쿼리를 구성합니다.
Elasticsearch API에 대해 쿼리 작업을 실행하세요.
터미널에서 바로 최종 답을 제시합니다.

여기서는 이전 프롬프트에 대한 Gemini의 응답 사례를 보고했습니다.

─────────────────────────────────────────────────────────── > Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index ─────────────────────────────────────────────────────────── ✓ Activate Skill "esql": Interact with Elasticsearch using ES|QL and curl. Use when querying, managing indices, … Skill esql activated. Resources loaded from /home/user/.gemini/extensions/elasticsearch/skills/esql: Showing up to 200 items (files + folders). /home/user/.gemini/extensions/elasticsearch/skills/esql/ ├───SKILL.md └───references/ ├───esql-reference.md ├───generation-tips.md └───query-patterns.md ✦ I will start by exploring the mapping of the kibana_sample_data_ecommerce index to identify the fields for product category and sales revenue. Then, I will construct and execute an ES|QL query to determine the top 5 product categories by total sales revenue. ✓ Shell curl -s "${ELASTIC_URL%/}/kibana_sample_data_ecommerce/_mapping" -H "Authorization: ApiKey $(printenv ELAS… { "kibana_sample_data_ecommerce": { "mappings": { "properties": { "category": { "type": "text", "fields": { "keyword": { "type": "keyword" } } }, "currency": { "type": "keyword" }, ✦ Okay, I have the mapping. The category is products.category.keyword and sales revenue is taxful_total_price. I'll now execute the ES|QL query to get the top 5 categories by revenue. ✓ Shell curl -s -X POST "${ELASTIC_URL%/}/_query" \ -H "Authorization: ApiKey $(printenv ELASTIC_API_KEY)" \ -H … { "took": 62, "is_partial": false, "completion_time_in_millis": 1772805644164, "documents_found": 4675, "values_loaded": 12084, "start_time_in_millis": 1772805644102, "expiration_time_in_millis": 1773237644087, "columns": [ { "name": "total_revenue", "type": "double" }, { "name": "products.category.keyword", ✦ The query for top 5 product categories by revenue was successful. I'll format the returned JSON values into a user-friendly list. ✓ Shell Top 5 product categories by total sales revenue: 1. Men's Clothing: 149393.91 2. Women's Clothing: 135099.91 3. Women's Shoes: 105479.17 4. Men's Shoes: 91797.92 5. Women's Accessories: 60830.31 ✦ I've found the answer; now I'll format it for clarity. ✓ Shell Here are the top 5 product categories by total sales revenue: | Rank | Category | Total Revenue | |------|-----------------------|---------------| | 1 | Men's Clothing | 149,393.91 | | 2 | Women's Clothing | 135,099.91 | | 3 | Women's Shoes | 105,479.17 | | 4 | Men's Shoes | 91,797.92 | | 5 | Women's Accessories | 60,830.31 | ✦ I've formatted and presented the answer. I'm finished. ───────────────────────────────────────────────────────────

Gemini 모델이 최종 응답을 도출하는 모든 단계를 보여주는 방식은 흥미로운 부분입니다. 여기에서 모델의 추론 과정에 대한 스킬의 영향력을 확실하게 확인할 수 있습니다. 모델이 스킬을 사용하거나 셸 명령을 실행해야 한다고 처음 인식할 때, 휴먼 인 더 루프 방식을 사용하여 권한을 요청합니다.

esql 스킬은 스키마 발견, 쿼리 생성 및 실행과 같은 복잡한 작업을 처리함으로써 답을 얻는 과정의 메커니즘이 아닌 답 자체에만 집중할 수 있도록 도와줍니다. 필요한 데이터를 제대로 된 형식으로 터미널에서 바로 얻을 수 있습니다. 단 한 줄의 구문도 작성하거나 다른 애플리케이션으로 컨텍스트를 전환할 필요도 없습니다.

결론

이 글에서는 최근에 출시한 Gemini CLI용 Elasticsearch 확장 기능을 소개했습니다. 이 확장 프로그램을 사용하면 Gemini와 Elastic Agent Builder에서 제공하는 Elasticsearch MCP 서버(버전 9.3.0부터 사용 가능)를 이용하여 Elasticsearch 인스턴스와 상호 작용할 수 있습니다. /elastic 명령어도 사용할 수 있습니다.

더불어, 이 확장에는 사용자의 요청을 자연어에서 ES|QL 쿼리로 변환하는 esql 스킬도 포함되어 있습니다. 이 기술은 MCP 서버를 사용할 수 없는 경우 특히 유용합니다. 기본 통신이 터미널에서 실행되는 간단한 curl 명령에 의해 이루어지기 때문입니다. Elasticsearch는 어떤 프로젝트에도 쉽게 통합될 수 있는 풍부한 REST API 세트를 제공합니다. 이는 에이전틱 AI 애플리케이션을 개발할 때 특히 유용합니다.

Gemini CLI 확장 기능에 대한 자세한 내용은 여기 프로젝트 리포지토리에서 확인하세요.

Google MCP Toolbox for Databases, 새롭게 추가된 Elasticsearch 지원

Enrico Zimuel,Laurent Saint-Félix — Fri, 12 Dec 2025 00:00:00 GMT

이 글에서는 Elasticsearch와 Google MCP Toolbox를 함께 사용해 Elasticsearch 인덱스에서 정보를 추출하는 간단한 도구를 만드는 방법을 단계별로 살펴봅니다.

최근 Elastic은 Google MCP Toolbox for Databases 오픈소스 프로젝트에 Elasticsearch를 데이터베이스로 사용할 수 있는 지원 기능을 추가했습니다.

이 새로운 기능을 통해 Google MCP Toolbox로 Elasticsearch에 연결하고 데이터와 직접 "대화하듯" 상호작용할 수 있습니다.

Elasticsearch

Elasticsearch 인스턴스가 실행 중이어야 합니다. Elastic Cloud에서 무료 체험을 활성화하거나 start-local 스크립트를 사용해 로컬에 설치할 수 있습니다.

curl -fsSL https://elastic.co/start-local | sh

이 명령을 실행하면 컴퓨터에 Elasticsearch와 Kibana가 설치되고 Google MCP Toolbox 설정에 사용할 API 키가 생성됩니다.

API 키는 이전 명령의 출력 결과로 표시되며 elastic-start-local 폴더 내 .env 파일에 저장됩니다.

예제 데이터 세트 설치하기

설치가 완료되면 사용자 이름 elastic과 start-local 스크립트로 생성된 비밀번호(.env 파일에 저장됨)를 사용해 Kibana에 로그인할 수 있습니다.

Kibana에서 제공되는 eCommerce orders 데이터 세트를 설치할 수 있습니다. 이 데이터 세트에는 kibana_sample_data_ecommerce라는 단일 인덱스가 포함되어 있으며 전자상거래 웹사이트의 4,675개 주문 정보를 담고 있습니다. 각 주문에는 다음과 같은 정보가 포함되어 있습니다.

고객 정보(이름, ID, 생년월일, 이메일 등)
주문 날짜
주문 ID
제품(가격, 수량, ID, 카테고리, 할인 등을 포함한 전체 제품 목록)
SKU
총액(세전, 세후)
총 수량
지리 정보(도시, 국가, 대륙, 위치, 지역)

샘플 데이터를 설치하려면 Kibana의 통합 페이지를 열고(상단 검색창에서 "통합"을 검색) "Sample Data"를 설치하세요. 자세한 내용은 다음 문서에서 확인할 수 있습니다: https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana

이 글의 목표는 Google MCP Toolbox를 설정해 Elasticsearch에 연결하고 자연어로 kibana_sample_data_ecommerce 인덱스와 손쉽게 상호작용하는 방법을 보여주는 것입니다.

Google MCP Toolbox

Google MCP Toolbox는 애플리케이션과 AI 에이전트가 데이터베이스와 안전하고 효율적으로 상호작용할 수 있도록 설계된 오픈 소스 MCP 서버입니다. 이전에는 'GenAI Toolbox for Databases'로 알려졌으나 Model Context Protocol(MCP)을 전면 지원하게 되면서 현재의 이름으로 변경되었습니다. 이 프로젝트의 목적은 연결 풀링, 인증, 통합 가시성 등과 같은 다양한 운영 관리 요소들을 백그라운드에서 처리하여 에이전트를 데이터베이스에 연결할 때 기존에 필요하던 번거로운 작업을 줄이는 데 있습니다.

Toolbox의 핵심은 개발자가 데이터베이스 상호작용을 캡슐화한 재사용 가능한 고수준 도구를 정의할 수 있도록 한다는 점입니다. 이러한 도구는 MCP 호환 클라이언트(예: AI 에이전트)에서 호출할 수 있으며 클라이언트가 저수준 SQL 쿼리를 구현하거나 데이터베이스 연결을 직접 관리할 필요가 없습니다. 이러한 접근 방식은 데이터베이스 인식 에이전트를 구축하는 데 필요한 보일러플레이트 코드(boilerplate code)의 양을 크게 줄여 단 몇 줄의 애플리케이션 로직만으로도 고급 데이터 처리 기능을 통합할 수 있게 합니다. 한 번 정의된 도구는 여러 에이전트, 프레임워크, 언어 간에 손쉽게 공유할 수도 있습니다(그림 1).

Toolbox를 사용할 때의 큰 장점 중 하나는 기본으로 제공되는 보안 모델입니다. OAuth2와 OIDC 같은 인증 흐름을 기본적으로 지원하므로 개발자는 에이전트에서 민감한 데이터베이스 자격 증명을 직접 다루거나 저장하지 않아도 됩니다. 또한 이 플랫폼은 OpenTelemetry를 통해 메트릭과 트레이싱을 포함한 통합 가시성 기능을 제공하며 이는 디버깅, 모니터링 및 프로덕션 배포에 필수적입니다. 종합하면 MCP Toolbox는 MCP를 지원하는 모든 시스템에서 데이터와 상호작용하기 위한 통합되고 안전하며 확장 가능한 인터페이스 역할을 합니다.

MCP Toolbox 설치 방법

다음 명령어를 사용하여 Linux에서 MCP Toolbox 서버를 설치할 수 있습니다.

export VERSION=0.21.0 curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox chmod +x toolbox

macOS 또는 Windows에 설치하려면 여기에 있는 자세한 안내를 따르세요.

Toolbox를 Elasticsearch용으로 구성하기

Elasticsearch용 MCP Toolbox를 구성하려면 다음과 같이 tools.yaml 파일을 생성해야 합니다.

sources: my-cluster: kind: elasticsearch addresses: - http://localhost:9200 apikey: tools: customer-orders: kind: elasticsearch-esql source: my-cluster description: Get the orders made by a customer identified by name. query: | FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name, {"operator": "AND"}) parameters: - name: name type: string description: The customer name. toolsets: elasticsearch-tools: - customer-orders

값을 유효한 Elasticsearch API 키로 교체해야 합니다. 로컬에서 start-local로 Elasticsearch를 실행하고 있는 경우 생성된 .env 파일의 ES_LOCAL_API_KEY 변수에서 API 키를 확인할 수 있습니다. Elastic Cloud를 사용하는 경우 여기에 설명된 절차를 따라 API 키를 생성할 수 있습니다.

이전 도구에는 Elasticsearch를 위한 다음 ES|QL 쿼리가 포함되어 있습니다:

ES|QL에 익숙하지 않다면 간단히 이렇게 이해할 수 있습니다. ES|QL은 Elastic이 개발한 쿼리 언어로 SQL과 비슷한 방식으로 하나 이상의 인덱스를 대상으로 데이터를 검색할 수 있습니다. ES|QL에 대한 더 자세한 내용은 여기에서 공식 문서를 통해 확인할 수 있습니다.

위의 쿼리는 ?name 매개변수(물음표는 매개변수를 의미)를 사용해 지정된 고객 이름이 포함된 모든 주문을 kibana_sample_data_ecommerce 인덱스에서 검색합니다.

고객 이름은 앞서 작성한 YAML 구성에서 string 타입과 'The customer name' 설명으로 정의되었습니다.

이 도구를 사용하면 고객인 Foo는 2025년 10월에 몇 건의 주문을 했나요?와 같은 고객의 주문 관련 질문에 답할 수 있습니다.

도구와 그 매개변수에 대한 설명은 사용자의 자연어 요청에서 관련 정보를 추출하는 데 매우 중요합니다. 이러한 정보 추출은 대규모 언어 모델(LLM)의 함수 호출 기능을 통해 수행됩니다. 실제로 LLM은 필요한 정보를 얻기 위해 실행해야 할 함수(도구)와 해당 함수에 필요한 매개변수를 자동으로 식별할 수 있습니다.

함수 호출에 대한 자세한 내용은 Ashish Tiwari가 작성한 OpenAI function calling with Elasticsearch(Elasticsearch와 함께 사용하는 OpenAI 함수 호출)라는 글을 참고하세요.

Toolbox 서버 실행하기

앞서 작성한 tools.yaml 파일을 사용해 MCP Toolbox를 다음 명령어로 실행할 수 있습니다.

./toolbox --tools-file tools.yaml --ui

-ui 매개변수를 사용하면 http://127.0.0.1:5000/ui에서 웹 애플리케이션이 실행됩니다(그림 2).

Tools > customer-orders를 선택한 뒤 name 매개변수에 고객 이름(예: Gwen Sanders)을 입력하고 Run Tool 버튼을 클릭할 수 있습니다. 그림 3에 표시된 것과 같은 JSON 응답이 표시됩니다.

이로써 설정이 완료되며 MCP Toolbox는 customer-orders 도구를 실행해 Elasticsearch와 통신하고 ES|QL 쿼리를 실행할 수 있습니다.

Gemini CLI와 함께 MCP Toolbox 사용하기

데이터베이스용 MCP Toolbox와의 통신에는 어떤 MCP 클라이언트든 사용할 수 있습니다. 예를 들어 Gemini를 사용하기 위한 명령줄 도구인 Gemini CLI를 사용할 수 있습니다. Gemini CLI는 여기에 안내된 지침에 따라 설치할 수 있습니다.

Gemini CLI에는 MCP Toolbox용으로 사전 구성된 확장 프로그램이 제공되며 gemini-cli-extensions/mcp-toolbox에서 사용할 수 있습니다. 다음 명령어를 실행해 이 확장 프로그램을 설치할 수 있습니다.

gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

설치가 완료되면 MCP Toolbox용 tools.yaml 설정 파일을 저장한 디렉터리로 이동한 뒤 다음과 같이 Gemini CLI를 실행해야 합니다. 이는 Gemini CLI가 MCP Toolbox와 자동으로 구성되기 위해 필요한 단계입니다.

gemini

그림 4에 표시된 출력 결과를 확인할 수 있습니다.

다음 명령어로 MCP Toolbox가 연결되어 있는지 확인할 수 있습니다.

/mcp list

mcp_toolbox 항목 아래에 customer-orders 도구가 나열된 것을 확인할 수 있습니다(그림 5).

MCP Toolbox가 Gemini CLI에 연결되었다면 이제 ”고객인 Gwen Sanders의 주문 내역을 알려주세요”와 같은 질문을 해볼 수 있습니다. 그러면 Gemini CLI가 mcp_toolbox 서버에서 customer-orders 도구를 실행할 수 있는 권한을 요청합니다(그림 6 참조).

확인되면 Gemini CLI는 MCP Toolbox에 요청을 보내 JSON 응답을 받은 다음 이를 바탕으로 최종 응답을 구성합니다(그림 7).

Gemini CLI의 응답에는 Gwen Sanders가 2개 상품을 한 번만 주문했으며 총액은 132유로라는 내용이 표시됩니다.

MCP Toolbox SDKs

Google MCP Toolbox는 Go, Python, JavaScript로 작성된 프로그램에서 모든 기능에 접근할 수 있는 SDK도 제공합니다.

예를 들어 Python SDK는 다음의 GitHub 페이지에서 이용할 수 있습니다: https://github.com/googleapis/mcp-toolbox-sdk-python

MCP Toolbox에 연결하기 위해 간단한 에이전트를 만들어야 합니다. 이를 위해 다음 패키지를 설치해야 합니다.

pip install toolbox-core pip install google-adk

그리고 아래 명령어로 새로운 에이전트 프로젝트를 생성합니다.

adk create my_agent

이 명령을 실행하면 agent.py 파일이 포함된 my_agent라는 새 디렉터리가 생성됩니다.

Toolbox에 연결하기 위해 my_agent/agent.py를 다음 내용으로 업데이트합니다.

from google.adk import Agent from google.adk.apps import App from toolbox_core import ToolboxSyncClient client = ToolboxSyncClient("http://127.0.0.1:5000") root_agent = Agent( name='root_agent', model='gemini-2.5-flash', instruction="You are a helpful AI assistant designed to search information about a dataset of ecommerce orders.", tools=client.load_toolset(), ) app = App(root_agent=root_agent, name="my_agent")

Google API 키를 포함한 .env 파일을 생성합니다.

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env

마지막으로 에이전트를 실행하여 결과를 확인할 수 있습니다. 에이전트를 실행하려면 아래 명령어를 입력합니다.

adk run my_agent

또는 웹 인터페이스로 제공할 수도 있습니다.

adk web --port 8000

두 경우 모두 Q&A 인터페이스를 통해 MCP Toolbox와 상호작용할 수 있습니다. 예를 들어 이전 예시처럼 고객인 Gwen Sanders의 주문 내역을 보여주세요라고 질문할 수 있습니다.

다양한 SDK에 대한 자세한 내용은 이 문서 페이지를 참고하세요.

결론

이번 글에서는 Google MCP Toolbox for Databases와 Elasticsearch를 통합하는 방법을 시연했습니다. 간단한 YAML 구성 파일만으로 ES|QL 언어를 활용해 자연어 질문을 Elasticsearch 쿼리로 변환하는 도구 세트를 정의할 수 있습니다.

또한 전자상거래 웹사이트의 주문 데이터를 포함하고 있는 kibana_sample_data_ecommerce 데이터 세트와 상호작용하는 방법을 시연했습니다. 이 설정 파일을 사용하면 MCP Toolbox 서버를 간단히 실행하고 모든 MCP 클라이언트에서 해당 서버에 연결할 수 있습니다.

마지막으로 Gemini CLI를 클라이언트로 사용해 MCP Toolbox for Databases에 연결하고 Elasticsearch에 저장된 전자상거래 데이터를 조회하는 과정을 시연했습니다. 특정 고객 이름을 기준으로 주문 정보를 조회하는 자연어 쿼리도 직접 실행해 보았습니다.

MCP 생태계가 계속 성장함에 따라 안전하고 프로덕션 환경에 바로 투입할 수 있는 인프라를 기반으로 한 경량 도구 정의 방식은 적은 노력으로도 점점 더 고도화되고 데이터에 정통한 에이전트를 구축할 수 있는 새로운 기회를 열어 줍니다. 로컬 환경에서 Elastic의 샘플 데이터 세트로 실험하는 경우나 대규모 애플리케이션에 검색 기능을 통합하는 경우에도 MCP Toolbox는 자연어를 통해 Elasticsearch 데이터와 상호작용할 수 있는 신뢰성 높고 확장 가능한 기반을 제공합니다.

에이전틱 AI 애플리케이션 개발에 대해 더 알고 싶다면 Anish Mathur와 Dana Juratoni가 작성한 Building AI Agentic Workflows with Elasticsearch(Elasticsearch로 AI 에이전틱 워크플로우 구축하기)라는 글을 참고해 보세요.

Google MCP Toolbox 관련 추가 정보는 https://googleapis.github.io/genai-toolbox/getting-started/introduction/에서 확인할 수 있습니다.

ES|QL에서 PHP 객체로

Enrico Zimuel — Mon, 08 Apr 2024 00:00:00 GMT

elasticsearch-php v8.13.0부터는 ES|QL 쿼리를 실행하고 그 결과를 stdClass 또는 사용자 정의 클래스의 PHP 객체에 매핑할 수 있습니다.

ES|QL

ES|QL은 Elasticsearch 8.11.0에 도입된 새로운 Elasticsearch 쿼리 언어입니다. 현재는 기술 미리보기 버전으로 제공됩니다. Elasticsearch에 저장된 데이터를 필터링, 변환, 분석할 수 있는 강력한 방법을 제공합니다.

"파이프" (|)를 사용하여 단계별 방식으로 데이터를 조작하고 변환합니다. 이 접근 방식을 통해 사용자는 한 작업의 출력이 다음 작업의 입력이 되는 일련의 작업을 구성하여 복잡한 데이터 변환 및 분석을 수행할 수 있습니다.

예를 들어 다음 쿼리는 sample_data 인덱스의 처음 3개 문서(행)를 반환합니다:

FROM sample_data | LIMIT 3

사용 사례: 공식 PHP 클라이언트의 ES|QL 기능

공식 PHP 클라이언트에서 개발된 ES|QL 기능을 설명하기 위해 다음 정보를 포함한 81,828권의 책(54.4MB)으로 구성된 CSV 파일을 Elasticsearch에 저장했습니다:

Title;Descrition;Author;Year;Publisher;Ratings

이 목록은 공개적으로 사용 가능한 Amazon 서평 데이터 세트에서 추출했습니다.

다음 Elasticsearch 매핑을 사용하여 books 인덱스를 생성했습니다:

'mappings' : { 'properties': { 'title': { 'type': 'text' }, 'description': { 'type': 'text' }, 'author': { 'type': 'text' }, 'year': { 'type': 'short' }, 'publisher': { 'type': 'keyword' }, 'rating': { 'type': 'half_float' } } }

rating 값은 2.9GB의 Books_rating.csv 파일에서 가져온 순위 리뷰의 평균입니다.

여기에서 Elasticsearch에서 모든 도서를 일괄 가져오기 위해 사용한 PHP 스크립트를 찾을 수 있습니다. 대량 작업은 PHP 8.2.17을 사용하여 7초와 28MB RAM이 소요되었습니다. 제안된 매핑을 사용하면 Elasticsearch의 인덱스 크기는 약 62MB입니다.

ES|QL 결과를 PHP 객체 또는 사용자 정의 클래스에 매핑하기

esql()->query() 엔드포인트를 사용하여 PHP에서 ES|QL 쿼리를 실행할 수 있습니다. 이 쿼리의 결과는 테이블 데이터 구조입니다. 이는 columns 및 values 필드를 사용하여 JSON으로 표현됩니다. columns 필드에는 name 및 type 정의가 있습니다.

다음은 사용자 순위 리뷰에 따라 스티븐 킹이 쓴 상위 10권의 책을 검색하는 ES|QL 쿼리의 예입니다:

$query = <<esql()->query([ 'body' => ['query' => $query] ]);

Elasticsearch의 JSON 결과는 다음과 같습니다:

{ "columns": [ { "name": "author", "type": "text" }, { "name": "description", "type": "text" }, { "name": "publisher", "type": "keyword" }, { "name": "rating", "type": "double" }, { "name": "title", "type": "text" }, { "name": "year", "type": "integer" } ], "values": [ [ "Stephen King", "The author ...", "Turtleback", 5.0, "How writers write", 2002 ], [ "Stephen King", "In Blockade Billy, a retired coach...", "Simon and Schuster", 5.0, "Blockade", 2010 ], [ "Stephen King", "A chilling collection of twenty horror stories.", "Signet Book", 4.55859375, "Night Shift (Signet)", 1979 ], ... ] }

이 예에서는 책과 관련된 6개의 속성(저자, 설명, 출판사, 등급, 제목, 연도)과 10개의 결과(모두 스티븐 킹의 책)가 있습니다.

ES|QL에서 지원되는 모든 유형 목록은 여기에 나와 있습니다.

$result 응답 개체는 배열, 문자열 또는 객체로 액세스할 수 있습니다(자세한 내용은 여기를 참조하세요).

객체 인터페이스를 사용하면 속성 및 인덱스를 사용하여 값에 액세스할 수 있습니다. 예를 들어 $result->values[0][4] 은 목록에서 첫 번째 책(0)의 제목(4)을 반환하고 $result->values[1][3] 은 두 번째 책(1)의 순위 점수(3) 등을 반환합니다. PHP에서 배열의 인덱스는 0부터 시작한다는 점을 기억하세요.

이 인터페이스는 일부 사용 사례에는 충분할 수 있지만 대부분의 경우 결과물로 여러 개의 객체를 원합니다.

결과를 객체 배열로 매핑하려면 elasticsearch-php의 새로운 mapTo() 기능을 사용할 수 있습니다.

이 기능은 Elasticsearch 응답 개체에서 직접 사용할 수 있습니다. 즉, 다음과 같이 액세스할 수 있습니다:

$books = $result->mapTo(); // Array of stdClass foreach ($books as $book) { printf( "%s, %s, %d, Rating: %.2f\n", $book->author, $book->title, $book->year, $book->rating ); }

사용자 지정 Book 클래스가 있는 경우 다음과 같이 이를 사용하여 결과를 매핑할 수 있습니다:

class Book { public string $author; public string $title; public string $description; public int $year; public float $rating; } $books = $result->mapTo(Book::class); // Array of Book

클래스에 ES|QL 결과에 포함된 속성 외에 다른 속성이 있는 경우 이 방법도 작동합니다. mapTo() 함수는 ES|QL 결과의 열로 반환된 속성만 사용합니다.

이 문서에 보고된 모든 예제는 여기에서 다운로드할 수 있습니다.