Funções de string

Essas funções de string funcionam em dois valores diferentes: tipos de dados STRING e BYTES. Os valores STRING precisam ter a codificação UTF-8 bem formada.

As funções que retornam valores de posição, como STRPOS, codificam essas posições como INT64. O valor 1 indica o primeiro caractere (ou byte), 2 indica o segundo, e assim por diante. O valor 0 indica um índice inválido. Ao trabalhar em tipos STRING, as posições retornadas indicam as posições dos caracteres.

Todas as comparações de string são feitas byte a byte, sem levar em conta a equivalência canônica Unicode.

BYTE_LENGTH

BYTE_LENGTH(value)

Descrição

Retorna o comprimento do valor STRING ou BYTES em BYTES, independentemente do tipo de valor ser STRING ou BYTES.

Tipo de retorno

INT64

Exemplos

WITH example AS
  (SELECT "абвгд" AS characters, b"абвгд" AS bytes)

SELECT
  characters,
  BYTE_LENGTH(characters) AS string_example,
  bytes,
  BYTE_LENGTH(bytes) AS bytes_example
FROM example;

+------------+----------------+-------+---------------+
| characters | string_example | bytes | bytes_example |
+------------+----------------+-------+---------------+
| абвгд      | 10             | абвгд | 10            |
+------------+----------------+-------+---------------+

CHAR_LENGTH

CHAR_LENGTH(value)

Descrição

Retorna o comprimento da STRING em caracteres.

Tipo de retorno

INT64

Exemplos

WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  CHAR_LENGTH(characters) AS char_length_example
FROM example;

+------------+---------------------+
| characters | char_length_example |
+------------+---------------------+
| абвгд      |                   5 |
+------------+---------------------+

CHARACTER_LENGTH

CHARACTER_LENGTH(value)

Descrição

Sinônimo para CHAR_LENGTH.

Tipo de retorno

INT64

Exemplos

WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  CHARACTER_LENGTH(characters) AS char_length_example
FROM example;

+------------+---------------------+
| characters | char_length_example |
+------------+---------------------+
| абвгд      |                   5 |
+------------+---------------------+

CODE_POINTS_TO_BYTES

CODE_POINTS_TO_BYTES(ascii_values)

Descrição

Usa uma matriz de pontos de código (em inglês) ASCII estendidos (ARRAY de INT64) e retorna BYTES.

Para converter de BYTES para uma matriz de pontos de código, consulte TO_CODE_POINTS.

Tipo de retorno

BYTES

Exemplos

Veja a seguir um exemplo básico usando CODE_POINTS_TO_BYTES.

SELECT CODE_POINTS_TO_BYTES([65, 98, 67, 100]) AS bytes;

-- Note that the result of CODE_POINTS_TO_BYTES is of type BYTES, displayed as a base64-encoded string.
-- In BYTES format, b'AbCd' is the result.
+----------+
| bytes    |
+----------+
| QWJDZA== |
+----------+

O exemplo a seguir utiliza um algoritmo ROT13 (rotacionar 13 posições) para codificar uma string.

SELECT CODE_POINTS_TO_BYTES(ARRAY(
  (SELECT
      CASE
        WHEN chr BETWEEN b'a' AND b'z'
          THEN TO_CODE_POINTS(b'a')[offset(0)] +
            MOD(code + 13 - TO_CODE_POINTS(b'a')[offset(0)],26)
        WHEN chr BETWEEN b'A' AND b'Z'
          THEN TO_CODE_POINTS(b'A')[offset(0)] +
            MOD(code + 13 - TO_CODE_POINTS(b'A')[offset(0)],26)
        ELSE code
      END
   FROM
     (SELECT code, CODE_POINTS_TO_BYTES(ARRAY[code]) AS chr
      FROM UNNEST(TO_CODE_POINTS(input)) AS code WITH OFFSET
      ORDER BY OFFSET)
   ))) AS encoded_string
FROM UNNEST(ARRAY['Test String!']) AS input;

-- Note that the result of CODE_POINTS_TO_BYTES is of type BYTES, displayed as a base64-encoded string.
-- In BYTES format, b'Grfg Fgevat!' is the result.
+------------------+
| encoded_string   |
+------------------+
| R3JmZyBGZ2V2YXQh |
+------------------+

CODE_POINTS_TO_STRING

CODE_POINTS_TO_STRING(value)

Descrição

Usa uma matriz de pontos de código (em inglês) Unicode (ARRAY de INT64) e retorna um STRING. Se um ponto de código for 0, não será retornado um caractere para ele na STRING.

Para converter uma string em uma matriz de pontos de código, consulte TO_CODE_POINTS.

Tipo de retorno

STRING

Exemplos

Veja a seguir exemplos básicos usando CODE_POINTS_TO_STRING.

SELECT CODE_POINTS_TO_STRING([65, 255, 513, 1024]) AS string;

+--------+
| string |
+--------+
| AÿȁЀ   |
+--------+

SELECT CODE_POINTS_TO_STRING([97, 0, 0xF9B5]) AS string;

+--------+
| string |
+--------+
| a例    |
+--------+

SELECT CODE_POINTS_TO_STRING([65, 255, NULL, 1024]) AS string;

+--------+
| string |
+--------+
| NULL   |
+--------+

O exemplo a seguir calcula a frequência das letras em um grupo de palavras.

WITH Words AS (
  SELECT word
  FROM UNNEST(['foo', 'bar', 'baz', 'giraffe', 'llama']) AS word
)
SELECT
  CODE_POINTS_TO_STRING([code_point]) AS letter,
  COUNT(*) AS letter_count
FROM Words,
  UNNEST(TO_CODE_POINTS(word)) AS code_point
GROUP BY 1
ORDER BY 2 DESC;

+--------+--------------+
| letter | letter_count |
+--------+--------------+
| a      | 5            |
| f      | 3            |
| r      | 2            |
| b      | 2            |
| l      | 2            |
| o      | 2            |
| g      | 1            |
| z      | 1            |
| e      | 1            |
| m      | 1            |
| i      | 1            |
+--------+--------------+

