From 794f7b1e5a20eb332a840c62ffdb919ec887db09 Mon Sep 17 00:00:00 2001 From: Leto_b Date: Wed, 22 Apr 2026 18:00:13 +0800 Subject: [PATCH] add binary function in table from 2091 --- .../Table/SQL-Manual/Basis-Function_apache.md | 491 ++++++++--- .../SQL-Manual/Basis-Function_timecho.md | 422 ++++++++-- .../SQL-Manual/Basis-Function_apache.md | 491 ++++++++--- .../SQL-Manual/Basis-Function_timecho.md | 422 ++++++++-- .../Table/SQL-Manual/Basis-Function_apache.md | 783 +++++++++++++++--- .../SQL-Manual/Basis-Function_timecho.md | 717 ++++++++++++++-- .../SQL-Manual/Basis-Function_apache.md | 781 ++++++++++++++--- .../SQL-Manual/Basis-Function_timecho.md | 717 ++++++++++++++-- 8 files changed, 4159 insertions(+), 665 deletions(-) diff --git a/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md b/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md index 575551b3b..75635fe35 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md +++ b/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md @@ -1222,13 +1222,304 @@ IoTDB:database1> select length, width, bitwise_right_shift_arithmetic(length,wid ``` -## 7. Conditional Expressions +## 7. Binary Functions + +> Supported since V2.0.9-beta + +### 7.1 Base64 Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ----------------------------- | ----------------------------------------------------------------------------- | --------------------- | ------------- | +| `to_base64(input)` | Encode input data to standard Base64 string for binary data transmission/storage | STRING/TEXT/BLOB | STRING | +| `from_base64(input)` | Decode standard Base64 string to raw binary data (inverse of to_base64) | STRING/TEXT | BLOB | +| `to_base64url(input)` | Encode input to URL-safe Base64URL string (replace +/_, omit padding) | STRING/TEXT/BLOB | STRING | +| `from_base64url(input)` | Decode Base64URL string to raw binary data (inverse of to_base64url) | STRING/TEXT | BLOB | +| `to_base32(input)` | Encode input to Base32 string (case-insensitive, high readability) | STRING/TEXT/BLOB | STRING | +| `from_base32(input)` | Decode Base32 string to raw binary data (inverse of to_base32) | STRING/TEXT | BLOB | + +**Examples** +1. to_base64: Encode string to standard Base64 +```SQL +SELECT DISTINCT to_base64('IoTDB Binary Test') FROM table1; +``` +``` ++----------------------------+ +| _col0| ++----------------------------+ +|SW9URELkuozov5vliLbmtYvor5U=| ++----------------------------+ +``` + +2. from_base64: Decode Base64 to binary +```SQL +SELECT DISTINCT from_base64('SW9URELkuozov5vliLbmtYvor5U=') FROM table1; +``` +``` ++------------------------------------------+ +| _col0| ++------------------------------------------+ +|0x496f544442e4ba8ce8bf9be588b6e6b58be8af95| ++------------------------------------------+ +``` + +3. to_base64url: Encode to URL-safe Base64URL +```SQL +SELECT DISTINCT to_base64url('https://iotdb.apache.org') FROM table1; +``` +``` ++--------------------------------+ +| _col0| ++--------------------------------+ +|aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn| ++--------------------------------+ +``` + +4. from_base64url: Decode Base64URL +```SQL +SELECT DISTINCT from_base64url('aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn') FROM table1; +``` +``` ++--------------------------------------------------+ +| _col0| ++--------------------------------------------------+ +|0x68747470733a2f2f696f7464622e6170616368652e6f7267| ++--------------------------------------------------+ +``` + +5. to_base32: Encode to Base32 +```SQL +SELECT DISTINCT to_base32('123456') FROM table1; +``` +``` ++----------------+ +| _col0| ++----------------+ +|GEZDGNBVGY======| ++----------------+ +``` + +6. from_base32: Decode Base32 +```SQL +SELECT DISTINCT from_base32('GEZDGNBVGY======') FROM table1; +``` +``` ++--------------+ +| _col0| ++--------------+ +|0x313233343536| ++--------------+ +``` + +### 7.2 Hex Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------ | -------------------------------------------------- | --------------------- | ------------- | +| `TO_HEX(input)` | Convert input to hex string (raw byte view) | STRING/TEXT/BLOB | STRING | +| `FROM_HEX(input)` | Decode hex string to raw binary (inverse of TO_HEX) | STRING/TEXT | BLOB | + +**Examples** +1. TO_HEX: Convert string/binary to hex +```SQL +SELECT DISTINCT TO_HEX('test') FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|74657374| ++--------+ +``` + +2. FROM_HEX: Decode hex to binary +```SQL +SELECT DISTINCT FROM_HEX('74657374') FROM table1; +``` +``` ++----------+ +| _col0| ++----------+ +|0x74657374| ++----------+ +``` + +### 7.3 Basic Binary Functions +| Function Name | Description | Input Type | Output Type | +| ----------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------- | -------------- | +| `length(input)` | Return data length: chars for TEXT, bytes for BLOB/OBJECT | STRING/TEXT/BLOB/OBJECT | INT32 | +| `REVERSE(input)` | Reverse input: chars for TEXT, bytes for BLOB | STRING/TEXT/BLOB | Same as input | +| `LPAD(input, length, pad_bytes)` | Left-pad/truncate BLOB to target byte length | BLOB, INT32/INT64, BLOB | BLOB | +| `RPAD(input, length, pad_bytes)` | Right-pad/truncate BLOB to target byte length | BLOB, INT32/INT64, BLOB | BLOB | + +**Examples** +1. length: Get data length +```SQL +SELECT DISTINCT length('IoTDB') FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +| 5| ++-----+ +``` + +2. REVERSE: Reverse data +```SQL +SELECT DISTINCT REVERSE('12345') FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +|54321| ++-----+ +``` + +3. LPAD: Left-pad BLOB +```SQL +SELECT DISTINCT LPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|0x7474657374| ++------------+ +``` + +4. RPAD: Right-pad BLOB +```SQL +SELECT DISTINCT RPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|0x7465737474| ++------------+ +``` + +### 7.4 Integer Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------------- | ------------------------------------------------------------------------- | ------------ | ------------ | +| `to_big_endian_32(input)` | Convert INT32 to 4-byte big-endian BLOB (network byte order) | INT32 | BLOB | +| `to_big_endian_64(input)` | Convert INT64 to 8-byte big-endian BLOB | INT64 | BLOB | +| `from_big_endian_32(input)` | Decode 4-byte big-endian BLOB to INT32 | BLOB | INT32 | +| `from_big_endian_64(input)` | Decode 8-byte big-endian BLOB to INT64 | BLOB | INT64 | +| `to_little_endian_32(input)` | Convert INT32 to 4-byte little-endian BLOB (x86 architecture) | INT32 | BLOB | +| `to_little_endian_64(input)` | Convert INT64 to 8-byte little-endian BLOB | INT64 | BLOB | +| `from_little_endian_32(input)` | Decode 4-byte little-endian BLOB to INT32 | BLOB | INT32 | +| `from_little_endian_64(input)` | Decode 8-byte little-endian BLOB to INT64 | BLOB | INT64 | + +**Examples** +1. Big-endian encode/decode +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_32(12345)) FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|00003039| ++--------+ +``` + +2. Little-endian encode/decode +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_32(12345)) FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|39300000| ++--------+ +``` + +### 7.5 Floating-Point Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------- | ------------------------------------------------------------------------- | ------------ | ------------ | +| `to_ieee754_32(input)` | Convert FLOAT to 4-byte big-endian IEEE754 BLOB | FLOAT | BLOB | +| `to_ieee754_64(input)` | Convert DOUBLE to 8-byte big-endian IEEE754 BLOB | DOUBLE | BLOB | +| `from_ieee754_32(input)` | Decode 4-byte IEEE754 BLOB to FLOAT | BLOB | FLOAT | +| `from_ieee754_64(input)` | Decode 8-byte IEEE754 BLOB to DOUBLE | BLOB | DOUBLE | + +**Examples** +1. FLOAT encode/decode +```SQL +SELECT DISTINCT from_ieee754_32(FROM_HEX('42b40000')) FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +| 90.0| ++-----+ +``` + +2. DOUBLE encode/decode +```SQL +SELECT DISTINCT from_ieee754_64(FROM_HEX('400921fb54411744')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|3.1415926535| ++------------+ +``` + +### 7.6 Hash Functions +| Function Name | Description | Input Type | Output Type | +| --------------------------------- | ------------------------------------------------------------------------- | ------------------ | ------------- | +| `sha256(input)` | SHA-256 cryptographic hash (collision-resistant) | STRING/TEXT/BLOB | BLOB(32B) | +| `SHA512(input)` | SHA-512 cryptographic hash (higher security) | STRING/TEXT/BLOB | BLOB(64B) | +| `SHA1(input)` | SHA-1 hash (not secure for cryptography) | STRING/TEXT/BLOB | BLOB(20B) | +| `MD5(input)` | MD5 hash (non-cryptographic checksum) | STRING/TEXT/BLOB | BLOB(16B) | +| `CRC32(input)` | CRC32 checksum (fast error detection) | STRING/TEXT/BLOB | INT64 | +| `spooky_hash_v2_32(input)` | 32-bit SpookyHashV2 (high-performance non-crypto) | STRING/TEXT/BLOB | BLOB(4B) | +| `spooky_hash_v2_64(input)` | 64-bit SpookyHashV2 | STRING/TEXT/BLOB | BLOB(8B) | +| `xxhash64(input)` | 64-bit xxHash (ultra-fast) | STRING/TEXT/BLOB | BLOB(8B) | +| `murmur3(input)` | 128-bit MurmurHash3 (uniform distribution) | STRING/TEXT/BLOB | BLOB(16B) | + +**Examples** +```SQL +SELECT DISTINCT TO_HEX(sha256('test')) FROM table1; +``` +``` ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08| ++----------------------------------------------------------------+ +``` + +### 7.7 HMAC Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- | ------------- | +| `hmac_md5(data, key)` | HMAC-MD5 message authentication code | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(16B) | +| `hmac_sha1(data, key)` | HMAC-SHA1 authentication code | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(20B) | +| `hmac_sha256(data, key)` | HMAC-SHA256 (industry-recommended, high security) | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(32B) | +| `hmac_sha512(data, key)` | HMAC-SHA512 (maximum security) | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(64B) | + +**Examples** +```SQL +SELECT DISTINCT TO_HEX(hmac_sha256('user_data_123', 'iotdb_secret_key')) FROM table1; +``` +``` ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|73b6f26bbcb5192dbe2cb83745b0fc48c63418fa674b0bf62fabe7f8747f3afd| ++----------------------------------------------------------------+ +``` + + +## 8. Conditional Expressions -### 7.1 CASE +### 8.1 CASE CASE expressions come in two forms: **Simple CASE** and **Searched CASE**. -#### 7.1.1 Simple CASE +#### 8.1.1 Simple CASE The simple form evaluates each value expression from left to right until it finds a match with the given expression: @@ -1253,7 +1544,7 @@ SELECT a, END ``` -#### 7.1.2 Searched CASE +#### 8.1.2 Searched CASE The searched form evaluates each Boolean condition from left to right until a `TRUE` condition is found, then returns the corresponding result: @@ -1278,7 +1569,7 @@ SELECT a, b, END ``` -### 7.2 COALESCE +### 8.2 COALESCE Returns the first non-null value from the given list of parameters. @@ -1286,11 +1577,11 @@ Returns the first non-null value from the given list of parameters. coalesce(value1, value2[, ...]) ``` -## 8. Conversion Functions +## 9. Conversion Functions -### 8.1 Conversion Functions +### 9.1 Conversion Functions -#### 8.1.1 cast(value AS type) → type +#### 9.1.1 cast(value AS type) → type Explicitly converts a value to the specified type. This can be used to convert strings (`VARCHAR`) to numeric types or numeric values to string types. @@ -1305,7 +1596,7 @@ SELECT * IN (CAST('2024-11-27' AS DATE), CAST('2024-11-28' AS DATE)); ``` -#### 8.1.2 try_cast(value AS type) → type +#### 9.1.2 try_cast(value AS type) → type Similar to `CAST()`. If the conversion fails, returns `NULL` instead of throwing an error. @@ -1318,11 +1609,11 @@ SELECT * IN (try_cast('2024-11-27' AS DATE), try_cast('2024-11-28' AS DATE)); ``` -### 8.2 Format Function +### 9.2 Format Function 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. -#### 8.2.1 Syntax +#### 9.2.1 Syntax ```SQL format(pattern, ...args) -> STRING @@ -1332,15 +1623,15 @@ format(pattern, ...args) -> STRING * `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. * `args`: Input arguments to replace format specifiers. Constraints: - * Number of arguments ≥ 1. - * Multiple arguments must be comma-separated (e.g., `arg1, arg2`). - * Total arguments can exceed the number of specifiers in `pattern` but cannot be fewer, otherwise an exception is triggered. + * Number of arguments ≥ 1. + * Multiple arguments must be comma-separated (e.g., `arg1, arg2`). + * Total arguments can exceed the number of specifiers in `pattern` but cannot be fewer, otherwise an exception is triggered. **Return Value** * Formatted result string of type `STRING`. -#### 8.2.2 Usage Examples +#### 9.2.2 Usage Examples 1. Format Floating-Point Numbers ```SQL @@ -1449,7 +1740,7 @@ IoTDB:database1> SELECT format('%1$tF %1$tT', 2024-01-01T00:00:00.000+08:00) FRO +-----+ ``` -#### 8.2.3 Format Conversion Failure Scenarios +#### 9.2.3 Format Conversion Failure Scenarios 1. Type Mismatch Errors @@ -1457,8 +1748,8 @@ IoTDB:database1> SELECT format('%1$tF %1$tT', 2024-01-01T00:00:00.000+08:00) FRO If the format specifier includes time-related tokens (e.g., `%Y-%m-%d`) but the argument: - * Is a non-`DATE`/`TIMESTAMP` type value. ◦ - * Requires sub-day precision (e.g., `%H`, `%M`) but the argument is not `TIMESTAMP`. + * Is a non-`DATE`/`TIMESTAMP` type value. ◦ + * Requires sub-day precision (e.g., `%H`, `%M`) but the argument is not `TIMESTAMP`. ```SQL -- Example 1 @@ -1488,10 +1779,10 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %.5f ( ``` 3. Invalid Invocation Errors - Triggered if: +Triggered if: - * Total arguments < 2 (must include `pattern` and at least one argument).• - * `pattern` is not of type `STRING`/`TEXT`. +* Total arguments < 2 (must include `pattern` and at least one argument).• +* `pattern` is not of type `STRING`/`TEXT`. ```SQL -- Example 1 @@ -1504,19 +1795,19 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h ``` -## 9. String Functions and Operators +## 10. String Functions and Operators -### 9.1 String operators +### 10.1 String operators -#### 9.1.1 || Operator +#### 10.1.1 || Operator The `||` operator is used for string concatenation and functions the same as the `concat` function. -#### 9.1.2 LIKE Statement +#### 10.1.2 LIKE Statement - The `LIKE` statement is used for pattern matching. For detailed usage, refer to Pattern Matching:[LIKE](#1-like-运算符). +The `LIKE` statement is used for pattern matching. For detailed usage, refer to Pattern Matching:[LIKE](#1-like-运算符). -### 9.2 String Functions +### 10.2 String Functions | Function Name | Description | Input | Output | Usage | | :------------ |:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------| :------ | :----------------------------------------------------------- | @@ -1534,33 +1825,33 @@ The `||` operator is used for string concatenation and functions the same as the | `substring` | Extracts a substring from `start_index` to the end of the string. **Notes:** - `start_index` starts at `1`. - Returns `NULL` if input is `NULL`. - Throws an error if `start_index` is greater than string length. | `string`, `start_index` | String | substring(string from start_index)or substring(string, start_index) | | `substring` | Extracts a substring of `length` characters starting from `start_index`. **Notes:** - `start_index` starts at `1`. - Returns `NULL` if input is `NULL`. - Throws an error if `start_index` is greater than string length. - Throws an error if `length` is negative. - If `start_index + length` exceeds `int.MAX`, an overflow error may occur. | `string`, `start_index`, `length` | String | substring(string from start_index for length) or substring(string, start_index, length) | -## 10. Pattern Matching Functions +## 11. Pattern Matching Functions -### 10.1 LIKE +### 11.1 LIKE -#### 10.1.1 Usage +#### 11.1.1 Usage The `LIKE `operator is used to compare a value with a pattern. It is commonly used in the `WHERE `clause to match specific patterns within strings. -#### 10.1.2 Syntax +#### 11.1.2 Syntax ```SQL ... column [NOT] LIKE 'pattern' ESCAPE 'character'; ``` -#### 10.1.3 Match rules +#### 11.1.3 Match rules - Matching characters is case-sensitive - The pattern supports two wildcard characters: - - `_` matches any single character - - `%` matches zero or more characters + - `_` matches any single character + - `%` matches zero or more characters -#### 10.1.4 Notes +#### 11.1.4 Notes - `LIKE` pattern matching applies to the entire string by default. Therefore, if it's desired to match a sequence anywhere within a string, the pattern must start and end with a percent sign. - To match the escape character itself, double it (e.g., `\\` to match `\`). For example, you can use `\\` to match for `\`. -#### 10.1.5 Examples +#### 11.1.5 Examples #### **Example 1: Match Strings Starting with a Specific Character** @@ -1602,13 +1893,13 @@ SELECT * FROM table1 WHERE continent LIKE 'South\_%' ESCAPE '\'; SELECT * FROM table1 WHERE continent LIKE 'South\\%' ESCAPE '\'; ``` -### 10.2 regexp_like +### 11.2 regexp_like -#### 10.2.1 Usage +#### 11.2.1 Usage Evaluates whether the regular expression pattern is present within the given string. -#### 10.2.2 Syntax +#### 11.2.2 Syntax ```SQL regexp_like(string, pattern); @@ -1620,24 +1911,24 @@ regexp_like(string, pattern); - To match the entire string, use the `^` and `$` anchors. - `^` signifies the "start of the string," and `$` signifies the "end of the string." - Regular expressions use the Java-defined regular syntax, but there are the following exceptions to be aware of: - - Multiline mode - 1. Enabled by: `(?m)`. - 2. Recognizes only `\n` as the line terminator. - 3. Does not support the `(?d)` flag, and its use is prohibited. - - Case-insensitive matching - 1. Enabled by: `(?i)`. - 2. Based on Unicode rules, it does not support context-dependent and localized matching. - 3. Does not support the `(?u)` flag, and its use is prohibited. - - Character classes - 1. Within character classes (e.g., `[A-Z123]`), `\Q` and `\E` are not supported and are treated as literals. - - Unicode character classes (`\p{prop}`) - 1. Underscores in names: All underscores in names must be removed (e.g., `OldItalic `instead of `Old_Italic`). - 2. Scripts: Specify directly, without the need for `Is`, `script=`, or `sc=` prefixes (e.g., `\p{Hiragana}`). - 3. Blocks: Must use the `In` prefix, `block=` or `blk=` prefixes are not supported (e.g., `\p{InMongolian}`). - 4. Categories: Specify directly, without the need for `Is`, `general_category=`, or `gc=` prefixes (e.g., `\p{L}`). - 5. Binary properties: Specify directly, without `Is` (e.g., `\p{NoncharacterCodePoint}`). - -#### 10.2.4 Examples + - Multiline mode + 1. Enabled by: `(?m)`. + 2. Recognizes only `\n` as the line terminator. + 3. Does not support the `(?d)` flag, and its use is prohibited. + - Case-insensitive matching + 1. Enabled by: `(?i)`. + 2. Based on Unicode rules, it does not support context-dependent and localized matching. + 3. Does not support the `(?u)` flag, and its use is prohibited. + - Character classes + 1. Within character classes (e.g., `[A-Z123]`), `\Q` and `\E` are not supported and are treated as literals. + - Unicode character classes (`\p{prop}`) + 1. Underscores in names: All underscores in names must be removed (e.g., `OldItalic `instead of `Old_Italic`). + 2. Scripts: Specify directly, without the need for `Is`, `script=`, or `sc=` prefixes (e.g., `\p{Hiragana}`). + 3. Blocks: Must use the `In` prefix, `block=` or `blk=` prefixes are not supported (e.g., `\p{InMongolian}`). + 4. Categories: Specify directly, without the need for `Is`, `general_category=`, or `gc=` prefixes (e.g., `\p{L}`). + 5. Binary properties: Specify directly, without `Is` (e.g., `\p{NoncharacterCodePoint}`). + +#### 11.2.4 Examples #### Example 1: **Matching strings containing a specific pattern** @@ -1646,9 +1937,9 @@ SELECT regexp_like('1a 2b 14m', '\\d+b'); -- true ``` - **Explanation**: Determines whether the string '1a 2b 14m' contains a substring that matches the pattern `\d+b`. - - `\d+` means "one or more digits". - - `b` represents the letter b. - - In `'1a 2b 14m'`, the substring `'2b'` matches this pattern, so it returns `true`. + - `\d+` means "one or more digits". + - `b` represents the letter b. + - In `'1a 2b 14m'`, the substring `'2b'` matches this pattern, so it returns `true`. #### **Example 2: Matching the entire string** @@ -1658,11 +1949,11 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false ``` - **Explanation**: Checks if the string `'1a 2b 14m'` matches the pattern `^\\d+b$` exactly. - - `\d+` means "one or more digits". - - `b` represents the letter b. - - `'1a 2b 14m'` does not match this pattern because it does not start with digits and does not end with `b`, so it returns `false`. + - `\d+` means "one or more digits". + - `b` represents the letter b. + - `'1a 2b 14m'` does not match this pattern because it does not start with digits and does not end with `b`, so it returns `false`. -## 11. Timeseries Windowing Functions +## 12. Timeseries Windowing Functions The sample data is as follows: @@ -1685,19 +1976,19 @@ CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); ``` -### 11.1 HOP +### 12.1 HOP -#### 11.1.1 Function Description +#### 12.1.1 Function Description The HOP function segments data into overlapping time windows for analysis, assigning each row to all windows that overlap with its timestamp. If windows overlap (when SLIDE < SIZE), data will be duplicated across multiple windows. -#### 11.1.2 Function Definition +#### 12.1.2 Function Definition ```SQL HOP(data, timecol, size, slide[, origin]) ``` -#### 11.1.3 Parameter Description +#### 12.1.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | ------------------------- | @@ -1708,7 +1999,7 @@ HOP(data, timecol, size, slide[, origin]) | ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | -#### 11.1.4 Returned Results +#### 12.1.4 Returned Results The HOP function returns: @@ -1716,7 +2007,7 @@ The HOP function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.1.5 Usage Example +#### 12.1.5 Usage Example ```SQL IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); @@ -1751,18 +2042,18 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DAT +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.2 SESSION +### 12.2 SESSION -#### 11.2.1 Function Description +#### 12.2.1 Function Description The SESSION function groups data into sessions based on time intervals. It checks the time gap between consecutive rows—rows with gaps smaller than the threshold (GAP) are grouped into the current window, while larger gaps trigger a new window. -#### 11.2.2 Function Definition +#### 12.2.2 Function Definition ```SQL SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) ``` -#### 11.2.3 Parameter Description +#### 12.2.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | @@ -1770,7 +2061,7 @@ SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) | TIMECOL | Scalar | String (default: 'time') | Time column name | | GAP | Scalar | Long integer | Session gap threshold | -#### 11.2.4 Returned Results +#### 12.2.4 Returned Results The SESSION function returns: @@ -1778,7 +2069,7 @@ The SESSION function returns: * `window_end`: Time of the last row in the session * Pass-through columns: All input columns from DATA -#### 11.2.5 Usage Example +#### 12.2.5 Usage Example ```SQL IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); @@ -1804,19 +2095,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.3 VARIATION +### 12.3 VARIATION -#### 11.3.1 Function Description +#### 12.3.1 Function Description The VARIATION function groups data based on value differences. The first row becomes the baseline for the first window. Subsequent rows are compared to the baseline—if the difference is within the threshold (DELTA), they join the current window; otherwise, a new window starts with that row as the new baseline. -#### 11.3.2 Function Definition +#### 12.3.2 Function Definition ```sql VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) ``` -#### 11.3.3 Parameter Description +#### 12.3.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | @@ -1824,14 +2115,14 @@ VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) | COL | Scalar | String | Column for difference calculation | | DELTA | Scalar | Float | Difference threshold | -#### 11.3.4 Returned Results +#### 12.3.4 Returned Results The VARIATION function returns: * `window_index`: Window identifier * Pass-through columns: All input columns from DATA -#### 11.3.5 Usage Example +#### 12.3.5 Usage Example ```sql IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); @@ -1858,33 +2149,33 @@ IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, a +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.4 CAPACITY +### 12.4 CAPACITY -#### 11.4.1 Function Description +#### 12.4.1 Function Description The CAPACITY function groups data into fixed-size windows, where each window contains up to SIZE rows. -#### 11.4.2 Function Definition +#### 12.4.2 Function Definition ```sql CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) ``` -#### 11.4.3 Parameter Description +#### 12.4.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | | DATA | Table | SET SEMANTIC, PASS THROUGH | Input table with partition/sort keys | | SIZE | Scalar | Long integer | Window size (row count) | -#### 11.4.4 Returned Results +#### 12.4.4 Returned Results The CAPACITY function returns: * `window_index`: Window identifier * Pass-through columns: All input columns from DATA -#### 11.4.5 Usage Example +#### 12.4.5 Usage Example ```sql IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); @@ -1911,18 +2202,18 @@ IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(p +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.5 TUMBLE +### 12.5 TUMBLE -#### 11.5.1 Function Description +#### 12.5.1 Function Description The TUMBLE function assigns each row to a non-overlapping, fixed-size time window based on a timestamp attribute. -#### 11.5.2 Function Definition +#### 12.5.2 Function Definition ```sql TUMBLE(data, timecol, size[, origin]) ``` -#### 11.5.3 Parameter Description +#### 12.5.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | ------------------------- | @@ -1931,7 +2222,7 @@ TUMBLE(data, timecol, size[, origin]) | SIZE | Scalar | Long integer (positive) | Window size | | ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | -#### 11.5.4 Returned Results +#### 12.5.4 Returned Results The TUMBLE function returns: @@ -1939,7 +2230,7 @@ The TUMBLE function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.5.5 Usage Example +#### 12.5.5 Usage Example ```SQL IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); @@ -1965,19 +2256,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE( +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.6 CUMULATE +### 12.6 CUMULATE -#### 11.6.1 Function Description +#### 12.6.1 Function Description The CUMULATE function creates expanding windows from an initial window, maintaining the same start time while incrementally extending the end time by STEP until reaching SIZE. Each window contains all elements within its range. For example, with a 1-hour STEP and 24-hour SIZE, daily windows would be: `[00:00, 01:00)`, `[00:00, 02:00)`, ..., `[00:00, 24:00)`. -#### 11.6.2 Function Definition +#### 12.6.2 Function Definition ```sql CUMULATE(data, timecol, size, step[, origin]) ``` -#### 11.6.3 Parameter Description +#### 12.6.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | --------------------------------------------------- | @@ -1989,7 +2280,7 @@ CUMULATE(data, timecol, size, step[, origin]) > Note: An error `Cumulative table function requires size must be an integral multiple of step` occurs if SIZE is not divisible by STEP. -#### 11.6.4 Returned Results +#### 12.6.4 Returned Results The CUMULATE function returns: @@ -1997,7 +2288,7 @@ The CUMULATE function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.6.5 Usage Example +#### 12.6.5 Usage Example ```sql IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m); diff --git a/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_timecho.md b/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_timecho.md index 7f354dc89..8324e7326 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_timecho.md +++ b/src/UserGuide/Master/Table/SQL-Manual/Basis-Function_timecho.md @@ -1222,14 +1222,304 @@ IoTDB:database1> select length, width, bitwise_right_shift_arithmetic(length,wid +------+-----+-----+ ``` +## 7. Binary Functions + +> Supported since V2.0.9.1 + +### 7.1 Base64 Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ----------------------------- | ----------------------------------------------------------------------------- | --------------------- | ------------- | +| `to_base64(input)` | Encode input data to standard Base64 string for binary data transmission/storage | STRING/TEXT/BLOB | STRING | +| `from_base64(input)` | Decode standard Base64 string to raw binary data (inverse of to_base64) | STRING/TEXT | BLOB | +| `to_base64url(input)` | Encode input to URL-safe Base64URL string (replace +/_, omit padding) | STRING/TEXT/BLOB | STRING | +| `from_base64url(input)` | Decode Base64URL string to raw binary data (inverse of to_base64url) | STRING/TEXT | BLOB | +| `to_base32(input)` | Encode input to Base32 string (case-insensitive, high readability) | STRING/TEXT/BLOB | STRING | +| `from_base32(input)` | Decode Base32 string to raw binary data (inverse of to_base32) | STRING/TEXT | BLOB | + +**Examples** +1. to_base64: Encode string to standard Base64 +```SQL +SELECT DISTINCT to_base64('IoTDB Binary Test') FROM table1; +``` +``` ++----------------------------+ +| _col0| ++----------------------------+ +|SW9URELkuozov5vliLbmtYvor5U=| ++----------------------------+ +``` + +2. from_base64: Decode Base64 to binary +```SQL +SELECT DISTINCT from_base64('SW9URELkuozov5vliLbmtYvor5U=') FROM table1; +``` +``` ++------------------------------------------+ +| _col0| ++------------------------------------------+ +|0x496f544442e4ba8ce8bf9be588b6e6b58be8af95| ++------------------------------------------+ +``` + +3. to_base64url: Encode to URL-safe Base64URL +```SQL +SELECT DISTINCT to_base64url('https://iotdb.apache.org') FROM table1; +``` +``` ++--------------------------------+ +| _col0| ++--------------------------------+ +|aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn| ++--------------------------------+ +``` + +4. from_base64url: Decode Base64URL +```SQL +SELECT DISTINCT from_base64url('aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn') FROM table1; +``` +``` ++--------------------------------------------------+ +| _col0| ++--------------------------------------------------+ +|0x68747470733a2f2f696f7464622e6170616368652e6f7267| ++--------------------------------------------------+ +``` + +5. to_base32: Encode to Base32 +```SQL +SELECT DISTINCT to_base32('123456') FROM table1; +``` +``` ++----------------+ +| _col0| ++----------------+ +|GEZDGNBVGY======| ++----------------+ +``` + +6. from_base32: Decode Base32 +```SQL +SELECT DISTINCT from_base32('GEZDGNBVGY======') FROM table1; +``` +``` ++--------------+ +| _col0| ++--------------+ +|0x313233343536| ++--------------+ +``` + +### 7.2 Hex Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------ | -------------------------------------------------- | --------------------- | ------------- | +| `TO_HEX(input)` | Convert input to hex string (raw byte view) | STRING/TEXT/BLOB | STRING | +| `FROM_HEX(input)` | Decode hex string to raw binary (inverse of TO_HEX) | STRING/TEXT | BLOB | + +**Examples** +1. TO_HEX: Convert string/binary to hex +```SQL +SELECT DISTINCT TO_HEX('test') FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|74657374| ++--------+ +``` + +2. FROM_HEX: Decode hex to binary +```SQL +SELECT DISTINCT FROM_HEX('74657374') FROM table1; +``` +``` ++----------+ +| _col0| ++----------+ +|0x74657374| ++----------+ +``` + +### 7.3 Basic Binary Functions +| Function Name | Description | Input Type | Output Type | +| ----------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------- | -------------- | +| `length(input)` | Return data length: chars for TEXT, bytes for BLOB/OBJECT | STRING/TEXT/BLOB/OBJECT | INT32 | +| `REVERSE(input)` | Reverse input: chars for TEXT, bytes for BLOB | STRING/TEXT/BLOB | Same as input | +| `LPAD(input, length, pad_bytes)` | Left-pad/truncate BLOB to target byte length | BLOB, INT32/INT64, BLOB | BLOB | +| `RPAD(input, length, pad_bytes)` | Right-pad/truncate BLOB to target byte length | BLOB, INT32/INT64, BLOB | BLOB | + +**Examples** +1. length: Get data length +```SQL +SELECT DISTINCT length('IoTDB') FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +| 5| ++-----+ +``` + +2. REVERSE: Reverse data +```SQL +SELECT DISTINCT REVERSE('12345') FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +|54321| ++-----+ +``` + +3. LPAD: Left-pad BLOB +```SQL +SELECT DISTINCT LPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|0x7474657374| ++------------+ +``` + +4. RPAD: Right-pad BLOB +```SQL +SELECT DISTINCT RPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|0x7465737474| ++------------+ +``` + +### 7.4 Integer Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------------- | ------------------------------------------------------------------------- | ------------ | ------------ | +| `to_big_endian_32(input)` | Convert INT32 to 4-byte big-endian BLOB (network byte order) | INT32 | BLOB | +| `to_big_endian_64(input)` | Convert INT64 to 8-byte big-endian BLOB | INT64 | BLOB | +| `from_big_endian_32(input)` | Decode 4-byte big-endian BLOB to INT32 | BLOB | INT32 | +| `from_big_endian_64(input)` | Decode 8-byte big-endian BLOB to INT64 | BLOB | INT64 | +| `to_little_endian_32(input)` | Convert INT32 to 4-byte little-endian BLOB (x86 architecture) | INT32 | BLOB | +| `to_little_endian_64(input)` | Convert INT64 to 8-byte little-endian BLOB | INT64 | BLOB | +| `from_little_endian_32(input)` | Decode 4-byte little-endian BLOB to INT32 | BLOB | INT32 | +| `from_little_endian_64(input)` | Decode 8-byte little-endian BLOB to INT64 | BLOB | INT64 | + +**Examples** +1. Big-endian encode/decode +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_32(12345)) FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|00003039| ++--------+ +``` + +2. Little-endian encode/decode +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_32(12345)) FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|39300000| ++--------+ +``` + +### 7.5 Floating-Point Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------- | ------------------------------------------------------------------------- | ------------ | ------------ | +| `to_ieee754_32(input)` | Convert FLOAT to 4-byte big-endian IEEE754 BLOB | FLOAT | BLOB | +| `to_ieee754_64(input)` | Convert DOUBLE to 8-byte big-endian IEEE754 BLOB | DOUBLE | BLOB | +| `from_ieee754_32(input)` | Decode 4-byte IEEE754 BLOB to FLOAT | BLOB | FLOAT | +| `from_ieee754_64(input)` | Decode 8-byte IEEE754 BLOB to DOUBLE | BLOB | DOUBLE | + +**Examples** +1. FLOAT encode/decode +```SQL +SELECT DISTINCT from_ieee754_32(FROM_HEX('42b40000')) FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +| 90.0| ++-----+ +``` + +2. DOUBLE encode/decode +```SQL +SELECT DISTINCT from_ieee754_64(FROM_HEX('400921fb54411744')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|3.1415926535| ++------------+ +``` + +### 7.6 Hash Functions +| Function Name | Description | Input Type | Output Type | +| --------------------------------- | ------------------------------------------------------------------------- | ------------------ | ------------- | +| `sha256(input)` | SHA-256 cryptographic hash (collision-resistant) | STRING/TEXT/BLOB | BLOB(32B) | +| `SHA512(input)` | SHA-512 cryptographic hash (higher security) | STRING/TEXT/BLOB | BLOB(64B) | +| `SHA1(input)` | SHA-1 hash (not secure for cryptography) | STRING/TEXT/BLOB | BLOB(20B) | +| `MD5(input)` | MD5 hash (non-cryptographic checksum) | STRING/TEXT/BLOB | BLOB(16B) | +| `CRC32(input)` | CRC32 checksum (fast error detection) | STRING/TEXT/BLOB | INT64 | +| `spooky_hash_v2_32(input)` | 32-bit SpookyHashV2 (high-performance non-crypto) | STRING/TEXT/BLOB | BLOB(4B) | +| `spooky_hash_v2_64(input)` | 64-bit SpookyHashV2 | STRING/TEXT/BLOB | BLOB(8B) | +| `xxhash64(input)` | 64-bit xxHash (ultra-fast) | STRING/TEXT/BLOB | BLOB(8B) | +| `murmur3(input)` | 128-bit MurmurHash3 (uniform distribution) | STRING/TEXT/BLOB | BLOB(16B) | + +**Examples** +```SQL +SELECT DISTINCT TO_HEX(sha256('test')) FROM table1; +``` +``` ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08| ++----------------------------------------------------------------+ +``` + +### 7.7 HMAC Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- | ------------- | +| `hmac_md5(data, key)` | HMAC-MD5 message authentication code | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(16B) | +| `hmac_sha1(data, key)` | HMAC-SHA1 authentication code | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(20B) | +| `hmac_sha256(data, key)` | HMAC-SHA256 (industry-recommended, high security) | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(32B) | +| `hmac_sha512(data, key)` | HMAC-SHA512 (maximum security) | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(64B) | + +**Examples** +```SQL +SELECT DISTINCT TO_HEX(hmac_sha256('user_data_123', 'iotdb_secret_key')) FROM table1; +``` +``` ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|73b6f26bbcb5192dbe2cb83745b0fc48c63418fa674b0bf62fabe7f8747f3afd| ++----------------------------------------------------------------+ +``` + -## 7. Conditional Expressions +## 8. Conditional Expressions -### 7.1 CASE +### 8.1 CASE CASE expressions come in two forms: **Simple CASE** and **Searched CASE**. -#### 7.1.1 Simple CASE +#### 8.1.1 Simple CASE The simple form evaluates each value expression from left to right until it finds a match with the given expression: @@ -1254,7 +1544,7 @@ SELECT a, END ``` -#### 7.1.2 Searched CASE +#### 8.1.2 Searched CASE The searched form evaluates each Boolean condition from left to right until a `TRUE` condition is found, then returns the corresponding result: @@ -1279,7 +1569,7 @@ SELECT a, b, END ``` -### 7.2 COALESCE +### 8.2 COALESCE Returns the first non-null value from the given list of parameters. @@ -1287,11 +1577,11 @@ Returns the first non-null value from the given list of parameters. coalesce(value1, value2[, ...]) ``` -## 8. Conversion Functions +## 9. Conversion Functions -### 8.1 Conversion Functions +### 9.1 Conversion Functions -#### 8.1.1 cast(value AS type) → type +#### 9.1.1 cast(value AS type) → type Explicitly converts a value to the specified type. This can be used to convert strings (`VARCHAR`) to numeric types or numeric values to string types. Starting from V2.0.8, OBJECT type can be explicitly cast to STRING type. @@ -1306,7 +1596,7 @@ SELECT * IN (CAST('2024-11-27' AS DATE), CAST('2024-11-28' AS DATE)); ``` -#### 8.1.2 try_cast(value AS type) → type +#### 9.1.2 try_cast(value AS type) → type Similar to `CAST()`. If the conversion fails, returns `NULL` instead of throwing an error. @@ -1319,11 +1609,11 @@ SELECT * IN (try_cast('2024-11-27' AS DATE), try_cast('2024-11-28' AS DATE)); ``` -### 8.2 Format Function +### 9.2 Format Function 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. -#### 8.2.1 Syntax +#### 9.2.1 Syntax ```SQL format(pattern, ...args) -> STRING @@ -1341,7 +1631,7 @@ format(pattern, ...args) -> STRING * Formatted result string of type `STRING`. -#### 8.2.2 Usage Examples +#### 9.2.2 Usage Examples 1. Format Floating-Point Numbers ```SQL @@ -1450,7 +1740,7 @@ IoTDB:database1> SELECT format('%1$tF %1$tT', 2024-01-01T00:00:00.000+08:00) FRO +-----+ ``` -#### 8.2.3 Format Conversion Failure Scenarios +#### 9.2.3 Format Conversion Failure Scenarios 1. Type Mismatch Errors @@ -1505,19 +1795,19 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h ``` -## 9. String Functions and Operators +## 10. String Functions and Operators -### 9.1 String operators +### 10.1 String operators -#### 9.1.1 || Operator +#### 10.1.1 || Operator The `||` operator is used for string concatenation and functions the same as the `concat` function. -#### 9.1.2 LIKE Statement +#### 10.1.2 LIKE Statement The `LIKE` statement is used for pattern matching. For detailed usage, refer to Pattern Matching:[LIKE](#1-like-运算符). -### 9.2 String Functions +### 10.2 String Functions | Function Name | Description | Input | Output | Usage | | :------------ |:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------| :------ | :----------------------------------------------------------- | @@ -1535,33 +1825,33 @@ The `||` operator is used for string concatenation and functions the same as the | `substring` | Extracts a substring from `start_index` to the end of the string. **Notes:** - `start_index` starts at `1`. - Returns `NULL` if input is `NULL`. - Throws an error if `start_index` is greater than string length. | `string`, `start_index` | String | substring(string from start_index)or substring(string, start_index) | | `substring` | Extracts a substring of `length` characters starting from `start_index`. **Notes:** - `start_index` starts at `1`. - Returns `NULL` if input is `NULL`. - Throws an error if `start_index` is greater than string length. - Throws an error if `length` is negative. - If `start_index + length` exceeds `int.MAX`, an overflow error may occur. | `string`, `start_index`, `length` | String | substring(string from start_index for length) or substring(string, start_index, length) | -## 10. Pattern Matching Functions +## 11. Pattern Matching Functions -### 10.1 LIKE +### 11.1 LIKE -#### 10.1.1 Usage +#### 11.1.1 Usage The `LIKE `operator is used to compare a value with a pattern. It is commonly used in the `WHERE `clause to match specific patterns within strings. -#### 10.1.2 Syntax +#### 11.1.2 Syntax ```SQL ... column [NOT] LIKE 'pattern' ESCAPE 'character'; ``` -#### 10.1.3 Match rules +#### 11.1.3 Match rules - Matching characters is case-sensitive - The pattern supports two wildcard characters: - `_` matches any single character - `%` matches zero or more characters -#### 10.1.4 Notes +#### 11.1.4 Notes - `LIKE` pattern matching applies to the entire string by default. Therefore, if it's desired to match a sequence anywhere within a string, the pattern must start and end with a percent sign. - To match the escape character itself, double it (e.g., `\\` to match `\`). For example, you can use `\\` to match for `\`. -#### 10.1.5 Examples +#### 11.1.5 Examples #### **Example 1: Match Strings Starting with a Specific Character** @@ -1603,13 +1893,13 @@ SELECT * FROM table1 WHERE continent LIKE 'South\_%' ESCAPE '\'; SELECT * FROM table1 WHERE continent LIKE 'South\\%' ESCAPE '\'; ``` -### 10.2 regexp_like +### 11.2 regexp_like -#### 10.2.1 Usage +#### 11.2.1 Usage Evaluates whether the regular expression pattern is present within the given string. -#### 10.2.2 Syntax +#### 11.2.2 Syntax ```SQL regexp_like(string, pattern); @@ -1638,7 +1928,7 @@ regexp_like(string, pattern); 4. Categories: Specify directly, without the need for `Is`, `general_category=`, or `gc=` prefixes (e.g., `\p{L}`). 5. Binary properties: Specify directly, without `Is` (e.g., `\p{NoncharacterCodePoint}`). -#### 10.2.4 Examples +#### 11.2.4 Examples #### Example 1: **Matching strings containing a specific pattern** @@ -1663,7 +1953,7 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false - `b` represents the letter b. - `'1a 2b 14m'` does not match this pattern because it does not start with digits and does not end with `b`, so it returns `false`. -## 11. Timeseries Windowing Functions +## 12. Timeseries Windowing Functions The sample data is as follows: @@ -1686,19 +1976,19 @@ CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); ``` -### 11.1 HOP +### 12.1 HOP -#### 11.1.1 Function Description +#### 12.1.1 Function Description The HOP function segments data into overlapping time windows for analysis, assigning each row to all windows that overlap with its timestamp. If windows overlap (when SLIDE < SIZE), data will be duplicated across multiple windows. -#### 11.1.2 Function Definition +#### 12.1.2 Function Definition ```SQL HOP(data, timecol, size, slide[, origin]) ``` -#### 11.1.3 Parameter Description +#### 12.1.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | ------------------------- | @@ -1709,7 +1999,7 @@ HOP(data, timecol, size, slide[, origin]) | ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | -#### 11.1.4 Returned Results +#### 12.1.4 Returned Results The HOP function returns: @@ -1717,7 +2007,7 @@ The HOP function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.1.5 Usage Example +#### 12.1.5 Usage Example ```SQL IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); @@ -1752,18 +2042,18 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DAT +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.2 SESSION +### 12.2 SESSION -#### 11.2.1 Function Description +#### 12.2.1 Function Description The SESSION function groups data into sessions based on time intervals. It checks the time gap between consecutive rows—rows with gaps smaller than the threshold (GAP) are grouped into the current window, while larger gaps trigger a new window. -#### 11.2.2 Function Definition +#### 12.2.2 Function Definition ```SQL SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) ``` -#### 11.2.3 Parameter Description +#### 12.2.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | @@ -1771,7 +2061,7 @@ SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) | TIMECOL | Scalar | String (default: 'time') | Time column name | | GAP | Scalar | Long integer | Session gap threshold | -#### 11.2.4 Returned Results +#### 12.2.4 Returned Results The SESSION function returns: @@ -1779,7 +2069,7 @@ The SESSION function returns: * `window_end`: Time of the last row in the session * Pass-through columns: All input columns from DATA -#### 11.2.5 Usage Example +#### 12.2.5 Usage Example ```SQL IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); @@ -1805,19 +2095,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.3 VARIATION +### 12.3 VARIATION -#### 11.3.1 Function Description +#### 12.3.1 Function Description The VARIATION function groups data based on value differences. The first row becomes the baseline for the first window. Subsequent rows are compared to the baseline—if the difference is within the threshold (DELTA), they join the current window; otherwise, a new window starts with that row as the new baseline. -#### 11.3.2 Function Definition +#### 12.3.2 Function Definition ```sql VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) ``` -#### 11.3.3 Parameter Description +#### 12.3.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | @@ -1825,14 +2115,14 @@ VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) | COL | Scalar | String | Column for difference calculation | | DELTA | Scalar | Float | Difference threshold | -#### 11.3.4 Returned Results +#### 12.3.4 Returned Results The VARIATION function returns: * `window_index`: Window identifier * Pass-through columns: All input columns from DATA -#### 11.3.5 Usage Example +#### 12.3.5 Usage Example ```sql IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); @@ -1859,33 +2149,33 @@ IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, a +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.4 CAPACITY +### 12.4 CAPACITY -#### 11.4.1 Function Description +#### 12.4.1 Function Description The CAPACITY function groups data into fixed-size windows, where each window contains up to SIZE rows. -#### 11.4.2 Function Definition +#### 12.4.2 Function Definition ```sql CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) ``` -#### 11.4.3 Parameter Description +#### 12.4.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | | DATA | Table | SET SEMANTIC, PASS THROUGH | Input table with partition/sort keys | | SIZE | Scalar | Long integer | Window size (row count) | -#### 11.4.4 Returned Results +#### 12.4.4 Returned Results The CAPACITY function returns: * `window_index`: Window identifier * Pass-through columns: All input columns from DATA -#### 11.4.5 Usage Example +#### 12.4.5 Usage Example ```sql IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); @@ -1912,18 +2202,18 @@ IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(p +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.5 TUMBLE +### 12.5 TUMBLE -#### 11.5.1 Function Description +#### 12.5.1 Function Description The TUMBLE function assigns each row to a non-overlapping, fixed-size time window based on a timestamp attribute. -#### 11.5.2 Function Definition +#### 12.5.2 Function Definition ```sql TUMBLE(data, timecol, size[, origin]) ``` -#### 11.5.3 Parameter Description +#### 12.5.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | ------------------------- | @@ -1932,7 +2222,7 @@ TUMBLE(data, timecol, size[, origin]) | SIZE | Scalar | Long integer (positive) | Window size | | ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | -#### 11.5.4 Returned Results +#### 12.5.4 Returned Results The TUMBLE function returns: @@ -1940,7 +2230,7 @@ The TUMBLE function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.5.5 Usage Example +#### 12.5.5 Usage Example ```SQL IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); @@ -1966,19 +2256,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE( +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.6 CUMULATE +### 12.6 CUMULATE -#### 11.6.1 Function Description +#### 12.6.1 Function Description The CUMULATE function creates expanding windows from an initial window, maintaining the same start time while incrementally extending the end time by STEP until reaching SIZE. Each window contains all elements within its range. For example, with a 1-hour STEP and 24-hour SIZE, daily windows would be: `[00:00, 01:00)`, `[00:00, 02:00)`, ..., `[00:00, 24:00)`. -#### 11.6.2 Function Definition +#### 12.6.2 Function Definition ```sql CUMULATE(data, timecol, size, step[, origin]) ``` -#### 11.6.3 Parameter Description +#### 12.6.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | --------------------------------------------------- | @@ -1990,7 +2280,7 @@ CUMULATE(data, timecol, size, step[, origin]) > Note: An error `Cumulative table function requires size must be an integral multiple of step` occurs if SIZE is not divisible by STEP. -#### 11.6.4 Returned Results +#### 12.6.4 Returned Results The CUMULATE function returns: @@ -1998,7 +2288,7 @@ The CUMULATE function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.6.5 Usage Example +#### 12.6.5 Usage Example ```sql IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m); diff --git a/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md b/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md index 575551b3b..75635fe35 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md +++ b/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md @@ -1222,13 +1222,304 @@ IoTDB:database1> select length, width, bitwise_right_shift_arithmetic(length,wid ``` -## 7. Conditional Expressions +## 7. Binary Functions + +> Supported since V2.0.9-beta + +### 7.1 Base64 Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ----------------------------- | ----------------------------------------------------------------------------- | --------------------- | ------------- | +| `to_base64(input)` | Encode input data to standard Base64 string for binary data transmission/storage | STRING/TEXT/BLOB | STRING | +| `from_base64(input)` | Decode standard Base64 string to raw binary data (inverse of to_base64) | STRING/TEXT | BLOB | +| `to_base64url(input)` | Encode input to URL-safe Base64URL string (replace +/_, omit padding) | STRING/TEXT/BLOB | STRING | +| `from_base64url(input)` | Decode Base64URL string to raw binary data (inverse of to_base64url) | STRING/TEXT | BLOB | +| `to_base32(input)` | Encode input to Base32 string (case-insensitive, high readability) | STRING/TEXT/BLOB | STRING | +| `from_base32(input)` | Decode Base32 string to raw binary data (inverse of to_base32) | STRING/TEXT | BLOB | + +**Examples** +1. to_base64: Encode string to standard Base64 +```SQL +SELECT DISTINCT to_base64('IoTDB Binary Test') FROM table1; +``` +``` ++----------------------------+ +| _col0| ++----------------------------+ +|SW9URELkuozov5vliLbmtYvor5U=| ++----------------------------+ +``` + +2. from_base64: Decode Base64 to binary +```SQL +SELECT DISTINCT from_base64('SW9URELkuozov5vliLbmtYvor5U=') FROM table1; +``` +``` ++------------------------------------------+ +| _col0| ++------------------------------------------+ +|0x496f544442e4ba8ce8bf9be588b6e6b58be8af95| ++------------------------------------------+ +``` + +3. to_base64url: Encode to URL-safe Base64URL +```SQL +SELECT DISTINCT to_base64url('https://iotdb.apache.org') FROM table1; +``` +``` ++--------------------------------+ +| _col0| ++--------------------------------+ +|aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn| ++--------------------------------+ +``` + +4. from_base64url: Decode Base64URL +```SQL +SELECT DISTINCT from_base64url('aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn') FROM table1; +``` +``` ++--------------------------------------------------+ +| _col0| ++--------------------------------------------------+ +|0x68747470733a2f2f696f7464622e6170616368652e6f7267| ++--------------------------------------------------+ +``` + +5. to_base32: Encode to Base32 +```SQL +SELECT DISTINCT to_base32('123456') FROM table1; +``` +``` ++----------------+ +| _col0| ++----------------+ +|GEZDGNBVGY======| ++----------------+ +``` + +6. from_base32: Decode Base32 +```SQL +SELECT DISTINCT from_base32('GEZDGNBVGY======') FROM table1; +``` +``` ++--------------+ +| _col0| ++--------------+ +|0x313233343536| ++--------------+ +``` + +### 7.2 Hex Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------ | -------------------------------------------------- | --------------------- | ------------- | +| `TO_HEX(input)` | Convert input to hex string (raw byte view) | STRING/TEXT/BLOB | STRING | +| `FROM_HEX(input)` | Decode hex string to raw binary (inverse of TO_HEX) | STRING/TEXT | BLOB | + +**Examples** +1. TO_HEX: Convert string/binary to hex +```SQL +SELECT DISTINCT TO_HEX('test') FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|74657374| ++--------+ +``` + +2. FROM_HEX: Decode hex to binary +```SQL +SELECT DISTINCT FROM_HEX('74657374') FROM table1; +``` +``` ++----------+ +| _col0| ++----------+ +|0x74657374| ++----------+ +``` + +### 7.3 Basic Binary Functions +| Function Name | Description | Input Type | Output Type | +| ----------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------- | -------------- | +| `length(input)` | Return data length: chars for TEXT, bytes for BLOB/OBJECT | STRING/TEXT/BLOB/OBJECT | INT32 | +| `REVERSE(input)` | Reverse input: chars for TEXT, bytes for BLOB | STRING/TEXT/BLOB | Same as input | +| `LPAD(input, length, pad_bytes)` | Left-pad/truncate BLOB to target byte length | BLOB, INT32/INT64, BLOB | BLOB | +| `RPAD(input, length, pad_bytes)` | Right-pad/truncate BLOB to target byte length | BLOB, INT32/INT64, BLOB | BLOB | + +**Examples** +1. length: Get data length +```SQL +SELECT DISTINCT length('IoTDB') FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +| 5| ++-----+ +``` + +2. REVERSE: Reverse data +```SQL +SELECT DISTINCT REVERSE('12345') FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +|54321| ++-----+ +``` + +3. LPAD: Left-pad BLOB +```SQL +SELECT DISTINCT LPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|0x7474657374| ++------------+ +``` + +4. RPAD: Right-pad BLOB +```SQL +SELECT DISTINCT RPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|0x7465737474| ++------------+ +``` + +### 7.4 Integer Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------------- | ------------------------------------------------------------------------- | ------------ | ------------ | +| `to_big_endian_32(input)` | Convert INT32 to 4-byte big-endian BLOB (network byte order) | INT32 | BLOB | +| `to_big_endian_64(input)` | Convert INT64 to 8-byte big-endian BLOB | INT64 | BLOB | +| `from_big_endian_32(input)` | Decode 4-byte big-endian BLOB to INT32 | BLOB | INT32 | +| `from_big_endian_64(input)` | Decode 8-byte big-endian BLOB to INT64 | BLOB | INT64 | +| `to_little_endian_32(input)` | Convert INT32 to 4-byte little-endian BLOB (x86 architecture) | INT32 | BLOB | +| `to_little_endian_64(input)` | Convert INT64 to 8-byte little-endian BLOB | INT64 | BLOB | +| `from_little_endian_32(input)` | Decode 4-byte little-endian BLOB to INT32 | BLOB | INT32 | +| `from_little_endian_64(input)` | Decode 8-byte little-endian BLOB to INT64 | BLOB | INT64 | + +**Examples** +1. Big-endian encode/decode +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_32(12345)) FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|00003039| ++--------+ +``` + +2. Little-endian encode/decode +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_32(12345)) FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|39300000| ++--------+ +``` + +### 7.5 Floating-Point Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------- | ------------------------------------------------------------------------- | ------------ | ------------ | +| `to_ieee754_32(input)` | Convert FLOAT to 4-byte big-endian IEEE754 BLOB | FLOAT | BLOB | +| `to_ieee754_64(input)` | Convert DOUBLE to 8-byte big-endian IEEE754 BLOB | DOUBLE | BLOB | +| `from_ieee754_32(input)` | Decode 4-byte IEEE754 BLOB to FLOAT | BLOB | FLOAT | +| `from_ieee754_64(input)` | Decode 8-byte IEEE754 BLOB to DOUBLE | BLOB | DOUBLE | + +**Examples** +1. FLOAT encode/decode +```SQL +SELECT DISTINCT from_ieee754_32(FROM_HEX('42b40000')) FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +| 90.0| ++-----+ +``` + +2. DOUBLE encode/decode +```SQL +SELECT DISTINCT from_ieee754_64(FROM_HEX('400921fb54411744')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|3.1415926535| ++------------+ +``` + +### 7.6 Hash Functions +| Function Name | Description | Input Type | Output Type | +| --------------------------------- | ------------------------------------------------------------------------- | ------------------ | ------------- | +| `sha256(input)` | SHA-256 cryptographic hash (collision-resistant) | STRING/TEXT/BLOB | BLOB(32B) | +| `SHA512(input)` | SHA-512 cryptographic hash (higher security) | STRING/TEXT/BLOB | BLOB(64B) | +| `SHA1(input)` | SHA-1 hash (not secure for cryptography) | STRING/TEXT/BLOB | BLOB(20B) | +| `MD5(input)` | MD5 hash (non-cryptographic checksum) | STRING/TEXT/BLOB | BLOB(16B) | +| `CRC32(input)` | CRC32 checksum (fast error detection) | STRING/TEXT/BLOB | INT64 | +| `spooky_hash_v2_32(input)` | 32-bit SpookyHashV2 (high-performance non-crypto) | STRING/TEXT/BLOB | BLOB(4B) | +| `spooky_hash_v2_64(input)` | 64-bit SpookyHashV2 | STRING/TEXT/BLOB | BLOB(8B) | +| `xxhash64(input)` | 64-bit xxHash (ultra-fast) | STRING/TEXT/BLOB | BLOB(8B) | +| `murmur3(input)` | 128-bit MurmurHash3 (uniform distribution) | STRING/TEXT/BLOB | BLOB(16B) | + +**Examples** +```SQL +SELECT DISTINCT TO_HEX(sha256('test')) FROM table1; +``` +``` ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08| ++----------------------------------------------------------------+ +``` + +### 7.7 HMAC Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- | ------------- | +| `hmac_md5(data, key)` | HMAC-MD5 message authentication code | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(16B) | +| `hmac_sha1(data, key)` | HMAC-SHA1 authentication code | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(20B) | +| `hmac_sha256(data, key)` | HMAC-SHA256 (industry-recommended, high security) | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(32B) | +| `hmac_sha512(data, key)` | HMAC-SHA512 (maximum security) | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(64B) | + +**Examples** +```SQL +SELECT DISTINCT TO_HEX(hmac_sha256('user_data_123', 'iotdb_secret_key')) FROM table1; +``` +``` ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|73b6f26bbcb5192dbe2cb83745b0fc48c63418fa674b0bf62fabe7f8747f3afd| ++----------------------------------------------------------------+ +``` + + +## 8. Conditional Expressions -### 7.1 CASE +### 8.1 CASE CASE expressions come in two forms: **Simple CASE** and **Searched CASE**. -#### 7.1.1 Simple CASE +#### 8.1.1 Simple CASE The simple form evaluates each value expression from left to right until it finds a match with the given expression: @@ -1253,7 +1544,7 @@ SELECT a, END ``` -#### 7.1.2 Searched CASE +#### 8.1.2 Searched CASE The searched form evaluates each Boolean condition from left to right until a `TRUE` condition is found, then returns the corresponding result: @@ -1278,7 +1569,7 @@ SELECT a, b, END ``` -### 7.2 COALESCE +### 8.2 COALESCE Returns the first non-null value from the given list of parameters. @@ -1286,11 +1577,11 @@ Returns the first non-null value from the given list of parameters. coalesce(value1, value2[, ...]) ``` -## 8. Conversion Functions +## 9. Conversion Functions -### 8.1 Conversion Functions +### 9.1 Conversion Functions -#### 8.1.1 cast(value AS type) → type +#### 9.1.1 cast(value AS type) → type Explicitly converts a value to the specified type. This can be used to convert strings (`VARCHAR`) to numeric types or numeric values to string types. @@ -1305,7 +1596,7 @@ SELECT * IN (CAST('2024-11-27' AS DATE), CAST('2024-11-28' AS DATE)); ``` -#### 8.1.2 try_cast(value AS type) → type +#### 9.1.2 try_cast(value AS type) → type Similar to `CAST()`. If the conversion fails, returns `NULL` instead of throwing an error. @@ -1318,11 +1609,11 @@ SELECT * IN (try_cast('2024-11-27' AS DATE), try_cast('2024-11-28' AS DATE)); ``` -### 8.2 Format Function +### 9.2 Format Function 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. -#### 8.2.1 Syntax +#### 9.2.1 Syntax ```SQL format(pattern, ...args) -> STRING @@ -1332,15 +1623,15 @@ format(pattern, ...args) -> STRING * `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. * `args`: Input arguments to replace format specifiers. Constraints: - * Number of arguments ≥ 1. - * Multiple arguments must be comma-separated (e.g., `arg1, arg2`). - * Total arguments can exceed the number of specifiers in `pattern` but cannot be fewer, otherwise an exception is triggered. + * Number of arguments ≥ 1. + * Multiple arguments must be comma-separated (e.g., `arg1, arg2`). + * Total arguments can exceed the number of specifiers in `pattern` but cannot be fewer, otherwise an exception is triggered. **Return Value** * Formatted result string of type `STRING`. -#### 8.2.2 Usage Examples +#### 9.2.2 Usage Examples 1. Format Floating-Point Numbers ```SQL @@ -1449,7 +1740,7 @@ IoTDB:database1> SELECT format('%1$tF %1$tT', 2024-01-01T00:00:00.000+08:00) FRO +-----+ ``` -#### 8.2.3 Format Conversion Failure Scenarios +#### 9.2.3 Format Conversion Failure Scenarios 1. Type Mismatch Errors @@ -1457,8 +1748,8 @@ IoTDB:database1> SELECT format('%1$tF %1$tT', 2024-01-01T00:00:00.000+08:00) FRO If the format specifier includes time-related tokens (e.g., `%Y-%m-%d`) but the argument: - * Is a non-`DATE`/`TIMESTAMP` type value. ◦ - * Requires sub-day precision (e.g., `%H`, `%M`) but the argument is not `TIMESTAMP`. + * Is a non-`DATE`/`TIMESTAMP` type value. ◦ + * Requires sub-day precision (e.g., `%H`, `%M`) but the argument is not `TIMESTAMP`. ```SQL -- Example 1 @@ -1488,10 +1779,10 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %.5f ( ``` 3. Invalid Invocation Errors - Triggered if: +Triggered if: - * Total arguments < 2 (must include `pattern` and at least one argument).• - * `pattern` is not of type `STRING`/`TEXT`. +* Total arguments < 2 (must include `pattern` and at least one argument).• +* `pattern` is not of type `STRING`/`TEXT`. ```SQL -- Example 1 @@ -1504,19 +1795,19 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h ``` -## 9. String Functions and Operators +## 10. String Functions and Operators -### 9.1 String operators +### 10.1 String operators -#### 9.1.1 || Operator +#### 10.1.1 || Operator The `||` operator is used for string concatenation and functions the same as the `concat` function. -#### 9.1.2 LIKE Statement +#### 10.1.2 LIKE Statement - The `LIKE` statement is used for pattern matching. For detailed usage, refer to Pattern Matching:[LIKE](#1-like-运算符). +The `LIKE` statement is used for pattern matching. For detailed usage, refer to Pattern Matching:[LIKE](#1-like-运算符). -### 9.2 String Functions +### 10.2 String Functions | Function Name | Description | Input | Output | Usage | | :------------ |:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------| :------ | :----------------------------------------------------------- | @@ -1534,33 +1825,33 @@ The `||` operator is used for string concatenation and functions the same as the | `substring` | Extracts a substring from `start_index` to the end of the string. **Notes:** - `start_index` starts at `1`. - Returns `NULL` if input is `NULL`. - Throws an error if `start_index` is greater than string length. | `string`, `start_index` | String | substring(string from start_index)or substring(string, start_index) | | `substring` | Extracts a substring of `length` characters starting from `start_index`. **Notes:** - `start_index` starts at `1`. - Returns `NULL` if input is `NULL`. - Throws an error if `start_index` is greater than string length. - Throws an error if `length` is negative. - If `start_index + length` exceeds `int.MAX`, an overflow error may occur. | `string`, `start_index`, `length` | String | substring(string from start_index for length) or substring(string, start_index, length) | -## 10. Pattern Matching Functions +## 11. Pattern Matching Functions -### 10.1 LIKE +### 11.1 LIKE -#### 10.1.1 Usage +#### 11.1.1 Usage The `LIKE `operator is used to compare a value with a pattern. It is commonly used in the `WHERE `clause to match specific patterns within strings. -#### 10.1.2 Syntax +#### 11.1.2 Syntax ```SQL ... column [NOT] LIKE 'pattern' ESCAPE 'character'; ``` -#### 10.1.3 Match rules +#### 11.1.3 Match rules - Matching characters is case-sensitive - The pattern supports two wildcard characters: - - `_` matches any single character - - `%` matches zero or more characters + - `_` matches any single character + - `%` matches zero or more characters -#### 10.1.4 Notes +#### 11.1.4 Notes - `LIKE` pattern matching applies to the entire string by default. Therefore, if it's desired to match a sequence anywhere within a string, the pattern must start and end with a percent sign. - To match the escape character itself, double it (e.g., `\\` to match `\`). For example, you can use `\\` to match for `\`. -#### 10.1.5 Examples +#### 11.1.5 Examples #### **Example 1: Match Strings Starting with a Specific Character** @@ -1602,13 +1893,13 @@ SELECT * FROM table1 WHERE continent LIKE 'South\_%' ESCAPE '\'; SELECT * FROM table1 WHERE continent LIKE 'South\\%' ESCAPE '\'; ``` -### 10.2 regexp_like +### 11.2 regexp_like -#### 10.2.1 Usage +#### 11.2.1 Usage Evaluates whether the regular expression pattern is present within the given string. -#### 10.2.2 Syntax +#### 11.2.2 Syntax ```SQL regexp_like(string, pattern); @@ -1620,24 +1911,24 @@ regexp_like(string, pattern); - To match the entire string, use the `^` and `$` anchors. - `^` signifies the "start of the string," and `$` signifies the "end of the string." - Regular expressions use the Java-defined regular syntax, but there are the following exceptions to be aware of: - - Multiline mode - 1. Enabled by: `(?m)`. - 2. Recognizes only `\n` as the line terminator. - 3. Does not support the `(?d)` flag, and its use is prohibited. - - Case-insensitive matching - 1. Enabled by: `(?i)`. - 2. Based on Unicode rules, it does not support context-dependent and localized matching. - 3. Does not support the `(?u)` flag, and its use is prohibited. - - Character classes - 1. Within character classes (e.g., `[A-Z123]`), `\Q` and `\E` are not supported and are treated as literals. - - Unicode character classes (`\p{prop}`) - 1. Underscores in names: All underscores in names must be removed (e.g., `OldItalic `instead of `Old_Italic`). - 2. Scripts: Specify directly, without the need for `Is`, `script=`, or `sc=` prefixes (e.g., `\p{Hiragana}`). - 3. Blocks: Must use the `In` prefix, `block=` or `blk=` prefixes are not supported (e.g., `\p{InMongolian}`). - 4. Categories: Specify directly, without the need for `Is`, `general_category=`, or `gc=` prefixes (e.g., `\p{L}`). - 5. Binary properties: Specify directly, without `Is` (e.g., `\p{NoncharacterCodePoint}`). - -#### 10.2.4 Examples + - Multiline mode + 1. Enabled by: `(?m)`. + 2. Recognizes only `\n` as the line terminator. + 3. Does not support the `(?d)` flag, and its use is prohibited. + - Case-insensitive matching + 1. Enabled by: `(?i)`. + 2. Based on Unicode rules, it does not support context-dependent and localized matching. + 3. Does not support the `(?u)` flag, and its use is prohibited. + - Character classes + 1. Within character classes (e.g., `[A-Z123]`), `\Q` and `\E` are not supported and are treated as literals. + - Unicode character classes (`\p{prop}`) + 1. Underscores in names: All underscores in names must be removed (e.g., `OldItalic `instead of `Old_Italic`). + 2. Scripts: Specify directly, without the need for `Is`, `script=`, or `sc=` prefixes (e.g., `\p{Hiragana}`). + 3. Blocks: Must use the `In` prefix, `block=` or `blk=` prefixes are not supported (e.g., `\p{InMongolian}`). + 4. Categories: Specify directly, without the need for `Is`, `general_category=`, or `gc=` prefixes (e.g., `\p{L}`). + 5. Binary properties: Specify directly, without `Is` (e.g., `\p{NoncharacterCodePoint}`). + +#### 11.2.4 Examples #### Example 1: **Matching strings containing a specific pattern** @@ -1646,9 +1937,9 @@ SELECT regexp_like('1a 2b 14m', '\\d+b'); -- true ``` - **Explanation**: Determines whether the string '1a 2b 14m' contains a substring that matches the pattern `\d+b`. - - `\d+` means "one or more digits". - - `b` represents the letter b. - - In `'1a 2b 14m'`, the substring `'2b'` matches this pattern, so it returns `true`. + - `\d+` means "one or more digits". + - `b` represents the letter b. + - In `'1a 2b 14m'`, the substring `'2b'` matches this pattern, so it returns `true`. #### **Example 2: Matching the entire string** @@ -1658,11 +1949,11 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false ``` - **Explanation**: Checks if the string `'1a 2b 14m'` matches the pattern `^\\d+b$` exactly. - - `\d+` means "one or more digits". - - `b` represents the letter b. - - `'1a 2b 14m'` does not match this pattern because it does not start with digits and does not end with `b`, so it returns `false`. + - `\d+` means "one or more digits". + - `b` represents the letter b. + - `'1a 2b 14m'` does not match this pattern because it does not start with digits and does not end with `b`, so it returns `false`. -## 11. Timeseries Windowing Functions +## 12. Timeseries Windowing Functions The sample data is as follows: @@ -1685,19 +1976,19 @@ CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); ``` -### 11.1 HOP +### 12.1 HOP -#### 11.1.1 Function Description +#### 12.1.1 Function Description The HOP function segments data into overlapping time windows for analysis, assigning each row to all windows that overlap with its timestamp. If windows overlap (when SLIDE < SIZE), data will be duplicated across multiple windows. -#### 11.1.2 Function Definition +#### 12.1.2 Function Definition ```SQL HOP(data, timecol, size, slide[, origin]) ``` -#### 11.1.3 Parameter Description +#### 12.1.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | ------------------------- | @@ -1708,7 +1999,7 @@ HOP(data, timecol, size, slide[, origin]) | ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | -#### 11.1.4 Returned Results +#### 12.1.4 Returned Results The HOP function returns: @@ -1716,7 +2007,7 @@ The HOP function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.1.5 Usage Example +#### 12.1.5 Usage Example ```SQL IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); @@ -1751,18 +2042,18 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DAT +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.2 SESSION +### 12.2 SESSION -#### 11.2.1 Function Description +#### 12.2.1 Function Description The SESSION function groups data into sessions based on time intervals. It checks the time gap between consecutive rows—rows with gaps smaller than the threshold (GAP) are grouped into the current window, while larger gaps trigger a new window. -#### 11.2.2 Function Definition +#### 12.2.2 Function Definition ```SQL SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) ``` -#### 11.2.3 Parameter Description +#### 12.2.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | @@ -1770,7 +2061,7 @@ SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) | TIMECOL | Scalar | String (default: 'time') | Time column name | | GAP | Scalar | Long integer | Session gap threshold | -#### 11.2.4 Returned Results +#### 12.2.4 Returned Results The SESSION function returns: @@ -1778,7 +2069,7 @@ The SESSION function returns: * `window_end`: Time of the last row in the session * Pass-through columns: All input columns from DATA -#### 11.2.5 Usage Example +#### 12.2.5 Usage Example ```SQL IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); @@ -1804,19 +2095,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.3 VARIATION +### 12.3 VARIATION -#### 11.3.1 Function Description +#### 12.3.1 Function Description The VARIATION function groups data based on value differences. The first row becomes the baseline for the first window. Subsequent rows are compared to the baseline—if the difference is within the threshold (DELTA), they join the current window; otherwise, a new window starts with that row as the new baseline. -#### 11.3.2 Function Definition +#### 12.3.2 Function Definition ```sql VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) ``` -#### 11.3.3 Parameter Description +#### 12.3.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | @@ -1824,14 +2115,14 @@ VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) | COL | Scalar | String | Column for difference calculation | | DELTA | Scalar | Float | Difference threshold | -#### 11.3.4 Returned Results +#### 12.3.4 Returned Results The VARIATION function returns: * `window_index`: Window identifier * Pass-through columns: All input columns from DATA -#### 11.3.5 Usage Example +#### 12.3.5 Usage Example ```sql IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); @@ -1858,33 +2149,33 @@ IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, a +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.4 CAPACITY +### 12.4 CAPACITY -#### 11.4.1 Function Description +#### 12.4.1 Function Description The CAPACITY function groups data into fixed-size windows, where each window contains up to SIZE rows. -#### 11.4.2 Function Definition +#### 12.4.2 Function Definition ```sql CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) ``` -#### 11.4.3 Parameter Description +#### 12.4.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | | DATA | Table | SET SEMANTIC, PASS THROUGH | Input table with partition/sort keys | | SIZE | Scalar | Long integer | Window size (row count) | -#### 11.4.4 Returned Results +#### 12.4.4 Returned Results The CAPACITY function returns: * `window_index`: Window identifier * Pass-through columns: All input columns from DATA -#### 11.4.5 Usage Example +#### 12.4.5 Usage Example ```sql IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); @@ -1911,18 +2202,18 @@ IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(p +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.5 TUMBLE +### 12.5 TUMBLE -#### 11.5.1 Function Description +#### 12.5.1 Function Description The TUMBLE function assigns each row to a non-overlapping, fixed-size time window based on a timestamp attribute. -#### 11.5.2 Function Definition +#### 12.5.2 Function Definition ```sql TUMBLE(data, timecol, size[, origin]) ``` -#### 11.5.3 Parameter Description +#### 12.5.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | ------------------------- | @@ -1931,7 +2222,7 @@ TUMBLE(data, timecol, size[, origin]) | SIZE | Scalar | Long integer (positive) | Window size | | ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | -#### 11.5.4 Returned Results +#### 12.5.4 Returned Results The TUMBLE function returns: @@ -1939,7 +2230,7 @@ The TUMBLE function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.5.5 Usage Example +#### 12.5.5 Usage Example ```SQL IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); @@ -1965,19 +2256,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE( +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.6 CUMULATE +### 12.6 CUMULATE -#### 11.6.1 Function Description +#### 12.6.1 Function Description The CUMULATE function creates expanding windows from an initial window, maintaining the same start time while incrementally extending the end time by STEP until reaching SIZE. Each window contains all elements within its range. For example, with a 1-hour STEP and 24-hour SIZE, daily windows would be: `[00:00, 01:00)`, `[00:00, 02:00)`, ..., `[00:00, 24:00)`. -#### 11.6.2 Function Definition +#### 12.6.2 Function Definition ```sql CUMULATE(data, timecol, size, step[, origin]) ``` -#### 11.6.3 Parameter Description +#### 12.6.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | --------------------------------------------------- | @@ -1989,7 +2280,7 @@ CUMULATE(data, timecol, size, step[, origin]) > Note: An error `Cumulative table function requires size must be an integral multiple of step` occurs if SIZE is not divisible by STEP. -#### 11.6.4 Returned Results +#### 12.6.4 Returned Results The CUMULATE function returns: @@ -1997,7 +2288,7 @@ The CUMULATE function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.6.5 Usage Example +#### 12.6.5 Usage Example ```sql IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m); diff --git a/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_timecho.md b/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_timecho.md index 7f354dc89..8324e7326 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_timecho.md +++ b/src/UserGuide/latest-Table/SQL-Manual/Basis-Function_timecho.md @@ -1222,14 +1222,304 @@ IoTDB:database1> select length, width, bitwise_right_shift_arithmetic(length,wid +------+-----+-----+ ``` +## 7. Binary Functions + +> Supported since V2.0.9.1 + +### 7.1 Base64 Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ----------------------------- | ----------------------------------------------------------------------------- | --------------------- | ------------- | +| `to_base64(input)` | Encode input data to standard Base64 string for binary data transmission/storage | STRING/TEXT/BLOB | STRING | +| `from_base64(input)` | Decode standard Base64 string to raw binary data (inverse of to_base64) | STRING/TEXT | BLOB | +| `to_base64url(input)` | Encode input to URL-safe Base64URL string (replace +/_, omit padding) | STRING/TEXT/BLOB | STRING | +| `from_base64url(input)` | Decode Base64URL string to raw binary data (inverse of to_base64url) | STRING/TEXT | BLOB | +| `to_base32(input)` | Encode input to Base32 string (case-insensitive, high readability) | STRING/TEXT/BLOB | STRING | +| `from_base32(input)` | Decode Base32 string to raw binary data (inverse of to_base32) | STRING/TEXT | BLOB | + +**Examples** +1. to_base64: Encode string to standard Base64 +```SQL +SELECT DISTINCT to_base64('IoTDB Binary Test') FROM table1; +``` +``` ++----------------------------+ +| _col0| ++----------------------------+ +|SW9URELkuozov5vliLbmtYvor5U=| ++----------------------------+ +``` + +2. from_base64: Decode Base64 to binary +```SQL +SELECT DISTINCT from_base64('SW9URELkuozov5vliLbmtYvor5U=') FROM table1; +``` +``` ++------------------------------------------+ +| _col0| ++------------------------------------------+ +|0x496f544442e4ba8ce8bf9be588b6e6b58be8af95| ++------------------------------------------+ +``` + +3. to_base64url: Encode to URL-safe Base64URL +```SQL +SELECT DISTINCT to_base64url('https://iotdb.apache.org') FROM table1; +``` +``` ++--------------------------------+ +| _col0| ++--------------------------------+ +|aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn| ++--------------------------------+ +``` + +4. from_base64url: Decode Base64URL +```SQL +SELECT DISTINCT from_base64url('aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn') FROM table1; +``` +``` ++--------------------------------------------------+ +| _col0| ++--------------------------------------------------+ +|0x68747470733a2f2f696f7464622e6170616368652e6f7267| ++--------------------------------------------------+ +``` + +5. to_base32: Encode to Base32 +```SQL +SELECT DISTINCT to_base32('123456') FROM table1; +``` +``` ++----------------+ +| _col0| ++----------------+ +|GEZDGNBVGY======| ++----------------+ +``` + +6. from_base32: Decode Base32 +```SQL +SELECT DISTINCT from_base32('GEZDGNBVGY======') FROM table1; +``` +``` ++--------------+ +| _col0| ++--------------+ +|0x313233343536| ++--------------+ +``` + +### 7.2 Hex Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------ | -------------------------------------------------- | --------------------- | ------------- | +| `TO_HEX(input)` | Convert input to hex string (raw byte view) | STRING/TEXT/BLOB | STRING | +| `FROM_HEX(input)` | Decode hex string to raw binary (inverse of TO_HEX) | STRING/TEXT | BLOB | + +**Examples** +1. TO_HEX: Convert string/binary to hex +```SQL +SELECT DISTINCT TO_HEX('test') FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|74657374| ++--------+ +``` + +2. FROM_HEX: Decode hex to binary +```SQL +SELECT DISTINCT FROM_HEX('74657374') FROM table1; +``` +``` ++----------+ +| _col0| ++----------+ +|0x74657374| ++----------+ +``` + +### 7.3 Basic Binary Functions +| Function Name | Description | Input Type | Output Type | +| ----------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------- | -------------- | +| `length(input)` | Return data length: chars for TEXT, bytes for BLOB/OBJECT | STRING/TEXT/BLOB/OBJECT | INT32 | +| `REVERSE(input)` | Reverse input: chars for TEXT, bytes for BLOB | STRING/TEXT/BLOB | Same as input | +| `LPAD(input, length, pad_bytes)` | Left-pad/truncate BLOB to target byte length | BLOB, INT32/INT64, BLOB | BLOB | +| `RPAD(input, length, pad_bytes)` | Right-pad/truncate BLOB to target byte length | BLOB, INT32/INT64, BLOB | BLOB | + +**Examples** +1. length: Get data length +```SQL +SELECT DISTINCT length('IoTDB') FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +| 5| ++-----+ +``` + +2. REVERSE: Reverse data +```SQL +SELECT DISTINCT REVERSE('12345') FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +|54321| ++-----+ +``` + +3. LPAD: Left-pad BLOB +```SQL +SELECT DISTINCT LPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|0x7474657374| ++------------+ +``` + +4. RPAD: Right-pad BLOB +```SQL +SELECT DISTINCT RPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|0x7465737474| ++------------+ +``` + +### 7.4 Integer Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------------- | ------------------------------------------------------------------------- | ------------ | ------------ | +| `to_big_endian_32(input)` | Convert INT32 to 4-byte big-endian BLOB (network byte order) | INT32 | BLOB | +| `to_big_endian_64(input)` | Convert INT64 to 8-byte big-endian BLOB | INT64 | BLOB | +| `from_big_endian_32(input)` | Decode 4-byte big-endian BLOB to INT32 | BLOB | INT32 | +| `from_big_endian_64(input)` | Decode 8-byte big-endian BLOB to INT64 | BLOB | INT64 | +| `to_little_endian_32(input)` | Convert INT32 to 4-byte little-endian BLOB (x86 architecture) | INT32 | BLOB | +| `to_little_endian_64(input)` | Convert INT64 to 8-byte little-endian BLOB | INT64 | BLOB | +| `from_little_endian_32(input)` | Decode 4-byte little-endian BLOB to INT32 | BLOB | INT32 | +| `from_little_endian_64(input)` | Decode 8-byte little-endian BLOB to INT64 | BLOB | INT64 | + +**Examples** +1. Big-endian encode/decode +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_32(12345)) FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|00003039| ++--------+ +``` + +2. Little-endian encode/decode +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_32(12345)) FROM table1; +``` +``` ++--------+ +| _col0| ++--------+ +|39300000| ++--------+ +``` + +### 7.5 Floating-Point Encoding Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------- | ------------------------------------------------------------------------- | ------------ | ------------ | +| `to_ieee754_32(input)` | Convert FLOAT to 4-byte big-endian IEEE754 BLOB | FLOAT | BLOB | +| `to_ieee754_64(input)` | Convert DOUBLE to 8-byte big-endian IEEE754 BLOB | DOUBLE | BLOB | +| `from_ieee754_32(input)` | Decode 4-byte IEEE754 BLOB to FLOAT | BLOB | FLOAT | +| `from_ieee754_64(input)` | Decode 8-byte IEEE754 BLOB to DOUBLE | BLOB | DOUBLE | + +**Examples** +1. FLOAT encode/decode +```SQL +SELECT DISTINCT from_ieee754_32(FROM_HEX('42b40000')) FROM table1; +``` +``` ++-----+ +|_col0| ++-----+ +| 90.0| ++-----+ +``` + +2. DOUBLE encode/decode +```SQL +SELECT DISTINCT from_ieee754_64(FROM_HEX('400921fb54411744')) FROM table1; +``` +``` ++------------+ +| _col0| ++------------+ +|3.1415926535| ++------------+ +``` + +### 7.6 Hash Functions +| Function Name | Description | Input Type | Output Type | +| --------------------------------- | ------------------------------------------------------------------------- | ------------------ | ------------- | +| `sha256(input)` | SHA-256 cryptographic hash (collision-resistant) | STRING/TEXT/BLOB | BLOB(32B) | +| `SHA512(input)` | SHA-512 cryptographic hash (higher security) | STRING/TEXT/BLOB | BLOB(64B) | +| `SHA1(input)` | SHA-1 hash (not secure for cryptography) | STRING/TEXT/BLOB | BLOB(20B) | +| `MD5(input)` | MD5 hash (non-cryptographic checksum) | STRING/TEXT/BLOB | BLOB(16B) | +| `CRC32(input)` | CRC32 checksum (fast error detection) | STRING/TEXT/BLOB | INT64 | +| `spooky_hash_v2_32(input)` | 32-bit SpookyHashV2 (high-performance non-crypto) | STRING/TEXT/BLOB | BLOB(4B) | +| `spooky_hash_v2_64(input)` | 64-bit SpookyHashV2 | STRING/TEXT/BLOB | BLOB(8B) | +| `xxhash64(input)` | 64-bit xxHash (ultra-fast) | STRING/TEXT/BLOB | BLOB(8B) | +| `murmur3(input)` | 128-bit MurmurHash3 (uniform distribution) | STRING/TEXT/BLOB | BLOB(16B) | + +**Examples** +```SQL +SELECT DISTINCT TO_HEX(sha256('test')) FROM table1; +``` +``` ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08| ++----------------------------------------------------------------+ +``` + +### 7.7 HMAC Functions +| Function Name | Description | Input Type | Output Type | +| ------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------- | ------------- | +| `hmac_md5(data, key)` | HMAC-MD5 message authentication code | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(16B) | +| `hmac_sha1(data, key)` | HMAC-SHA1 authentication code | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(20B) | +| `hmac_sha256(data, key)` | HMAC-SHA256 (industry-recommended, high security) | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(32B) | +| `hmac_sha512(data, key)` | HMAC-SHA512 (maximum security) | data: STRING/TEXT/BLOB key: STRING/TEXT | BLOB(64B) | + +**Examples** +```SQL +SELECT DISTINCT TO_HEX(hmac_sha256('user_data_123', 'iotdb_secret_key')) FROM table1; +``` +``` ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|73b6f26bbcb5192dbe2cb83745b0fc48c63418fa674b0bf62fabe7f8747f3afd| ++----------------------------------------------------------------+ +``` + -## 7. Conditional Expressions +## 8. Conditional Expressions -### 7.1 CASE +### 8.1 CASE CASE expressions come in two forms: **Simple CASE** and **Searched CASE**. -#### 7.1.1 Simple CASE +#### 8.1.1 Simple CASE The simple form evaluates each value expression from left to right until it finds a match with the given expression: @@ -1254,7 +1544,7 @@ SELECT a, END ``` -#### 7.1.2 Searched CASE +#### 8.1.2 Searched CASE The searched form evaluates each Boolean condition from left to right until a `TRUE` condition is found, then returns the corresponding result: @@ -1279,7 +1569,7 @@ SELECT a, b, END ``` -### 7.2 COALESCE +### 8.2 COALESCE Returns the first non-null value from the given list of parameters. @@ -1287,11 +1577,11 @@ Returns the first non-null value from the given list of parameters. coalesce(value1, value2[, ...]) ``` -## 8. Conversion Functions +## 9. Conversion Functions -### 8.1 Conversion Functions +### 9.1 Conversion Functions -#### 8.1.1 cast(value AS type) → type +#### 9.1.1 cast(value AS type) → type Explicitly converts a value to the specified type. This can be used to convert strings (`VARCHAR`) to numeric types or numeric values to string types. Starting from V2.0.8, OBJECT type can be explicitly cast to STRING type. @@ -1306,7 +1596,7 @@ SELECT * IN (CAST('2024-11-27' AS DATE), CAST('2024-11-28' AS DATE)); ``` -#### 8.1.2 try_cast(value AS type) → type +#### 9.1.2 try_cast(value AS type) → type Similar to `CAST()`. If the conversion fails, returns `NULL` instead of throwing an error. @@ -1319,11 +1609,11 @@ SELECT * IN (try_cast('2024-11-27' AS DATE), try_cast('2024-11-28' AS DATE)); ``` -### 8.2 Format Function +### 9.2 Format Function 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. -#### 8.2.1 Syntax +#### 9.2.1 Syntax ```SQL format(pattern, ...args) -> STRING @@ -1341,7 +1631,7 @@ format(pattern, ...args) -> STRING * Formatted result string of type `STRING`. -#### 8.2.2 Usage Examples +#### 9.2.2 Usage Examples 1. Format Floating-Point Numbers ```SQL @@ -1450,7 +1740,7 @@ IoTDB:database1> SELECT format('%1$tF %1$tT', 2024-01-01T00:00:00.000+08:00) FRO +-----+ ``` -#### 8.2.3 Format Conversion Failure Scenarios +#### 9.2.3 Format Conversion Failure Scenarios 1. Type Mismatch Errors @@ -1505,19 +1795,19 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h ``` -## 9. String Functions and Operators +## 10. String Functions and Operators -### 9.1 String operators +### 10.1 String operators -#### 9.1.1 || Operator +#### 10.1.1 || Operator The `||` operator is used for string concatenation and functions the same as the `concat` function. -#### 9.1.2 LIKE Statement +#### 10.1.2 LIKE Statement The `LIKE` statement is used for pattern matching. For detailed usage, refer to Pattern Matching:[LIKE](#1-like-运算符). -### 9.2 String Functions +### 10.2 String Functions | Function Name | Description | Input | Output | Usage | | :------------ |:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------| :------ | :----------------------------------------------------------- | @@ -1535,33 +1825,33 @@ The `||` operator is used for string concatenation and functions the same as the | `substring` | Extracts a substring from `start_index` to the end of the string. **Notes:** - `start_index` starts at `1`. - Returns `NULL` if input is `NULL`. - Throws an error if `start_index` is greater than string length. | `string`, `start_index` | String | substring(string from start_index)or substring(string, start_index) | | `substring` | Extracts a substring of `length` characters starting from `start_index`. **Notes:** - `start_index` starts at `1`. - Returns `NULL` if input is `NULL`. - Throws an error if `start_index` is greater than string length. - Throws an error if `length` is negative. - If `start_index + length` exceeds `int.MAX`, an overflow error may occur. | `string`, `start_index`, `length` | String | substring(string from start_index for length) or substring(string, start_index, length) | -## 10. Pattern Matching Functions +## 11. Pattern Matching Functions -### 10.1 LIKE +### 11.1 LIKE -#### 10.1.1 Usage +#### 11.1.1 Usage The `LIKE `operator is used to compare a value with a pattern. It is commonly used in the `WHERE `clause to match specific patterns within strings. -#### 10.1.2 Syntax +#### 11.1.2 Syntax ```SQL ... column [NOT] LIKE 'pattern' ESCAPE 'character'; ``` -#### 10.1.3 Match rules +#### 11.1.3 Match rules - Matching characters is case-sensitive - The pattern supports two wildcard characters: - `_` matches any single character - `%` matches zero or more characters -#### 10.1.4 Notes +#### 11.1.4 Notes - `LIKE` pattern matching applies to the entire string by default. Therefore, if it's desired to match a sequence anywhere within a string, the pattern must start and end with a percent sign. - To match the escape character itself, double it (e.g., `\\` to match `\`). For example, you can use `\\` to match for `\`. -#### 10.1.5 Examples +#### 11.1.5 Examples #### **Example 1: Match Strings Starting with a Specific Character** @@ -1603,13 +1893,13 @@ SELECT * FROM table1 WHERE continent LIKE 'South\_%' ESCAPE '\'; SELECT * FROM table1 WHERE continent LIKE 'South\\%' ESCAPE '\'; ``` -### 10.2 regexp_like +### 11.2 regexp_like -#### 10.2.1 Usage +#### 11.2.1 Usage Evaluates whether the regular expression pattern is present within the given string. -#### 10.2.2 Syntax +#### 11.2.2 Syntax ```SQL regexp_like(string, pattern); @@ -1638,7 +1928,7 @@ regexp_like(string, pattern); 4. Categories: Specify directly, without the need for `Is`, `general_category=`, or `gc=` prefixes (e.g., `\p{L}`). 5. Binary properties: Specify directly, without `Is` (e.g., `\p{NoncharacterCodePoint}`). -#### 10.2.4 Examples +#### 11.2.4 Examples #### Example 1: **Matching strings containing a specific pattern** @@ -1663,7 +1953,7 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false - `b` represents the letter b. - `'1a 2b 14m'` does not match this pattern because it does not start with digits and does not end with `b`, so it returns `false`. -## 11. Timeseries Windowing Functions +## 12. Timeseries Windowing Functions The sample data is as follows: @@ -1686,19 +1976,19 @@ CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); ``` -### 11.1 HOP +### 12.1 HOP -#### 11.1.1 Function Description +#### 12.1.1 Function Description The HOP function segments data into overlapping time windows for analysis, assigning each row to all windows that overlap with its timestamp. If windows overlap (when SLIDE < SIZE), data will be duplicated across multiple windows. -#### 11.1.2 Function Definition +#### 12.1.2 Function Definition ```SQL HOP(data, timecol, size, slide[, origin]) ``` -#### 11.1.3 Parameter Description +#### 12.1.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | ------------------------- | @@ -1709,7 +1999,7 @@ HOP(data, timecol, size, slide[, origin]) | ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | -#### 11.1.4 Returned Results +#### 12.1.4 Returned Results The HOP function returns: @@ -1717,7 +2007,7 @@ The HOP function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.1.5 Usage Example +#### 12.1.5 Usage Example ```SQL IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); @@ -1752,18 +2042,18 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DAT +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.2 SESSION +### 12.2 SESSION -#### 11.2.1 Function Description +#### 12.2.1 Function Description The SESSION function groups data into sessions based on time intervals. It checks the time gap between consecutive rows—rows with gaps smaller than the threshold (GAP) are grouped into the current window, while larger gaps trigger a new window. -#### 11.2.2 Function Definition +#### 12.2.2 Function Definition ```SQL SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) ``` -#### 11.2.3 Parameter Description +#### 12.2.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | @@ -1771,7 +2061,7 @@ SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) | TIMECOL | Scalar | String (default: 'time') | Time column name | | GAP | Scalar | Long integer | Session gap threshold | -#### 11.2.4 Returned Results +#### 12.2.4 Returned Results The SESSION function returns: @@ -1779,7 +2069,7 @@ The SESSION function returns: * `window_end`: Time of the last row in the session * Pass-through columns: All input columns from DATA -#### 11.2.5 Usage Example +#### 12.2.5 Usage Example ```SQL IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); @@ -1805,19 +2095,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.3 VARIATION +### 12.3 VARIATION -#### 11.3.1 Function Description +#### 12.3.1 Function Description The VARIATION function groups data based on value differences. The first row becomes the baseline for the first window. Subsequent rows are compared to the baseline—if the difference is within the threshold (DELTA), they join the current window; otherwise, a new window starts with that row as the new baseline. -#### 11.3.2 Function Definition +#### 12.3.2 Function Definition ```sql VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) ``` -#### 11.3.3 Parameter Description +#### 12.3.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | @@ -1825,14 +2115,14 @@ VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) | COL | Scalar | String | Column for difference calculation | | DELTA | Scalar | Float | Difference threshold | -#### 11.3.4 Returned Results +#### 12.3.4 Returned Results The VARIATION function returns: * `window_index`: Window identifier * Pass-through columns: All input columns from DATA -#### 11.3.5 Usage Example +#### 12.3.5 Usage Example ```sql IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); @@ -1859,33 +2149,33 @@ IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, a +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.4 CAPACITY +### 12.4 CAPACITY -#### 11.4.1 Function Description +#### 12.4.1 Function Description The CAPACITY function groups data into fixed-size windows, where each window contains up to SIZE rows. -#### 11.4.2 Function Definition +#### 12.4.2 Function Definition ```sql CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) ``` -#### 11.4.3 Parameter Description +#### 12.4.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | ---------------------------- | -------------------------------------- | | DATA | Table | SET SEMANTIC, PASS THROUGH | Input table with partition/sort keys | | SIZE | Scalar | Long integer | Window size (row count) | -#### 11.4.4 Returned Results +#### 12.4.4 Returned Results The CAPACITY function returns: * `window_index`: Window identifier * Pass-through columns: All input columns from DATA -#### 11.4.5 Usage Example +#### 12.4.5 Usage Example ```sql IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); @@ -1912,18 +2202,18 @@ IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(p +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.5 TUMBLE +### 12.5 TUMBLE -#### 11.5.1 Function Description +#### 12.5.1 Function Description The TUMBLE function assigns each row to a non-overlapping, fixed-size time window based on a timestamp attribute. -#### 11.5.2 Function Definition +#### 12.5.2 Function Definition ```sql TUMBLE(data, timecol, size[, origin]) ``` -#### 11.5.3 Parameter Description +#### 12.5.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | ------------------------- | @@ -1932,7 +2222,7 @@ TUMBLE(data, timecol, size[, origin]) | SIZE | Scalar | Long integer (positive) | Window size | | ORIGIN | Scalar | Timestamp (default: Unix epoch) | First window start time | -#### 11.5.4 Returned Results +#### 12.5.4 Returned Results The TUMBLE function returns: @@ -1940,7 +2230,7 @@ The TUMBLE function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.5.5 Usage Example +#### 12.5.5 Usage Example ```SQL IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); @@ -1966,19 +2256,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE( +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.6 CUMULATE +### 12.6 CUMULATE -#### 11.6.1 Function Description +#### 12.6.1 Function Description The CUMULATE function creates expanding windows from an initial window, maintaining the same start time while incrementally extending the end time by STEP until reaching SIZE. Each window contains all elements within its range. For example, with a 1-hour STEP and 24-hour SIZE, daily windows would be: `[00:00, 01:00)`, `[00:00, 02:00)`, ..., `[00:00, 24:00)`. -#### 11.6.2 Function Definition +#### 12.6.2 Function Definition ```sql CUMULATE(data, timecol, size, step[, origin]) ``` -#### 11.6.3 Parameter Description +#### 12.6.3 Parameter Description | Parameter | Type | Attributes | Description | | ----------- | -------- | --------------------------------- | --------------------------------------------------- | @@ -1990,7 +2280,7 @@ CUMULATE(data, timecol, size, step[, origin]) > Note: An error `Cumulative table function requires size must be an integral multiple of step` occurs if SIZE is not divisible by STEP. -#### 11.6.4 Returned Results +#### 12.6.4 Returned Results The CUMULATE function returns: @@ -1998,7 +2288,7 @@ The CUMULATE function returns: * `window_end`: Window end time (exclusive) * Pass-through columns: All input columns from DATA -#### 11.6.5 Usage Example +#### 12.6.5 Usage Example ```sql IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m); diff --git a/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md b/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md index 78febd1b0..63ebd6461 100644 --- a/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md +++ b/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_apache.md @@ -1205,13 +1205,596 @@ IoTDB:database1> select length, width, bitwise_right_shift_arithmetic(length,wid +------+-----+-----+ ``` -## 7. 条件表达式 +## 7. 二进制函数 -### 7.1 CASE 表达式 +> V2.0.9-beta 起支持 + +### 7.1 Base64 编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ----------------------------- | ------------------------------------------------------------------------- | ------------------ | -------------- | +| `to_base64(input)` | 将输入数据编码为标准 Base64 字符串，解决二进制数据传输 / 存储兼容性问题 | STRING/TEXT/BLOB | STRING | +| `from_base64(input)` | 将标准 Base64 字符串解码为原始二进制数据，为 to\_base64 逆操作 | STRING/TEXT | BLOB | +| `to_base64url(input)` | 将输入数据编码为 URL 安全的 Base64URL 字符串，替换 +/\_、省略填充符 | STRING/TEXT/BLOB | STRING | +| `from_base64url(input)` | 将 Base64URL 字符串解码为原始二进制数据，为 to\_base64url 逆操作 | STRING/TEXT | BLOB | +| `to_base32(input)` | 将输入数据编码为 Base32 字符串，字符无混淆、不区分大小写，可读性高 | STRING/TEXT/BLOB | STRING | +| `from_base32(input)` | 将 Base32 字符串解码为原始二进制数据，为 to\_base32 逆操作 | STRING/TEXT | BLOB | + +**使用示例** + +1. to\_base64：编码字符串为标准Base64 + +```SQL +SELECT DISTINCT to_base64('IoTDB二进制测试') FROM table1; +``` + +```Bash ++----------------------------+ +| _col0| ++----------------------------+ +|SW9URELkuozov5vliLbmtYvor5U=| ++----------------------------+ +``` + +2. from\_base64：解码Base64字符串为二进制 + +```SQL +SELECT DISTINCT from_base64('SW9URELkuozov5vliLbmtYvor5U=') FROM table1; +``` + +```Bash ++------------------------------------------+ +| _col0| ++------------------------------------------+ +|0x496f544442e4ba8ce8bf9be588b6e6b58be8af95| ++------------------------------------------+ +``` + +3. to\_base64url：编码为URL安全的Base64URL（无+/\_、无填充符=） + +```SQL +SELECT DISTINCT to_base64url('https://iotdb.apache.org') FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn| ++--------------------------------+ +``` + +4. from\_base64url：解码Base64URL字符串 + +```SQL +SELECT DISTINCT from_base64url('aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn') FROM table1; +``` + +```Bash ++--------------------------------------------------+ +| _col0| ++--------------------------------------------------+ +|0x68747470733a2f2f696f7464622e6170616368652e6f7267| ++--------------------------------------------------+ +``` + +5. to\_base32：编码为Base32字符串 + +```SQL +SELECT DISTINCT to_base32('123456') FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|GEZDGNBVGY======| ++----------------+ +``` + +6. from\_base32：解码Base32字符串 + +```SQL +SELECT DISTINCT from_base32('GEZDGNBVGY======') FROM table1; +``` + +```SQL ++--------------+ +| _col0| ++--------------+ +|0x313233343536| ++--------------+ +``` + +### 7.2 十六进制编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ----------------------- | -------------------------------------------------------------- | ------------------ | -------------- | +| `TO_HEX(input)` | 将输入数据转换为十六进制字符串，直接反映底层字节值，便于调试 | STRING/TEXT/BLOB | STRING | +| `FROM_HEX(input)` | 将十六进制字符串解码为原始二进制数据，为TO\_HEX逆操作 | STRING/TEXT | BLOB | + +**使用示例** + +1. TO\_HEX：将字符串/二进制转换为十六进制 + +```SQL +SELECT DISTINCT TO_HEX('test') FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|74657374| ++--------+ +``` + +2. FROM\_HEX：将十六进制字符串解码为二进制 + +```SQL +SELECT DISTINCT FROM_HEX('74657374') FROM table1; +``` + +```Bash ++----------+ +| _col0| ++----------+ +|0x74657374| ++----------+ +``` + +### 7.3 二进制基础函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| -------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------- | ---------------- | +| `length(input)` | 返回输入数据长度，文本类型返字符数，BLOB类型返回字节数，OBJECT 类型返回对象二进制字节大小 | STRING/TEXT/BLOB/OBJECT | INT32 | +| `REVERSE(input)`| 反转输入数据顺序，文本类型反转字符，BLOB类型反转字节 | STRING/TEXT/BLOB | 与输入类型一致 | +| `LPAD(input, length, pad_bytes)` | 对BLOB进行字节级左填充/截断，使最终字节长度等于指定值 | BLOB、INT32/INT64、BLOB | BLOB | +| `RPAD(input, length, pad_bytes)` | 对BLOB进行字节级右填充/截断，使最终字节长度等于指定值 | BLOB、INT32/INT64、BLOB | BLOB | + +**使用示例** + +1. length：获取数据长度 + +```SQL +SELECT DISTINCT length('IoTDB') FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +| 5| ++-----+ +``` + +2. REVERSE：反转数据 + +```SQL +SELECT DISTINCT REVERSE('12345') FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|54321| ++-----+ +``` + +3. LPAD：左填充/截断BLOB（参数：原BLOB、目标长度、填充字节） + +```SQL +SELECT DISTINCT LPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|0x7474657374| ++------------+ +``` + +4. RPAD：右填充/截断BLOB + +```SQL +SELECT DISTINCT RPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|0x7465737474| ++------------+ +``` + +### 7.4 整数编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------------ | ------------------------------------------------------------------ | -------------- | -------------- | +| `to_big_endian_32(input)` | 将INT32整数转换为4字节大端序BLOB，符合网络字节序标准 | INT32 | BLOB | +| `to_big_endian_64(input)` | 将INT64整数转换为8字节大端序BLOB，符合网络字节序标准 | INT64 | BLOB | +| `from_big_endian_32(input)` | 将4字节大端序BLOB解码为INT32整数，为to\_big\_endian\_32逆操作 | BLOB | INT32 | +| `from_big_endian_64(input)` | 将8字节大端序BLOB解码为INT64整数，为to\_big\_endian\_64逆操作 | BLOB | INT64 | +| `to_little_endian_32(input)` | 将INT32整数转换为4字节小端序BLOB，适配x86等主流架构 | INT32 | BLOB | +| `to_little_endian_64(input)` | 将INT64整数转换为8字节小端序BLOB，适配x86等主流架构 | INT64 | BLOB | +| `from_little_endian_32(input)` | 将4字节小端序BLOB解码为INT32整数，为to\_little\_endian\_32逆操作 | BLOB | INT32 | +| `from_little_endian_64(input)` | 将8字节小端序BLOB解码为INT64整数，为to\_little\_endian\_64逆操作 | BLOB | INT64 | + +**使用示例** + +1. 大端序编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_32(12345)) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|00003039| ++--------+ +``` + +```SQL +SELECT DISTINCT from_big_endian_32(FROM_HEX('00003039')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|12345| ++-----+ +``` + +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_64(1234567890123)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|0000011f71fb04cb| ++----------------+ +``` + +```SQL +SELECT DISTINCT from_big_endian_64(FROM_HEX('0000011f71fb04cb')) FROM table1; +``` + +```Bash ++-------------+ +| _col0| ++-------------+ +|1234567890123| ++-------------+ +``` + +2. 小端序编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_32(12345)) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|39300000| ++--------+ +``` + +```SQL +SELECT DISTINCT from_little_endian_32(FROM_HEX('39300000')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|12345| ++-----+ +``` + +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_64(1234567890123)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|cb04fb711f010000| ++----------------+ +``` + +```SQL +SELECT DISTINCT from_little_endian_64(FROM_HEX('cb04fb711f010000')) FROM table1; +``` + +```Bash ++-------------+ +| _col0| ++-------------+ +|1234567890123| ++-------------+ +``` + +### 7.5 浮点型编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------ | ------------------------------------------------------------------- | -------------- | -------------- | +| `to_ieee754_32(input)` | 将FLOAT单精度浮点数转换为4字节大端序IEEE754标准BLOB | FLOAT | BLOB | +| `to_ieee754_64(input)` | 将DOUBLE双精度浮点数转换为8字节大端序IEEE754标准BLOB | DOUBLE | BLOB | +| `from_ieee754_32(input)` | 将4字节IEEE754标准BLOB解码为FLOAT浮点数，为to\_ieee754\_32逆操作 | BLOB | FLOAT | +| `from_ieee754_64(input)` | 将8字节IEEE754标准BLOB解码为DOUBLE浮点数，为to\_ieee754\_64逆操作 | BLOB | DOUBLE | + +**使用示例** + +1. 单精度浮点数（FLOAT）编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_ieee754_32(temperature)) FROM table1 where time = 2024-11-26 13:37:00; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|42b40000| ++--------+ +``` + +```SQL +SELECT DISTINCT from_ieee754_32(FROM_HEX('42b40000')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +| 90.0| ++-----+ +``` + +2. 双精度浮点数（DOUBLE）编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_ieee754_64(3.1415926535)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|400921fb54411744| ++----------------+ +``` + +```Bash +SELECT DISTINCT from_ieee754_64(FROM_HEX('400921fb54411744')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|3.1415926535| ++------------+ +``` + +### 7.6 哈希函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| -------------------------------- | ---------------------------------------------------------------- | -------------------- | -------------- | +| `sha256(input)` | 计算输入数据的SHA-256密码学哈希值，不可逆、抗碰撞 | STRING、TEXT、BLOB | BLOB(32字节) | +| `SHA512(input)` | 计算输入数据的SHA-512密码学哈希值，安全强度高于SHA256 | STRING、TEXT、BLOB | BLOB(64字节) | +| `SHA1(input)` | 计算输入数据的SHA-1哈希值，抗碰撞性弱，不推荐安全场景使用 | STRING、TEXT、BLOB | BLOB(20字节) | +| `MD5(input)` | 计算输入数据的MD5哈希值，无密码学安全性，仅用于非加密校验 | STRING、TEXT、BLOB | BLOB(16字节) | +| `CRC32(input)` | 计算输入数据的CRC32循环冗余校验码，高效检测非恶意数据错误 | STRING、TEXT、BLOB | INT64 | +| `spooky_hash_v2_32(input)` | 计算输入数据的32位SpookyHashV2非密码学哈希值，高性能、低冲突 | STRING、TEXT、BLOB | BLOB(4字节) | +| `spooky_hash_v2_64(input)` | 计算输入数据的64位SpookyHashV2非密码学哈希值，高性能、低冲突 | STRING、TEXT、BLOB | BLOB(8字节) | +| `xxhash64(input)` | 计算输入数据的64位xxHash非密码学哈希值，计算速度极快 | STRING、TEXT、BLOB | BLOB(8字节) | +| `murmur3(input)` | 计算输入数据的128位MurmurHash3非密码学哈希值，分布均匀、应用广 | STRING、TEXT、BLOB | BLOB(16字节) | + +**使用示例** + +1. 密码学哈希函数 + +```SQL +SELECT DISTINCT TO_HEX(sha256('test')) FROM table1; +``` + +```Bash ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08| ++----------------------------------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(SHA512('test')) FROM table1; +``` + +```Bash ++--------------------------------------------------------------------------------------------------------------------------------+ +| _col0| ++--------------------------------------------------------------------------------------------------------------------------------+ +|ee26b0dd4af7e749aa1a8ee3c10ae9923f618980772e473f8819a5d4940e0db27ac185f8a0e1d5f84f88bc887fd67b143732c304cc5fa9ad8e6f57f50028a8ff| ++--------------------------------------------------------------------------------------------------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(SHA1('test')) FROM table1; +``` + +```Bash ++----------------------------------------+ +| _col0| ++----------------------------------------+ +|a94a8fe5ccb19ba61c4c0873d391e987982fbbd3| ++----------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(MD5('test')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|098f6bcd4621d373cade4e832627b4f6| ++--------------------------------+ +``` + +2. 校验/非密码学哈希函数 + +```SQL +SELECT DISTINCT CRC32('test') FROM table1; +``` + +```Bash ++----------+ +| _col0| ++----------+ +|3632233996| ++----------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(spooky_hash_v2_32('test')) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|ec0d8b75| ++--------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(spooky_hash_v2_64('test')) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|7b01e8bcec0d8b75| ++----------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(xxhash64('test')) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|4fdcca5ddb678139| ++----------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(murmur3('test')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|9de1bd74cc287dac824dbdf93182129a| ++--------------------------------+ +``` + +### 7.7 HMAC函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------ | ------------------------------------------------------------------- | -------------------------------------------- | -------------- | +| `hmac_md5(data, key)` | 结合MD5与密钥计算HMAC消息认证码，验证数据完整性和来源，适配旧系统 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(16字节) | +| `hmac_sha1(data, key)` | 结合SHA-1与密钥计算HMAC消息认证码，验证数据完整性和来源 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(20字节) | +| `hmac_sha256(data, key)` | 结合SHA256与密钥计算HMAC消息认证码，业界推荐标准，安全强度高 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(32字节) | +| `hmac_sha512(data, key)` | 结合SHA512与密钥计算HMAC消息认证码，商用级别最高安全强度 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(64字节) | + +**使用示例** + +* 通用密钥：'iotdb\_secret\_key' +* 待验证数据：'user\_data\_123' + +1. hmac\_md5 + +```SQL +SELECT DISTINCT TO_HEX(hmac_md5('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|8ee863080ceb3b43b5ffdc7a937e7f28| ++--------------------------------+ +``` + +2. hmac\_sha1 + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha1('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++----------------------------------------+ +| _col0| ++----------------------------------------+ +|b5b7ae1a495745299ec3bd236c511c13540481ce| ++----------------------------------------+ +``` + +3. hmac\_sha256（推荐使用） + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha256('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|73b6f26bbcb5192dbe2cb83745b0fc48c63418fa674b0bf62fabe7f8747f3afd| ++----------------------------------------------------------------+ +``` + +4. hmac\_sha512 + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha512('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++--------------------------------------------------------------------------------------------------------------------------------+ +| _col0| ++--------------------------------------------------------------------------------------------------------------------------------+ +|2fed4ec5a0535e3349798b371d6525255ee85d9eae0ddcbdecf89db84f943151f5febf0ffd9c01ae9661278504aba186cf6f732ae5f42d63be58aadee2baccc2| ++--------------------------------------------------------------------------------------------------------------------------------+ +``` + + + +## 8. 条件表达式 + +### 8.1 CASE 表达式 CASE 表达式有两种形式：简单形式、搜索形式 -#### 7.1.1 简单形式 +#### 8.1.1 简单形式 简单形式从左到右搜索每个值表达式，直到找到一个与表达式相等的值： @@ -1234,7 +1817,7 @@ SELECT a, END ``` -#### 7.1.2 搜索形式 +#### 8.1.2 搜索形式 搜索形式从左到右评估每个布尔条件，直到找到一个为真的条件，并返回相应的结果： @@ -1257,7 +1840,7 @@ SELECT a, b, END ``` -### 7.2 COALESCE 函数 +### 8.2 COALESCE 函数 返回参数列表中的第一个非空值。 @@ -1265,14 +1848,14 @@ SELECT a, b, coalesce(value1, value2[, ...]) ``` -## 8. 转换函数 +## 9. 转换函数 -### 8.1 转换函数 +### 9.1 转换函数 -#### 8.1.1 cast(value AS type) → type +#### 9.1.1 cast(value AS type) → type 1. 显式地将一个值转换为指定类型。 -2. 可以用于将字符串（varchar）转换为数值类型，或数值转换为字符串类型。 +2. 可以用于将字符串（varchar）转换为数值类型，或数值转换为字符串类型 3. 如果转换失败，将抛出运行时错误。 示例： @@ -1284,7 +1867,7 @@ SELECT * IN (CAST('2024-11-27' AS DATE), CAST('2024-11-28' AS DATE)); ``` -#### 8.1.2 try_cast(value AS type) → type +#### 9.1.2 try_cast(value AS type) → type 1. 与 `cast()` 类似。 2. 如果转换失败，则返回 `null`。 @@ -1298,10 +1881,10 @@ SELECT * IN (try_cast('2024-11-27' AS DATE), try_cast('2024-11-28' AS DATE)); ``` -### 8.2 Format 函数 +### 9.2 Format 函数 该函数基于指定的格式字符串与输入参数，生成并返回格式化后的字符串输出。其功能与 Java 语言中的`String.format` 方法及 C 语言中的`printf`函数相类似，支持开发者通过占位符语法构建动态字符串模板，其中预设的格式标识符将被传入的对应参数值精准替换，最终形成符合特定格式要求的完整字符串。 -#### 8.2.1 语法介绍 +#### 9.2.1 语法介绍 ```SQL format(pattern,...args) -> String @@ -1311,15 +1894,15 @@ format(pattern,...args) -> String * `pattern`: 格式字符串，可包含静态文本及一个或多个格式说明符（如 `%s`, `%d` 等），或任意返回类型为 `STRING/TEXT` 的表达式。 * `args`: 用于替换格式说明符的输入参数。需满足以下条件： - * 参数数量 ≥ 1 - * 若存在多个参数，以逗号`,`分隔（如 `arg1,arg2`） - * 参数总数可多于 `pattern` 中的占位符数量，但不可少于，否则触发异常 + * 参数数量 ≥ 1 + * 若存在多个参数，以逗号`,`分隔（如 `arg1,arg2`） + * 参数总数可多于 `pattern` 中的占位符数量，但不可少于，否则触发异常 **返回值** * 类型为 `STRING` 的格式化结果字符串 -#### 8.2.2 使用示例 +#### 9.2.2 使用示例 1. 格式化浮点数 @@ -1435,13 +2018,13 @@ IoTDB:database1> SELECT format('%s%%', 99.9) from table1 limit 1 +-----+ ``` -#### 8.2.3 **格式转换失败场景说明** +#### 9.2.3 **格式转换失败场景说明** 1. 类型不匹配错误 * 时间戳类型冲突 若格式说明符中包含时间相关标记（如 `%Y-%m-%d`），但参数提供： - * 非 `DATE`/`TIMESTAMP` 类型值 - * 或涉及日期细粒度单位（如 `%H` 小时、`%M` 分钟）时，参数仅支持 `TIMESTAMP` 类型，否则将抛出类型异常 + * 非 `DATE`/`TIMESTAMP` 类型值 + * 或涉及日期细粒度单位（如 `%H` 小时、`%M` 分钟）时，参数仅支持 `TIMESTAMP` 类型，否则将抛出类型异常 ```SQL -- 示例1 @@ -1473,8 +2056,8 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %.5f % 3. 无效调用错误 * 当函数参数满足以下任一条件时，视为非法调用： - * 参数总数 小于 2（必须包含格式字符串及至少一个参数） - * 格式字符串（`pattern`）类型非 `STRING/TEXT` + * 参数总数 小于 2（必须包含格式字符串及至少一个参数） + * 格式字符串（`pattern`）类型非 `STRING/TEXT` ```SQL -- 示例1 @@ -1488,19 +2071,19 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h -## 9. 字符串函数和操作符 +## 10. 字符串函数和操作符 -### 9.1 字符串操作符 +### 10.1 字符串操作符 -#### 9.1.1 || 操作符 +#### 10.1.1 || 操作符 `||` 操作符用于字符串连接，功能与 `concat` 函数相同。 -#### 9.1.2 LIKE 语句 +#### 10.1.2 LIKE 语句 `LIKE` 语句用于模式匹配，具体用法在[模式匹配：LIKE](#1-like-运算符) 中有详细文档。 -### 9.2 字符串函数 +### 10.2 字符串函数 | 函数名 | 描述 | 输入 | 输出 | 用法 | | ----------- |---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------ | ------------------------------------------------------------ | @@ -1518,33 +2101,33 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h | substring | 从指定位置提取字符到字符串末尾。需要注意的是，起始位置是基于字符而不是字节数组确定的。`start_index` 从 1 开始计数，长度从 `start_index` 位置计算。 | 支持两个参数**string**：要提取子字符串的源字符串，可以是字符串或文本类型。**start_index**：从哪个索引开始提取子字符串，索引从 1 开始计数。 | String：返回一个字符串，从 `start_index` 位置开始到字符串末尾的所有字符。**注意事项**：`start_index` 从 1 开始，即数组的第 0 个位置是 1参数为 null时，返回 `null`start_index 大于字符串长度时，结果报错。 | substring(string from start_index)或 substring(string, start_index) | | substring | 从一个字符串中提取从指定位置开始、指定长度的子字符串注意：起始位置和长度是基于字符而不是字节数组确定的。`start_index` 从 1 开始计数，长度从 `start_index` 位置计算。 | 支持三个参数**string**：要提取子字符串的源字符串，可以是字符串或文本类型。**start_index**：从哪个索引开始提取子字符串，索引从 1 开始计数。**length**：要提取的子字符串的长度。 | String：返回一个字符串，从 `start_index` 位置开始，提取 `length` 个字符。**注意事项**：参数为 null时，返回 `null`如果 `start_index` 大于字符串的长度，结果报错。如果 `length` 小于 0，结果报错。极端情况，`start_index + length` 超过 `int.MAX` 并变成负数，将导致异常结果。 | substring(string from start_index for length) 或 substring(string, start_index, length) | -## 10. 模式匹配函数 +## 11. 模式匹配函数 -### 10.1 LIKE 运算符 +### 11.1 LIKE 运算符 -#### 10.1.1 用途 +#### 11.1.1 用途 `LIKE` 运算符用于将值与模式进行比较。它通常用于 `WHERE` 子句中，用于匹配字符串中的特定模式。 -#### 10.1.2 语法 +#### 11.1.2 语法 ```SQL ... column [NOT] LIKE 'pattern' ESCAPE 'character'; ``` -#### 10.1.3 匹配规则 +#### 11.1.3 匹配规则 - 匹配字符是区分大小写的。 - 模式支持两个匹配符号： - - `_`：匹配任意单个字符。 - - `%`：匹配0个或多个字符。 + - `_`：匹配任意单个字符。 + - `%`：匹配0个或多个字符。 -#### 10.1.4 注意事项 +#### 11.1.4 注意事项 - `LIKE` 模式匹配总是覆盖整个字符串。如果需要匹配字符串中的任意位置，模式必须以 `%` 开头和结尾。 - 如果需要匹配 `%` 或 `_` 作为普通字符，必须使用转义字符。 -#### 10.1.5 示例 +#### 11.1.5 示例 示例 1：匹配以特定字符开头的字符串 @@ -1586,42 +2169,42 @@ SELECT * FROM table1 WHERE continent LIKE 'South\_%' ESCAPE '\'; SELECT * FROM table1 WHERE continent LIKE 'South\\%' ESCAPE '\'; ``` -### 10.2 regexp_like 函数 +### 11.2 regexp_like 函数 -#### 10.2.1 用途 +#### 11.2.1 用途 `regexp_like` 函数用于评估正则表达式模式，并确定该模式是否包含在字符串中。 -#### 10.2.2 语法 +#### 11.2.2 语法 ```SQL regexp_like(string, pattern); ``` -#### 10.2.3 注意事项 +#### 11.2.3 注意事项 - `regexp_like` 的模式只需包含在字符串中，而不需要匹配整个字符串。 - 如果需要匹配整个字符串，可以使用正则表达式的锚点 `^` 和 `$`。 - `^` 表示“字符串的开头”，`$` 表示“字符串的结尾”。 - 正则表达式采用 Java 定义的正则语法，但存在以下需要注意的例外情况： - - **多行模式** - 1. 启用方式：`(?m)`。 - 2. 只识别`\n`作为行终止符。 - 3. 不支持`(?d)`标志，且禁止使用。 - - **不区分大小写匹配** - 1. 启用方式：`(?i)`。 - 2. 基于Unicode规则，不支持上下文相关和本地化匹配。 - 3. 不支持`(?u)`标志，且禁止使用。 - - **字符类** - 1. 在字符类（如`[A-Z123]`）中，`\Q`和`\E`不被支持，被视为普通字面量。 - - **Unicode字符类（**`\p{prop}`**）** - 1. **名称下划线**：名称中的所有下划线必须删除（如`OldItalic`而非`Old_Italic`）。 - 2. **文字（Scripts）**：直接指定，无需`Is`、`script=`或`sc=`前缀（如`\p{Hiragana}`）。 - 3. **区块（Blocks）**：必须使用`In`前缀，不支持`block=`或`blk=`前缀（如`\p{InMongolian}`）。 - 4. **类别（Categories）**：直接指定，无需`Is`、`general_category=`或`gc=`前缀（如`\p{L}`）。 - 5. **二元属性（Binary Properties）**：直接指定，无需`Is`（如`\p{NoncharacterCodePoint}`）。 - -#### 10.2.4 示例 + - **多行模式** + 1. 启用方式：`(?m)`。 + 2. 只识别`\n`作为行终止符。 + 3. 不支持`(?d)`标志，且禁止使用。 + - **不区分大小写匹配** + 1. 启用方式：`(?i)`。 + 2. 基于Unicode规则，不支持上下文相关和本地化匹配。 + 3. 不支持`(?u)`标志，且禁止使用。 + - **字符类** + 1. 在字符类（如`[A-Z123]`）中，`\Q`和`\E`不被支持，被视为普通字面量。 + - **Unicode字符类（**`\p{prop}`**）** + 1. **名称下划线**：名称中的所有下划线必须删除（如`OldItalic`而非`Old_Italic`）。 + 2. **文字（Scripts）**：直接指定，无需`Is`、`script=`或`sc=`前缀（如`\p{Hiragana}`）。 + 3. **区块（Blocks）**：必须使用`In`前缀，不支持`block=`或`blk=`前缀（如`\p{InMongolian}`）。 + 4. **类别（Categories）**：直接指定，无需`Is`、`general_category=`或`gc=`前缀（如`\p{L}`）。 + 5. **二元属性（Binary Properties）**：直接指定，无需`Is`（如`\p{NoncharacterCodePoint}`）。 + +#### 11.2.4 示例 示例 1：匹配包含特定模式的字符串 @@ -1630,9 +2213,9 @@ SELECT regexp_like('1a 2b 14m', '\\d+b'); -- true ``` - **说明**：检查字符串 `'1a 2b 14m'` 是否包含模式 `\d+b`。 - - `\d+` 表示“一个或多个数字”。 - - `b` 表示字母 `b`。 - - 在 `'1a 2b 14m'` 中，`2b` 符合这个模式，所以返回 `true`。 + - `\d+` 表示“一个或多个数字”。 + - `b` 表示字母 `b`。 + - 在 `'1a 2b 14m'` 中，`2b` 符合这个模式，所以返回 `true`。 示例 2：匹配整个字符串 @@ -1641,11 +2224,11 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false ``` - **说明**：检查字符串 `'1a 2b 14m'` 是否完全匹配模式 `^\\d+b$`。 - - `\d+` 表示“一个或多个数字”。 - - `b` 表示字母 `b`。 - - `'1a 2b 14m'` 并不符合这个模式，因为它不是从数字开始，也不是以 `b` 结束，所以返回 `false`。 + - `\d+` 表示“一个或多个数字”。 + - `b` 表示字母 `b`。 + - `'1a 2b 14m'` 并不符合这个模式，因为它不是从数字开始，也不是以 `b` 结束，所以返回 `false`。 -## 11. 时序分窗函数 +## 12. 时序分窗函数 原始示例数据如下： @@ -1668,19 +2251,19 @@ CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); ``` -### 11.1 HOP +### 12.1 HOP -#### 11.1.1 功能描述 +#### 12.1.1 功能描述 HOP 函数用于按时间分段分窗分析，识别每一行数据所属的时间窗口。该函数通过指定固定窗口大小（size）和窗口滑动步长（SLIDE），将数据按时间戳分配到所有与其时间戳重叠的窗口中。若窗口之间存在重叠（步长 < 窗口大小），数据会自动复制到多个窗口。 -#### 11.1.2 函数定义 +#### 12.1.2 函数定义 ```SQL HOP(data, timecol, size, slide[, origin]) ``` -#### 11.1.3 参数说明 +#### 12.1.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------- | @@ -1690,7 +2273,7 @@ HOP(data, timecol, size, slide[, origin]) | SLIDE | 标量参数 | 长整数类型 | 窗口滑动步长 | | ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | -#### 11.1.4 返回结果 +#### 12.1.4 返回结果 HOP 函数的返回结果列包含： @@ -1698,7 +2281,7 @@ HOP 函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.1.5 使用示例 +#### 12.1.5 使用示例 ```SQL IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); @@ -1733,18 +2316,18 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DAT +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.2 SESSION +### 12.2 SESSION -#### 11.2.1 功能描述 +#### 12.2.1 功能描述 SESSION 函数用于按会话间隔对数据进行分窗。系统逐行检查与前一行的时间间隔，小于阈值（GAP）则归入当前窗口，超过则归入下一个窗口。 -#### 11.2.2 函数定义 +#### 12.2.2 函数定义 ```SQL SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) ``` -#### 11.2.3 参数说明 +#### 12.2.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | -------------------------- | ---------------------------------------- | @@ -1753,7 +2336,7 @@ SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) | | GAP | 标量参数 | 长整数类型 | 会话间隔阈值 | -#### 11.2.4 返回结果 +#### 12.2.4 返回结果 SESSION 函数的返回结果列包含： @@ -1761,7 +2344,7 @@ SESSION 函数的返回结果列包含： * window\_end: 会话窗口内的最后一条数据的时间 * 映射列：DATA 参数的所有输入列 -#### 11.2.5 使用示例 +#### 12.2.5 使用示例 ```SQL IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); @@ -1787,19 +2370,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.3 VARIATION +### 12.3 VARIATION -#### 11.3.1 功能描述 +#### 12.3.1 功能描述 VARIATION 函数用于按数据差值分窗，将第一条数据作为首个窗口的基准值，每个数据点会与基准值进行差值运算，如果差值小于给定的阈值（delta）则加入当前窗口；如果超过阈值，则分为下一个窗口，将该值作为下一个窗口的基准值。 -#### 11.3.2 函数定义 +#### 12.3.2 函数定义 ```sql VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) ``` -#### 11.3.3 参数说明 +#### 12.3.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | -------- | ---------- | -------------------------- | ---------------------------------------- | @@ -1807,14 +2390,14 @@ VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) | COL | 标量参数 | 字符串类型 | 标识对哪一列计算差值 | | DELTA | 标量参数 | 浮点数类型 | 差值阈值 | -#### 11.3.4 返回结果 +#### 12.3.4 返回结果 VARIATION 函数的返回结果列包含： * window\_index: 窗口编号 * 映射列：DATA 参数的所有输入列 -#### 11.3.5 使用示例 +#### 12.3.5 使用示例 ```sql IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); @@ -1841,33 +2424,33 @@ IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, a +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.4 CAPACITY +### 12.4 CAPACITY -#### 11.4.1 功能描述 +#### 12.4.1 功能描述 CAPACITY 函数用于按数据点数（行数）分窗，每个窗口最多有 SIZE 行数据。 -#### 11.4.2 函数定义 +#### 12.4.2 函数定义 ```sql CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) ``` -#### 11.4.3 参数说明 +#### 12.4.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | -------- | ---------- | -------------------------- | ---------------------------------------- | | DATA | 表参数 | SET SEMANTICPASS THROUGH | 输入表通过 pkeys、okeys 指定分区和排序 | | SIZE | 标量参数 | 长整数类型 | 窗口大小 | -#### 11.4.4 返回结果 +#### 12.4.4 返回结果 CAPACITY 函数的返回结果列包含： * window\_index: 窗口编号 * 映射列：DATA 参数的所有输入列 -#### 11.4.5 使用示例 +#### 12.4.5 使用示例 ```sql IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); @@ -1894,18 +2477,18 @@ IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(p +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.5 TUMBLE +### 12.5 TUMBLE -#### 11.5.1 功能描述 +#### 12.5.1 功能描述 TUMBLE 函数用于通过时间属性字段为每行数据分配一个窗口，滚动窗口的大小固定且不重复。 -#### 11.5.2 函数定义 +#### 12.5.2 函数定义 ```sql TUMBLE(data, timecol, size[, origin]) ``` -#### 11.5.3 参数说明 +#### 12.5.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------- | @@ -1914,7 +2497,7 @@ TUMBLE(data, timecol, size[, origin]) | SIZE | 标量参数 | 长整数类型 | 窗口大小，需为正数 | | ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | -#### 11.5.4 返回结果 +#### 12.5.4 返回结果 TUBMLE 函数的返回结果列包含： @@ -1922,7 +2505,7 @@ TUBMLE 函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.5.5 使用示例 +#### 12.5.5 使用示例 ```SQL IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); @@ -1948,19 +2531,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE( +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.6 CUMULATE +### 12.6 CUMULATE -#### 11.6.1 功能描述 +#### 12.6.1 功能描述 Cumulate 函数用于从初始的窗口开始，创建相同窗口开始但窗口结束步长不同的窗口，直到达到最大的窗口大小。每个窗口包含其区间内的元素。例如：1小时步长，24小时大小的累计窗口，每天可以获得如下这些窗口：`[00:00, 01:00)`，`[00:00, 02:00)`，`[00:00, 03:00)`， …， `[00:00, 24:00)` -#### 11.6.2 函数定义 +#### 12.6.2 函数定义 ```sql CUMULATE(data, timecol, size, step[, origin]) ``` -#### 11.6.3 参数说明 +#### 12.6.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------------------------------- | @@ -1972,7 +2555,7 @@ CUMULATE(data, timecol, size, step[, origin]) > 注意：size 如果不是 step 的整数倍，则会报错`Cumulative table function requires size must be an integral multiple of step` -#### 11.6.4 返回结果 +#### 12.6.4 返回结果 CUMULATE函数的返回结果列包含： @@ -1980,7 +2563,7 @@ CUMULATE函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.6.5 使用示例 +#### 12.6.5 使用示例 ```sql IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m); diff --git a/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_timecho.md b/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_timecho.md index 210eb2613..f8a48b9e1 100644 --- a/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_timecho.md +++ b/src/zh/UserGuide/Master/Table/SQL-Manual/Basis-Function_timecho.md @@ -1205,13 +1205,596 @@ IoTDB:database1> select length, width, bitwise_right_shift_arithmetic(length,wid +------+-----+-----+ ``` -## 7. 条件表达式 +## 7. 二进制函数 -### 7.1 CASE 表达式 +> V2.0.9.1 起支持 + +### 7.1 Base64 编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ----------------------------- | ------------------------------------------------------------------------- | ------------------ | -------------- | +| `to_base64(input)` | 将输入数据编码为标准 Base64 字符串，解决二进制数据传输 / 存储兼容性问题 | STRING/TEXT/BLOB | STRING | +| `from_base64(input)` | 将标准 Base64 字符串解码为原始二进制数据，为 to\_base64 逆操作 | STRING/TEXT | BLOB | +| `to_base64url(input)` | 将输入数据编码为 URL 安全的 Base64URL 字符串，替换 +/\_、省略填充符 | STRING/TEXT/BLOB | STRING | +| `from_base64url(input)` | 将 Base64URL 字符串解码为原始二进制数据，为 to\_base64url 逆操作 | STRING/TEXT | BLOB | +| `to_base32(input)` | 将输入数据编码为 Base32 字符串，字符无混淆、不区分大小写，可读性高 | STRING/TEXT/BLOB | STRING | +| `from_base32(input)` | 将 Base32 字符串解码为原始二进制数据，为 to\_base32 逆操作 | STRING/TEXT | BLOB | + +**使用示例** + +1. to\_base64：编码字符串为标准Base64 + +```SQL +SELECT DISTINCT to_base64('IoTDB二进制测试') FROM table1; +``` + +```Bash ++----------------------------+ +| _col0| ++----------------------------+ +|SW9URELkuozov5vliLbmtYvor5U=| ++----------------------------+ +``` + +2. from\_base64：解码Base64字符串为二进制 + +```SQL +SELECT DISTINCT from_base64('SW9URELkuozov5vliLbmtYvor5U=') FROM table1; +``` + +```Bash ++------------------------------------------+ +| _col0| ++------------------------------------------+ +|0x496f544442e4ba8ce8bf9be588b6e6b58be8af95| ++------------------------------------------+ +``` + +3. to\_base64url：编码为URL安全的Base64URL（无+/\_、无填充符=） + +```SQL +SELECT DISTINCT to_base64url('https://iotdb.apache.org') FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn| ++--------------------------------+ +``` + +4. from\_base64url：解码Base64URL字符串 + +```SQL +SELECT DISTINCT from_base64url('aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn') FROM table1; +``` + +```Bash ++--------------------------------------------------+ +| _col0| ++--------------------------------------------------+ +|0x68747470733a2f2f696f7464622e6170616368652e6f7267| ++--------------------------------------------------+ +``` + +5. to\_base32：编码为Base32字符串 + +```SQL +SELECT DISTINCT to_base32('123456') FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|GEZDGNBVGY======| ++----------------+ +``` + +6. from\_base32：解码Base32字符串 + +```SQL +SELECT DISTINCT from_base32('GEZDGNBVGY======') FROM table1; +``` + +```SQL ++--------------+ +| _col0| ++--------------+ +|0x313233343536| ++--------------+ +``` + +### 7.2 十六进制编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ----------------------- | -------------------------------------------------------------- | ------------------ | -------------- | +| `TO_HEX(input)` | 将输入数据转换为十六进制字符串，直接反映底层字节值，便于调试 | STRING/TEXT/BLOB | STRING | +| `FROM_HEX(input)` | 将十六进制字符串解码为原始二进制数据，为TO\_HEX逆操作 | STRING/TEXT | BLOB | + +**使用示例** + +1. TO\_HEX：将字符串/二进制转换为十六进制 + +```SQL +SELECT DISTINCT TO_HEX('test') FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|74657374| ++--------+ +``` + +2. FROM\_HEX：将十六进制字符串解码为二进制 + +```SQL +SELECT DISTINCT FROM_HEX('74657374') FROM table1; +``` + +```Bash ++----------+ +| _col0| ++----------+ +|0x74657374| ++----------+ +``` + +### 7.3 二进制基础函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| -------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------- | ---------------- | +| `length(input)` | 返回输入数据长度，文本类型返字符数，BLOB类型返回字节数，OBJECT 类型返回对象二进制字节大小 | STRING/TEXT/BLOB/OBJECT | INT32 | +| `REVERSE(input)`| 反转输入数据顺序，文本类型反转字符，BLOB类型反转字节 | STRING/TEXT/BLOB | 与输入类型一致 | +| `LPAD(input, length, pad_bytes)` | 对BLOB进行字节级左填充/截断，使最终字节长度等于指定值 | BLOB、INT32/INT64、BLOB | BLOB | +| `RPAD(input, length, pad_bytes)` | 对BLOB进行字节级右填充/截断，使最终字节长度等于指定值 | BLOB、INT32/INT64、BLOB | BLOB | + +**使用示例** + +1. length：获取数据长度 + +```SQL +SELECT DISTINCT length('IoTDB') FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +| 5| ++-----+ +``` + +2. REVERSE：反转数据 + +```SQL +SELECT DISTINCT REVERSE('12345') FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|54321| ++-----+ +``` + +3. LPAD：左填充/截断BLOB（参数：原BLOB、目标长度、填充字节） + +```SQL +SELECT DISTINCT LPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|0x7474657374| ++------------+ +``` + +4. RPAD：右填充/截断BLOB + +```SQL +SELECT DISTINCT RPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|0x7465737474| ++------------+ +``` + +### 7.4 整数编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------------ | ------------------------------------------------------------------ | -------------- | -------------- | +| `to_big_endian_32(input)` | 将INT32整数转换为4字节大端序BLOB，符合网络字节序标准 | INT32 | BLOB | +| `to_big_endian_64(input)` | 将INT64整数转换为8字节大端序BLOB，符合网络字节序标准 | INT64 | BLOB | +| `from_big_endian_32(input)` | 将4字节大端序BLOB解码为INT32整数，为to\_big\_endian\_32逆操作 | BLOB | INT32 | +| `from_big_endian_64(input)` | 将8字节大端序BLOB解码为INT64整数，为to\_big\_endian\_64逆操作 | BLOB | INT64 | +| `to_little_endian_32(input)` | 将INT32整数转换为4字节小端序BLOB，适配x86等主流架构 | INT32 | BLOB | +| `to_little_endian_64(input)` | 将INT64整数转换为8字节小端序BLOB，适配x86等主流架构 | INT64 | BLOB | +| `from_little_endian_32(input)` | 将4字节小端序BLOB解码为INT32整数，为to\_little\_endian\_32逆操作 | BLOB | INT32 | +| `from_little_endian_64(input)` | 将8字节小端序BLOB解码为INT64整数，为to\_little\_endian\_64逆操作 | BLOB | INT64 | + +**使用示例** + +1. 大端序编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_32(12345)) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|00003039| ++--------+ +``` + +```SQL +SELECT DISTINCT from_big_endian_32(FROM_HEX('00003039')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|12345| ++-----+ +``` + +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_64(1234567890123)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|0000011f71fb04cb| ++----------------+ +``` + +```SQL +SELECT DISTINCT from_big_endian_64(FROM_HEX('0000011f71fb04cb')) FROM table1; +``` + +```Bash ++-------------+ +| _col0| ++-------------+ +|1234567890123| ++-------------+ +``` + +2. 小端序编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_32(12345)) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|39300000| ++--------+ +``` + +```SQL +SELECT DISTINCT from_little_endian_32(FROM_HEX('39300000')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|12345| ++-----+ +``` + +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_64(1234567890123)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|cb04fb711f010000| ++----------------+ +``` + +```SQL +SELECT DISTINCT from_little_endian_64(FROM_HEX('cb04fb711f010000')) FROM table1; +``` + +```Bash ++-------------+ +| _col0| ++-------------+ +|1234567890123| ++-------------+ +``` + +### 7.5 浮点型编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------ | ------------------------------------------------------------------- | -------------- | -------------- | +| `to_ieee754_32(input)` | 将FLOAT单精度浮点数转换为4字节大端序IEEE754标准BLOB | FLOAT | BLOB | +| `to_ieee754_64(input)` | 将DOUBLE双精度浮点数转换为8字节大端序IEEE754标准BLOB | DOUBLE | BLOB | +| `from_ieee754_32(input)` | 将4字节IEEE754标准BLOB解码为FLOAT浮点数，为to\_ieee754\_32逆操作 | BLOB | FLOAT | +| `from_ieee754_64(input)` | 将8字节IEEE754标准BLOB解码为DOUBLE浮点数，为to\_ieee754\_64逆操作 | BLOB | DOUBLE | + +**使用示例** + +1. 单精度浮点数（FLOAT）编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_ieee754_32(temperature)) FROM table1 where time = 2024-11-26 13:37:00; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|42b40000| ++--------+ +``` + +```SQL +SELECT DISTINCT from_ieee754_32(FROM_HEX('42b40000')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +| 90.0| ++-----+ +``` + +2. 双精度浮点数（DOUBLE）编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_ieee754_64(3.1415926535)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|400921fb54411744| ++----------------+ +``` + +```Bash +SELECT DISTINCT from_ieee754_64(FROM_HEX('400921fb54411744')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|3.1415926535| ++------------+ +``` + +### 7.6 哈希函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| -------------------------------- | ---------------------------------------------------------------- | -------------------- | -------------- | +| `sha256(input)` | 计算输入数据的SHA-256密码学哈希值，不可逆、抗碰撞 | STRING、TEXT、BLOB | BLOB(32字节) | +| `SHA512(input)` | 计算输入数据的SHA-512密码学哈希值，安全强度高于SHA256 | STRING、TEXT、BLOB | BLOB(64字节) | +| `SHA1(input)` | 计算输入数据的SHA-1哈希值，抗碰撞性弱，不推荐安全场景使用 | STRING、TEXT、BLOB | BLOB(20字节) | +| `MD5(input)` | 计算输入数据的MD5哈希值，无密码学安全性，仅用于非加密校验 | STRING、TEXT、BLOB | BLOB(16字节) | +| `CRC32(input)` | 计算输入数据的CRC32循环冗余校验码，高效检测非恶意数据错误 | STRING、TEXT、BLOB | INT64 | +| `spooky_hash_v2_32(input)` | 计算输入数据的32位SpookyHashV2非密码学哈希值，高性能、低冲突 | STRING、TEXT、BLOB | BLOB(4字节) | +| `spooky_hash_v2_64(input)` | 计算输入数据的64位SpookyHashV2非密码学哈希值，高性能、低冲突 | STRING、TEXT、BLOB | BLOB(8字节) | +| `xxhash64(input)` | 计算输入数据的64位xxHash非密码学哈希值，计算速度极快 | STRING、TEXT、BLOB | BLOB(8字节) | +| `murmur3(input)` | 计算输入数据的128位MurmurHash3非密码学哈希值，分布均匀、应用广 | STRING、TEXT、BLOB | BLOB(16字节) | + +**使用示例** + +1. 密码学哈希函数 + +```SQL +SELECT DISTINCT TO_HEX(sha256('test')) FROM table1; +``` + +```Bash ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08| ++----------------------------------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(SHA512('test')) FROM table1; +``` + +```Bash ++--------------------------------------------------------------------------------------------------------------------------------+ +| _col0| ++--------------------------------------------------------------------------------------------------------------------------------+ +|ee26b0dd4af7e749aa1a8ee3c10ae9923f618980772e473f8819a5d4940e0db27ac185f8a0e1d5f84f88bc887fd67b143732c304cc5fa9ad8e6f57f50028a8ff| ++--------------------------------------------------------------------------------------------------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(SHA1('test')) FROM table1; +``` + +```Bash ++----------------------------------------+ +| _col0| ++----------------------------------------+ +|a94a8fe5ccb19ba61c4c0873d391e987982fbbd3| ++----------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(MD5('test')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|098f6bcd4621d373cade4e832627b4f6| ++--------------------------------+ +``` + +2. 校验/非密码学哈希函数 + +```SQL +SELECT DISTINCT CRC32('test') FROM table1; +``` + +```Bash ++----------+ +| _col0| ++----------+ +|3632233996| ++----------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(spooky_hash_v2_32('test')) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|ec0d8b75| ++--------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(spooky_hash_v2_64('test')) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|7b01e8bcec0d8b75| ++----------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(xxhash64('test')) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|4fdcca5ddb678139| ++----------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(murmur3('test')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|9de1bd74cc287dac824dbdf93182129a| ++--------------------------------+ +``` + +### 7.7 HMAC函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------ | ------------------------------------------------------------------- | -------------------------------------------- | -------------- | +| `hmac_md5(data, key)` | 结合MD5与密钥计算HMAC消息认证码，验证数据完整性和来源，适配旧系统 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(16字节) | +| `hmac_sha1(data, key)` | 结合SHA-1与密钥计算HMAC消息认证码，验证数据完整性和来源 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(20字节) | +| `hmac_sha256(data, key)` | 结合SHA256与密钥计算HMAC消息认证码，业界推荐标准，安全强度高 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(32字节) | +| `hmac_sha512(data, key)` | 结合SHA512与密钥计算HMAC消息认证码，商用级别最高安全强度 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(64字节) | + +**使用示例** + +* 通用密钥：'iotdb\_secret\_key' +* 待验证数据：'user\_data\_123' + +1. hmac\_md5 + +```SQL +SELECT DISTINCT TO_HEX(hmac_md5('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|8ee863080ceb3b43b5ffdc7a937e7f28| ++--------------------------------+ +``` + +2. hmac\_sha1 + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha1('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++----------------------------------------+ +| _col0| ++----------------------------------------+ +|b5b7ae1a495745299ec3bd236c511c13540481ce| ++----------------------------------------+ +``` + +3. hmac\_sha256（推荐使用） + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha256('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|73b6f26bbcb5192dbe2cb83745b0fc48c63418fa674b0bf62fabe7f8747f3afd| ++----------------------------------------------------------------+ +``` + +4. hmac\_sha512 + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha512('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++--------------------------------------------------------------------------------------------------------------------------------+ +| _col0| ++--------------------------------------------------------------------------------------------------------------------------------+ +|2fed4ec5a0535e3349798b371d6525255ee85d9eae0ddcbdecf89db84f943151f5febf0ffd9c01ae9661278504aba186cf6f732ae5f42d63be58aadee2baccc2| ++--------------------------------------------------------------------------------------------------------------------------------+ +``` + + + +## 8. 条件表达式 + +### 8.1 CASE 表达式 CASE 表达式有两种形式：简单形式、搜索形式 -#### 7.1.1 简单形式 +#### 8.1.1 简单形式 简单形式从左到右搜索每个值表达式，直到找到一个与表达式相等的值： @@ -1234,7 +1817,7 @@ SELECT a, END ``` -#### 7.1.2 搜索形式 +#### 8.1.2 搜索形式 搜索形式从左到右评估每个布尔条件，直到找到一个为真的条件，并返回相应的结果： @@ -1257,7 +1840,7 @@ SELECT a, b, END ``` -### 7.2 COALESCE 函数 +### 8.2 COALESCE 函数 返回参数列表中的第一个非空值。 @@ -1265,11 +1848,11 @@ SELECT a, b, coalesce(value1, value2[, ...]) ``` -## 8. 转换函数 +## 9. 转换函数 -### 8.1 转换函数 +### 9.1 转换函数 -#### 8.1.1 cast(value AS type) → type +#### 9.1.1 cast(value AS type) → type 1. 显式地将一个值转换为指定类型。 2. 可以用于将字符串（varchar）转换为数值类型，或数值转换为字符串类型，V2.0.8 版本起支持 OBJECT 类型强转成 STRING 类型。 @@ -1284,7 +1867,7 @@ SELECT * IN (CAST('2024-11-27' AS DATE), CAST('2024-11-28' AS DATE)); ``` -#### 8.1.2 try_cast(value AS type) → type +#### 9.1.2 try_cast(value AS type) → type 1. 与 `cast()` 类似。 2. 如果转换失败，则返回 `null`。 @@ -1298,10 +1881,10 @@ SELECT * IN (try_cast('2024-11-27' AS DATE), try_cast('2024-11-28' AS DATE)); ``` -### 8.2 Format 函数 +### 9.2 Format 函数 该函数基于指定的格式字符串与输入参数，生成并返回格式化后的字符串输出。其功能与 Java 语言中的`String.format` 方法及 C 语言中的`printf`函数相类似，支持开发者通过占位符语法构建动态字符串模板，其中预设的格式标识符将被传入的对应参数值精准替换，最终形成符合特定格式要求的完整字符串。 -#### 8.2.1 语法介绍 +#### 9.2.1 语法介绍 ```SQL format(pattern,...args) -> String @@ -1319,7 +1902,7 @@ format(pattern,...args) -> String * 类型为 `STRING` 的格式化结果字符串 -#### 8.2.2 使用示例 +#### 9.2.2 使用示例 1. 格式化浮点数 @@ -1435,7 +2018,7 @@ IoTDB:database1> SELECT format('%s%%', 99.9) from table1 limit 1 +-----+ ``` -#### 8.2.3 **格式转换失败场景说明** +#### 9.2.3 **格式转换失败场景说明** 1. 类型不匹配错误 @@ -1488,19 +2071,19 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h -## 9. 字符串函数和操作符 +## 10. 字符串函数和操作符 -### 9.1 字符串操作符 +### 10.1 字符串操作符 -#### 9.1.1 || 操作符 +#### 10.1.1 || 操作符 `||` 操作符用于字符串连接，功能与 `concat` 函数相同。 -#### 9.1.2 LIKE 语句 +#### 10.1.2 LIKE 语句 `LIKE` 语句用于模式匹配，具体用法在[模式匹配：LIKE](#1-like-运算符) 中有详细文档。 -### 9.2 字符串函数 +### 10.2 字符串函数 | 函数名 | 描述 | 输入 | 输出 | 用法 | | ----------- |---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------ | ------------------------------------------------------------ | @@ -1518,33 +2101,33 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h | substring | 从指定位置提取字符到字符串末尾。需要注意的是，起始位置是基于字符而不是字节数组确定的。`start_index` 从 1 开始计数，长度从 `start_index` 位置计算。 | 支持两个参数**string**：要提取子字符串的源字符串，可以是字符串或文本类型。**start_index**：从哪个索引开始提取子字符串，索引从 1 开始计数。 | String：返回一个字符串，从 `start_index` 位置开始到字符串末尾的所有字符。**注意事项**：`start_index` 从 1 开始，即数组的第 0 个位置是 1参数为 null时，返回 `null`start_index 大于字符串长度时，结果报错。 | substring(string from start_index)或 substring(string, start_index) | | substring | 从一个字符串中提取从指定位置开始、指定长度的子字符串注意：起始位置和长度是基于字符而不是字节数组确定的。`start_index` 从 1 开始计数，长度从 `start_index` 位置计算。 | 支持三个参数**string**：要提取子字符串的源字符串，可以是字符串或文本类型。**start_index**：从哪个索引开始提取子字符串，索引从 1 开始计数。**length**：要提取的子字符串的长度。 | String：返回一个字符串，从 `start_index` 位置开始，提取 `length` 个字符。**注意事项**：参数为 null时，返回 `null`如果 `start_index` 大于字符串的长度，结果报错。如果 `length` 小于 0，结果报错。极端情况，`start_index + length` 超过 `int.MAX` 并变成负数，将导致异常结果。 | substring(string from start_index for length) 或 substring(string, start_index, length) | -## 10. 模式匹配函数 +## 11. 模式匹配函数 -### 10.1 LIKE 运算符 +### 11.1 LIKE 运算符 -#### 10.1.1 用途 +#### 11.1.1 用途 `LIKE` 运算符用于将值与模式进行比较。它通常用于 `WHERE` 子句中，用于匹配字符串中的特定模式。 -#### 10.1.2 语法 +#### 11.1.2 语法 ```SQL ... column [NOT] LIKE 'pattern' ESCAPE 'character'; ``` -#### 10.1.3 匹配规则 +#### 11.1.3 匹配规则 - 匹配字符是区分大小写的。 - 模式支持两个匹配符号： - `_`：匹配任意单个字符。 - `%`：匹配0个或多个字符。 -#### 10.1.4 注意事项 +#### 11.1.4 注意事项 - `LIKE` 模式匹配总是覆盖整个字符串。如果需要匹配字符串中的任意位置，模式必须以 `%` 开头和结尾。 - 如果需要匹配 `%` 或 `_` 作为普通字符，必须使用转义字符。 -#### 10.1.5 示例 +#### 11.1.5 示例 示例 1：匹配以特定字符开头的字符串 @@ -1586,19 +2169,19 @@ SELECT * FROM table1 WHERE continent LIKE 'South\_%' ESCAPE '\'; SELECT * FROM table1 WHERE continent LIKE 'South\\%' ESCAPE '\'; ``` -### 10.2 regexp_like 函数 +### 11.2 regexp_like 函数 -#### 10.2.1 用途 +#### 11.2.1 用途 `regexp_like` 函数用于评估正则表达式模式，并确定该模式是否包含在字符串中。 -#### 10.2.2 语法 +#### 11.2.2 语法 ```SQL regexp_like(string, pattern); ``` -#### 10.2.3 注意事项 +#### 11.2.3 注意事项 - `regexp_like` 的模式只需包含在字符串中，而不需要匹配整个字符串。 - 如果需要匹配整个字符串，可以使用正则表达式的锚点 `^` 和 `$`。 @@ -1621,7 +2204,7 @@ regexp_like(string, pattern); 4. **类别（Categories）**：直接指定，无需`Is`、`general_category=`或`gc=`前缀（如`\p{L}`）。 5. **二元属性（Binary Properties）**：直接指定，无需`Is`（如`\p{NoncharacterCodePoint}`）。 -#### 10.2.4 示例 +#### 11.2.4 示例 示例 1：匹配包含特定模式的字符串 @@ -1645,7 +2228,7 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false - `b` 表示字母 `b`。 - `'1a 2b 14m'` 并不符合这个模式，因为它不是从数字开始，也不是以 `b` 结束，所以返回 `false`。 -## 11. 时序分窗函数 +## 12. 时序分窗函数 原始示例数据如下： @@ -1668,19 +2251,19 @@ CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); ``` -### 11.1 HOP +### 12.1 HOP -#### 11.1.1 功能描述 +#### 12.1.1 功能描述 HOP 函数用于按时间分段分窗分析，识别每一行数据所属的时间窗口。该函数通过指定固定窗口大小（size）和窗口滑动步长（SLIDE），将数据按时间戳分配到所有与其时间戳重叠的窗口中。若窗口之间存在重叠（步长 < 窗口大小），数据会自动复制到多个窗口。 -#### 11.1.2 函数定义 +#### 12.1.2 函数定义 ```SQL HOP(data, timecol, size, slide[, origin]) ``` -#### 11.1.3 参数说明 +#### 12.1.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------- | @@ -1690,7 +2273,7 @@ HOP(data, timecol, size, slide[, origin]) | SLIDE | 标量参数 | 长整数类型 | 窗口滑动步长 | | ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | -#### 11.1.4 返回结果 +#### 12.1.4 返回结果 HOP 函数的返回结果列包含： @@ -1698,7 +2281,7 @@ HOP 函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.1.5 使用示例 +#### 12.1.5 使用示例 ```SQL IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); @@ -1733,18 +2316,18 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DAT +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.2 SESSION +### 12.2 SESSION -#### 11.2.1 功能描述 +#### 12.2.1 功能描述 SESSION 函数用于按会话间隔对数据进行分窗。系统逐行检查与前一行的时间间隔，小于阈值（GAP）则归入当前窗口，超过则归入下一个窗口。 -#### 11.2.2 函数定义 +#### 12.2.2 函数定义 ```SQL SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) ``` -#### 11.2.3 参数说明 +#### 12.2.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | -------------------------- | ---------------------------------------- | @@ -1753,7 +2336,7 @@ SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) | | GAP | 标量参数 | 长整数类型 | 会话间隔阈值 | -#### 11.2.4 返回结果 +#### 12.2.4 返回结果 SESSION 函数的返回结果列包含： @@ -1761,7 +2344,7 @@ SESSION 函数的返回结果列包含： * window\_end: 会话窗口内的最后一条数据的时间 * 映射列：DATA 参数的所有输入列 -#### 11.2.5 使用示例 +#### 12.2.5 使用示例 ```SQL IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); @@ -1787,19 +2370,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.3 VARIATION +### 12.3 VARIATION -#### 11.3.1 功能描述 +#### 12.3.1 功能描述 VARIATION 函数用于按数据差值分窗，将第一条数据作为首个窗口的基准值，每个数据点会与基准值进行差值运算，如果差值小于给定的阈值（delta）则加入当前窗口；如果超过阈值，则分为下一个窗口，将该值作为下一个窗口的基准值。 -#### 11.3.2 函数定义 +#### 12.3.2 函数定义 ```sql VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) ``` -#### 11.3.3 参数说明 +#### 12.3.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | -------- | ---------- | -------------------------- | ---------------------------------------- | @@ -1807,14 +2390,14 @@ VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) | COL | 标量参数 | 字符串类型 | 标识对哪一列计算差值 | | DELTA | 标量参数 | 浮点数类型 | 差值阈值 | -#### 11.3.4 返回结果 +#### 12.3.4 返回结果 VARIATION 函数的返回结果列包含： * window\_index: 窗口编号 * 映射列：DATA 参数的所有输入列 -#### 11.3.5 使用示例 +#### 12.3.5 使用示例 ```sql IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); @@ -1841,33 +2424,33 @@ IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, a +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.4 CAPACITY +### 12.4 CAPACITY -#### 11.4.1 功能描述 +#### 12.4.1 功能描述 CAPACITY 函数用于按数据点数（行数）分窗，每个窗口最多有 SIZE 行数据。 -#### 11.4.2 函数定义 +#### 12.4.2 函数定义 ```sql CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) ``` -#### 11.4.3 参数说明 +#### 12.4.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | -------- | ---------- | -------------------------- | ---------------------------------------- | | DATA | 表参数 | SET SEMANTICPASS THROUGH | 输入表通过 pkeys、okeys 指定分区和排序 | | SIZE | 标量参数 | 长整数类型 | 窗口大小 | -#### 11.4.4 返回结果 +#### 12.4.4 返回结果 CAPACITY 函数的返回结果列包含： * window\_index: 窗口编号 * 映射列：DATA 参数的所有输入列 -#### 11.4.5 使用示例 +#### 12.4.5 使用示例 ```sql IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); @@ -1894,18 +2477,18 @@ IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(p +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.5 TUMBLE +### 12.5 TUMBLE -#### 11.5.1 功能描述 +#### 12.5.1 功能描述 TUMBLE 函数用于通过时间属性字段为每行数据分配一个窗口，滚动窗口的大小固定且不重复。 -#### 11.5.2 函数定义 +#### 12.5.2 函数定义 ```sql TUMBLE(data, timecol, size[, origin]) ``` -#### 11.5.3 参数说明 +#### 12.5.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------- | @@ -1914,7 +2497,7 @@ TUMBLE(data, timecol, size[, origin]) | SIZE | 标量参数 | 长整数类型 | 窗口大小，需为正数 | | ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | -#### 11.5.4 返回结果 +#### 12.5.4 返回结果 TUBMLE 函数的返回结果列包含： @@ -1922,7 +2505,7 @@ TUBMLE 函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.5.5 使用示例 +#### 12.5.5 使用示例 ```SQL IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); @@ -1948,19 +2531,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE( +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.6 CUMULATE +### 12.6 CUMULATE -#### 11.6.1 功能描述 +#### 12.6.1 功能描述 Cumulate 函数用于从初始的窗口开始，创建相同窗口开始但窗口结束步长不同的窗口，直到达到最大的窗口大小。每个窗口包含其区间内的元素。例如：1小时步长，24小时大小的累计窗口，每天可以获得如下这些窗口：`[00:00, 01:00)`，`[00:00, 02:00)`，`[00:00, 03:00)`， …， `[00:00, 24:00)` -#### 11.6.2 函数定义 +#### 12.6.2 函数定义 ```sql CUMULATE(data, timecol, size, step[, origin]) ``` -#### 11.6.3 参数说明 +#### 12.6.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------------------------------- | @@ -1972,7 +2555,7 @@ CUMULATE(data, timecol, size, step[, origin]) > 注意：size 如果不是 step 的整数倍，则会报错`Cumulative table function requires size must be an integral multiple of step` -#### 11.6.4 返回结果 +#### 12.6.4 返回结果 CUMULATE函数的返回结果列包含： @@ -1980,7 +2563,7 @@ CUMULATE函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.6.5 使用示例 +#### 12.6.5 使用示例 ```sql IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m); diff --git a/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md b/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md index b1c772aac..63ebd6461 100644 --- a/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md +++ b/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_apache.md @@ -1205,13 +1205,596 @@ IoTDB:database1> select length, width, bitwise_right_shift_arithmetic(length,wid +------+-----+-----+ ``` -## 7. 条件表达式 +## 7. 二进制函数 -### 7.1 CASE 表达式 +> V2.0.9-beta 起支持 + +### 7.1 Base64 编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ----------------------------- | ------------------------------------------------------------------------- | ------------------ | -------------- | +| `to_base64(input)` | 将输入数据编码为标准 Base64 字符串，解决二进制数据传输 / 存储兼容性问题 | STRING/TEXT/BLOB | STRING | +| `from_base64(input)` | 将标准 Base64 字符串解码为原始二进制数据，为 to\_base64 逆操作 | STRING/TEXT | BLOB | +| `to_base64url(input)` | 将输入数据编码为 URL 安全的 Base64URL 字符串，替换 +/\_、省略填充符 | STRING/TEXT/BLOB | STRING | +| `from_base64url(input)` | 将 Base64URL 字符串解码为原始二进制数据，为 to\_base64url 逆操作 | STRING/TEXT | BLOB | +| `to_base32(input)` | 将输入数据编码为 Base32 字符串，字符无混淆、不区分大小写，可读性高 | STRING/TEXT/BLOB | STRING | +| `from_base32(input)` | 将 Base32 字符串解码为原始二进制数据，为 to\_base32 逆操作 | STRING/TEXT | BLOB | + +**使用示例** + +1. to\_base64：编码字符串为标准Base64 + +```SQL +SELECT DISTINCT to_base64('IoTDB二进制测试') FROM table1; +``` + +```Bash ++----------------------------+ +| _col0| ++----------------------------+ +|SW9URELkuozov5vliLbmtYvor5U=| ++----------------------------+ +``` + +2. from\_base64：解码Base64字符串为二进制 + +```SQL +SELECT DISTINCT from_base64('SW9URELkuozov5vliLbmtYvor5U=') FROM table1; +``` + +```Bash ++------------------------------------------+ +| _col0| ++------------------------------------------+ +|0x496f544442e4ba8ce8bf9be588b6e6b58be8af95| ++------------------------------------------+ +``` + +3. to\_base64url：编码为URL安全的Base64URL（无+/\_、无填充符=） + +```SQL +SELECT DISTINCT to_base64url('https://iotdb.apache.org') FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn| ++--------------------------------+ +``` + +4. from\_base64url：解码Base64URL字符串 + +```SQL +SELECT DISTINCT from_base64url('aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn') FROM table1; +``` + +```Bash ++--------------------------------------------------+ +| _col0| ++--------------------------------------------------+ +|0x68747470733a2f2f696f7464622e6170616368652e6f7267| ++--------------------------------------------------+ +``` + +5. to\_base32：编码为Base32字符串 + +```SQL +SELECT DISTINCT to_base32('123456') FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|GEZDGNBVGY======| ++----------------+ +``` + +6. from\_base32：解码Base32字符串 + +```SQL +SELECT DISTINCT from_base32('GEZDGNBVGY======') FROM table1; +``` + +```SQL ++--------------+ +| _col0| ++--------------+ +|0x313233343536| ++--------------+ +``` + +### 7.2 十六进制编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ----------------------- | -------------------------------------------------------------- | ------------------ | -------------- | +| `TO_HEX(input)` | 将输入数据转换为十六进制字符串，直接反映底层字节值，便于调试 | STRING/TEXT/BLOB | STRING | +| `FROM_HEX(input)` | 将十六进制字符串解码为原始二进制数据，为TO\_HEX逆操作 | STRING/TEXT | BLOB | + +**使用示例** + +1. TO\_HEX：将字符串/二进制转换为十六进制 + +```SQL +SELECT DISTINCT TO_HEX('test') FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|74657374| ++--------+ +``` + +2. FROM\_HEX：将十六进制字符串解码为二进制 + +```SQL +SELECT DISTINCT FROM_HEX('74657374') FROM table1; +``` + +```Bash ++----------+ +| _col0| ++----------+ +|0x74657374| ++----------+ +``` + +### 7.3 二进制基础函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| -------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------- | ---------------- | +| `length(input)` | 返回输入数据长度，文本类型返字符数，BLOB类型返回字节数，OBJECT 类型返回对象二进制字节大小 | STRING/TEXT/BLOB/OBJECT | INT32 | +| `REVERSE(input)`| 反转输入数据顺序，文本类型反转字符，BLOB类型反转字节 | STRING/TEXT/BLOB | 与输入类型一致 | +| `LPAD(input, length, pad_bytes)` | 对BLOB进行字节级左填充/截断，使最终字节长度等于指定值 | BLOB、INT32/INT64、BLOB | BLOB | +| `RPAD(input, length, pad_bytes)` | 对BLOB进行字节级右填充/截断，使最终字节长度等于指定值 | BLOB、INT32/INT64、BLOB | BLOB | + +**使用示例** + +1. length：获取数据长度 + +```SQL +SELECT DISTINCT length('IoTDB') FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +| 5| ++-----+ +``` + +2. REVERSE：反转数据 + +```SQL +SELECT DISTINCT REVERSE('12345') FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|54321| ++-----+ +``` + +3. LPAD：左填充/截断BLOB（参数：原BLOB、目标长度、填充字节） + +```SQL +SELECT DISTINCT LPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|0x7474657374| ++------------+ +``` + +4. RPAD：右填充/截断BLOB + +```SQL +SELECT DISTINCT RPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|0x7465737474| ++------------+ +``` + +### 7.4 整数编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------------ | ------------------------------------------------------------------ | -------------- | -------------- | +| `to_big_endian_32(input)` | 将INT32整数转换为4字节大端序BLOB，符合网络字节序标准 | INT32 | BLOB | +| `to_big_endian_64(input)` | 将INT64整数转换为8字节大端序BLOB，符合网络字节序标准 | INT64 | BLOB | +| `from_big_endian_32(input)` | 将4字节大端序BLOB解码为INT32整数，为to\_big\_endian\_32逆操作 | BLOB | INT32 | +| `from_big_endian_64(input)` | 将8字节大端序BLOB解码为INT64整数，为to\_big\_endian\_64逆操作 | BLOB | INT64 | +| `to_little_endian_32(input)` | 将INT32整数转换为4字节小端序BLOB，适配x86等主流架构 | INT32 | BLOB | +| `to_little_endian_64(input)` | 将INT64整数转换为8字节小端序BLOB，适配x86等主流架构 | INT64 | BLOB | +| `from_little_endian_32(input)` | 将4字节小端序BLOB解码为INT32整数，为to\_little\_endian\_32逆操作 | BLOB | INT32 | +| `from_little_endian_64(input)` | 将8字节小端序BLOB解码为INT64整数，为to\_little\_endian\_64逆操作 | BLOB | INT64 | + +**使用示例** + +1. 大端序编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_32(12345)) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|00003039| ++--------+ +``` + +```SQL +SELECT DISTINCT from_big_endian_32(FROM_HEX('00003039')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|12345| ++-----+ +``` + +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_64(1234567890123)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|0000011f71fb04cb| ++----------------+ +``` + +```SQL +SELECT DISTINCT from_big_endian_64(FROM_HEX('0000011f71fb04cb')) FROM table1; +``` + +```Bash ++-------------+ +| _col0| ++-------------+ +|1234567890123| ++-------------+ +``` + +2. 小端序编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_32(12345)) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|39300000| ++--------+ +``` + +```SQL +SELECT DISTINCT from_little_endian_32(FROM_HEX('39300000')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|12345| ++-----+ +``` + +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_64(1234567890123)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|cb04fb711f010000| ++----------------+ +``` + +```SQL +SELECT DISTINCT from_little_endian_64(FROM_HEX('cb04fb711f010000')) FROM table1; +``` + +```Bash ++-------------+ +| _col0| ++-------------+ +|1234567890123| ++-------------+ +``` + +### 7.5 浮点型编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------ | ------------------------------------------------------------------- | -------------- | -------------- | +| `to_ieee754_32(input)` | 将FLOAT单精度浮点数转换为4字节大端序IEEE754标准BLOB | FLOAT | BLOB | +| `to_ieee754_64(input)` | 将DOUBLE双精度浮点数转换为8字节大端序IEEE754标准BLOB | DOUBLE | BLOB | +| `from_ieee754_32(input)` | 将4字节IEEE754标准BLOB解码为FLOAT浮点数，为to\_ieee754\_32逆操作 | BLOB | FLOAT | +| `from_ieee754_64(input)` | 将8字节IEEE754标准BLOB解码为DOUBLE浮点数，为to\_ieee754\_64逆操作 | BLOB | DOUBLE | + +**使用示例** + +1. 单精度浮点数（FLOAT）编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_ieee754_32(temperature)) FROM table1 where time = 2024-11-26 13:37:00; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|42b40000| ++--------+ +``` + +```SQL +SELECT DISTINCT from_ieee754_32(FROM_HEX('42b40000')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +| 90.0| ++-----+ +``` + +2. 双精度浮点数（DOUBLE）编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_ieee754_64(3.1415926535)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|400921fb54411744| ++----------------+ +``` + +```Bash +SELECT DISTINCT from_ieee754_64(FROM_HEX('400921fb54411744')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|3.1415926535| ++------------+ +``` + +### 7.6 哈希函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| -------------------------------- | ---------------------------------------------------------------- | -------------------- | -------------- | +| `sha256(input)` | 计算输入数据的SHA-256密码学哈希值，不可逆、抗碰撞 | STRING、TEXT、BLOB | BLOB(32字节) | +| `SHA512(input)` | 计算输入数据的SHA-512密码学哈希值，安全强度高于SHA256 | STRING、TEXT、BLOB | BLOB(64字节) | +| `SHA1(input)` | 计算输入数据的SHA-1哈希值，抗碰撞性弱，不推荐安全场景使用 | STRING、TEXT、BLOB | BLOB(20字节) | +| `MD5(input)` | 计算输入数据的MD5哈希值，无密码学安全性，仅用于非加密校验 | STRING、TEXT、BLOB | BLOB(16字节) | +| `CRC32(input)` | 计算输入数据的CRC32循环冗余校验码，高效检测非恶意数据错误 | STRING、TEXT、BLOB | INT64 | +| `spooky_hash_v2_32(input)` | 计算输入数据的32位SpookyHashV2非密码学哈希值，高性能、低冲突 | STRING、TEXT、BLOB | BLOB(4字节) | +| `spooky_hash_v2_64(input)` | 计算输入数据的64位SpookyHashV2非密码学哈希值，高性能、低冲突 | STRING、TEXT、BLOB | BLOB(8字节) | +| `xxhash64(input)` | 计算输入数据的64位xxHash非密码学哈希值，计算速度极快 | STRING、TEXT、BLOB | BLOB(8字节) | +| `murmur3(input)` | 计算输入数据的128位MurmurHash3非密码学哈希值，分布均匀、应用广 | STRING、TEXT、BLOB | BLOB(16字节) | + +**使用示例** + +1. 密码学哈希函数 + +```SQL +SELECT DISTINCT TO_HEX(sha256('test')) FROM table1; +``` + +```Bash ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08| ++----------------------------------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(SHA512('test')) FROM table1; +``` + +```Bash ++--------------------------------------------------------------------------------------------------------------------------------+ +| _col0| ++--------------------------------------------------------------------------------------------------------------------------------+ +|ee26b0dd4af7e749aa1a8ee3c10ae9923f618980772e473f8819a5d4940e0db27ac185f8a0e1d5f84f88bc887fd67b143732c304cc5fa9ad8e6f57f50028a8ff| ++--------------------------------------------------------------------------------------------------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(SHA1('test')) FROM table1; +``` + +```Bash ++----------------------------------------+ +| _col0| ++----------------------------------------+ +|a94a8fe5ccb19ba61c4c0873d391e987982fbbd3| ++----------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(MD5('test')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|098f6bcd4621d373cade4e832627b4f6| ++--------------------------------+ +``` + +2. 校验/非密码学哈希函数 + +```SQL +SELECT DISTINCT CRC32('test') FROM table1; +``` + +```Bash ++----------+ +| _col0| ++----------+ +|3632233996| ++----------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(spooky_hash_v2_32('test')) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|ec0d8b75| ++--------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(spooky_hash_v2_64('test')) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|7b01e8bcec0d8b75| ++----------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(xxhash64('test')) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|4fdcca5ddb678139| ++----------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(murmur3('test')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|9de1bd74cc287dac824dbdf93182129a| ++--------------------------------+ +``` + +### 7.7 HMAC函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------ | ------------------------------------------------------------------- | -------------------------------------------- | -------------- | +| `hmac_md5(data, key)` | 结合MD5与密钥计算HMAC消息认证码，验证数据完整性和来源，适配旧系统 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(16字节) | +| `hmac_sha1(data, key)` | 结合SHA-1与密钥计算HMAC消息认证码，验证数据完整性和来源 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(20字节) | +| `hmac_sha256(data, key)` | 结合SHA256与密钥计算HMAC消息认证码，业界推荐标准，安全强度高 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(32字节) | +| `hmac_sha512(data, key)` | 结合SHA512与密钥计算HMAC消息认证码，商用级别最高安全强度 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(64字节) | + +**使用示例** + +* 通用密钥：'iotdb\_secret\_key' +* 待验证数据：'user\_data\_123' + +1. hmac\_md5 + +```SQL +SELECT DISTINCT TO_HEX(hmac_md5('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|8ee863080ceb3b43b5ffdc7a937e7f28| ++--------------------------------+ +``` + +2. hmac\_sha1 + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha1('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++----------------------------------------+ +| _col0| ++----------------------------------------+ +|b5b7ae1a495745299ec3bd236c511c13540481ce| ++----------------------------------------+ +``` + +3. hmac\_sha256（推荐使用） + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha256('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|73b6f26bbcb5192dbe2cb83745b0fc48c63418fa674b0bf62fabe7f8747f3afd| ++----------------------------------------------------------------+ +``` + +4. hmac\_sha512 + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha512('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++--------------------------------------------------------------------------------------------------------------------------------+ +| _col0| ++--------------------------------------------------------------------------------------------------------------------------------+ +|2fed4ec5a0535e3349798b371d6525255ee85d9eae0ddcbdecf89db84f943151f5febf0ffd9c01ae9661278504aba186cf6f732ae5f42d63be58aadee2baccc2| ++--------------------------------------------------------------------------------------------------------------------------------+ +``` + + + +## 8. 条件表达式 + +### 8.1 CASE 表达式 CASE 表达式有两种形式：简单形式、搜索形式 -#### 7.1.1 简单形式 +#### 8.1.1 简单形式 简单形式从左到右搜索每个值表达式，直到找到一个与表达式相等的值： @@ -1234,7 +1817,7 @@ SELECT a, END ``` -#### 7.1.2 搜索形式 +#### 8.1.2 搜索形式 搜索形式从左到右评估每个布尔条件，直到找到一个为真的条件，并返回相应的结果： @@ -1257,7 +1840,7 @@ SELECT a, b, END ``` -### 7.2 COALESCE 函数 +### 8.2 COALESCE 函数 返回参数列表中的第一个非空值。 @@ -1265,11 +1848,11 @@ SELECT a, b, coalesce(value1, value2[, ...]) ``` -## 8. 转换函数 +## 9. 转换函数 -### 8.1 转换函数 +### 9.1 转换函数 -#### 8.1.1 cast(value AS type) → type +#### 9.1.1 cast(value AS type) → type 1. 显式地将一个值转换为指定类型。 2. 可以用于将字符串（varchar）转换为数值类型，或数值转换为字符串类型 @@ -1284,7 +1867,7 @@ SELECT * IN (CAST('2024-11-27' AS DATE), CAST('2024-11-28' AS DATE)); ``` -#### 8.1.2 try_cast(value AS type) → type +#### 9.1.2 try_cast(value AS type) → type 1. 与 `cast()` 类似。 2. 如果转换失败，则返回 `null`。 @@ -1298,10 +1881,10 @@ SELECT * IN (try_cast('2024-11-27' AS DATE), try_cast('2024-11-28' AS DATE)); ``` -### 8.2 Format 函数 +### 9.2 Format 函数 该函数基于指定的格式字符串与输入参数，生成并返回格式化后的字符串输出。其功能与 Java 语言中的`String.format` 方法及 C 语言中的`printf`函数相类似，支持开发者通过占位符语法构建动态字符串模板，其中预设的格式标识符将被传入的对应参数值精准替换，最终形成符合特定格式要求的完整字符串。 -#### 8.2.1 语法介绍 +#### 9.2.1 语法介绍 ```SQL format(pattern,...args) -> String @@ -1311,15 +1894,15 @@ format(pattern,...args) -> String * `pattern`: 格式字符串，可包含静态文本及一个或多个格式说明符（如 `%s`, `%d` 等），或任意返回类型为 `STRING/TEXT` 的表达式。 * `args`: 用于替换格式说明符的输入参数。需满足以下条件： - * 参数数量 ≥ 1 - * 若存在多个参数，以逗号`,`分隔（如 `arg1,arg2`） - * 参数总数可多于 `pattern` 中的占位符数量，但不可少于，否则触发异常 + * 参数数量 ≥ 1 + * 若存在多个参数，以逗号`,`分隔（如 `arg1,arg2`） + * 参数总数可多于 `pattern` 中的占位符数量，但不可少于，否则触发异常 **返回值** * 类型为 `STRING` 的格式化结果字符串 -#### 8.2.2 使用示例 +#### 9.2.2 使用示例 1. 格式化浮点数 @@ -1435,13 +2018,13 @@ IoTDB:database1> SELECT format('%s%%', 99.9) from table1 limit 1 +-----+ ``` -#### 8.2.3 **格式转换失败场景说明** +#### 9.2.3 **格式转换失败场景说明** 1. 类型不匹配错误 * 时间戳类型冲突 若格式说明符中包含时间相关标记（如 `%Y-%m-%d`），但参数提供： - * 非 `DATE`/`TIMESTAMP` 类型值 - * 或涉及日期细粒度单位（如 `%H` 小时、`%M` 分钟）时，参数仅支持 `TIMESTAMP` 类型，否则将抛出类型异常 + * 非 `DATE`/`TIMESTAMP` 类型值 + * 或涉及日期细粒度单位（如 `%H` 小时、`%M` 分钟）时，参数仅支持 `TIMESTAMP` 类型，否则将抛出类型异常 ```SQL -- 示例1 @@ -1473,8 +2056,8 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid format string: %.5f % 3. 无效调用错误 * 当函数参数满足以下任一条件时，视为非法调用： - * 参数总数 小于 2（必须包含格式字符串及至少一个参数） - * 格式字符串（`pattern`）类型非 `STRING/TEXT` + * 参数总数 小于 2（必须包含格式字符串及至少一个参数） + * 格式字符串（`pattern`）类型非 `STRING/TEXT` ```SQL -- 示例1 @@ -1488,19 +2071,19 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h -## 9. 字符串函数和操作符 +## 10. 字符串函数和操作符 -### 9.1 字符串操作符 +### 10.1 字符串操作符 -#### 9.1.1 || 操作符 +#### 10.1.1 || 操作符 `||` 操作符用于字符串连接，功能与 `concat` 函数相同。 -#### 9.1.2 LIKE 语句 +#### 10.1.2 LIKE 语句 `LIKE` 语句用于模式匹配，具体用法在[模式匹配：LIKE](#1-like-运算符) 中有详细文档。 -### 9.2 字符串函数 +### 10.2 字符串函数 | 函数名 | 描述 | 输入 | 输出 | 用法 | | ----------- |---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------ | ------------------------------------------------------------ | @@ -1518,33 +2101,33 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h | substring | 从指定位置提取字符到字符串末尾。需要注意的是，起始位置是基于字符而不是字节数组确定的。`start_index` 从 1 开始计数，长度从 `start_index` 位置计算。 | 支持两个参数**string**：要提取子字符串的源字符串，可以是字符串或文本类型。**start_index**：从哪个索引开始提取子字符串，索引从 1 开始计数。 | String：返回一个字符串，从 `start_index` 位置开始到字符串末尾的所有字符。**注意事项**：`start_index` 从 1 开始，即数组的第 0 个位置是 1参数为 null时，返回 `null`start_index 大于字符串长度时，结果报错。 | substring(string from start_index)或 substring(string, start_index) | | substring | 从一个字符串中提取从指定位置开始、指定长度的子字符串注意：起始位置和长度是基于字符而不是字节数组确定的。`start_index` 从 1 开始计数，长度从 `start_index` 位置计算。 | 支持三个参数**string**：要提取子字符串的源字符串，可以是字符串或文本类型。**start_index**：从哪个索引开始提取子字符串，索引从 1 开始计数。**length**：要提取的子字符串的长度。 | String：返回一个字符串，从 `start_index` 位置开始，提取 `length` 个字符。**注意事项**：参数为 null时，返回 `null`如果 `start_index` 大于字符串的长度，结果报错。如果 `length` 小于 0，结果报错。极端情况，`start_index + length` 超过 `int.MAX` 并变成负数，将导致异常结果。 | substring(string from start_index for length) 或 substring(string, start_index, length) | -## 10. 模式匹配函数 +## 11. 模式匹配函数 -### 10.1 LIKE 运算符 +### 11.1 LIKE 运算符 -#### 10.1.1 用途 +#### 11.1.1 用途 `LIKE` 运算符用于将值与模式进行比较。它通常用于 `WHERE` 子句中，用于匹配字符串中的特定模式。 -#### 10.1.2 语法 +#### 11.1.2 语法 ```SQL ... column [NOT] LIKE 'pattern' ESCAPE 'character'; ``` -#### 10.1.3 匹配规则 +#### 11.1.3 匹配规则 - 匹配字符是区分大小写的。 - 模式支持两个匹配符号： - - `_`：匹配任意单个字符。 - - `%`：匹配0个或多个字符。 + - `_`：匹配任意单个字符。 + - `%`：匹配0个或多个字符。 -#### 10.1.4 注意事项 +#### 11.1.4 注意事项 - `LIKE` 模式匹配总是覆盖整个字符串。如果需要匹配字符串中的任意位置，模式必须以 `%` 开头和结尾。 - 如果需要匹配 `%` 或 `_` 作为普通字符，必须使用转义字符。 -#### 10.1.5 示例 +#### 11.1.5 示例 示例 1：匹配以特定字符开头的字符串 @@ -1586,42 +2169,42 @@ SELECT * FROM table1 WHERE continent LIKE 'South\_%' ESCAPE '\'; SELECT * FROM table1 WHERE continent LIKE 'South\\%' ESCAPE '\'; ``` -### 10.2 regexp_like 函数 +### 11.2 regexp_like 函数 -#### 10.2.1 用途 +#### 11.2.1 用途 `regexp_like` 函数用于评估正则表达式模式，并确定该模式是否包含在字符串中。 -#### 10.2.2 语法 +#### 11.2.2 语法 ```SQL regexp_like(string, pattern); ``` -#### 10.2.3 注意事项 +#### 11.2.3 注意事项 - `regexp_like` 的模式只需包含在字符串中，而不需要匹配整个字符串。 - 如果需要匹配整个字符串，可以使用正则表达式的锚点 `^` 和 `$`。 - `^` 表示“字符串的开头”，`$` 表示“字符串的结尾”。 - 正则表达式采用 Java 定义的正则语法，但存在以下需要注意的例外情况： - - **多行模式** - 1. 启用方式：`(?m)`。 - 2. 只识别`\n`作为行终止符。 - 3. 不支持`(?d)`标志，且禁止使用。 - - **不区分大小写匹配** - 1. 启用方式：`(?i)`。 - 2. 基于Unicode规则，不支持上下文相关和本地化匹配。 - 3. 不支持`(?u)`标志，且禁止使用。 - - **字符类** - 1. 在字符类（如`[A-Z123]`）中，`\Q`和`\E`不被支持，被视为普通字面量。 - - **Unicode字符类（**`\p{prop}`**）** - 1. **名称下划线**：名称中的所有下划线必须删除（如`OldItalic`而非`Old_Italic`）。 - 2. **文字（Scripts）**：直接指定，无需`Is`、`script=`或`sc=`前缀（如`\p{Hiragana}`）。 - 3. **区块（Blocks）**：必须使用`In`前缀，不支持`block=`或`blk=`前缀（如`\p{InMongolian}`）。 - 4. **类别（Categories）**：直接指定，无需`Is`、`general_category=`或`gc=`前缀（如`\p{L}`）。 - 5. **二元属性（Binary Properties）**：直接指定，无需`Is`（如`\p{NoncharacterCodePoint}`）。 - -#### 10.2.4 示例 + - **多行模式** + 1. 启用方式：`(?m)`。 + 2. 只识别`\n`作为行终止符。 + 3. 不支持`(?d)`标志，且禁止使用。 + - **不区分大小写匹配** + 1. 启用方式：`(?i)`。 + 2. 基于Unicode规则，不支持上下文相关和本地化匹配。 + 3. 不支持`(?u)`标志，且禁止使用。 + - **字符类** + 1. 在字符类（如`[A-Z123]`）中，`\Q`和`\E`不被支持，被视为普通字面量。 + - **Unicode字符类（**`\p{prop}`**）** + 1. **名称下划线**：名称中的所有下划线必须删除（如`OldItalic`而非`Old_Italic`）。 + 2. **文字（Scripts）**：直接指定，无需`Is`、`script=`或`sc=`前缀（如`\p{Hiragana}`）。 + 3. **区块（Blocks）**：必须使用`In`前缀，不支持`block=`或`blk=`前缀（如`\p{InMongolian}`）。 + 4. **类别（Categories）**：直接指定，无需`Is`、`general_category=`或`gc=`前缀（如`\p{L}`）。 + 5. **二元属性（Binary Properties）**：直接指定，无需`Is`（如`\p{NoncharacterCodePoint}`）。 + +#### 11.2.4 示例 示例 1：匹配包含特定模式的字符串 @@ -1630,9 +2213,9 @@ SELECT regexp_like('1a 2b 14m', '\\d+b'); -- true ``` - **说明**：检查字符串 `'1a 2b 14m'` 是否包含模式 `\d+b`。 - - `\d+` 表示“一个或多个数字”。 - - `b` 表示字母 `b`。 - - 在 `'1a 2b 14m'` 中，`2b` 符合这个模式，所以返回 `true`。 + - `\d+` 表示“一个或多个数字”。 + - `b` 表示字母 `b`。 + - 在 `'1a 2b 14m'` 中，`2b` 符合这个模式，所以返回 `true`。 示例 2：匹配整个字符串 @@ -1641,11 +2224,11 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false ``` - **说明**：检查字符串 `'1a 2b 14m'` 是否完全匹配模式 `^\\d+b$`。 - - `\d+` 表示“一个或多个数字”。 - - `b` 表示字母 `b`。 - - `'1a 2b 14m'` 并不符合这个模式，因为它不是从数字开始，也不是以 `b` 结束，所以返回 `false`。 + - `\d+` 表示“一个或多个数字”。 + - `b` 表示字母 `b`。 + - `'1a 2b 14m'` 并不符合这个模式，因为它不是从数字开始，也不是以 `b` 结束，所以返回 `false`。 -## 11. 时序分窗函数 +## 12. 时序分窗函数 原始示例数据如下： @@ -1668,19 +2251,19 @@ CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); ``` -### 11.1 HOP +### 12.1 HOP -#### 11.1.1 功能描述 +#### 12.1.1 功能描述 HOP 函数用于按时间分段分窗分析，识别每一行数据所属的时间窗口。该函数通过指定固定窗口大小（size）和窗口滑动步长（SLIDE），将数据按时间戳分配到所有与其时间戳重叠的窗口中。若窗口之间存在重叠（步长 < 窗口大小），数据会自动复制到多个窗口。 -#### 11.1.2 函数定义 +#### 12.1.2 函数定义 ```SQL HOP(data, timecol, size, slide[, origin]) ``` -#### 11.1.3 参数说明 +#### 12.1.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------- | @@ -1690,7 +2273,7 @@ HOP(data, timecol, size, slide[, origin]) | SLIDE | 标量参数 | 长整数类型 | 窗口滑动步长 | | ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | -#### 11.1.4 返回结果 +#### 12.1.4 返回结果 HOP 函数的返回结果列包含： @@ -1698,7 +2281,7 @@ HOP 函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.1.5 使用示例 +#### 12.1.5 使用示例 ```SQL IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); @@ -1733,18 +2316,18 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DAT +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.2 SESSION +### 12.2 SESSION -#### 11.2.1 功能描述 +#### 12.2.1 功能描述 SESSION 函数用于按会话间隔对数据进行分窗。系统逐行检查与前一行的时间间隔，小于阈值（GAP）则归入当前窗口，超过则归入下一个窗口。 -#### 11.2.2 函数定义 +#### 12.2.2 函数定义 ```SQL SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) ``` -#### 11.2.3 参数说明 +#### 12.2.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | -------------------------- | ---------------------------------------- | @@ -1753,7 +2336,7 @@ SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) | | GAP | 标量参数 | 长整数类型 | 会话间隔阈值 | -#### 11.2.4 返回结果 +#### 12.2.4 返回结果 SESSION 函数的返回结果列包含： @@ -1761,7 +2344,7 @@ SESSION 函数的返回结果列包含： * window\_end: 会话窗口内的最后一条数据的时间 * 映射列：DATA 参数的所有输入列 -#### 11.2.5 使用示例 +#### 12.2.5 使用示例 ```SQL IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); @@ -1787,19 +2370,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.3 VARIATION +### 12.3 VARIATION -#### 11.3.1 功能描述 +#### 12.3.1 功能描述 VARIATION 函数用于按数据差值分窗，将第一条数据作为首个窗口的基准值，每个数据点会与基准值进行差值运算，如果差值小于给定的阈值（delta）则加入当前窗口；如果超过阈值，则分为下一个窗口，将该值作为下一个窗口的基准值。 -#### 11.3.2 函数定义 +#### 12.3.2 函数定义 ```sql VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) ``` -#### 11.3.3 参数说明 +#### 12.3.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | -------- | ---------- | -------------------------- | ---------------------------------------- | @@ -1807,14 +2390,14 @@ VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) | COL | 标量参数 | 字符串类型 | 标识对哪一列计算差值 | | DELTA | 标量参数 | 浮点数类型 | 差值阈值 | -#### 11.3.4 返回结果 +#### 12.3.4 返回结果 VARIATION 函数的返回结果列包含： * window\_index: 窗口编号 * 映射列：DATA 参数的所有输入列 -#### 11.3.5 使用示例 +#### 12.3.5 使用示例 ```sql IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); @@ -1841,33 +2424,33 @@ IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, a +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.4 CAPACITY +### 12.4 CAPACITY -#### 11.4.1 功能描述 +#### 12.4.1 功能描述 CAPACITY 函数用于按数据点数（行数）分窗，每个窗口最多有 SIZE 行数据。 -#### 11.4.2 函数定义 +#### 12.4.2 函数定义 ```sql CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) ``` -#### 11.4.3 参数说明 +#### 12.4.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | -------- | ---------- | -------------------------- | ---------------------------------------- | | DATA | 表参数 | SET SEMANTICPASS THROUGH | 输入表通过 pkeys、okeys 指定分区和排序 | | SIZE | 标量参数 | 长整数类型 | 窗口大小 | -#### 11.4.4 返回结果 +#### 12.4.4 返回结果 CAPACITY 函数的返回结果列包含： * window\_index: 窗口编号 * 映射列：DATA 参数的所有输入列 -#### 11.4.5 使用示例 +#### 12.4.5 使用示例 ```sql IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); @@ -1894,18 +2477,18 @@ IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(p +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.5 TUMBLE +### 12.5 TUMBLE -#### 11.5.1 功能描述 +#### 12.5.1 功能描述 TUMBLE 函数用于通过时间属性字段为每行数据分配一个窗口，滚动窗口的大小固定且不重复。 -#### 11.5.2 函数定义 +#### 12.5.2 函数定义 ```sql TUMBLE(data, timecol, size[, origin]) ``` -#### 11.5.3 参数说明 +#### 12.5.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------- | @@ -1914,7 +2497,7 @@ TUMBLE(data, timecol, size[, origin]) | SIZE | 标量参数 | 长整数类型 | 窗口大小，需为正数 | | ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | -#### 11.5.4 返回结果 +#### 12.5.4 返回结果 TUBMLE 函数的返回结果列包含： @@ -1922,7 +2505,7 @@ TUBMLE 函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.5.5 使用示例 +#### 12.5.5 使用示例 ```SQL IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); @@ -1948,19 +2531,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE( +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.6 CUMULATE +### 12.6 CUMULATE -#### 11.6.1 功能描述 +#### 12.6.1 功能描述 Cumulate 函数用于从初始的窗口开始，创建相同窗口开始但窗口结束步长不同的窗口，直到达到最大的窗口大小。每个窗口包含其区间内的元素。例如：1小时步长，24小时大小的累计窗口，每天可以获得如下这些窗口：`[00:00, 01:00)`，`[00:00, 02:00)`，`[00:00, 03:00)`， …， `[00:00, 24:00)` -#### 11.6.2 函数定义 +#### 12.6.2 函数定义 ```sql CUMULATE(data, timecol, size, step[, origin]) ``` -#### 11.6.3 参数说明 +#### 12.6.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------------------------------- | @@ -1972,7 +2555,7 @@ CUMULATE(data, timecol, size, step[, origin]) > 注意：size 如果不是 step 的整数倍，则会报错`Cumulative table function requires size must be an integral multiple of step` -#### 11.6.4 返回结果 +#### 12.6.4 返回结果 CUMULATE函数的返回结果列包含： @@ -1980,7 +2563,7 @@ CUMULATE函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.6.5 使用示例 +#### 12.6.5 使用示例 ```sql IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m); diff --git a/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_timecho.md b/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_timecho.md index 210eb2613..f8a48b9e1 100644 --- a/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_timecho.md +++ b/src/zh/UserGuide/latest-Table/SQL-Manual/Basis-Function_timecho.md @@ -1205,13 +1205,596 @@ IoTDB:database1> select length, width, bitwise_right_shift_arithmetic(length,wid +------+-----+-----+ ``` -## 7. 条件表达式 +## 7. 二进制函数 -### 7.1 CASE 表达式 +> V2.0.9.1 起支持 + +### 7.1 Base64 编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ----------------------------- | ------------------------------------------------------------------------- | ------------------ | -------------- | +| `to_base64(input)` | 将输入数据编码为标准 Base64 字符串，解决二进制数据传输 / 存储兼容性问题 | STRING/TEXT/BLOB | STRING | +| `from_base64(input)` | 将标准 Base64 字符串解码为原始二进制数据，为 to\_base64 逆操作 | STRING/TEXT | BLOB | +| `to_base64url(input)` | 将输入数据编码为 URL 安全的 Base64URL 字符串，替换 +/\_、省略填充符 | STRING/TEXT/BLOB | STRING | +| `from_base64url(input)` | 将 Base64URL 字符串解码为原始二进制数据，为 to\_base64url 逆操作 | STRING/TEXT | BLOB | +| `to_base32(input)` | 将输入数据编码为 Base32 字符串，字符无混淆、不区分大小写，可读性高 | STRING/TEXT/BLOB | STRING | +| `from_base32(input)` | 将 Base32 字符串解码为原始二进制数据，为 to\_base32 逆操作 | STRING/TEXT | BLOB | + +**使用示例** + +1. to\_base64：编码字符串为标准Base64 + +```SQL +SELECT DISTINCT to_base64('IoTDB二进制测试') FROM table1; +``` + +```Bash ++----------------------------+ +| _col0| ++----------------------------+ +|SW9URELkuozov5vliLbmtYvor5U=| ++----------------------------+ +``` + +2. from\_base64：解码Base64字符串为二进制 + +```SQL +SELECT DISTINCT from_base64('SW9URELkuozov5vliLbmtYvor5U=') FROM table1; +``` + +```Bash ++------------------------------------------+ +| _col0| ++------------------------------------------+ +|0x496f544442e4ba8ce8bf9be588b6e6b58be8af95| ++------------------------------------------+ +``` + +3. to\_base64url：编码为URL安全的Base64URL（无+/\_、无填充符=） + +```SQL +SELECT DISTINCT to_base64url('https://iotdb.apache.org') FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn| ++--------------------------------+ +``` + +4. from\_base64url：解码Base64URL字符串 + +```SQL +SELECT DISTINCT from_base64url('aHR0cHM6Ly9pb3RkYi5hcGFjaGUub3Jn') FROM table1; +``` + +```Bash ++--------------------------------------------------+ +| _col0| ++--------------------------------------------------+ +|0x68747470733a2f2f696f7464622e6170616368652e6f7267| ++--------------------------------------------------+ +``` + +5. to\_base32：编码为Base32字符串 + +```SQL +SELECT DISTINCT to_base32('123456') FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|GEZDGNBVGY======| ++----------------+ +``` + +6. from\_base32：解码Base32字符串 + +```SQL +SELECT DISTINCT from_base32('GEZDGNBVGY======') FROM table1; +``` + +```SQL ++--------------+ +| _col0| ++--------------+ +|0x313233343536| ++--------------+ +``` + +### 7.2 十六进制编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ----------------------- | -------------------------------------------------------------- | ------------------ | -------------- | +| `TO_HEX(input)` | 将输入数据转换为十六进制字符串，直接反映底层字节值，便于调试 | STRING/TEXT/BLOB | STRING | +| `FROM_HEX(input)` | 将十六进制字符串解码为原始二进制数据，为TO\_HEX逆操作 | STRING/TEXT | BLOB | + +**使用示例** + +1. TO\_HEX：将字符串/二进制转换为十六进制 + +```SQL +SELECT DISTINCT TO_HEX('test') FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|74657374| ++--------+ +``` + +2. FROM\_HEX：将十六进制字符串解码为二进制 + +```SQL +SELECT DISTINCT FROM_HEX('74657374') FROM table1; +``` + +```Bash ++----------+ +| _col0| ++----------+ +|0x74657374| ++----------+ +``` + +### 7.3 二进制基础函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| -------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------- | ---------------- | +| `length(input)` | 返回输入数据长度，文本类型返字符数，BLOB类型返回字节数，OBJECT 类型返回对象二进制字节大小 | STRING/TEXT/BLOB/OBJECT | INT32 | +| `REVERSE(input)`| 反转输入数据顺序，文本类型反转字符，BLOB类型反转字节 | STRING/TEXT/BLOB | 与输入类型一致 | +| `LPAD(input, length, pad_bytes)` | 对BLOB进行字节级左填充/截断，使最终字节长度等于指定值 | BLOB、INT32/INT64、BLOB | BLOB | +| `RPAD(input, length, pad_bytes)` | 对BLOB进行字节级右填充/截断，使最终字节长度等于指定值 | BLOB、INT32/INT64、BLOB | BLOB | + +**使用示例** + +1. length：获取数据长度 + +```SQL +SELECT DISTINCT length('IoTDB') FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +| 5| ++-----+ +``` + +2. REVERSE：反转数据 + +```SQL +SELECT DISTINCT REVERSE('12345') FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|54321| ++-----+ +``` + +3. LPAD：左填充/截断BLOB（参数：原BLOB、目标长度、填充字节） + +```SQL +SELECT DISTINCT LPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|0x7474657374| ++------------+ +``` + +4. RPAD：右填充/截断BLOB + +```SQL +SELECT DISTINCT RPAD(FROM_HEX('74657374'),5, FROM_HEX('74657374')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|0x7465737474| ++------------+ +``` + +### 7.4 整数编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------------ | ------------------------------------------------------------------ | -------------- | -------------- | +| `to_big_endian_32(input)` | 将INT32整数转换为4字节大端序BLOB，符合网络字节序标准 | INT32 | BLOB | +| `to_big_endian_64(input)` | 将INT64整数转换为8字节大端序BLOB，符合网络字节序标准 | INT64 | BLOB | +| `from_big_endian_32(input)` | 将4字节大端序BLOB解码为INT32整数，为to\_big\_endian\_32逆操作 | BLOB | INT32 | +| `from_big_endian_64(input)` | 将8字节大端序BLOB解码为INT64整数，为to\_big\_endian\_64逆操作 | BLOB | INT64 | +| `to_little_endian_32(input)` | 将INT32整数转换为4字节小端序BLOB，适配x86等主流架构 | INT32 | BLOB | +| `to_little_endian_64(input)` | 将INT64整数转换为8字节小端序BLOB，适配x86等主流架构 | INT64 | BLOB | +| `from_little_endian_32(input)` | 将4字节小端序BLOB解码为INT32整数，为to\_little\_endian\_32逆操作 | BLOB | INT32 | +| `from_little_endian_64(input)` | 将8字节小端序BLOB解码为INT64整数，为to\_little\_endian\_64逆操作 | BLOB | INT64 | + +**使用示例** + +1. 大端序编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_32(12345)) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|00003039| ++--------+ +``` + +```SQL +SELECT DISTINCT from_big_endian_32(FROM_HEX('00003039')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|12345| ++-----+ +``` + +```SQL +SELECT DISTINCT TO_HEX(to_big_endian_64(1234567890123)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|0000011f71fb04cb| ++----------------+ +``` + +```SQL +SELECT DISTINCT from_big_endian_64(FROM_HEX('0000011f71fb04cb')) FROM table1; +``` + +```Bash ++-------------+ +| _col0| ++-------------+ +|1234567890123| ++-------------+ +``` + +2. 小端序编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_32(12345)) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|39300000| ++--------+ +``` + +```SQL +SELECT DISTINCT from_little_endian_32(FROM_HEX('39300000')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +|12345| ++-----+ +``` + +```SQL +SELECT DISTINCT TO_HEX(to_little_endian_64(1234567890123)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|cb04fb711f010000| ++----------------+ +``` + +```SQL +SELECT DISTINCT from_little_endian_64(FROM_HEX('cb04fb711f010000')) FROM table1; +``` + +```Bash ++-------------+ +| _col0| ++-------------+ +|1234567890123| ++-------------+ +``` + +### 7.5 浮点型编码函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------ | ------------------------------------------------------------------- | -------------- | -------------- | +| `to_ieee754_32(input)` | 将FLOAT单精度浮点数转换为4字节大端序IEEE754标准BLOB | FLOAT | BLOB | +| `to_ieee754_64(input)` | 将DOUBLE双精度浮点数转换为8字节大端序IEEE754标准BLOB | DOUBLE | BLOB | +| `from_ieee754_32(input)` | 将4字节IEEE754标准BLOB解码为FLOAT浮点数，为to\_ieee754\_32逆操作 | BLOB | FLOAT | +| `from_ieee754_64(input)` | 将8字节IEEE754标准BLOB解码为DOUBLE浮点数，为to\_ieee754\_64逆操作 | BLOB | DOUBLE | + +**使用示例** + +1. 单精度浮点数（FLOAT）编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_ieee754_32(temperature)) FROM table1 where time = 2024-11-26 13:37:00; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|42b40000| ++--------+ +``` + +```SQL +SELECT DISTINCT from_ieee754_32(FROM_HEX('42b40000')) FROM table1; +``` + +```Bash ++-----+ +|_col0| ++-----+ +| 90.0| ++-----+ +``` + +2. 双精度浮点数（DOUBLE）编码/解码 + +```SQL +SELECT DISTINCT TO_HEX(to_ieee754_64(3.1415926535)) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|400921fb54411744| ++----------------+ +``` + +```Bash +SELECT DISTINCT from_ieee754_64(FROM_HEX('400921fb54411744')) FROM table1; +``` + +```Bash ++------------+ +| _col0| ++------------+ +|3.1415926535| ++------------+ +``` + +### 7.6 哈希函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| -------------------------------- | ---------------------------------------------------------------- | -------------------- | -------------- | +| `sha256(input)` | 计算输入数据的SHA-256密码学哈希值，不可逆、抗碰撞 | STRING、TEXT、BLOB | BLOB(32字节) | +| `SHA512(input)` | 计算输入数据的SHA-512密码学哈希值，安全强度高于SHA256 | STRING、TEXT、BLOB | BLOB(64字节) | +| `SHA1(input)` | 计算输入数据的SHA-1哈希值，抗碰撞性弱，不推荐安全场景使用 | STRING、TEXT、BLOB | BLOB(20字节) | +| `MD5(input)` | 计算输入数据的MD5哈希值，无密码学安全性，仅用于非加密校验 | STRING、TEXT、BLOB | BLOB(16字节) | +| `CRC32(input)` | 计算输入数据的CRC32循环冗余校验码，高效检测非恶意数据错误 | STRING、TEXT、BLOB | INT64 | +| `spooky_hash_v2_32(input)` | 计算输入数据的32位SpookyHashV2非密码学哈希值，高性能、低冲突 | STRING、TEXT、BLOB | BLOB(4字节) | +| `spooky_hash_v2_64(input)` | 计算输入数据的64位SpookyHashV2非密码学哈希值，高性能、低冲突 | STRING、TEXT、BLOB | BLOB(8字节) | +| `xxhash64(input)` | 计算输入数据的64位xxHash非密码学哈希值，计算速度极快 | STRING、TEXT、BLOB | BLOB(8字节) | +| `murmur3(input)` | 计算输入数据的128位MurmurHash3非密码学哈希值，分布均匀、应用广 | STRING、TEXT、BLOB | BLOB(16字节) | + +**使用示例** + +1. 密码学哈希函数 + +```SQL +SELECT DISTINCT TO_HEX(sha256('test')) FROM table1; +``` + +```Bash ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08| ++----------------------------------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(SHA512('test')) FROM table1; +``` + +```Bash ++--------------------------------------------------------------------------------------------------------------------------------+ +| _col0| ++--------------------------------------------------------------------------------------------------------------------------------+ +|ee26b0dd4af7e749aa1a8ee3c10ae9923f618980772e473f8819a5d4940e0db27ac185f8a0e1d5f84f88bc887fd67b143732c304cc5fa9ad8e6f57f50028a8ff| ++--------------------------------------------------------------------------------------------------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(SHA1('test')) FROM table1; +``` + +```Bash ++----------------------------------------+ +| _col0| ++----------------------------------------+ +|a94a8fe5ccb19ba61c4c0873d391e987982fbbd3| ++----------------------------------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(MD5('test')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|098f6bcd4621d373cade4e832627b4f6| ++--------------------------------+ +``` + +2. 校验/非密码学哈希函数 + +```SQL +SELECT DISTINCT CRC32('test') FROM table1; +``` + +```Bash ++----------+ +| _col0| ++----------+ +|3632233996| ++----------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(spooky_hash_v2_32('test')) FROM table1; +``` + +```Bash ++--------+ +| _col0| ++--------+ +|ec0d8b75| ++--------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(spooky_hash_v2_64('test')) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|7b01e8bcec0d8b75| ++----------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(xxhash64('test')) FROM table1; +``` + +```Bash ++----------------+ +| _col0| ++----------------+ +|4fdcca5ddb678139| ++----------------+ +``` + +```SQL +SELECT DISTINCT TO_HEX(murmur3('test')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|9de1bd74cc287dac824dbdf93182129a| ++--------------------------------+ +``` + +### 7.7 HMAC函数 + +| 函数名称 | 功能描述 | 输入参数类型 | 输出参数类型 | +| ------------------------------ | ------------------------------------------------------------------- | -------------------------------------------- | -------------- | +| `hmac_md5(data, key)` | 结合MD5与密钥计算HMAC消息认证码，验证数据完整性和来源，适配旧系统 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(16字节) | +| `hmac_sha1(data, key)` | 结合SHA-1与密钥计算HMAC消息认证码，验证数据完整性和来源 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(20字节) | +| `hmac_sha256(data, key)` | 结合SHA256与密钥计算HMAC消息认证码，业界推荐标准，安全强度高 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(32字节) | +| `hmac_sha512(data, key)` | 结合SHA512与密钥计算HMAC消息认证码，商用级别最高安全强度 | data：STRING/TEXT/BLOBkey：STRING/TEXT | BLOB(64字节) | + +**使用示例** + +* 通用密钥：'iotdb\_secret\_key' +* 待验证数据：'user\_data\_123' + +1. hmac\_md5 + +```SQL +SELECT DISTINCT TO_HEX(hmac_md5('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++--------------------------------+ +| _col0| ++--------------------------------+ +|8ee863080ceb3b43b5ffdc7a937e7f28| ++--------------------------------+ +``` + +2. hmac\_sha1 + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha1('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++----------------------------------------+ +| _col0| ++----------------------------------------+ +|b5b7ae1a495745299ec3bd236c511c13540481ce| ++----------------------------------------+ +``` + +3. hmac\_sha256（推荐使用） + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha256('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++----------------------------------------------------------------+ +| _col0| ++----------------------------------------------------------------+ +|73b6f26bbcb5192dbe2cb83745b0fc48c63418fa674b0bf62fabe7f8747f3afd| ++----------------------------------------------------------------+ +``` + +4. hmac\_sha512 + +```SQL +SELECT DISTINCT TO_HEX(hmac_sha512('user_data_123', 'iotdb_secret_key')) FROM table1; +``` + +```Bash ++--------------------------------------------------------------------------------------------------------------------------------+ +| _col0| ++--------------------------------------------------------------------------------------------------------------------------------+ +|2fed4ec5a0535e3349798b371d6525255ee85d9eae0ddcbdecf89db84f943151f5febf0ffd9c01ae9661278504aba186cf6f732ae5f42d63be58aadee2baccc2| ++--------------------------------------------------------------------------------------------------------------------------------+ +``` + + + +## 8. 条件表达式 + +### 8.1 CASE 表达式 CASE 表达式有两种形式：简单形式、搜索形式 -#### 7.1.1 简单形式 +#### 8.1.1 简单形式 简单形式从左到右搜索每个值表达式，直到找到一个与表达式相等的值： @@ -1234,7 +1817,7 @@ SELECT a, END ``` -#### 7.1.2 搜索形式 +#### 8.1.2 搜索形式 搜索形式从左到右评估每个布尔条件，直到找到一个为真的条件，并返回相应的结果： @@ -1257,7 +1840,7 @@ SELECT a, b, END ``` -### 7.2 COALESCE 函数 +### 8.2 COALESCE 函数 返回参数列表中的第一个非空值。 @@ -1265,11 +1848,11 @@ SELECT a, b, coalesce(value1, value2[, ...]) ``` -## 8. 转换函数 +## 9. 转换函数 -### 8.1 转换函数 +### 9.1 转换函数 -#### 8.1.1 cast(value AS type) → type +#### 9.1.1 cast(value AS type) → type 1. 显式地将一个值转换为指定类型。 2. 可以用于将字符串（varchar）转换为数值类型，或数值转换为字符串类型，V2.0.8 版本起支持 OBJECT 类型强转成 STRING 类型。 @@ -1284,7 +1867,7 @@ SELECT * IN (CAST('2024-11-27' AS DATE), CAST('2024-11-28' AS DATE)); ``` -#### 8.1.2 try_cast(value AS type) → type +#### 9.1.2 try_cast(value AS type) → type 1. 与 `cast()` 类似。 2. 如果转换失败，则返回 `null`。 @@ -1298,10 +1881,10 @@ SELECT * IN (try_cast('2024-11-27' AS DATE), try_cast('2024-11-28' AS DATE)); ``` -### 8.2 Format 函数 +### 9.2 Format 函数 该函数基于指定的格式字符串与输入参数，生成并返回格式化后的字符串输出。其功能与 Java 语言中的`String.format` 方法及 C 语言中的`printf`函数相类似，支持开发者通过占位符语法构建动态字符串模板，其中预设的格式标识符将被传入的对应参数值精准替换，最终形成符合特定格式要求的完整字符串。 -#### 8.2.1 语法介绍 +#### 9.2.1 语法介绍 ```SQL format(pattern,...args) -> String @@ -1319,7 +1902,7 @@ format(pattern,...args) -> String * 类型为 `STRING` 的格式化结果字符串 -#### 8.2.2 使用示例 +#### 9.2.2 使用示例 1. 格式化浮点数 @@ -1435,7 +2018,7 @@ IoTDB:database1> SELECT format('%s%%', 99.9) from table1 limit 1 +-----+ ``` -#### 8.2.3 **格式转换失败场景说明** +#### 9.2.3 **格式转换失败场景说明** 1. 类型不匹配错误 @@ -1488,19 +2071,19 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h -## 9. 字符串函数和操作符 +## 10. 字符串函数和操作符 -### 9.1 字符串操作符 +### 10.1 字符串操作符 -#### 9.1.1 || 操作符 +#### 10.1.1 || 操作符 `||` 操作符用于字符串连接，功能与 `concat` 函数相同。 -#### 9.1.2 LIKE 语句 +#### 10.1.2 LIKE 语句 `LIKE` 语句用于模式匹配，具体用法在[模式匹配：LIKE](#1-like-运算符) 中有详细文档。 -### 9.2 字符串函数 +### 10.2 字符串函数 | 函数名 | 描述 | 输入 | 输出 | 用法 | | ----------- |---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------ | ------------------------------------------------------------ | @@ -1518,33 +2101,33 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Scalar function format must h | substring | 从指定位置提取字符到字符串末尾。需要注意的是，起始位置是基于字符而不是字节数组确定的。`start_index` 从 1 开始计数，长度从 `start_index` 位置计算。 | 支持两个参数**string**：要提取子字符串的源字符串，可以是字符串或文本类型。**start_index**：从哪个索引开始提取子字符串，索引从 1 开始计数。 | String：返回一个字符串，从 `start_index` 位置开始到字符串末尾的所有字符。**注意事项**：`start_index` 从 1 开始，即数组的第 0 个位置是 1参数为 null时，返回 `null`start_index 大于字符串长度时，结果报错。 | substring(string from start_index)或 substring(string, start_index) | | substring | 从一个字符串中提取从指定位置开始、指定长度的子字符串注意：起始位置和长度是基于字符而不是字节数组确定的。`start_index` 从 1 开始计数，长度从 `start_index` 位置计算。 | 支持三个参数**string**：要提取子字符串的源字符串，可以是字符串或文本类型。**start_index**：从哪个索引开始提取子字符串，索引从 1 开始计数。**length**：要提取的子字符串的长度。 | String：返回一个字符串，从 `start_index` 位置开始，提取 `length` 个字符。**注意事项**：参数为 null时，返回 `null`如果 `start_index` 大于字符串的长度，结果报错。如果 `length` 小于 0，结果报错。极端情况，`start_index + length` 超过 `int.MAX` 并变成负数，将导致异常结果。 | substring(string from start_index for length) 或 substring(string, start_index, length) | -## 10. 模式匹配函数 +## 11. 模式匹配函数 -### 10.1 LIKE 运算符 +### 11.1 LIKE 运算符 -#### 10.1.1 用途 +#### 11.1.1 用途 `LIKE` 运算符用于将值与模式进行比较。它通常用于 `WHERE` 子句中，用于匹配字符串中的特定模式。 -#### 10.1.2 语法 +#### 11.1.2 语法 ```SQL ... column [NOT] LIKE 'pattern' ESCAPE 'character'; ``` -#### 10.1.3 匹配规则 +#### 11.1.3 匹配规则 - 匹配字符是区分大小写的。 - 模式支持两个匹配符号： - `_`：匹配任意单个字符。 - `%`：匹配0个或多个字符。 -#### 10.1.4 注意事项 +#### 11.1.4 注意事项 - `LIKE` 模式匹配总是覆盖整个字符串。如果需要匹配字符串中的任意位置，模式必须以 `%` 开头和结尾。 - 如果需要匹配 `%` 或 `_` 作为普通字符，必须使用转义字符。 -#### 10.1.5 示例 +#### 11.1.5 示例 示例 1：匹配以特定字符开头的字符串 @@ -1586,19 +2169,19 @@ SELECT * FROM table1 WHERE continent LIKE 'South\_%' ESCAPE '\'; SELECT * FROM table1 WHERE continent LIKE 'South\\%' ESCAPE '\'; ``` -### 10.2 regexp_like 函数 +### 11.2 regexp_like 函数 -#### 10.2.1 用途 +#### 11.2.1 用途 `regexp_like` 函数用于评估正则表达式模式，并确定该模式是否包含在字符串中。 -#### 10.2.2 语法 +#### 11.2.2 语法 ```SQL regexp_like(string, pattern); ``` -#### 10.2.3 注意事项 +#### 11.2.3 注意事项 - `regexp_like` 的模式只需包含在字符串中，而不需要匹配整个字符串。 - 如果需要匹配整个字符串，可以使用正则表达式的锚点 `^` 和 `$`。 @@ -1621,7 +2204,7 @@ regexp_like(string, pattern); 4. **类别（Categories）**：直接指定，无需`Is`、`general_category=`或`gc=`前缀（如`\p{L}`）。 5. **二元属性（Binary Properties）**：直接指定，无需`Is`（如`\p{NoncharacterCodePoint}`）。 -#### 10.2.4 示例 +#### 11.2.4 示例 示例 1：匹配包含特定模式的字符串 @@ -1645,7 +2228,7 @@ SELECT regexp_like('1a 2b 14m', '^\\d+b$'); -- false - `b` 表示字母 `b`。 - `'1a 2b 14m'` 并不符合这个模式，因为它不是从数字开始，也不是以 `b` 结束，所以返回 `false`。 -## 11. 时序分窗函数 +## 12. 时序分窗函数 原始示例数据如下： @@ -1668,19 +2251,19 @@ CREATE TABLE bid(time TIMESTAMP TIME, stock_id STRING TAG, price FLOAT FIELD); INSERT INTO bid(time, stock_id, price) VALUES('2021-01-01T09:05:00','AAPL',100.0),('2021-01-01T09:06:00','TESL',200.0),('2021-01-01T09:07:00','AAPL',103.0),('2021-01-01T09:07:00','TESL',202.0),('2021-01-01T09:09:00','AAPL',102.0),('2021-01-01T09:15:00','TESL',195.0); ``` -### 11.1 HOP +### 12.1 HOP -#### 11.1.1 功能描述 +#### 12.1.1 功能描述 HOP 函数用于按时间分段分窗分析，识别每一行数据所属的时间窗口。该函数通过指定固定窗口大小（size）和窗口滑动步长（SLIDE），将数据按时间戳分配到所有与其时间戳重叠的窗口中。若窗口之间存在重叠（步长 < 窗口大小），数据会自动复制到多个窗口。 -#### 11.1.2 函数定义 +#### 12.1.2 函数定义 ```SQL HOP(data, timecol, size, slide[, origin]) ``` -#### 11.1.3 参数说明 +#### 12.1.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------- | @@ -1690,7 +2273,7 @@ HOP(data, timecol, size, slide[, origin]) | SLIDE | 标量参数 | 长整数类型 | 窗口滑动步长 | | ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | -#### 11.1.4 返回结果 +#### 12.1.4 返回结果 HOP 函数的返回结果列包含： @@ -1698,7 +2281,7 @@ HOP 函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.1.5 使用示例 +#### 12.1.5 使用示例 ```SQL IoTDB> SELECT * FROM HOP(DATA => bid,TIMECOL => 'time',SLIDE => 5m,SIZE => 10m); @@ -1733,18 +2316,18 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM HOP(DAT +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.2 SESSION +### 12.2 SESSION -#### 11.2.1 功能描述 +#### 12.2.1 功能描述 SESSION 函数用于按会话间隔对数据进行分窗。系统逐行检查与前一行的时间间隔，小于阈值（GAP）则归入当前窗口，超过则归入下一个窗口。 -#### 11.2.2 函数定义 +#### 12.2.2 函数定义 ```SQL SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) ``` -#### 11.2.3 参数说明 +#### 12.2.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | -------------------------- | ---------------------------------------- | @@ -1753,7 +2336,7 @@ SESSION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], timecol, gap) | | GAP | 标量参数 | 长整数类型 | 会话间隔阈值 | -#### 11.2.4 返回结果 +#### 12.2.4 返回结果 SESSION 函数的返回结果列包含： @@ -1761,7 +2344,7 @@ SESSION 函数的返回结果列包含： * window\_end: 会话窗口内的最后一条数据的时间 * 映射列：DATA 参数的所有输入列 -#### 11.2.5 使用示例 +#### 12.2.5 使用示例 ```SQL IoTDB> SELECT * FROM SESSION(DATA => bid PARTITION BY stock_id ORDER BY time,TIMECOL => 'time',GAP => 2m); @@ -1787,19 +2370,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM SESSION +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.3 VARIATION +### 12.3 VARIATION -#### 11.3.1 功能描述 +#### 12.3.1 功能描述 VARIATION 函数用于按数据差值分窗，将第一条数据作为首个窗口的基准值，每个数据点会与基准值进行差值运算，如果差值小于给定的阈值（delta）则加入当前窗口；如果超过阈值，则分为下一个窗口，将该值作为下一个窗口的基准值。 -#### 11.3.2 函数定义 +#### 12.3.2 函数定义 ```sql VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) ``` -#### 11.3.3 参数说明 +#### 12.3.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | -------- | ---------- | -------------------------- | ---------------------------------------- | @@ -1807,14 +2390,14 @@ VARIATION(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], col, delta) | COL | 标量参数 | 字符串类型 | 标识对哪一列计算差值 | | DELTA | 标量参数 | 浮点数类型 | 差值阈值 | -#### 11.3.4 返回结果 +#### 12.3.4 返回结果 VARIATION 函数的返回结果列包含： * window\_index: 窗口编号 * 映射列：DATA 参数的所有输入列 -#### 11.3.5 使用示例 +#### 12.3.5 使用示例 ```sql IoTDB> SELECT * FROM VARIATION(DATA => bid PARTITION BY stock_id ORDER BY time,COL => 'price',DELTA => 2.0); @@ -1841,33 +2424,33 @@ IoTDB> SELECT first(time) as window_start, last(time) as window_end, stock_id, a +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.4 CAPACITY +### 12.4 CAPACITY -#### 11.4.1 功能描述 +#### 12.4.1 功能描述 CAPACITY 函数用于按数据点数（行数）分窗，每个窗口最多有 SIZE 行数据。 -#### 11.4.2 函数定义 +#### 12.4.2 函数定义 ```sql CAPACITY(data [PARTITION BY(pkeys, ...)] [ORDER BY(okeys, ...)], size) ``` -#### 11.4.3 参数说明 +#### 12.4.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | -------- | ---------- | -------------------------- | ---------------------------------------- | | DATA | 表参数 | SET SEMANTICPASS THROUGH | 输入表通过 pkeys、okeys 指定分区和排序 | | SIZE | 标量参数 | 长整数类型 | 窗口大小 | -#### 11.4.4 返回结果 +#### 12.4.4 返回结果 CAPACITY 函数的返回结果列包含： * window\_index: 窗口编号 * 映射列：DATA 参数的所有输入列 -#### 11.4.5 使用示例 +#### 12.4.5 使用示例 ```sql IoTDB> SELECT * FROM CAPACITY(DATA => bid PARTITION BY stock_id ORDER BY time, SIZE => 2); @@ -1894,18 +2477,18 @@ IoTDB> SELECT first(time) as start_time, last(time) as end_time, stock_id, avg(p +-----------------------------+-----------------------------+--------+-----+ ``` -### 11.5 TUMBLE +### 12.5 TUMBLE -#### 11.5.1 功能描述 +#### 12.5.1 功能描述 TUMBLE 函数用于通过时间属性字段为每行数据分配一个窗口，滚动窗口的大小固定且不重复。 -#### 11.5.2 函数定义 +#### 12.5.2 函数定义 ```sql TUMBLE(data, timecol, size[, origin]) ``` -#### 11.5.3 参数说明 +#### 12.5.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------- | @@ -1914,7 +2497,7 @@ TUMBLE(data, timecol, size[, origin]) | SIZE | 标量参数 | 长整数类型 | 窗口大小，需为正数 | | ORIGIN | 标量参数 | 时间戳类型默认值：Unix 纪元时间 | 第一个窗口起始时间 | -#### 11.5.4 返回结果 +#### 12.5.4 返回结果 TUBMLE 函数的返回结果列包含： @@ -1922,7 +2505,7 @@ TUBMLE 函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.5.5 使用示例 +#### 12.5.5 使用示例 ```SQL IoTDB> SELECT * FROM TUMBLE( DATA => bid, TIMECOL => 'time', SIZE => 10m); @@ -1948,19 +2531,19 @@ IoTDB> SELECT window_start, window_end, stock_id, avg(price) as avg FROM TUMBLE( +-----------------------------+-----------------------------+--------+------------------+ ``` -### 11.6 CUMULATE +### 12.6 CUMULATE -#### 11.6.1 功能描述 +#### 12.6.1 功能描述 Cumulate 函数用于从初始的窗口开始，创建相同窗口开始但窗口结束步长不同的窗口，直到达到最大的窗口大小。每个窗口包含其区间内的元素。例如：1小时步长，24小时大小的累计窗口，每天可以获得如下这些窗口：`[00:00, 01:00)`，`[00:00, 02:00)`，`[00:00, 03:00)`， …， `[00:00, 24:00)` -#### 11.6.2 函数定义 +#### 12.6.2 函数定义 ```sql CUMULATE(data, timecol, size, step[, origin]) ``` -#### 11.6.3 参数说明 +#### 12.6.3 参数说明 | 参数名 | 参数类型 | 参数属性 | 描述 | | --------- | ---------- | --------------------------------- | -------------------------------------------- | @@ -1972,7 +2555,7 @@ CUMULATE(data, timecol, size, step[, origin]) > 注意：size 如果不是 step 的整数倍，则会报错`Cumulative table function requires size must be an integral multiple of step` -#### 11.6.4 返回结果 +#### 12.6.4 返回结果 CUMULATE函数的返回结果列包含： @@ -1980,7 +2563,7 @@ CUMULATE函数的返回结果列包含： * window\_end: 窗口结束时间（开区间） * 映射列：DATA 参数的所有输入列 -#### 11.6.5 使用示例 +#### 12.6.5 使用示例 ```sql IoTDB> SELECT * FROM CUMULATE(DATA => bid,TIMECOL => 'time',STEP => 2m,SIZE => 10m);