ClickHouse/docs
iammagicc 08549c0a02
增加最后一个索引条目存储了上图中颗粒1082的主键列的最大值与图片不符的描述
为什么图中显示的数据与结论不符合?因为图中的数据是禁用了自适应索引粒度后得到的,默认情况下索引粒度是自适应的。
https://clickhouse.com/docs/en/optimize/sparse-primary-indexes
We mentioned in the beginning of this guide in the "DDL Statement Details", that we disabled adaptive index granularity (in order to simplify the discussions in this guide, as well as make the diagrams and results reproducible).
For tables with adaptive index granularity (index granularity is adaptive by default) the size of some granules can be less than 8192 rows depending on the row data sizes.
我们在本指南开头的“DDL 语句详细信息”中提到,我们禁用了自适应索引粒度(为了简化本指南中的讨论,并使图表和结果可重现)。
对于具有自适应索引粒度的表(默认情况下索引粒度是自适应的),某些粒度的大小可以小于 8192 行,具体取决于行数据大小。


https://clickhouse.com/docs/en/whats-new/changelog/2019#experimental-features-1
ClickHouse Release 19.6.3.18, 2019-06-13
Experimental Features:实验性特性   
Add setting index_granularity_bytes (adaptive index granularity) for MergeTree* tables family.
为合并树家族的表系列添加设置index_granularity_bytes(自适应索引粒度)。

ClickHouse Release 19.10.1.5, 2019-07-12
Performance Improvement:优化改进
Add the possibility to write the final mark at the end of MergeTree columns. It allows to avoid useless reads for keys that are out of table data range. It is enabled only if adaptive index granularity is in use.
添加在合并树列末尾写入最终标记的可能性。它允许避免对超出表数据范围的键进行无用的读取。仅当使用自适应索引粒度时,才会启用它。
2023-03-21 15:53:45 +08:00
..
_includes Give users option of overwriting 2023-03-02 23:05:37 +01:00
changelogs Update version_date.tsv and changelogs after v22.8.15.23-lts 2023-03-10 22:01:27 +00:00
en Update string-search-functions.md 2023-03-20 15:20:40 -03:00
ru Merge pull request #47522 from kolechenkov/patch-2 2023-03-20 14:28:36 +01:00
zh 增加最后一个索引条目存储了上图中颗粒1082的主键列的最大值与图片不符的描述 2023-03-21 15:53:45 +08:00
.gitignore
clean
mkdocs.yml
README.md Remove "Original article links" 2023-01-09 15:13:36 +01:00
redirects.txt chore: delete obsolete modelEvaluate() function + SYSTEM.MODELS view 2022-09-08 09:10:11 +00:00

Contributing to ClickHouse Documentation

Why Do You Need to Document ClickHouse

The main reason is that ClickHouse is an open source project, and if you don't write the docs, nobody does. "Incomplete or Confusing Documentation" is the top complaint about open source software by the results of a Github Open Source Survey of 2017. Documentation is highly valued but often overlooked. One of the most important contributions someone can make to an open source repository is a documentation update.

Many developers can say that the code is the best docs by itself, and they are right. But, ClickHouse is not a project for C++ developers. Most of its users don't know C++, and they can't understand the code quickly. ClickHouse is large enough to absorb almost any change without a noticeable trace. Nobody will find your very useful function, or an important setting, or a very informative new column in a system table if it is not referenced in the documentation.

If you want to help ClickHouse with documentation you can face, for example, the following questions:

  • "I don't know how to write."

    We have prepared some recommendations for you.

  • "I know what I want to write, but I don't know how to contribute to docs."

    Here are some tips.

Writing the docs is extremely useful for project's users and developers, and grows your karma.

Contents

What is the ClickHouse Documentation

The documentation contains information about all the aspects of the ClickHouse lifecycle: developing, testing, installing, operating, and using. The base language of the documentation is English. The English version is the most actual. All other languages are supported as much as they can by contributors from different countries.

At the moment, documentation exists in English, Russian, and Chinese. We store the reference documentation besides the ClickHouse source code in the GitHub repository, and user guides in a separate repo Clickhouse/clickhouse-docs.

Each language lies in the corresponding folder. Files that are not translated from English are symbolic links to the English ones.