CONCAT

CONCAT(value1[, ...])

Descrição

Concatena um ou mais valores STRING ou BYTE em um único resultado.

A função retornará NULL se algum argumento de entrada for NULL.

Tipo de retorno

STRING ou BYTES

Exemplos

SELECT CONCAT("T.P.", " ", "Bar") as author;

+---------------------+
| author              |
+---------------------+
| T.P. Bar            |
+---------------------+


With Employees AS
  (SELECT
    "John" AS first_name,
    "Doe" AS last_name
  UNION ALL
  SELECT
    "Jane" AS first_name,
    "Smith" AS last_name
  UNION ALL
  SELECT
    "Joe" AS first_name,
    "Jackson" AS last_name)

SELECT
  CONCAT(first_name, " ", last_name)
  AS full_name
FROM Employees;

+---------------------+
| full_name           |
+---------------------+
| John Doe            |
| Jane Smith          |
| Joe Jackson         |
+---------------------+

ENDS_WITH

ENDS_WITH(value1, value2)

Descrição

Utiliza dois valores STRING ou BYTES. Retorna TRUE se o segundo valor for um sufixo do primeiro.

Tipo de retorno

BOOL

Exemplos

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  ENDS_WITH(item, "e") as example
FROM items;

+---------+
| example |
+---------+
|    True |
|   False |
|    True |
+---------+

FORMAT

O Cloud Spanner SQL é compatível com FORMAT() para formatação de strings. Essa função é semelhante à função C printf. Ela produz uma STRING a partir de uma string de formato que contém zero ou mais especificadores de formato e uma lista de comprimentos variáveis de argumentos extras que correspondem aos especificadores. Veja alguns exemplos:

Descrição Instrução Resultado
Inteiro simples FORMAT("%d", 10) 10
Inteiro com preenchimento vazio à esquerda FORMAT("|%10d|", 11) |           11|
Inteiro com preenchimento com zero à esquerda FORMAT("+%010d+", 12) +0000000012+
Inteiro com vírgulas FORMAT("%'d", 123456789) 123,456,789
STRING FORMAT("-%s-", 'abcd efg') -abcd efg-
FLOAT64 FORMAT("%f %E", 1.1, 2.2) 1.100000 2.200000E+00
DATA FORMAT("%t", date "2015-09-01") 2015-09-01
TIMESTAMP FORMAT("%t", timestamp "2015-09-01 12:34:56 America/Los_Angeles") 2015‑09‑01 19:34:56+00

A função FORMAT() não oferece formato totalmente personalizável para todos os tipos e valores, nem formato sensível à localidade.

Se o formato personalizado for necessário para um tipo, primeiro formate-o usando as funções específicas do tipo, como FORMAT_DATE() ou FORMAT_TIMESTAMP(). Exemplo:

SELECT FORMAT("date: %s!", FORMAT_DATE("%B %d, %Y", date '2015-01-02'));

Retorna

date: January 02, 2015!

Sintaxe

A sintaxe FORMAT() usa uma lista de strings de formato e comprimentos variáveis dos argumentos e produz um resultado STRING:

FORMAT(format_string, ...)

A expressão format_string pode conter zero ou mais especificadores de formato. Cada especificador de formato é introduzido pelo símbolo % e precisa ser mapeado para um ou mais dos argumentos restantes. Em geral, esse é um mapeamento um para um, exceto quando o especificador * está presente. Por exemplo, %.*i realiza o mapeamento para dois argumentos: um de comprimento e um de número inteiro com sinal. Se o número de argumentos relacionados com os especificadores de formato não for o mesmo número de argumentos, ocorrerá um erro.

Especificadores de formatos compatíveis

O especificador de formato da função FORMAT() segue este protótipo:

%[flags][width][.precision]specifier

Os especificadores de formatos compatíveis são identificados na tabela a seguir. Os desvios de printf() são identificados em itálico.

Especificador Descrição Exemplos Tipos
d ou i Decimal inteiro. 392 INT64
o Octal 610
INT64*
x Inteiro hexadecimal 7fa
INT64*
X Inteiro hexadecimal (maiúsculas) 7FA
INT64*
f Notação decimal, em [-](parte inteira).(parte fracionária) para valores finitos e em minúsculas para valores não finitos 392.650000
inf
nan		 NUMERIC
FLOAT64
F Notação decimal, em [-](parte inteira).(parte fracionária) para valores finitos e em maiúsculas para valores não finitos 392.650000
INF
NAN		 NUMERIC
FLOAT64
e Notação científica (mantissa/expoente), minúsculas 3,926500e+02
inf
nan		 NUMERIC
FLOAT64
E Notação científica (mantissa/expoente), maiúsculas 3,926500E+02
INF
NAN		 NUMERIC
FLOAT64
g Notação decimal ou notação científica, dependendo do expoente do valor de entrada e da precisão especificada. Minúscula. Consulte Comportamento de%g e %G para detalhes. 392,65
3,9265e+07
inf
nan		 NUMERIC
FLOAT64
G Notação decimal ou notação científica, dependendo do expoente do valor de entrada e da precisão especificada. Maiúscula. Consulte Comportamento de%g e %G para detalhes. 392.65
3.9265E+07
INF
NAN 		NUMERIC
FLOAT64
s String de caracteres amostra STRING
t Retorna uma string para impressão que representa o valor. Geralmente é semelhante a fazer o cast do argumento para STRING. Consulte Comportamento de %t e %T. amostra
2014‑01‑01 		<any>
T Produz uma string que é uma constante válida do Cloud Spanner SQL, com um tipo semelhante ao do valor (talvez mais amplo ou string). Consulte Comportamento de %t e %T. 'amostra'
amostra b'bytes '
1234
2.3
data '2014‑01‑01' 		<any>
% '%%' produz um único '%' % n/a

* Os especificadores %o, %x e %X geram um erro se valores negativos forem usados.

O formato do especificador também pode conter os subespecificadores identificados acima no protótipo do especificador.

