콘텐츠로 이동

문제 해결 ​

증상을 찾고, 원인을 읽고, 해결 방법을 적용하세요. 여기에 없는 문제라면 무엇을 했고 무엇이 일어났는지 자세히 적어 issue를 열어 주세요.

설치와 실행 ​

증상원인과 해결
Intel Mac에서 앱이 열리지 않음macOS 릴리스는 Apple silicon 전용으로 빌드되었습니다. Intel에서는 소스에서 빌드하세요
이 문서의 바로 가기가 Windows나 Linux에서 동작하지 않음**⌘**를 Ctrl로 바꿔 읽으세요. 여기서 ⌘↵는 Ctrl+Enter입니다
ducklocal: command not found디스크 이미지는 앱을 설치할 뿐 명령은 설치하지 않습니다. 바이너리를 PATH에 링크하세요
창이 열려 있는 동안 터미널이 사용 중임터미널에서 GUI를 실행하면 포그라운드에서 동작합니다. 대신 응용 프로그램에서 실행하거나, 그 터미널을 그대로 두세요
기록, 설정, 기억된 파일이 더 이상 저장되지 않음두 번째 DuckLocal이 실행 중이며 앱 데이터 파일을 잡고 있습니다. 다른 하나를 종료하고 다시 실행하세요
지난번 DuckLocal이 예기치 않게 종료되었습니다크래시가 발생해 로그 폴더에 보고서를 저장했습니다. 보고서 표시를 클릭해 issue에 첨부하세요 — 저장 위치를 참고하세요
업데이트 확인 실패마우스를 올리면 이유가 나옵니다: 오프라인, 프록시, 또는 체크섬이 일치하지 않은 다운로드입니다. 클릭해 다시 시도하거나 GitHub에서 릴리스를 내려받으세요 — 업데이트 확인 참고

데이터 열기 ​

증상원인과 해결
지정한 경로에서 File not found경로가 없거나, 생각하는 것과 다른 디렉터리 기준의 상대 경로입니다. 확실히 하려면 절대 경로를 사용하세요
폴더에 데이터 파일이 없다고 나옴그 아래에 .csv, .tsv, .txt, .parquet, .json, .ndjson, .jsonl, .xlsx, .xls, .xlsb, .ods 중 어느 것도 맞지 않았습니다
폴더에서 예상보다 적은 파일이 나옴숨은 항목과 심볼릭 링크는 건너뛰고, 한 번의 열기 요청은 최대 256개 파일을 연결합니다. 하위 폴더를 따로 여세요
경로가 예기치 않게 데이터베이스로 열림데이터 파일이 아닌 기존 파일은 DuckDB 데이터베이스로 취급됩니다. 열리지 않으면 DuckLocal이 이유를 알려 주고, 실행 시에는 메모리로 대체됩니다. 데이터베이스 열기를 참고하세요
연결되지 않았습니다 …: 데이터베이스에 이미 … 이름의 테이블 또는 뷰가 있습니다데이터베이스에 기억된 파일과 같은 이름의 테이블이나 뷰가 이미 있습니다. DuckLocal은 그것을 절대 바꾸지 않습니다. 둘 중 하나의 이름을 바꾸거나 삭제하거나, 로컬 파일에서 그 파일을 제거하고 다시 열어 새 이름을 받으세요
상대 경로를 복원할 수 없습니다 …파일이 상대 경로로 기억되어 새 세션에서는 해석할 수 없습니다. 로컬 파일에서 제거하고 다시 여세요
뷰가 sales 대신 sales_2로 표시됨다른 파일이나 테이블이 이미 그 이름을 쓰고 있어 새 뷰에 접미사가 붙었습니다
파일의 뷰가 오래된 내용을 보여 줌뷰는 쿼리할 때마다 파일을 읽습니다. CSV의 열 구성이 바뀌었다면 사이드바의 스키마 새로 고침을 사용하세요

데이터베이스 열기 ​

