Problem

There are many functions in ClickHouse, but not all are documented. See #1682 #1512 as examples. This issue serves as the main holding-issue for many child/sub-issues. Essentially, if you want to know which functions have recently had documentation added, you should treat this issue as the source-of-truth.

Solution

Document 100% of the functions in ClickHouse.

Process

1. List all the functions that exist in ClickHouse.
2. List all the functions that have docs.
3. Create a list of functions that don't have docs.
4. Loop through this new list to write a description and syntax example for each function.
   1. To get this info, check the tests that each function was written with.
   2. Check in with the author of each function to get a background on why it was created.
5. Repeat step 4 until all the functions have docs.

Scope

List each function, what it does, and a syntax example.

Example

Here is a markdown example of what a function should look like the following (a copy of this is available in the clickhouse/clickhouse repository at /docs/en/sql-reference/functions/_function-template.md):

## Example

This function serves as an example of what function documentation should look like.

**Syntax**

```sql
Example(input, secondary_input)
```

**Parameters**

- `input`: This is an example input. [String literal](../syntax#syntax-string-literal)
- `secondary_input`: This is another example input. [Expression](../syntax#syntax-expressions)

**Returned value**

This function doesn't exists. But if it did, they it would return a bool.

**Implementation details**

Any additional information pertaining to this function that users might need to know about. Things like known-bugs or edge cases would fit into this section. For example, if a function used _bankers rounding_ instead of standard rounding.

**Example**

Query:

```sql
CREATE TABLE example_table
(
    id UUID,
    name String,
) ENGINE = MergeTree
ORDER BY id;

INSERT INTO example_table VALUES (generateUUIDv4(), Example());
SELECT * FROM example_table;
```

```response
9e22db8c-d343-4bc5-8a95-501f635c0fc4	Example
```

Things to note:

1. The arguments must end in a valid type and link to that type within the docs.
2. The example query must be valid and complete; a user should be able to copy and paste the query directly into fiddle.clickhouse.com and have the query run without any modifications.
3. The example result must be similar to what the user can expect to see when running it in fiddle.clickhouse.com. Some functions, such as generateUUIDv4(), will return a random string; as such, you shouldn't try to have your example response match what the user might see.

Out of scope

We will not:

• Create a fancy new way of searching through functions.
• Expand on or update existing function docs.
• Create in-depth guides or tutorials for each function.
• Add docs directly into clickhouse/clickhouse code.
• Showcase specific functions.

These items are valid points to improve the docs, but they're entirely separate projects that require planning and setup of their own.

Timeline

This project should be completed in Q1 2024. So, by the end of March 2024.