Strings
Transform, measure, and match text values.
Scalar Functions
| Function | Summary |
|---|---|
spql.str.capitalize | Uppercase the first character and lowercase the remainder. |
spql.str.concat | Concatenate two strings. |
spql.str.contains | Whether string contains pattern. |
spql.str.ends_with | Whether string ends with pattern. |
spql.str.escape_regex | Escape regular-expression metacharacters in a string. |
spql.str.is_alpha | Whether a non-empty string contains only alphabetic characters. |
spql.str.is_ascii | Whether every byte in a string is ASCII. |
spql.str.is_digit | Whether a non-empty string contains only numeric characters. |
spql.str.is_empty | Whether a string is empty. |
spql.str.len_bytes | Count the number of UTF-8 bytes in a string. |
spql.str.len_chars | Count the number of characters in a string. |
spql.str.lower | Convert a string to lowercase. |
spql.str.lstrip | Remove leading whitespace from a string. |
spql.str.replace_regex | Replace the first regular-expression match. |
spql.str.reverse | Reverse the characters in a string. |
spql.str.rstrip | Remove trailing whitespace from a string. |
spql.str.starts_with | Whether string starts with pattern. |
spql.str.strip | Remove leading and trailing whitespace from a string. |
spql.str.substr | Extract a substring by character position. |
spql.str.titlecase | Convert a string to title case. |
spql.str.upper | Convert a string to uppercase. |
spql.str.capitalize
Uppercase the first character and lowercase the remainder.
- Kind:
scalar function - Volatility:
immutable
spql.str.capitalize(value) -> type(value)Same type and nullability as value.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Utf8 expression.
spql.str.concat
Concatenate two strings.
- Kind:
scalar function - Volatility:
immutable
spql.str.concat(left, right) -> utf8Null arguments are treated as empty strings.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
left | yes | utf8? | Text placed before the right-hand input. |
right | yes | utf8? | Text placed after the left-hand input. |
Returns
A Utf8 expression.
spql.str.contains
Whether string contains pattern.
- Kind:
scalar function - Volatility:
immutable
spql.str.contains(string, pattern) -> bool?Nullable when an argument is nullable; otherwise non-nullable.
Literal substring containment: pattern is matched exactly, with no wildcard or regular-expression syntax. A null string or pattern yields null.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
string | yes | utf8 | String to search within. |
pattern | yes | utf8 | Pattern to match, compared literally. |
Returns
A Bool expression.
spql.str.ends_with
Whether string ends with pattern.
- Kind:
scalar function - Volatility:
immutable
spql.str.ends_with(string, pattern) -> bool?Nullable when an argument is nullable; otherwise non-nullable.
Literal suffix test: pattern is matched exactly, with no wildcard or regular-expression syntax. A null string or pattern yields null.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
string | yes | utf8 | String to search within. |
pattern | yes | utf8 | Pattern to match, compared literally. |
Returns
A Bool expression.
spql.str.escape_regex
Escape regular-expression metacharacters in a string.
- Kind:
scalar function - Volatility:
immutable
spql.str.escape_regex(value) -> type(value)Same type and nullability as value.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Utf8 expression.
spql.str.is_alpha
Whether a non-empty string contains only alphabetic characters.
- Kind:
scalar function - Volatility:
immutable
spql.str.is_alpha(value) -> bool?Nullable when an argument is nullable; otherwise non-nullable.
Uses Unicode alphabetic-character classification.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Bool expression.
spql.str.is_ascii
Whether every byte in a string is ASCII.
- Kind:
scalar function - Volatility:
immutable
spql.str.is_ascii(value) -> bool?Nullable when an argument is nullable; otherwise non-nullable.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Bool expression.
spql.str.is_digit
Whether a non-empty string contains only numeric characters.
- Kind:
scalar function - Volatility:
immutable
spql.str.is_digit(value) -> bool?Nullable when an argument is nullable; otherwise non-nullable.
Uses Unicode numeric-character classification.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Bool expression.
spql.str.is_empty
Whether a string is empty.
- Kind:
scalar function - Volatility:
immutable
spql.str.is_empty(value) -> bool?Nullable when an argument is nullable; otherwise non-nullable.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform. |
Returns
A Bool value or expression.
spql.str.len_bytes
Count the number of UTF-8 bytes in a string.
- Kind:
scalar function - Volatility:
immutable
spql.str.len_bytes(value) -> u64?Nullable when an argument is nullable; otherwise non-nullable.
Counts encoded bytes, so a multi-byte character counts more than once.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform. |
Returns
A U64 value or expression.
spql.str.len_chars
Count the number of characters in a string.
- Kind:
scalar function - Volatility:
immutable
spql.str.len_chars(value) -> u64?Nullable when an argument is nullable; otherwise non-nullable.
Counts Unicode scalar values, not bytes; multi-byte characters count once each.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A U64 expression.
spql.str.lower
Convert a string to lowercase.
- Kind:
scalar function - Volatility:
immutable
spql.str.lower(value) -> type(value)Same type and nullability as value.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Utf8 expression.
spql.str.lstrip
Remove leading whitespace from a string.
- Kind:
scalar function - Volatility:
immutable
spql.str.lstrip(value) -> type(value)Same type and nullability as value.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Utf8 expression.
spql.str.replace_regex
Replace the first regular-expression match.
- Kind:
scalar function - Volatility:
immutable
spql.str.replace_regex(string, pattern, replacement) -> utf8?Nullable when an argument is nullable; otherwise non-nullable.
Matching is case-sensitive. Backslash followed by 0 selects the complete match; 1 through 9 select capture groups. Dollar signs are literal. Two backslashes produce one literal backslash. A null argument yields null; an invalid pattern on a non-null row produces an error. SQL REGEXP_REPLACE with three arguments invokes this function.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
string | yes | utf8 | String to search. |
pattern | yes | utf8 | Regular expression. Look-around and pattern backreferences are not supported. |
replacement | yes | utf8 | Replacement template. Use backslash-number references for capture groups. |
Returns
A Utf8 expression.
spql.str.reverse
Reverse the characters in a string.
- Kind:
scalar function - Volatility:
immutable
spql.str.reverse(value) -> type(value)Same type and nullability as value.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Utf8 expression.
spql.str.rstrip
Remove trailing whitespace from a string.
- Kind:
scalar function - Volatility:
immutable
spql.str.rstrip(value) -> type(value)Same type and nullability as value.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Utf8 expression.
spql.str.starts_with
Whether string starts with pattern.
- Kind:
scalar function - Volatility:
immutable
spql.str.starts_with(string, pattern) -> bool?Nullable when an argument is nullable; otherwise non-nullable.
Literal prefix test: pattern is matched exactly, with no wildcard or regular-expression syntax. A null string or pattern yields null.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
string | yes | utf8 | String to search within. |
pattern | yes | utf8 | Pattern to match, compared literally. |
Returns
A Bool expression.
spql.str.strip
Remove leading and trailing whitespace from a string.
- Kind:
scalar function - Volatility:
immutable
spql.str.strip(value) -> type(value)Same type and nullability as value.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Utf8 expression.
spql.str.substr
Extract a substring by character position.
- Kind:
scalar function - Volatility:
immutable
spql.str.substr(string, start, length) -> utf8?Nullable when an argument is nullable; otherwise non-nullable.
start is one-based and length counts Unicode scalar values, not bytes. Positions before the first character reduce the returned length. A start after the string returns an empty string. A negative length is invalid. A null argument yields null.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
string | yes | utf8 | String to extract from. |
start | yes | i64 | One-based character position at which extraction starts. |
length | yes | i64 | Maximum number of characters to return. |
Returns
A Utf8 expression.
spql.str.titlecase
Convert a string to title case.
- Kind:
scalar function - Volatility:
immutable
spql.str.titlecase(value) -> type(value)Same type and nullability as value.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Utf8 expression.
spql.str.upper
Convert a string to uppercase.
- Kind:
scalar function - Volatility:
immutable
spql.str.upper(value) -> type(value)Same type and nullability as value.
Parameters
| Name | Required | Type | Description |
|---|---|---|---|
value | yes | utf8 | UTF-8 text to transform or inspect. |
Returns
A Utf8 expression.