증상원인과 해결
데이터베이스가 더 새로운 DuckDB에서 만들어졌다는 메시지파일이 DuckLocal에 내장된 DuckDB가 읽을 수 있는 것보다 새로운 저장 형식을 사용합니다. 그 파일을 만든 DuckDB에서 메시지에 있는 ATTACH … COPY FROM DATABASE 줄을 실행한 뒤 복사본을 여세요. 데이터베이스가 열리지 않을 때를 참고하세요
데이터베이스가 DuckDB v0.9 이전에서 왔다는 메시지그 파일을 기록한 DuckDB에서 EXPORT DATABASE 'dir'를 실행한 다음 DuckLocal에서 IMPORT DATABASE 'dir'을 실행하세요
SQLite 데이터베이스라는 메시지열지 말고 **열기 → 데이터베이스 연결…**로 연결하세요
파일이 DuckDB 데이터베이스가 아니라는 메시지확장자가 DuckLocal이 데이터로 읽는 것이 아니어서 데이터베이스로 시도되었습니다. 지원되는 확장자를 붙이거나, 예를 들어 SELECT * FROM read_csv('export.dat')처럼 SQL로 읽으세요
DuckDB가 파일에 잠금을 설정할 수 없다고 함다른 프로그램 — 다른 DuckDB, 스크립트, 두 번째 앱 — 이 그 데이터베이스를 쓰기용으로 열고 있으며, DuckDB는 한 프로세스만 파일에 쓸 수 있습니다. 그쪽에서 닫은 다음 파일을 다시 여세요
DuckDB가 권한이 거부되었다고 함계정이 파일을 읽을 수 없거나 쓸 수 없습니다. 기본 데이터베이스는 쓰기용으로 열립니다. 파일 권한을 고치거나, 읽기 전용을 선택한 상태로 연결하세요
데이터베이스 열기가 실패했는데 아무것도 바뀌지 않음DuckLocal이 실행 중일 때는 정상입니다. 열기에 실패하면 이전 워크스페이스가 그대로 남습니다. 알림에서 이유를 확인하세요
상태 표시줄 툴팁에 **readable by DuckDB v1.x+**가 나오고 동료가 파일을 열 수 없음동료의 DuckDB가 그 버전보다 오래되었습니다. 동료가 업그레이드하거나, 더 오래된 STORAGE_VERSION으로 파일을 복사해야 합니다 — 어떤 DuckDB가 데이터베이스를 읽을 수 있는지를 참고하세요

연결된 데이터베이스 ​

증상원인과 해결
다시 실행한 뒤 연결된 데이터베이스가 사라짐실행 시점에 기억된 경로에 파일이 없어 건너뛰었습니다. 등록은 유지되므로 파일을 되돌려 놓으면 다음 연결 때 다시 나타납니다
이 데이터베이스는 이미 …(으)로 열려 있습니다그 파일이 이미 기본 데이터베이스이거나 그 이름으로 연결되어 있습니다. 그 이름으로 쿼리하세요
연결할 수 없습니다 …: … 이름은 열린 데이터베이스에서 이미 사용 중입니다.연결 안의 다른 무언가가 기억된 별칭을 이미 사용하고 있습니다. 예를 들어 SQL에서 같은 이름으로 연결한 데이터베이스입니다. 그것을 DETACH한 다음 데이터베이스를 다시 열거나 다시 실행하세요
연결된 데이터베이스에 쓰기가 실패함기본값인 읽기 전용으로 연결되었습니다. 사이드바에서 데이터베이스 연결 해제를 한 다음 읽기 전용을 선택 해제하고 다시 연결하세요
연결했더니 빈 데이터베이스가 만들어짐읽기 전용을 선택 해제한 상태에서는 존재하지 않는 DuckDB 경로가 생성됩니다. 연결을 해제하고 빈 파일을 삭제한 뒤 경로를 확인하세요
데이터베이스를 지정하지 않은 테이블 이름이 엉뚱한 테이블을 찾음데이터베이스 없이 쓴 이름은 기본 데이터베이스에서 해석됩니다. 데이터베이스를 오른쪽 클릭해 기본 데이터베이스로 사용을 선택하거나 alias.table처럼 쓰세요

