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 considerar a equivalência canônica Unicode.

ASCII

ASCII(value)

Descrição

Retorna o código ASCII do primeiro caractere ou byte em value. Retornará 0 se value estiver vazio ou o código ASCII for 0 para o primeiro caractere ou byte.

Tipo de retorno

INT64

Exemplos

SELECT ASCII('abcd') as A, ASCII('a') as B, ASCII('') as C, ASCII(NULL) as D;

+-------+-------+-------+-------+
| A     | B     | C     | D     |
+-------+-------+-------+-------+
| 97    | 97    | 0     | NULL  |
+-------+-------+-------+-------+

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 |
+------------+---------------------+

CHR

CHR(value)

Descrição

Pega um ponto de código Unicode e retorna o caractere que corresponde a esse ponto. Cada ponto de código válido estará dentro do intervalo de [0, 0xD7FF] e [0xE000, 0x10FFFF]. Retornará uma string vazia se o ponto do código for 0. Se um ponto de código Unicode inválido for especificado, um erro será retornado.

Para trabalhar com uma matriz de pontos de código Unicode, consulte CODE_POINTS_TO_STRING

Tipo de retorno

STRING

Exemplos

SELECT CHR(65) AS A, CHR(255) AS B, CHR(513) AS C, CHR(1024)  AS D;

+-------+-------+-------+-------+
| A     | B     | C     | D     |
+-------+-------+-------+-------+
| A     | ÿ     | ȁ     | Ѐ     |
+-------+-------+-------+-------+

SELECT CHR(97) AS A, CHR(0xF9B5) AS B, CHR(0) AS C, CHR(NULL) AS D;

+-------+-------+-------+-------+
| A     | B     | C     | D     |
+-------+-------+-------+-------+
| a     | 例    |       | NULL  |
+-------+-------+-------+-------+

CODE_POINTS_TO_BYTES

CODE_POINTS_TO_BYTES(ascii_code_points)

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_AGG(
  (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([code]) chr)
  ) ORDER BY OFFSET)) AS encoded_string
FROM UNNEST(TO_CODE_POINTS(b'Test String!')) code WITH OFFSET;

-- 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(unicode_code_points)

Descrição

Usa uma matriz de pontos de código (em inglês) Unicode (ARRAY de INT64) e retorna um 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            |
+--------+--------------+

COLLATE

COLLATE(value, collate_specification)

Recebe uma STRING e uma especificação de compilação. Retorna um STRING com uma especificação de compilação. Se collate_specification estiver vazio, retornará um valor com a compilação removida do STRING.

A especificação de compilação define como a STRING resultante pode ser comparada e classificada. Para saber mais, consulte Como trabalhar com compilação.

• collation_specification precisa ser um literal de string. Caso contrário, um erro será gerado.
• Retorna NULL se value for NULL.

Tipo de retorno

STRING

Exemplos

Neste exemplo, o peso de a é menor que o de Z. Isso ocorre devido à especificação da colagem. und:ci atribui mais peso a Z.

WITH Words AS (
  SELECT
    COLLATE('a', 'und:ci') AS char1,
    COLLATE('Z', 'und:ci') AS char2
)
SELECT ( Words.char1 < Words.char2 ) AS a_less_than_Z
FROM Words;

+----------------+
| a_less_than_Z  |
+----------------+
| TRUE           |
+----------------+

Neste exemplo, o peso de a é maior que o de Z. Isso ocorre porque a especificação de agrupamento padrão atribui mais peso a a.

WITH Words AS (
  SELECT
    'a' AS char1,
    'Z' AS char2
)
SELECT ( Words.char1 < Words.char2 ) AS a_less_than_Z
FROM Words;

+----------------+
| a_less_than_Z  |
+----------------+
| FALSE          |
+----------------+

CONCAT

CONCAT(value1[, ...])

Descrição

Concatena um ou mais valores em um único resultado. Todos os valores precisam ser BYTES ou tipos de dados que podem passar pelo cast para STRING.

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

Observação: é possível também usar o || operador de concatenação para concatenar valores em uma string.

Tipo de retorno

STRING ou BYTES

Exemplos

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

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

SELECT CONCAT('Summer', ' ', 1923) as release_date;

+---------------------+
| release_date        |
+---------------------+
| Summer 1923         |
+---------------------+

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         |
+---------------------+

CONTAINS_SUBSTR

CONTAINS_SUBSTR(expression, search_value_literal)

Descrição

Executa uma pesquisa normalizada e indiferente a maiúsculas para ver se existe um valor em uma expressão. Retorna TRUE se o valor existir. Caso contrário, retorna FALSE.

O valor da pesquisa precisa ser um literal STRING, mas não o NULL.

A expressão pode ser uma referência de coluna ou tabela. Uma referência de tabela é avaliada como um STRUCT, com campos que são as colunas da tabela. Uma referência de coluna é avaliada como um dos seguintes tipos de dados:

• STRING
• INT64
• BOOL
• NUMERIC
• BIGNUMERIC
• TIMESTAMP
• TIME
• DATE
• DATETIME
• ARRAY
• STRUCT

Quando a expressão é avaliada, o resultado é convertido em um STRING e, em seguida, a função procura o valor da pesquisa no resultado. Se o valor de pesquisa for NULL, um erro será lançado. Se a expressão for NULL, o valor de retorno será NULL.

Você pode realizar uma pesquisa entre campos em uma expressão avaliada como STRUCT ou ARRAY. Se a expressão for avaliada como um STRUCT, a pesquisa entre campos será recursiva e incluirá todos os subcampos dentro do STRUCT.

Em uma pesquisa entre campos, cada campo e subcampo é convertido individualmente em uma string e pesquisado pelo valor. A função retornará TRUE se pelo menos um campo incluir o valor de pesquisa. Caso contrário, se pelo menos um campo for NULL, ele retornará NULL; caso contrário, se o valor da pesquisa não for encontrado e todos os campos forem não NULL, ele retornará FALSE.

Antes da comparação dos valores, eles são normalizados e dobrados por maiúsculas à normalização NFKC. As pesquisas com caracteres curinga não são compatíveis.

Tipo de retorno

BOOL

Exemplos

A consulta a seguir retorna TRUE porque essa correspondência não diferencia maiúsculas de minúsculas foi encontrada: blue house e Blue house.

