@clickzetta/cz-cli-darwin-arm64 0.3.94 → 0.3.96

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/split.md

@@ -0,0 +1,57 @@
+### SPLIT 
+
+#### Description
+The `SPLIT` function is used to split a string (`str`) into multiple substrings based on a specified regular expression (`regex`), and store these substrings in an array. This function is very useful when processing and analyzing text data, as it can help you quickly extract the required information.
+
+#### Parameters
+* `str` (string): The original string to be split.
+* `regex` (string): The regular expression used to define the splitting rules.
+* `limit` (int, optional): The maximum length of the returned array. When `limit` is greater than 0, the length of the returned array will not exceed the value specified by `limit`. When `limit` is less than or equal to 0, it means that the length of the array is not limited. The default value is 0.
+
+#### Return Value
+Returns an array (`array<string>`) containing the split substrings.
+
+#### Example
+
+**Example 1**: Basic usage
+```sql
+SELECT SPLIT('1a2b3c', '[abc]');
+```
+Results:
+```
+["1","2","3",""]
+
+```
+**Example 2**: Limit the length of the returned array
+```sql
+SELECT SPLIT('1a2b3c', '[abc]', 2);
+```
+Results:
+```
+["1", "2b3c"]
+```
+**Example 3**: Using different delimiters
+```sql
+SELECT SPLIT('apple,banana,cherry', ',');
+```
+Results:
+```
+["apple", "banana", "cherry"]
+```
+**Example 4**: Handling Nested Delimiters
+```sql
+SELECT SPLIT('1-a2-b3-c', '-([a-z]+)-');
+```
+Results:
+```
+["1-a2-b3-c"]
+
+```
+**Example 5**: Using with the `limit` parameter
+```sql
+SELECT SPLIT('one:two:three:four', ':', 3);
+```
+Results:
+```
+["one", "two", "three:four"]
+```

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/split_by_regexp.md

@@ -0,0 +1,34 @@
+# SPLIT_BY_REGEXP
+
+## Overview
+
+Splits a string by a regular expression and returns an `ARRAY<STRING>`. This function is identical to `REGEXP_SPLIT_TO_ARRAY`.
+
+## Syntax
+
+```Plain
+SPLIT_BY_REGEXP(<str>, <pattern>)
+```
+
+## Parameters
+
+- `<str>`: STRING type. The string to split.
+- `<pattern>`: STRING type. The regular expression pattern.
+
+## Examples
+
+```sql
+-- Split by digit (trailing empty string included)
+SELECT split_by_regexp('a1b2c3', '[0-9]');
+-- ["a","b","c",""]
+
+-- Split by one or more whitespace characters (using POSIX character class)
+SELECT split_by_regexp('a  b   c', '[[:space:]]+');
+-- ["a","b","c"]
+```
+
+## Related Documentation
+
+- [REGEXP_SPLIT_TO_ARRAY](regexp_split_to_array.md) — alias with identical behavior
+- [SPLIT_BY_STRING](split_by_string.md) — splits by a literal string (no regex interpretation)
+- [SPLIT](split.md)

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/split_by_string.md

@@ -0,0 +1,33 @@
+# SPLIT_BY_STRING
+
+## Overview
+
+Splits a string by a literal string delimiter and returns an `ARRAY<STRING>`. Unlike `SPLIT`, the delimiter is treated as a literal string rather than a regular expression, making it safe for delimiters that contain regex special characters (such as `::` or `|`).
+
+## Syntax
+
+```Plain
+SPLIT_BY_STRING(<str>, <delimiter>)
+```
+
+## Parameters
+
+- `<str>`: STRING type. The string to split.
+- `<delimiter>`: STRING type. The literal string delimiter; not interpreted as a regular expression.
+
+## Examples
+
+```sql
+SELECT split_by_string('a::b::c', '::');
+-- ["a","b","c"]
+
+-- Safe when the delimiter contains regex special characters
+SELECT split_by_string('a|b|c', '|');
+-- ["a","b","c"]
+```
+
+## Related Documentation
+
+- [SPLIT](split.md) — splits by regular expression
+- [SPLIT_BY_REGEXP](split_by_regexp.md) — explicitly splits by regular expression
+- [REGEXP_SPLIT_TO_ARRAY](regexp_split_to_array.md)

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/split_part.md

