AI 에이전트가 SQL로 로컬 데이터를 쿼리하도록 하십시오

Claude Code, Codex, Cursor 및 기타 코딩 에이전트에 CSV, Parquet, JSON, DuckDB 데이터를 다루는 헤드리스 DuckDB 워크플로를 제공합니다. GUI 자동화도, 데이터베이스 서버도, 사용자 지정 API도 필요 없습니다.

CLI는 기본적으로 JSON을 출력하고, 인수, SQL, I/O 실패에 대해 명시적인 종료 코드를 사용합니다.

먼저 파악하고, 그다음에 쿼리하십시오

공식 워크플로는 에이전트가 열 이름을 추측하거나 일부 미리보기를 전체 데이터셋으로 착각하지 않게 합니다.

  1. 스키마를 파악하십시오

    ducklocal schema ./data/를 실행하면 릴레이션, 바로 쿼리에 쓸 수 있는 FROM 식, 열과 타입을 얻습니다. 카탈로그가 크면 더 깊이 파고들 수 있는 힌트와 함께 요약을 반환합니다.

  2. 범위 안에서 미리보십시오

    하나의 SQL 문과 작은 --limit로 대표 행을 확인합니다. 명령의 종료 상태와 JSON truncated 필드를 확인하십시오.

  3. SQL에서 답을 계산하십시오

    잘린 미리보기를 에이전트 컨텍스트에서 합산하지 말고 필터, 조인, 집계를 DuckDB에서 실행합니다. 답에 필요한 근거만 반환하십시오.

Claude Code, Codex, Cursor에서 설정하기

모든 에이전트에는 두 가지가 필요합니다. PATH에 있는 ducklocal 명령과 그 사용법에 대한 지침입니다. 둘 다 앱의 Command line & AI…(제목 표시줄의 로봇 버튼 또는 DuckLocal 메뉴)에서 준비할 수 있습니다.

Claude Code: 스킬 설치

Install command를 클릭한 다음 Add to Claude Code를 클릭하세요. 스킬이 ~/.claude/skills/ducklocal에 저장되고, Claude Code는 모든 프로젝트에서 이를 찾습니다. 요청이 스킬과 맞으면 Claude Code가 스킬을 불러와 시키지 않아도 스키마부터 확인하는 워크플로를 따릅니다.

# In any project, ask in plain language:
Which channel brought in the most revenue in data/sales.csv?
Use DuckLocal and show me the query.

한 프로젝트에서만 스킬을 쓰려면 skills/ducklocal을 그 프로젝트의 .claude/skills/에 복사하세요.

Codex: 지침을 AGENTS.md에 붙여넣기

Install command를 클릭한 다음 Copy brief를 클릭하고, 지침을 프로젝트 루트의 AGENTS.md에 붙여넣으세요. Codex는 세션을 시작할 때 이 파일을 읽습니다. 지침 내용(일부):

DuckLocal is installed on this machine. Its command, ducklocal,
runs DuckDB SQL over local CSV, TSV, Parquet, JSON and Excel files
and databases, and prints JSON.

- Start with `ducklocal --help` for the options.
- See what there is to query, with columns, before writing SQL:
  `ducklocal schema ./data/` (or `--database file.duckdb`).
- Profile what you will chart or summarize:
  `ducklocal schema data.csv --stats`.
- Compute totals in SQL, not from sample rows;
  check `truncated` in the output.
- It opens data read-only by default. Answer from the values
  it returns, and say which query produced them.

사용하는 Codex 버전이 스킬을 지원한다면 같은 SKILL.md와 references/cli.md를 그 스킬 디렉터리에 복사해도 됩니다.

Cursor: 지침을 프로젝트 규칙으로 저장