Finder와 Quick Look ​

macOS에서만 해당됩니다.

증상원인과 해결
.parquet 또는 .duckdb 파일을 더블 클릭하면 다른 앱이 열림그 앱이 이미 기본값입니다. Finder에서 정보 가져오기 → 다음으로 열기로 DuckLocal을 선택한 다음 **모두 변경…**을 클릭하세요
CSV 또는 Excel 파일을 더블 클릭해도 DuckLocal이 열리지 않음의도된 동작입니다. DuckLocal은 이 형식을 가져오지 않습니다. 다음으로 열기 → DuckLocal을 사용하거나 파일을 Dock 아이콘에 놓으세요
다음으로 열기에 DuckLocal이 없거나 Space를 눌러도 DuckLocal 미리보기가 나오지 않음macOS가 아직 앱을 등록하지 않았습니다. 앱을 응용 프로그램으로 옮기고 한 번 실행하세요. 미리보기는 그다음 터미널에서 qlmanage -r을 실행하고, 시스템 설정의 확장 기능 설정에서 Quick Look 아래 DuckLocal Preview가 켜져 있는지 확인하세요
일반 .json 또는 Excel 파일에 DuckLocal 미리보기가 나오지 않음의도된 동작입니다. 그 형식은 macOS 자체 미리보기에 맡깁니다. .jsonl과 .ndjson 파일은 미리보기가 됩니다
미리보기에 50행만 나옴의도된 동작입니다. 미리보기는 파일 전체를 스캔하지 않습니다. 나머지는 DuckLocal에서 파일을 여세요
.duckdb 파일의 미리보기에 오류가 나옴미리보기는 DuckLocal 자체의 DuckDB로 파일을 읽으므로, 더 새로운 DuckDB의 파일은 거기서도 실패합니다. 데이터베이스 열기를 참고하세요

쿼리 실행 ​

증상원인과 해결
실행을 눌러도 아무 일도 없음이미 쿼리가 실행 중입니다. 실행 옆의 중지를 누르거나 **⌘.**로 중단하세요
쿼리가 Interrupted로 실패함실행 중에 누군가 중지(또는 ⌘.)를 눌렀습니다. 다시 실행하세요
SQL 일부에 빨간 물결 밑줄이 있음마지막 실행이 그 지점에서 실패했습니다. 쿼리 실패 메시지를 읽으세요. 표시는 다음 실행 때 사라집니다
**⌘↵**를 눌렀는데 실행되지 않고 에디터가 나옴첫 실행 화면에서 ⌘↵는 "에디터를 달라"는 뜻입니다. 한 번 더 누르면 실행됩니다
결과가 잘림 알림과 함께 일찍 끝남100,000행 또는 2,000,000셀 한도에 도달했습니다. 쿼리 범위를 좁히세요. 페이지 이동은 없습니다
타임스탬프가 밀려 보임그리드는 타임스탬프를 로컬 시간이 아니라 UTC로 표시합니다
TIMETZ 값에서 오프셋이 사라졌거나, BIT 또는 BIGNUM 값이 바이트처럼 보임그런 유형은 DuckLocal로 오는 과정에서 일반 값과 구분할 수 없습니다. SQL에서 CAST(column AS VARCHAR)로 실제 값을 확인하세요
정렬해도 미리보기 밖의 행이 나오지 않음헤더 정렬은 이미 불러온 행만 재배치합니다. 잘리기 전의 전체 결과를 정렬하려면 SQL에서 ORDER BY를 사용하세요
쿼리에 설치되지 않은 확장 기능이 필요함이제 빠진 확장 기능을 자동으로 내려받지 않습니다. 확장 기능 탭에서 직접 설치한 다음 로드하거나 쿼리를 다시 실행하세요
0.3.0 이전에 동작하던 쿼리가 확장 기능이 설치되지 않았다거나 함수가 없다고 함DuckLocal 0.3.0은 DuckDB 2.0을 실행하며, 설치된 확장 기능을 릴리스별로 관리합니다. 확장 기능 탭에서 다시 설치하세요 — 확장 기능을 참고하세요
minutes처럼 따옴표 없는 열 별칭이 파서 오류를 냄SQL 키워드이기 때문입니다. AS minutes라고 쓰거나 따옴표로 감싸세요: SELECT count(*) AS "minutes" FROM events
테이블이나 기록 항목을 클릭했더니 SQL이 사라짐그 클릭은 에디터 버퍼 전체를 바꿉니다. 임시 작업에는 새 쿼리 탭을 사용하세요
내보내기가 조용히 파일을 바꿔 버림내보내기는 묻지 않고 지정한 경로에 씁니다. 새 이름을 고르세요