@@ -0,0 +1,42 @@
+### SPLIT_PART
+```sql
+split_part(str, delim, partNum)
+```
+####  Description
+The SPLIT_PART function is used to split a string (str) by a specified delimiter (delim) and return the substring at the specified position (partNum).
+
+#### Parameter Description
+* str (string): The string to be split.
+* delim (string): The string used as a delimiter to split the input string into multiple substrings.
+* partNum (bigint): Specifies the position of the substring to return. When partNum is greater than 0, it indicates the partNum-th substring from the left; when partNum is less than 0, it indicates the partNum-th substring from the right. If partNum exceeds the number of substrings after splitting, an empty string is returned. partNum cannot be 0.
+
+#### Return Result
+Returns a string (string) representing the substring at the specified position.
+
+#### Usage Example
+```sql
+-- Example 1: Return the second substring
+SELECT split_part('a,b,c', ',', 2);
+-- Result: b
+
+-- Example 2: Return the last substring
+SELECT split_part('a,b,c', ',', -1);
+-- Result: c
+
+-- Example 3: Return the third substring (counting from the right)
+SELECT split_part('a,b,c,d,e', ',', -2);
+-- Result: d
+
+-- Example 4: When partNum exceeds the number of substrings, return an empty string
+SELECT split_part('a,b,c', ',', 4);
+-- Result is empty
+
+-- Example 5: Use multiple characters as delimiters
+SELECT split_part('apple-orange-grape', '-|g', 1);
+-- Result: apple-orange-grape
+```
+#### Notes
+* When partNum is 0, the function will return an error.
+* If the input string or delimiter is empty, the function will return an empty string.
+* When partNum is negative, the position of the substring is calculated from the right side.
+* If multiple characters are needed as delimiters, multiple characters can be used consecutively or a regular expression can be used for splitting.

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/startswith.md

@@ -0,0 +1,68 @@
+# STARTSWITH 
+
+##  Description
+
+The `STARTSWITH` function is used to determine whether a string starts with another specified string. If the condition is met, it returns the Boolean value `TRUE`; otherwise, it returns `FALSE`. This function supports both string and binary data and is applicable to string processing and pattern matching scenarios.
+
+## Syntax
+
+```sql
+STARTSWITH(expr, startExpr)
+```
+
+## Parameters
+
+- `expr`: A `STRING` or `BINARY` expression representing the target data to be checked.
+- `startExpr`: A `STRING` or `BINARY` expression representing the starting pattern for comparison.
+
+## Return Value
+
+- The return value is of Boolean type (`TRUE` or `FALSE`).
+- If either `expr` or `startExpr` is `NULL`, the function returns `NULL`.
+- If `startExpr` is an empty string or empty binary data, the function returns `TRUE`.
+
+## Examples
+
+Example 1: String pattern matching
+
+```sql
+SELECT STARTSWITH('SparkSQL', 'Spark') AS result;
++--------+
+| result |
++--------+
+| true   |
++--------+
+```
+
+Example 2: Case sensitivity
+
+```sql
+SELECT STARTSWITH('LakehouseSQL', 'lakehouse') AS result;
++--------+
+| result |
++--------+
+| false  |
++--------+
+```
+
+Example 3: Including NULL values
+
+```sql
+SELECT STARTSWITH('LakehouseSQL', NULL) AS result;
++--------+
+| result |
++--------+
+| null   |
++--------+
+```
+
+Example 4: Empty string or empty binary
+
+```sql
+SELECT STARTSWITH('LakehouseSQL', '') AS result;
++--------+
+| result |
++--------+
+| true   |
++--------+
+```

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/str_to_map.md