Install command를 클릭한 다음 Copy brief를 클릭하고, 지침을 프로젝트 규칙(예: .cursor/rules/ducklocal.mdc)으로 저장하세요. 그러면 Cursor 에이전트는 그 프로젝트에서 작업할 때마다 이 명령을 압니다. 터미널 도구에는 ducklocal을 실행할 권한이 필요합니다. schema와 query는 허용하고, 파일에 쓰는 작업은 계속 하나씩 승인하세요.

# Then ask the agent:
Compare monthly order counts in exports/orders-*.csv
for 2025 and 2026 with DuckLocal.

에이전트가 미리보기를 직접 합산하면 안 되는 이유

행을 읽어 자기 컨텍스트에서 더하는 에이전트는 보여 준 만큼만으로 답합니다. 120만 행짜리 파일과 기본 1,000행 한도라면, 보이는 것은 데이터의 0.1%도 안 됩니다. 보고하는 합계가 그럴듯해 보여도 자릿수가 틀릴 수 있습니다.

DuckLocal은 그 공백을 조용히 숨기지 않고 드러냅니다. 미리보기는 "truncated": true를 반환하고, total_rows는 결과가 실제로 몇 행이었는지 보여 줍니다. 세기가 일찍 멈추면 total_rows_exact가 false이고 그 합계는 하한일 뿐입니다. 스킬은 에이전트가 이를 표본으로 다루고 계산을 모든 행을 읽는 DuckDB에 맡기도록 알려 줍니다.

한도, 예산, 출력 형식

Terminal
$ ducklocal query --sql \
  "SELECT * FROM 'events.csv'"
{..., "row_count":1000,
 "truncated":true,
 "total_rows":101000,
 "total_rows_exact":false}

$ ducklocal query --sql \
  "SELECT count(*) AS n, sum(amount) AS total
   FROM 'events.csv'"
{..., "rows":[[1204381,8812094.5]],
 "truncated":false}

명령 하나, SQL 문 하나

호출마다 전용 DuckDB 연결을 만들고, 입력에 문이 정확히 하나 있는지 검증한 뒤 기계가 읽을 수 있는 결과를 stdout에 씁니다. 오류는 JSON으로 stderr에 기록되고 0이 아닌 종료 코드가 반환됩니다.

쿼리 계약 읽기

터미널
$ ducklocal query --sql \
  "SELECT channel, round(sum(revenue), 2) AS revenue
   FROM 'sales.csv'
   GROUP BY channel
   ORDER BY revenue DESC"

{"columns":[...],
 "rows":[["Mobile app",290549.76],...],
 "row_count":4,
 "truncated":false,
 "elapsed_ms":14}

계약이 명시된 작은 인터페이스

ducklocal schema ./data/

릴레이션 찾기

SQL을 작성하기 전에 파일, 테이블, 뷰와 그 열을 나열합니다.

ducklocal schema sales.csv --stats

릴레이션 하나 프로파일링하기

정확한 null 수, 서로 다른 값의 수, 범위, 중앙값, 날짜 범위를 얻습니다.

ducklocal query --sql "…"

문 하나 실행하기

기본적으로 타입이 지정된 JSON을, --format md를 사용하면 Markdown 표를 받습니다.

ducklocal open --title "…" --run --sql "…"

작업을 사람에게 넘기기

결과를 검토하거나 더 탐색해야 할 때 데스크톱 앱에서 쿼리를 엽니다.

결과가 불완전하다는 것을 에이전트에 알려 주는 출력

기본 반환 한도는 1,000행이며, 추가로 2,000,000셀 예산이 적용됩니다. DuckLocal은 한 행을 더 읽어 응답이 잘렸는지 판단하고 이를 truncated로 노출합니다.

GROUP BY, ORDER BY, 집계 같은 쿼리는 상한이 적용된 결과를 반환하기 전에 전체 입력에 대해 계산됩니다.

  • 안정적인 JSON 봉투에 담긴 타입이 지정된 열과 행
  • 명시적인 row_count, truncated, elapsed_ms
  • 잘못된 인수는 종료 코드 2, 실행 실패는 종료 코드 1
  • 오류는 JSON으로 stderr에, stdout은 비어 있음
  • 사람이 읽는 보고서를 위한 Markdown 출력