SELECT CONTAINS_SUBSTR('the blue house', 'Blue house') AS result;

+--------+
| result |
+--------+
| true   |
+--------+

A consulta a seguir retorna FALSE porque blue não foi encontrado em the red house.

SELECT CONTAINS_SUBSTR('the red house', 'blue') AS result;

+--------+
| result |
+--------+
| false  |
+--------+

A consulta a seguir retorna TRUE porque Ⅸ e IX representam o mesmo valor normalizado.

SELECT '\u2168 day' AS a, 'IX' AS b, CONTAINS_SUBSTR('\u2168', 'IX') AS result;

+----------------------+
| a      | b  | result |
+----------------------+
| Ⅸ day | IX | true   |
+----------------------+

A consulta a seguir retorna TRUE porque 35 foi encontrado em um campo STRUCT.

SELECT CONTAINS_SUBSTR((23, 35, 41), '35') AS result;

+--------+
| result |
+--------+
| true   |
+--------+

A consulta a seguir retorna TRUE porque jk foi encontrado durante uma pesquisa recursiva dentro de um STRUCT.

SELECT CONTAINS_SUBSTR(('abc', ['def', 'ghi', 'jkl'], 'mno'), 'jk');

+--------+
| result |
+--------+
| true   |
+--------+

A consulta a seguir retorna TRUE porque NULLs são ignoradas quando uma correspondência é encontrada dentro de um STRUCT ou ARRAY.

SELECT CONTAINS_SUBSTR((23, NULL, 41), '41') AS result;

+--------+
| result |
+--------+
| true   |
+--------+

A consulta a seguir retorna NULL porque um NULL existia em um STRUCT que não resultou em uma correspondência.

SELECT CONTAINS_SUBSTR((23, NULL, 41), '35') AS result;

+--------+
| result |
+--------+
| null   |
+--------+

Na consulta a seguir, um erro é gerado porque o valor da pesquisa não pode ser um NULL literal.

SELECT CONTAINS_SUBSTR('hello', NULL) AS result;
-- Throws an error

Os exemplos a seguir fazem referência a uma tabela chamada Recipes, que pode ser emulada com uma cláusula WITH como esta:

WITH Recipes AS
 (SELECT 'Blueberry pancakes' as Breakfast, 'Egg salad sandwich' as Lunch, 'Potato dumplings' as Dinner UNION ALL
  SELECT 'Potato pancakes', 'Toasted cheese sandwich', 'Beef stroganoff' UNION ALL
  SELECT 'Ham scramble', 'Steak avocado salad', 'Tomato pasta' UNION ALL
  SELECT 'Avocado toast', 'Tomato soup', 'Blueberry salmon' UNION ALL
  SELECT 'Corned beef hash', 'Lentil potato soup', 'Glazed ham')
SELECT * FROM Recipes;

+-------------------+-------------------------+------------------+
| Breakfast         | Lunch                   | Dinner           |
+-------------------+-------------------------+------------------+
| Bluberry pancakes | Egg salad sandwich      | Potato dumplings |
| Potato pancakes   | Toasted cheese sandwich | Beef stroganoff  |
| Ham scramble      | Steak avocado salad     | Tomato pasta     |
| Avocado toast     | Tomato soup             | Blueberry samon  |
| Corned beef hash  | Lentil potato soup      | Glazed ham       |
+-------------------+-------------------------+------------------+

A consulta a seguir procura o valor toast em todas as colunas da tabela Recipes e retorna as linhas que contêm esse valor.

SELECT * FROM Recipes WHERE CONTAINS_SUBSTR(Recipes, 'toast');

+-------------------+-------------------------+------------------+
| Breakfast         | Lunch                   | Dinner           |
+-------------------+-------------------------+------------------+
| Potato pancakes   | Toasted cheese sandwich | Beef stroganoff  |
| Avocado toast     | Tomato soup             | Blueberry samon  |
+-------------------+-------------------------+------------------+

A consulta a seguir pesquisa o valor potato nas colunas Lunch e Dinner da tabela Recipe e retorna a linha se alguma coluna contiver esse valor.

SELECT * FROM Recipes WHERE CONTAINS_SUBSTR((Lunch, Dinner), 'potato');

+-------------------+-------------------------+------------------+
| Breakfast         | Lunch                   | Dinner           |
+-------------------+-------------------------+------------------+
| Bluberry pancakes | Egg salad sandwich      | Potato dumplings |
| Corned beef hash  | Lentil potato soup      | Glazed ham       |
+-------------------+-------------------------+------------------+

As consultas a seguir pesquisam em todas as colunas da tabela Recipes, exceto nas colunas Lunch e Dinner. Elas retornam as linhas de qualquer coluna diferente de Lunch ou Dinner que contém o valor potato.

SELECT *
FROM Recipes
WHERE CONTAINS_SUBSTR(
  (SELECT AS STRUCT Recipes.* EXCEPT (Lunch, Dinner)),
  'potato'
);

+-------------------+-------------------------+------------------+
| Breakfast         | Lunch                   | Dinner           |
+-------------------+-------------------------+------------------+
| Potato pancakes   | Toasted cheese sandwich | Beef stroganoff  |
+-------------------+-------------------------+------------------+

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.

Essa função é compatível com a especificação de compilação.

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

FORMAT(format_string_expression, data_type_expression[, ...])

Descrição

FORMAT formata uma expressão de tipo de dados como uma string.

• format_string_expression: 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.
• data_type_expression: o valor a ser formatado como uma string. Pode ser qualquer tipo de dados do BigQuery.

Tipo de retorno

STRING

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
DATE	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!

Especificadores de formatos compatíveis

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

Um especificador de formato adiciona formatação ao transmitir um valor para uma string. Ele pode conter estes subespecificadores:

• Sinalizações
• Largura
• Precisão

Outras informações sobre especificadores de formato:

• Comportamento de %g e %G
• Comportamento de %p e %P
• Comportamento de %t e %T
• Condições de erro
• Tratamento do argumento NULL
• Outras regras semânticas

