ducklocal schema ./data/릴레이션 찾기
SQL을 작성하기 전에 파일, 테이블, 뷰와 그 열을 나열합니다.
Claude Code, Codex, Cursor 및 기타 코딩 에이전트에 CSV, Parquet, JSON, DuckDB 데이터를 다루는 헤드리스 DuckDB 워크플로를 제공합니다. GUI 자동화도, 데이터베이스 서버도, 사용자 지정 API도 필요 없습니다.
CLI는 기본적으로 JSON을 출력하고, 인수, SQL, I/O 실패에 대해 명시적인 종료 코드를 사용합니다.
공식 워크플로는 에이전트가 열 이름을 추측하거나 일부 미리보기를 전체 데이터셋으로 착각하지 않게 합니다.
ducklocal schema ./data/를 실행하면 릴레이션, 바로 쿼리에 쓸 수 있는 FROM 식, 열과 타입을 얻습니다. 카탈로그가 크면 더 깊이 파고들 수 있는 힌트와 함께 요약을 반환합니다.
하나의 SQL 문과 작은 --limit로 대표 행을 확인합니다. 명령의 종료 상태와 JSON truncated 필드를 확인하십시오.
잘린 미리보기를 에이전트 컨텍스트에서 합산하지 말고 필터, 조인, 집계를 DuckDB에서 실행합니다. 답에 필요한 근거만 반환하십시오.
모든 에이전트에는 두 가지가 필요합니다. PATH에 있는 ducklocal 명령과 그 사용법에 대한 지침입니다. 둘 다 앱의 Command line & AI…(제목 표시줄의 로봇 버튼 또는 DuckLocal 메뉴)에서 준비할 수 있습니다.
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/에 복사하세요.
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를 그 스킬 디렉터리에 복사해도 됩니다.
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.
지침의 정확한 문구는 설치된 앱에서 가져오며, ducklocal이 아직 PATH에 없으면 명령의 전체 경로가 들어갑니다. 스킬 설치하고 살펴보기 →
행을 읽어 자기 컨텍스트에서 더하는 에이전트는 보여 준 만큼만으로 답합니다. 120만 행짜리 파일과 기본 1,000행 한도라면, 보이는 것은 데이터의 0.1%도 안 됩니다. 보고하는 합계가 그럴듯해 보여도 자릿수가 틀릴 수 있습니다.
DuckLocal은 그 공백을 조용히 숨기지 않고 드러냅니다. 미리보기는 "truncated": true를 반환하고, total_rows는 결과가 실제로 몇 행이었는지 보여 줍니다. 세기가 일찍 멈추면 total_rows_exact가 false이고 그 합계는 하한일 뿐입니다. 스킬은 에이전트가 이를 표본으로 다루고 계산을 모든 행을 읽는 DuckDB에 맡기도록 알려 줍니다.
$ 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}
호출마다 전용 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, 집계 같은 쿼리는 상한이 적용된 결과를 반환하기 전에 전체 입력에 대해 계산됩니다.
row_count, truncated, elapsed_ms오픈 소스 DuckLocal 스킬은 에이전트에게 스키마를 확인하고, 상한이 적용된 샘플을 미리보고, SQL로 집계하고, 잘림 여부를 검증하고, 반환된 값으로 답하는 방법을 가르칩니다. 앱에서 Claude Code용으로 설치하거나 같은 설명을 다른 코딩 에이전트에 복사하십시오.
DuckLocal은 로컬 파일을 DuckLocal 서비스에 업로드하지 않지만, 임의의 SQL이 무해한 척하지도 않습니다. 읽기 전용 데이터베이스 모드는 파일 시스템이나 네트워크 샌드박스가 아닙니다. COPY 같은 SQL, 확장 기능 설치, 명시적인 외부 액세스는 부작용을 남길 수 있습니다.
--read-write를 사용하십시오ducklocal --help를 확인하십시오대신 시각적인 워크플로가 필요하십니까? 데스크톱 앱에서 로컬 데이터 분석 보기 →
ducklocal schema를 실행해 릴레이션과 열을 확인한 다음, 하나의 SQL 문으로 ducklocal query를 실행합니다. 이 명령은 데스크톱 창을 열거나 서버를 시작하지 않고 기본적으로 구조화된 JSON을 반환합니다.ducklocal query 호출은 각각 정확히 하나의 SQL 문만 받습니다. 여러 문이 있는 스크립트는 일부만 실행되지 않고 거부되므로 각 도구 호출을 검토하기가 더 쉽습니다.AGENTS.md나 프로젝트 규칙에 붙여넣으면 됩니다.관련 항목: DuckDB GUI · Parquet 뷰어 · SQL로 CSV 쿼리 · SQL 대시보드 · DuckLocal vs DBeaver
DuckLocal을 설치하고 명령을 PATH에 추가한 뒤, 데이터에 실제로 무엇이 있는지 묻는 것부터 시작하십시오.