> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 내장 Web SQL UI(`/play`)의 노트북 모드에 대한 문서입니다. 노트북 모드는 탭을 쿼리 셀과 텍스트 셀로 이루어진 시퀀스로 바꿉니다

# Web UI 노트북 모드

내장 Web SQL UI(`play.html`, 모든 ClickHouse HTTP 포트의 [`/play`](/ko/concepts/features/interfaces/http) 경로에서 제공)에서는 탭을 노트북으로 전환할 수 있습니다. 노트북은 순서대로 배열된 셀의 시퀀스이며, 각 셀은 자체 결과를 가진 쿼리이거나 Markdown 텍스트 블록입니다. Jupyter, Observable, Hex, Deepnote와 같은 형태의 문서로, 용도도 같습니다. 즉, 연이은 쿼리와 그 사이의 추론 과정을 한 페이지에 함께 남겨 두기 위한 것입니다.

노트북 모드는 탭 단위로 적용됩니다. 한 탭은 노트북으로 사용하고 다른 탭은 일반 단일 쿼리 편집기로 유지할 수 있으며, 각 탭의 노트북은 페이지를 다시 로드해도 그대로 유지됩니다.

<h2 id="adding-cells">
  셀 추가
</h2>

탭은 쿼리 셀 하나로 시작하며, 겉보기에는 일반 편집기와 완전히 같습니다. 헤더도, 셀 테두리 같은 UI 요소도 없고, 노트북이라는 것이 드러나지도 않습니다. 쿼리 결과가 나오면 그 아래에 큰 `[+]` 버튼이 나타납니다. 이 버튼은 결과보다 눈에 띄지 않도록 일부러 흐리게 표시됩니다. 버튼을 클릭하면 추가할 수 있는 두 가지 셀 유형이 펼쳐집니다.

* **Query** — 새 쿼리 셀입니다. 추가되는 즉시 편집기 포커스를 가져오므로 바로 입력할 수 있습니다.
* **Text** — 새 Markdown 셀로, 편집 모드로 열립니다.

두 번째 셀을 추가하면 해당 탭에서 노트북 모드가 활성화됩니다.

<h2 id="cell-headers">
  셀 헤더
</h2>

셀이 두 개 이상이 되면 모든 셀에 `1. Query` 또는 `2. Text`처럼 셀의 위치와 종류를 나타내는 헤더가 표시됩니다. 쿼리 셀에는 실행이 진행되는 동안 상태 점이 표시되고, 실행에 실패하면 빨간색 점이 표시됩니다. 실행이 완료된 셀은 결과가 바로 아래에 나타나므로 별도의 표시가 없습니다.

헤더의 동작 버튼은 셀에 마우스를 올리거나 셀에 포커스가 있을 때 나타납니다.

| 동작 | 의미 |
| - | - |
| `▶` | 이 셀을 실행합니다(쿼리 셀만 해당) |
| `✎` | 이 셀을 편집합니다. 편집기를 이 셀로 가져오거나, 텍스트 셀을 다시 소스 보기로 전환합니다 |
| `＋` | 이 셀 앞에 새 셀을 삽입합니다. 이때 동일한 Query/Text 선택 항목이 해당 위치에 인라인으로 표시됩니다 |
| `↑` / `↓` | 셀을 위 또는 아래로 이동합니다 |
| `✕` | 셀을 삭제합니다 |

공유 편집기는 쿼리 셀에 위치하므로 탭에는 항상 쿼리 셀이 하나 이상 유지됩니다. 따라서 마지막으로 남은 쿼리 셀에서는 `✕`가 비활성화됩니다.

<h2 id="query-cells">
  쿼리 셀
</h2>

페이지에는 항상 쿼리 편집기가 하나만 존재합니다. 이 편집기는 구문 강조, 자동 완성, 쿼리 매개변수 입력을 모두 갖춘 전체 편집기입니다. 노트북 모드에서는 현재 활성 쿼리 셀에 편집기가 배치되며, 포커스가 있는 동안에만 표시됩니다. 포커스가 벗어나는 즉시 해당 셀도 접히므로, 노트북을 읽는 동안에는 열린 텍스트 영역이 전혀 보이지 않습니다. 접힌 쿼리를 클릭하면 편집기가 다시 표시됩니다(편집기가 다른 셀에 있었다면 해당 셀로 이동합니다). 쿼리 매개변수 입력이나 자동 완성 후보처럼 편집기 내부에서 포커스가 이동할 때는 편집기가 접히지 않습니다.