@@ -0,0 +1,46 @@
+### STR_TO_MAP
+
+###  Description
+
+This function is used to split a string into key-value pairs according to specified delimiters and generate a result of type map.
+
+### Parameter Description
+
+* str (string type): The string to be split.
+* pairDelim (string type, optional parameter, default value is ','): Used to specify the delimiter between each key-value pair.
+* keyValueDelim (string type, optional parameter, default value is ':'): Used to specify the delimiter between the key and value.
+
+### Return Value
+
+Returns a result of type map, where both the keys and values are of string type.
+
+### Usage Example
+
+1. Basic Usage
+   ```sql
+   SELECT STR_TO_MAP('a:1,b:2,c:3');
+   ```
+Return results:
+   ```json
+   {"a" : "1", "b" : "2", "c" : "3"}
+   ```
+2. Custom Key-Value Pair Separator
+   ```sql
+   SELECT STR_TO_MAP('a/1;b/2;c/3', ';', '/');
+   ```
+Return results:
+   ```json
+   {"a" : "1", "b" : "2", "c" : "3"}
+   ```
+3. Custom Key-Value Separators and Keys Without Values
+   ```sql
+   SELECT STR_TO_MAP('name:Tom;age:28;gender:;hobby:coding', ';', ':');
+   ```
+Return results:
+   ```json
+   {"name" : "Tom", "age" : "28", "gender" : "", "hobby" : "coding"}
+   ```
+### Precautions
+
+* If there are missing keys or values in the input string, the function will treat it as a valid key-value pair and set the missing key or value to null.
+* If the input string format is incorrect, the function will return an empty map type result.

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/strpos.md

@@ -0,0 +1,80 @@
+### STRPOS
+```sql
+strpos(str, substr [, instance])
+```
+
+#### Function
+Returns the position of the first occurrence (or the instance-th occurrence) of the substring substr in the string str.
+
+#### Parameters
+* str: string type
+* substr: string type, the substring to search for
+* instance: int type (optional), specifies which occurrence to find, defaulting to 1
+
+#### Returns
+* int type, returns the position of the substring occurrence (1-based indexing)
+* Returns 0 if the substring is not found
+* Returns NULL if any parameter is NULL
+* Returns 0 if instance is less than or equal to 0
+
+#### Examples
+```sql
+SELECT strpos('high', 'ig');
+-- Result: 2
+```
+
+```sql
+SELECT strpos('high', 'igx');
+-- Result: 0
+```
+
+```sql
+SELECT strpos('Quadratically', 'a');
+-- Result: 3
+```
+
+```sql
+SELECT strpos('abc/xyz/foo/bar', '/', 1);
+-- Result: 4
+```
+
+```sql
+SELECT strpos('abc/xyz/foo/bar', '/', 2);
+-- Result: 8
+```
+
+```sql
+SELECT strpos('abc/xyz/foo/bar', '/', 3);
+-- Result: 12
+```
+
+```sql
+SELECT strpos('abc/xyz/foo/bar', '/', 4);
+-- Result: 0
+```
+
+```sql
+SELECT strpos('Belief,Love,Hope', 'Love');
+-- Result: 8
+```
+
+```sql
+SELECT strpos('Belief,Love,Hope', 'Hope');
+-- Result: 14
+```
+
+```sql
+SELECT strpos('', '');
+-- Result: 1
+```
+
+```sql
+SELECT strpos(null, '');
+-- Result: NULL
+```
+
+#### Notes
+* Position indexing starts at 1 (not 0).
+* Supports Unicode strings.
+* Returns 0 when the instance parameter exceeds the actual number of occurrences.
+* When substr is an empty string, returns 1 if str is non-empty; returns 1 if both str and substr are empty.

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/substr.md