명령만이 아니라 워크플로를 가르칩니다

오픈 소스 DuckLocal 스킬은 에이전트에게 스키마를 확인하고, 상한이 적용된 샘플을 미리보고, SQL로 집계하고, 잘림 여부를 검증하고, 반환된 값으로 답하는 방법을 가르칩니다. 앱에서 Claude Code용으로 설치하거나 같은 설명을 다른 코딩 에이전트에 복사하십시오.

스킬 설치하고 살펴보기

읽기: Claude Dashboards에서 DuckLocal에 대해 배운 것 →

숨겨진 클라우드 서비스나 샌드박스가 아닌 로컬 CLI

DuckLocal은 로컬 파일을 DuckLocal 서비스에 업로드하지 않지만, 임의의 SQL이 무해한 척하지도 않습니다. 읽기 전용 데이터베이스 모드는 파일 시스템이나 네트워크 샌드박스가 아닙니다. COPY 같은 SQL, 확장 기능 설치, 명시적인 외부 액세스는 부작용을 남길 수 있습니다.

  • 출력 경로, 덮어쓰기, 데이터베이스 변경을 승인하십시오
  • 확장 기능 설치와 외부 액세스를 승인하십시오
  • 실패한 쓰기를 다시 시도하기 전에 대상을 확인하십시오
  • 의도적으로 데이터베이스를 변경할 때만 --read-write를 사용하십시오
  • 명령에 의존하기 전에 ducklocal --help를 확인하십시오

AI 에이전트 SQL 관련 질문

AI 에이전트는 DuckLocal로 로컬 데이터를 어떻게 쿼리합니까?
에이전트는 ducklocal schema를 실행해 릴레이션과 열을 확인한 다음, 하나의 SQL 문으로 ducklocal query를 실행합니다. 이 명령은 데스크톱 창을 열거나 서버를 시작하지 않고 기본적으로 구조화된 JSON을 반환합니다.
CLI는 기본적으로 전체 데이터를 반환합니까?
아니요. 쿼리 출력에는 의도적으로 상한이 있습니다. 기본 행 제한은 1,000행이며 2,000,000셀 예산도 함께 적용됩니다. JSON 응답은 결과가 잘렸는지 알려 줍니다. 전체 집계는 SQL 안에서 계산하십시오.
DuckLocal은 에이전트를 위해 SQL 스크립트를 실행할 수 있습니까?
ducklocal query 호출은 각각 정확히 하나의 SQL 문만 받습니다. 여러 문이 있는 스크립트는 일부만 실행되지 않고 거부되므로 각 도구 호출을 검토하기가 더 쉽습니다.
DuckLocal은 Codex와 Cursor에서도 쓸 수 있나요, 아니면 Claude Code 전용인가요?
터미널 명령을 실행할 수 있는 에이전트라면 무엇이든 쓸 수 있습니다. Claude Code는 앱에서 클릭 한 번으로 공식 스킬을 설치합니다. Codex, Cursor 등 다른 에이전트에는 앱의 Copy brief 버튼으로 만든 지침을 AGENTS.md나 프로젝트 규칙에 붙여넣으면 됩니다.
DuckLocal은 MCP 서버나 보안 샌드박스입니까?
아니요. DuckLocal이 제공하는 것은 명령줄 인터페이스와 선택적 에이전트 스킬이며, MCP 서버나 보안 샌드박스가 아닙니다. 쓰기 가능성, 확장 기능 설치, 외부 액세스에는 여전히 정상적인 승인이 필요합니다.

에이전트에 스키마 우선 SQL 워크플로를 제공하십시오

DuckLocal을 설치하고 명령을 PATH에 추가한 뒤, 데이터에 실제로 무엇이 있는지 묻는 것부터 시작하십시오.