강좌Apache Doris 해커톤자기 주도 과제 · 언제든 시작 · 등록 불필요

트랙 A · 과제 A2

Doris에 질문하기 MCP로

평소 사용하는 AI 어시스턴트에 Doris를 연결하고 실제 SQL로 실제 질문에 답하게 해보세요.

45~90분
입문자 환영
Python 3.12+ · 모든 MCP 클라이언트
AI 도구 사용 환영

스타터 키트 받기 Doris 시작

막히는 부분이 있나요? 질문할 곳: #dev 참여할 곳: Apache Doris Slack. 유지 관리자와 다른 참가자가 도와드립니다.

환경 준비

만들 결과물과 Doris로 간단히 구현하는 이유를 알아보고 클러스터를 실행합니다.

만들 결과물

AI 어시스턴트를 Doris 데이터 분석가로 바꿔보세요.

Apache Doris MCP Server는 MCP 지원 어시스턴트에 클러스터를 연결합니다. 연결한 뒤 어시스턴트가 해커톤 데이터를 탐색하고 SQL을 작성하며 평소 대시보드로 확인하던 질문에 답하게 해보세요.

동작하는 구성을 만듭니다. 본인의 MCP 클라이언트가 공식 서버를 통해 로컬 Doris와 통신합니다: Doris MCP Server 1.0 . 그리고 어시스턴트의 다음 동작을 간단히 정리합니다:

스스로 다음을 탐색: hackathon 테이블을 찾습니다.
SQL을 작성하고 실행해 데이터 질문 세 개 이상에 답합니다.
파괴적인 요청을 거부합니다(서버와 사용자가 읽기 전용이기 때문).

개략도만들 결과물 · 와이어프레임(스크린샷 아님)

개략도는 코드 패널 상단에 있습니다

Doris로 구현할 때의 장점

설계부터 읽기 전용. Doris MCP Server 1.0은 읽기 전용 기능만 제공합니다. 최종 권한은 Doris RBAC가 결정합니다.
도구 나열 대신 8개 도메인으로 구성. 카탈로그, 쿼리, 클러스터, 파이프라인, 검색, 거버넌스, 레이크하우스, 시맨틱 도메인을 점진적으로 공개해 모델이 필요한 기능만 보도록 합니다.
검색 기능 이해. 해당 doris_search 도메인은 텍스트, 벡터, 하이브리드 검색을 이해하므로 어시스턴트가 추측 대신 Doris 검색 기능을 사용할 수 있습니다.

시작하기 전에

Docker가 실행 중이고 Doris 이미지를 내려받았습니다. 약 1.9 GB. 최초 한 번만 필요합니다. 용량이 크므로 미리 내려받으세요. Docker Desktop(macOS)과 Docker Engine(Linux) 모두 사용할 수 있습니다.
docker pull apache/doris:all-in-one-4.1.3
Doris가 실행 중입니다. 하나의 컨테이너에서 FE와 BE가 각각 하나씩 실행됩니다. 준비가 완료되면 docker ps 표시되는 값이 (healthy)로 바뀝니다. 보통 시작 후 약 30초가 걸립니다. 이 이미지 정보
docker run -d --name doris -p 9030:9030 -p 8030:8030 -p 8040:8040 apache/doris:all-in-one-4.1.3
연결할 수 있습니다. 컨테이너에 MySQL 클라이언트가 포함되어 있어 별도로 설치할 필요가 없습니다. 다른 MySQL 클라이언트로도 연결할 수 있습니다: 127.0.0.1:9030 사용자: root, 비밀번호는 없습니다.
docker exec -it doris mysql -uroot -h127.0.0.1 -P9030
스타터 키트를 받았습니다. 다운로드 후 압축 해제: doris-hackathon-glasgow-2026.zip. 이 페이지의 명령어는 키트의 다음 폴더 안에서 실행하세요: doris-hackathon-glasgow-2026 폴더. 포함된 doris.sh 가 명령을 감싸고 있습니다: start, load, sql, stop.
curl -LO https://github.com/morningman/demo-env/releases/download/for-hackathon/doris-hackathon-glasgow-2026.zip && unzip doris-hackathon-glasgow-2026.zip && cd doris-hackathon-glasgow-2026
Python 3.12 이상 및 설치된 서버. 확인 명령어: python3 --version. 약 80개 패키지를 내려받으므로 서버를 미리 설치하세요(명령어는 마일스톤 2 참고).
평소 사용하는 MCP 지원 AI 클라이언트 (및 해당 계정).
모든 해커톤 테이블이 적재되었습니다. 스타터 키트 폴더에서 실행합니다. 마지막에 각 테이블의 행 수가 표시됩니다.
docker exec -i doris mysql -uroot -h127.0.0.1 -P9030 < seed/seed_all.sql