Especificadores de formato

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 BIGNUMERIC 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 BIGNUMERIC FLOAT64
e	Notação científica (mantissa/expoente), minúsculas	3,926500e+02 inf nan	NUMERIC BIGNUMERIC FLOAT64
E	Notação científica (mantissa/expoente), maiúsculas	3,926500E+02 INF NAN	NUMERIC BIGNUMERIC 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 BIGNUMERIC 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 BIGNUMERIC FLOAT64
p	Produz uma string de uma linha que pode ser impressa representando JSON. Consulte Comportamento de %p e %P.	{"month":10,"year":2019}	JSON
P	Produz uma string de várias linhas que pode ser impressa representando JSON. Consulte Comportamento de %p e %P.	{ "month": 10, "year": 2019 }	JSON
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.	sample 2014‑01‑01	<any>
T	Produz uma string que é uma constante válida do BigQuery, com um tipo semelhante ao do valor (talvez mais amplo ou string). Consulte Comportamento de %t e %T.	'amostra' b'amostra de 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 %p e %P

O especificador de formato %p produz uma string imprimível de uma linha. O especificador de formato %P produz uma string imprimível em várias linhas. Use esses especificadores de formato com os seguintes tipos de dados:

Tipo	%p	%P
JSON	Entrada JSON: JSON ' { "month": 10, "year": 2019 } ' Produz uma string de uma linha que pode ser impressa representando JSON: {"month":10,"year":2019}	Entrada JSON: JSON ' { "month": 10, "year": 2019 } ' Produz uma string de várias linhas que pode ser impressa representando JSON: { "month": 10, "year": 2019 }

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"
INTERVAL	1-2 3 4:5:6.789	INTERVAL "1-2 3 4:5:6.789" YEAR TO SECOND
ARRAY	[valor, valor, ...] onde os valores são formatados com %t	[valor, valor, ...] onde os valores são formatados com %T
STRUCT	(valor, valor, ...) onde os campos são formatados com %t	(valor, valor, ...) em que os campos são formatados com %T Casos especiais: Nenhum campo: STRUCT() Um campo: STRUCT(value)
JSON	String de uma linha que pode ser impressa e que representa JSON {"name":"apple","stock":3}	String de uma linha que pode ser impressa e que representa um literal JSON. JSON '{"name":"apple","stock":3}'

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 BigQuery faz o cast desses valores para STRING. Para %T, o BigQuery 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.

Há várias codificações base64 em uso comum que variam exatamente no alfabeto de 65 caracteres ASCII usado para codificar os 64 dígitos e o espaçamento. Consulte RFC 4648 para detalhes. Essa função espera o alfabeto [A-Za-z0-9+/=].

Tipo de retorno

BYTES

Exemplo

SELECT FROM_BASE64('/+A=') AS byte_data;

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

Para trabalhar com uma codificação usando um alfabeto base64 diferente, talvez seja necessário escrever FROM_BASE64 com a função REPLACE. Por exemplo, a codificação segura de nome de arquivo e URL base64url usada com frequência na programação da Web usa -_= como os últimos caracteres em vez de +/=. Para decodificar uma string codificada em base64url, substitua - e _ por + e /, respectivamente.

SELECT FROM_BASE64(REPLACE(REPLACE('_-A=', '-', '+'), '_', '/')) AS binary;

-- Note that the result of FROM_BASE64 is of type BYTES, displayed as a base64-encoded string.
+--------+
| binary |
+--------+
| /+A=   |
+--------+

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     |
+------------------+--------------+

INITCAP

INITCAP(value[, delimiters])

Descrição

Pega uma STRING e a retorna com o primeiro caractere de cada palavra em maiúsculas e todos os outros caracteres em minúsculas. Caracteres não alfabéticos permanecem da mesma forma.

delimiters é um argumento de string opcional usado para substituir o conjunto padrão de caracteres usados para separar palavras. Se delimiters não for especificado, o padrão será os seguintes caracteres:
<whitespace> [ ] ( ) { } / | \ < > ! ? @ " ^ # $ & ~ _ , . : ; * % + -

Se value ou delimiters for NULL, a função retornará NULL.

Tipo de retorno

STRING

Exemplos

WITH example AS
(
  SELECT 'Hello World-everyone!' AS value UNION ALL
  SELECT 'tHe dog BARKS loudly+friendly' AS value UNION ALL
  SELECT 'apples&oranges;&pears' AS value UNION ALL
  SELECT 'καθίσματα ταινιών' AS value
)
SELECT value, INITCAP(value) AS initcap_value FROM example

+-------------------------------+-------------------------------+
| value                         | initcap_value                 |
+-------------------------------+-------------------------------+
| Hello World-everyone!         | Hello World-Everyone!         |
| tHe dog BARKS loudly+friendly | The Dog Barks Loudly+Friendly |
| apples&oranges;&pears         | Apples&Oranges;&Pears         |
| καθίσματα ταινιών             | Καθίσματα Ταινιών             |
+-------------------------------+-------------------------------+

WITH example AS
(
  SELECT 'hello WORLD!' AS value, '' AS delimiters UNION ALL
  SELECT 'καθίσματα ταιντιώ@ν' AS value, 'τ@' AS delimiters UNION ALL
  SELECT 'Apples1oranges2pears' AS value, '12' AS delimiters UNION ALL
  SELECT 'tHisEisEaESentence' AS value, 'E' AS delimiters
)
SELECT value, delimiters, INITCAP(value, delimiters) AS initcap_value FROM example;

+----------------------+------------+----------------------+
| value                | delimiters | initcap_value        |
+----------------------+------------+----------------------+
| hello WORLD!         |            | Hello world!         |
| καθίσματα ταιντιώ@ν  | τ@         | ΚαθίσματΑ τΑιντΙώ@Ν  |
| Apples1oranges2pears | 12         | Apples1Oranges2Pears |
| tHisEisEaESentence   | E          | ThisEIsEAESentence   |
+----------------------+------------+----------------------+

INSTR

INSTR(source_value, search_value[, position[, occurrence]])

Descrição

Retorna o menor índice baseado em 1 de search_value em source_value. É retornado 0 quando nenhuma correspondência é encontrada. source_value e search_value precisam ser do mesmo tipo, STRING ou BYTES.

Se position for especificado, a pesquisa começará nessa posição em source_value. Caso contrário, ela começará no início de source_value. Se position for negativo, a função pesquisará para trás a partir do final de source_value, com -1 indicando o último caractere. position não pode ser 0.