@@ -0,0 +1,40 @@
+### SUBSTR 
+
+####  Description
+The SUBSTR function is used to extract a substring of specified position and length from a string or binary data.
+
+#### Syntax
+```
+SUBSTR(str, pos [, len])
+```
+or
+```
+SUBSTR(str FROM pos [FOR len])
+```
+#### Parameter Description
+- `str` (string/binary): Input string or binary data.
+- `pos` (bigint): Starting position of the substring. If `pos` is greater than or equal to 1, extraction starts from the `pos`-th character from the left; if `pos` is less than or equal to -1, extraction starts from the `-pos`-th character from the right; if `pos` is equal to 0, extraction starts from the first character on the left.
+- `len` (bigint, optional): Length of the substring to extract. If not specified, the full substring starting from `pos` is returned.
+
+#### Return Result
+Returns the extracted substring, type is string.
+
+####  Example
+1. Extract 5 characters from the string "Hello, world!" starting from the second character:
+```sql
+SELECT SUBSTR('Hello, world!', 2, 5);
+-- Output result: ello,
+```
+2. Extract all characters from the fourth character onwards from the string "123456789":
+```sql
+SELECT SUBSTR('123456789', 4);
+-- Output result: 456789
+```
+3. Extract 1 character from the string "Database" starting from the second character, and specify the character set as UTF-8:
+```sql
+SELECT SUBSTR('Database' FROM 2 FOR 1 );
+-- Output result: a
+```
+#### Notes
+- If the value of `pos` or `len` exceeds the range of the input string, the function will return an empty string.
+- When extracting a string, the units for `pos` and `len` are characters, not bytes.

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/substring.md

@@ -0,0 +1,47 @@
+### SUBSTRING 
+
+#### Description
+The SUBSTRING function is used to extract a substring from a string or binary data. Based on the specified starting position (pos) and length (len), the SUBSTRING function returns the corresponding substring.
+
+#### Syntax
+```
+substring(str, pos [, len])
+    
+substring(str FROM pos [FOR len])
+```
+#### Parameters
+- `str` (string/binary): The input string or binary data.
+- `pos` (bigint): The starting position of the substring. If pos is greater than or equal to 1, it starts from the pos-th character from the left; if pos is less than or equal to -1, it starts from the -pos-th character from the right; if pos is equal to 0, it starts from the first character on the left.
+- `len` (bigint, optional): The length of the substring. If not specified, the complete substring starting from pos is returned.
+
+#### Return Result
+Returns a string representing the substring extracted from the input string.
+
+#### Usage Example
+
+1. Extract the first two characters of the string:
+   ```sql
+   > SELECT substring('Hello, world!', 1, 2);
+   He
+   ```
+2. Extract the complete substring starting from the fourth character:
+   ```sql
+   > SELECT substring('Hello, world!', 4);
+   lo, world!
+   ```
+3. Extract the two characters starting from the second to last character of the string:
+   ```sql
+   > SELECT substring('Hello, world!', -2, 2);
+   d!
+   ```
+4. Extract the domain name from the URL:
+   ```sql
+   > SELECT substring('http\://www\.example.com', LOCATE('://', 'http\://www\.example.com')+3);
+   www.example.com
+   ```
+5. Extract specific parts of a string (e.g., extract month and date):
+   ```sql
+   > SELECT substring('2023-04-15', 5, 5);
+   -04-1  
+   ```
+By the above examples, you can see the application of the SUBSTRING function in different scenarios. Using the SUBSTRING function allows you to conveniently extract the required substring from a string, thereby meeting various data processing needs.

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/substring_index.md