Esses subespecificadores precisam seguir estas especificações.

Sinalizações
Sinalizações Descrição
- Justificada à esquerda dentro da largura do campo. O padrão é a justificação à direita (informe-se sobre subespecificador de largura).
+ Força o resultado a ser precedido por um sinal de mais ou menos (+ ou -), mesmo para números positivos. Por padrão, apenas os números negativos são precedidos por um sinal -
<space> Se nenhum sinal for gravado, um espaço em branco será inserido antes do valor
#
  • Para "%o", "%x" e "%X", essa sinalização significa preceder valores diferentes de zero com 0, 0x ou 0X, respectivamente.
  • Para "%f", "%F", "%e" e "%E", essa sinalização significa adicionar o ponto decimal mesmo quando não houver parte fracionária, a menos que o valor não seja finito.
  • Para "%g" e "%G", essa sinalização significa adicionar o ponto decimal mesmo quando não houver parte fracionária, a menos que o valor seja não finito e nunca remova os zeros à direita do ponto decimal.
0 Quando o preenchimento é especificado, coloca zeros (0) à esquerda do número, em vez de espaços (consulte sobre subespecificador de largura)
'

Formata inteiros usando o caractere de agrupamento adequado. Exemplo:

  • FORMAT("%'d", 12345678) retorna 12,345,678.
  • FORMAT("%'x", 12345678) retorna bc:614e
  • FORMAT("%'o", 55555) retorna 15,4403

    • Essa sinalização só é relevante para valores decimais, hexadecimais e octais.

As sinalizações podem ser especificadas em qualquer ordem. Sinalizações duplicadas não são um erro. As sinalizações são ignoradas quando não são relevantes para algum tipo de elemento.

Largura
Largura Descrição
<número> O número mínimo de caracteres a ser impresso. Se o valor a ser impresso for mais curto do que esse número, o resultado será preenchido com espaços em branco. O valor não é truncado mesmo que o resultado seja maior
* A largura não é especificada na string de formato, mas como um argumento de valor inteiro complementar precedendo o argumento que precisa ser formatado
Precisão
Precisão Descrição
.<number>
  • Para especificadores inteiros "%d", "%i", "%o", "%u", "%x" e "%X": a precisão especifica o número mínimo de dígitos a serem gravados. Se o valor a ser gravado for menor que esse número, o resultado será preenchido com zeros à direita. O valor não será truncado mesmo que o resultado seja maior. Uma precisão de 0 significa que nenhum caractere é gravado para o valor 0.
  • Para os especificadores "%a", "%A", "%e", "%E", "%f" e "%F": esse é o número de dígitos a serem impressos após o ponto decimal. O valor padrão é 6.
  • Para especificadores "%g" e "%G": este é o número de dígitos significativos a serem impressos, antes da remoção dos zeros à direita após o ponto decimal. O valor padrão é 6.
.* A precisão não é especificada na string de formato, mas como um argumento de valor inteiro extra precedendo o argumento que precisa ser formatado.

Comportamento de %g e %G

Os especificadores de formato %g e %G escolhem a notação decimal (como os especificadores %f e %F) ou a notação científica (como os especificadores %e e %E), dependendo do expoente do valor de entrada e da precisão especificada.

Deixe p representar a precisão especificada (o padrão é 6; mas será 1 se a precisão especificada for menor que 1). O valor de entrada é convertido primeiro em notação científica com precisão = (p - 1). Se a parte x do expoente resultante for menor que -4 ou menor que p, a notação científica com precisão = (p - 1) será usada. Caso contrário, a notação decimal com precisão = (p - 1 - x) é usada.

A menos que a sinalização # esteja presente, os zeros à direita após a vírgula decimal serão removidos, e a vírgula decimal também será removida se não houver um dígito depois dela.

Comportamento de %t e %T

Os especificadores de formato %t e %T são definidos para todos os tipos. A largura, a precisão e as sinalizações agem da mesma forma que para %s: a largura é a largura mínima e a STRING será preenchida com esse tamanho. Precisão é a largura máxima do conteúdo a ser exibido e a STRING será truncada com esse tamanho, antes de preencher a largura.

O especificador %t é sempre uma forma legível do valor.

O especificador %T é sempre um literal SQL válido de um tipo semelhante, como um tipo numérico mais amplo. O literal não inclui casts ou um nome de tipo, exceto no caso especial de valores de ponto flutuante não finitos.

O STRING é formatado da seguinte forma:

Tipo %t %T
NULL de qualquer tipo NULL NULL
INT64
 123 123
NUMERIC 123.0 (sempre com .0)NUMERIC "123,0"
FLOAT64 123.0 (sempre com .0)
123e+10
inf
-inf
NaN 		123.0 (sempre com .0)
123e+10
CAST("inf" AS <type>)
CAST("-inf" AS <type>)
CAST("nan" AS <type>)
STRING valor da string sem aspas literal da string com aspas
BYTES bytes escapados sem aspas
por exemplo, abc\x01\x02 		bytes literais com aspas
por exemplo, b"abc\x01\x02"
DATA 2011-02-03 DATE "2011-02-03"
TIMESTAMP 2011-02-03 04:05:06+00 TIMESTAMP "2011-02-03 04:05:06+00"
ARRAY [valor, valor, ...]
onde os valores são formatados com %t		 [valor, valor, ...]
onde os valores são formatados com %T

Condições de erro

Se um especificador de formato for inválido ou não compatível com o tipo de argumento relacionado, ou forem fornecidos o número ou os argumentos incorretos, ocorrerá um erro. Por exemplo, as seguintes expressões <format_string> são inválidas:

FORMAT('%s', 1)

FORMAT('%')

Tratamento do argumento NULL

Uma string de formato NULL resulta em uma saída STRING NULL. Outros argumentos são ignorados, neste caso.

Em geral, a função produz um valor NULL se um argumento NULL estiver presente. Por exemplo, FORMAT('%i', NULL_expression) produz um NULL STRING como saída.

