# SQL 편집기

> DuckLocal의 DuckDB SQL 편집기: 쿼리 탭, 서식, 인라인 오류, 스키마 기반 자동 완성, Explain 계획, 연산자별 프로파일링, 바로 가기 키.

Source: https://ducklocal.app/docs/ko/sql-editor

각 쿼리 탭은 자체 편집기 버퍼를 가집니다. 편집기는 tree-sitter로 실제 SQL을 강조하고,
2칸으로 들여쓰며, 줄 번호를 표시합니다.

## 탭

| 조작 | 하는 일 |
| --- | --- |
| `+` 또는 **⌘T** | 새 쿼리 탭을 추가하고 그 탭으로 포커스를 옮깁니다 |
| 탭 클릭 | 그 탭으로 전환합니다 |
| **Ctrl+Tab** / **Ctrl+Shift+Tab** | 다음 / 이전 탭 |
| **⌘1** … **⌘8**, **⌘9** | 첫 번째부터 여덟 번째 탭. ⌘9는 마지막 탭 |
| 탭 드래그 | 탭 스트립에서 옮깁니다 |
| `×`, **⌘W** 또는 가운데 클릭 | 탭을 닫습니다. 마지막 탭은 닫을 수 없습니다: 그 `×`는 숨겨지고 ⌘W는 아무것도 하지 않습니다. 저장하지 않은 편집이 있는 대시보드는 먼저 묻습니다 |
| 탭 마우스 오른쪽 클릭 | **탭 닫기**, **다른 탭 모두 닫기**, **오른쪽 탭 모두 닫기**. 저장하지 않은 편집이 있는 대시보드는 열린 채로 두며, 알림에 그 개수가 표시됩니다 |
| 탭 더블클릭 | 제목을 그 자리에서 편집합니다. Enter 또는 바깥 클릭으로 새 제목을 유지하고, Escape는 이전 제목을 유지합니다. 빈 제목은 `Query N`으로 돌아갑니다 |

열린 탭은 다음 실행 시 그 순서대로 돌아옵니다: 쿼리 탭은 제목과 편집기의 SQL(실행했는지
여부와 관계없이), 그리고 대시보드 탭입니다. 결과는 돌아오지 않습니다 — 쿼리를 다시
실행하세요. 새로 연 쿼리 탭은 `SELECT 'Hello, DuckLocal' AS greeting;`으로 시작합니다.

## 도구 모음

편집기 위, 왼쪽부터:

