I think we should make a separate document for the functions, and in general give more details about the functions' behavior. The current model is to give a very brief description of the function, but that's often not enough, users have to resort to either experiments or to reading documentation from other databases. The behavior should be described for corner cases, and ideally there should be examples as well.
Mihai ________________________________ From: Cancai Cai <[email protected]> Sent: Wednesday, January 24, 2024 7:14 AM To: [email protected] <[email protected]> Subject: Refactor reference.md Hey Calcite Devs, I am currently working on CALCITE-6215 <https://issues.apache.org/jira/browse/CALCITE-6215>. During my work, I have noticed that certain functions have multiple variations with different parameter types in their respective databases. For example, in PostgreSQL, the to_char function supports multiple forms such as to_char(timestamp, text), to_char(interval, text), and to_char(numeric_type, text). However, the description in Calcite is not clear enough. For instance, the reference.md document describes the to_char function as follows: | m o p | TO_CHAR(timestamp, format) | Converts *timestamp* to a string using the format *format*. This description may not provide enough clarity for users to understand the usage of each function across different databases. I suggest considering adding specific links to the corresponding database functions in the reference.md document to enhance its completeness. This would allow users to easily access the documentation for the respective database functions. Thanks as always, Cancai Cai https://www.postgresql.org/docs/16/functions-formatting.html#FUNCTIONS-FORMATTING-DATETIME-TABLE