No entanto, há algumas exceções: se o especificador de formato for %t ou %T (que produzem STRINGs que efetivamente correspondem à semântica do valor literal e CAST), um valor NULL produzirá 'NULL' (sem as aspas) na STRING do resultado. Por exemplo, a função:

FORMAT('00-%t-00', NULL_expression);

Retorna

00-NULL-00

Outras regras semânticas

Os valores FLOAT64 podem ser +/-inf ou NaN. Quando um argumento tem um desses valores, o resultado dos especificadores de formato %f, %F, %e, %E, %g, %G e %t são inf, -inf ou nan (ou o mesmo em maiúsculas), conforme apropriado. Isso é consistente com a forma como o Cloud Spanner SQL faz o cast desses valores para STRING. Para %T, o Cloud Spanner SQL retorna strings entre aspas para valores FLOAT64 que não têm representações literais que não sejam de string.

FROM_BASE32

FROM_BASE32(string_expr)

Descrição

Converte no formato BYTES a entrada codificada em base32 string_expr. Para converter BYTES em uma STRING codificada em base32, use TO_BASE32.

Tipo de retorno

BYTES

Exemplo

SELECT FROM_BASE32('MFRGGZDF74======') AS byte_data;

-- Note that the result of FROM_BASE32 is of type BYTES, displayed as a base64-encoded string.
+-----------+
| byte_data |
+-----------+
| YWJjZGX/  |
+-----------+

FROM_BASE64

FROM_BASE64(string_expr)

Descrição

Converte no formato BYTES a entrada string_expr codificada em base64. Para converter BYTES em uma STRING codificada em base64, use TO_BASE64.

Tipo de retorno

BYTES

Exemplo

SELECT FROM_BASE64('3q2+7w==') AS byte_data;

-- Note that the result of FROM_BASE64 is of type BYTES, displayed as a base64-encoded string.
+-----------+
| byte_data |
+-----------+
| 3q2+7w==  |
+-----------+

FROM_HEX

FROM_HEX(string)

Descrição

Converte um STRING codificado em hexadecimal em formato BYTES. Retorna um erro se a STRING de entrada contiver caracteres fora do intervalo (0..9, A..F, a..f). Não importa se os caracteres estão em maiúsculas ou minúsculas. Se a entrada STRING tiver um número ímpar de caracteres, a função age como se a entrada tivesse um 0 à esquerda. Para converter BYTES em uma STRING codificada em hexadecimal, use TO_HEX.

Tipo de retorno

BYTES

Exemplo

WITH Input AS (
  SELECT '00010203aaeeefff' AS hex_str UNION ALL
  SELECT '0AF' UNION ALL
  SELECT '666f6f626172'
)
SELECT hex_str, FROM_HEX(hex_str) AS bytes_str
FROM Input;

-- Note that the result of FROM_HEX is of type BYTES, displayed as a base64-encoded string.
+------------------+--------------+
| hex_str          | bytes_str    |
+------------------+--------------+
| 0AF              | AAECA6ru7/8= |
| 00010203aaeeefff | AK8=         |
| 666f6f626172     | Zm9vYmFy     |
+------------------+--------------+

LENGTH

LENGTH(value)

Descrição

Retorna o comprimento do valor STRING ou BYTES. O valor retornado está em caracteres para argumentos STRING e em bytes para o argumento BYTES.

Tipo de retorno

INT64

Exemplos


WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  LENGTH(characters) AS string_example,
  LENGTH(CAST(characters AS BYTES)) AS bytes_example
FROM example;

+------------+----------------+---------------+
| characters | string_example | bytes_example |
+------------+----------------+---------------+
| абвгд      |              5 |            10 |
+------------+----------------+---------------+

LPAD

LPAD(original_value, return_length[, pattern])

Descrição

Retorna um valor STRING ou BYTES que consiste em original_value precedido por pattern. O return_length é um INT64 que especifica o comprimento do valor retornado. Se original_value for do tipo BYTES, return_length será o número de bytes. Se original_value for do tipo STRING, return_length será o número de caracteres.

O valor padrão de pattern é um espaço em branco.

Tanto original_value quanto pattern precisam ser do mesmo tipo de dados.

Se return_length for menor ou igual ao comprimento de original_value, essa função retornará o valor original_value, truncado para o valor de return_length. Por exemplo, LPAD("hello world", 7); retorna "hello w".

Se original_value, return_length ou pattern for NULL, essa função retornará NULL.

Essa função retornará um erro se:

  • return_length for negativo;
  • pattern estiver vazio.

Tipo de retorno

STRING ou BYTES

Exemplos

SELECT t, len, FORMAT("%T", LPAD(t, len)) AS LPAD FROM UNNEST([
  STRUCT('abc' AS t, 5 AS len),
  ('abc', 2),
  ('例子', 4)
]);

+------+-----+----------+
| t    | len | LPAD     |
|------|-----|----------|
| abc  | 5   | "  abc"  |
| abc  | 2   | "ab"     |
| 例子  | 4   | "  例子" |
+------+-----+----------+

SELECT t, len, pattern, FORMAT("%T", LPAD(t, len, pattern)) AS LPAD FROM UNNEST([
  STRUCT('abc' AS t, 8 AS len, 'def' AS pattern),
  ('abc', 5, '-'),
  ('例子', 5, '中文')
]);

+------+-----+---------+--------------+
| t    | len | pattern | LPAD         |
|------|-----|---------|--------------|
| abc  | 8   | def     | "defdeabc"   |
| abc  | 5   | -       | "--abc"      |
| 例子  | 5   | 中文    | "中文中例子"   |
+------+-----+---------+--------------+

SELECT FORMAT("%T", t) AS t, len, FORMAT("%T", LPAD(t, len)) AS LPAD FROM UNNEST([
  STRUCT(b'abc' AS t, 5 AS len),
  (b'abc', 2),
  (b'\xab\xcd\xef', 4)
]);

