Operadores

Os operadores são representados por caracteres especiais ou palavras-chave. Eles não usam a sintaxe de chamada de função. Um operador manipula qualquer número de entradas de dados, também chamados de operandos, e retorna um resultado.

Convenções comuns:

• A menos que especificado em contrário, todos os operadores retornam NULL quando um dos operandos é NULL.
• Todos os operadores geram um erro se o resultado do cálculo estourar.
• Para todas as operações de ponto flutuante, +/-inf e NaN só poderão ser retornadas se um dos operandos for +/-inf ou NaN. Em outros casos, um erro é retornado.

A tabela a seguir lista todos os operadores do Cloud Spanner SQL da precedência mais alta à mais baixa, isto é, na ordem em que são avaliados em uma declaração.

Ordem de precedência	Operador	Tipos de dados de entrada	Nome	Arity do operador
1	.	STRUCT	Operador de acesso ao campo do membro	Binário
	[ ]	ARRAY	Posição da matriz. Precisa ser usado com OFFSET ou ORDINAL. Consulte Funções Array .	Binário
2	+	Todos os tipos numéricos	Mais unário.	Unário
	-	Todos os tipos numéricos	Unário menos	Unário
	~	Inteiro ou BYTES	Bit a bit NOT	Unário
3	*	Todos os tipos numéricos	Multiplicação	Binário
	/	Todos os tipos numéricos	Divisão	Binário
	||	STRING, BYTES ou ARRAY<T>	Operador de concatenação	Binário
4	+	Todos os tipos numéricos	Adição	Binário
	-	Todos os tipos numéricos	Subtração	Binário
5	<<	Inteiro ou BYTES	Bit a bit deslocado para a esquerda	Binário
	>>	Inteiro ou BYTES	Bit a bit deslocado para a direita	Binário
6	&	Inteiro ou BYTES	Bit a bit and	Binário
7	^	Inteiro ou BYTES	Bit a bit xor	Binário
8	|	Inteiro ou BYTES	Bit a bit or	Binário
9 (operadores de comparação)	=	Qualquer tipo comparável. Para ver uma lista completa, consulte Tipos de dados.	Igual	Binário
	<	Qualquer tipo comparável. Para ver uma lista completa, consulte Tipos de dados.	Menos de	Binário
	>	Qualquer tipo comparável. Para ver uma lista completa, consulte Tipos de dados.	Maior que	Binário
	<=	Qualquer tipo comparável. Para ver uma lista completa, consulte Tipos de dados.	Menor que ou igual a	Binário
	>=	Qualquer tipo comparável. Para ver uma lista completa, consulte Tipos de dados.	Maior que ou igual a	Binário
	!=, <>	Qualquer tipo comparável. Para ver uma lista completa, consulte Tipos de dados.	Diferente	Binário
	[NOT] LIKE	STRING e byte	O valor [não] corresponde ao padrão especificado	Binário
	[NOT] BETWEEN	Qualquer tipo comparável. Para ver uma lista completa, consulte Tipos de dados.	O valor [não] está dentro do intervalo especificado	Binário
	[NOT] IN	Qualquer tipo comparável. Para ver uma lista completa, consulte Tipos de dados.	O valor [não] está no grupo de valores especificados	Binário
	IS [NOT] NULL	Todos	O valor [não] é NULL	Unário
	IS [NOT] TRUE	BOOL	O valor [não] é TRUE.	Unário
	IS [NOT] FALSE	BOOL	O valor [não] é FALSE.	Unário
10	NOT	BOOL	Lógico NOT	Unário
11	AND	BOOL	Lógico AND	Binário
12	OR	BOOL	Lógico OR	Binário

Os operadores com a mesma precedência são associativos da esquerda, ou seja, são agrupados da esquerda para a direita. Por exemplo, a expressão:

x AND y AND z

é interpretada como

( ( x AND y ) AND z )

A expressão:

x * y / z

é interpretada como:

( ( x * y ) / z )

Todos os operadores de comparação têm a mesma prioridade, mas eles não são associativos. Portanto, é preciso usar parênteses para resolver ambiguidade. Por exemplo:

(x < y) IS FALSE

Operadores de acesso ao elemento