How to Contribute to ClickHouse Documentation

You can contribute to the documentation in many ways, for example:

Contribute all new information in English language. Other languages are translations from English.

Markdown Dialect Cheatsheet

  • Headings: Place them on a separate line and start with # , ## or ### . Use the Title Case for them. Example:

    # The First Obligatory Title on a Page.
    
  • Bold text: **asterisks** or __underlines__.

  • Links: [link text](uri). Examples:

    • External link: [ClickHouse repo](https://github.com/ClickHouse/ClickHouse)
    • Cross link: [How to build docs](tools/README.md)
  • Images: ![Exclamation sign](uri). You can refer to local images as well as remote in internet.

  • Lists: Lists can be of two types:

    • - unordered: Each item starts from the -.
    • 1. ordered: Each item starts from the number.

    A list must be separated from the text by an empty line. Nested lists must be indented with 4 spaces.

  • Inline code: `in backticks`.

  • Multiline code blocks:

    ```lang_name
      code
      lines
      ```
  • Note:

    !!! info "Header"
        4 spaces indented text.
    
  • Warning:

    !!! warning "Header"
        4 spaces indented text.
    
  • Text hidden behind a cut (single sting that opens on click):

    <details markdown="1"> <summary>Visible text</summary>
        Hidden content.
    </details>`.
    
  • Colored text: <span style="color: red;">text</span>.

  • Heading anchor to be linked to: # Title {#anchor-name}.

  • Table:

    | Header    1 | Header    2 | Header    3 |
    | ----------- | ----------- | ----------- |
    | Cell     A1 | Cell     A2 | Cell     A3 |
    | Cell     B1 | Cell     B2 | Cell     B3 |
    | Cell     C1 | Cell     C2 | Cell     C3 |
    

Adding a New File

{## When adding a new file:

  • Make symbolic links for all other languages. You can use the following commands:

    $ cd /ClickHouse/clone/directory/docs
    $ ln -sr en/new/file.md lang/new/file.md
    

##}

Adding a New Language

  1. Create a new docs subfolder named using the ISO-639-1 language code.
  2. Add Markdown files with the translation, mirroring the folder structure of other languages.
  3. Commit and open a pull-request with the new content.

When everything is ready, we will add the new language to the website.

How to Write Content for ClickHouse Documentation

Documentation for Different Audiences

When writing documentation, think about the people who read it. Each audience has specific requirements for terms they use in communications.

ClickHouse documentation can be divided up by the audience for the following parts:

  • Conceptual topics like tutorials and overviews.

    These topics are for the most common audience. When editing text in them, use the most common terms that are comfortable for the audience with basic technical skills.

  • Query language reference and related topics.

    These parts of the documentation are dedicated to those who use ClickHouse for data analysis. Carefully describe syntax, input, and output data for expressions. Don't forget the examples.

  • Description of table engines and operation details.

    Operation engineers who help data analysts to solve their tasks should know how to install/update a ClickHouse server, maintain the ClickHouse cluster, how to integrate it with other tools and systems, how to get the maximum performance of their entire environment.

  • Developer's guides.

    The documentation provides code writers with information about how to write code for ClickHouse and how to build it in different environments.

Common Recommendations

  • When searching for a position for your text, try to place it in the most anticipated place.
  • Group entities. For example, if several functions solve similar tasks or belong to a specific group by use case or an application type, place them together.
  • Try to avoid slang. Use the most common and specific terms possible. If some terms are used as synonyms, state this explicitly.
  • Add examples for all the functionality. Add basic examples to show how the function works by itself. Add use case examples to show how the function participates in solving specific tasks.
  • Any text concerning politics, religion, or other social related themes are strictly prohibited in all the ClickHouse texts.
  • Proofread your text before publishing. Look for typos, missing punctuation, or repetitions that could be avoided.

Description Templates

When writing docs, you can use prepared templates. Copy the code of a template and use it in your contribution. Sometimes you just need to change level of headers.

Templates:

How to Build Documentation

You can build your documentation manually by following the instructions in the docs repo contrib-writing-guide. Also, our CI runs the documentation build after the documentation label is added to PR. You can see the results of a build in the GitHub interface. If you have no permissions to add labels, a reviewer of your PR will add it.