+-----------------+-----+------------------+
| t               | len | LPAD             |
|-----------------|-----|------------------|
| b"abc"          | 5   | b"  abc"         |
| b"abc"          | 2   | b"ab"            |
| b"\xab\xcd\xef" | 4   | b" \xab\xcd\xef" |
+-----------------+-----+------------------+

SELECT
  FORMAT("%T", t) AS t,
  len,
  FORMAT("%T", pattern) AS pattern,
  FORMAT("%T", LPAD(t, len, pattern)) AS LPAD
FROM UNNEST([
  STRUCT(b'abc' AS t, 8 AS len, b'def' AS pattern),
  (b'abc', 5, b'-'),
  (b'\xab\xcd\xef', 5, b'\x00')
]);

+-----------------+-----+---------+-------------------------+
| t               | len | pattern | LPAD                    |
|-----------------|-----|---------|-------------------------|
| b"abc"          | 8   | b"def"  | b"defdeabc"             |
| b"abc"          | 5   | b"-"    | b"--abc"                |
| b"\xab\xcd\xef" | 5   | b"\x00" | b"\x00\x00\xab\xcd\xef" |
+-----------------+-----+---------+-------------------------+

LOWER

LOWER(value)

Descrição

Para argumentos STRING, retorna a string original com todos os caracteres alfabéticos em minúsculas. O mapeamento entre maiúsculas e minúsculas é feito de acordo com o banco de dados de caracteres Unicode. Os mapeamentos específicos do idioma não são considerados.

Para argumentos BYTES, o argumento é tratado como texto ASCII, com todos os bytes superiores a 127 intactos.

Tipo de retorno

STRING ou BYTES

Exemplos


WITH items AS
  (SELECT
    "FOO" as item
  UNION ALL
  SELECT
    "BAR" as item
  UNION ALL
  SELECT
    "BAZ" as item)

SELECT
  LOWER(item) AS example
FROM items;

+---------+
| example |
+---------+
| foo     |
| bar     |
| baz     |
+---------+

LTRIM

LTRIM(value1[, value2])

Descrição

Idêntico a TRIM, mas remove apenas os caracteres iniciais.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH items AS
  (SELECT "   apple   " as item
  UNION ALL
  SELECT "   banana   " as item
  UNION ALL
  SELECT "   orange   " as item)

SELECT
  CONCAT("#", LTRIM(item), "#") as example
FROM items;

+-------------+
| example     |
+-------------+
| #apple   #  |
| #banana   # |
| #orange   # |
+-------------+

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  LTRIM(item, "*") as example
FROM items;

+-----------+
| example   |
+-----------+
| apple***  |
| banana*** |
| orange*** |
+-----------+

WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)

SELECT
  LTRIM(item, "xyz") as example
FROM items;

+-----------+
| example   |
+-----------+
| applexxx  |
| bananayyy |
| orangezzz |
| pearxyz   |
+-----------+

REGEXP_CONTAINS

REGEXP_CONTAINS(value, regexp)

Descrição

Retorna TRUE se value for uma correspondência parcial para a expressão regular, regexp.

Se o argumento regexp for inválido, a função retornará um erro.

É possível pesquisar uma correspondência total usando ^ (início do texto) e $ (fim do texto). Devido à precedência do operador de expressão regular, é recomendável usar parênteses em torno de tudo entre ^ e $.

Tipo de retorno

BOOL

Exemplos

SELECT
  email,
  REGEXP_CONTAINS(email, r"@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+") AS is_valid
FROM
  (SELECT
    ["foo@example.com", "bar@example.org", "www.example.net"]
    AS addresses),
  UNNEST(addresses) AS email;

+-----------------+----------+
| email           | is_valid |
+-----------------+----------+
| foo@example.com | true     |
| bar@example.org | true     |
| www.example.net | false    |
+-----------------+----------+

# Performs a full match, using ^ and $. Due to regular expression operator
# precedence, it is good practice to use parentheses around everything between ^
# and $.
SELECT
  email,
  REGEXP_CONTAINS(email, r"^([\w.+-]+@foo\.com|[\w.+-]+@bar\.org)$")
    AS valid_email_address,
  REGEXP_CONTAINS(email, r"^[\w.+-]+@foo\.com|[\w.+-]+@bar\.org$")
    AS without_parentheses
FROM
  (SELECT
    ["a@foo.com", "a@foo.computer", "b@bar.org", "!b@bar.org", "c@buz.net"]
    AS addresses),
  UNNEST(addresses) AS email;

+----------------+---------------------+---------------------+
| email          | valid_email_address | without_parentheses |
+----------------+---------------------+---------------------+
| a@foo.com      | true                | true                |
| a@foo.computer | false               | true                |
| b@bar.org      | true                | true                |
| !b@bar.org     | false               | true                |
| c@buz.net      | false               | false               |
+----------------+---------------------+---------------------+

REGEXP_EXTRACT

REGEXP_EXTRACT(value, regexp)

Descrição

Retorna a primeira substring em value que corresponde à expressão regular, regexp. Retorna NULL se não houver correspondência.

Se a expressão regular contiver um grupo de captura, a função retornará a substring que corresponde a esse grupo. Se a expressão não contiver um grupo de captura, a função retornará toda a substring correspondente.

Retorna um erro se:

  • a expressão regular for inválida;
  • a expressão regular tiver mais de um grupo de captura.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH email_addresses AS
  (SELECT "foo@example.com" as email
  UNION ALL
  SELECT "bar@example.org" as email
  UNION ALL
  SELECT "baz@example.net" as email)

SELECT
  REGEXP_EXTRACT(email, r"^[a-zA-Z0-9_.+-]+")
  AS user_name
FROM email_addresses;

+-----------+
| user_name |
+-----------+
| foo       |
| bar       |
| baz       |
+-----------+

WITH email_addresses AS
  (SELECT "foo@example.com" as email
  UNION ALL
  SELECT "bar@example.org" as email
  UNION ALL
  SELECT "baz@example.net" as email)

