Project: Beam (App Definition and Development / Streaming & Messaging)
File: string-functions.md

type: languages title: "Beam ZetaSQL string functions" <!-- Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> This page documents the ZetaSQL string functions supported by Beam ZetaSQL. These string functions work on STRING data. STRING values must be well-formed UTF-8. All string comparisons are done byte-by-byte, without regard to Unicode canonical equivalence. {{< table >}} | Operator syntax | Description | | - | - | | | Returns the length of the string in characters | | | Synonym for CHAR_LENGTH | | | Concatenates up to five values into a single result | | | Returns TRUE if the second value is a suffix of the first | | | Identical to TRIM, but only removes leading characters. | | | Replaces all occurrences of `fromvalue` with `tovalue` in `original_value` | | | Returns the reverse of the input string | | | Identical to TRIM, but only removes trailing characters | | | Returns TRUE if the second value is a prefix of the first. | | | Returns a substring of the supplied value | | | Removes all leading and trailing characters that match `value2` | {{< /table >}} ``` CHAR_LENGTH(value) ``` Description Returns the length of the STRING in characters. Return type INT64 Examples ``` Table example: +-+ | characters | +-+ | | +-+ SELECT characters, CHARLENGTH(characters) AS charlength_example FROM example; +++ | characters | charlengthexample | +++ | | 5 | +++ ``` ``` CHARACTER_LENGTH(value) ``` Description Synonym for . Return type INT64 Examples ``` Table example: +-+ | characters | +-+ | | +-+ SELECT characters, CHARACTERLENGTH(characters) AS charlength_example FROM example; +++ | characters | charlengthexample | +++ | | 5 | +++ ``` ``` CONCAT(value1[, ...]) ``` Description Concatenates up to five values into a single result. Return type STRING Examples ``` Table Employees: +-+--+ | firstname | lastname | +-+--+ | John | Doe | | Jane | Smith | | Joe | Jackson | +-+--+ SELECT CONCAT(firstname, " ", lastname) AS full_name FROM Employees; ++ | full_name | ++ | John Doe | | Jane Smith | | Joe Jackson | ++ ``` ``` ENDS_WITH(value1, value2) ``` Description Takes two values. Returns TRUE if the second value is a suffix of the

Return type BOOL Examples ``` Table items: +-+ | item | +-+ | apple | | banana | | orange | +-+ SELECT ENDS_WITH(item, "e") as example FROM items; ++ | example | ++ | True | | False | | True | ++ ``` ``` LTRIM(value1[, value2]) ``` Description Identical to , but only removes leading characters. Return type STRING Examples ``` Table items: +-+ | item | +-+ | apple | | banana | | orange | +-+ SELECT CONCAT("#", LTRIM(item), "#") as example FROM items; +-+ | example | +-+ | #apple # | | #banana # | | #orange # | +-+ Table items: +-+ | item | +-+ | *apple* | | *banana* | | *orange* | +-+ SELECT LTRIM(item, "*") as example FROM items; +--+ | example | +--+ | apple* | | banana* | | orange* | +--+ Table items: +-+ | item | +-+ | xxxapplexxx | | yyybananayyy | | zzzorangezzz | | xyzpearzyz | +-+ SELECT LTRIM(item, "xyz") as example FROM items; +--+ | example | +--+ | applexxx | | bananayyy | | orangezzz | | pearxyz | +--+ ``` ``` REPLACE(originalvalue, fromvalue, to_value) ``` Description Replaces all occurrences of `fromvalue` with `tovalue` in `original_value`. If `from_value` is empty, no replacement is made. Return type STRING Examples ```sql +--+ | dessert | +--+ | apple pie | | blackberry pie | | cherry pie | +--+ SELECT REPLACE (dessert, "pie", "cobbler") as example FROM desserts; +--+ | example | +--+ | apple cobbler | | blackberry cobbler | | cherry cobbler | +--+ ``` ``` REVERSE(value) ``` Description Returns the reverse of the input STRING. Return type STRING Examples ``` WITH example AS ( SELECT "foo" AS sample_string UNION ALL SELECT "" AS sample_string ) SELECT sample_string, REVERSE(samplestring) AS reversestring FROM example; ++-+ | samplestring | reversestring | ++-+ | foo | oof | | | | ++-+ ``` ``` RTRIM(value1[, value2]) ``` Description Identical to , but only removes trailing characters. Return type STRING Examples ``` Table items: +-+ | item | +-+ | *apple* | | *banana* | | *orange* | +-+ SELECT RTRIM(item, "*") as example FROM items; +--+ | example | +--+ | *apple | | *banana | | *orange | +--+ Table items: +-+ | item | +-+ | applexxx | | bananayyy | | orangezzz | | pearxyz | +-+ SELECT RTRIM(item, "xyz") as example FROM items; ++ | example | ++ | apple | | banana | | orange | | pear | ++ ``` ``` STARTS_WITH(value1, value2) ``` Description Takes two values. Returns TRUE if the second value is a prefix of the

Return type BOOL Examples ``` SELECT STARTS_WITH(item, "b") as example FROM ( SELECT "foo" as item UNION ALL SELECT "bar" as item UNION ALL SELECT "baz" as item) AS items; ++ | example | ++ | False | | True | | True | ++ ``` ``` SUBSTR(value, position[, length]) ``` Description Returns a substring of the supplied value. The `position` argument is an integer specifying the starting position of the substring, with position = 1 indicating the first character or byte. The `length` argument is the maximum number of characters for STRING arguments. If `position` is negative, the function counts from the end of `value`, with -1 indicating the last character. If `position` is a position off the left end of the STRING (`position` = 0 or `position` &lt; `-LENGTH(value)`), the function starts from position = 1. If `length` exceeds the length of `value`, returns fewer than `length` characters. If `length` is less than 0, the function returns an error. Return type STRING Examples ``` Table items: +-+ | item | +-+ | apple | | banana | | orange | +-+ SELECT SUBSTR(item, 2) as example FROM items; ++ | example | ++ | pple | | anana | | range | ++ Table items: +-+ | item | +-+ | apple | | banana | | orange | +-+ SELECT SUBSTR(item, 2, 2) as example FROM items; ++ | example | ++ | pp | | an | | ra | ++ Table items: +-+ | item | +-+ | apple | | banana | | orange | +-+ SELECT SUBSTR(item, -2) as example FROM items; ++ | example | ++ | le | | na | | ge | ++ ``` ``` TRIM(value1[, value2]) ``` Description Removes all leading and trailing characters that match `value2`. If `value2` is not specified, all leading and trailing whitespace characters (as defined by the Unicode standard) are removed. If `value2` contains more than one character, the function removes all leading or trailing characters contained in `value2`. Return type STRING Examples ``` Table items: +-+ | item | +-+ | apple | | banana | | orange | +-+ SELECT CONCAT("#", TRIM(item), "#") as example FROM items; +-+ | example | +-+ | #apple# | | #banana# | | #orange# | +-+ Table items: +-+ | item | +-+ | *apple* | | *banana* | | *orange* | +-+ SELECT TRIM(item, "*") as example FROM items; ++ | example | ++ | apple | | banana | | orange | ++ Table items: +-+ | item | +-+ | xxxapplexxx | | yyybananayyy | | zzzorangezzz | | xyzpearxyz | +-+ SELECT TRIM(item, "xyz") as example FROM items; ++ | example | ++ | apple | | banana | | orange | | pear | ++ ```