Tracking: re-org the functions doc

[BohuTANG]

Summary

Re-org the doc as duckdb-style: https://databend.rs/doc/sql-functions

Tasks:

• [x] Numeric Functions https://github.com/datafuselabs/databend/pull/10003
• [x] Arithmetic Operators #10030
• [x] Comparison Operators #10030
• [x] Logical/Boolean Operators #10030
• [ ] String Functions
• [x] Hash Functions
• [x] UUID Functions
• [x] Conversion Functions @wangjili8417
• [ ] IP Address Functions
• [x] Context Functions
• [x] Conditional Functions
• [ ] Semi-structured Data Functions
• [ ] Aggregate Functions
• [ ] Date & Time Functions
• [x] Geography Function（@wangjili8417)
• [ ] Test Functions

[suyanhanx]

I think it's important to be consistent with the capitalization of functions in the documentation. For example, in the documentation for DuckDB, function names are all lowercase.

[BohuTANG]

I think it's important to be consistent with the capitalization of functions in the documentation. For example, in the documentation for DuckDB, function names are all lowercase.

Prefer all the function name to uppercase like snowflake https://docs.snowflake.com/en/sql-reference-functions

[wangjili8417]

I'd like to work on Conversion Functions

[sundy-li]

Prefer all the function name to uppercase like snowflake docs.snowflake.com/en/sql-reference-functions

@BohuTANG It's not the same behavior.

1. snowflake resolve and stored uppercase Identifier by default, see https://docs.snowflake.com/en/sql-reference/identifiers-syntax

2. databend resolve and stored lowercase Identifier by default, see https://databend.rs/doc/sql-reference/sql-identifiers

I suggest that functions should be lower and snake case by default to keep it consistent with our rules. Otherwise, there will be misleading and bugs.

[BohuTANG]

Prefer all the function name to uppercase like snowflake docs.snowflake.com/en/sql-reference-functions

@BohuTANG It's not the same behavior.

1. snowflake resolve and stored uppercase Identifier by default, see https://docs.snowflake.com/en/sql-reference/identifiers-syntax
2. databend resolve and stored lowercase Identifier by default, see https://databend.rs/doc/sql-reference/sql-identifiers

I suggest that functions should be lower and snake case by default to keep it consistent with our rules.

I agree with Databend function's name to lowercase. (Sorry @suyanhanx I missed this).

But I think these are two things:

1. the function name is case insensitive in most databases no matter what the Identifier is.

For example, these two SQL should both work:

mysql> SELECT VERSION();
+------------------------------------------------------------------------------------+
| version()                                                                          |
+------------------------------------------------------------------------------------+
| 8.0.26-v0.9.29-nightly-f53dc21(rust-1.68.0-nightly-2023-02-09T05:04:10.989449884Z) |
+------------------------------------------------------------------------------------+

mysql> select version();
+------------------------------------------------------------------------------------+
| version()                                                                          |
+------------------------------------------------------------------------------------+
| 8.0.26-v0.9.29-nightly-f53dc21(rust-1.68.0-nightly-2023-02-09T05:04:10.989449884Z) |
+------------------------------------------------------------------------------------+

From PostgreSQL, some functions' name is uppercase some is lowercase, and the lowercase's function example is in uppercase, a bit confusing (cc @leiysky )

2. the table/database/view object name should be under the Identifier rule.

[suyanhanx]

SGTM.

But I have to say that conventionally, functions and other built-in identifiers in databases are more like constants. While many databases may not be case-sensitive, in documentation, these identifiers are often written in uppercase in examples, in order to distinguish them from user input such as table names and column names.

The underlying implementation may not be as important, as it does not affect how users interact with the database. Therefore, it may be more important to note the “case-insensitive" in the documentation rather than break the convention.

So I personally think that it would be better to follow convention and use uppercase for built-in identifiers.

[BohuTANG]

Q:

database function name in the doc is lowercase or uppercase?

ChatGPT:

The naming conventions for functions in a database documentation may vary depending on the specific database system and the documentation style being used.

However, in general, it is common to use lowercase letters for function names in a database documentation. This is because lowercase letters are generally easier to read and distinguish from other text, and they are consistent with many programming language conventions.

That being said, it's always a good idea to follow any naming conventions that are specific to your database system or your organization's documentation style.

[suyanhanx]

database function name in the doc is lowercase or uppercase?

The question seems too general.

Q:

In the documentation of a database software, should built-in functions be in uppercase or lowercase?

ChatGPT:

The convention for casing of built-in functions in documentation of a database software 
may vary depending on the specific database software and its community. However, it is 
common to use uppercase for built-in functions as a convention in many database 
systems, such as MySQL and Oracle. Using uppercase letters for built-in functions can 
help to differentiate them from user-defined functions or other elements in the database 
system. Nevertheless, it is always a good practice to follow the conventions of the specific 
database software and its community when writing documentation.

🤔

[wangjili8417]

I'd like to work on Geography Functions.