접힌 쿼리 셀은 쿼리를 한 줄로 표시합니다. 구문 강조가 적용되고, 연속된 공백(들여쓰기와 줄바꿈 포함)은 공백 하나로 줄어들며, 한 줄에 다 들어가지 않으면 뒷부분이 오른쪽으로 갈수록 흐리게 표시됩니다. 접힌 셀에는 자체 배경이 없으므로 별도의 입력 상자가 아니라 페이지의 일반 텍스트처럼 보입니다.

`Run` 버튼, 진행 상황 표시줄, 복사/다운로드 작업은 페이지 헤더를 떠나 편집 중인 쿼리 아래, 즉 쿼리와 그 결과 사이에 배치됩니다. 이 위치는 이 요소들이 나타내는 실행이 실제로 속한 곳이며, 해당 셀을 실행하는 방법이 한눈에 드러나는 곳입니다. 이 요소들은 편집기에 속하므로, 셀에 포커스가 들어오고 나감에 따라 편집기와 함께 나타나고 사라집니다.

노트북 모드에서는 결과가 더 간결하게 표시됩니다. 글꼴이 작아지고 셀 여백도 그에 맞게 줄어들며, 테이블 높이는 최대 뷰포트 높이의 4분의 1로 제한됩니다. 쿼리 편집기 크기를 조정할 때와 똑같이 결과의 아래쪽 가장자리를 드래그하여 공간을 늘리거나 줄일 수 있으며, 텍스트 셀의 Markdown 편집기에도 같은 조절 핸들이 있습니다. 테이블 자체가 세로와 가로 방향의 스크롤 컨테이너이므로 얇은 스크롤바가 테이블 가장자리에 표시됩니다. 따라서 길거나 넓은 결과가 노트북의 나머지 부분을 아래로 밀어내거나 넓히지 않으며, 스크롤하는 동안에도 컬럼 헤더가 테이블 상단에 고정됩니다. 이처럼 헤더가 테이블 맨 위에 있기 때문에, 컬럼 타입은 페이지 스크롤 테이블처럼 헤더 위가 아니라 헤더 바로 아래, 첫 몇 행 위에 겹쳐 표시됩니다.

실행 방식은 이전과 같습니다. `Ctrl/Cmd+Enter`(또는 `Run` 버튼)를 누르면 편집기에 있는 쿼리, 즉 활성 셀이 실행됩니다. 탭마다 한 번에 하나의 쿼리만 실행됩니다. 같은 탭의 다른 셀에서 실행을 시작하거나 `Stop`을 누르면 이전 실행이 종료됩니다.

`Logs` 및 `Metrics` 뷰와 진행 상황 표시줄의 리소스 측정값은 해당 결과를 만든 셀에 속합니다. 각 셀은 자체 선택 상태와 측정값을 유지하며, 공유 토글에는 활성 셀이 생성한 내용이 표시됩니다. 셀을 전환하면 그 셀의 로그, 메트릭, 측정값이 다시 표시됩니다. 쿼리가 실행되는 동안에는 진행 상황 표시줄이 실행 중인 셀에 그대로 남아 있습니다. 다음 쿼리를 작성하려고 편집기를 다른 셀로 옮기더라도 실시간 진행 상황이 사라지거나 토글이 다른 셀의 결과로 바뀌지 않습니다.

