Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Add server-backed documentation search to the Reference drawer

Đang mở
  • Có gì không ổn?
#420 3 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Ít trao đổi
Công nghệ
clickhouse, typescript
Lĩnh vực
databases, full-stack

Hướng nghiên cứu

Bắt đầu với child issue #421, issue này định nghĩa dịch vụ tìm kiếm tài liệu nhận biết capability và server/application contract của dịch vụ; sau đó đọc #422 về tương tác của Reference drawer và #423 về các tinh chỉnh xếp hạng. Sử dụng Reference drawer hiện có, tra cứu docEntry(target) và entry-rendering path làm các điểm vào được định danh. Được coi là hoàn tất khi cả ba child issue đều hoàn thành và các bất biến về compatibility, lifecycle, provenance và drawer được nêu trong umbrella được đáp ứng.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

enhancement

Product goal

Add server-backed documentation search to the existing persistent Reference drawer.

Search must describe the documentation and metadata exposed by the connected ClickHouse server so results remain version-exact, permission-aware, and usable without a remote web index.

The drawer remains non-modal and the editor remains usable while search results or documentation entries are open.

Core design decisions

  • Add a search input and submit button to the Reference drawer header.
  • Search is explicitly submitted; the first version does not query on every keystroke.
  • A valid search executes one capability-generated UNION ALL query over the usable documentation-bearing system tables.
  • Every query branch reports its actual physical source_table.
  • Query branches are generated only after table and column capabilities are confirmed for the active connection.
  • Heterogeneous rows normalize into the existing DocKind / DocTarget domain.
  • Duplicate logical entities from different physical sources merge while retaining source provenance.
  • Final relevance ranking is deterministic and performed in JavaScript.
  • Selecting a result uses the existing docEntry(target) lookup and entry-rendering path.
  • Search, caches, and UI responses are connection-generation-safe and protected from stale repaint.
  • Server payloads, snippets, result counts, cache size, and retries remain bounded.

Work breakdown

  • #421 — Build capability-aware documentation search service
  • #422 — Add documentation search UI to the Reference drawer
  • #423 — Improve documentation search ranking with match position and proximity

The child issues are the authoritative implementation specifications. Detailed SQL construction, interfaces, ranking weights, lifecycle mechanics, UI behavior, and test matrices belong there rather than in this umbrella issue.

Dependency order

  • #421 establishes the server/application search contract and baseline ranking.
  • #422 depends on #421 and adds the complete drawer interaction.
  • #423 depends on #421 and refines ranking and contextual snippets. It may be implemented independently of #422 once the service contract exists.

Completion definition

#420 closes only after all three child issues are complete.

#421 and #422 produce the functional search experience. #423 is also required before closing this umbrella because position, phrase, proximity, lexical-boundary ranking, and match-centered snippets are part of the agreed search-quality design.

Cross-cutting invariants

Capability and compatibility
  • Never reference an unavailable table or unconfirmed optional column.
  • Degrade safely across ClickHouse versions and partial permissions.
  • Capability state is scoped to the active connection and invalidated on reconnect/sign-out.
  • A stale table/column failure may trigger one bounded reprobe-and-retry attempt, never an unbounded source-removal loop.
Query and provenance
  • One submitted search produces one dynamic UNION ALL request.
  • Each branch emits its physical source table explicitly.
  • Search results preserve the distinction between physical source and logical documentation kind.
  • Search candidate retrieval is bounded; final merge and ranking are JavaScript-owned.
Safety and lifecycle
  • User input is bound or escaped through the existing SQL-safe seam.
  • Result summaries are rendered as text, never trusted HTML.
  • Full entries continue through the existing bounded safe Markdown pipeline.
  • Late responses from an older search, closed drawer, selected entry, reconnect, or sign-out cannot repaint current UI.
  • Search caches and in-flight deduplication are bounded and connection-generation-aware.
Drawer behavior
  • The Reference title and close control remain accessible.
  • Search results are keyboard reachable and screen-reader announced.
  • Selecting a result reuses existing documentation entry navigation.
  • Back restores the prior bounded search snapshot, selection, focus, and scroll when still valid.
  • Existing hover, completion, F1, alias, related-entry, disambiguation, Retry, resize, Escape, and focus-restoration behavior remains intact.

Non-goals

  • Remote search against clickhouse.com or another web index.
  • Semantic, vector, fuzzy edit-distance, or regular-expression search.
  • Search-as-you-type server requests in the first version.
  • Searching full examples in the initial candidate query.
  • Persisted cross-session search history.
  • A large kind-filter UI in the initial release.
  • Replacing the existing context-aware documentation entry and rendering flows.
Ngôn ngữ chính
TypeScript
Star
8
Fork
2
Merge trung bình
1 giờ 17 phút
Pull request đã merge (30 ngày)
3

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của Altinity/altinity-sql-browser

Tất cả issue của Altinity/altinity-sql-browser

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.