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 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. Menor que 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 Quaisquer tipos comparáveis. Para ver uma lista completa, consulte Tipos de dados. O valor [não] está dentro do intervalo especificado Binário
  [NOT] IN Quaisquer tipos comparáveis. 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
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 e multiplicação:

 INT64FLOAT64
INT64INT64FLOAT64
FLOAT64FLOAT64FLOAT64

Tipos de resultados para subtração:

 INT64FLOAT64
INT64INT64FLOAT64
FLOAT64FLOAT64FLOAT64

Tipos de resultados para divisão:

 INT64FLOAT64
INT64FLOAT64FLOAT64
FLOAT64FLOAT64FLOAT64

Tipos de resultados para Unário menos:

Tipo de dados de entrada Tipo de dados de resultado
INT64 INT64
FLOAT64 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

Todos os operadores lógicos permitem apenas a entrada BOOL.

Nome Sintaxe Descrição
Lógico NOT NOT X Retorna FALSE se a entrada for TRUE. Retorna TRUE se a entrada for FALSE. Caso contrário, retorna NULL.
Lógico AND X AND Y Retorna FALSE se pelo menos uma entrada for FALSE. Retorna TRUE se X e Y forem TRUE. Caso contrário, retorna NULL.
Lógico OR X OR Y Retorna FALSE se X e Y forem FALSE. Retorna TRUE se pelo menos uma entrada for TRUE. Caso contrário, retorna 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. 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>