컬럼 색상 지정, 고정 컬럼, 그리고 [결과 구조](/ko/concepts/features/interfaces/web-ui-result-shaping)(정렬, 필터, 페이지)도 셀에 속합니다. 이 설정들은 결과에서 선택하므로 해당 결과를 따라갑니다. 셀 결과를 정렬하거나 필터링하면 해당 셀이 다시 실행되며, 편집기가 다른 셀에 있었다면 먼저 편집기를 해당 셀로 가져옵니다. `Run all`로 여러 테이블을 생성한 셀에서는 모든 테이블이 하나의 설정을 공유하며, 셀마다 각자의 설정을 유지합니다. 공유 링크와 브라우저 이력에는 활성 셀의 설정이 담기고, 다른 셀의 설정은 각 셀에 그대로 유지됩니다.

<h2 id="text-cells">
  텍스트 셀
</h2>

텍스트 셀에는 Markdown을 작성합니다. 편집 중에는 텍스트 영역에 마커가 강조 표시된 소스가 그대로 나타납니다. 제목, 강조, 코드 스팬, 링크, 목록 글머리 기호, 인용 블록은 색상으로만 구분되고 렌더링되어 사라지지 않으므로, 편집하는 대상은 항상 소스입니다. 텍스트 영역은 내용에 맞춰 늘어납니다.

텍스트 영역을 벗어나면(다른 곳을 클릭하거나 `Escape` 또는 `Ctrl/Cmd+Enter`를 누르면) 편집이 끝나고 텍스트 영역이 렌더링된 Markdown으로 대체됩니다. 렌더링된 텍스트를 클릭하면 다시 편집 상태로 돌아갑니다.

텍스트 셀은 편집 상태와 렌더링 상태 모두에서 쿼리와 동일한 고정폭 글꼴로 표시됩니다. 따라서 노트북 전체가 하나의 문서처럼 읽히고, 셀이 소스와 렌더링 결과 사이를 오갈 때 글꼴이 바뀌지 않습니다.

제목, 강조, 인라인 코드와 펜스 코드 블록, 링크와 이미지, 자동 링크된 URL, 순서 있는 목록과 순서 없는 목록, 인용 블록, 가로 구분선, 파이프 테이블을 지원합니다. 텍스트 셀의 원시 HTML은 렌더링되지 않고 이스케이프 처리되며, 링크 및 이미지 URL은 `http`, `https`, `mailto` 및 상대 경로로만 제한됩니다. `[guide](guide.md)`나 `![pic](images/pic.png)` 같은 일반적인 상대 링크는 정상적으로 동작하지만, `javascript:`나 `data:` 같은 스킴과 프로토콜 상대 경로인 `//host/...`(상대 경로가 아니라 다른 출처(origin)를 가리킵니다)는 일반 텍스트로 남습니다.

<h2 id="persistence">
  영속화
</h2>

탭의 노트북 전체(모든 셀과 그 내용, 작은 결과 스냅샷)는 워크스페이스의 나머지 데이터와 함께 IndexedDB에 저장되며, 다시 로드하면 복원됩니다. 이때 [Web SQL UI](/ko/concepts/features/interfaces/web-sql)에서 설명한 것과 동일한 최선 노력(best-effort) 방식과 결과 크기 제한이 적용됩니다.

URL과 브라우저 이력은 활성(ACTIVE) 셀을 기준으로 합니다. `#` 프래그먼트에는 해당 셀의 쿼리가 담기며, 뒤로 가기와 앞으로 가기로 방문했던 셀(및 탭) 사이를 이동할 수 있습니다. 노트북의 URL을 공유하면 노트북 전체가 아니라 활성 셀의 쿼리만 공유됩니다.

탭을 복제하면 결과를 제외한 노트북 전체가 복제됩니다.

탭을 Markdown으로 저장하면(탭 표시줄의 저장 버튼) 노트북의 모든 셀이 순서대로 기록됩니다. 각 쿼리 셀은 펜스 코드 블록으로 기록되고 그 뒤에 매개변수와 결과 테이블이 이어지며, 각 텍스트 셀은 `markdown` 정보 문자열이 지정된 펜스 코드 블록으로 기록됩니다. 이렇게 저장한 문서를 불러오면 모든 탭이 각자의 셀을 모두 포함한 채 복원됩니다. 단, 결과는 복원되지 않으므로 불러온 쿼리 셀은 실행되지 않은 상태로 시작됩니다.