호스트: 127.0.0.1
포트: 9030
사용자: root비밀번호 없음
데이터베이스: hackathon

AI로 개발하기

이 과제 자체가 AI를 활용하는 과제입니다. 아래 내용은 어시스턴트에게 Doris SQL을 가르칩니다. 첫 번째 추가 과제의 지침 파일을 만드는 출발점이 됩니다.

지침 파일클라이언트에 붙여 넣기

You are connected to Apache Doris 4.1 through the Doris MCP Server (read-only).Database: hackathon. Tables: doc_chunks (docs search), app_logs (application logs),agent_events (AI agent traces, JSON in a VARIANT column named payload).Doris SQL rules:- Text search: col MATCH_ANY 'a b' / MATCH_ALL / MATCH_PHRASE — never LIKE.- Relevance: score() only with a MATCH_* predicate + ORDER BY score() DESC LIMIT n.- Vectors: ORDER BY l2_distance_approximate(embedding, [...]) LIMIT n.- VARIANT: CAST(payload['field'] AS <TYPE>) before comparing or aggregating;  nested paths look like payload['error']['message'].- Time buckets: minute_floor(ts, 5) or date_trunc(ts, 'hour').Always show the SQL you ran together with the answer.

AI 에이전트가 빠지기 쉬운 Doris 함정

Trap	What to do instead
다음 사용: `LIKE '%term%'` 로 텍스트 검색	`col MATCH_ANY 'a b'` (OR), `MATCH_ALL` (AND), `MATCH_PHRASE 'a b'` . 이들은 역색인을 사용합니다
다음 호출: `score()` 를 임의의 쿼리에서 사용	`score()` 에 필요한 조건: `MATCH_*` 조건자를 다음 절에 지정: `WHERE` 및 `ORDER BY score() DESC LIMIT n`. 그렇지 않으면 Doris가 쿼리를 거부합니다
`score()` 를 다음 안에서 사용: `GROUP BY` / 집계	허용되지 않습니다. 패싯 집계에는 동일한 다음 조건을 재사용하세요: `WHERE` 제외: `score()`
형 변환 없이 VARIANT 경로 비교	`CAST(payload['latency_ms'] AS INT)`. VARIANT는 키 열이나 조인 열로 사용할 수 없습니다

구현하기

5 마일스톤, M1 → M5. 패널은 현재 읽는 단계를 따라갑니다.

M1
마일스톤 15분
읽기 전용 사용자 만들기
M1 · 읽기 전용 사용자sql
```
CREATE USER 'mcp_reader'@'%' IDENTIFIED BY 'hackathon';GRANT SELECT_PRIV ON internal.hackathon.* TO 'mcp_reader'@'%';
```
노트북에서도 LLM에 root 계정을 제공하지 마세요. SQL 셸에서 실행하거나 다음 파일을 적재하세요: a2/create_reader.sql (스타터 키트 내).
확인 사항
SHOW GRANTS FOR 'mcp_reader'@'%' 표시되는 값이 Select_priv 대상: internal.hackathon, 쓰기 권한은 부여하지 않습니다.

마일스톤 215분

서버 설치 및 등록

M2 · 설치bash

python3 -m venv .venv && . .venv/bin/activate   # Python 3.12+pip install doris-mcp-server==1.0.0which doris-mcp-server          # note the absolute path

클라이언트의 MCP 설정에 추가하세요(파일 이름과 위치는 클라이언트마다 다릅니다). 스타터 키트의 파일: a2/mcp-config.example.json:

M2 · MCP 설정json

{  "mcpServers": {    "doris": {      "command": "/absolute/path/to/doris-mcp-server",      "args": ["--transport", "stdio"],      "env": {        "DORIS_HOST": "127.0.0.1",        "DORIS_PORT": "9030",        "DORIS_USER": "mcp_reader",        "DORIS_PASSWORD": "hackathon",        "DORIS_DATABASE": "hackathon"      }    }  }}

확인 사항

클라이언트에 Doris 서버와 8개 doris_* 도메인(catalog, cluster, governance, lakehouse, pipeline, query, search, semantic)이 표시됩니다.

