# 스키마 브라우저와 기록

> DuckLocal의 스키마 사이드바에서 데이터베이스, 테이블, 열을 살펴보고, SELECT 쿼리를 생성하고, DuckDB 확장 기능을 관리하고, 지난 쿼리를 다시 사용하는 방법입니다.

Source: https://ducklocal.app/docs/ko/schema-and-history

사이드바에는 **스키마**, **기록**, **확장 기능** 세 개의 탭이 있습니다(중국어에서는
**表结构**, **查询历史**, **扩展**). 제목 표시줄 왼쪽의 버튼이나 **⌘B**로 사이드바를
숨기고 다시 표시할 수 있으며, 버튼은 어느 상태에서든 같은 자리에 있습니다.
사이드바를 숨겼는지 여부는 기억됩니다.

## 스키마 트리

트리는 위에서 아래로 **로컬 파일**, **대시보드**, **지표**, **S3**를 작은 회색 섹션 제목으로 보여 주고, 그 아래에 데이터베이스를 굵은 행으로 표시합니다:

- **로컬 파일** — 등록한 데이터 파일입니다. 각각 뷰 이름으로 표시되고 행 수가 함께
  나옵니다. 하위 항목은 그 뷰의 열입니다.
  - 뷰 이름과 파일 이름이 다를 때만 뷰 이름 옆에 파일 이름이 표시됩니다
    (`sales.csv`의 `sales_2`).
  - 두 파일이 같은 뷰 이름을 쓰면 폴더가 표시됩니다.
  - 행 위에 마우스를 올리면 전체 경로가 표시됩니다.
- **대시보드** — 최근에 연 `.dash` 대시보드입니다. 이름순으로 정렬되므로 클릭해도
  행 위치가 그대로입니다.
  - 클릭하면 파일처럼 탭으로 다시 열립니다.
  - 이름이 같은 대시보드가 둘이면 옆에 폴더가 표시됩니다. 같은 파일에 두 가지
    경로 표기(`E:\Proj`와 `E:\proj`, 또는 상대 경로와 절대 경로)로 도달한 경우는
    하나의 항목이며 탭도 하나만 열립니다.
  - 마우스를 올렸을 때 나오는 ×를 누르면 목록에서 빠지며, 파일과 열려 있는 탭은
    그대로입니다.
  - 경로가 더 이상 존재하지 않는 항목은 목록에서 제거됩니다.