@@ -0,0 +1,46 @@
+### SUBSTRING_INDEX
+```sql
+substring_index(expr, delim, count) 
+```
+####  Description
+The SUBSTRING_INDEX function is used to extract the substring before the delimiter delim appears count times in a string or binary data. This function is very useful when processing text data, especially when you need to split or extract strings based on a specific delimiter.
+
+#### Parameter Description
+* **expr** (string/binary): The original string or binary data to be processed.
+* **delim** (string/binary): The string or binary data used as the delimiter, of the same type as expr.
+* **count** (bigint): Indicates the count of the delimiter's occurrences. If count is positive, counting starts from the left side of the string; if count is negative, counting starts from the right side; if count is 0, an empty string is returned.
+
+#### Return Result
+Returns a string or binary data representing the substring before the delimiter appears count times in expr.
+
+#### Usage Example
+```sql
+-- Example 1: Extract substring from left to right
+SELECT substring_index('a,b,c,d', ',', 2);
+-- Result: 'a,b'
+
+-- Example 2: Extract substring from right to left
+SELECT substring_index('a,b,c,d', ',', -2);
+-- Result: 'c,d'
+
+-- Example 3: Extract the entire string before the delimiter
+SELECT substring_index('a,b,c,d', ',', 1);
+-- Result: 'a'
+
+-- Example 4: Use negative count to extract substring from right to left
+SELECT substring_index('a,b,c,d', ',', -1);
+-- Result: 'd'
+
+-- Example 5: Return an empty string when count is 0
+SELECT substring_index('a,b,c,d', ',', 0);
+-- Result: ''
+
+-- Example 6: Extract substring from binary data
+SELECT substring_index('hello,world,123', ',world,', 1);
+-- Result: 'hello'
+```
+#### Notes
+* When count is a positive number, the function will start searching for the delimiter delim from the left side of the string and return the substring before it.
+* When count is a negative number, the function will start searching for the delimiter delim from the right side of the string and return the substring before it.
+* When the absolute value of count is greater than the number of occurrences of the delimiter, the function will return an empty string.
+* If expr or delim is NULL, it returns NULL.

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/translate.md

@@ -0,0 +1,42 @@
+### TRANSLATE
+
+###  Description
+The `translate` function is used to convert certain characters in the input string `str` according to the specified replacement rules. Specifically, it matches the characters in `str` with the character set in the `from` parameter and replaces the matched characters with the characters at the corresponding positions in the `to` parameter. If a character in `from` does not have a corresponding replacement character in `to`, that character is removed from the resulting string.
+
+### Parameter Description
+- `str` (string type): The original string that needs character replacement.
+- `from` (string type): Contains the set of characters that need to be replaced.
+- `to` (string type): Contains the set of characters used for replacement. The order of characters should correspond to the order in the `from` parameter.
+
+### Return Value
+Returns the processed string.
+
+###  Example
+1. Suppose we have a string "HelloWorld" and we want to replace all "l" with "b", we can use the following statement:
+   ```sql
+   SELECT translate('HelloWorld', 'l', 'b');
+   ```
+The execution result is "HebboWorbd".
+
+2. If we want to replace "lo" in the string "HelloWorld" with "ab", we can use the following statement:
+   ```sql
+   SELECT translate('HelloWorld', 'lo', 'ab');
+   ```
+The execution result is "HeaabWbrad".
+
+3. Now, if we want to replace "l" and "o" in the string "HelloWorld" with "b" and "n" respectively, we can use the following statement:
+   ```sql
+   SELECT translate('HelloWorld', 'lo', 'bn');
+   ```
+The execution result is "HebbnWnrbd".
+
+4. When the number of characters in the `to` parameter is less than the `from` parameter, the extra characters will be deleted. For example, to replace "lo" in the string "HelloWorld" with "a", you can use the following statement:
+   ```sql
+   SELECT translate('HelloWorld', 'lo', 'a');
+   ```
+The execution result is "HeaaWrad".
+
+### Notes
+- Ensure that the number of characters in the `from` and `to` parameters are equal, otherwise it may result in incomplete replacement or deletion of characters.
+- If the `to` parameter is NULL, it will cause all `from` return results to also be NULL.
+- This function is case-sensitive, so make sure the case of the input characters matches the case of the characters to be replaced.

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/trim.md