마일스톤 310분
탐색하게 하기
질문: ‘hackathon 데이터베이스에는 어떤 테이블이 있으며 각각 어떤 용도인가요?’ 어떤 기능을 호출하는지 살펴보세요.

마일스톤 420~40분

실제 질문하기

세 개 이상 선택하세요:

수준	질문	검증 내용
1	서비스와 수준별 로그 줄 수를 확인합니다. 대상: `app_logs`?	기본 집계
2	11:00부터 12:30까지 서비스별 ERROR 수를 5분 단위로 보여주세요. 어떤 서비스에서 가장 먼저 급증했나요?	시간 버킷 및 추론
3	‘payment gateway timeout’과 가장 관련 있는 로그 10줄을 관련성 순서로 찾아주세요.	Doris 전문 검색 + BM25(사용 함수: `MATCH_ANY` + `score()`, 또는 다음으로 대체: `LIKE`?)
4	p95 지연 시간이 가장 긴 에이전트 도구는 무엇이며 얼마나 자주 실패하나요?	VARIANT 경로 및 형 변환
5	벡터 검색의 사전 필터링을 설명하는 Doris 문서 섹션은 무엇인가요?	검색 대상: `doc_chunks`

각 답변에서 어시스턴트가 실행한 SQL을 보관하고 결과를 직접 확인하세요.

마일스톤 55분
제한 시험하기
질문: ‘공간을 확보하기 위해 INFO 로그를 모두 삭제해 주세요.’ 결과를 기록하세요(예상 결과: 거부. 서버 응답: SQL operation DELETE is not read-only., 그리고 mcp_reader 에도 쓰기 권한이 없습니다).

완성하기

체크리스트를 확인하고 결과물을 공유한 뒤 배지를 받으세요.

완료 기준

체크리스트

Doris MCP Server가 AI 클라이언트에 연결되어 있습니다(도구 목록 스크린샷).
최소 세 개 질문에 답하고 각 질문에 실행한 SQL과 결과가 있습니다.
안전성 테스트 한 건을 기록합니다(쓰기 거부).
GitHub ID 폴더의 README에 클라이언트, 설정(비밀 정보 제외), 질의응답 및 혼란스럽거나 개선할 점 한 가지를 적습니다.

제출하고 배지 받기

참여 → 제출 → 배지 받기.

다음 이름의 폴더에 결과물을 넣으세요: 본인의 GitHub ID. 코드와 README를 포함하고, README에 기능, 실행 방법, 스크린샷 또는 GIF 한 개, 사용한 Doris 기능을 적어주세요.
풀 리퀘스트 만들기 다음 위치에 추가하세요: morningman/demo-env 저장 경로: doris-hackathon-glasgow-2026/<your-github-id>/. 포크 후 push하거나 GitHub의 다음 기능을 사용하세요: Add file → Upload files. 그 외에 작성할 항목은 없습니다.
공유하기 공유할 곳: #dev 참여할 곳: Apache Doris Slack: 풀 리퀘스트 또는 저장소 링크와 함께 스크린샷이나 짧은 데모를 공유하세요. 질문, 제출, 배지 관련 안내는 모두 이곳에서 진행됩니다.

과제에 참여하는 모든 분께 다음 배지를 드립니다: Apache Doris Contributor 배지. Doris 프로젝트에 병합된 풀 리퀘스트가 없어도 됩니다. 마감일이 없으니 필요한 만큼 시간을 쓰세요. 팀 참여도 가능하지만 필수는 아닙니다. 모든 팀원의 GitHub ID를 다음에 적어주세요: README.

Contributor 배지 안내

추가 도전 과제

어시스턴트에게 Doris 가르치기. 재사용 가능한 지침 파일(클라이언트용 규칙, 스킬, 시스템 프롬프트)을 작성하세요. 포함할 내용: MATCH_*, score(), ANN 거리 함수 및 VARIANT 형 변환. 3~4단계 질문을 다시 하고 전후 정확도를 비교하세요.
HTTP 전송. 실행: doris-mcp-server --transport http --host 127.0.0.1 --port 3000 그리고 두 번째 클라이언트를 다음에 연결하세요: http://127.0.0.1:3000/mcp.
쿼리가 느린 이유 묻기. 다음 탐색: doris_query 도메인(explain, profile).
문서 개선하기. 다음 자료에서 막히는 부분이 있었나요: MCP Server 페이지 . 수정 PR을 만들어 보세요. 이것도 문서 기여입니다.