- **지표** — 이 대시보드 옆에 `model.ossie.yaml`이 있으면 나타납니다. 지표마다 한 행이며, 클릭하면 쿼리 에디터로 컴파일되어 실행됩니다. [시맨틱 지표](metrics.md#sidebar)를 참고하세요. 0.4.1보다 새로운 기능입니다.
- **S3** — [S3를 설정](s3.md)하면 나타납니다. 지연 로딩합니다.
- 데이터베이스, 그다음 스키마, 그다음 테이블과 뷰, 그다음 열 순서입니다. 창을 열
  때의 데이터베이스가 먼저 오고, [그 옆에 연결](data-sources.md#attached-databases)한
  데이터베이스가 뒤따르며, 그렇게 연결한 경우 `read-only`로 표시됩니다.

테이블에는 추정 행 수가 표시되지만 뷰에는 표시되지 않습니다. 열 항목에는 DuckDB 데이터 형식이 표시됩니다. 시스템 데이터베이스와 `information_schema`, `pg_catalog`, `system` 스키마는 숨겨집니다.

트리 위의 검색 상자(**테이블과 열 검색**)는 이름에 입력한 내용이 들어 있는 행(대소문자 무시)과 그 위의 행만 남깁니다. 이름이 일치하는 테이블은 모든 열을 유지하고, 일치하는 열 때문에 남은 테이블은 그 열이 보이도록 펼쳐집니다. 상자를 비우면 트리 전체가 돌아옵니다.

### 데이터베이스 {#databases}

열려 있는 데이터베이스가 먼저 오고, 그다음 각
[연결된 데이터베이스](data-sources.md#attached-databases)가 이름 옆에 테이블 수와 함께 별도 그룹으로 표시됩니다.

- 연결된 데이터베이스는 비어 있어도 표시됩니다. 열려 있는 데이터베이스는 테이블이
  없는 동안 표시되지 않으며, 새 인메모리 세션은 이 상태로 시작합니다.
- 이름 옆의 흐린 힌트에 **read-only**가 표시되고, DuckDB가 아니면 파일 형식
  (**sqlite**)도 표시됩니다.
- 이름 위에 마우스를 올리면 데이터베이스 파일의 경로가 표시됩니다.

데이터베이스를 오른쪽 클릭하면 기본 데이터베이스로 만들거나 분리할 수 있습니다.
[오른쪽 클릭 메뉴](#right-click-menu)를 참고하세요.

탭 옆의 새로 고침 버튼(**스키마 새로 고침**)은 카탈로그와 등록된 파일 목록을 다시 불러옵니다.

## SELECT 생성

아래 클릭은 모두 활성 탭의 **버퍼 전체를 바꿉니다**. 커서 위치에 삽입하지 않습니다.
기록 항목을 클릭할 때도 마찬가지입니다. 중요한 내용은 먼저 저장하세요.

클릭하면 활성 편집기에 입력되는 내용:

| 클릭 | 생성되는 SQL |
| --- | --- |
| 테이블의 재생 버튼 | `SELECT * FROM db.schema.table LIMIT 100;` |
| 열의 확인란, 또는 열 이름 | `SELECT col FROM db.schema.table LIMIT 100;` |
| 같은 테이블의 열을 더 선택 | `SELECT a, b FROM db.schema.table LIMIT 100;` |
| 데이터 파일인 S3 객체 | `SELECT * FROM 's3://bucket/key' LIMIT 100;` |

테이블, 뷰, 로컬 파일의 각 열에는 확인란이 있습니다. 열을 체크하거나 이름을
클릭하면(체크됩니다) 체크한 열로 `SELECT`를 만듭니다. 순서는 체크한 순서가 아니라
테이블의 열 순서입니다. 마지막 체크를 풀면 `SELECT *`가 됩니다. 체크는 한 테이블에
속합니다. 다른 테이블의 열을 체크하면 거기서 처음부터 다시 시작합니다.

생성되는 SQL은 세 줄입니다(`SELECT …`, `FROM …`, `LIMIT 100;`). 테이블 이름은
현재 기본 데이터베이스와 스키마가 허용하는 만큼 짧게 씁니다: 기본 스키마의
테이블은 `orders`, 같은 데이터베이스의 다른 스키마는 `main.orders`, 그 밖의 경우는
`database.schema.table`입니다. `snap`에서 **기본 데이터베이스로 사용**을 실행하면
그 테이블의 미리보기는 `FROM orders`가 됩니다. 첫 쿼리가 실행되기 전까지는 이름이
완전히 한정됩니다.

이름에 영문자, 숫자, 밑줄 외의 문자가 들어 있을 때만 큰따옴표로 묶습니다.

## 오른쪽 클릭 메뉴 {#right-click-menu}

행의 마우스 오버 버튼이 제공하는 모든 명령은 오른쪽 클릭 메뉴에도 있으므로 마우스를 올리지 않고도 명령을 찾을 수 있습니다:

| 행 | 메뉴 |
| --- | --- |
| 테이블 또는 뷰 | SELECT 쿼리 생성, 열 개요, 이름 복사, 테이블 정보 복사 |
| 열 | SELECT 쿼리 생성, 이름 복사, 데이터 형식 변경…(테이블 열만) |
| 연결된 데이터베이스 | 기본 데이터베이스로 사용, 데이터베이스 분리 |
| S3 버킷 목록 | 버킷 새로 고침 |
| 최근 대시보드 | 목록에서 제거 |
| 로컬 파일 | SELECT 쿼리 생성, 열 개요, 이름 복사, 테이블 정보 복사, 로컬 파일에서 제거 |

**이름 복사**는 이름 자체(테이블, 열, 뷰 이름만)를 복사합니다. 데이터베이스와
스키마로 한정하지 않고 따옴표도 붙이지 않습니다.

**테이블 정보 복사**는 테이블 전체를 Markdown으로 복사하며, 채팅, 이슈, AI
에이전트 프롬프트에 바로 붙여 넣을 수 있습니다. 쿼리에서 쓰는 이름, 무엇인지,
크기, 그리고 모든 열과 그 형식이 들어갑니다:

```md
memory.main.orders (table, ~224 rows, 3 columns)

| column | type |
|---|---|
| date | DATE |
| channel | VARCHAR |
| revenue | DOUBLE |
```

**열 개요**는 활성 편집기의 텍스트를 `FROM <table>;`로 바꿔 실행하고, 결과 패널의
**개요** 탭을 엽니다. 테이블 전체의 모든 열을 한 번에 요약합니다: NULL, 서로 다른
값의 수, 범위, 값의 작은 차트입니다. [열 개요](results-and-charts.md#overview)를 참고하세요.

**기본 데이터베이스로 사용**은 그 데이터베이스에서 `USE`를 실행하므로, 데이터베이스를
지정하지 않은 테이블 이름이 그곳에서 해석되고 생성되는 쿼리가 짧아집니다(위 참고).
이미 기본인 데이터베이스에서는 제공되지 않습니다.

**데이터베이스 분리**는 연결된 데이터베이스를 분리하고 잊으므로 다음에 다시 연결되지
않습니다. 기본 데이터베이스였다면 세션이 먼저 다른 데이터베이스로 옮겨집니다. 파일은
건드리지 않습니다. 열려 있는 데이터베이스 자체는 분리할 수 없으므로 그 메뉴에 이
항목이 없습니다. 자세한 내용은
[연결된 데이터베이스](data-sources.md#attached-databases)를 참고하세요.

## 열 형식 변경

열 행에는 형식 작업이 있습니다(뷰 열에는 없으므로 연결된 CSV와 Parquet 열은 형식을
바꿀 수 없습니다). 이 작업을 선택하면 현재 형식이 미리 채워진 자유 입력 대화 상자가
열리고 다음이 실행됩니다:

```sql
ALTER TABLE db.schema.table ALTER COLUMN col SET DATA TYPE <what you typed>
```

여기서는 테이블 이름이 항상 완전히 한정되고, 열 이름은 필요한 경우에만 따옴표로
묶입니다.

선택 목록도 검증 목록도 없습니다. `DECIMAL(10,2)`처럼 매개변수가 있는 형식을 포함해
어떤 DuckDB 형식 문자열이든 됩니다. 잘못된 형식은 오류 알림으로 돌아옵니다. 성공하면
카탈로그가 다시 로드됩니다.

열 이름 바꾸기와 삭제, 열 주석 편집은 제공되지 않습니다.

## 등록된 파일 제거

파일 행의 **×**는 확인을 요청한 뒤 뷰를 삭제하고 등록을 잊습니다. **디스크의 파일은
건드리지 않습니다.**

여러 등록을 한꺼번에 제거하려면 **로컬 파일** 아래에서 해당 행을 선택합니다:

- macOS에서는 **⌘-클릭**, Windows/Linux에서는 **Ctrl-클릭**으로 선택에 파일 하나를 추가하거나 제거합니다.
- **Shift-클릭**은 연속된 범위를 선택합니다.
- 선택한 파일의 **×**를 클릭하거나 오른쪽 클릭 제거 작업을 사용하면 선택한 등록을 제거할지 확인합니다. 메뉴에 제거될 파일 수가 표시됩니다.

이렇게 하면 뷰와 등록이 제거되고 원본 파일은 디스크에 남습니다. 이 방법으로 파일을 선택해도 데이터베이스 테이블이나 대시보드 필터는 선택되지 않습니다.

## 확장 기능 {#extensions}

**확장 기능** 탭에는 엔진이 아는 모든 DuckDB 확장 기능이 나열됩니다. 로드된 것,
설치된 것, 나머지 순서로, 각 그룹은 이름순입니다.

각 행에 표시되는 내용:

- 확장 기능의 이름과 상태 태그: **로드됨**, **설치됨**, **설치 안 됨**
- DuckDB가 제공하는 한 줄 설명
- 버전과 출처: **내장**, 또는 설치한 저장소(`core`, `community`, 또는 URL)

상태의 의미:

| 상태 | 의미 |
| --- | --- |
| 로드됨 | 현재 연결에서 활성입니다. 함수, 리더, 형식이 지금 쿼리에서 동작합니다 |
| 설치됨 | 이 컴퓨터에 내려받았지만 이 연결에서는 로드되지 않았습니다 |
| 설치 안 됨 | DuckDB는 알고 있지만 아직 이 컴퓨터에 없습니다 |

**내장** 확장 기능은 DuckLocal에 컴파일되어 있으며, `parquet`과 `json`이 여기에
속하고 둘 다 처음부터 로드됩니다. 설치하거나 업데이트하지 않습니다.

커뮤니티 확장 기능도 같은 방식으로 설치합니다. 0.4.1부터 이 탭은 DuckDB의 코어
저장소뿐 아니라 커뮤니티 저장소에도 접근하므로, `mssql`(SQL Server) 같은 확장
기능을 앱을 떠나지 않고 설치하고 로드할 수 있으며, 그 행의 저장소 태그는
`community`로 표시됩니다.

각 행에는 해당하는 작업이 표시됩니다:

| 버튼 | 표시 조건 | 실행 |
| --- | --- | --- |
| **설치** | 설치 안 됨 | `INSTALL name` |
| **로드** | 설치됨, 로드되지 않음 | `LOAD name` |
| **업데이트** | 저장소에서 설치됨 | `UPDATE EXTENSIONS (name)` |

- **설치**와 **업데이트**는 DuckDB 확장 기능 저장소에서 내려받으므로 네트워크가
  필요합니다. **로드**는 설치된 파일을 읽을 뿐이라 네트워크가 필요하지 않습니다.
- 설치해도 로드되지는 않습니다. 그 뒤에 **로드**를 클릭하거나 `LOAD name`을
  실행하세요.
- 설치한 확장 기능은 설치된 채로 남습니다. DuckDB 자체 확장 기능 폴더에 있는
  디스크상의 파일이기 때문입니다. 로드는 현재 연결 동안만 유지됩니다.
- 그 폴더는 DuckDB 릴리스마다 다릅니다(`~/.duckdb/extensions/v2.0.0/…`). 업데이트로
  DuckLocal이 새 DuckDB 릴리스로 옮겨 가면(0.3.0이 DuckDB 2.0으로 옮겨 갔을 때처럼)
  쓰던 확장 기능은 다시 설치할 때까지 **설치 안 됨**으로 표시됩니다.
- 작업은 한 번에 하나만 실행되고, 그동안 다른 버튼은 비활성화됩니다. 알림에
  *설치했습니다 …*, *로드했습니다 …*, *업데이트했습니다 …* 중 하나, 또는 실패한
  이유가 표시됩니다.
- 로드나 업데이트 후에는 스키마 트리가 다시 로드됩니다. 확장 기능이 테이블과 함수를
  함께 가져올 수 있기 때문입니다.

목록은 탭을 열 때마다, 각 작업 후에, 탭이 열려 있는 동안 연결이 바뀔 때, 그리고
탭 옆의 새로 고침 버튼(**확장 기능 새로 고침**)을 클릭할 때 `duckdb_extensions()`에서
읽습니다. 따라서 다른 방법으로 로드된 확장 기능(쿼리 탭에서 입력한 `LOAD`, 또는
DuckDB 자체 로드)도 표시됩니다.

v0.2.1부터는 쿼리에 필요한 확장 기능이 없을 때 창도 CLI도 자동으로 내려받지 않습니다. **확장 기능**에서 명시적으로 설치하거나 `INSTALL name`을 실행하세요. 이 컴퓨터에 이미 설치된 확장 기능은 예전처럼 자동으로 로드될 수 있습니다.

### DuckDB UI 열기 {#duckdb-ui}

[DuckDB UI](https://duckdb.org/2025/03/12/duckdb-ui)는 MotherDuck이 만든 DuckDB 자체의
브라우저 노트북으로, 다른 확장 기능과 같은 방식이라 DuckLocal 안에서도 실행됩니다:

1. **확장 기능** 탭에서 `ui` 행의 **설치**를 클릭한 다음 **로드**를 클릭합니다.
2. 쿼리 탭에서 실행합니다:

   ```sql
   CALL start_ui();
   ```

   브라우저가 `http://localhost:4213`에서 UI를 엽니다. 브라우저를 열지 않고 서버만
   시작하려면 `CALL start_ui_server();`를 실행하세요.

![ui 확장 기능을 로드한 확장 기능 탭](../assets/duckdb-ui.png)

UI는 시작된 DuckDB 인스턴스(여기서는 DuckLocal의 것)에서 실행됩니다. 몇 가지 알아둘 점:

- **네트워크가 필요합니다.** `ui` 설치는 다른 확장 기능처럼 내려받기를 합니다. 또
  시작할 때마다 확장 기능의 로컬 서버가 `https://ui.duckdb.org`에서 UI 자체 파일을
  가져옵니다. 쿼리와 데이터는 여전히 로컬에서 실행됩니다.
- **DuckLocal이 종료될 때까지 유지됩니다.** DuckLocal을 종료하면 DuckDB 인스턴스가
  닫히고 서버도 함께 종료됩니다. `CALL stop_ui_server();`로 더 일찍 멈출 수 있습니다.
- **노트북은 DuckLocal이 아니라 확장 기능이 저장합니다.** `~/.duckdb/extension_data/ui/`에
  저장됩니다. DuckLocal의 쿼리 기록에는 UI에서 실행한 내용이 포함되지 않습니다.
- **읽기 전용 데이터베이스에서는 직접 실행할 수 없습니다.** 대신 노트북에서
  `ATTACH '…' (READ_ONLY)`로 그 데이터베이스를 연결하세요.

[DuckDB UI와 DuckLocal 비교](https://ducklocal.app/blog/duckdb-ui-vs-ducklocal/)는 둘을 비교하고
각각 언제 쓰면 좋은지 다룹니다.

## 쿼리 기록 {#query-history}

모든 실행이 성공과 실패 모두 기록되며, 로컬 시간 타임스탬프, 밀리초 단위 실행 시간,
행 수(DML이면 영향받은 행 수), 실패한 경우 오류 텍스트가 포함됩니다. 실패한 항목은
빨간색에 *실패* 태그로 표시됩니다.

목록에는 최신 **200**개가 표시됩니다. 행을 클릭하면 활성 편집기가 그 SQL로 채워지고
포커스가 이동하며, 있던 내용은 바뀝니다.

보존 정책도 정리 작업도 없습니다. 기록 테이블은 무한히 커지고 UI는 최근 200개만 보여
줍니다. 검색도, 필터도, 내보내기도 없고 인터페이스에서 항목을 삭제할 방법도 없습니다.

기록은 열려 있는 데이터베이스가 아니라 DuckLocal 자체 데이터베이스 파일에 저장되므로
데이터베이스를 바꾸거나 작업 공간을 잃어도 남습니다. 저장 위치는
[설정과 앱 데이터](settings-and-data.md)를 참고하세요.