Se occurrence for especificado, a pesquisa retornará a posição de uma instância específica de search_value em source_value. Caso contrário, retornará o índice da primeira ocorrência. Se occurrence for maior que o número de correspondências encontradas, 0 será retornado. Para occurrence maior que 1, a função procura ocorrências sobrepostas. Em outras palavras, a função procura outras ocorrências que comecem pelo segundo caractere na ocorrência anterior. occurrence não pode ser 0 nem negativo.

Essa função é compatível com a especificação de compilação.

Tipo de retorno

INT64

Exemplos

WITH example AS
(SELECT 'banana' as source_value, 'an' as search_value, 1 as position, 1 as
occurrence UNION ALL
SELECT 'banana' as source_value, 'an' as search_value, 1 as position, 2 as
occurrence UNION ALL
SELECT 'banana' as source_value, 'an' as search_value, 1 as position, 3 as
occurrence UNION ALL
SELECT 'banana' as source_value, 'an' as search_value, 3 as position, 1 as
occurrence UNION ALL
SELECT 'banana' as source_value, 'an' as search_value, -1 as position, 1 as
occurrence UNION ALL
SELECT 'banana' as source_value, 'an' as search_value, -3 as position, 1 as
occurrence UNION ALL
SELECT 'banana' as source_value, 'ann' as search_value, 1 as position, 1 as
occurrence UNION ALL
SELECT 'helloooo' as source_value, 'oo' as search_value, 1 as position, 1 as
occurrence UNION ALL
SELECT 'helloooo' as source_value, 'oo' as search_value, 1 as position, 2 as
occurrence
)
SELECT source_value, search_value, position, occurrence, INSTR(source_value,
search_value, position, occurrence) AS instr
FROM example;

+--------------+--------------+----------+------------+-------+
| source_value | search_value | position | occurrence | instr |
+--------------+--------------+----------+------------+-------+
| banana       | an           | 1        | 1          | 2     |
| banana       | an           | 1        | 2          | 4     |
| banana       | an           | 1        | 3          | 0     |
| banana       | an           | 3        | 1          | 4     |
| banana       | an           | -1       | 1          | 4     |
| banana       | an           | -3       | 1          | 4     |
| banana       | ann          | 1        | 1          | 0     |
| helloooo     | oo           | 1        | 1          | 5     |
| helloooo     | oo           | 1        | 2          | 6     |
+--------------+--------------+----------+------------+-------+

LEFT

LEFT(value, length)

Descrição

Retorna um valor STRING ou BYTES que consiste no número especificado de bytes ou caracteres mais à esquerda de value. length é um INT64 que especifica o comprimento do valor retornado. Se value for do tipo BYTES, length será o número de bytes mais à esquerda a ser retornado. Se value for STRING, length será o número de caracteres mais à esquerda a ser retornado.

Se length for 0, um valor STRING ou BYTES vazio será retornado. Se length for negativo, um erro será retornado. Se length ultrapassar o número de caracteres ou bytes de value, o value original será retornado.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH examples AS
(SELECT 'apple' as example
UNION ALL
SELECT 'banana' as example
UNION ALL
SELECT 'абвгд' as example
)
SELECT example, LEFT(example, 3) AS left_example
FROM examples;

+---------+--------------+
| example | left_example |
+---------+--------------+
| apple   | app          |
| banana  | ban          |
| абвгд   | абв          |
+---------+--------------+

WITH examples AS
(SELECT b'apple' as example
UNION ALL
SELECT b'banana' as example
UNION ALL
SELECT b'\xab\xcd\xef\xaa\xbb' as example
)
SELECT example, LEFT(example, 3) AS left_example
FROM examples;

-- Note that the result of LEFT is of type BYTES, displayed as a base64-encoded string.
+----------+--------------+
| example  | left_example |
+----------+--------------+
| YXBwbGU= | YXBw         |
| YmFuYW5h | YmFu         |
| q83vqrs= | q83v         |
+----------+--------------+

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   |
+-----------+

NORMALIZE

NORMALIZE(value[, normalization_mode])

Descrição

Pega um valor de string e retorna como uma string normalizada. Se você não fornecer um modo de normalização, NFC será usado.

A normalização é utilizada para garantir que duas strings sejam equivalentes. Em geral, a normalização é usada em situações em que duas strings são renderizadas da mesma maneira na tela, mas têm diferentes pontos de código Unicode.

NORMALIZE é compatível com quatro modos de normalização opcionais:

Valor	Nome	Descrição
NFC	Composição canônica do Formulário de normalização	Decompõe e recompõe caracteres por equivalência canônica.
NFKC	Composição de Compatibilidade do Formulário de Normalização	Decompõe caracteres por compatibilidade e os recompõe por equivalência canônica.
NFD	Decomposição canônica do Formulário de normalização	Decompõe caracteres por equivalência canônica. Vários caracteres de combinação são organizados em uma ordem específica.
NFKD	Decomposição de compatibilidade do Formulário de normalização	Decompõe caracteres por compatibilidade. Vários caracteres de combinação são organizados em uma ordem específica.

Tipo de retorno

STRING

Exemplos

SELECT a, b, a = b as normalized
FROM (SELECT NORMALIZE('\u00ea') as a, NORMALIZE('\u0065\u0302') as b);

+---+---+------------+
| a | b | normalized |
+---+---+------------+
| ê | ê | true       |
+---+---+------------+

O exemplo a seguir normaliza diferentes caracteres de espaços.

WITH EquivalentNames AS (
  SELECT name
  FROM UNNEST([
      'Jane\u2004Doe',
      'John\u2004Smith',
      'Jane\u2005Doe',
      'Jane\u2006Doe',
      'John Smith']) AS name
)
SELECT
  NORMALIZE(name, NFKC) AS normalized_name,
  COUNT(*) AS name_count
FROM EquivalentNames
GROUP BY 1;

+-----------------+------------+
| normalized_name | name_count |
+-----------------+------------+
| John Smith      | 2          |
| Jane Doe        | 3          |
+-----------------+------------+

NORMALIZE_AND_CASEFOLD

NORMALIZE_AND_CASEFOLD(value[, normalization_mode])

Descrição

Pega um valor de string e retorna como uma string normalizada. Se você não fornecer um modo de normalização, NFC será usado.

A normalização é utilizada para garantir que duas strings sejam equivalentes. Em geral, a normalização é usada em situações em que duas strings renderizam da mesma maneira na tela, mas têm diferentes pontos de código Unicode.