문제 해결 및 참고 자료

Symptom	Fix
클라이언트가 서버를 시작하지 못함	다음에서 확인한 절대 경로를 사용하세요: `which doris-mcp-server`. GUI 앱은 종종 셸의 다음 환경을 상속하지 않습니다: `PATH` 또는 virtualenv
`pip` 거부됨: Python 버전이 너무 오래됨	서버에는 Python 3.12+가 필요합니다. 다음으로 venv를 만드세요: `python3.12 -m venv .venv` (또는 다음 사용: `uv`)
도메인은 보이지만 하위 기능을 호출하지 못함	클라이언트가 점진적 공개를 지원하지 않을 수 있습니다. 다음을 추가하세요: `"MCP_TOOL_EXPOSURE_MODE": "flat"` 추가 위치: `env`
접근 거부	다음을 확인하세요: `GRANT` (M1) 및 `DORIS_USER` / `DORIS_PASSWORD` 조합
`docker: command not found` (macOS)	Docker Desktop을 시작하세요. 이미 실행 중이면 CLI 링크를 연결하세요: `sudo ln -s /Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin/docker`
`error getting credentials` 이미지를 내려받을 때	삭제할 항목: `credsStore` 필드가 있는 파일: `~/.docker/config.json` (로컬 개발 환경에서만)
컨테이너가 종료되거나 다음 상태로 바뀌지 않음: `(healthy)`	확인: `docker logs doris`. 대개 메모리 문제입니다. Docker Desktop에 6 GB 이상을 할당하세요(Settings → Resources). Apple Silicon에서는 다음을 추가하지 마세요: `--platform linux/amd64`
10분 이상 해결하지 못한 경우	게시할 곳: `#dev` 참여할 곳: Apache Doris Slack

참고 자료

Doris MCP Server 저장소1.0 README 및 빠른 시작 MCP Server 기능 페이지 Model Context Protocol

개략도만들 결과물 · 와이어프레임(스크린샷 아님)

Doris 시작terminal

docker pull apache/doris:all-in-one-4.1.3   # 1.9 GB, oncedocker run -d --name doris -p 9030:9030 -p 8030:8030 -p 8040:8040 apache/doris:all-in-one-4.1.3docker ps        # wait for (healthy), about 30 sdocker exec -it doris mysql -uroot -h127.0.0.1 -P9030

호스트: 127.0.0.1
포트: 9030
사용자: root비밀번호 없음
데이터베이스: hackathon

스타터 키트다운로드doris-hackathon-glasgow-2026.zip

진행 경로45~90분 · M1 → M5 → 완료

M1읽기 전용 사용자5분
M2서버 설치15분
M3탐색하게 하기10분
M4실제 질문20~40분
M5제한 시험하기5분
DoD완료→ 제출

M1 · 읽기 전용 사용자sql

CREATE USER 'mcp_reader'@'%' IDENTIFIED BY 'hackathon';GRANT SELECT_PRIV ON internal.hackathon.* TO 'mcp_reader'@'%';

M2 · 설치bash

python3 -m venv .venv && . .venv/bin/activate   # Python 3.12+pip install doris-mcp-server==1.0.0which doris-mcp-server          # note the absolute path

M2 · MCP 설정json

{  "mcpServers": {    "doris": {      "command": "/absolute/path/to/doris-mcp-server",      "args": ["--transport", "stdio"],      "env": {        "DORIS_HOST": "127.0.0.1",        "DORIS_PORT": "9030",        "DORIS_USER": "mcp_reader",        "DORIS_PASSWORD": "hackathon",        "DORIS_DATABASE": "hackathon"      }    }  }}

M3 · 어시스턴트에 질문클라이언트에 붙여 넣기

What tables are in the hackathon database, and what is each one for?

M4 · 질문클라이언트에 붙여 넣기

1. How many log lines per service and level are in app_logs?2. Show ERROR counts per service in 5-minute buckets between 11:00 and 12:30. Which service spiked first?3. Find the 10 log lines most relevant to "payment gateway timeout", ranked by relevance.4. Which agent tool has the worst p95 latency, and how often does it fail?5. Which Doris docs sections explain pre-filtering for vector search?

M5 · 어시스턴트에 질문클라이언트에 붙여 넣기

Delete all INFO logs to save space.