Merge branch 'main' into docs-cdc

Author: morsapaes

.gitignore

@@ -55,17 +55,22 @@ static/knowledgebase_toc.json
 .frontmatter-validation-failed
 logs/
 
+# Landing page files with autogenerated table of contents
+docs/cloud/reference/release-notes-index.md
+docs/cloud/manage/api/api-reference-index.md
+docs/getting-started/index.md
+docs/data-modeling/projections/index.md
+docs/cloud/manage/jan2025_faq/index.md
+docs/chdb/guides/index.md
+docs/use-cases/AI_ML/index.md
+docs/use-cases/AI_ML/MCP/index.md
+docs/use-cases/AI_ML/MCP/ai_agent_libraries/index.md
+docs/integrations/data-ingestion/clickpipes/kafka/index.md
+
 .vscode
 .aspell.en.prepl
 *.md.bak
 
 **.translated
 **.translate
 /ClickHouse/
-
-# Ignore table of contents files
-docs/cloud/reference/release-notes-index.md
-docs/whats-new/changelog/index.md
-docs/cloud/manage/api/api-reference-index.md
-docs/getting-started/index.md
-docs/data-modeling/projections/index.md

README.md

@@ -1,8 +1,8 @@
 <div align=center>
 
-![Website](https://img.shields.io/website?up_message=AVAILABLE&down_message=DOWN&url=https%3A%2F%2Fclickhouse.com%2Fdocs&style=for-the-badge)
+[![Website](https://img.shields.io/website?up_message=AVAILABLE&down_message=DOWN&url=https%3A%2F%2Fclickhouse.com%2Fdocs&style=for-the-badge)](https://clickhouse.com)
 [![CC BY-NC-SA 4.0 License](https://img.shields.io/badge/license-CC-blueviolet?style=for-the-badge)](http://creativecommons.org/licenses/by-nc-sa/4.0/)
-![Checks](https://img.shields.io/github/actions/workflow/status/clickhouse/clickhouse-docs/debug.yml?style=for-the-badge&label=Checks)
+[![Checks](https://img.shields.io/github/actions/workflow/status/clickhouse/clickhouse-docs/debug.yml?style=for-the-badge&label=Checks)](https://github.com/ClickHouse/clickhouse-docs/actions)
 
 <picture align=center>
     <source media="(prefers-color-scheme: dark)" srcset="https://github.com/ClickHouse/clickhouse-docs/assets/9611008/4ef9c104-2d3f-4646-b186-507358d2fe28">
@@ -18,19 +18,19 @@
 
 ClickHouse is blazing fast, but understanding ClickHouse and using it effectively is a journey. The documentation is your source for gaining the knowledge you need to be successful with your ClickHouse projects and applications. [Head over to clickhouse.com/docs to learn more →](https://clickhouse.com/)
 
-## Table of contents {#table-of-contents}
+## Table of contents
 
 - [About this repo](#about-this-repo)
 - [Run locally](#run-locally)
 - [Contributing](#contributing)
 - [Issues](#issues)
 - [License](#license)
 
-## About this repo {#about-this-repo}
+## About this repo
 
 This repository manages the documentation for [ClickHouse](https://clickhouse.com/docs). The content is built with [Docusaurus](https://docusaurus.io/) and hosted on [Vercel](https://vercel.com). Documentation content is written in Markdown and is held in the `/docs` directory.
 
-## Run locally {#run-locally}
+## Run locally
 
 You can run a copy of this website locally within a few steps. Some folks find this useful when contributing so they can see precisely what their changes will look like on the production site.
 
@@ -116,23 +116,19 @@ To check spelling and markdown is correct locally run:
 yarn check-style
 ```
 
-### Notes {#notes}
+### Notes
 
 Here are some things to keep in mind when building a local copy of the ClickHouse docs site.
 
-#### Build-time {#build-time}
-
-Due to the complex structure of this repo, the docs site can take some time to build locally. As a benchmark, it takes ~3 minutes to build on an M1 Macbook with 8GB RAM.
-
-#### Redirects {#redirects}
+#### Redirects
 
 Due to how the local server is built, redirects will not work. For example, visiting `clickhouse.com/docs` on the production site will lead you to `clickhouse.com/docs/intro`. However, on a local copy of the site, you will see a 404 page if you try to visit `localhost:8000/docs`.
 
-## Contributing {#contributing}
+## Contributing
 
 Want to help out? Contributions are always welcome! If you want to help out but aren't sure where to start, check out the [issues board](https://github.com/clickhouse/clickhouse-docs/issues).
 
-### Pull requests {#pull-requests}
+### Pull requests
 
 Please assign any pull request (PR) against an issue; this helps the docs team track who is working on what and what each PR is meant to address. If there isn't an issue for the specific _thing_ you want to work on, quickly create one and comment so that it can be assigned to you. One of the repository maintainers will add you as an assignee.
 
@@ -153,7 +149,7 @@ yarn check-style
 For an overview of how reference documentation such as settings, system tables
 and functions are generated from the source code, see ["Generating documentation from source code"](/contribute/autogenerated-documentation-from-source.md)
 
-### Tests and CI/CD {#tests-and-cicd}
+### Tests and CI/CD
 
 There are five workflows that run against PRs in this repo:
 
@@ -165,7 +161,7 @@ There are five workflows that run against PRs in this repo:
 | [Scheduled Vercel build](https://github.com/ClickHouse/clickhouse-docs/blob/main/.github/workflows/scheduled-vercel-build.yml) | Builds the site every day at 00:10 UTC and hosts the build on Vercel. |
 | [Trigger build](https://github.com/ClickHouse/clickhouse-docs/blob/main/.github/workflows/trigger-build.yml) | Uses the [peter-evans/repository-dispatch@v2](https://github.com/peter-evans/repository-dispatch) workflow to create a repository dispatch. |
 
-### Quick contributions {#quick-contributions}
+### Quick contributions
 
 Have you noticed a typo or found some wonky formatting? For small contributions like these, it's usually faster and easier to make your changes directly in GitHub. Here's a quick guide to show you how the GitHub editor works:
 
@@ -200,10 +196,10 @@ Have you noticed a typo or found some wonky formatting? For small contributions
 
 At this point, your pull request will be handed over to the docs team, who will review it and suggest or make changes where necessary.
 
-## Issues {#issues}
+## Issues
 
 Found a problem with the Clickhouse docs site? [Please raise an issue](https://github.com/clickhouse/clickhouse-docs/issues/new). Be as specific and descriptive as possible; screenshots help!
 
-## License {#license}
+## License
 
 This work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/).

contribute/style-guide.md

@@ -340,7 +340,7 @@ When using URL parameters to control which version of documentation is displayed
 there are conventions to follow for reliable functionality. 
 Here's how the `?v=v08` parameter relates to the snippet selection:
 
-#### How It Works
+#### How it works
 
 The URL parameter acts as a selector that matches against the `version` property 
 in your component configuration. For example:
@@ -393,3 +393,22 @@ show_related_blogs: true
 
 This will show it on the page, assuming there is a matching blog. If there is no
 match then it remains hidden.
+
+## Vale
+
+Vale is a command-line tool that brings code-like linting to prose.
+We have a number of rules set up to ensure that our documentation is
+consistent in style.
+
+The style rules are located at `/styles/ClickHouse`, and largely based
+off of the Google styleset, with some ClickHouse specific adaptions.
+If you want to check only a specific rule locally, you
+can run:
+
+```bash
+vale --filter='.Name == "ClickHouse.Headings"' docs/integrations
+```
+
+This will run only the rule named `Headings` on
+the `docs/integrations` directory. Specifying a specific markdown
+file is also possible.

docs/_snippets/_GCS_authentication_and_bucket.md

@@ -19,7 +19,7 @@ import Image from '@theme/IdealImage';
 
 <Image size="md" img={GCS_bucket_2} alt="Creating a GCS bucket in US East 4" border />
 
-### Generate an Access key {#generate-an-access-key}
+### Generate an access key {#generate-an-access-key}
 
 ### Create a service account HMAC key and secret {#create-a-service-account-hmac-key-and-secret}
 

docs/_snippets/_add_superset_detail.md

@@ -13,7 +13,7 @@ There are a few tasks to be done before running `docker compose`:
 The commands below are to be run from the  top level of the GitHub repo, `superset`.
 :::
 
-## Official ClickHouse Connect driver {#official-clickhouse-connect-driver}
+## Official ClickHouse connect driver {#official-clickhouse-connect-driver}
 
 To make the ClickHouse Connect driver available in the Superset deployment add it to the local requirements file:
 

docs/_snippets/_users-and-roles-common.md

@@ -269,7 +269,7 @@ Roles are used to define groups of users for certain privileges instead of manag
    Verify that only the above two rows are returned, rows with the value `B` in `column1` should be excluded.
    :::
 
-## Modifying Users and Roles {#modifying-users-and-roles}
+## Modifying users and roles {#modifying-users-and-roles}
 
 Users can be assigned multiple roles for a combination of privileges needed. When using multiple roles, the system will combine the roles to determine privileges, the net effect will be that the role permissions will be cumulative.
 

docs/about-us/beta-and-experimental-features.md

@@ -14,19 +14,19 @@ Due to the uncertainty of when features are classified as generally available, w
 
 The sections below explicitly describe the properties of **Beta** and **Experimental** features:
 
-## Beta Features {#beta-features}
+## Beta features {#beta-features}
 
 - Under active development to make them generally available (GA)
 - Main known issues can be tracked on GitHub
 - Functionality may change in the future
 - Possibly enabled in ClickHouse Cloud
 - The ClickHouse team supports beta features
 
-The following features are considered Beta in ClickHouse Cloud and are available for use in ClickHouse Cloud Services, even though they may be currently under a ClickHouse SETTING named ```allow_experimental_*```:
+You can find below the features considered Beta in ClickHouse Cloud and are available for use in your ClickHouse Cloud Services.
 
 Note: please be sure to be using a current version of the ClickHouse [compatibility](/operations/settings/settings#compatibility) setting to be using a recently introduced feature.
 
-## Experimental Features {#experimental-features}
+## Experimental features {#experimental-features}
 
 - May never become GA
 - May be removed

docs/about-us/distinctive-features.md

@@ -7,81 +7,81 @@ title: 'Distinctive Features of ClickHouse'
 keywords: ['compression', 'secondary-indexes','column-oriented']
 ---
 
-# Distinctive Features of ClickHouse
+# Distinctive features of ClickHouse
 
-## True Column-Oriented Database Management System {#true-column-oriented-database-management-system}
+## True column-oriented database management system {#true-column-oriented-database-management-system}
 
 In a real column-oriented DBMS, no extra data is stored with the values. This means that constant-length values must be supported to avoid storing their length "number" next to the values. For example, a billion UInt8-type values should consume around 1 GB uncompressed, or this strongly affects the CPU use. It is essential to store data compactly (without any "garbage") even when uncompressed since the speed of decompression (CPU usage) depends mainly on the volume of uncompressed data.
 
 This is in contrast to systems that can store values of different columns separately, but that cannot effectively process analytical queries due to their optimization for other scenarios, such as HBase, Bigtable, Cassandra, and Hypertable. You would get throughput around a hundred thousand rows per second in these systems, but not hundreds of millions of rows per second.
 
 Finally, ClickHouse is a database management system, not a single database. It allows creating tables and databases in runtime, loading data, and running queries without reconfiguring and restarting the server.
 
-## Data Compression {#data-compression}
+## Data compression {#data-compression}
 
 Some column-oriented DBMSs do not use data compression. However, data compression plays a key role in achieving excellent performance.
 
 In addition to efficient general-purpose compression codecs with different trade-offs between disk space and CPU consumption, ClickHouse provides [specialized codecs](/sql-reference/statements/create/table.md#specialized-codecs) for specific kinds of data, which allow ClickHouse to compete with and outperform more niche databases, like time-series ones.
 
-## Disk Storage of Data {#disk-storage-of-data}
+## Disk storage of data {#disk-storage-of-data}
 
 Keeping data physically sorted by primary key makes it possible to extract data based on specific values or value ranges with low latency in less than a few dozen milliseconds. Some column-oriented DBMSs, such as SAP HANA and Google PowerDrill, can only work in RAM. This approach requires allocation of a larger hardware budget than necessary for real-time analysis.
 
 ClickHouse is designed to work on regular hard drives, which means the cost per GB of data storage is low, but SSD and additional RAM are also fully used if available.
 
-## Parallel Processing on Multiple Cores {#parallel-processing-on-multiple-cores}
+## Parallel processing on multiple cores {#parallel-processing-on-multiple-cores}
 
 Large queries are parallelized naturally, taking all the necessary resources available on the current server.
 
-## Distributed Processing on Multiple Servers {#distributed-processing-on-multiple-servers}
+## Distributed processing on multiple servers {#distributed-processing-on-multiple-servers}
 
 Almost none of the columnar DBMSs mentioned above have support for distributed query processing.
 
 In ClickHouse, data can reside on different shards. Each shard can be a group of replicas used for fault tolerance. All shards are used to run a query in parallel, transparently for the user.
 
-## SQL Support {#sql-support}
+## SQL support {#sql-support}
 
 ClickHouse supports [SQL language](/sql-reference/) that is mostly compatible with the ANSI SQL standard.
 
 Supported queries include [GROUP BY](../sql-reference/statements/select/group-by.md), [ORDER BY](../sql-reference/statements/select/order-by.md), subqueries in [FROM](../sql-reference/statements/select/from.md), [JOIN](../sql-reference/statements/select/join.md) clause, [IN](../sql-reference/operators/in.md) operator, [window functions](../sql-reference/window-functions/index.md) and scalar subqueries.
 
 Correlated (dependent) subqueries are not supported at the time of writing but might become available in the future.
 
-## Vector Computation Engine {#vector-engine}
+## Vector computation engine {#vector-engine}
 
 Data is not only stored by columns but is processed by vectors (parts of columns), which allows achieving high CPU efficiency.
 
-## Real-Time Data Inserts {#real-time-data-updates}
+## Real-time data inserts {#real-time-data-updates}
 
 ClickHouse supports tables with a primary key. To quickly perform queries on the range of the primary key, the data is sorted incrementally using the merge tree. Due to this, data can continually be added to the table. No locks are taken when new data is ingested.
 
-## Primary Indexes {#primary-index}
+## Primary indexes {#primary-index}
 
 Having data physically sorted by primary key makes it possible to extract data based on specific values or value ranges with low latency in less than a few dozen milliseconds.
 
-## Secondary Indexes {#secondary-indexes}
+## Secondary indexes {#secondary-indexes}
 
 Unlike other database management systems, secondary indexes in ClickHouse do not point to specific rows or row ranges. Instead, they allow the database to know in advance that all rows in some data parts would not match the query filtering conditions and do not read them at all, thus they are called [data skipping indexes](../engines/table-engines/mergetree-family/mergetree.md#table_engine-mergetree-data_skipping-indexes).
 
-## Suitable for Online Queries {#suitable-for-online-queries}
+## Suitable for online queries {#suitable-for-online-queries}
 
 Most OLAP database management systems do not aim for online queries with sub-second latencies. In alternative systems, report building time of tens of seconds or even minutes is often considered acceptable. Sometimes it takes even more time, which forces systems to prepare reports offline (in advance or by responding with "come back later").
 
 In ClickHouse "low latency" means that queries can be processed without delay and without trying to prepare an answer in advance, right at the same moment as the user interface page is loading. In other words, online.
 
-## Support for Approximated Calculations {#support-for-approximated-calculations}
+## Support for approximated calculations {#support-for-approximated-calculations}
 
 ClickHouse provides various ways to trade accuracy for performance:
 
 1.  Aggregate functions for approximated calculation of the number of distinct values, medians, and quantiles.
 2.  Running a query based on a part ([SAMPLE](../sql-reference/statements/select/sample.md)) of data and getting an approximated result. In this case, proportionally less data is retrieved from the disk.
 3.  Running an aggregation for a limited number of random keys, instead of for all keys. Under certain conditions for key distribution in the data, this provides a reasonably accurate result while using fewer resources.
 
-## Adaptive Join Algorithm {#adaptive-join-algorithm}
+## Adaptive join algorithm {#adaptive-join-algorithm}
 
 ClickHouse adaptively chooses how to [JOIN](../sql-reference/statements/select/join.md) multiple tables, by preferring hash-join algorithm and falling back to the merge-join algorithm if there's more than one large table.
 
-## Data Replication and Data Integrity Support {#data-replication-and-data-integrity-support}
+## Data replication and data integrity support {#data-replication-and-data-integrity-support}
 
 ClickHouse uses asynchronous multi-master replication. After being written to any available replica, all the remaining replicas retrieve their copy in the background. The system maintains identical data on different replicas. Recovery after most failures is performed automatically, or semi-automatically in complex cases.
 
@@ -91,7 +91,7 @@ For more information, see the section [Data replication](../engines/table-engine
 
 ClickHouse implements user account management using SQL queries and allows for [role-based access control configuration](/guides/sre/user-management/index.md) similar to what can be found in ANSI SQL standard and popular relational database management systems.
 
-## Features that Can Be Considered Disadvantages {#clickhouse-features-that-can-be-considered-disadvantages}
+## Features that can be considered disadvantages {#clickhouse-features-that-can-be-considered-disadvantages}
 
 1.  No full-fledged transactions.
 2.  Lack of ability to modify or delete already inserted data with a high rate and low latency. There are batch deletes and updates available to clean up or modify data, for example, to comply with [GDPR](https://gdpr-info.eu).