S3 ​

증상원인과 해결
S3 자격 증명이 사라짐설계상 세션 동안에만 유지되며, 데이터베이스를 열거나 전환하면 지워집니다. S3을 다시 설정하세요
오프라인에서 S3 설정이 실패함첫 사용 시 INSTALL httpfs가 실행되며 확장 기능을 내려받습니다. 한 번 연결하면 캐시됩니다
임시(STS) 자격 증명이 거부됨세션 토큰을 보내지 않습니다. 수명이 긴 키를 사용하세요 — S3와 httpfs를 참고하세요
버킷이 실제보다 작아 보임목록은 단계마다 1,000개에서 멈춥니다. 대신 's3://bucket/prefix/*.parquet' 같은 글롭으로 쿼리하세요

대시보드 ​

증상원인과 해결
대시보드 차트가 쿼리가 읽기 전용이어야 한다고 함.dash 쿼리가 쓰기를 시도했습니다(DDL, DML, COPY, ATTACH 등). 대시보드는 읽기 전용 문만 실행하므로 준비 작업은 SQL 에디터로 옮기세요
에이전트가 내 주석을 보지 못함주석은 어디로도 전송되지 않습니다. 에이전트가 직접 읽어야 합니다. ducklocal comments FILE을 실행하게 하거나, 공식 스킬이 있다면 "FILE의 주석을 처리해 줘"라고 요청하세요
에이전트의 답변이나 수정이 보이지 않음창은 스펙과 FILE.comments.json을 1초 안에 따라갑니다. 더 이상 검증되지 않는 스펙은 마지막으로 동작한 대시보드를 그대로 두고 그 위에 이유를 표시합니다. 스펙 보기를 열어 파일을 확인하세요
대시보드의 PIVOT이 거부됨SELECT나 WITH 안에 중첩된 PIVOT은 값을 지정해야 합니다. PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue)처럼 나열하거나, 쿼리를 PIVOT으로 시작하세요

모양 ​

증상원인과 해결
실행할 때마다 테마가 밝게 초기화됨테마는 실행 사이에 저장되지 않습니다. 언어는 저장됩니다
텍스트나 아이콘이 너무 작거나 큼제목 표시줄의 Aa 버튼이나 ⌘+ / ⌘− / ⌘0을 사용하세요. 인터페이스 크기를 참고하세요
인터페이스 언어가 잘못됨제목 표시줄의 EN / 中 버튼을 사용하세요. 선택은 기억됩니다

처음부터 다시 시작 ​

기록, 기억된 파일, 열린 탭, 설정을 지우려면 DuckLocal을 종료하고 앱 데이터 디렉터리를 삭제하세요:

bash
rm -rf ~/Library/Application\ Support/DuckLocal

데이터 파일은 절대 건드리지 않습니다. DuckLocal 자체 기록만 제거됩니다. 그곳에 무엇이 저장되는지는 설정과 앱 데이터를 참고하세요.

Apache-2.0 라이선스로 공개되었습니다.