O dobramento de caso é usado para a comparação de strings sem maiúsculas. Se você precisar comparar strings e maiúsculas e minúsculas não puderem ser consideradas, use NORMALIZE_AND_CASEFOLD. Caso contrário, use NORMALIZE.

NORMALIZE_AND_CASEFOLD é compatível com quatro modos de normalização opcionais:

Valor	Nome	Descrição
NFC	Composição canônica do Formulário de normalização	Decompõe e recompõe caracteres por equivalência canônica.
NFKC	Composição de Compatibilidade do Formulário de Normalização	Decompõe caracteres por compatibilidade e os recompõe por equivalência canônica.
NFD	Decomposição canônica do Formulário de normalização	Decompõe caracteres por equivalência canônica. Vários caracteres de combinação são organizados em uma ordem específica.
NFKD	Decomposição de compatibilidade do Formulário de normalização	Decompõe caracteres por compatibilidade. Vários caracteres de combinação são organizados em uma ordem específica.

Tipo de retorno

STRING

Exemplos

SELECT
  a, b,
  NORMALIZE(a) = NORMALIZE(b) as normalized,
  NORMALIZE_AND_CASEFOLD(a) = NORMALIZE_AND_CASEFOLD(b) as normalized_with_case_folding
FROM (SELECT 'The red barn' AS a, 'The Red Barn' AS b);

+--------------+--------------+------------+------------------------------+
| a            | b            | normalized | normalized_with_case_folding |
+--------------+--------------+------------+------------------------------+
| The red barn | The Red Barn | false      | true                         |
+--------------+--------------+------------+------------------------------+

WITH Strings AS (
  SELECT '\u2168' AS a, 'IX' AS b UNION ALL
  SELECT '\u0041\u030A', '\u00C5'
)
SELECT a, b,
  NORMALIZE_AND_CASEFOLD(a, NFD)=NORMALIZE_AND_CASEFOLD(b, NFD) AS nfd,
  NORMALIZE_AND_CASEFOLD(a, NFC)=NORMALIZE_AND_CASEFOLD(b, NFC) AS nfc,
  NORMALIZE_AND_CASEFOLD(a, NFKD)=NORMALIZE_AND_CASEFOLD(b, NFKD) AS nkfd,
  NORMALIZE_AND_CASEFOLD(a, NFKC)=NORMALIZE_AND_CASEFOLD(b, NFKC) AS nkfc
FROM Strings;

+---+----+-------+-------+------+------+
| a | b  | nfd   | nfc   | nkfd | nkfc |
+---+----+-------+-------+------+------+
| Ⅸ | IX | false | false | true | true |
| Å | Å  | true  | true  | true | true |
+---+----+-------+-------+------+------+

OCTET_LENGTH

OCTET_LENGTH(value)

Alias para BYTE_LENGTH.

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 $.

Observação: o BigQuery é compatível com expressões regulares usando a biblioteca re2 (em inglês). Consulte a documentação correspondente para conhecer a sintaxe da expressão regular.

Tipo de retorno

BOOL

Exemplos

SELECT
  email,
  REGEXP_CONTAINS(email, r'@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+') AS is_valid
FROM
  (SELECT
    ['[e-mail]', '[e-mail]', 'www.example.net']
    AS addresses),
  UNNEST(addresses) AS email;

+-----------------+----------+
| email           | is_valid |
+-----------------+----------+
| [e-mail] | true     |
| [e-mail] | 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
    ['[e-mail]', '[e-mail]', '[e-mail]', '![e-mail]', '[e-mail]']
    AS addresses),
  UNNEST(addresses) AS email;

+----------------+---------------------+---------------------+
| email          | valid_email_address | without_parentheses |
+----------------+---------------------+---------------------+
| [e-mail]      | true                | true                |
| [e-mail] | false               | true                |
| [e-mail]      | true                | true                |
| ![e-mail]     | false               | true                |
| [e-mail]      | false               | false               |
+----------------+---------------------+---------------------+

REGEXP_EXTRACT

REGEXP_EXTRACT(value, regexp[, position[, occurrence]])

Descrição

Retorna a substring em value que corresponde à expressão regular, regexp. Retorna NULL se não há 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.

Se position for especificado, a pesquisa começará nessa posição em value. Caso contrário, ela começará no início de value. position precisa ser um número inteiro positivo e não pode ser 0. Se position for maior que o tamanho de value, NULL será retornado.

Se occurrence for especificado, a pesquisa retornará uma ocorrência específica de regexp em value. Caso contrário, retornará a primeira correspondência. Se occurrence for maior que o número de correspondências encontradas, NULL será retornado. Para occurrence maior que 1, a função pesquisa outras ocorrências que comecem com o caractere após a ocorrência anterior.

Retornará um erro se:

• a expressão regular for inválida;
• a expressão regular tiver mais de um grupo de captura;
• position não for um número inteiro positivo;
• occurrence não for um número inteiro positivo.

