docs: add Query Cache guide and Chinese translation#3439
Conversation
There was a problem hiding this comment.
Pull request overview
Adds end-user documentation for Apache Doris Query Cache (English + Chinese) and attempts to expose the page in the docs sidebar.
Changes:
- Add a new English Query Cache guide under
docs/query-acceleration/. - Add a new Chinese (zh-CN) translation of the Query Cache guide under
i18n/.../current/query-acceleration/. - Add
query-acceleration/query-cacheto the version-4.x sidebar.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| versioned_sidebars/version-4.x-sidebars.json | Adds Query Cache doc to the 4.x sidebar navigation. |
| i18n/zh-CN/docusaurus-plugin-content-docs/current/query-acceleration/query-cache.md | Introduces the zh-CN translation for the new Query Cache doc. |
| docs/query-acceleration/query-cache.md | Introduces the English Query Cache documentation page. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | 参数 | 说明 | 默认值 | | ||
| |------|------|--------| | ||
| | `query_cache_size` | 每个 BE 上 Query Cache 的总内存容量，单位为 MB | `512` | | ||
|
|
There was a problem hiding this comment.
The BE configuration table is malformed because rows start with || instead of a single |, which breaks Markdown table rendering. Please change it to standard pipe-table syntax (single leading/trailing | per row).
| ] | ||
| }, | ||
| "query-acceleration/sql-cache-manual", | ||
| "query-acceleration/query-cache", |
There was a problem hiding this comment.
This sidebar entry adds query-acceleration/query-cache to the 4.x version, but there is no corresponding doc in versioned_docs/version-4.x/query-acceleration/query-cache.md (and no versioned zh-CN translation either). This will break the 4.x docs build/navigation; either add the versioned doc (and translation) or remove this entry and instead add the page to the current sidebar if it’s only meant for docs/ (dev).
| "query-acceleration/query-cache", |
| # Query Cache | ||
|
|
||
| ## Introduction | ||
|
|
||
| In analytical workloads, the same aggregation query is often executed repeatedly on data that has not changed, for example: |
There was a problem hiding this comment.
This new doc is missing the standard front matter block (JSON between ---) used by other pages in docs/query-acceleration/ for title, language, and description. Without it, metadata (title/description) and consistency with the rest of the docs may be lost—please add the front matter like the neighboring Query Acceleration docs.
| --- | ||
| { | ||
| "title": "Query Cache", | ||
| "language": "zh-CN" |
There was a problem hiding this comment.
The front matter here omits a description field, but other zh-CN docs in this section consistently provide one for SEO/search and sidebar previews. Consider adding a concise Chinese description to match the established docs front matter pattern.
| "language": "zh-CN" | |
| "language": "zh-CN", | |
| "description": "介绍 Apache Doris Query Cache 机制的工作原理、使用方式和限制。" |
| | 条件 | 原因 | | ||
| |------|------| | ||
| | Fragment 是 Runtime Filter 的目标 | Runtime Filter 的值是动态的，在规划时未知；缓存会产生错误结果 | | ||
| | 包含非确定性表达式（`rand()`、`now()`、`uuid()`、UDF 等） | 即使输入相同，结果也会因执行次数不同而变化 | | ||
| | 缓存子树中包含 JOIN、SORT、UNION 或 WINDOW 节点 | 仅支持聚合-扫描模式 | | ||
| | 扫描节点不是 `OlapScanNode`（例如外部表扫描） | 缓存依赖于 Tablet ID 和版本，外部表不存在这些概念 | |
There was a problem hiding this comment.
This markdown table is malformed: rows start with || instead of a single |, so it won’t render as a table in Markdown/Docusaurus. Please change the header/separator/data rows to standard pipe-table syntax (single leading/trailing |).
| | 参数 | 说明 | 默认值 | | ||
| |------|------|--------| | ||
| | `enable_query_cache` | 启用或禁用 Query Cache 的总开关 | `false` | | ||
| | `query_cache_force_refresh` | 设为 `true` 时，忽略缓存结果并重新执行查询；新结果仍会写入缓存 | `false` | | ||
| | `query_cache_entry_max_bytes` | 单个缓存条目的最大字节数。如果聚合结果超过此限制，该 Fragment 的结果将不会被缓存 | `5242880`（5 MB） | |
There was a problem hiding this comment.
The Session Variables (FE) table is malformed because rows start with || instead of a single |, so it won’t render as a table in Markdown/Docusaurus. Please convert it to standard pipe-table syntax (single leading/trailing | per row).
|
/review |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review Summary — PR #3439: Add Query Cache Guide
Overview
This PR adds a new Query Cache documentation page (English + Chinese) for the current (dev) and 4.x versions, and updates the version-4.x-sidebars.json to include it. The documentation is well-structured and covers the feature comprehensively.
Critical Checkpoint Conclusions
-
Goal vs. Implementation: The goal is to document the Query Cache feature. The documentation content is thorough and well-organized. However, the implementation has two issues that prevent the goal from being fully achieved — the
currentversion sidebar is not updated, so the page is unreachable in dev docs navigation, and the English files are missing front matter. -
Change size and focus: The change is appropriately scoped — new doc files for 2 versions × 2 languages + sidebar update. Focused and clear.
-
Documentation information architecture: Issue found. The
sidebars.tsfile (which controlscurrent/dev version navigation) was not updated to includequery-acceleration/query-cache. The page exists on disk atdocs/query-acceleration/query-cache.mdbut is orphaned from navigation. Users browsing the dev docs cannot reach it via the sidebar. Theversion-4.x-sidebars.jsonwas correctly updated. -
Sidebar/navigation consistency: As noted above,
sidebars.tsis missing the entry. Theversion-4.x-sidebars.jsonchange is correct — the new entry is placed in the "Caching" category alongsidesql-cache-manualandcondition-cache. -
Front matter: Issue found. Both English files (
docs/query-acceleration/query-cache.mdandversioned_docs/version-4.x/query-acceleration/query-cache.md) are missing the JSON front matter block. Every sibling file in the same directory (e.g.,sql-cache-manual.md,condition-cache.md,colocation-join.md) has front matter withtitle,language, anddescriptionfields. The Chinese files do have front matter. This inconsistency affects SEO metadata and Docusaurus title/description resolution. -
Version/locale consistency:
- English
currentand4.xfiles are identical — correct. - Chinese
currentand4.xfiles are identical — correct. - English and Chinese content is semantically consistent — correct.
- The PR description checks
devand unchecks4.x, but the4.xversion files are included in the PR. This is fine (the sidebar was updated for 4.x), but the checkbox is misleading. - Absence from
3.xand2.1appears intentional — Query Cache is a newer pipeline-level feature.
- English
-
Link validity: The relative link
[SQL Cache](./sql-cache-manual.md)resolves correctly in all four file locations. No broken links detected. -
Content quality: The documentation follows feature doc standards well — has overview, working principle explanation, configuration reference with defaults, usage examples, applicable/not-applicable scenarios, and notes. The content is technically detailed and clear.
-
Validation: No build was run, but structural checks were performed. The sidebar omission would cause the page to be unreachable in dev docs.
Issues Found
| # | Severity | File | Issue |
|---|---|---|---|
| 1 | High | sidebars.ts |
Missing query-acceleration/query-cache entry in the Caching category. The dev/current version page is unreachable through navigation. |
| 2 | Medium | docs/query-acceleration/query-cache.md |
Missing JSON front matter (title, language, description). All sibling files have it. |
| 3 | Medium | versioned_docs/version-4.x/query-acceleration/query-cache.md |
Same: missing JSON front matter. |
| @@ -0,0 +1,231 @@ | |||
| # Query Cache | |||
|
|
|||
There was a problem hiding this comment.
Missing front matter. Every sibling file in this directory (sql-cache-manual.md, condition-cache.md, colocation-join.md, etc.) has a JSON front matter block with title, language, and description fields. This file should have one too, for example:
---
{
"title": "Query Cache",
"language": "en",
"description": "Query Cache caches intermediate aggregation results in the pipeline execution engine to accelerate repeated analytical queries on internal OLAP tables."
}
---Without front matter, Docusaurus may not set the correct page title and meta description for SEO.
| @@ -0,0 +1,231 @@ | |||
| # Query Cache | |||
|
|
|||
There was a problem hiding this comment.
Missing front matter — same issue as the docs/ copy. This file should include JSON front matter with title, language, and description to match every other file in this directory.
| "items": [ | ||
| "query-acceleration/sql-cache-manual", | ||
| "query-acceleration/query-cache", | ||
| "query-acceleration/condition-cache", |
There was a problem hiding this comment.
The version-4.x-sidebars.json is correctly updated, but sidebars.ts (the current/dev version sidebar) was not updated. The file docs/query-acceleration/query-cache.md exists on disk but is orphaned from navigation — users browsing the dev docs cannot reach it via the sidebar.
Please add 'query-acceleration/query-cache' to the Caching category in sidebars.ts (around line 630), matching the placement here:
{
type: 'category',
label: 'Caching',
items: [
'query-acceleration/sql-cache-manual',
'query-acceleration/query-cache', // <-- add this
'query-acceleration/condition-cache',
'query-acceleration/tuning/tuning-plan/accelerating-queries-with-sql-cache',
],
},
Add Query Cache documentation and its Chinese localization; update sidebars.json to include the new page. This documents Query Cache behavior, configuration, limitations and examples.
Versions
Languages
Docs Checklist