| 버튼 | 하는 일 |
| --- | --- |
| **실행** | 편집기의 SQL을 실행합니다 — [SQL 실행](#running-sql) 참고 |
| **중지** | 실행이 한동안 이어진 뒤에 표시되며, 그것을 중단합니다 |
| **서식** | SQL을 다시 서식화합니다 — [서식](#format) 참고 |
| **Explain** | 문을 실행하지 않고 DuckDB가 쓸 계획을 표시합니다 |
| **프로파일** | 쿼리를 실행하고 각 연산자의 비용을 표시합니다 |

**Explain**과 **프로파일**은
[Explain과 프로파일](#explain-and-profile)에서 설명합니다.

## SQL 실행 {#running-sql}

편집기에 포커스가 있는 상태에서 **⌘↵**(Cmd+Enter)를 누르거나 **실행** 버튼을 사용합니다.

쿼리가 실행 중일 때 다시 실행을 눌러도 아무 일도 없으며(Explain과 프로파일도 마찬가지),
쿼리가 한동안 실행되면 **실행** 옆에 **중지** 버튼이 나타납니다. **중지** 또는 **⌘.**로 쿼리를 중단합니다. 쿼리는
DuckDB의 `Interrupted` 오류로 끝나고, 다른 실패와 마찬가지로 기록에 남습니다. 타임아웃은
없습니다: 중지하지 않으면 쿼리는 DuckDB가 필요로 하는 만큼 실행되며, 다른 데이터베이스
작업은 그 뒤에서 대기합니다.

결과는 DuckDB에서 스트리밍되므로, 스캔은 그리드의
[행 수 제한](results-and-charts.md#row-limits)에 도달하면 파일의 나머지를 읽지 않고
멈춥니다. 첫 행 전에 모든 행을 봐야 하는 쿼리 — `ORDER BY`, `GROUP BY`, 집계, 윈도우
함수 — 는 여전히 전체를 계산합니다.

각 탭은 자체 결과를 가집니다. 탭을 전환한 뒤 도착한 결과는 그것을 실행한 탭에 들어갑니다.

문이 어떻게 처리되는지는 맨 앞 키워드로 결정됩니다. `SELECT`, `WITH`, `SHOW`, `DESCRIBE`,
`EXPLAIN`, `PRAGMA`, `SUMMARIZE`, `VALUES`, `FROM`, `TABLE`, `PIVOT`, `CALL`은 결과 집합을
만듭니다. 그 밖의 것 — DDL(데이터 정의)과 DML(데이터 수정) 문 — 은 그리드 대신
`Done: N rows affected, took …`를 보고합니다. 판단할 때 맨 앞 `--` 주석은 건너뛰지만,
블록 주석은 건너뛰지 않습니다.

### 스크립트

편집기는 여러 문을 담을 수 있습니다. **실행**은 모든 문을 순서대로, DuckDB 셸이 파일을
읽는 방식으로 실행하며, **첫 실패에서 멈춥니다** — 실패한 `ATTACH` 뒤에 `SELECT`를
실행하면 오해를 부르는 두 번째 오류만 더할 뿐입니다. 결과 위의 스트립에 문이 나열되고,
각각 행 수와 *완료*, *실패*, *실행 안 됨* 표시가 붙습니다. 하나를 클릭하면 그 결과를 볼 수
있습니다. 오류는 스크립트 전체가 아니라 실패한 문에 밑줄을 긋습니다.

셸의 점 명령 몇 가지도 각각 한 줄에 쓸 수 있습니다:

| 명령 | 표시 내용 |
| --- | --- |
| `.tables ?PATTERN?` | 테이블과 뷰. 선택적으로 `stat%` 같은 `ILIKE` 패턴으로 필터링 |
| `.schema ?PATTERN?` | 테이블과 뷰의 `CREATE` 문. 선택적으로 필터링 |
| `.databases` | 연결된 데이터베이스 |
| `.help` | 이 목록 |

그 밖의 점 명령(`.mode`, `.read`, …)은 동작하는 명령 이름을 알려 주는 오류입니다.

## 오류

실패한 문은 DuckDB 메시지를 그대로 담은 *쿼리 실패* 제목의 알림을 표시합니다. 메시지는
엔진에서 오며 인터페이스 언어와 관계없이 항상 영어입니다. 그리드에는 아무것도 쓰이지 않고,
시도는 실패 표시와 함께 [기록](schema-and-history.md)에 남습니다.

메시지가 위치를 가리키면 — 파서와 바인더 오류가 `LINE n:` 줄과 캐럿으로 그렇게 합니다 —
편집기는 그 지점에 빨간 물결 밑줄을 긋습니다: 캐럿이 가리키는 토큰, 또는 연속된 캐럿이
덮는 범위입니다. 표시는 편집을 따라가고 다음 실행에서 지워집니다. 런타임 오류는 위치가
없어 표시가 붙지 않습니다.

## 서식 {#format}

**서식**은 버퍼를 2칸 들여쓰기와 대문자 키워드로 `sqlformat`에 통과시킨 뒤 버퍼 전체를
바꿉니다. 빈 버퍼에서는 아무것도 하지 않습니다.

## Explain과 프로파일 {#explain-and-profile}

두 버튼 모두 편집기의 전체 텍스트에 동작하고, 둘 다 **정확히 하나의 문**만 받습니다. 둘
이상이거나 점 명령이 있으면
*Explain과 프로파일은 문 하나만 받습니다: 살펴볼 문을 전용 탭에 넣으세요.*라는 메시지로
거부합니다. 끝의 `;`와 끝의 주석은 괜찮습니다.

실행, Explain, 프로파일 중 하나가 바쁘면 나머지 둘은 아무것도 하지 않습니다. Explain과
프로파일은 [기록](schema-and-history.md#query-history)에 남지 않습니다. 그 출력은 **결과**
탭의 그리드를 대체하며, 다른 탭이 열려 있으면 그 탭으로 전환합니다. 실패하면 실행 실패와
마찬가지로 *쿼리 실패* 알림을 표시합니다.

### Explain

**Explain**은 `EXPLAIN <your statement>`를 실행하고 DuckDB의 계획을 걸린 시간과 함께
일반 고정폭 텍스트로 표시합니다. 계획만 세우므로 문은 실행되지 않아 `INSERT`, `UPDATE`,
`DELETE`를 Explain하는 것은 안전합니다.

### 프로파일

**프로파일**은 `EXPLAIN (ANALYZE, FORMAT JSON)` 아래에서 문을 실행하고, 실행된 계획을
트리로 표시합니다: 각 연산자 자체의 시간과 전체에서 차지하는 비중, 옵티마이저 추정치에
대한 실제 출력 행 수(10배 넘게 어긋나면 표시됨), 그리고 무엇을 필터링하고, 무엇으로
조인하고, 무엇을 투영했는지입니다. 가장 비용이 큰 연산자는 맨 위에 이름이 나오고 빨간색으로
그려집니다. 읽는 방법은
[Explain과 프로파일 출력](results-and-charts.md#explain-and-profile)을 참고하세요.

**프로파일링은 실제로 문을 실행합니다** — 그래야 연산자의 시간이 측정됩니다. 따라서
단일 읽기 전용 쿼리만 받습니다:

- **허용:** `SELECT`, `WITH … SELECT`, `FROM …`, `VALUES`, `TABLE`, `SHOW`, `DESCRIBE`,
  `SUMMARIZE`.
- **거부:** 쓰기를 하는 모든 것(`INSERT`, `UPDATE`, `DELETE`, `CREATE`, …), `CALL`,
  `PRAGMA`, `COPY`, `EXPLAIN` 자체, `WITH` 뒤에 숨은 쓰기(`WITH s AS (…) INSERT …`),
  명시적 `IN (…)` 목록이 없는 `PIVOT`.

거부된 문에는 *읽기만 하는 문만 프로파일할 수 있습니다(SELECT, WITH, FROM…): 프로파일링은
문을 실행합니다.*가 표시됩니다. 이를 결정하는 것은 첫 키워드가 아니라 DuckDB 자체 파서이며,
아무것도 실행되기 전에 판단합니다.

프로파일은 쿼리와 같은 시간에 측정 비용이 더해집니다. **중지**(또는 **⌘.**)로 실행과
마찬가지로 중단할 수 있습니다.

## 자동 완성

완성 메뉴는 카탈로그를 인식합니다. 후보의 순위는 다음과 같습니다:

1. 스키마의 테이블과 열(최대 35개 항목)
2. DuckDB 함수 이름
3. SQL 키워드

최대 50개 항목이 제시됩니다. 일치는 커서 바로 왼쪽 식별자에 대한 대소문자 구분 없는
**접두사** 일치이므로 `sel`은 `SELECT`로 완성되지만 `elect`는 아무것도 완성되지 않습니다.
함수는 이름과 여는 괄호를 삽입하고, 공백이나 특수 문자가 있는 식별자는 큰따옴표로 감싸
삽입합니다.

키워드와 함수 목록은 엄선된 부분 집합이라 모든 DuckDB 함수가 나타나지는 않습니다.

## 바로 가기 키

Windows와 Linux에서는 전체적으로 **⌘** 대신 **Ctrl**로 읽으세요.

DuckLocal 자체의 바로 가기 키는 모두 메뉴 막대에 나열되어 있습니다:

| 바로 가기 키 | 동작 |
| --- | --- |
| ⌘↵ | 쿼리 실행 |
| ⌘. | 실행 중인 쿼리 중지 |
| ⌘T | 새 쿼리 탭 |
| ⌘W | 탭 닫기 |
| Ctrl+Tab / Ctrl+Shift+Tab | 다음 / 이전 탭(Mac에서도 Ctrl) |
| ⌘1 … ⌘9 | 그 위치의 탭으로 이동. ⌘9는 마지막 |
| ⌘O | 데이터 열기 |
| ⌘S | 대시보드의 소스를 소스 뷰에서 저장 |
| ⌘B | 사이드바 숨기기 또는 표시 |
| ⌘+ / ⌘− / ⌘0 | 인터페이스를 크게 / 작게 / 기본 크기로 — [인터페이스 크기](settings-and-data.md#interface-size) 참고 |
| ⌘Q | 종료 |

편집기 자체의 바로 가기 키는 다른 텍스트 필드와 똑같이 동작합니다:

| 바로 가기 키 | 동작 |
| --- | --- |
| ⌘F / ⇧⌘F | 편집기에서 찾기 / 바꾸기 |
| ⌘Z / ⇧⌘Z | 실행 취소 / 다시 실행 |
| ⌘A | 모두 선택 |
| ⌘C / ⌘X / ⌘V | 복사 / 잘라내기 / 붙여넣기 |
| ⌥⌘↑ / ⌥⌘↓ | 위 / 아래에 커서 추가 |
| ⌘← / ⌘→ / ⌥← / ⌥→ | 줄 / 단어 단위로 이동 |
| ⌘↑ / ⌘↓ | 문서의 시작 / 끝으로 이동 |
| ⌘⌫ / ⌥⌫ | 줄 시작 / 이전 단어까지 삭제 |

## 메뉴

메뉴 막대에는 모든 창 명령이 바로 가기 키와 함께 있습니다:

| 메뉴 | 명령 |
| --- | --- |
| DuckLocal | 명령줄과 AI, 업데이트 확인…, 시작 시 업데이트 확인, 가이드 보기, 로그 폴더 열기, DuckLocal 종료 |
| 파일 | 새 쿼리, 데이터 열기, 저장, 탭 닫기, 다음 탭, 이전 탭 |
| 편집 | 실행 취소, 다시 실행, 잘라내기, 복사, 붙여넣기, 모두 선택 |
| 쿼리 | 실행, 중지 |
| 보기 | 사이드바 표시 또는 숨기기, 인터페이스 크게, 인터페이스 작게, 기본 크기, 온라인 베이스 맵(OpenStreetMap) |

Windows와 Linux에는 메뉴 막대가 없습니다. 그곳에서는 **가이드 보기**와
**로그 폴더 열기**가 상태 표시줄 오른쪽 끝 버전의 마우스 오른쪽 메뉴에 있습니다.

**온라인 베이스 맵(OpenStreetMap)**은 체크 항목입니다.
[차트](results-and-charts.md#charts)를 참고하세요. 스키마 사이드바의 행에도 마우스 오른쪽
메뉴가 있습니다. [스키마와 기록](schema-and-history.md#right-click-menu)을 참고하세요.
명령 팔레트는 없습니다.