Observação: o BigQuery é compatível com expressões regulares usando a biblioteca re2 (em inglês). Consulte a documentação correspondente para conhecer a sintaxe da expressão regular.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH email_addresses AS
  (SELECT '[e-mail]' as email
  UNION ALL
  SELECT '[e-mail]' as email
  UNION ALL
  SELECT '[e-mail]' 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 '[e-mail]' as email
  UNION ALL
  SELECT '[e-mail]' as email
  UNION ALL
  SELECT '[e-mail]' 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              |
+------------------+

WITH example AS
(SELECT 'Hello Helloo and Hellooo' AS value, 'H?ello+' AS regex, 1 as position,
1 AS occurrence UNION ALL
SELECT 'Hello Helloo and Hellooo', 'H?ello+', 1, 2 UNION ALL
SELECT 'Hello Helloo and Hellooo', 'H?ello+', 1, 3 UNION ALL
SELECT 'Hello Helloo and Hellooo', 'H?ello+', 1, 4 UNION ALL
SELECT 'Hello Helloo and Hellooo', 'H?ello+', 2, 1 UNION ALL
SELECT 'Hello Helloo and Hellooo', 'H?ello+', 3, 1 UNION ALL
SELECT 'Hello Helloo and Hellooo', 'H?ello+', 3, 2 UNION ALL
SELECT 'Hello Helloo and Hellooo', 'H?ello+', 3, 3 UNION ALL
SELECT 'Hello Helloo and Hellooo', 'H?ello+', 20, 1 UNION ALL
SELECT 'cats&dogs&rabbits' ,'\\w+&', 1, 2 UNION ALL
SELECT 'cats&dogs&rabbits', '\\w+&', 2, 3
)
SELECT value, regex, position, occurrence, REGEXP_EXTRACT(value, regex,
position, occurrence) AS regexp_value FROM example;

+--------------------------+---------+----------+------------+--------------+
| value                    | regex   | position | occurrence | regexp_value |
+--------------------------+---------+----------+------------+--------------+
| Hello Helloo and Hellooo | H?ello+ | 1        | 1          | Hello        |
| Hello Helloo and Hellooo | H?ello+ | 1        | 2          | Helloo       |
| Hello Helloo and Hellooo | H?ello+ | 1        | 3          | Hellooo      |
| Hello Helloo and Hellooo | H?ello+ | 1        | 4          | NULL         |
| Hello Helloo and Hellooo | H?ello+ | 2        | 1          | ello         |
| Hello Helloo and Hellooo | H?ello+ | 3        | 1          | Helloo       |
| Hello Helloo and Hellooo | H?ello+ | 3        | 2          | Hellooo      |
| Hello Helloo and Hellooo | H?ello+ | 3        | 3          | NULL         |
| Hello Helloo and Hellooo | H?ello+ | 20       | 1          | NULL         |
| cats&dogs&rabbits        | \w+&    | 1        | 2          | dogs&        |
| cats&dogs&rabbits        | \w+&    | 2        | 3          | NULL         |
+--------------------------+---------+----------+------------+--------------+

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.

Observação: o BigQuery é compatível com expressões regulares usando a biblioteca re2 (em inglês). Consulte a documentação correspondente para conhecer a sintaxe da expressão regular.

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_INSTR

REGEXP_INSTR(source_value, regexp [, position[, occurrence, [occurrence_position]]])

Descrição

Retorna o menor índice baseado em 1 de uma expressão regular, regexp, em source_value. Retorna 0 quando nenhuma correspondência é encontrada ou se a expressão regular está vazia. Retorna um erro se a expressão regular é inválida ou tem mais de um grupo de captura. source_value e regexp precisam ser do mesmo tipo, STRING ou BYTES.

Se position for especificado, a pesquisa começará nessa posição em source_value. Caso contrário, ela começará no início de source_value. position não pode ser 0 nem um número negativo.

Se occurrence for especificado, a pesquisa retornará a posição de uma instância específica de regexp em source_value. Caso contrário, retornará o índice da primeira ocorrência. Se occurrence for maior que o número de correspondências encontradas, 0 será retornado. Para occurrence maior que 1, a função procura ocorrências sobrepostas. Em outras palavras, a função procura outras ocorrências que comecem pelo segundo caractere na ocorrência anterior. occurrence não pode ser 0 nem negativo.

Como opção, é possível usar occurrence_position para especificar onde começa uma posição em relação a uma occurrence. Suas opções são: + 0: retorna a posição inicial da ocorrência. + 1: retorna a primeira posição após o final da ocorrência. Se o final da ocorrência também for o final da entrada, o fim da ocorrência será retornado. Por exemplo, comprimento de uma string + 1.

Tipo de retorno

INT64

Exemplos

WITH example AS (
  SELECT '[e-mail]' AS source_value, '@[^.]*' AS regexp UNION ALL
  SELECT '[e-mail]', '@[^.]*' UNION ALL
  SELECT '[e-mail]', '@[^.]*' UNION ALL
  SELECT 'abc.com', '@[^.]*')
SELECT source_value, regexp, REGEXP_INSTR(source_value, regexp) AS instr
FROM example;

+---------------+--------+-------+
| source_value  | regexp | instr |
+---------------+--------+-------+
| [e-mail]  | @[^.]* | 3     |
| [e-mail]   | @[^.]* | 3     |
| [e-mail] | @[^.]* | 4     |
| abc.com       | @[^.]* | 0     |
+---------------+--------+-------+

WITH example AS (
  SELECT '[e-mail] [e-mail]' AS source_value, '@[^.]*' AS regexp, 1 AS position UNION ALL
  SELECT '[e-mail] [e-mail]', '@[^.]*', 2 UNION ALL
  SELECT '[e-mail] [e-mail]', '@[^.]*', 3 UNION ALL
  SELECT '[e-mail] [e-mail]', '@[^.]*', 4)
SELECT
  source_value, regexp, position,
  REGEXP_INSTR(source_value, regexp, position) AS instr
FROM example;

+-------------------------+--------+----------+-------+
| source_value            | regexp | position | instr |
+-------------------------+--------+----------+-------+
| [e-mail] [e-mail] | @[^.]* | 1        | 2     |
| [e-mail] [e-mail] | @[^.]* | 2        | 2     |
| [e-mail] [e-mail] | @[^.]* | 3        | 14    |
| [e-mail] [e-mail] | @[^.]* | 4        | 14    |
+-------------------------+--------+----------+-------+

WITH example AS (
  SELECT '[e-mail] [e-mail] [e-mail]' AS source_value,
         '@[^.]*' AS regexp, 1 AS position, 1 AS occurrence UNION ALL
  SELECT '[e-mail] [e-mail] [e-mail]', '@[^.]*', 1, 2 UNION ALL
  SELECT '[e-mail] [e-mail] [e-mail]', '@[^.]*', 1, 3)
SELECT
  source_value, regexp, position, occurrence,
  REGEXP_INSTR(source_value, regexp, position, occurrence) AS instr
FROM example;

+-------------------------------------+--------+----------+------------+-------+
| source_value                        | regexp | position | occurrence | instr |
+-------------------------------------+--------+----------+------------+-------+
| [e-mail] [e-mail] [e-mail] | @[^.]* | 1        | 1          | 2     |
| [e-mail] [e-mail] [e-mail] | @[^.]* | 1        | 2          | 14    |
| [e-mail] [e-mail] [e-mail] | @[^.]* | 1        | 3          | 26    |
+-------------------------------------+--------+----------+------------+-------+

WITH example AS (
  SELECT '[e-mail]' AS source_value, '@[^.]*' AS regexp,
         1 AS position, 1 AS occurrence, 0 AS o_position UNION ALL
  SELECT '[e-mail]', '@[^.]*', 1, 1, 1)
SELECT
  source_value, regexp, position, occurrence, o_position,
  REGEXP_INSTR(source_value, regexp, position, occurrence, o_position) AS instr
FROM example;

+--------------+--------+----------+------------+------------+-------+
| source_value | regexp | position | occurrence | o_position | instr |
+--------------+--------+----------+------------+------------+-------+
| [e-mail]  | @[^.]* | 1        | 1          | 0          | 2     |
| [e-mail]  | @[^.]* | 1        | 1          | 1          | 8     |
+--------------+--------+----------+------------+------------+-------+

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.

Insira um caractere de escape antes de adicionar uma barra invertida na expressão regular. Por exemplo, SELECT REGEXP_REPLACE('abc', 'b(.)', 'X\\1'); retorna aXc. Também é possível usar strings brutas para remover uma camada de escape, por exemplo, SELECT REGEXP_REPLACE('abc', 'b(.)', r'X\1');.

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.

Observação: o BigQuery é compatível com expressões regulares usando a biblioteca re2 (em inglês). Consulte a documentação correspondente para conhecer a sintaxe da expressão regular.

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> |
+--------------------------+

REGEXP_SUBSTR

REGEXP_SUBSTR(value, regexp[, position[, occurrence]])

Descrição

Sinônimo de REGEXP_EXTRACT.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH example AS
(SELECT 'Hello World Helloo' AS value, 'H?ello+' AS regex, 1 AS position, 1 AS
occurrence
)
SELECT value, regex, position, occurrence, REGEXP_SUBSTR(value, regex,
position, occurrence) AS regexp_value FROM example;

+--------------------+---------+----------+------------+--------------+
| value              | regex   | position | occurrence | regexp_value |
+--------------------+---------+----------+------------+--------------+
| Hello World Helloo | H?ello+ | 1        | 1          | Hello        |
+--------------------+---------+----------+------------+--------------+

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.

Essa função é compatível com a especificação de compilação.

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           |
+---------------+----------------+--------------+---------------+

RIGHT

RIGHT(value, length)

Descrição

Retorna um valor STRING ou BYTES que consiste no número especificado de caracteres ou bytes mais à direita de value. length é um INT64 que especifica o comprimento do valor retornado. Se value for BYTES, length será o número de bytes mais à direita a ser retornado. Se value for STRING, length será o número de caracteres mais à direita a ser retornado.

Se length for 0, um valor STRING ou BYTES vazio será retornado. Se length for negativo, um erro será retornado. Se length ultrapassar o número de caracteres ou bytes de value, o value original será retornado.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH examples AS
(SELECT 'apple' as example
UNION ALL
SELECT 'banana' as example
UNION ALL
SELECT 'абвгд' as example
)
SELECT example, RIGHT(example, 3) AS right_example
FROM examples;

+---------+---------------+
| example | right_example |
+---------+---------------+
| apple   | ple           |
| banana  | ana           |
| абвгд   | вгд           |
+---------+---------------+

WITH examples AS
(SELECT b'apple' as example
UNION ALL
SELECT b'banana' as example
UNION ALL
SELECT b'\xab\xcd\xef\xaa\xbb' as example
)
SELECT example, RIGHT(example, 3) AS right_example
FROM examples;

-- Note that the result of RIGHT is of type BYTES, displayed as a base64-encoded string.
+----------+---------------+
| example  | right_example |
+----------+---------------+
| YXBwbGU= | cGxl          |
| YmFuYW5h | YW5h          |
| q83vqrs= | 76q7          |
+----------+---------------+

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;

SOUNDEX

SOUNDEX(value)

Descrição

Retorna um STRING que representa o código do Soundex para value.

SOUNDEX produz uma representação fonética de uma string. Ele indexa palavras por som, conforme pronunciadas em inglês. Geralmente é usado para determinar se duas strings, como os nomes de famíliaLevine e Lavanda ou as palavras to e too, têm pronúncia semelhante em inglês.

O resultado do SOUNDEX consiste em uma letra seguida por três dígitos. Caracteres não latinos são ignorados. Se a string restante estiver vazia depois da remoção de caracteres não latinos, um STRING vazio será retornado.

Tipo de retorno

STRING

Exemplos

WITH example AS (
  SELECT 'Ashcraft' AS value UNION ALL
  SELECT 'Raven' AS value UNION ALL
  SELECT 'Ribbon' AS value UNION ALL
  SELECT 'apple' AS value UNION ALL
  SELECT 'Hello world!' AS value UNION ALL
  SELECT '  H3##!@llo w00orld!' AS value UNION ALL
  SELECT '#1' AS value UNION ALL
  SELECT NULL AS value
)
SELECT value, SOUNDEX(value) AS soundex
FROM example;

+----------------------+---------+
| value                | soundex |
+----------------------+---------+
| Ashcraft             | A261    |
| Raven                | R150    |
| Ribbon               | R150    |
| apple                | a140    |
| Hello world!         | H464    |
|   H3##!@llo w00orld! | H464    |
| #1                   |         |
| NULL                 | NULL    |
+----------------------+---------+

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.

Essa função é compatível com a especificação de compilação.

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.

Essa função é compatível com a especificação de compilação.

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(value1, value2)

Descrição

Utiliza dois valores STRING ou BYTES. Retorna o índice com base em 1 da primeira ocorrência de value2 em value1. Retorna 0 se value2 não for encontrado.

Essa função é compatível com a especificação de compilação.

Tipo de retorno

INT64

Exemplos

WITH email_addresses AS
  (SELECT
    '[e-mail]' AS email_address
  UNION ALL
  SELECT
    '[e-mail]' AS email_address
  UNION ALL
  SELECT
    '[e-mail]' 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.

• Se position for 1, a substring começará do primeiro caractere ou byte.
• Se position for 0 ou menor que -LENGTH(value), position será definido como 1, e a substring começará do primeiro caractere ou byte.
• Se position for maior que value, a função produzirá uma substring vazia.
• Se position for negativo, a função fará a contagem do final de value, com -1 indicando o último caractere ou byte.

O argumento length especifica o número máximo de caracteres ou bytes a serem retornados.

• Se length não for especificado, a função produzirá uma substring que começa na posição especificada e termina no último caractere ou byte de value.
• Se length for 0, a função produzirá uma substring vazia.
• Se length for negativo, a função produzirá um erro.
• A substring retornada pode ser menor que length, por exemplo, quando length exceder o comprimento de value ou quando a posição inicial da substring mais length for maior que o comprimento de value.

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      |
+---------+

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

SELECT
  SUBSTR(item, 1, 123) 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
  SUBSTR(item, 123) as example
FROM items;

+---------+
| example |
+---------+
|         |
|         |
|         |
+---------+

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

SELECT
  SUBSTR(item, 123, 5) as example
FROM items;

+---------+
| example |
+---------+
|         |
|         |
|         |
+---------+

SUBSTRING

SUBSTRING(value, position[, length])

Alias para SUBSTR.

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.

Há várias codificações base64 em uso comum que variam exatamente no alfabeto de 65 caracteres ASCII usado para codificar os 64 dígitos e o espaçamento. Consulte RFC 4648 para detalhes. Esta função adiciona espaçamento e usa o alfabeto [A-Za-z0-9+/=].

Tipo de retorno

STRING

Exemplo

SELECT TO_BASE64(b'\377\340') AS base64_string;

+---------------+
| base64_string |
+---------------+
| /+A=          |
+---------------+

Para trabalhar com uma codificação usando um alfabeto base64 diferente, talvez seja necessário escrever TO_BASE64 com a função REPLACE. Por exemplo, a codificação segura de nome de arquivo e URL base64url usada com frequência na programação da Web usa -_= como os últimos caracteres em vez de +/=. Para codificar uma string codificada em base64url, substitua + e / por - e _, respectivamente.

SELECT REPLACE(REPLACE(TO_BASE64(b'\377\340'), '+', '-'), '/', '_') as websafe_base64;

+----------------+
| websafe_base64 |
+----------------+
| _-A=           |
+----------------+

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     |
+----------------------------------+------------------+

TRANSLATE

TRANSLATE(expression, source_characters, target_characters)

Descrição

Em expression, substitui cada caractere em source_characters pelo caractere correspondente em target_characters. Todas as entradas precisam ser do mesmo tipo, STRING ou BYTES.

• Cada caractere em expression é traduzido, no máximo, uma vez.
• Um caractere em expression que não está presente em source_characters é deixado inalterado em expression.
• Um caractere em source_characters sem um caractere correspondente em target_characters é omitido do resultado.
• Um caractere duplicado em source_characters resulta em erro.

Tipo de retorno

STRING ou BYTES

Exemplos

WITH example AS (
  SELECT 'This is a cookie' AS expression, 'sco' AS source_characters, 'zku' AS
  target_characters UNION ALL
  SELECT 'A coaster' AS expression, 'co' AS source_characters, 'k' as
  target_characters
)
SELECT expression, source_characters, target_characters, TRANSLATE(expression,
source_characters, target_characters) AS translate
FROM example;

+------------------+-------------------+-------------------+------------------+
| expression       | source_characters | target_characters | translate        |
+------------------+-------------------+-------------------+------------------+
| This is a cookie | sco               | zku               | Thiz iz a kuukie |
| A coaster        | co                | k                 | A kaster         |
+------------------+-------------------+-------------------+------------------+

TRIM

TRIM(value_to_trim[, set_of_characters_to_remove])

Descrição

Usa um valor STRING ou BYTES para cortar.

Se o valor de corte for STRING, todos os pontos de código Unicode iniciais e final em set_of_characters_to_remove serão removidos. O conjunto de pontos de código é opcional. Se não for especificado, todos os caracteres de espaço em branco serão removidos do início e do fim do valor para cortar.

Se o valor de corte for BYTES, este valor será removido de todos os bytes principais e finais em set_of_characters_to_remove. O conjunto de bytes é obrigatório.

Tipo de retorno

• STRING, se value_to_trim for um valor de STRING.
• BYTES, se value_to_trim for um valor de BYTES.

Exemplos

No exemplo a seguir, todos os caracteres de espaço em branco à esquerda e à direita são removidos de item porque set_of_characters_to_remove não é especificado.

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# |
+----------+

No exemplo a seguir, todos os caracteres * à esquerda e à direita são removidos do item.

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  |
+---------+

No exemplo a seguir, todos os caracteres x, y e z à esquerda e à direita são removidos de item.

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    |
+---------+

No exemplo a seguir, analise como TRIM interpreta caracteres como pontos de código Unicode. Se o conjunto de caracteres à direita contiver uma marca diacrítica combinada em uma letra específica, TRIM poderá remover a mesma marca diacrítica de uma letra diferente.

SELECT
  TRIM('abaW̊', 'Y̊') AS a,
  TRIM('W̊aba', 'Y̊') AS b,
  TRIM('abaŪ̊', 'Y̊') AS c,
  TRIM('Ū̊aba', 'Y̊') AS d;

+---------------------------+
| a    | b    | c    | d    |
+---------------------------+
| abaW | W̊aba | abaŪ | Ūaba |
+---------------------------+

No exemplo a seguir, todos os bytes b'n', b'a' e b'\xab' à esquerda e à direita são removidos de item.

WITH items AS
(
  SELECT b'apple' as item UNION ALL
  SELECT b'banana' as item UNION ALL
  SELECT b'\xab\xcd\xef\xaa\xbb' as item
)
SELECT item, TRIM(item, b'na\xab') AS examples
FROM items;

-- Note that the result of TRIM is of type BYTES, displayed as a base64-encoded string.
+----------------------+------------------+
| item                 | example          |
+----------------------+------------------+
| YXBwbGU=             | cHBsZQ==         |
| YmFuYW5h             | Yg==             |
| q83vqrs=             | ze+quw==         |
+----------------------+------------------+

UNICODE

UNICODE(value)

Descrição

Retorna o ponto de código Unicode para o primeiro caractere em value. Retorna 0 se value está vazio ou se o ponto de código Unicode resultante é 0.

Tipo de retorno

INT64

Exemplos

SELECT UNICODE('âbcd') as A, UNICODE('â') as B, UNICODE('') as C, UNICODE(NULL) as D;

+-------+-------+-------+-------+
| A     | B     | C     | D     |
+-------+-------+-------+-------+
| 226   | 226   | 0     | NULL  |
+-------+-------+-------+-------+

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     |
+---------+