SELECT
  REGEXP_EXTRACT(email, r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.([a-zA-Z0-9-.]+$)")
  AS top_level_domain
FROM email_addresses;

+------------------+
| top_level_domain |
+------------------+
| com              |
| org              |
| net              |
+------------------+

REGEXP_EXTRACT_ALL

REGEXP_EXTRACT_ALL(value, regexp)

Descrição

Retorna uma matriz de todas as substrings de value que correspondem à expressão regular, regexp.

A função REGEXP_EXTRACT_ALL retorna apenas as correspondências não sobrepostas. Por exemplo, o uso dessa função para extrair ana de banana retorna apenas uma substring, não duas.

Tipo de retorno

Uma ARRAY de STRINGs ou BYTES.

Exemplos

WITH code_markdown AS
  (SELECT "Try `function(x)` or `function(y)`" as code)

SELECT
  REGEXP_EXTRACT_ALL(code, "`(.+?)`") AS example
FROM code_markdown;

+----------------------------+
| example                    |
+----------------------------+
| [function(x), function(y)] |
+----------------------------+

REGEXP_REPLACE

REGEXP_REPLACE(value, regexp, replacement)

Descrição

Retorna uma STRING em que todas as substrings de value que correspondem à expressão regular regexp são substituídas por replacement.

Use dígitos de escape com barra invertida (\1 a \9) no argumento replacement para inserir um texto correspondente ao grupo entre parênteses no padrão regexp. Use \0 para indicar o texto correspondente inteiro.

A função REGEXP_REPLACE substitui apenas as correspondências não sobrepostas. Por exemplo, substituir ana em banana resulta em apenas uma substituição, não duas.

Se o argumento regexp não for uma expressão regular válida, essa função retornará um erro.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH markdown AS
  (SELECT "# Heading" as heading
  UNION ALL
  SELECT "# Another heading" as heading)

SELECT
  REGEXP_REPLACE(heading, r"^# ([a-zA-Z0-9\s]+$)", "<h1>\\1</h1>")
  AS html
FROM markdown;

+--------------------------+
| html                     |
+--------------------------+
| <h1>Heading</h1>         |
| <h1>Another heading</h1> |
+--------------------------+

REPLACE

REPLACE(original_value, from_value, to_value)

Descrição

Substitui todas as ocorrências de from_value por to_value em original_value. Se from_value estiver vazio, nenhuma substituição será feita.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH desserts AS
  (SELECT "apple pie" as dessert
  UNION ALL
  SELECT "blackberry pie" as dessert
  UNION ALL
  SELECT "cherry pie" as dessert)

SELECT
  REPLACE (dessert, "pie", "cobbler") as example
FROM desserts;

+--------------------+
| example            |
+--------------------+
| apple cobbler      |
| blackberry cobbler |
| cherry cobbler     |
+--------------------+

REPEAT

REPEAT(original_value, repetitions)

Descrição

Retorna um valor STRING ou BYTES que consiste em original_value repetido. O parâmetro repetitions especifica o número de vezes para repetir original_value. Retorna NULL se original_value ou repetitions forem NULL.

Essa função retornará um erro se o valor repetitions for negativo.

Tipo de retorno

STRING ou BYTES

Exemplos

SELECT t, n, REPEAT(t, n) AS REPEAT FROM UNNEST([
  STRUCT('abc' AS t, 3 AS n),
  ('例子', 2),
  ('abc', null),
  (null, 3)
]);

+------+------+-----------+
| t    | n    | REPEAT    |
|------|------|-----------|
| abc  | 3    | abcabcabc |
| 例子 | 2    | 例子例子  |
| abc  | NULL | NULL      |
| NULL | 3    | NULL      |
+------+------+-----------+

INVERSO

REVERSE(value)

Descrição

Retorna o inverso de entrada STRING ou BYTES.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH example AS (
  SELECT "foo" AS sample_string, b"bar" AS sample_bytes UNION ALL
  SELECT "абвгд" AS sample_string, b"123" AS sample_bytes
)
SELECT
  sample_string,
  REVERSE(sample_string) AS reverse_string,
  sample_bytes,
  REVERSE(sample_bytes) AS reverse_bytes
FROM example;

+---------------+----------------+--------------+---------------+
| sample_string | reverse_string | sample_bytes | reverse_bytes |
+---------------+----------------+--------------+---------------+
| foo           | oof            | bar          | rab           |
| абвгд         | дгвба          | 123          | 321           |
+---------------+----------------+--------------+---------------+

RPAD

RPAD(original_value, return_length[, pattern])

Descrição

Retorna um valor STRING ou BYTES que consiste em original_value anexado a pattern. O parâmetro return_length é um INT64 que especifica o comprimento do valor retornado. Se original_value for BYTES, return_length é o número de bytes. Se original_value for STRING, return_length será o número de caracteres.

O valor padrão de pattern é um espaço em branco.

Tanto original_value quanto pattern precisam ser do mesmo tipo de dados.

Se return_length for menor ou igual ao comprimento de original_value, essa função retornará o valor original_value, truncado para o valor de return_length. Por exemplo, RPAD("hello world", 7); retorna "hello w".

Se original_value, return_length ou pattern for NULL, essa função retornará NULL.

Essa função retornará um erro se:

  • return_length for negativo;
  • pattern estiver vazio.

Tipo de retorno

STRING ou BYTES

Exemplos

SELECT t, len, FORMAT("%T", RPAD(t, len)) AS RPAD FROM UNNEST([
  STRUCT('abc' AS t, 5 AS len),
  ('abc', 2),
  ('例子', 4)
]);

+------+-----+----------+
| t    | len | RPAD     |
|------|-----|----------|
| abc  | 5   | "abc  "  |
| abc  | 2   | "ab"     |
| 例子  | 4   | "例子  " |
+------+-----+----------+

SELECT t, len, pattern, FORMAT("%T", RPAD(t, len, pattern)) AS RPAD FROM UNNEST([
  STRUCT('abc' AS t, 8 AS len, 'def' AS pattern),
  ('abc', 5, '-'),
  ('例子', 5, '中文')
]);

+------+-----+---------+--------------+
| t    | len | pattern | RPAD         |
|------|-----|---------|--------------|
| abc  | 8   | def     | "abcdefde"   |
| abc  | 5   | -       | "abc--"      |
| 例子  | 5   | 中文     | "例子中文中"  |
+------+-----+---------+--------------+

SELECT FORMAT("%T", t) AS t, len, FORMAT("%T", RPAD(t, len)) AS RPAD FROM UNNEST([
  STRUCT(b'abc' AS t, 5 AS len),
  (b'abc', 2),
  (b'\xab\xcd\xef', 4)
]);

+-----------------+-----+------------------+
| t               | len | RPAD             |
|-----------------|-----|------------------|
| b"abc"          | 5   | b"abc  "         |
| b"abc"          | 2   | b"ab"            |
| b"\xab\xcd\xef" | 4   | b"\xab\xcd\xef " |
+-----------------+-----+------------------+

SELECT
  FORMAT("%T", t) AS t,
  len,
  FORMAT("%T", pattern) AS pattern,
  FORMAT("%T", RPAD(t, len, pattern)) AS RPAD
FROM UNNEST([
  STRUCT(b'abc' AS t, 8 AS len, b'def' AS pattern),
  (b'abc', 5, b'-'),
  (b'\xab\xcd\xef', 5, b'\x00')
]);

+-----------------+-----+---------+-------------------------+
| t               | len | pattern | RPAD                    |
|-----------------|-----|---------|-------------------------|
| b"abc"          | 8   | b"def"  | b"abcdefde"             |
| b"abc"          | 5   | b"-"    | b"abc--"                |
| b"\xab\xcd\xef" | 5   | b"\x00" | b"\xab\xcd\xef\x00\x00" |
+-----------------+-----+---------+-------------------------+

RTRIM

RTRIM(value1[, value2])

Descrição

Idêntico a TRIM, mas remove somente caracteres finais.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  RTRIM(item, "*") as example
FROM items;

+-----------+
| example   |
+-----------+
| ***apple  |
| ***banana |
| ***orange |
+-----------+

WITH items AS
  (SELECT "applexxx" as item
  UNION ALL
  SELECT "bananayyy" as item
  UNION ALL
  SELECT "orangezzz" as item
  UNION ALL
  SELECT "pearxyz" as item)

SELECT
  RTRIM(item, "xyz") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
| pear    |
+---------+

SAFE_CONVERT_BYTES_TO_STRING

SAFE_CONVERT_BYTES_TO_STRING(value)

Descrição

Converte uma sequência de BYTES em um STRING. Todos os caracteres UTF-8 inválidos são substituídos pelo caractere de substituição Unicode, U+FFFD.

Tipo de retorno

STRING

Exemplos

A declaração a seguir retorna o caractere de substituição Unicode �.

SELECT SAFE_CONVERT_BYTES_TO_STRING(b'\xc2') as safe_convert;

SPLIT

SPLIT(value[, delimiter])

Descrição

Divide value usando o argumento delimiter.

Para STRING, o delimitador padrão é a vírgula ,.

Para BYTES, especifique um delimitador.

A divisão em um delimitador vazio produz uma matriz de caracteres UTF-8 para valores STRING, e uma matriz de BYTES para valores BYTES.

A divisão de uma STRING vazia retorna uma ARRAY com uma única STRING vazia.

Tipo de retorno

ARRAY do tipo STRING ou ARRAY do tipo BYTES

Exemplos

WITH letters AS
  (SELECT "" as letter_group
  UNION ALL
  SELECT "a" as letter_group
  UNION ALL
  SELECT "b c d" as letter_group)

SELECT SPLIT(letter_group, " ") as example
FROM letters;

+----------------------+
| example              |
+----------------------+
| []                   |
| [a]                  |
| [b, c, d]            |
+----------------------+

STARTS_WITH

STARTS_WITH(value1, value2)

Descrição

Utiliza dois valores STRING ou BYTES. Retorna TRUE se o segundo valor for um prefixo do primeiro.

Tipo de retorno

BOOL

Exemplos

WITH items AS
  (SELECT "foo" as item
  UNION ALL
  SELECT "bar" as item
  UNION ALL
  SELECT "baz" as item)

SELECT
  STARTS_WITH(item, "b") as example
FROM items;

+---------+
| example |
+---------+
|   False |
|    True |
|    True |
+---------+

STRPOS

STRPOS(string, substring)

Descrição

Retorna o índice com base em 1 da primeira ocorrência de substring em string. Retorna 0 se substring não for encontrado.

Tipo de retorno

INT64

Exemplos

WITH email_addresses AS
  (SELECT
    "foo@example.com" AS email_address
  UNION ALL
  SELECT
    "foobar@example.com" AS email_address
  UNION ALL
  SELECT
    "foobarbaz@example.com" AS email_address
  UNION ALL
  SELECT
    "quxexample.com" AS email_address)

SELECT
  STRPOS(email_address, "@") AS example
FROM email_addresses;

+---------+
| example |
+---------+
|       4 |
|       7 |
|      10 |
|       0 |
+---------+

SUBSTR

SUBSTR(value, position[, length])

Descrição

Retorna uma substring do valor STRING ou BYTES fornecido. O argumento position é um número inteiro que especifica a posição inicial da substring, com posição = 1 indicando o primeiro caractere ou byte. O argumento length é o número máximo de caracteres para argumentos STRING ou de bytes para argumentos BYTES.

Se position for negativo, a função contará a partir do final de value, com -1 indicando o último caractere.

Se position for uma posição fora do lado esquerdo de STRING (position = 0 ou position < -LENGTH(value)), a função começará a partir da posição = 1. Se length exceder o comprimento de value, a função retornará menos que length caracteres.

Se length for menor que zero, a função retornará um erro.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, 2) as example
FROM items;