Operador	Sintaxe	Tipos de dados de entrada	Tipo de dados de resultado	Descrição
.	expression.fieldname1...	STRUCT	Tipo T armazenado em nomedocampo1	Operador de ponto. Pode ser usado para acessar campos aninhados, como expressão.nomedocampo1.nomedocampo2...
[ ]	matriz_expressão [posição_palavra-chave (int_expressão ) ]	Consulte Funções ARRAY	Tipo T armazenado em ARRAY	position_keyword pode ser OFFSET ou ORDINAL. Consulte Funções ARRAY para saber mais sobre as duas funções que usam esse operador.

Operadores aritméticos

Todos os operadores aritméticos aceitam a entrada do tipo numérico T, também presente no tipo de resultado, a menos que indicado de outra forma na descrição abaixo:

Nome	Sintaxe
Adição	X + Y
Subtração	X - Y
Multiplicação	X * Y
Divisão	X / Y
Mais unário.	+ X
Unário menos	- X

NOTA: as operações de divisão por zero retornam um erro. Para retornar um resultado diferente, considere as funções IEEE_DIVIDE ou SAFE_DIVIDE.

Tipos de resultados para adição, subtração e multiplicação:

INPUT	INT64	NUMERIC	FLOAT64
INT64	INT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

Tipos de resultados para divisão:

INPUT	INT64	NUMERIC	FLOAT64
INT64	FLOAT64	NUMERIC	FLOAT64
NUMERIC	NUMERIC	NUMERIC	FLOAT64
FLOAT64	FLOAT64	FLOAT64	FLOAT64

Tipos de resultados para Unary Plus:

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	INT64	NUMERIC	FLOAT64

Tipos de resultados para Unário menos:

INPUT	INT64	NUMERIC	FLOAT64
OUTPUT	INT64	NUMERIC	FLOAT64

Operadores bit a bit

Todos os operadores bit a bit retornam o mesmo tipo e comprimento do primeiro operando.

Nome	Sintaxe	Tipo de dados de entrada	Descrição
Bit a bit not	~ X	Inteiro ou BYTES	Executa a negação lógica em cada bit, formando o complemento dos números um do valor binário.
Bit a bit or	X | Y	X: número inteiro ou BYTES Y: o mesmo tipo que X	Toma dois padrões de bits de comprimento igual e executa a operação lógica OR inclusiva em cada par dos bits correspondentes. Esse operador gerará um erro se X e Y forem BYTES de comprimentos diferentes.
Bit a bit xor	X ^ Y	X: número inteiro ou BYTES Y: o mesmo tipo que X	Toma dois padrões de bits de comprimento igual e executa a operação lógica OR exclusiva em cada par dos bits correspondentes. Esse operador gerará um erro se X e Y forem BYTES de comprimentos diferentes.
Bit a bit and	X & Y	X: número inteiro ou BYTES Y: o mesmo tipo que X	Toma dois padrões de bits de comprimento igual e executa a operação lógica AND em cada par dos bits correspondentes. Esse operador gerará um erro se X e Y forem BYTES de comprimentos diferentes.
Deslocado para a esquerda	X << Y	X: número inteiro ou BYTES Y: INT64	Desloca o primeiro operando X para a esquerda. Esse operador retorna 0 ou uma sequência de bytes de b'\x00' se o segundo operando, Y, for maior ou igual ao comprimento do bit do primeiro operando, X, (por exemplo, 64, se X tiver o tipo INT64). Esse operador gerará um erro se Y for negativo.
Deslocado para a direita	X >> Y	X: número inteiro ou BYTES Y: INT64	Desloca o primeiro operando X para a direita. Esse operador não faz a extensão de bit de sinal com um tipo com sinal. Isso significa que ele preenche com 0 os bits vagos à esquerda. Esse operador retorna 0 ou uma sequência de bytes de b'\x00' se o segundo operando, Y, for maior ou igual ao comprimento do bit do primeiro operando, X, (por exemplo, 64, se X tiver o tipo INT64). Esse operador gerará um erro se Y for negativo.

Operadores lógicos

O Cloud Spanner SQL é compatível com os operadores lógicos AND, OR e NOT. Os operadores lógicos permitem apenas entradas BOOL ou NULL e usam lógica de três valores (em inglês) para produzir um resultado. O resultado pode ser TRUE, FALSE ou NULL:

x	y	x AND y	x OR y
TRUE	TRUE	TRUE	TRUE
TRUE	FALSE	FALSE	TRUE
TRUE	NULL	NULL	TRUE
FALSE	TRUE	FALSE	TRUE
FALSE	FALSE	FALSE	FALSE
FALSE	NULL	FALSE	NULL
NULL	TRUE	NULL	TRUE
NULL	FALSE	FALSE	NULL
NULL	NULL	NULL	NULL

x	NOT X
TRUE	FALSE
FALSE	TRUE
NULL	NULL

Por exemplo

Os exemplos nesta seção fazem referência a uma tabela chamada entry_table:

+-------+
| entry |
+-------+
| a     |
| b     |
| c     |
| NULL  |
+-------+

SELECT 'a' FROM entry_table WHERE entry = 'a'

-- a => 'a' = 'a' => TRUE
-- b => 'b' = 'a' => FALSE
-- NULL => NULL = 'a' => NULL

+-------+
| entry |
+-------+
| a     |
+-------+

SELECT entry FROM entry_table WHERE NOT (entry = 'a')

-- a => NOT('a' = 'a') => NOT(TRUE) => FALSE
-- b => NOT('b' = 'a') => NOT(FALSE) => TRUE
-- NULL => NOT(NULL = 'a') => NOT(NULL) => NULL

+-------+
| entry |
+-------+
| b     |
| c     |
+-------+

SELECT entry FROM entry_table WHERE entry IS NULL

-- a => 'a' IS NULL => FALSE
-- b => 'b' IS NULL => FALSE
-- NULL => NULL IS NULL => TRUE

+-------+
| entry |
+-------+
| NULL  |
+-------+

Operadores de comparação

As comparações sempre retornam BOOL. Elas geralmente exigem que os dois operandos sejam do mesmo tipo. Se os operandos forem de tipos diferentes e o Cloud Spanner SQL puder converter os valores desses tipos em um tipo comum sem perda de precisão, ele geralmente os coagirá a esse tipo comum para a comparação. O Cloud Spanner SQL geralmente coage literais ao tipo não literal, quando o primeiro tipo está presente. Os tipos de dados comparáveis são definidos na seção Tipos de dados.

STRUCTs aceitam apenas quatro operadores de comparação: igual (=), diferente (!= e <>) e IN.

As regras a seguir são aplicadas na comparação desses tipos de dados:

• FLOAT64: todas as comparações com NaN retornam FALSE, exceto != e <>, que retornam TRUE.
• BOOL: FALSE é menor que TRUE.
• STRING: as strings são comparadas ponto de código a ponto de código. Isso significa que strings canonicamente equivalentes somente serão comparadas como iguais se tiverem sido normalizadas primeiro.
• NULL: A convenção é válida aqui: qualquer operação com uma entrada NULL retorna NULL.

Nome	Sintaxe	Descrição
Menor que	X < Y	Retorna TRUE, se X for menor que Y.
Menor que ou igual a	X <= Y	Retorna TRUE, se X for menor que ou igual a Y.
Maior que	X > Y	Retorna TRUE, se X for maior que Y.
Maior que ou igual a	X >= Y	Retorna TRUE, se X for maior que ou igual a Y.
Igual	X = Y	Retorna TRUE, se X for igual a Y.
Diferente	X != Y X <> Y	Retorna TRUE, se X não for igual a Y.
BETWEEN	X [NOT] BETWEEN Y AND Z	Retorna TRUE, se X [não] estiver dentro do intervalo especificado. O resultado de "X BETWEEN Y AND Z" é equivalente a "Y <= X AND X <= Z", mas X é avaliado somente uma vez no primeiro.
LIKE	X [NOT] LIKE Y	Verifica se a STRING no primeiro operando, X, corresponde a um padrão especificado pelo segundo operando, Y. As expressões podem conter estes caracteres: Um sinal de porcentagem "%" corresponde a qualquer número de caracteres ou bytes. Um sublinhado "_" corresponde a um único caractere ou byte. É possível inserir um caractere de escape em "\", "_" ou "%" usando duas barras invertidas. Por exemplo, "\\%". Se você estiver usando strings brutas, basta uma barra invertida. Por exemplo, r"\%";
IN	Várias - veja abaixo	Retorna FALSE se o operando à direita estiver vazio. Retorna NULL se o operando à esquerda for NULL. Retorna TRUE ou NULL, nunca FALSE, se o operando à direita contiver NULL. Os argumentos em qualquer lado do operador IN são expressões gerais. Nenhum operando precisa ser um literal, embora seja mais comum usar um literal à direita. X é avaliado apenas uma vez.

