Skip to content

Commit cc87cf7

Browse files
leto-bleto-b
authored
add format function in table model (#682)
* add format function in table model * fix subtitle
1 parent 68708fe commit cc87cf7

4 files changed

Lines changed: 752 additions & 0 deletions

File tree

‎src/UserGuide/Master/Table/SQL-Manual/Basis-Function.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -758,6 +758,192 @@ SELECT *
758758
IN (try_cast('2024-11-27' AS DATE), try_cast('2024-11-28' AS DATE));
759759
```
760760

761+
### 7.2 Format Function
762+
763+
This function generates and returns a formatted string based on a specified format string and input arguments. Similar to Java’s `String.format` or C’s `printf`, it allows developers to construct dynamic string templates using placeholder syntax. Predefined format specifiers in the template are replaced precisely with corresponding argument values, producing a complete string that adheres to specific formatting requirements.
764+
765+
#### 7.2.1 Syntax
766+
767+
```SQL
768+
format(pattern, ...args) -> STRING
769+
```
770+
771+
**Parameters**
772+
773+
* `pattern`: A format string containing static text and one or more format specifiers (e.g., `%s`, `%d`), or any expression returning a `STRING`/`TEXT` type.
774+
* `args`: Input arguments to replace format specifiers. Constraints:
775+
* Number of arguments ≥ 1.
776+
* Multiple arguments must be comma-separated (e.g., `arg1, arg2`).
777+
* Total arguments can exceed the number of specifiers in `pattern` but cannot be fewer, otherwise an exception is triggered.
778+
779+
**Return Value**
780+
781+
* Formatted result string of type `STRING`.
782+
783+
#### 7.2.2 Usage Examples
784+
785+
1. Format Floating-Point Numbers
786+
```SQL
787+
IoTDB:database1> SELECT format('%.5f', humidity) FROM table1 WHERE humidity = 35.4;
788+
+--------+
789+
| _col0|
790+
+--------+
791+
|35.40000|
792+
+--------+
793+
```
794+
2. Format Integers
795+
```SQL
796+
IoTDB:database1> SELECT format('%03d', 8) FROM table1 LIMIT 1;
797+
+-----+
798+
|_col0|
799+
+-----+
800+
| 008|
801+
+-----+
802+
```
803+
3. Format Dates and Timestamps
804+
805+
* Locale-Specific Date
806+
807+
```SQL
808+
IoTDB:database1> SELECT format('%1$tA, %1$tB %1$te, %1$tY', 2024-01-01) FROM table1 LIMIT 1;
809+
+--------------------+
810+
| _col0|
811+
+--------------------+
812+
|Monday, January 1, 2024|
813+
+--------------------+
814+
```
815+
816+
* Remove Timezone Information
817+
818+
```SQL
819+
IoTDB:database1> SELECT format('%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS.%1$tL', 2024-01-01T00:00:00.000+08:00) FROM table1 LIMIT 1;
820+
+-----------------------+
821+
| _col0|
822+
+-----------------------+
823+
|2024-01-01 00:00:00.000|
824+
+-----------------------+
825+
```
826+
827+
* Second-Level Timestamp Precision
828+
829+
```SQL
830+
IoTDB:database1> SELECT format('%1$tF %1$tT', 2024-01-01T00:00:00.000+08:00) FROM table1 LIMIT 1;
831+
+-------------------+
832+
| _col0|
833+
+-------------------+
834+
|2024-01-01 00:00:00|
835+
+-------------------+
836+
```
837+
838+
* Date/Time Format Symbols
839+
840+
| **Symbol** | **​ Description** |
841+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
842+
| 'H' | 24-hour format (two digits, zero-padded), i.e. 00 - 23 |
843+
| 'I' | 12-hour format (two digits, zero-padded), i.e. 01 - 12 |
844+
| 'k' | 24-hour format (no padding), i.e. 0 - 23 |
845+
| 'l' | 12-hour format (no padding), i.e. 1 - 12 |
846+
| 'M' | Minute (two digits, zero-padded), i.e. 00 - 59 |
847+
| 'S' | Second (two digits, zero-padded; supports leap seconds), i.e. 00 - 60 |
848+
| 'L' | Millisecond (three digits, zero-padded), i.e. 000 - 999 |
849+
| 'N' | Nanosecond (nine digits, zero-padded), i.e. 000000000 - 999999999。 |
850+
| 'p' | Locale-specific lowercase AM/PM marker (e.g., "am", "pm"). Prefix with`T`to force uppercase (e.g., "AM"). |
851+
| 'z' | RFC 822 timezone offset from GMT (e.g.,`-0800`). Adjusts for daylight saving. Uses the JVM's default timezone for`long`/`Long`/`Date`. |
852+
| 'Z' | Timezone abbreviation (e.g., "PST"). Adjusts for daylight saving. Uses the JVM's default timezone; Formatter's timezone overrides the argument's timezone if specified. |
853+
| 's' | Seconds since Unix epoch (1970-01-01 00:00:00 UTC), i.e. Long.MIN\_VALUE/1000 to Long.MAX\_VALUE/1000。 |
854+
| 'Q' | Milliseconds since Unix epoch, i.e. Long.MIN\_VALUE 至 Long.MAX\_VALUE。 |
855+
856+
* Common Date/Time Conversion Characters
857+
858+
| **Symbol** | **​ Description** |
859+
| ---------------- | -------------------------------------------------------------------- |
860+
| 'B' | Locale-specific full month name, for example "January", "February" |
861+
| 'b' | Locale-specific abbreviated month name, for example "Jan", "Feb" |
862+
| 'h' | Same as`b` |
863+
| 'A' | Locale-specific full weekday name, for example "Sunday", "Monday" |
864+
| 'a' | Locale-specific short weekday name, for example "Sun", "Mon" |
865+
| 'C' | Year divided by 100 (two digits, zero-padded) |
866+
| 'Y' | Year (minimum 4 digits, zero-padded) |
867+
| 'y' | Last two digits of year (zero-padded) |
868+
| 'j' | Day of year (three digits, zero-padded) |
869+
| 'm' | Month (two digits, zero-padded) |
870+
| 'd' | Day of month (two digits, zero-padded) |
871+
| 'e' | Day of month (no padding) |
872+
873+
4. Format Strings
874+
```SQL
875+
IoTDB:database1> SELECT format('The measurement status is: %s', status) FROM table2 LIMIT 1;
876+
+-------------------------------+
877+
| _col0|
878+
+-------------------------------+
879+
|The measurement status is: true|
880+
+-------------------------------+
881+
```
882+
5. Format Percentage Sign
883+
```SQL
884+
IoTDB:database1> SELECT format('%s%%', 99.9) FROM table1 LIMIT 1;
885+
+-----+
886+
|_col0|
887+
+-----+
888+
|99.9%|
889+
+-----+
890+
```
891+
892+
#### 7.2.3 Format Conversion Failure Scenarios
893+
894+
1. Type Mismatch Errors
895+
896+
* Timestamp Type Conflict
897+
898+
If the format specifier includes time-related tokens (e.g., `%Y-%m-%d`) but the argument:
899+
900+
* Is a non-`DATE`/`TIMESTAMP` type value. ◦
901+
* Requires sub-day precision (e.g., `%H`, `%M`) but the argument is not `TIMESTAMP`.
902+
903+
```SQL
904+
-- Example 1
905+
IoTDB:database1> SELECT format('%1$tA, %1$tB %1$te, %1$tY', humidity) from table2 limit 1
906+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %1$tA, %1$tB %1$te, %1$tY (IllegalFormatConversion: A != java.lang.Float)
907+
908+
-- Example 2
909+
IoTDB:database1> SELECT format('%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS.%1$tL', humidity) from table1 limit 1
910+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS.%1$tL (IllegalFormatConversion: Y != java.lang.Float)
911+
```
912+
913+
* Floating-Point Type Conflict
914+
915+
Using `%f` with non-numeric arguments (e.g., strings or booleans):
916+
917+
```SQL
918+
IoTDB:database1> select format('%.5f',status) from table1 where humidity = 35.4
919+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %.5f (IllegalFormatConversion: f != java.lang.Boolean)
920+
```
921+
922+
2. Argument Count Mismatch
923+
The number of arguments must equal or exceed the number of format specifiers.
924+
925+
```SQL
926+
IoTDB:database1> SELECT format('%.5f %03d', humidity) FROM table1 WHERE humidity = 35.4;
927+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %.5f %03d (MissingFormatArgument: Format specifier '%03d')
928+
```
929+
3. Invalid Invocation Errors
930+
931+
Triggered if:
932+
933+
* Total arguments < 2 (must include `pattern` and at least one argument).•
934+
* `pattern` is not of type `STRING`/`TEXT`.
935+
936+
```SQL
937+
-- Example 1
938+
IoTDB:database1> select format('%s') from table1 limit 1
939+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must have at least two arguments, and first argument pattern must be TEXT or STRING type.
940+
941+
--Example 2
942+
IoTDB:database1> select format(123, humidity) from table1 limit 1
943+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must have at least two arguments, and first argument pattern must be TEXT or STRING type.
944+
```
945+
946+
761947
## 8. String Functions and Operators
762948

763949
### 8.1 String operators

‎src/UserGuide/latest-Table/SQL-Manual/Basis-Function.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -758,6 +758,192 @@ SELECT *
758758
IN (try_cast('2024-11-27' AS DATE), try_cast('2024-11-28' AS DATE));
759759
```
760760

761+
### 7.2 Format Function
762+
763+
This function generates and returns a formatted string based on a specified format string and input arguments. Similar to Java’s `String.format` or C’s `printf`, it allows developers to construct dynamic string templates using placeholder syntax. Predefined format specifiers in the template are replaced precisely with corresponding argument values, producing a complete string that adheres to specific formatting requirements.
764+
765+
#### 7.2.1 Syntax
766+
767+
```SQL
768+
format(pattern, ...args) -> STRING
769+
```
770+
771+
**Parameters**
772+
773+
* `pattern`: A format string containing static text and one or more format specifiers (e.g., `%s`, `%d`), or any expression returning a `STRING`/`TEXT` type.
774+
* `args`: Input arguments to replace format specifiers. Constraints:
775+
* Number of arguments ≥ 1.
776+
* Multiple arguments must be comma-separated (e.g., `arg1, arg2`).
777+
* Total arguments can exceed the number of specifiers in `pattern` but cannot be fewer, otherwise an exception is triggered.
778+
779+
**Return Value**
780+
781+
* Formatted result string of type `STRING`.
782+
783+
#### 7.2.2 Usage Examples
784+
785+
1. Format Floating-Point Numbers
786+
```SQL
787+
IoTDB:database1> SELECT format('%.5f', humidity) FROM table1 WHERE humidity = 35.4;
788+
+--------+
789+
| _col0|
790+
+--------+
791+
|35.40000|
792+
+--------+
793+
```
794+
2. Format Integers
795+
```SQL
796+
IoTDB:database1> SELECT format('%03d', 8) FROM table1 LIMIT 1;
797+
+-----+
798+
|_col0|
799+
+-----+
800+
| 008|
801+
+-----+
802+
```
803+
3. Format Dates and Timestamps
804+
805+
* Locale-Specific Date
806+
807+
```SQL
808+
IoTDB:database1> SELECT format('%1$tA, %1$tB %1$te, %1$tY', 2024-01-01) FROM table1 LIMIT 1;
809+
+--------------------+
810+
| _col0|
811+
+--------------------+
812+
|Monday, January 1, 2024|
813+
+--------------------+
814+
```
815+
816+
* Remove Timezone Information
817+
818+
```SQL
819+
IoTDB:database1> SELECT format('%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS.%1$tL', 2024-01-01T00:00:00.000+08:00) FROM table1 LIMIT 1;
820+
+-----------------------+
821+
| _col0|
822+
+-----------------------+
823+
|2024-01-01 00:00:00.000|
824+
+-----------------------+
825+
```
826+
827+
* Second-Level Timestamp Precision
828+
829+
```SQL
830+
IoTDB:database1> SELECT format('%1$tF %1$tT', 2024-01-01T00:00:00.000+08:00) FROM table1 LIMIT 1;
831+
+-------------------+
832+
| _col0|
833+
+-------------------+
834+
|2024-01-01 00:00:00|
835+
+-------------------+
836+
```
837+
838+
* Date/Time Format Symbols
839+
840+
| **Symbol** | **​ Description** |
841+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
842+
| 'H' | 24-hour format (two digits, zero-padded), i.e. 00 - 23 |
843+
| 'I' | 12-hour format (two digits, zero-padded), i.e. 01 - 12 |
844+
| 'k' | 24-hour format (no padding), i.e. 0 - 23 |
845+
| 'l' | 12-hour format (no padding), i.e. 1 - 12 |
846+
| 'M' | Minute (two digits, zero-padded), i.e. 00 - 59 |
847+
| 'S' | Second (two digits, zero-padded; supports leap seconds), i.e. 00 - 60 |
848+
| 'L' | Millisecond (three digits, zero-padded), i.e. 000 - 999 |
849+
| 'N' | Nanosecond (nine digits, zero-padded), i.e. 000000000 - 999999999。 |
850+
| 'p' | Locale-specific lowercase AM/PM marker (e.g., "am", "pm"). Prefix with`T`to force uppercase (e.g., "AM"). |
851+
| 'z' | RFC 822 timezone offset from GMT (e.g.,`-0800`). Adjusts for daylight saving. Uses the JVM's default timezone for`long`/`Long`/`Date`. |
852+
| 'Z' | Timezone abbreviation (e.g., "PST"). Adjusts for daylight saving. Uses the JVM's default timezone; Formatter's timezone overrides the argument's timezone if specified. |
853+
| 's' | Seconds since Unix epoch (1970-01-01 00:00:00 UTC), i.e. Long.MIN\_VALUE/1000 to Long.MAX\_VALUE/1000。 |
854+
| 'Q' | Milliseconds since Unix epoch, i.e. Long.MIN\_VALUE 至 Long.MAX\_VALUE。 |
855+
856+
* Common Date/Time Conversion Characters
857+
858+
| **Symbol** | **​ Description** |
859+
| ---------------- | -------------------------------------------------------------------- |
860+
| 'B' | Locale-specific full month name, for example "January", "February" |
861+
| 'b' | Locale-specific abbreviated month name, for example "Jan", "Feb" |
862+
| 'h' | Same as`b` |
863+
| 'A' | Locale-specific full weekday name, for example "Sunday", "Monday" |
864+
| 'a' | Locale-specific short weekday name, for example "Sun", "Mon" |
865+
| 'C' | Year divided by 100 (two digits, zero-padded) |
866+
| 'Y' | Year (minimum 4 digits, zero-padded) |
867+
| 'y' | Last two digits of year (zero-padded) |
868+
| 'j' | Day of year (three digits, zero-padded) |
869+
| 'm' | Month (two digits, zero-padded) |
870+
| 'd' | Day of month (two digits, zero-padded) |
871+
| 'e' | Day of month (no padding) |
872+
873+
4. Format Strings
874+
```SQL
875+
IoTDB:database1> SELECT format('The measurement status is: %s', status) FROM table2 LIMIT 1;
876+
+-------------------------------+
877+
| _col0|
878+
+-------------------------------+
879+
|The measurement status is: true|
880+
+-------------------------------+
881+
```
882+
5. Format Percentage Sign
883+
```SQL
884+
IoTDB:database1> SELECT format('%s%%', 99.9) FROM table1 LIMIT 1;
885+
+-----+
886+
|_col0|
887+
+-----+
888+
|99.9%|
889+
+-----+
890+
```
891+
892+
#### 7.2.3 Format Conversion Failure Scenarios
893+
894+
1. Type Mismatch Errors
895+
896+
* Timestamp Type Conflict
897+
898+
If the format specifier includes time-related tokens (e.g., `%Y-%m-%d`) but the argument:
899+
900+
* Is a non-`DATE`/`TIMESTAMP` type value. ◦
901+
* Requires sub-day precision (e.g., `%H`, `%M`) but the argument is not `TIMESTAMP`.
902+
903+
```SQL
904+
-- Example 1
905+
IoTDB:database1> SELECT format('%1$tA, %1$tB %1$te, %1$tY', humidity) from table2 limit 1
906+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %1$tA, %1$tB %1$te, %1$tY (IllegalFormatConversion: A != java.lang.Float)
907+
908+
-- Example 2
909+
IoTDB:database1> SELECT format('%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS.%1$tL', humidity) from table1 limit 1
910+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS.%1$tL (IllegalFormatConversion: Y != java.lang.Float)
911+
```
912+
913+
* Floating-Point Type Conflict
914+
915+
Using `%f` with non-numeric arguments (e.g., strings or booleans):
916+
917+
```SQL
918+
IoTDB:database1> select format('%.5f',status) from table1 where humidity = 35.4
919+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %.5f (IllegalFormatConversion: f != java.lang.Boolean)
920+
```
921+
922+
2. Argument Count Mismatch
923+
The number of arguments must equal or exceed the number of format specifiers.
924+
925+
```SQL
926+
IoTDB:database1> SELECT format('%.5f %03d', humidity) FROM table1 WHERE humidity = 35.4;
927+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %.5f %03d (MissingFormatArgument: Format specifier '%03d')
928+
```
929+
3. Invalid Invocation Errors
930+
931+
Triggered if:
932+
933+
* Total arguments < 2 (must include `pattern` and at least one argument).•
934+
* `pattern` is not of type `STRING`/`TEXT`.
935+
936+
```SQL
937+
-- Example 1
938+
IoTDB:database1> select format('%s') from table1 limit 1
939+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must have at least two arguments, and first argument pattern must be TEXT or STRING type.
940+
941+
--Example 2
942+
IoTDB:database1> select format(123, humidity) from table1 limit 1
943+
Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must have at least two arguments, and first argument pattern must be TEXT or STRING type.
944+
```
945+
946+
761947
## 8. String Functions and Operators
762948

763949
### 8.1 String operators

0 commit comments

Comments
 (0)