+---------+
| example |
+---------+
| pple    |
| anana   |
| range   |
+---------+

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, 2, 2) as example
FROM items;

+---------+
| example |
+---------+
| pp      |
| an      |
| ra      |
+---------+

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, -2) as example
FROM items;

+---------+
| example |
+---------+
| le      |
| na      |
| ge      |
+---------+

TO_BASE32

TO_BASE32(bytes_expr)

Descrição

Converte uma sequência de BYTES em um STRING codificado em base32. Para converter uma STRING codificada em base32 em BYTES, use FROM_BASE32.

Tipo de retorno

STRING

Exemplo

SELECT TO_BASE32(b'abcde\xFF') AS base32_string;

+------------------+
| base32_string    |
+------------------+
| MFRGGZDF74====== |
+------------------+

TO_BASE64

TO_BASE64(bytes_expr)

Descrição

Converte uma sequência de BYTES em um STRING codificado em base64. Para converter uma STRING codificada em base64 em BYTES, use FROM_BASE64.

Tipo de retorno

STRING

Exemplo

SELECT TO_BASE64(b'\xde\xad\xbe\xef') AS base64_string;

+---------------+
| base64_string |
+---------------+
| 3q2+7w==      |
+---------------+

TO_CODE_POINTS

TO_CODE_POINTS(value)

