문서 검색

문서 검색 페이지는 내장된 레퍼런스 문서를 즉시 검색할 수 있는 작고 독립적인 웹 UI예요. ClickHouse HTTP 포트의 /docs 경로에서 제공돼요.

출처: 문서

본문

문서 검색 페이지는 내장된 레퍼런스 문서를 즉시 검색할 수 있는 작고 독립적인 웹 UI예요. ClickHouse HTTP 포트의 /docs 경로에서 제공돼요.

어떤 ClickHouse HTTP 포트의 /docs로 이동하면(예: http://localhost:8123/docs) 열 수 있어요.

무엇을 하는가 (What it does)

이 페이지는 입력할 때 system.documentation 테이블을 HTTP로 조회하고, 선택한 엔티티의 Markdown을 렌더링해요. system.documentation을 읽으므로 그 테이블이 노출하는 모든 엔티티 — 함수, 집계 함수, 테이블 함수, 테이블 엔진, 데이터베이스 엔진, 데이터 타입, 설정, 포맷, 압축 코덱, 프로파일 이벤트, 메트릭, 시스템 테이블 자체 등 — 를 다루며, 항상 실행 중인 서버에 내장된 문서와 일치해요.

검색 상자에 입력하면 일치 항목이 유형별 색상 코드 목록으로 나타나고, 일치 항목을 선택하면 그 문서가 렌더링돼요. 렌더링에는 다음이 포함돼요:

  • 엔티티 제목 옆의 연필 링크: system.documentation의 source 열에서 가져온, GitHub의 소스 파일을 엽니다.
  • /play UI와 같은 내장 렉서(Lexer.wasm)를 사용한 코드 블록의 ClickHouse SQL 구문 강조.
  • KaTeX를 통한 TeX 수식(예: corr 페이지의 수식).
  • :::note/:::tip/… 어드모니션, 공유 가능한 링크가 있는 제목 앵커, 코드 블록의 호버 "Copy" 버튼.
  • 상대 링크는 앱 내에 해당 문서 엔티티가 있으면 그쪽으로, 없으면 https://clickhouse.com/docs로 해석돼요. "Related"와 "Alias of" 참조는 앱 내 링크가 돼요.

현재 검색어, 열린 엔티티, 섹션은 URL 프래그먼트에 반영되므로 특정 페이지나 섹션을 직접 링크할 수 있고 브라우저의 뒤로/앞으로 탐색으로 복원돼요. 밝은/어두운 테마 전환기(자동 감지 포함)는 /play와 일치해요.

연결하기 (Connecting)

헤더에는 /play와 정확히 같은 URL, user, password 입력이 있어요. 페이지가 ClickHouse에서 제공될 때 URL은 현재 오리진으로 기본 설정되고, 페이지를 로컬 파일로 열면 http://localhost:8123/로 기본 설정돼요. 그래서 페이지를 원격 서버에 대해 로컬로 열 수도 있어요. 크로스 링크 이름 캐시는 연결이 바뀔 때 자동으로 다시 빌드돼요.

에셋 (Assets)

Markdown 렌더러(Marked), 수식 렌더러(KaTeX와 그 폰트), SQL 렉서를 포함한 모든 에셋은 페이지가 HTTP로 제공될 때 ClickHouse 바이너리 자체에서 제공돼요. ClickHouse HTTP 오리진에서는 서드파티 CDN이 로드되지 않으므로, 페이지는 자체 포함(self-contained)이고 오프라인에서 동작하며, 다루는 자격 증명과 함께 서드파티 네트워크 코드를 실행하지 않아요.

보안 고려 사항 (Security considerations)

이 페이지는 헤더에 입력된 자격 증명으로 ClickHouse HTTP 엔드포인트에 쿼리를 보내므로, HTTP 프로토콜에 적용되는 것과 같은 주의 사항이 여기에도 적용돼요:

  • 신뢰할 수 없는 환경에서는 자격 증명을 보호하기 위해 항상 HTTPS로 /docs를 제공하세요.
  • HTTP 프로토콜에 대한 접근을 제한하는 것과 같은 방식으로 네트워크 레벨(방화벽, 리버스 프록시 또는 listen_host 설정)에서 접근을 제한하세요.

system.documentation에는 서버에 내장된 정적 레퍼런스 문서만 들어 있으므로, 이 페이지는 여러분의 테이블에서 어떤 데이터도 노출하지 않아요.

더 알아보기 (Learn more)