[docs] extra F.A.Q. content (#11898)

* more content for F.A.Q.

* more content

* normalize

* more content

* maybe fix the docs check

* absolute img urls

* fix tests

docs/en/faq/general/columnar-database.md

@@ -0,0 +1,25 @@
+---
+title: What is a columnar database?
+toc_hidden: true
+toc_priority: 101
+---
+
+# What Is a Columnar Database? {#what-is-a-columnar-database}
+
+A columnar database stores data of each column independently. This allows to read data from disks only for those columns that are used in any given query. The cost is that operations that affect whole rows become proportionally more expensive. The synonym for a columnar database is a column-oriented database management system. ClickHouse is a typical example of such a system.
+
+Key columnar database advantages are:
+
+-   Queries that use only a few columns out of many.
+-   Aggregating queries against large volumes of data.
+-   Column-wise data compression.
+
+Here is the illustration of the difference between traditional row-oriented systems and columnar databases when building reports:
+
+**Traditional row-oriented**
+![Traditional row-oriented](https://clickhouse.tech/docs/en/images/row-oriented.gif#)
+
+**Columnar**
+![Columnar](https://clickhouse.tech/docs/en/images/column-oriented.gif#)
+
+A columnar database is a preferred choice for analytical applications because it allows to have many columns in a table just in case, but don’t pay the cost for unused columns on read query execution time. Column-oriented databases are designed for big data processing because and data warehousing, they often natively scale using distributed clusters of low-cost hardware to increase throughput. ClickHouse does it with combination of [distributed](../../engines/table-engines/special/distributed.md) and [replicated](../../engines/table-engines/mergetree-family/replication.md) tables.

docs/en/faq/general/dbms-naming.md

@@ -1,11 +1,17 @@
 ---
+title: "What does \u201CClickHouse\u201D mean?"
 toc_hidden: true
 toc_priority: 10
 ---
 
 # What Does “ClickHouse” Mean? {#what-does-clickhouse-mean}
 
-It’s a combination of “**Click**stream” and “Data ware**house**”. It comes from the original use case at Yandex.Metrica, where ClickHouse was supposed to keep records of all clicks by people from all over the Internet and it still does the job. You can read more about this use case on [ClickHouse history](../../introduction/history.md) page.
+It’s a combination of “**Click**stream” and “Data ware**House**”. It comes from the original use case at Yandex.Metrica, where ClickHouse was supposed to keep records of all clicks by people from all over the Internet and it still does the job. You can read more about this use case on [ClickHouse history](../../introduction/history.md) page.
+
+This two-part meaning has two consequences:
+
+-   The only correct way to write Click**H**ouse is with capital H.
+-   If you need to abbreviate it, use **CH**. For some historical reasons, abbreviating as CK is also popular in China, mostly because one of the first talks about ClickHouse in Chinese used this form.
 
 !!! info "Fun fact"
     Many years after ClickHouse got its name, this approach of combining two words that are meaningful on their own has been highlighted as the best way to name a database in a [research by Andy Pavlo](https://www.cs.cmu.edu/~pavlo/blog/2020/03/on-naming-a-database-management-system.html), an Associate Professor of Databases at Carnegie Mellon University. ClickHouse shared his “best database name of all time” award with Postgres.

docs/en/faq/general/index.md

@@ -1,4 +1,5 @@
 ---
+title: General questions about ClickHouse
 toc_hidden_folder: true
 toc_priority: 1
 toc_title: General
@@ -8,8 +9,13 @@ toc_title: General
 
 Questions:
 
+-   [What is ClickHouse?](../../index.md#what-is-clickhouse)
+-   [Why ClickHouse is so fast?](../../faq/general/why-clickhouse-is-so-fast.md)
+-   [Who is using ClickHouse?](../../faq/general/who-is-using-clickhouse.md)
 -   [What does “ClickHouse” mean?](../../faq/general/dbms-naming.md)
 -   [What does “Не тормозит” mean?](../../faq/general/ne-tormozit.md)
+-   [What is OLAP?](../../faq/general/olap.md)
+-   [What is a columnar database?](../../faq/general/columnar-database.md)
 -   [Why not use something like MapReduce?](../../faq/general/mapreduce.md)
 
 !!! info "Don’t see what you were looking for?"

docs/en/faq/general/mapreduce.md

@@ -1,6 +1,7 @@
 ---
+title: Why not use something like MapReduce?
 toc_hidden: true
-toc_priority: 20
+toc_priority: 110
 ---
 
 # Why Not Use Something Like MapReduce? {#why-not-use-something-like-mapreduce}

docs/en/faq/general/ne-tormozit.md

@@ -1,13 +1,15 @@
 ---
+title: "What does \u201C\u043D\u0435 \u0442\u043E\u0440\u043C\u043E\u0437\u0438\u0442\
+  \u201D mean?"
 toc_hidden: true
 toc_priority: 11
 ---
 
-# What Does “Не тормозит” mean? {#what-does-ne-tormozit-mean}
+# What Does “Не тормозит” Mean? {#what-does-ne-tormozit-mean}
 
 This question usually arises when people see official ClickHouse t-shirts. They have large words **“ClickHouse не тормозит”** on the front.
 
-Before ClickHouse became open-source, it has been developed as an in-house storage system by the largest Russian IT company, [Yandex](https://yandex.com/company/). That’s why it initially got its slogan in Russian, which is “не тормозит”. After the open-source release we first produced some of those t-shirts for events in Russia and it was a no-brainer to use the slogan as-is.
+Before ClickHouse became open-source, it has been developed as an in-house storage system by the largest Russian IT company, [Yandex](https://yandex.com/company/). That’s why it initially got its slogan in Russian, which is “не тормозит” (pronounced as “ne tormozit”). After the open-source release we first produced some of those t-shirts for events in Russia and it was a no-brainer to use the slogan as-is.
 
 One of the following batches of those t-shirts was supposed to be given away on events outside of Russia and we tried to make the English version of the slogan. Unfortunately, the Russian language is kind of elegant in terms of expressing stuff and there was a restriction of limited space on a t-shirt, so we failed to come up with good enough translation (most options appeared to be either long or inaccurate) and decided to keep the slogan in Russian even on t-shirts produced for international events. It appeared to be a great decision because people all over the world get positively surprised and curious when they see it.
 

docs/en/faq/general/olap.md

@@ -0,0 +1,39 @@
+---
+title: What is OLAP?
+toc_hidden: true
+toc_priority: 100
+---
+
+# What Is OLAP? {#what-is-olap}
+
+[OLAP](https://en.wikipedia.org/wiki/Online_analytical_processing) stands for Online Analytical Processing. It is a broad term that can be looked at from two perspectives: technical and business. But at the very high level, you can just read these words backward:
+
+Processing
+:   Some source data is processed…
+
+Analytical
+:   …to produce some analytical reports and insights…
+
+Online
+:   …in real-time.
+
+## OLAP from the Business Perspective {#olap-from-the-business-perspective}
+
+In recent years, business people started to realize the value of data. Companies who make their decisions blindly, more often than not fail to keep up with the competition. The data-driven approach of successful companies forces them to collect all data that might be remotely useful for making business decisions and need mechanisms to timely analyze them. Here’s where OLAP database management systems (DBMS) come in.
+
+In a business sense, OLAP allows companies to continuously plan, analyze, and report operational activities, thus maximizing efficiency, reducing expenses, and ultimately conquering the market share. It could be done either in an in-house system or outsourced to SaaS providers like web/mobile analytics services, CRM services, etc. OLAP is the technology behind many BI applications (Business Intelligence).
+
+ClickHouse is an OLAP database management system that is pretty often used as a backend for those SaaS solutions for analyzing domain-specific data. However, some businesses are still reluctant to share their data with third-party providers and an in-house data warehouse scenario is also viable.
+
+## OLAP from the Technical Perspective {#olap-from-the-technical-perspective}
+
+All database management systems could be classified into two groups: OLAP (Online **Analytical** Processing) and OLTP (Online **Transactional** Processing). Former focuses on building reports, each based on large volumes of historical data, but doing it not so frequently. While the latter usually handle a continuous stream of transactions, constantly modifying the current state of data.
+
+In practice OLAP and OLTP are not categories, it’s more like a spectrum. Most real systems usually focus on one of them but provide some solutions or workarounds if the opposite kind of workload is also desired. This situation often forces businesses to operate multiple storage systems integrated, which might be not so big deal but having more systems make it more expensive to maintain. So the trend of recent years is HTAP (**Hybrid Transactional/Analytical Processing**) when both kinds of the workload are handled equally well by a single database management system.
+
+Even if a DBMS started as a pure OLAP or pure OLTP, they are forced to move towards that HTAP direction to keep up with their competition. And ClickHouse is no exception, initially, it has been designed as [fast-as-possible OLAP system](../../faq/general/why-clickhouse-is-so-fast.md) and it still doesn’t have full-fledged transaction support, but some features like consistent read/writes and mutations for updating/deleting data had to be added.
+
+The fundamental trade-off between OLAP and OLTP systems remains:
+
+-   To build analytical reports efficiently it’s crucial to be able to read columns separately, thus most OLAP databases are [columnar](../../faq/general/columnar-database.md),
+-   While storing columns separately increases costs of operations on rows, like append or in-place modification, proportionally to the number of columns (which can be huge if the systems try to collect all details of an event just in case). Thus, most OLTP systems store data arranged by rows.

docs/en/faq/general/who-is-using-clickhouse.md

@@ -0,0 +1,19 @@
+---
+title: Who is using ClickHouse?
+toc_hidden: true
+toc_priority: 9
+---
+
+# Who Is Using ClickHouse? {#who-is-using-clickhouse}
+
+Being an open-source product makes this question not so straightforward to answer. You don’t have to tell anyone if you want to start using ClickHouse, you just go grab source code or pre-compiled packages. There’s no contract to sign and the [Apache 2.0 license](https://github.com/ClickHouse/ClickHouse/blob/master/LICENSE) allows for unconstrained software distribution.
+
+Also, the technology stack is often in a grey zone of what’s covered by an NDA. Some companies consider technologies they use as a competitive advantage even if they are open-source and don’t allow employees to share any details publicly. Some see some PR risks and allow employees to share implementation details only with their PR department approval.
+
+So how to tell who is using ClickHouse?
+
+One way is to **ask around**. If it’s not in writing, people are much more willing to share what technologies are used in their companies, what the use cases are, what kind of hardware is used, data volumes, etc. We’re talking with users regularly on [ClickHouse Meetups](https://www.youtube.com/channel/UChtmrD-dsdpspr42P_PyRAw/playlists) all over the world and have heard stories about 1000+ companies that use ClickHouse. Unfortunately, that’s not reproducible and we try to treat such stories as if they were told under NDA to avoid any potential troubles. But you can come to any of our future meetups and talk with other users on your own. There are multiple ways how meetups are announced, for example, you can subscribe to [our Twitter](http://twitter.com/ClickHouseDB/).
+
+The second way is to look for companies **publicly saying** that they use ClickHouse. It’s more substantial because there’s usually some hard evidence like a blog post, talk video recording, slide deck, etc. We collect the collection of links to such evidence on our **[Adopters](../../introduction/adopters.md)** page. Feel free to contribute the story of your employer or just some links you’ve stumbled upon (but try not to violate your NDA in the process).
+
+You can find names of very large companies in the adopters list, like Bloomberg, Cisco, China Telecom, Tencent, or Uber, but with the first approach, we found that there are many more. For example, if you take [the list of largest IT companies by Forbes (2020)](https://www.forbes.com/sites/hanktucker/2020/05/13/worlds-largest-technology-companies-2020-apple-stays-on-top-zoom-and-uber-debut/) over half of them are using ClickHouse in some way. Also, it would be unfair not to mention [Yandex](../../introduction/history.md), the company which initially open-sourced ClickHouse in 2016 and happens to be one of the largest IT companies in Europe.

docs/en/faq/general/why-clickhouse-is-so-fast.md

@@ -0,0 +1,63 @@
+---
+title: Why ClickHouse is so fast?
+toc_hidden: true
+toc_priority: 8
+---
+
+# Why ClickHouse Is So Fast? {#why-clickhouse-is-so-fast}
+
+It was designed to be fast. Query execution performance has always been a top priority during the development process, but other important characteristics like user-friendliness, scalability, and security were also considered so ClickHouse could become a real production system.
+
+ClickHouse was initially built as a prototype to do just a single task well: to filter and aggregate data as fast as possible. That’s what needs to be done to build a typical analytical report and that’s what a typical [GROUP BY](../../sql-reference/statements/select/group-by.md) query does. ClickHouse team has made several high-level decisions that combined made achieving this task possible:
+
+Column-oriented storage
+:   Source data often contain hundreds or even thousands of columns, while a report can use just a few of them. The system needs to avoid reading unnecessary columns, or most expensive disk read operations would be wasted.
+
+Indexes
+:   ClickHouse keeps data structures in memory that allows reading not only used columns but only necessary row ranges of those columns.
+
+Data compression
+:   Storing different values of the same column together often leads to better compression ratios (compared to row-oriented systems) because in real data column often has the same or not so many different values for neighboring rows. In addition to general-purpose compression, ClickHouse supports [specialized codecs](../../sql-reference/statements/create.md#create-query-specialized-codecs) that can make data even more compact.
+
+Vectorized query execution
+:   ClickHouse not only stores data in columns but also processes data in columns. It leads to better CPU cache utilization and allows for [SIMD](https://en.wikipedia.org/wiki/SIMD) CPU instructions usage.
+
+Scalability
+:   ClickHouse can leverage all available CPU cores and disks to execute even a single query. Not only on a single server but all CPU cores and disks of a cluster as well.
+
+But many other database management systems use similar techniques. What really makes ClickHouse stand out is **attention to low-level details**. Most programming languages provide implementations for most common algorithms and data structures, but they tend to be too generic to be effective. Every task can be considered as a landscape with various characteristics, instead of just throwing in random implementation. For example, if you need a hash table, here are some key questions to consider:
+
+-   Which hash function to choose?
+-   Collision resolution algorithm: [open addressing](https://en.wikipedia.org/wiki/Open_addressing) vs [chaining](https://en.wikipedia.org/wiki/Hash_table#Separate_chaining)?
+-   Memory layout: one array for keys and values or separate arrays? Will it store small or large values?
+-   Fill factor: when and how to resize? How to move values around on resize?
+-   Will values be removed and which algorithm will work better if they will?
+-   Will we need fast probing with bitmaps, inline placement of string keys, support for non-movable values, prefetch, and batching?
+
+Hash table is a key data structure for `GROUP BY` implementation and ClickHouse automatically chooses one of [30+ variations](https://github.com/ClickHouse/ClickHouse/blob/master/src/Interpreters/Aggregator.h) for each specific query.
+
+The same goes for algorithms, for example, in sorting you might consider:
+
+-   What will be sorted: an array of numbers, tuples, strings, or structures?
+-   Is all data available completely in RAM?
+-   Do we need a stable sort?
+-   Do we need a full sort? Maybe partial sort or n-th element will suffice?
+-   How to implement comparisons?
+-   Are we sorting data that has already been partially sorted?
+
+Algorithms that they rely on characteristics of data they are working with can often do better than their generic counterparts. If it is not really known in advance, the system can try various implementations and choose the one that works best in runtime. For example, see an [article on how LZ4 decompression is implemented in ClickHouse](https://habr.com/en/company/yandex/blog/457612/).
+
+Last but not least, the ClickHouse team always monitors the Internet on people claiming that they came up with the best implementation, algorithm, or data structure to do something and tries it out. Those claims mostly appear to be false, but from time to time you’ll indeed find a gem.
+
+!!! info "Tips for building your own high-performance software"
+
+
+    -   Keep in mind low-level details when designing your system.
+    -   Design based on hardware capabilities.
+    -   Choose data structures and abstractions based on the needs of the task.
+    -   Provide specializations for special cases.
+    -   Try new, “best” algorithms, that you read about yesterday.
+    -   Choose an algorithm in runtime based on statistics.
+    -   Benchmark on real datasets.
+    -   Test for performance regressions in CI.
+    -   Measure and observe everything.

docs/en/faq/index.md

@@ -10,8 +10,37 @@ This section of the documentation is a place to collect answers to ClickHouse-re
 
 Categories:
 
--   [General](../faq/general/index.md)
--   [Operations](../faq/operations/index.md)
--   [Integration](../faq/integration/index.md)
+-   **[General](../faq/general/index.md)**
+    -   [What is ClickHouse?](../index.md#what-is-clickhouse)
+    -   [Why ClickHouse is so fast?](../faq/general/why-clickhouse-is-so-fast.md)
+    -   [Who is using ClickHouse?](../faq/general/who-is-using-clickhouse.md)
+    -   [What does “ClickHouse” mean?](../faq/general/dbms-naming.md)
+    -   [What does “Не тормозит” mean?](../faq/general/ne-tormozit.md)
+    -   [What is OLAP?](../faq/general/olap.md)
+    -   [What is a columnar database?](../faq/general/columnar-database.md)
+    -   [Why not use something like MapReduce?](../faq/general/mapreduce.md)
+-   **[Use Cases](../faq/use-cases/index.md)**
+    -   [Can I use ClickHouse as a time-series database?](../faq/use-cases/time-series.md)
+    -   [Can I use ClickHouse as a key-value storage?](../faq/use-cases/key-value.md)
+-   **[Operations](../faq/operations/index.md)**
+    -   [Which ClickHouse version to use in production?](../faq/operations/production.md)
+    -   [Is it possible to delete old records from a ClickHouse table?](../faq/operations/delete-old-data.md)
+-   **[Integration](../faq/integration/index.md)**
+    -   [How do I export data from ClickHouse to a file?](../faq/integration/file-export.md)
+    -   [What if I have a problem with encodings when connecting to Oracle via ODBC?](../faq/integration/oracle-odbc.md)
+
+{## TODO
+Question candidates:
+- How to choose a primary key?
+- How to add a column in ClickHouse?
+- Too many parts
+- How to filter ClickHouse table by an array column contents?
+- How to insert all rows from one table to another of identical structure?
+- How to kill a process (query) in ClickHouse?
+- How to implement pivot (like in pandas)?
+- How to remove the default ClickHouse user through users.d?
+- Importing MySQL dump to Clickhouse
+- Window function workarounds (row\_number, lag/lead, running diff/sum/average)
+##}
 
 {## [Original article](https://clickhouse.tech/docs/en/faq) ##}

docs/en/faq/integration/file-export.md

@@ -1,4 +1,5 @@
 ---
+title: How do I export data from ClickHouse to a file?
 toc_hidden: true
 toc_priority: 10
 ---

docs/en/faq/integration/index.md

@@ -1,15 +1,17 @@
 ---
+title: Questions about integrating ClickHouse and other systems
 toc_hidden_folder: true
-toc_priority: 3
+toc_priority: 4
 toc_title: Integration
 ---
 
-# Question About Integrating ClickHouse and Other Systems {#question-about-integrating-clickhouse-and-other-systems}
+# Questions About Integrating ClickHouse and Other Systems {#question-about-integrating-clickhouse-and-other-systems}
 
 Questions:
 
 -   [How do I export data from ClickHouse to a file?](../../faq/integration/file-export.md)
--   [What if I Have a problem with encodings when connecting to Oracle via ODBC?](../../faq/integration/oracle-odbc.md)
+-   [How to import JSON into ClickHouse?](../../faq/integration/json-import.md)
+-   [What if I have a problem with encodings when connecting to Oracle via ODBC?](../../faq/integration/oracle-odbc.md)
 
 !!! info "Don’t see what you were looking for?"
     Check out [other F.A.Q. categories](../../faq/index.md) or browse around main documentation articles found in the left sidebar.

docs/en/faq/integration/json-import.md

@@ -0,0 +1,33 @@
+---
+title: How to import JSON into ClickHouse?
+toc_hidden: true
+toc_priority: 11
+---
+
+# How to Import JSON Into ClickHouse? {#how-to-import-json-into-clickhouse}
+
+ClickHouse supports a wide range of [data formats for input and output](../../interfaces/formats.md). There are multiple JSON variations among them, but the most commonly used for data ingestion is [JSONEachRow](../../interfaces/formats.md#jsoneachrow). It expects one JSON object per row, each object separated by a newline.
+
+## Examples {#examples}
+
+Using [HTTP interface](../../interfaces/http.md):
+
+``` bash
+$ echo '{"foo":"bar"}' | curl 'http://localhost:8123/?query=INSERT%20INTO%20test%20FORMAT%20JSONEachRow' --data-binary @-
+```
+
+Using [CLI interface](../../interfaces/cli.md):
+
+``` bash
+$ echo '{"foo":"bar"}'  | clickhouse-client ---query="INSERT INTO test FORMAT 20JSONEachRow"
+```
+
+Instead of inserting data manually, you might consider to use one of [client libraries](../../interfaces/index.md) instead.
+
+## Useful Settings {#useful-settings}
+
+-   `input_format_skip_unknown_fields` allows to insert JSON even if there were additional fields not present in table schema (by discarding them).
+-   `input_format_import_nested_json` allows to insert nested JSON objects into columns of [Nested](../../sql-reference/data-types/nested-data-structures/nested.md) type.
+
+!!! note "Note"
+    Settings are specified as `GET` parameters for the HTTP interface or as additional command-line arguments prefixed with `--` for the CLI interface.

docs/en/faq/integration/oracle-odbc.md

@@ -1,4 +1,5 @@
 ---
+title: What if I have a problem with encodings when using Oracle via ODBC?
 toc_hidden: true
 toc_priority: 20
 ---

docs/en/faq/operations/delete-old-data.md

@@ -0,0 +1,42 @@
+---
+title: Is it possible to delete old records from a ClickHouse table?
+toc_hidden: true
+toc_priority: 20
+---
+
+# Is It Possible to Delete Old Records from a ClickHouse Table? {#is-it-possible-to-delete-old-records-from-a-clickhouse-table}
+
+The short answer is “yes”. ClickHouse has multiple mechanisms that allow freeing up disk space by removing old data. Each mechanism is aimed for different scenarios.
+
+## TTL {#ttl}
+
+ClickHouse allows to automatically drop values when some condition happens. This condition is configured as an expression based on any columns, usually just static offset for any timestamp column.
+
+The key advantage of this approach is that it doesn’t need any external system to trigger, once TTL is configured, data removal happens automatically in background.
+
+!!! note "Note"
+    TTL can also be used to move data not only to [/dev/null](https://en.wikipedia.org/wiki/Null_device), but also between different storage systems, like from SSD to HDD.
+
+More details on [configuring TTL](../../engines/table-engines/mergetree-family/mergetree.md#table_engine-mergetree-ttl).
+
+## ALTER DELETE {#alter-delete}
+
+ClickHouse doesn’t have real-time point deletes like in [OLTP](https://en.wikipedia.org/wiki/Online_transaction_processing) databases. The closest thing to them are mutations. They are issued as `ALTER ... DELETE` or `ALTER ... UPDATE` queries to distinguish from normal `DELETE` or `UPDATE` as they are asynchronous batch operations, not immediate modifications. The rest of syntax after `ALTER TABLE` prefix is similar.
+
+`ALTER DELETE` can be issued to flexibly remove old data. If you need to do it regularly, the main downside will be the need to have an external system to submit the query. There are also some performance considerations since mutation rewrite complete parts even there’s only a single row to be deleted.
+
+This is the most common approach to make your system based on ClickHouse [GDPR](https://gdpr-info.eu)-compliant.
+
+More details on [mutations](../../sql-reference/statements/alter.md#alter-mutations).
+
+## DROP PARTITION {#drop-partition}
+
+`ALTER TABLE ... DROP PARTITION` provides a cost-efficient way to drop a whole partition. It’s not that flexible and needs proper partitioning scheme configured on table creation, but still covers most common cases. Like mutations need to be executed from an external system for regular use.
+
+More details on [manipulating partitions](../../sql-reference/statements/alter.md#alter_drop-partition).
+
+## TRUNCATE {#truncate}
+
+It’s rather radical to drop all data from a table, but in some cases it might be exactly what you need.
+
+More details on [table truncation](../../sql-reference/statements/alter.md#alter_drop-partition).

docs/en/faq/operations/index.md

@@ -1,6 +1,7 @@
 ---
+title: Question about operating ClickHouse servers and clusters
 toc_hidden_folder: true
-toc_priority: 2
+toc_priority: 3
 toc_title: Operations
 ---
 
@@ -9,6 +10,7 @@ toc_title: Operations
 Questions:
 
 -   [Which ClickHouse version to use in production?](../../faq/operations/production.md)
+-   [Is it possible to delete old records from a ClickHouse table?](../../faq/operations/delete-old-data.md)
 
 !!! info "Don’t see what you were looking for?"
     Check out [other F.A.Q. categories](../../faq/index.md) or browse around main documentation articles found in the left sidebar.

docs/en/faq/operations/production.md

@@ -1,4 +1,5 @@
 ---
+title: Which ClickHouse version to use in production?
 toc_hidden: true
 toc_priority: 10
 ---

docs/en/faq/use-cases/index.md

@@ -0,0 +1,18 @@
+---
+title: Questions about ClickHouse use cases
+toc_hidden_folder: true
+toc_priority: 2
+toc_title: Use Cases
+---
+
+# Questions About ClickHouse Use Cases {#questions-about-clickhouse-use-cases}
+
+Questions:
+
+-   [Can I use ClickHouse as a time-series database?](../../faq/use-cases/time-series.md)
+-   [Can I use ClickHouse as a key-value storage?](../../faq/use-cases/key-value.md)
+
+!!! info "Don’t see what you were looking for?"
+    Check out [other F.A.Q. categories](../../faq/index.md) or browse around main documentation articles found in the left sidebar.
+
+{## [Original article](https://clickhouse.tech/docs/en/faq/use-cases/) ##}

docs/en/faq/use-cases/key-value.md

@@ -0,0 +1,17 @@
+---
+title: Can I use ClickHouse as a key-value storage?
+toc_hidden: true
+toc_priority: 101
+---
+
+# Can I Use ClickHouse As a Key-Value Storage? {#can-i-use-clickhouse-as-a-key-value-storage}
+
+The short answer is **“no”**. The key-value workload is among top positions in the list of cases when NOT{.text-danger} to use ClickHouse. It’s an [OLAP](../../faq/general/olap.md) system after all, while there are many excellent key-value storage systems out there.
+
+However, there might be situations where it still makes sense to use ClickHouse for key-value-like queries. Usually, it’s some low-budget products where the main workload is analytical in nature and fits ClickHouse well, but there’s also some secondary process that needs a key-value pattern with not so high request throughput and without strict latency requirements. If you had an unlimited budget, you would have installed a secondary key-value database for thus secondary workload, but in reality, there’s an additional cost of maintaining one more storage system (monitoring, backups, etc.) which might be desirable to avoid.
+
+If you decide to go against recommendations and run some key-value-like queries against ClickHouse, here’re some tips:
+
+-   The key reason why point queries are expensive in ClickHouse is its sparse primary index of main [MergeTree table engine family](../../engines/table-engines/mergetree-family/mergetree.md). This index can’t point to each specific row of data, instead, it points to each N-th and the system has to scan from the neighboring N-th row to the desired one, reading excessive data along the way. In a key-value scenario, it might be useful to reduce the value of N with the `index_granularity` setting.
+-   ClickHouse keeps each column in a separate set of files, so to assemble one complete row it needs to go through each of those files. Their count increases linearly with the number of columns, so in the key-value scenario, it might be worth to avoid using many columns and put all your payload in a single `String` column encoded in some serialization format like JSON, Protobuf or whatever makes sense.
+-   There’s an alternative approach that uses [Join](../../engines/table-engines/special/join.md) table engine instead of normal `MergeTree` tables and [joinGet](../../sql-reference/functions/other-functions.md#joinget) function to retrieve the data. It can provide better query performance but might have some usability and reliability issues. Here’s an [usage example](https://github.com/ClickHouse/ClickHouse/blob/master/tests/queries/0_stateless/00800_versatile_storage_join.sql#L49-L51).

docs/en/faq/use-cases/time-series.md

@@ -0,0 +1,15 @@
+---
+title: Can I use ClickHouse as a time-series database?
+toc_hidden: true
+toc_priority: 101
+---
+
+# Can I Use ClickHouse As a Time-Series Database? {#can-i-use-clickhouse-as-a-time-series-database}
+
+ClickHouse is a generic data storage solution for [OLAP](../../faq/general/olap.md) workloads, while there are many specialized time-series database management systems. Nevertheless, ClickHouse’s [focus on query execution speed](../../faq/general/why-clickhouse-is-so-fast.md) allows it to outperform specialized systems in many cases. There are many independent benchmarks on this topic out there ([example](https://medium.com/@AltinityDB/clickhouse-for-time-series-scalability-benchmarks-e181132a895b)), so we’re not going to conduct one here. Instead, let’s focus on ClickHouse features that are important to use if that’s your use case.
+
+First of all, there are **[specialized codecs](../../sql-reference/statements/create.md#create-query-specialized-codecs)** which make typical time-series. Either common algorithms like `DoubleDelta` and `Gorilla` or specific to ClickHouse like `T64`.
+
+Second, time-series queries often hit only recent data, like one day or one week old. It makes sense to use servers that have both fast nVME/SSD drives and high-capacity HDD drives. ClickHouse [TTL](../../engines/table-engines/mergetree-family/mergetree.md#table_engine-mergetree-multiple-volumes) feature allows to configure keeping fresh hot data on fast drives and gradually move it to slower drives as it ages. Rollup or removal of even older data is also possible if your requirements demand it.
+
+Even though it’s against ClickHouse philosophy of storing and processing raw data, you can use [materialized views](../../sql-reference/statements/create.md#create-view) to fit into even tighter latency or costs requirements.

docs/en/whats-new/index.md

@@ -1,6 +1,10 @@
 ---
 toc_folder_title: What's New
-toc_priority: 72
+toc_priority: 82
 ---
 
+# What's New In ClickHouse?
+
+There's a short high-level [roadmap](roadmap.md) and a detailed [changelog](changelog/index.md) for releases that have already been published.
+
 

docs/tools/mdx_clickhouse.py

@@ -26,6 +26,7 @@ MARKDOWN_EXTENSIONS = [
     'mdx_clickhouse',
     'admonition',
     'attr_list',
+    'def_list',
     'codehilite',
     'nl2br',
     'sane_lists',

docs/tools/translate/filter.py

@@ -117,6 +117,7 @@ def translate_filter(key, value, _format, _):
             admonition_value = []
             remaining_para_value = []
             in_admonition = True
+            break_value = [pandocfilters.LineBreak(), pandocfilters.Str(' ' * 4)]
             for item in value:
                 if in_admonition:
                     if item.get('t') == 'SoftBreak':
@@ -124,9 +125,11 @@ def translate_filter(key, value, _format, _):
                     else:
                         admonition_value.append(item)
                 else:
-                    remaining_para_value.append(item)
+                    if item.get('t') == 'SoftBreak':
+                        remaining_para_value += break_value
+                    else:
+                        remaining_para_value.append(item)
 
-            break_value = [pandocfilters.LineBreak(), pandocfilters.Str(' ' * 4)]
             if admonition_value[-1].get('t') == 'Quoted':
                 text = process_sentence(admonition_value[-1]['c'][-1])
                 text[0]['c'] = '"' + text[0]['c']
@@ -136,7 +139,7 @@ def translate_filter(key, value, _format, _):
             else:
                 text = admonition_value[-1].get('c')
                 if text:
-                    text = translate(text[0].upper() + text[1:])
+                    text = translate.translate(text[0].upper() + text[1:])
                     admonition_value.append(pandocfilters.Space())
                     admonition_value.append(pandocfilters.Str(f'"{text}"'))
 

docs/tools/translate/translate.sh

@@ -16,7 +16,7 @@ source "${BASE_DIR}/venv/bin/activate"
 ${BASE_DIR}/split_meta.py "${INPUT_PATH}"
 
 pandoc "${INPUT_CONTENT}" --filter "${BASE_DIR}/filter.py" -o "${TEMP_FILE}" \
-    -f "markdown-space_in_atx_header" -t "markdown_strict+pipe_tables+markdown_attribute+all_symbols_escapable+backtick_code_blocks+autolink_bare_uris-link_attributes+markdown_attribute+mmd_link_attributes-raw_attribute+header_attributes-grid_tables" \
+    -f "markdown-space_in_atx_header" -t "markdown_strict+pipe_tables+markdown_attribute+all_symbols_escapable+backtick_code_blocks+autolink_bare_uris-link_attributes+markdown_attribute+mmd_link_attributes-raw_attribute+header_attributes-grid_tables+definition_lists" \
     --atx-headers --wrap=none --columns=99999 --tab-stop=4
 perl -pi -e 's/{\\#\\#/{##/g' "${TEMP_FILE}"
 perl -pi -e 's/\\#\\#}/##}/g' "${TEMP_FILE}"

docs/tools/website.py

@@ -67,6 +67,13 @@ def adjust_markdown_html(content):
                 summary.extract()
                 details.insert(0, summary)
 
+    for dd in soup.find_all('dd'):
+        dd_class = dd.attrs.get('class')
+        if dd_class:
+            dd.attrs['class'] = dd_class + ['pl-3']
+        else:
+            dd.attrs['class'] = 'pl-3'
+
     for div in soup.find_all('div'):
         div_class = div.attrs.get('class')
         is_admonition = div_class and 'admonition' in div.attrs.get('class')