Descrição

Usa um valor e retorna uma matriz de INT64.

  • Se value for uma STRING, cada elemento na matriz retornada representará um ponto de código (em inglês). Cada ponto de código está dentro do intervalo de [0, 0xD7FF] e [0xE000, 0x10FFFF].
  • Se value for BYTES, cada elemento na matriz será um valor de caractere ASCII estendido no intervalo de [0, 255].

Para converter uma matriz de pontos de código em STRING ou em BYTES, consulte CODE_POINTS_TO_STRING ou CODE_POINTS_TO_BYTES.

Tipo de retorno

ARRAY de INT64

Exemplos

O exemplo a seguir mostra os pontos de código de cada elemento em uma matriz de palavras.

SELECT word, TO_CODE_POINTS(word) AS code_points
FROM UNNEST(['foo', 'bar', 'baz', 'giraffe', 'llama']) AS word;

+---------+------------------------------------+
| word    | code_points                        |
+---------+------------------------------------+
| foo     | [102, 111, 111]                    |
| bar     | [98, 97, 114]                      |
| baz     | [98, 97, 122]                      |
| giraffe | [103, 105, 114, 97, 102, 102, 101] |
| llama   | [108, 108, 97, 109, 97]            |
+---------+------------------------------------+

O exemplo a seguir converte as representações de inteiros de BYTES para os valores de caracteres ASCII correspondentes.

SELECT word, TO_CODE_POINTS(word) AS bytes_value_as_integer
FROM UNNEST([b'\x00\x01\x10\xff', b'\x66\x6f\x6f']) AS word;

+------------------+------------------------+
| word             | bytes_value_as_integer |
+------------------+------------------------+
| \x00\x01\x10\xff | [0, 1, 16, 255]        |
| foo              | [102, 111, 111]        |
+------------------+------------------------+

O exemplo a seguir demonstra a diferença entre os resultados BYTES e STRING.

SELECT TO_CODE_POINTS(b'Ā') AS b_result, TO_CODE_POINTS('Ā') AS s_result;

+------------+----------+
| b_result   | s_result |
+------------+----------+
| [196, 128] | [256]    |
+------------+----------+

O caractere Ā é representado como uma sequência Unicode de dois bytes. Como resultado, a versão BYTES de TO_CODE_POINTS retorna uma matriz com dois elementos, enquanto a versão STRING retorna uma matriz com um único elemento.

TO_HEX

TO_HEX(bytes)

Descrição

Converte uma sequência de BYTES em uma STRING hexadecimal. Converte cada byte na STRING como dois caracteres hexadecimais no intervalo (0..9, a..f). Para converter um STRING codificado em hexadecimal em BYTES, use FROM_HEX.

Tipo de retorno

STRING

Exemplo

WITH Input AS (
  SELECT b'\x00\x01\x02\x03\xAA\xEE\xEF\xFF' AS byte_str UNION ALL
  SELECT b'foobar'
)
SELECT byte_str, TO_HEX(byte_str) AS hex_str
FROM Input;

+----------------------------------+------------------+
| byte_string                      | hex_string       |
+----------------------------------+------------------+
| \x00\x01\x02\x03\xaa\xee\xef\xff | 00010203aaeeefff |
| foobar                           | 666f6f626172     |
+----------------------------------+------------------+

TRIM

TRIM(value1[, value2])

Descrição

Remove todos os caracteres iniciais e finais correspondentes a value2. Se value2 não for especificado, todos os caracteres de espaço em branco iniciais e finais (conforme definido pelo padrão Unicode) são removidos. Se o primeiro argumento for do tipo BYTES, o segundo argumento será obrigatório.

Se value2 tiver mais de um caractere ou byte, a função removerá todos os bytes ou caracteres iniciais ou finais contidos em value2.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH items AS
  (SELECT "   apple   " as item
  UNION ALL
  SELECT "   banana   " as item
  UNION ALL
  SELECT "   orange   " as item)

SELECT
  CONCAT("#", TRIM(item), "#") as example
FROM items;

+----------+
| example  |
+----------+
| #apple#  |
| #banana# |
| #orange# |
+----------+

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  TRIM(item, "*") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
+---------+

WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)

SELECT
  TRIM(item, "xyz") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
| pear    |
+---------+

UPPER

UPPER(value)

Descrição

Para argumentos STRING, retorna a string original com todos os caracteres alfabéticos em maiúsculas. O mapeamento entre maiúsculas e minúsculas é feito de acordo com o banco de dados de caracteres Unicode. Os mapeamentos específicos do idioma não são considerados.

Para argumentos BYTES, o argumento é tratado como texto ASCII, com todos os bytes superiores a 127 intactos.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH items AS
  (SELECT
    "foo" as item
  UNION ALL
  SELECT
    "bar" as item
  UNION ALL
  SELECT
    "baz" as item)

SELECT
  UPPER(item) AS example
FROM items;

+---------+
| example |
+---------+
| FOO     |
| BAR     |
| BAZ     |
+---------+