@@ -0,0 +1,51 @@
+### TRIM 
+```
+trim(str [, trimStr])
+```
+####  Description
+The TRIM function is used to remove specified characters (or spaces) from both sides of the string `str`. If the `trimStr` parameter is not specified, all space characters on both sides of the string are removed by default.
+
+#### Parameter Description
+- `str` (string): The original string to be processed.
+- `trimStr` (string, optional): The set of characters to be removed. If this parameter is omitted, space characters are removed by default.
+
+#### Return Result
+Returns the processed string.
+
+####  Example
+1. Remove spaces from both ends of the string:
+   ```sql
+   > SELECT '  Hello, World!  ' AS original, TRIM(original) AS trimmed;
+    +----------------+--------+
+    | original       | trimmed |
+    +----------------+--------+
+    |  Hello, World!  | Hello, World! |
+    +----------------+--------+
+   ```
+2. Remove specific characters (such as asterisks) from both ends of a string:
+   ```sql
+   > SELECT '**Hello, World!**' AS original, TRIM('**Hello, World!**' ,'**' ) AS trimmed;
+    +----------------+--------+
+    | original       | trimmed |
+    +----------------+--------+
+    | **Hello, World!** | Hello, World! |
+    +----------------+--------+
+   ```
+3. Remove leading zero characters from a string:
+   ```sql
+   > SELECT '000Hello, World!' AS original, TRIM('000Hello, World!', '0' ) AS trimmed;
+    +----------------+--------+
+    | original       | trimmed |
+    +----------------+--------+
+    | 000Hello, World! | Hello, World! |
+    +----------------+--------+
+   ```
+4. Remove the percentage sign from the right side of the string:
+   ```sql
+   > SELECT 'Hello, World!%' AS original, TRIM('Hello, World!%', '%' ) AS trimmed;
+    +----------------+--------+
+    | original       | trimmed |
+    +----------------+--------+
+    | Hello, World!% | Hello, World! |
+    +----------------+--------+
+   ```

package/bin/skills/lakehouse-doc-en/references/sql_functions/scalar_functions/string_functions/typeof.md

@@ -0,0 +1,63 @@
+### TYPEOF
+```sql
+typeof(expr)
+```
+#### Function
+Returns the data type of the expression. This function is used to query the type information of an expression or column, and is very useful in dynamic SQL and type checking scenarios.
+
+#### Parameters
+* `expr`: An expression of any type
+
+#### Returns
+* string type
+* Returns the data type name of the expression
+* For basic types, returns the type name (e.g., 'int', 'string', 'boolean')
+* For complex types, returns the full type definition (e.g., `array<...>`, `map<...>`, `struct<...>`)
+
+#### Examples
+```sql
+SELECT typeof(true);
+-- Result: boolean
+```
+
+```sql
+SELECT typeof(1);
+-- Result: int
+```
+
+```sql
+SELECT typeof(1.0);
+-- Result: decimal(2,1)
+```
+
+```sql
+SELECT typeof("1");
+-- Result: string
+```
+
+```sql
+SELECT typeof(array(1, 2, 3));
+-- Result: array<int>
+```
+
+```sql
+SELECT typeof(map(1, 2));
+-- Result: map<int,int>
+```
+
+```sql
+SELECT typeof(struct(1, 2, 3));
+-- Result: struct<col1:int,col2:int,col3:int>
+```
+
+#### Notes
+* The typeof function returns a type name string, not a type object.
+* For the decimal type, returns complete precision information, such as 'decimal(10,2)'.
+* For complex types (array, map, struct), returns the complete nested type definition.
+* Field names in `struct` types default to `col1`, `col2`, `col3`, etc.
+* This function determines the type at compile time and does not change at runtime.
+* Common use cases:
+  * Debugging and diagnostics
+  * Generating type-related metadata
+* Note: `TYPEOF` only returns type information, not NULL constraint information.
+* This function has minimal performance impact because type information is determined at compile time.