Quando a igualdade dos valores com tipo de dados STRUCT é testada, é possível que um ou mais campos sejam NULL. Nesses casos:

• Se todos os valores de campo não NULL forem iguais, a comparação retornará NULL.
• Se qualquer valor de campo não NULL for diferente, a comparação retornará FALSE.

A tabela a seguir demonstra como os tipos de dados STRUCT são comparados quando têm campos com valores NULL.

Struct1	Struct2	Struct1 = Struct2
STRUCT(1, NULL)	STRUCT(1, NULL)	NULL
STRUCT(1, NULL)	STRUCT(2, NULL)	FALSE
STRUCT(1,2)	STRUCT(1, NULL)	NULL

Operadores IN

O operador IN aceita estas sintaxes:

x [NOT] IN (y, z, ... ) # Requires at least one element
x [NOT] IN (<subquery>)
x [NOT] IN UNNEST(<array expression>) # analysis error if the expression
                                      # does not return an ARRAY type.

Os argumentos em qualquer lado do operador IN são expressões gerais. É comum o uso de literais na expressão do lado direito. No entanto, isso não é obrigatório.

A semântica de:

x IN (y, z, ...)

é definida como equivalente a

(x = y) OR (x = z) OR ...

e os formatos de subconsulta e matriz são definidos de maneira semelhante.

x NOT IN ...

é equivalente a:

NOT(x IN ...)

O formato UNNEST trata uma varredura de matriz como UNNEST na cláusula FROM:

x [NOT] IN UNNEST(<array expression>)

Esse formato é usado muitas vezes com parâmetros ARRAY. Por exemplo:

x IN UNNEST(@array_parameter)

Observação: um ARRAY NULL será tratado de maneira equivalente a um ARRAY vazio.

Consulte o tópico Matrizes para mais informações sobre como usar essa sintaxe.

Quando o operador IN é usado, aplica-se a seguinte semântica:

• IN com uma expressão vazia do lado direito é sempre FALSE.
• IN com uma expressão NULL do lado esquerdo e uma expressão não vazia do lado direito é sempre NULL.
• IN com NULL na lista IN retorna somente TRUE ou NULL, nunca FALSE.
• NULL IN (NULL) retorna NULL.
• IN UNNEST(<NULL array>) retorna FALSE (não NULL).
• NOT IN com NULL na lista IN retorna somente FALSE ou NULL, nunca TRUE.

IN pode ser usado com chaves de várias partes usando a sintaxe struct do construtor. Exemplo:

(Key1, Key2) IN ( (12,34), (56,78) )
(Key1, Key2) IN ( SELECT (table.a, table.b) FROM table )

Para mais informações sobre essa sintaxe, consulte a seção Tipo struct do tópico Tipos de dados.

Operadores IS

Os operadores IS retornam TRUE ou FALSE para a condição que estão testando. Eles nunca retornam NULL, mesmo para entradas NULL, ao contrário das funções IS_INF e IS_NAN, definidas em Funções matemáticas. Se NOT estiver presente, o valor de saída BOOL será invertido.

Sintaxe da função	Tipo de dados de entrada	Tipo de dados de resultado	Descrição
X IS [NOT] NULL	Qualquer tipo de valor	BOOL	Retorna TRUE se o operando X for avaliado como NULL. Caso contrário, retorna FALSE.
X IS [NOT] TRUE	BOOL	BOOL	Retorna TRUE, se o operando BOOL for avaliado como TRUE. Caso contrário, retorna FALSE.
X IS [NOT] FALSE	BOOL	BOOL	Retorna TRUE se o operando BOOL for avaliado como FALSE. Caso contrário, retorna FALSE.

Operador de concatenação

O operador de concatenação combina vários valores em um.

Sintaxe da função	Tipo de dados de entrada	Tipo de dados de resultado
STRING || STRING [ || ... ]	STRING	STRING
BYTES || BYTES [ || ... ]	BYTES	STRING
ARRAY<T> || ARRAY<T> [ || ... ]	ARRAY<T>	ARRAY<T>