As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# AWS Clean Rooms Funções do Spark SQL
AWS Clean Rooms O Spark SQL é compatível com as seguintes funções SQL:
**Topics**
+ [Funções agregadas](sql-functions-agg-spark.md)
+ [Funções de array](Array_Functions.md)
+ [Expressões condicionais](sql-functions-conditional-expressions-spark.md)
+ [Funções do construtor](sql-functions-constructor.md)
+ [Funções de formatação de tipo de dados](Data_type_formatting.md)
+ [Perfis de data e hora](date-time-functions-spark.md)
+ [Funções de criptografia e descriptografia](encryption-decryption-functions.md)
+ [Funções de hash](s_hash-functions.md)
+ [Funções do Hyperloglog](hyperloglog-functions.md)
+ [Funções JSON](json-functions-spark.md)
+ [Funções matemáticas](Math_functions-spark.md)
+ [Funções escalares](scalar_functions.md)
+ [Funções de string](String_functions_spark.md)
+ [Funções relacionadas à privacidade](privacy-related-functions.md)
+ [Funções de janela](Window_functions.md)
# Funções agregadas
As funções agregadas no AWS Clean Rooms Spark SQL são usadas para realizar cálculos ou operações em um grupo de linhas e retornar um único valor. Eles são essenciais para tarefas de análise e resumo de dados.
AWS Clean Rooms O Spark SQL é compatível com as seguintes funções agregadas:
**Topics**
+ [Função ANY\$1VALUE](ANY_VALUE.md)
+ [Função APPROX COUNT\$1DISTINCT](approx-count-distinct.md)
+ [Função PERCENTILE APROXIMADA](approx-percentile.md)
+ [Função AVG](avg-function.md)
+ [Função BOOL\$1AND](BOOL_AND.md)
+ [Função BOOL\$1OR](BOOL_OR.md)
+ [Função CARDINALITY](CARDINALITY.md)
+ [função COLLECT\$1LIST](COLLECT_LIST.md)
+ [função COLLECT\$1SET](COLLECT_SET.md)
+ [Funções COUNT e COUNT DISTINCT](count-function.md)
+ [Função COUNT](COUNT.md)
+ [Função MAX](MAX.md)
+ [Função MEDIAN](MEDIAN.md)
+ [Função MIN](MIN.md)
+ [Função PERCENTILE](percentile.md)
+ [Função SKEWNESS](SKEWNESS.md)
+ [Funções STDDEV\$1SAMP e STDDEV\$1POP](STDDEV_functions.md)
+ [Funções SUM e SUM DISTINCT](sum-function.md)
+ [Funções VAR\$1SAMP e VAR\$1POP](VARIANCE_functions.md)
# Função ANY\$1VALUE
A função ANY\$1VALUE retorna qualquer valor dos valores de expressão de entrada não deterministicamente. Esta função pode retornar NULL se a expressão de entrada não resultar no retorno de nenhuma linha.
## Sintaxe
```
ANY_VALUE (expression[, isIgnoreNull] )
```
## Argumentos
*expressão*
A coluna ou expressão de destino na qual a função opera. A *expressão* é um destes tipos de dados:
*isIgnoreNull*
Um booleano que determina se a função deve retornar somente valores não nulos.
## Retornos
Retorna o mesmo tipo de dados da *expressão*.
## Observações de uso
Se uma instrução que especifica a função ANY\$1VALUE para uma coluna também incluir uma segunda referência de coluna, a segunda coluna deve aparecer em uma cláusula GROUP BY ou ser incluída em uma função agregada.
## Exemplos
O exemplo a seguir exibe uma instância de qualquer `dateid` em que o `eventname` seja `Eagles`.
```
select any_value(dateid) as dateid, eventname from event where eventname ='Eagles' group by eventname;
```
A seguir estão os resultados.
```
dateid | eventname
-------+---------------
1878 | Eagles
```
O exemplo a seguir exibe uma instância de qualquer `dateid` em que o `eventname` seja `Eagles` ou `Cold War Kids`.
```
select any_value(dateid) as dateid, eventname from event where eventname in('Eagles', 'Cold War Kids') group by eventname;
```
A seguir estão os resultados.
```
dateid | eventname
-------+---------------
1922 | Cold War Kids
1878 | Eagles
```
# Função APPROX COUNT\$1DISTINCT
APPROX COUNT\$1DISTINCT fornece uma maneira eficiente de estimar o número de valores exclusivos em uma coluna ou conjunto de dados.
## Sintaxe
```
approx_count_distinct(expr[, relativeSD])
```
## Argumentos
*expr*
A expressão ou coluna para a qual você deseja estimar o número de valores exclusivos.
Pode ser uma única coluna, uma expressão complexa ou uma combinação de colunas.
*SD relativo*
Um parâmetro opcional que especifica o desvio padrão relativo desejado da estimativa.
É um valor entre 0 e 1, representando o erro relativo máximo aceitável da estimativa. Um valor menor de RelativeSD resultará em uma estimativa mais precisa, porém mais lenta.
Se esse parâmetro não for fornecido, um valor padrão (geralmente em torno de 0,05 ou 5%) será usado.
## Retornos
Retorna a cardinalidade estimada em HyperLogLog \$1\$1. RelativeSD define o desvio padrão relativo máximo permitido.
## Exemplo
A consulta a seguir estima o número de valores exclusivos na `col1` coluna, com um desvio padrão relativo de 1% (0,01).
```
SELECT approx_count_distinct(col1, 0.01)
```
A consulta a seguir estima que há 3 valores exclusivos na `col1` coluna (os valores 1, 2 e 3).
```
SELECT approx_count_distinct(col1) FROM VALUES (1), (1), (2), (2), (3) tab(col1)
```
# Função PERCENTILE APROXIMADA
O PERCENTILE APROXIMADO é usado para estimar o valor percentual de uma determinada expressão ou coluna sem precisar classificar todo o conjunto de dados. Essa função é útil em cenários em que você precisa entender rapidamente a distribuição de um grande conjunto de dados ou rastrear métricas baseadas em percentis, sem a sobrecarga computacional de realizar um cálculo de percentil exato. No entanto, é importante entender as vantagens e desvantagens entre velocidade e precisão e escolher a tolerância de erro apropriada com base nos requisitos específicos do seu caso de uso.
## Sintaxe
```
APPROX_PERCENTILE(expr, percentile [, accuracy])
```
## Argumentos
*expr*
A expressão ou coluna para a qual você deseja estimar o valor do percentil.
Pode ser uma única coluna, uma expressão complexa ou uma combinação de colunas.
*percentil*
O valor do percentil que você deseja estimar, expresso como um valor entre 0 e 1.
Por exemplo, 0,5 corresponderia ao 50º percentil (mediana).
*precisão*
Um parâmetro opcional que especifica a precisão desejada da estimativa do percentil. É um valor entre 0 e 1, representando o erro relativo máximo aceitável da estimativa. Um `accuracy` valor menor resultará em uma estimativa mais precisa, porém mais lenta. Se esse parâmetro não for fornecido, um valor padrão (geralmente em torno de 0,05 ou 5%) será usado.
## Retornos
Retorna o percentil aproximado da coluna de intervalo numérico ou ANSI col, que é o menor valor nos valores de col ordenados (classificados do menor para o maior), de forma que não mais do que a porcentagem dos valores de col seja menor que o valor ou igual a esse valor.
O valor da porcentagem deve estar entre 0,0 e 1,0. O parâmetro de precisão (padrão: 10000) é um literal numérico positivo que controla a precisão da aproximação ao custo da memória.
Um valor mais alto de precisão gera melhor precisão, `1.0/accuracy` é o erro relativo da aproximação.
Quando a porcentagem é uma matriz, cada valor da matriz de porcentagem deve estar entre 0,0 e 1,0. Nesse caso, retorna a matriz de percentis aproximada da coluna col na matriz de porcentagem fornecida.
## Exemplos
A consulta a seguir estima o 95º percentil da `response_time` coluna, com um erro relativo máximo de 1% (0,01).
```
SELECT APPROX_PERCENTILE(response_time, 0.95, 0.01) AS p95_response_time
FROM my_table;
```
A consulta a seguir estima os valores dos percentis 50, 40 e 10 da coluna na `col` tabela. `tab`
```
SELECT approx_percentile(col, array(0.5, 0.4, 0.1), 100) FROM VALUES (0), (1), (2), (10) AS tab(col)
```
A consulta a seguir estima o 50º percentil (mediana) dos valores na coluna col.
```
SELECT approx_percentile(col, 0.5, 100) FROM VALUES (0), (6), (7), (9), (10) AS tab(col)
```
# Função AVG
A função AVG retorna a média (média aritmética) dos valores da expressão de entrada. A função AVG trabalha com valores numéricos e ignora valores NULL.
## Sintaxe
```
AVG (column)
```
## Argumentos
*column*
A coluna de destino na qual a função opera. A coluna é um dos seguintes tipos de dados:
+ SMALLINT
+ INTEGER
+ BIGINT
+ DECIMAL
+ DOUBLE
+ FLOAT
## Tipos de dados
Os tipos de argumentos suportados pela função AVG são SMALLINT, INTEGER, BIGINT, DECIMAL e DOUBLE.
Os tipos de retorno suportados pela função AVG são:
+ BIGINT para qualquer argumento de tipo inteiro
+ DOUBLE para um argumento de ponto flutuante
+ Retorna o mesmo tipo de dados que a expressão para qualquer outro tipo de argumento
A precisão padrão para um resultado de função AVG com um argumento DECIMAL é 38. A escala do resultado é a mesma que a escala do argumento. Por exemplo, um AVG de uma coluna DEC(5,2) de a retorna um tipo de dados DEC(38,2).
## Exemplo
Encontre a quantidade média vendida por transação na tabela SALES.
```
select avg(qtysold) from sales;
```
# Função BOOL\$1AND
A função BOOL\$1AND opera em uma única coluna ou expressão de boolianos ou inteiros. Essa função aplica lógica semelhante às funções BIT\$1AND e BIT\$1OR. Para essa função, o tipo de retorno é um valor booliano (`true` ou `false`).
Se todos os valores em um conjunto forem verdadeiros, a função BOOL\$1AND retorna `true` (`t`). Se qualquer valor for falso, a função retorna `false` (`f`).
## Sintaxe
```
BOOL_AND ( [DISTINCT | ALL] expression )
```
## Argumentos
*expressão*
A coluna ou expressão de destino na qual a função opera. Essa expressão deve ter um tipo de dados BOOLEAN ou de inteiros. O tipo de retorno da função é BOOLEAN.
DISTINCT \$1 ALL
Com o argumento DISTINCT, a função elimina todos os valores duplicados para a expressão especificada antes de calcular o resultado. Com o argumento ALL, a função retém todos os valores duplicados. ALL é o padrão.
## Exemplos
Você pode usar as funções booleanas com expressões booleanas ou expressões de inteiro.
Por exemplo, o seguinte retorno de consulta resultada da tabela USERS padrão no banco de dados TICKIT, que tem várias colunas booleanas.
A função BOOL\$1AND retorna `false` para todas as cinco linhas. Nem todos os usuários em cada um dos estados gostam de esportes.
```
select state, bool_and(likesports) from users
group by state order by state limit 5;
state | bool_and
------+---------
AB | f
AK | f
AL | f
AZ | f
BC | f
(5 rows)
```
# Função BOOL\$1OR
A função BOOL\$1OR opera em uma única coluna ou expressão de boolianos ou inteiros. Essa função aplica lógica semelhante às funções BIT\$1AND e BIT\$1OR. Para essa função, o tipo de retorno é um valor booliano (`true`, `false` ou `NULL`).
Se um valor de um conjunto for `true`, a função BOOL\$1OR retornará `true` (`t`). Se um valor de um conjunto for `false`, a função retornará `false` (`f`). NULL poderá ser retornado se o valor for desconhecido.
## Sintaxe
```
BOOL_OR ( [DISTINCT | ALL] expression )
```
## Argumentos
*expressão*
A coluna ou expressão de destino na qual a função opera. Essa expressão deve ter um tipo de dados BOOLEAN ou de inteiros. O tipo de retorno da função é BOOLEAN.
DISTINCT \$1 ALL
Com o argumento DISTINCT, a função elimina todos os valores duplicados para a expressão especificada antes de calcular o resultado. Com o argumento ALL, a função retém todos os valores duplicados. ALL é o padrão.
## Exemplos
Você pode usar as funções booleanas com expressões booleanas ou expressões de inteiro. Por exemplo, o seguinte retorno de consulta resultada da tabela USERS padrão no banco de dados TICKIT, que tem várias colunas booleanas.
A função BOOL\$1OR retorna `true` para todas as cinco linhas. Pelo menos um usuário em cada um dos estados gosta de esportes.
```
select state, bool_or(likesports) from users
group by state order by state limit 5;
state | bool_or
------+--------
AB | t
AK | t
AL | t
AZ | t
BC | t
(5 rows)
```
O exemplo a seguir retorna NULL.
```
SELECT BOOL_OR(NULL = '123')
bool_or
------
NULL
```
# Função CARDINALITY
A função CARDINALITY retorna o tamanho de uma expressão ARRAY ou MAP (*expr*).
Essa função é útil para encontrar o tamanho ou o comprimento de uma matriz.
## Sintaxe
```
cardinality(expr)
```
## Argumentos
*expr*
Uma expressão ARRAY ou MAP.
## Retornos
Retorna o tamanho de uma matriz ou mapa (INTEGER).
A função retorna `NULL` para entrada nula se `sizeOfNull` estiver definida como `false` ou `enabled` definida como. `true`
Caso contrário, a função retornará `-1` para entrada nula. Com as configurações padrão, a função retorna `-1` para entrada nula.
## Exemplo
A consulta a seguir calcula a cardinalidade, ou o número de elementos, na matriz fornecida. O array (`'b', 'd', 'c', 'a'`) tem 4 elementos, então a saída dessa consulta seria`4`.
```
SELECT cardinality(array('b', 'd', 'c', 'a'));
4
```
# função COLLECT\$1LIST
A função COLLECT\$1LIST coleta e retorna uma lista de elementos não exclusivos.
Esse tipo de função é útil quando você deseja coletar vários valores de um conjunto de linhas em uma única matriz ou estrutura de dados de lista.
**nota**
A função não é determinística porque a ordem dos resultados coletados depende da ordem das linhas, que pode não ser determinística após a execução de uma operação aleatória.
## Sintaxe
```
collect_list(expr)
```
## Argumentos
*expr*
Uma expressão de qualquer tipo.
## Retornos
Retorna um ARRAY do tipo de argumento. A ordem dos elementos na matriz não é determinística.
Valores NULL são excluídos.
Se DISTINCT for especificado, a função coletará somente valores exclusivos e será sinônimo de função `collect_set ` agregada.
## Exemplo
A consulta a seguir coleta todos os valores da coluna col em uma lista. A `VALUES` cláusula é usada para criar uma tabela embutida com três linhas, em que cada linha tem uma única coluna com os valores 1, 2 e 1, respectivamente. A `collect_list() ` função é então usada para agregar todos os valores da coluna col em uma única matriz. A saída dessa instrução SQL seria a matriz`[1,2,1]`, que contém todos os valores da coluna col na ordem em que eles aparecem nos dados de entrada.
```
SELECT collect_list(col) FROM VALUES (1), (2), (1) AS tab(col);
[1,2,1]
```
# função COLLECT\$1SET
A função COLLECT\$1SET coleta e retorna um conjunto de elementos exclusivos.
Essa função é útil quando você deseja coletar todos os valores distintos de um conjunto de linhas em uma única estrutura de dados, sem incluir duplicatas.
**nota**
A função não é determinística porque a ordem dos resultados coletados depende da ordem das linhas, que pode não ser determinística após a execução de uma operação aleatória.
## Sintaxe
```
collect_set(expr)
```
## Argumentos
*expr*
Uma expressão de qualquer tipo, exceto MAP.
## Retornos
Retorna um ARRAY do tipo de argumento. A ordem dos elementos na matriz não é determinística.
Valores NULL são excluídos.
## Exemplo
A consulta a seguir coleta todos os valores exclusivos da coluna col em um conjunto. A `VALUES` cláusula é usada para criar uma tabela embutida com três linhas, em que cada linha tem uma única coluna com os valores 1, 2 e 1, respectivamente. A `collect_set()` função é então usada para agregar todos os valores exclusivos da coluna col em um único conjunto. A saída dessa instrução SQL seria o conjunto`[1,2]`, que contém os valores exclusivos da coluna col. O valor duplicado de 1 só é incluído uma vez no resultado.
```
SELECT collect_set(col) FROM VALUES (1), (2), (1) AS tab(col);
[1,2]
```
# Funções COUNT e COUNT DISTINCT
A função COUNT conta as linhas definidas pela expressão. A função COUNT DISTINCT calcula o número de valores distintos não NULL em uma coluna ou uma expressão. Ela elimina todos os valores duplicados da expressão especificada antes de realizar a contagem.
## Sintaxe
```
COUNT (DISTINCT column)
```
## Argumentos
*column*
A coluna de destino na qual a função opera.
## Tipos de dados
As funções COUNT e COUNT DISTINCT comportam todos os tipos de dados de argumento.
A função COUNT DISTINCT exibe BIGINT.
## Exemplos
Conte todos os usuários do Estado da Flórida.
```
select count (identifier) from users where state='FL';
```
Conte todo o local exclusivo IDs da EVENT mesa.
```
select count (distinct venueid) as venues from event;
```
# Função COUNT
A função COUNT conta as linhas definidas pela expressão.
A função COUNT tem as variações a seguir.
+ COUNT ( \$1 ) conta todas as linhas na tabela de destino independente se elas contêm nulls ou não.
+ COUNT ( *expressão* ) computa o número de linhas com valores não NULL em uma coluna ou expressão específica.
+ COUNT ( *expressão* DISTINCT ) computa o número de valores distintos não NULL em uma coluna ou expressão.
## Sintaxe
```
COUNT( * | expression )
```
```
COUNT ( [ DISTINCT | ALL ] expression )
```
## Argumentos
*expressão*
A coluna ou expressão de destino na qual a função opera. A função COUNT é compatível com todos os tipos de dados de argumento.
DISTINCT \$1 ALL
Com o argumento DISTINCT, a função elimina todos os valores duplicados da expressão especificada antes realizar a contagem. Com o argumento ALL, a função retém todos os valores duplicados da expressão para contagem. ALL é o padrão.
## Tipo de retorno
A função COUNT retorna BIGINT.
## Exemplos
Conte todos os usuários do estado da Flórida:
```
select count(*) from users where state='FL';
count
-------
510
```
Conte todos os nomes de eventos da tabela EVENT:
```
select count(eventname) from event;
count
-------
8798
```
Conte todos os nomes de eventos da tabela EVENT:
```
select count(all eventname) from event;
count
-------
8798
```
Conte todos os locais exclusivos IDs da tabela do EVENTO:
```
select count(distinct venueid) as venues from event;
venues
--------
204
```
Conte o número de vezes que cada vendedor listou lotes de um ou mais ingressos para venda. Agrupe os resultados por ID de vendedor:
```
select count(*), sellerid from listing
where numtickets > 4
group by sellerid
order by 1 desc, 2;
count | sellerid
------+----------
12 | 6386
11 | 17304
11 | 20123
11 | 25428
...
```
# Função MAX
A função MAX retorna o valor máximo em um conjunto de linhas. DISTINCT ou ALL podem ser usadas, mas não afetam os resultados.
## Sintaxe
```
MAX ( [ DISTINCT | ALL ] expression )
```
## Argumentos
*expressão*
A coluna ou expressão de destino na qual a função opera. A *expressão* é qualquer tipo de dado numérico.
DISTINCT \$1 ALL
Com o argumento DISTINCT, a função elimina todos os valores duplicados da expressão especificada antes de calcular o máximo. Com o argumento ALL, a função retém todos os valores duplicados da expressão para calcular o máximo. ALL é o padrão.
## Tipos de dados
Retorna o mesmo tipo de dados da *expressão*.
## Exemplos
Encontre o preço mais alto pago de todas as vendas:
```
select max(pricepaid) from sales;
max
----------
12624.00
(1 row)
```
Encontre o preço mais alto pago por ingresso em todas as vendas:
```
select max(pricepaid/qtysold) as max_ticket_price
from sales;
max_ticket_price
-----------------
2500.00000000
(1 row)
```
# Função MEDIAN
## Sintaxe
```
MEDIAN ( median_expression )
```
## Argumentos
*median\$1expression*
A coluna ou expressão de destino na qual a função opera.
# Função MIN
A função MIN retorna o valor mínimo em um conjunto de linhas. DISTINCT ou ALL podem ser usadas, mas não afetam os resultados.
## Sintaxe
```
MIN ( [ DISTINCT | ALL ] expression )
```
## Argumentos
*expressão*
A coluna ou expressão de destino na qual a função opera. A *expressão* é qualquer tipo de dado numérico.
DISTINCT \$1 ALL
Com o argumento DISTINCT, a função elimina todos os valores duplicados da expressão especificada antes de calcular o mínimo. Com o argumento ALL, a função retém todos os valores duplicados da expressão para calcular o mínimo. ALL é o padrão.
## Tipos de dados
Retorna o mesmo tipo de dados da *expressão*.
## Exemplos
Encontre o preço mais baixo pago de todas as vendas:
```
select min(pricepaid) from sales;
min
-------
20.00
(1 row)
```
Encontre o preço mais baixo pago por ingresso em todas as vendas:
```
select min(pricepaid/qtysold)as min_ticket_price
from sales;
min_ticket_price
------------------
20.00000000
(1 row)
```
# Função PERCENTILE
A função PERCENTILE é usada para calcular o valor exato do percentil, primeiro classificando os valores na `col` coluna e, em seguida, localizando o valor no especificado. `percentage`
A função PERCENTILE é útil quando você precisa calcular o valor exato do percentil e o custo computacional é aceitável para seu caso de uso. Ela fornece resultados mais precisos do que a função APPROX\$1PERCENTILE, mas pode ser mais lenta, especialmente para grandes conjuntos de dados.
Por outro lado, a função APPROX\$1PERCENTILE é uma alternativa mais eficiente que pode fornecer uma estimativa do valor do percentil com uma tolerância de erro especificada, tornando-a mais adequada para cenários em que a velocidade é uma prioridade maior do que a precisão absoluta.
## Sintaxe
```
percentile(col, percentage [, frequency])
```
## Argumentos
*resfriado*
A expressão ou coluna para a qual você deseja calcular o valor do percentil.
*porcentagem*
O valor do percentil que você deseja calcular, expresso como um valor entre 0 e 1.
Por exemplo, 0,5 corresponderia ao 50º percentil (mediana).
*frequência*
Um parâmetro opcional que especifica a frequência ou o peso de cada valor na `col` coluna. Se fornecida, a função calculará o percentil com base na frequência de cada valor.
## Retornos
Retorna o valor percentual exato da coluna numérica ou de intervalo ANSI col na porcentagem fornecida.
O valor da porcentagem deve estar entre 0,0 e 1,0.
O valor da frequência deve ser integral positiva
## Exemplo
A consulta a seguir encontra o valor maior ou igual a 30% dos valores na `col` coluna. Como os valores são 0 e 10, o 30º percentil é 3,0, porque é o valor maior ou igual a 30% dos dados.
```
SELECT percentile(col, 0.3) FROM VALUES (0), (10) AS tab(col);
3.0
```
# Função SKEWNESS
A função SKEWNESS retorna o valor de assimetria calculado a partir dos valores de um grupo.
A assimetria é uma medida estatística que descreve a assimetria ou a falta de simetria em um conjunto de dados. Ele fornece informações sobre a forma da distribuição de dados.
Essa função pode ser útil para entender as propriedades estatísticas de um conjunto de dados e informar análises adicionais ou tomadas de decisão.
## Sintaxe
```
skewness(expr)
```
## Argumentos
*expr*
Uma expressão que é avaliada como numérica.
## Retornos
Retorna em DOBRO.
Se DISTINCT for especificado, a função operará somente em um conjunto exclusivo de valores *expr.*
## Exemplos
A consulta a seguir calcula a assimetria dos valores na coluna. `col` Neste exemplo, a `VALUES` cláusula é usada para criar uma tabela embutida com quatro linhas, em que cada linha tem uma única coluna `col` com os valores -10, -20, 100 e 1000. A `skewness()` função é então usada para calcular a assimetria dos valores na `col` coluna. O resultado, 1.1135657469022011, representa o grau e a direção da distorção nos dados. Um valor de assimetria positivo indica que os dados estão inclinados para a direita, com a maior parte dos valores concentrados no lado esquerdo da distribuição. Um valor de distorção negativo indica que os dados estão inclinados para a esquerda, com a maior parte dos valores concentrados no lado direito da distribuição.
```
SELECT skewness(col) FROM VALUES (-10), (-20), (100), (1000) AS tab(col);
1.1135657469022011
```
A consulta a seguir calcula a assimetria dos valores na coluna col. Semelhante ao exemplo anterior, a `VALUES` cláusula é usada para criar uma tabela embutida com quatro linhas, em que cada linha tem uma única coluna `col` com os valores -1000, -100, 10 e 20. A `skewness()` função é então usada para calcular a assimetria dos valores na `col` coluna. O resultado, -1.1135657469022011, representa o grau e a direção da distorção nos dados. Nesse caso, o valor de assimetria negativa indica que os dados estão inclinados para a esquerda, com a maior parte dos valores concentrados no lado direito da distribuição.
```
SELECT skewness(col) FROM VALUES (-1000), (-100), (10), (20) AS tab(col);
-1.1135657469022011
```
# Funções STDDEV\$1SAMP e STDDEV\$1POP
As funções STDDEV\$1SAMP e STDDEV\$1POP retornam o desvio padrão da amostra e da população de um conjunto de valores numéricos (número inteiro, decimal ou ponto flutuante). O resultado da função STDDEV\$1SAMP é equivalente à raiz quadrada da variação de amostra do mesmo conjunto de valores.
STDDEV\$1SAMP e STDDEV são sinônimos para a mesma função.
## Sintaxe
```
STDDEV_SAMP | STDDEV ( [ DISTINCT | ALL ] expression) STDDEV_POP ( [ DISTINCT | ALL ] expression)
```
A expressão deve ter um tipo de dados numérico. Independente do tipo de dados da expressão, o tipo de retorno desta função é um número de precisão dupla.
**nota**
O desvio padrão é calculado utilizando a aritmética de ponto flutuante, que pode resultar em uma ligeira imprecisão.
## Observações de uso
Quando o desvio padrão de amostra (STDDEV ou STDDEV\$1SAMP) é calculado para uma expressão que consiste em um único valor, o resultado da função é NULL ou 0.
## Exemplos
A seguinte consulta retorna a média dos valores na coluna VENUESEATS da tabela VENUE, seguida pelo desvio padrão de amostra e desvio padrão de população do mesmo conjunto de valores. VENUESEATS é uma coluna INTEGER. A escala do resultado é reduzida a 2 dígitos.
```
select avg(venueseats),
cast(stddev_samp(venueseats) as dec(14,2)) stddevsamp,
cast(stddev_pop(venueseats) as dec(14,2)) stddevpop
from venue;
avg | stddevsamp | stddevpop
-------+------------+-----------
17503 | 27847.76 | 27773.20
(1 row)
```
A seguinte consulta retorna o desvio padrão de amostra para a coluna COMMISSION na tabela SALES. COMMISSION é uma coluna DECIMAL. A escala do resultado é reduzida a 10 dígitos.
```
select cast(stddev(commission) as dec(18,10))
from sales;
stddev
----------------
130.3912659086
(1 row)
```
A seguinte consulta converte o desvio padrão de amostra para a coluna COMMISSION para um inteiro.
```
select cast(stddev(commission) as integer)
from sales;
stddev
--------
130
(1 row)
```
A seguinte consulta retorna o desvio padrão da amostra e a raiz quadrada da variação da amostra para a coluna COMMISSION. Os resultados desses cálculos são os mesmos.
```
select
cast(stddev_samp(commission) as dec(18,10)) stddevsamp,
cast(sqrt(var_samp(commission)) as dec(18,10)) sqrtvarsamp
from sales;
stddevsamp | sqrtvarsamp
----------------+----------------
130.3912659086 | 130.3912659086
(1 row)
```
# Funções SUM e SUM DISTINCT
A função SUM retorna a soma da coluna de entrada ou dos valores da expressão. A função SUM trabalha com valores numéricos e ignora valores NULL.
A função SUM DISTINCT elimina todos os valores duplicados da expressão especificada antes de calcular a soma.
## Sintaxe
```
SUM (DISTINCT column )
```
## Argumentos
*column*
A coluna de destino na qual a função opera. A coluna é qualquer tipo de dado numérico.
## Exemplos
Encontre a soma de todas as comissões pagas na tabela SALES.
```
select sum(commission) from sales
```
Encontre a soma de todas as comissões distintas pagas na tabela SALES.
```
select sum (distinct (commission)) from sales
```
# Funções VAR\$1SAMP e VAR\$1POP
As funções VAR\$1SAMP e VAR\$1POP retornam a variação da amostra e da população de um conjunto de valores numéricos (número inteiro, decimal ou ponto flutuante). O resultado da função VAR\$1SAMP é equivalente à raiz quadrada do desvio padrão da amostra do mesmo conjunto de valores.
VAR\$1SAMP e VARIANCE são sinônimos para a mesma função.
## Sintaxe
```
VAR_SAMP | VARIANCE ( [ DISTINCT | ALL ] expression)
VAR_POP ( [ DISTINCT | ALL ] expression)
```
A expressão deve ter um tipo de dados de número inteiro, decimal ou ponto flutuante. Independente do tipo de dados da expressão, o tipo de retorno desta função é um número de precisão dupla.
**nota**
Os resultados dessas funções podem variar entre os clusters de data warehouse dependendo da configuração do cluster em cada caso.
## Observações de uso
Quando a variação da amostra (VARIANCE ou VAR\$1SAMP) é calculada para uma expressão que consiste em um único valor, o resultado da função é NULL ou 0.
## Exemplos
A seguinte consulta retorna a variação arredondada da amostra e da população para a coluna NUMTICKETS da tabela LISTING.
```
select avg(numtickets),
round(var_samp(numtickets)) varsamp,
round(var_pop(numtickets)) varpop
from listing;
avg | varsamp | varpop
-----+---------+--------
10 | 54 | 54
(1 row)
```
A seguinte consulta executa os mesmos cálculos, mas converte os resultados para valores decimais.
```
select avg(numtickets),
cast(var_samp(numtickets) as dec(10,4)) varsamp,
cast(var_pop(numtickets) as dec(10,4)) varpop
from listing;
avg | varsamp | varpop
-----+---------+---------
10 | 53.6291 | 53.6288
(1 row)
```
# Funções de array
Esta seção descreve as funções de matriz para SQL suportadas no AWS Clean Rooms.
**Topics**
+ [Função ARRAY](array.md)
+ [função ARRAY\$1CONTAINS](array_contains.md)
+ [função ARRAY\$1DISTINCT](array_distinct.md)
+ [função ARRAY\$1EXCEPT](array_except.md)
+ [função ARRAY\$1INTERSECT](array_intersect.md)
+ [função ARRAY\$1JOIN](array_join.md)
+ [função ARRAY\$1REMOVE](array_remove.md)
+ [função ARRAY\$1UNION](array_union.md)
+ [Função EXPLODE](explode.md)
+ [Função FLATTEN](flatten.md)
# Função ARRAY
Cria uma matriz com os elementos fornecidos.
## Sintaxe
```
ARRAY( [ expr1 ] [ , expr2 [ , ... ] ] )
```
## Argumento
*expr1, expr2*
Expressões de qualquer tipo de dados, exceto tipos de data e hora. Os argumentos não precisam ser do mesmo tipo de dado.
## Tipo de retorno
A função de matriz retorna uma MATRIZ com os elementos na expressão.
## Exemplo
O exemplo a seguir mostra uma matriz de valores numéricos e uma matriz de diferentes tipos de dados.
```
--an array of numeric values
select array(1,50,null,100);
array
------------------
[1,50,null,100]
(1 row)
--an array of different data types
select array(1,'abc',true,3.14);
array
-----------------------
[1,"abc",true,3.14]
(1 row)
```
# função ARRAY\$1CONTAINS
A função ARRAY\$1CONTAINS pode ser usada para realizar verificações básicas de associação em estruturas de dados de matriz. A função ARRAY\$1CONTAINS é útil quando você precisa verificar se um valor específico está presente em uma matriz.
## Sintaxe
```
array_contains(array, value)
```
## Argumentos
*array*
Uma MATRIZ a ser pesquisada.
*value*
Uma expressão com um tipo que compartilha um tipo menos comum com os elementos da matriz.
## Tipo de retorno
A função ARRAY\$1CONTAINS retorna um BOOLEAN.
Se o valor for NULL, o resultado será NULL.
Se algum elemento na matriz for NULL, o resultado será NULL se o valor não corresponder a nenhum outro elemento.
## Exemplos
O exemplo a seguir verifica se a matriz `[1, 2, 3]` contém o valor`4`. Como a matriz`[1, 2, 3`] não contém o valor`4`, a função array\$1contains retorna. `false`
```
SELECT array_contains(array(1, 2, 3), 4)
false
```
O exemplo a seguir verifica se a matriz `[1, 2, 3]` contém o valor`2`. Como a matriz `[1, 2, 3]` contém o valor`2`, a função array\$1contains retorna. `true`
```
SELECT array_contains(array(1, 2, 3), 2);
true
```
# função ARRAY\$1DISTINCT
A função ARRAY\$1DISTINCT pode ser usada para remover valores duplicados de uma matriz. A função ARRAY\$1DISTINCT é útil quando você precisa remover duplicatas de uma matriz e trabalhar somente com os elementos exclusivos. Isso pode ser útil em cenários em que você deseja realizar operações ou análises em um conjunto de dados sem a interferência de valores repetidos.
## Sintaxe
```
array_distinct(array)
```
## Argumentos
*array*
Uma expressão ARRAY.
## Tipo de retorno
A função ARRAY\$1DISTINCT retorna uma MATRIZ que contém somente os elementos exclusivos da matriz de entrada.
## Exemplos
Neste exemplo, a matriz de entrada `[1, 2, 3, null, 3]` contém um valor duplicado de`3`. A `array_distinct` função remove esse valor duplicado `3` e retorna uma nova matriz com os elementos exclusivos:`[1, 2, 3, null]`.
```
SELECT array_distinct(array(1, 2, 3, null, 3));
[1,2,3,null]
```
Neste exemplo, a matriz de entrada `[1, 2, 2, 3, 3, 3]` contém valores duplicados de `2` e. `3` A `array_distinct` função remove essas duplicatas e retorna uma nova matriz com os elementos exclusivos:`[1, 2, 3]`.
```
SELECT array_distinct(array(1, 2, 2, 3, 3, 3))
[1,2,3]
```
# função ARRAY\$1EXCEPT
A função ARRAY\$1EXCEPT usa duas matrizes como argumentos e retorna uma nova matriz que contém somente os elementos presentes na primeira matriz, mas não na segunda matriz.
O ARRAY\$1EXCEPT é útil quando você precisa encontrar os elementos que são exclusivos de uma matriz em comparação com outra. Isso pode ser útil em cenários em que você precisa realizar operações semelhantes a conjuntos em matrizes, como encontrar a diferença entre dois conjuntos de dados.
## Sintaxe
```
array_except(array1, array2)
```
## Argumentos
*matriz1*
Uma MATRIZ de qualquer tipo com elementos comparáveis.
*matriz2*
Uma MATRIZ de elementos que compartilham um tipo menos comum com os elementos de *array1*.
## Tipo de retorno
A função ARRAY\$1EXCEPT retorna um ARRAY do tipo correspondente ao *array1* sem duplicatas.
## Exemplos
Neste exemplo, a primeira matriz `[1, 2, 3]` contém os elementos 1, 2 e 3. A segunda matriz `[2, 3, 4]` contém os elementos 2, 3 e 4. A `array_except` função remove os elementos 2 e 3 da primeira matriz, pois eles também estão presentes na segunda matriz. A saída resultante é a matriz`[1]`.
```
SELECT array_except(array(1, 2, 3), array(2, 3, 4))
[1]
```
Neste exemplo, a primeira matriz `[1, 2, 3]` contém os elementos 1, 2 e 3. A segunda matriz `[1, 3, 5]` contém os elementos 1, 3 e 5. A `array_except` função remove os elementos 1 e 3 da primeira matriz, pois eles também estão presentes na segunda matriz. A saída resultante é a matriz`[2]`.
```
SELECT array_except(array(1, 2, 3), array(1, 3, 5));
[2]
```
# função ARRAY\$1INTERSECT
A função ARRAY\$1INTERSECT usa duas matrizes como argumentos e retorna uma nova matriz que contém os elementos presentes nas duas matrizes de entrada. Essa função é útil quando você precisa encontrar os elementos comuns entre duas matrizes. Isso pode ser útil em cenários em que você precisa realizar operações semelhantes a conjuntos em matrizes, como encontrar a interseção entre dois conjuntos de dados.
## Sintaxe
```
array_intersect(array1, array2)
```
## Argumentos
*matriz1*
Uma MATRIZ de qualquer tipo com elementos comparáveis.
*matriz2*
Uma MATRIZ de elementos que compartilham um tipo menos comum com os elementos de array1.
## Tipo de retorno
A função ARRAY\$1INTERSECT retorna uma MATRIZ do tipo correspondente à matriz1 sem duplicatas e elementos contidos na matriz1 e na matriz2.
## Exemplos
Neste exemplo, a primeira matriz `[1, 2, 3]` contém os elementos 1, 2 e 3. A segunda matriz `[1, 3, 5]` contém os elementos 1, 3 e 5. A função ARRAY\$1INTERSECT identifica os elementos comuns entre as duas matrizes, que são 1 e 3. A matriz de saída resultante é`[1, 3]`.
```
SELECT array_intersect(array(1, 2, 3), array(1, 3, 5));
[1,3]
```
# função ARRAY\$1JOIN
A função ARRAY\$1JOIN usa dois argumentos: o primeiro argumento é a matriz de entrada que será unida. O segundo argumento é a string separadora que será usada para concatenar os elementos da matriz. Essa função é útil quando você precisa converter uma matriz de strings (ou qualquer outro tipo de dados) em uma única string concatenada. Isso pode ser útil em cenários em que você deseja apresentar uma matriz de valores como uma única string formatada, por exemplo, para fins de exibição ou para uso em processamento posterior.
## Sintaxe
```
array_join(array, delimiter[, nullReplacement])
```
## Argumentos
*array*
Qualquer tipo de ARRAY, mas seus elementos são interpretados como strings.
*delimitador*
Uma STRING usada para separar os elementos concatenados da matriz.
*Substituição nula*
Uma STRING usada para expressar um valor NULL no resultado.
## Tipo de retorno
A função ARRAY\$1JOIN retorna uma STRING em que os elementos da matriz são separados por delimitador e os elementos nulos são substituídos. `nullReplacement` Se `nullReplacement` for omitido, os `null` elementos serão filtrados. Se houver algum argumento`NULL`, o resultado é`NULL`.
## Exemplos
Neste exemplo, a função ARRAY\$1JOIN pega a matriz `['hello', 'world']` e une os elementos usando o separador `' '` (um caractere de espaço). A saída resultante é a string`'hello world'`.
```
SELECT array_join(array('hello', 'world'), ' ');
hello world
```
Neste exemplo, a função ARRAY\$1JOIN pega a matriz `['hello', null, 'world']` e une os elementos usando o separador `' '` (um caractere de espaço). O `null` valor é substituído pela string de substituição fornecida `','` (uma vírgula). A saída resultante é a string`'hello , world'`.
```
SELECT array_join(array('hello', null ,'world'), ' ', ',');
hello , world
```
# função ARRAY\$1REMOVE
A função ARRAY\$1REMOVE usa dois argumentos: o primeiro argumento é a matriz de entrada da qual os elementos serão removidos. O segundo argumento é o valor que será removido da matriz. Essa função é útil quando você precisa remover elementos específicos de uma matriz. Isso pode ser útil em cenários em que você precisa realizar a limpeza ou o pré-processamento de dados em uma matriz de valores.
## Sintaxe
```
array_remove(array, element)
```
## Argumentos
*array*
Um ARRAY.
*Elemento*
Uma expressão de um tipo que compartilha um tipo menos comum com os elementos da matriz.
## Tipo de retorno
A função ARRAY\$1REMOVE retorna o tipo de resultado correspondente ao tipo da matriz. Se o elemento a ser removido for`NULL`, o resultado será`NULL`.
## Exemplos
Neste exemplo, a função ARRAY\$1REMOVE pega a matriz `[1, 2, 3, null, 3]` e remove todas as ocorrências do valor 3. A saída resultante é a matriz`[1, 2, null]`.
```
SELECT array_remove(array(1, 2, 3, null, 3), 3);
[1,2,null]
```
# função ARRAY\$1UNION
A função ARRAY\$1UNION usa duas matrizes como argumentos e retorna uma nova matriz que contém os elementos exclusivos de ambas as matrizes de entrada. Essa função é útil quando você precisa combinar duas matrizes e eliminar quaisquer elementos duplicados. Isso pode ser útil em cenários em que você precisa realizar operações semelhantes a conjuntos em matrizes, como encontrar a união entre dois conjuntos de dados.
## Sintaxe
```
array_union(array1, array2)
```
## Argumentos
*matriz1*
Um ARRAY.
*matriz2*
Um ARRAY do mesmo tipo que *array1*.
## Tipo de retorno
A função ARRAY\$1UNION retorna uma MATRIZ do mesmo tipo da matriz.
## Exemplo
Neste exemplo, a primeira matriz `[1, 2, 3]` contém os elementos 1, 2 e 3. A segunda matriz `[1, 3, 5]` contém os elementos 1, 3 e 5. A função ARRAY\$1UNION combina os elementos exclusivos de ambas as matrizes, resultando na matriz de saída. `[1, 2, 3, 5]` T
```
SELECT array_union(array(1, 2, 3), array(1, 3, 5));
[1,2,3,5]
```
# Função EXPLODE
A função EXPLODE é usada para transformar uma única linha com uma matriz ou coluna de mapa em várias linhas, onde cada linha corresponde a um único elemento da matriz ou do mapa.
## Sintaxe
```
explode(expr)
```
## Argumentos
*expr*
Uma expressão de matriz ou uma expressão de mapa.
## Tipo de retorno
A função EXPLODE retorna um conjunto de linhas, em que cada linha representa um único elemento da matriz ou mapa de entrada.
O tipo de dados das linhas de saída depende do tipo de dados dos elementos na matriz de entrada ou no mapa.
## Exemplos
O exemplo a seguir pega a matriz de linha única [10, 20] e a transforma em duas linhas separadas, cada uma contendo um dos elementos da matriz (10 e 20).
```
SELECT explode(array(10, 20));
```
No primeiro exemplo, a matriz de entrada foi passada diretamente como argumento para`explode()`. Neste exemplo, a matriz de entrada é especificada usando a `=>` sintaxe, em que o nome da coluna (`collection`) é fornecido explicitamente.
```
SELECT explode(array(10, 20));
```
Ambas as abordagens são válidas e alcançam o mesmo resultado, mas a segunda sintaxe pode ser mais útil quando você precisa explodir uma coluna de um conjunto de dados maior, em vez de apenas uma simples matriz literal.
# Função FLATTEN
A função FLATTEN é usada para “nivelar” uma estrutura de matriz aninhada em uma única matriz plana.
## Sintaxe
```
flatten(arrayOfArrays)
```
## Argumentos
*arrayOfArrays*
Uma matriz de matrizes.
## Tipo de retorno
A função FLATTEN retorna uma matriz.
## Exemplo
Neste exemplo, a entrada é uma matriz aninhada com duas matrizes internas e a saída é uma única matriz plana contendo todos os elementos das matrizes internas. A função FLATTEN pega a matriz aninhada `[[1, 2], [3, 4]]` e combina todos os elementos em uma única matriz. `[1, 2, 3, 4]`
```
SELECT flatten(array(array(1, 2), array(3, 4)));
[1,2,3,4]
```
# Expressões condicionais
No SQL, expressões condicionais são usadas para tomar decisões com base em determinadas condições. Eles permitem que você controle o fluxo de suas instruções SQL e retorne valores diferentes ou execute ações diferentes com base na avaliação de uma ou mais condições.
AWS Clean Rooms suporta as seguintes expressões condicionais:
**Topics**
+ [Expressão condicional CASE](CASE_function.md)
+ [expressão COALESCE](coalesce-function.md)
+ [MAIOR e MENOR expressão](GREATEST_LEAST.md)
+ [Expressão IF](IF.md)
+ [expressão IS\$1NULL](IS_NULL.md)
+ [expressão IS\$1NOT\$1NULL](IS_NOT_NULL.md)
+ [Funções NVL e COALESCE](NVL_function.md)
+ [NVL2 função](NVL2.md)
+ [Função NULLIF](NULLIF_function.md)
# Expressão condicional CASE
A expressão CASE é uma expressão condicional, semelhante às if/then/else declarações encontradas em outras linguagens. CASE é usada para especificar um resultado onde há várias condições. Use CASE onde uma expressão SQL é válida, como em um comando SELECT.
Há dois tipos de expressões CASE: simples e pesquisada.
+ Em expressões CASE simples, uma expressão é comparada a um valor. Quando uma correspondência é encontrada, a ação especificada na cláusula THEN é aplicada. Se nenhuma correspondência é encontrada, a ação especificada na cláusula ELSE é aplicada.
+ Em expressões CASE pesquisadas, cada CASE é avaliado com base em uma expressão booleana e a instrução CASE retorna o primeiro CASE correspondente. Se nenhuma correspondência for encontrada entre as cláusulas WHEN, a ação na cláusula ELSE será retornada.
## Sintaxe
Instrução CASE simples usada para correspondência de condições:
```
CASE expression
WHEN value THEN result
[WHEN...]
[ELSE result]
END
```
Instrução CASE pesquisada usada para avaliação de cada condição:
```
CASE
WHEN condition THEN result
[WHEN ...]
[ELSE result]
END
```
## Argumentos
*expressão*
Um nome de coluna ou qualquer expressão válida.
*value*
Valor ao qual a expressão é comparada, tal como uma constante numérica ou string de caracteres.
*resultado*
O valor ou uma expressão de destino retornado quando uma expressão ou condição booleana é avaliada. Os tipos de dados de todas as expressões de resultados devem poder ser convertidos em um único tipo de saída.
*condição*
Uma expressão booliana que avalia como verdadeiro ou falso. Se a *condição* for verdadeira, o valor da expressão CASE será o resultado que segue a condição e o restante da expressão CASE não será processado. Se a *condição* for falsa, todas as cláusulas WHEN subsequentes serão avaliadas. Se nenhum resultado da condição WHEN for verdadeiro, o valor da expressão CASE será o resultado da cláusula ELSE. Se a cláusula ELSE for omitida e não nenhuma condição for verdadeira, o resultado será nulo.
## Exemplos
Use uma expressão CASE simples para substituir `New York City` por `Big Apple` em uma consulta da tabela VENUE. Substitua todos os outros nomes de cidade por `other`.
```
select venuecity,
case venuecity
when 'New York City'
then 'Big Apple' else 'other'
end
from venue
order by venueid desc;
venuecity | case
-----------------+-----------
Los Angeles | other
New York City | Big Apple
San Francisco | other
Baltimore | other
...
```
Use uma expressão CASE pesquisada para atribuir números de grupo com base no valor PRICEPAID para vendas individuais de ingresso:
```
select pricepaid,
case when pricepaid <10000 then 'group 1'
when pricepaid >10000 then 'group 2'
else 'group 3'
end
from sales
order by 1 desc;
pricepaid | case
----------+---------
12624 | group 2
10000 | group 3
10000 | group 3
9996 | group 1
9988 | group 1
...
```
# expressão COALESCE
Uma expressão COALESCE retorna o valor da primeira expressão da lista que não é nula. Se todas as expressões forem nulas, o resultado será nulo. Quando um valor não nulo é localizado, as demais expressões na lista não são avaliadas.
Este tipo de expressão é útil quando você deseja retornar um valor de backup para algo quando o valor preferido está ausente ou é nulo. Por exemplo, uma consulta pode retornar um de três números de telefone (celular, residência ou comercial, nessa ordem), o que for localizado primeiro na tabela (não nulo).
## Sintaxe
```
COALESCE (expression, expression, ... )
```
## Exemplos
Aplique a expressão COALESCE em duas colunas.
```
select coalesce(start_date, end_date)
from datetable
order by 1;
```
O nome da coluna padrão para uma expressão NVL é COALESCE. A consulta a seguir retorna os mesmos resultados.
```
select coalesce(start_date, end_date) from datetable order by 1;
```
# MAIOR e MENOR expressão
Retorna o maior ou menor valor de uma lista com qualquer número de expressões.
## Sintaxe
```
GREATEST (value [, ...])
LEAST (value [, ...])
```
## Parâmetros
*expression\$1list*
Uma lista de expressões, tais como nomes de coluna, separadas por vírgula. As expressões devem ser conversíveis para um tipo de dados comum. Valores NULL na lista são ignorados. Se todas as expressões avaliarem para NULL, o resultado será NULL.
## Retornos
Retorna o maior (para GREATEST) ou menor (para LEAST) valor da lista de expressões fornecida.
## Exemplo
O seguinte exemplo retorna o valor mais alto alfabeticamente para `firstname` ou `lastname`.
```
select firstname, lastname, greatest(firstname,lastname) from users
where userid < 10
order by 3;
firstname | lastname | greatest
-----------+-----------+-----------
Alejandro | Rosalez | Ratliff
Carlos | Salazar | Carlos
Jane | Doe | Doe
John | Doe | Doe
John | Stiles | John
Shirley | Rodriguez | Rodriguez
Terry | Whitlock | Terry
Richard | Roe | Richard
Xiulan | Wang | Wang
(9 rows)
```
# Expressão IF
A função condicional IF retorna um dos dois valores com base em uma condição.
Essa função é uma instrução de fluxo de controle comum usada em SQL para tomar decisões e retornar valores diferentes com base na avaliação de uma condição. É útil para implementar uma lógica if-else simples em uma consulta.
## Sintaxe
```
if(expr1, expr2, expr3)
```
## Argumentos
*expr 1*
A condição ou expressão que é avaliada. Se for`true`, a função retornará o valor de *expr2*. *Se *expr1* for`false`, a função retornará o valor de expr3.*
*expr 2*
A expressão que é avaliada e retornada se *expr1* for. `true`
*expr 3*
A expressão que é avaliada e retornada se *expr1* for. `false`
## Retornos
Se for `expr1` avaliado como`true`, então retorna`expr2`; caso contrário, retorna`expr3`.
## Exemplo
O exemplo a seguir usa a `if()` função para retornar um dos dois valores com base em uma condição. A condição que está sendo avaliada é`1 < 2`, ou seja`true`, o primeiro valor `'a'` é retornado.
```
SELECT if(1 < 2, 'a', 'b');
a]
```
# expressão IS\$1NULL
A expressão IS\$1NULL condicional é usada para verificar se um valor é nulo.
Essa expressão é sinônimo deIS NULL.
## Sintaxe
```
is_null(expr)
```
## Argumentos
*expr*
Uma expressão de qualquer tipo.
## Retornos
A expressão IS\$1NULL condicional retorna um booleano. Se `expr1` for NULL, retorna, caso contrário`true`, retorna`false`.
## Exemplos
O exemplo a seguir verifica se o valor `1` é nulo e retorna o resultado booleano `true` porque 1 é um valor válido e não nulo.
```
SELECT is not null(1);
true
```
O exemplo a seguir seleciona a `id` coluna da `squirrels` tabela, mas somente para as linhas em que a coluna de idade está`null`.
```
SELECT id FROM squirrels WHERE is_null(age)
```
# expressão IS\$1NOT\$1NULL
A expressão IS\$1NOT\$1NULL condicional é usada para verificar se um valor não é nulo.
Essa expressão é sinônimo deIS NOT NULL.
## Sintaxe
```
is_not_null(expr)
```
## Argumentos
*expr*
Uma expressão de qualquer tipo.
## Retornos
A expressão IS\$1NOT\$1NULL condicional retorna um booleano. Se não `expr1` for NULL, retorna, caso contrário`true`, retorna`false`.
## Exemplos
O exemplo a seguir verifica se o valor não `1` é nulo e retorna o resultado booleano `true` porque 1 é um valor válido e não nulo.
```
SELECT is not null(1);
true
```
O exemplo a seguir seleciona a `id` coluna da `squirrels` tabela, mas somente para as linhas em que a coluna de idade não `null` está.
```
SELECT id FROM squirrels WHERE is_not_null(age)
```
# Funções NVL e COALESCE
Retorna o valor da primeira expressão não nula em uma série de expressões. Quando um valor não nulo é encontrado, as demais expressões na lista não são avaliadas.
NVL é idêntica a COALESCE. São funções sinônimas. Este tópico explica a sintaxe e apresenta exemplos de ambas.
## Sintaxe
```
NVL( expression, expression, ... )
```
A sintaxe de COALESCE é a mesma:
```
COALESCE( expression, expression, ... )
```
Se todas as expressões forem nulas, o resultado será nulo.
Essas funções são úteis para retornar um valor secundário quando um valor primário está ausente ou é nulo. Por exemplo, uma consulta pode retornar o primeiro dos três números de telefone disponíveis: celular, residencial ou profissional. A ordem das expressões na função determina a ordem de avaliação.
## Argumentos
*expressão*
Uma expressão, tal como um nome de coluna, a ser avaliada quanto ao status nulo.
## Tipo de retorno
AWS Clean Rooms determina o tipo de dados do valor retornado com base nas expressões de entrada. Se os tipos de dados das expressões de entrada não tiverem um tipo comum, um erro será retornado.
## Exemplos
Se a lista contiver expressões do tipo inteiro, a função retornará um inteiro.
```
SELECT COALESCE(NULL, 12, NULL);
coalesce
--------------
12
```
Esse exemplo, que é igual ao exemplo anterior, exceto pelo fato de usar NVL, retorna o mesmo resultado.
```
SELECT NVL(NULL, 12, NULL);
coalesce
--------------
12
```
O exemplo a seguir retorna um tipo string.
```
SELECT COALESCE(NULL, 'AWS Clean Rooms', NULL);
coalesce
--------------
AWS Clean Rooms
```
O exemplo a seguir resulta em um erro porque os tipos de dados variam na lista de expressões. Nesse caso, há uma string e um número na lista.
```
SELECT COALESCE(NULL, 'AWS Clean Rooms', 12);
ERROR: invalid input syntax for integer: "AWS Clean Rooms"
```
# NVL2 função
Retorna um de dois valores, dependendo se uma expressão especificada avalia para NULL ou NOT NULL.
## Sintaxe
```
NVL2 ( expression, not_null_return_value, null_return_value )
```
## Argumentos
*expressão*
Uma expressão, tal como um nome de coluna, a ser avaliada quanto ao status nulo.
*not\$1null\$1return\$1value*
O valor retornado se a *expressão* avaliar para NOT NULL. O valor *not\$1null\$1return\$1value* deve ter o mesmo tipo de dados que a *expressão* ou ser implicitamente conversível para esse tipo de dados.
*null\$1return\$1value*
O valor retornado se a *expressão* avaliar para NULL. O valor *null\$1return\$1value* deve ter o mesmo tipo de dados que a *expressão* ou ser implicitamente conversível para esse tipo de dados.
## Tipo de retorno
O tipo de NVL2 retorno é determinado da seguinte forma:
+ Se *not\$1null\$1return\$1value* ou *null\$1return\$1value* for nulo, o tipo de dados da expressão não nula será retornado.
Se *not\$1null\$1return\$1value* e *null\$1return\$1value* não forem nulos:
+ Se *not\$1null\$1return\$1value* e *null\$1return\$1value* tiverem o mesmo tipo de dados, esse tipo de dados será retornado.
+ Se *not\$1null\$1return\$1value* e *null\$1return\$1value* tiverem diferentes tipos de dados numéricos, o menor tipo de dados numérico compatível será retornado.
+ Se *not\$1null\$1return\$1value* e *null\$1return\$1value* tiverem diferentes tipos de dados datetime, um tipo de dados de timestamp será retornado.
+ Se *not\$1null\$1return\$1value* e *null\$1return\$1value* tiverem diferentes tipos de dados de caracteres, o tipo de dados de *not\$1null\$1return\$1value* será retornado.
+ Se *not\$1null\$1return\$1value* e *null\$1return\$1value* tiverem tipos de dados numéricos e não numéricos variados, o tipo de dados de *not\$1null\$1return\$1value* será retornado.
**Importante**
Nos últimos dois casos onde o tipo de dados de *not\$1null\$1return\$1value* é retornado, *o null\$1return\$1value* é convertido implicitamente para esse tipo de dados. Se os tipos de dados forem incompatíveis, a função falhará.
## Observações de uso
*Pois NVL2, o retorno terá o valor do parâmetro *not\$1null\$1return\$1value ou null\$1return\$1value*, o que for selecionado pela função, mas terá o tipo de dados *not\$1null\$1return\$1value*.*
Por exemplo, supondo que column1 seja NULL, as consultas seguintes retornarão o mesmo valor. No entanto, o tipo de dados do valor de retorno DECODE será INTEGER e o tipo de dados do valor de NVL2 retorno será VARCHAR.
```
select decode(column1, null, 1234, '2345');
select nvl2(column1, '2345', 1234);
```
## Exemplo
O seguinte exemplo altera alguns dados de amostra e, então, avalia dois campos para fornecer as informações de contato apropriadas para usuários:
```
update users set email = null where firstname = 'Aphrodite' and lastname = 'Acevedo';
select (firstname + ' ' + lastname) as name,
nvl2(email, email, phone) AS contact_info
from users
where state = 'WA'
and lastname like 'A%'
order by lastname, firstname;
name contact_info
--------------------+-------------------------------------------
Aphrodite Acevedo (555) 555-0100
Caldwell Acevedo Nunc.sollicitudin@example.ca
Quinn Adams vel@example.com
Kamal Aguilar quis@example.com
Samson Alexander hendrerit.neque@example.com
Hall Alford ac.mattis@example.com
Lane Allen et.netus@example.com
Xander Allison ac.facilisis.facilisis@example.com
Amaya Alvarado dui.nec.tempus@example.com
Vera Alvarez at.arcu.Vestibulum@example.com
Yetta Anthony enim.sit@example.com
Violet Arnold ad.litora@example.comm
August Ashley consectetuer.euismod@example.com
Karyn Austin ipsum.primis.in@example.com
Lucas Ayers at@example.com
```
# Função NULLIF
Compara dois argumentos e retorna nulo se os argumentos forem iguais. Se eles não forem iguais, o primeiro argumento será retornado.
## Sintaxe
A expressão NULLIF compara dois argumentos e retorna nulo se os argumentos forem iguais. Se eles não forem iguais, o primeiro argumento será retornado. Essa expressão é o inverso da expressão NVL ou COALESCE.
```
NULLIF ( expression1, expression2 )
```
## Argumentos
*expression1, expression2*
As colunas ou expressões de destino que são comparadas. O tipo de retorno é igual ao tipo da primeira expressão.
## Exemplos
No exemplo a seguir, a consulta retorna a string `first` porque os argumentos não são iguais.
```
SELECT NULLIF('first', 'second');
case
-------
first
```
No exemplo a seguir, a consulta retorna `NULL` porque os argumentos literais da string são iguais.
```
SELECT NULLIF('first', 'first');
case
-------
NULL
```
No exemplo a seguir, a consulta retorna `1` porque os argumentos inteiros não são iguais.
```
SELECT NULLIF(1, 2);
case
-------
1
```
No exemplo a seguir, a consulta retorna `NULL` porque os argumentos inteiros são iguais.
```
SELECT NULLIF(1, 1);
case
-------
NULL
```
No exemplo a seguir, a consulta retorna nulo quando há correspondência dos valores LISTID e SALESID:
```
select nullif(listid,salesid), salesid
from sales where salesid<10 order by 1, 2 desc;
listid | salesid
--------+---------
4 | 2
5 | 4
5 | 3
6 | 5
10 | 9
10 | 8
10 | 7
10 | 6
| 1
(9 rows)
```
# Funções do construtor
Uma função construtora SQL é uma função usada para criar novas estruturas de dados, como matrizes ou mapas.
Eles pegam alguns valores de entrada e retornam um novo objeto de estrutura de dados. As funções do construtor geralmente são nomeadas de acordo com o tipo de dados que elas criam, como ARRAY ou MAP.
As funções construtoras são diferentes das funções escalares ou agregadas, que operam com dados existentes e retornam um único valor. As funções do construtor são usadas para criar novas estruturas de dados que podem ser usadas em processamento ou análise de dados adicionais.
AWS Clean Rooms suporta as seguintes funções de construtor:
**Topics**
+ [Função construtora MAP](map_function.md)
+ [Função construtora NAMED\$1STRUCT](named-struct_function.md)
+ [Função construtora STRUCT](struct_function.md)
# Função construtora MAP
A função construtora MAP cria um mapa com os pares chave/valor fornecidos.
Funções de construtor, como MAP, são úteis quando você precisa criar novas estruturas de dados programaticamente em suas consultas SQL. Eles permitem que você crie estruturas de dados complexas que podem ser usadas em processamento ou análise de dados adicionais.
## Sintaxe
```
map(key0, value0, key1, value1, ...)
```
## Argumentos
*chave 0*
Uma expressão de qualquer tipo comparável. Todas as *key0* devem compartilhar um tipo menos comum.
*valor0*
Uma expressão de qualquer tipo. Todos os *ValueN* devem compartilhar um tipo menos comum.
## Retornos
*A função MAP retorna um MAP com chaves digitadas como o tipo menos comum de *chave0* e valores digitados como o tipo menos comum de valor0.*
## Exemplos
O exemplo a seguir cria um novo mapa com dois pares de valores-chave: A chave `1.0` está associada ao valor. `'2'` A chave `3.0` está associada ao valor`'4'`. O mapa resultante é então retornado como a saída da instrução SQL.
```
SELECT map(1.0, '2', 3.0, '4');
{1.0:"2",3.0:"4"}
```
# Função construtora NAMED\$1STRUCT
A função do construtor NAMED\$1STRUCT cria uma estrutura com os nomes e valores de campo fornecidos.
Funções de construtor como NAMED\$1STRUCT são úteis quando você precisa criar novas estruturas de dados programaticamente em suas consultas SQL. Eles permitem que você crie estruturas de dados complexas, como estruturas ou registros, que podem ser usadas em processamento ou análise de dados adicionais.
## Sintaxe
```
named_struct(name1, val1, name2, val2, ...)
```
## Argumentos
*nome1*
Um campo de nomenclatura literal STRING 1.
*val1*
Uma expressão de qualquer tipo especificando o valor do campo 1.
## Retornos
*A função NAMED\$1STRUCT retorna uma estrutura com o campo 1 correspondente ao tipo de val1.*
## Exemplos
O exemplo a seguir cria uma nova estrutura com três campos nomeados: O valor `"a"` `1` é atribuído ao campo. O campo `"b"` recebe o valor `2.` O campo `"c"` recebe o valor`3`. A estrutura resultante é então retornada como saída da instrução SQL.
```
SELECT named_struct("a", 1, "b", 2, "c", 3);
{"a":1,"b":2,"c":3}
```
# Função construtora STRUCT
A função construtora STRUCT cria uma estrutura com os valores de campo fornecidos.
Funções de construtor como STRUCT são úteis quando você precisa criar novas estruturas de dados programaticamente em suas consultas SQL. Eles permitem que você crie estruturas de dados complexas, como estruturas ou registros, que podem ser usadas em processamento ou análise de dados adicionais.
## Sintaxe
```
struct(col1, col2, col3, ...)
```
## Argumentos
*col1*
Um nome de coluna ou qualquer expressão válida.
## Retornos
*A função STRUCT retorna uma estrutura com *field1 correspondente ao tipo de expr1*.*
Se os argumentos forem referências nomeadas, os nomes serão usados para nomear o campo. Caso contrário, os campos são *denominados* colN, onde N é a posição do campo na estrutura.
## Exemplos
O exemplo a seguir cria uma nova estrutura com três campos: O primeiro campo recebe o valor 1. O segundo campo recebe o valor 2. O terceiro campo recebe o valor 3. Por padrão, os campos na estrutura resultante são nomeados`col1`,, e `col2``col3`, com base em sua posição na lista de argumentos. A estrutura resultante é então retornada como saída da instrução SQL.
```
SELECT struct(1, 2, 3);
{"col1":1,"col2":2,"col3":3}
```
# Funções de formatação de tipo de dados
Usando uma função de formatação de tipo de dados, você pode converter valores de um tipo de dados para outro. Para cada uma dessas funções, o primeiro argumento é sempre o valor a ser formatado e o segundo argumento contém o modelo para o novo formato.
AWS Clean Rooms O Spark SQL oferece suporte a várias funções de formatação de tipos de dados.
**Topics**
+ [BASE64 função](base64.md)
+ [Função CAST](CAST_function.md)
+ [Função DECODE](DECODE.md)
+ [Função ENCODE](ENCODE.md)
+ [Função HEX](HEX.md)
+ [função STR\$1TO\$1MAP](STR_TO_MAP.md)
+ [TO\$1CHAR](TO_CHAR.md)
+ [Função TO\$1DATE](TO_DATE_function.md)
+ [TO\$1NUMBER](TO_NUMBER.md)
+ [UNBASE64 função](unbase64.md)
+ [Função UNHEX](UNHEX.md)
+ [Strings de formato datetime](FORMAT_strings.md)
+ [Strings de formato numérico](Numeric_formating.md)
# BASE64 função
A BASE64 função converte uma expressão em uma string de base 64 usando a [codificação de transferência RFC2045 Base64 para](https://datatracker.ietf.org/doc/html/rfc2045) MIME.
## Sintaxe
```
base64(expr)
```
## Argumentos
*expr*
Uma expressão BINÁRIA ou uma STRING que a função interpretará como BINÁRIA.
## Tipo de retorno
`STRING`
## Exemplo
Para converter a entrada de string fornecida em sua representação codificada em Base64. use o exemplo a seguir. O resultado é a representação codificada em Base64 da string de entrada 'Spark SQL', que é 'u3bhcmsgu1fm'.
```
SELECT base64('Spark SQL');
U3BhcmsgU1FM
```
# Função CAST
A função CAST converte um tipo de dados em outro compatível. Por exemplo, é possível converter uma string em uma data ou um tipo numérico em uma string. CAST executa uma conversão em tempo de execução, o que significa que a conversão não altera o tipo de dados de um valor em uma tabela de origem. Isso é alterado somente no contexto da consulta.
Alguns tipos de dados exigem uma conversão explícita para outros tipos de dados usando a função CAST. Outros tipos de dados podem ser convertidos implicitamente, como parte de outro comando, sem usar CAST. Consulte [Compatibilidade e conversão dos tipos](s_Type_conversion.md).
## Sintaxe
Use uma dessas duas formas equivalentes de sintaxe para transmitir expressões de um tipo de dados para outro.
```
CAST ( expression AS type )
```
## Argumentos
*expressão*
Uma expressão que avalia para um ou mais valores, tal como um nome de coluna ou um literal. A conversão de valores nulos retorna nulos. A expressão não pode conter strings em branco ou vazias.
*tipo*
Um dos suportados[Tipos de dados](s_Supported_data_types.md), exceto para os tipos de dados BINARY e BINARY VARYING.
## Tipo de retorno
CAST retorna o tipo de dados especificado pelo argumento *type*.
**nota**
AWS Clean Rooms retorna um erro se você tentar realizar uma conversão problemática, como uma conversão DECIMAL que perde a precisão, como a seguir:
```
select 123.456::decimal(2,1);
```
ou uma conversão INTEGER que causa um transbordamento:
```
select 12345678::smallint;
```
## Exemplos
As seguintes duas consultas são equivalentes. Ambas convertem um valor decimal em um número inteiro:
```
select cast(pricepaid as integer)
from sales where salesid=100;
pricepaid
-----------
162
(1 row)
```
```
select pricepaid::integer
from sales where salesid=100;
pricepaid
-----------
162
(1 row)
```
O seguinte produz um resultado semelhante. Ele não exige dados de exemplo para ser executado:
```
select cast(162.00 as integer) as pricepaid;
pricepaid
-----------
162
(1 row)
```
Neste exemplo, os valores em uma coluna de carimbo de data/hora são transmitidos como datas, o que resulta na remoção do horário de cada resultado:
```
select cast(saletime as date), salesid
from sales order by salesid limit 10;
saletime | salesid
-----------+---------
2008-02-18 | 1
2008-06-06 | 2
2008-06-06 | 3
2008-06-09 | 4
2008-08-31 | 5
2008-07-16 | 6
2008-06-26 | 7
2008-07-10 | 8
2008-07-22 | 9
2008-08-06 | 10
(10 rows)
```
Se você não usasse CAST conforme ilustrado no exemplo anterior, os resultados incluiriam o horário: *2008-02-18 02:36:48*.
A consulta a seguir converte dados de caracteres variáveis em uma data. Ele não exige dados de exemplo para ser executado.
```
select cast('2008-02-18 02:36:48' as date) as mysaletime;
mysaletime
--------------------
2008-02-18
(1 row)
```
Neste exemplo, os valores em uma coluna de data são convertidos como timestamps:
```
select cast(caldate as timestamp), dateid
from date order by dateid limit 10;
caldate | dateid
--------------------+--------
2008-01-01 00:00:00 | 1827
2008-01-02 00:00:00 | 1828
2008-01-03 00:00:00 | 1829
2008-01-04 00:00:00 | 1830
2008-01-05 00:00:00 | 1831
2008-01-06 00:00:00 | 1832
2008-01-07 00:00:00 | 1833
2008-01-08 00:00:00 | 1834
2008-01-09 00:00:00 | 1835
2008-01-10 00:00:00 | 1836
(10 rows)
```
Em um caso como no exemplo anterior, é possível ter controle adicional sobre a formatação de saída usando [TO\$1CHAR](TO_CHAR.md).
Neste exemplo, um número inteiro é convertido como uma string de caracteres:
```
select cast(2008 as char(4));
bpchar
--------
2008
```
Neste exemplo, um valor DECIMAL(6,3) é convertido como um valor DECIMAL(4,1):
```
select cast(109.652 as decimal(4,1));
numeric
---------
109.7
```
Este exemplo mostra uma expressão mais complexa. A coluna PRICEPAID (uma coluna DECIMAL(8,2)) na tabela SALES é convertida em uma coluna DECIMAL(38,2) e os valores são multiplicados por 100.000.000.000.000.000.000.
```
select salesid, pricepaid::decimal(38,2)*100000000000000000000
as value from sales where salesid<10 order by salesid;
salesid | value
---------+----------------------------
1 | 72800000000000000000000.00
2 | 7600000000000000000000.00
3 | 35000000000000000000000.00
4 | 17500000000000000000000.00
5 | 15400000000000000000000.00
6 | 39400000000000000000000.00
7 | 78800000000000000000000.00
8 | 19700000000000000000000.00
9 | 59100000000000000000000.00
(9 rows)
```
# Função DECODE
A função DECODE é a contrapartida da função ENCODE, que é usada para converter uma string em um formato binário usando uma codificação de caracteres específica. A função DECODE pega os dados binários e os converte novamente em um formato de string legível usando a codificação de caracteres especificada.
Essa função é útil quando você precisa trabalhar com dados binários armazenados em um banco de dados e apresentá-los em um formato legível por humanos ou quando precisa converter dados entre diferentes codificações de caracteres.
## Sintaxe
```
decode(expr, charset)
```
## Argumentos
*expr*
Uma expressão BINÁRIA codificada em charset.
*conjunto de caracteres*
Uma expressão STRING.
Codificações de conjuntos de caracteres compatíveis (sem distinção entre maiúsculas e minúsculas):`'US-ASCII'`,,`'ISO-8859-1'`,`'UTF-8'`, e. `'UTF-16BE'` `'UTF-16LE'` `'UTF-16'`
## Tipo de retorno
A função DECODE retorna uma STRING.
## Exemplo
O exemplo a seguir tem uma tabela chamada `messages` com uma coluna chamada `message_text` que armazena dados de mensagens em um formato binário usando a codificação de caracteres UTF-8. A função DECODE converte os dados binários de volta em um formato de string legível. A saída dessa consulta é o texto legível da mensagem armazenada na tabela de mensagens, com o ID`123`, convertido do formato binário em uma string usando a `'utf-8'` codificação.
```
SELECT decode(message_text, 'utf-8') AS message
FROM messages
WHERE message_id = 123;
```
# Função ENCODE
A função ENCODE é usada para converter uma string em sua representação binária usando uma codificação de caracteres especificada.
Essa função é útil quando você precisa trabalhar com dados binários ou quando precisa converter entre diferentes codificações de caracteres. Por exemplo, você pode usar a função ENCODE ao armazenar dados em um banco de dados que requer armazenamento binário ou quando precisar transferir dados entre sistemas que usam codificações de caracteres diferentes.
## Sintaxe
```
encode(str, charset)
```
## Argumentos
*str*
Uma expressão STRING a ser codificada.
*conjunto de caracteres*
Uma expressão STRING especificando a codificação.
Codificações de conjuntos de caracteres compatíveis (sem distinção entre maiúsculas e minúsculas):`'US-ASCII'`,,`'ISO-8859-1'`,`'UTF-8'`, e. `'UTF-16BE'` `'UTF-16LE'` `'UTF-16'`
## Tipo de retorno
A função ENCODE retorna um BINÁRIO.
## Exemplo
O exemplo a seguir converte `'abc'` a string em sua representação binária usando a `'utf-8'` codificação, o que, nesse caso, resulta no retorno da string original. Isso ocorre porque a `'utf-8'` codificação é uma codificação de caracteres de largura variável que pode representar todo o conjunto de caracteres ASCII (que inclui as letras `'a'``'b'`, e`'c'`) usando um único byte por caractere. Portanto, a representação binária do `'abc'` uso `'utf-8'` é a mesma da string original.
```
SELECT encode('abc', 'utf-8');
abc
```
# Função HEX
A função HEX converte um valor numérico (um número inteiro ou um número de ponto flutuante) em sua representação de string hexadecimal correspondente.
O hexadecimal é um sistema numérico que usa 16 símbolos distintos (0-9 e A-F) para representar valores numéricos. É comumente usado em ciência da computação e programação para representar dados binários em um formato mais compacto e legível por humanos.
## Sintaxe
```
hex(expr)
```
## Argumentos
*expr*
Uma expressão BIGINT, BINARY ou STRING.
## Tipo de retorno
HEX retorna uma STRING. A função retorna a representação hexadecimal do argumento.
## Exemplo
O exemplo a seguir usa o valor inteiro 17 como entrada e aplica a função HEX () a ele. A saída é`11`, que é a representação hexadecimal do valor de entrada. `17`
```
SELECT hex(17);
11
```
O exemplo a seguir converte a string em sua `'Spark_SQL'` representação hexadecimal. A saída é`537061726B2053514C`, que é a representação hexadecimal da string de entrada. `'Spark_SQL'`
```
SELECT hex('Spark_SQL');
537061726B2053514C
```
Neste exemplo, a string 'Spark\$1SQL' é convertida da seguinte forma:
+ 'S' -> 53
+ 'p' -> 70
+ 'a' -> 61
+ 'r' -> 72 '
+ k' -> 6B
+ '\$1' -> 20
+ 'S' -> 53
+ 'Q' -> 51
+ 'L' -> 4C
A concatenação desses valores hexadecimais resulta na saída final ". `537061726B2053514C"`
# função STR\$1TO\$1MAP
A função STR\$1TO\$1MAP é uma função de conversão. string-to-map Ele converte uma representação em cadeia de caracteres de um mapa (ou dicionário) em uma estrutura de dados real do mapa.
Essa função é útil quando você precisa trabalhar com estruturas de dados de mapas em SQL, mas os dados são inicialmente armazenados como uma string. Ao converter a representação da string em um mapa real, você pode então realizar operações e manipulações nos dados do mapa.
## Sintaxe
```
str_to_map(text[, pairDelim[, keyValueDelim]])
```
## Argumentos
*texto*
Uma expressão STRING que representa o mapa.
*Par de LIM*
Um literal STRING opcional que especifica como separar as entradas. O padrão é uma vírgula (). `','`
*keyValueDelim*
Um literal STRING opcional que especifica como separar cada par de valores-chave. O padrão é dois pontos (). `':'`
## Tipo de retorno
A função STR\$1TO\$1MAP retorna um MAP de STRING para chaves e valores. Tanto o *PairDelim* quanto o PairDelim *keyValueDelim*são tratados como expressões regulares.
## Exemplo
O exemplo a seguir usa a string de entrada e os dois argumentos delimitadores e converte a representação da string em uma estrutura de dados de mapa real. Neste exemplo específico, a string de entrada `'a:1,b:2,c:3'` representa um mapa com os seguintes pares de valores-chave: `'a'` é a chave e `'1'` é o valor. `'b'`é a chave e `'2'` é o valor. `'c'`é a chave e `'3'` é o valor. O `','` delimitador é usado para separar os pares de valores-chave e o `':'` delimitador é usado para separar a chave e o valor em cada par. A saída dessa consulta é:`{"a":"1","b":"2","c":"3"}`. Essa é a estrutura de dados do mapa resultante, onde as chaves são `'a'``'b'`,`'c'`, e, e os valores correspondentes são `'1'``'2'`, `'3'` e.
```
SELECT str_to_map('a:1,b:2,c:3', ',', ':');
{"a":"1","b":"2","c":"3"}
```
O exemplo a seguir demonstra que a função STR\$1TO\$1MAP espera que a string de entrada esteja em um formato específico, com os pares de valores-chave delimitados corretamente. Se a string de entrada não corresponder ao formato esperado, a função ainda tentará criar um mapa, mas os valores resultantes podem não ser os esperados.
```
SELECT str_to_map('a');
{"a":null}
```
# TO\$1CHAR
TO\$1CHAR Converte uma expressão de timestamp ou numérica para o formato de dados de string de caracteres.
## Sintaxe
```
TO_CHAR (timestamp_expression | numeric_expression , 'format')
```
## Argumentos
*timestamp\$1expression*
Uma expressão que resulta em um valor do tipo TIMESTAMP ou TIMESTAMPTZ ou um valor que pode ser implicitamente forçado para um timestamp.
*numeric\$1expression*
Uma expressão que resulta em um valor de tipo de dados numérico ou em um valor que pode implicitamente ser convertido para tipo numérico. Para obter mais informações, consulte [Tipos numéricos](Numeric_types.md). TO\$1CHAR insere um espaço à esquerda da string numérica.
TO\$1CHAR não permite valores do tipo DECIMAL de 128 bits.
*format*
O formato para o novo valor. Para obter os formatos válidos, consulte [Strings de formato datetime](FORMAT_strings.md) e [Strings de formato numérico](Numeric_formating.md).
## Tipo de retorno
VARCHAR
## Exemplos
O exemplo a seguir converte um carimbo de data/hora em um valor com a data e a hora em um formato com o nome do mês preenchido com nove caracteres, o nome do dia da semana e o número do dia do mês.
```
select to_char(timestamp '2009-12-31 23:15:59', 'MONTH-DY-DD-YYYY HH12:MIPM');
to_char
-------------------------
DECEMBER -THU-31-2009 11:15PM
```
O exemplo a seguir converte um carimbo de data/hora em um valor com o número do dia do ano.
```
select to_char(timestamp '2009-12-31 23:15:59', 'DDD');
to_char
-------------------------
365
```
O exemplo a seguir converte um carimbo de data/hora em um número do dia da semana da norma ISO.
```
select to_char(timestamp '2022-05-16 23:15:59', 'ID');
to_char
-------------------------
1
```
O exemplo a seguir extrai o nome do mês de uma data.
```
select to_char(date '2009-12-31', 'MONTH');
to_char
-------------------------
DECEMBER
```
O seguinte exemplo converte cada valor de STARTTIME na tabela EVENT em uma string que consiste em horas, minutos e segundos.
```
select to_char(starttime, 'HH12:MI:SS')
from event where eventid between 1 and 5
order by eventid;
to_char
----------
02:30:00
08:00:00
02:30:00
02:30:00
07:00:00
(5 rows)
```
O exemplo a seguir converte um valor de timestamp inteiro em um formato diferente.
```
select starttime, to_char(starttime, 'MON-DD-YYYY HH12:MIPM')
from event where eventid=1;
starttime | to_char
---------------------+---------------------
2008-01-25 14:30:00 | JAN-25-2008 02:30PM
(1 row)
```
O exemplo a seguir converte um literal de timestamp em uma string de caracteres.
```
select to_char(timestamp '2009-12-31 23:15:59','HH24:MI:SS');
to_char
----------
23:15:59
(1 row)
```
O exemplo a seguir converte um número em uma string de caracteres com o sinal menos no final.
```
select to_char(-125.8, '999D99S');
to_char
---------
125.80-
(1 row)
```
O exemplo a seguir converte um número em uma string de caracteres com o símbolo de moeda.
```
select to_char(-125.88, '$S999D99');
to_char
---------
$-125.88
(1 row)
```
O exemplo a seguir converte um número em uma string de caracteres usando colchetes angulares para números negativos.
```
select to_char(-125.88, '$999D99PR');
to_char
---------
$<125.88>
(1 row)
```
O exemplo a seguir converte um número em uma string de numerais romanos.
```
select to_char(125, 'RN');
to_char
---------
CXXV
(1 row)
```
O exemplo a seguir exibe o dia da semana.
```
SELECT to_char(current_timestamp, 'FMDay, FMDD HH12:MI:SS');
to_char
-----------------------
Wednesday, 31 09:34:26
```
O exemplo a seguir exibe o sufixo de número ordinal de um número.
```
SELECT to_char(482, '999th');
to_char
-----------------------
482nd
```
O exemplo a seguir subtrai a comissão do preço pago na tabela de vendas. A diferença é então arredondada para cima e convertida em um numeral romano, exibido na coluna `to_char`:
```
select salesid, pricepaid, commission, (pricepaid - commission)
as difference, to_char(pricepaid - commission, 'rn') from sales
group by sales.pricepaid, sales.commission, salesid
order by salesid limit 10;
salesid | pricepaid | commission | difference | to_char
---------+-----------+------------+------------+-----------------
1 | 728.00 | 109.20 | 618.80 | dcxix
2 | 76.00 | 11.40 | 64.60 | lxv
3 | 350.00 | 52.50 | 297.50 | ccxcviii
4 | 175.00 | 26.25 | 148.75 | cxlix
5 | 154.00 | 23.10 | 130.90 | cxxxi
6 | 394.00 | 59.10 | 334.90 | cccxxxv
7 | 788.00 | 118.20 | 669.80 | dclxx
8 | 197.00 | 29.55 | 167.45 | clxvii
9 | 591.00 | 88.65 | 502.35 | dii
10 | 65.00 | 9.75 | 55.25 | lv
(10 rows)
```
O seguinte exemplo adiciona o cifrão aos valores da diferença exibidos na coluna `to_char`:
```
select salesid, pricepaid, commission, (pricepaid - commission)
as difference, to_char(pricepaid - commission, 'l99999D99') from sales
group by sales.pricepaid, sales.commission, salesid
order by salesid limit 10;
salesid | pricepaid | commission | difference | to_char
--------+-----------+------------+------------+------------
1 | 728.00 | 109.20 | 618.80 | $ 618.80
2 | 76.00 | 11.40 | 64.60 | $ 64.60
3 | 350.00 | 52.50 | 297.50 | $ 297.50
4 | 175.00 | 26.25 | 148.75 | $ 148.75
5 | 154.00 | 23.10 | 130.90 | $ 130.90
6 | 394.00 | 59.10 | 334.90 | $ 334.90
7 | 788.00 | 118.20 | 669.80 | $ 669.80
8 | 197.00 | 29.55 | 167.45 | $ 167.45
9 | 591.00 | 88.65 | 502.35 | $ 502.35
10 | 65.00 | 9.75 | 55.25 | $ 55.25
(10 rows)
```
O seguinte exemplo lista o século em que cada venda foi efetuada.
```
select salesid, saletime, to_char(saletime, 'cc') from sales
order by salesid limit 10;
salesid | saletime | to_char
---------+---------------------+---------
1 | 2008-02-18 02:36:48 | 21
2 | 2008-06-06 05:00:16 | 21
3 | 2008-06-06 08:26:17 | 21
4 | 2008-06-09 08:38:52 | 21
5 | 2008-08-31 09:17:02 | 21
6 | 2008-07-16 11:59:24 | 21
7 | 2008-06-26 12:56:06 | 21
8 | 2008-07-10 02:12:36 | 21
9 | 2008-07-22 02:23:17 | 21
10 | 2008-08-06 02:51:55 | 21
(10 rows)
```
O seguinte exemplo converte cada valor de STARTTIME na tabela EVENT em uma string que consiste em horas, minutos, segundos e fuso horário:
```
select to_char(starttime, 'HH12:MI:SS TZ')
from event where eventid between 1 and 5
order by eventid;
to_char
----------
02:30:00 UTC
08:00:00 UTC
02:30:00 UTC
02:30:00 UTC
07:00:00 UTC
(5 rows)
(10 rows)
```
O seguinte exemplo exibe a formatação para segundos, milissegundos e microssegundos.
```
select sysdate,
to_char(sysdate, 'HH24:MI:SS') as seconds,
to_char(sysdate, 'HH24:MI:SS.MS') as milliseconds,
to_char(sysdate, 'HH24:MI:SS:US') as microseconds;
timestamp | seconds | milliseconds | microseconds
--------------------+----------+--------------+----------------
2015-04-10 18:45:09 | 18:45:09 | 18:45:09.325 | 18:45:09:325143
```
# Função TO\$1DATE
TO\$1DATE converte uma data representada em uma string de caracteres para um tipo de dados DATE.
## Sintaxe
```
TO_DATE (date_str)
```
```
TO_DATE (date_str, format)
```
## Argumentos
*data\$1str*
Uma string de data ou um tipo de dados que pode ser convertido em uma string de data.
*format*
Uma string literal que corresponde aos padrões de data e hora do Spark. Para padrões de data e hora válidos, consulte Padrões de [data e hora para formatação](https://spark.apache.org/docs/latest/sql-ref-datetime-pattern.html) e análise.
## Tipo de retorno
TO\$1DATE retorna uma DATE, dependendo do valor do *format*.
Se ocorrer falha na conversão no *formato*, um erro será gerado.
## Exemplos
A instrução SQL a seguir converte a data `02 Oct 2001` em um tipo de dados de data.
```
select to_date('02 Oct 2001', 'dd MMM yyyy');
to_date
------------
2001-10-02
(1 row)
```
A instrução SQL a seguir converte a string `20010631` em uma data.
```
select to_date('20010631', 'yyyyMMdd');
```
A seguinte instrução SQL converte a string `20010631` em uma data:
```
to_date('20010631', 'YYYYMMDD', TRUE);
```
O resultado é um valor nulo porque há apenas 30 dias em junho.
```
to_date
------------
NULL
```
# TO\$1NUMBER
TO\$1NUMBER converte uma string em um valor numérico (decimal).
## Sintaxe
```
to_number(string, format)
```
## Argumentos
*string*
String a ser convertida. O formato deve ser um valor literal.
*format*
O segundo argumento é uma string de formato que indica como a string de caracteres deve ser analisada para criar o valor numérico. Por exemplo, o formato `'99D999'` especifica que a string a ser convertida consiste em cinco dígitos com o ponto decimal na terceira posição. Por exemplo, `to_number('12.345','99D999')` retorna `12.345` como um valor numérico. Para obter uma lista dos formatos válidos, consulte [Strings de formato numérico](Numeric_formating.md).
## Tipo de retorno
TO\$1NUMBER retorna um número DECIMAL.
Se ocorrer falha na conversão no *formato*, um erro será gerado.
## Exemplos
O exemplo a seguir converte a string `12,454.8-` em um número:
```
select to_number('12,454.8-', '99G999D9S');
to_number
-----------
-12454.8
```
O exemplo a seguir converte a string `$ 12,454.88` em um número:
```
select to_number('$ 12,454.88', 'L 99G999D99');
to_number
-----------
12454.88
```
O exemplo a seguir converte a string `$ 2,012,454.88` em um número:
```
select to_number('$ 2,012,454.88', 'L 9,999,999.99');
to_number
-----------
2012454.88
```
# UNBASE64 função
A UNBASE64 função converte um argumento de uma string de base 64 em um binário.
A codificação Base64 é comumente usada para representar dados binários (como imagens, arquivos ou informações criptografadas) em um formato textual seguro para transmissão por vários canais de comunicação (como e-mail, parâmetros de URL ou armazenamento de banco de dados).
A UNBASE64 função permite reverter esse processo e recuperar os dados binários originais. Esse tipo de funcionalidade pode ser útil em cenários em que você precisa trabalhar com dados codificados no formato Base64, como na integração com sistemas externos ou APIs que usam o Base64 como mecanismo de transferência de dados.
## Sintaxe
```
unbase64(expr)
```
## Argumentos
*expr*
Uma expressão STRING no formato base64.
## Tipo de retorno
`BINARY`
## Exemplo
No exemplo a seguir, a string codificada em Base64 `'U3BhcmsgU1FM'` é convertida novamente na string original. `'Spark SQL'`
```
SELECT unbase64('U3BhcmsgU1FM');
Spark SQL
```
# Função UNHEX
A função UNHEX converte uma string hexadecimal de volta à sua representação de string original.
Essa função pode ser útil em cenários em que você precisa trabalhar com dados que foram armazenados ou transmitidos em formato hexadecimal e restaurar a representação da string original para processamento ou exibição adicionais.
[A função UNHEX é a contrapartida da função HEX.](HEX.md)
## Sintaxe
```
unhex(expr)
```
## Argumentos
*expr*
Uma expressão STRING de caracteres hexadecimais.
## Tipo de retorno
UNHEX retorna um BINÁRIO.
Se o comprimento de *expr* for ímpar, o primeiro caractere será descartado e o resultado será preenchido com um byte nulo. Se *expr* contiver caracteres não hexadecimais, o resultado será NULL.
## Exemplo
O exemplo a seguir converte uma string hexadecimal de volta à sua representação de string original usando as funções UNHEX () e DECODE () juntas. A primeira parte da consulta usa a função UNHEX () para converter a string hexadecimal '537061726B2053514C' em sua representação binária. A segunda parte da consulta usa a função DECODE () para converter os dados binários obtidos da função UNHEX () em uma string, usando a codificação de caracteres 'UTF-8'. A saída da consulta é a string original 'Spark\$1SQL' que foi convertida em hexadecimal e depois novamente em uma string.
```
SELECT decode(unhex('537061726B2053514C'), 'UTF-8');
Spark SQL
```
# Strings de formato datetime
Você pode usar padrões de data e hora nos seguintes cenários comuns:
+ Ao trabalhar com fontes de dados CSV e JSON para analisar e formatar conteúdo de data e hora
+ Ao converter entre tipos de string e tipos de data ou timestamp usando funções como:
+ unix\$1timestamp
+ date\$1format
+ carimbo de data/hora to\$1unix\$1
+ from\$1unixtime
+ to\$1date
+ to\$1timestamp
+ from\$1utc\$1timestamp
+ to\$1utc\$1timestamp
Use as letras padrão na tabela a seguir para análise e formatação de data e hora.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/clean-rooms/latest/sql-reference/FORMAT_strings.html)
O número de letras padrão determina o tipo de formato:
Formato de texto
+ Use de 1 a 3 letras para a forma abreviada (por exemplo, “Mon” para segunda-feira)
+ Use exatamente 4 letras para o formulário completo (por exemplo, “segunda-feira”)
+ Não use 5 ou mais letras - isso causará um erro
Formato numérico (n)
+ O valor n representa o número máximo de letras permitido
+ Para padrões de letra única:
+ A saída usa dígitos mínimos sem preenchimento
+ Para vários padrões de letras:
+ A saída é preenchida com zeros para corresponder à largura da contagem de letras
+ Ao analisar, a entrada deve conter o número exato de dígitos
Formato de número/texto
+ Para 3 ou mais letras, siga as regras de formato de texto
+ Para menos letras, siga as regras de formato numérico
Formato de fração
+ Use de 1 a 9 caracteres 'S' (por exemplo, SSSSSS)
+ Para análise:
+ Aceite frações entre 1 e o número de caracteres S
+ Para formatação:
+ Almofada com zeros para corresponder ao número de caracteres S
+ Suporta até 6 dígitos para precisão de microssegundos
+ Pode analisar nanossegundos, mas trunca dígitos extras
Formato do ano
+ A contagem de letras define a largura mínima do campo para preenchimento
+ Para duas letras:
+ Imprime os dois últimos dígitos
+ Analisa anos entre 2000 e 2099
+ Por menos de quatro letras (exceto duas):
+ Mostra o sinal apenas para anos negativos
+ Não use 7 ou mais letras - isso causará um erro
Formato do mês
+ Use 'M' para o formulário padrão ou 'L' para o formulário autônomo
+ Único 'M' ou 'L':
+ Mostra os números dos meses de 1 a 12 sem preenchimento
+ 'MM' ou 'LL':
+ Mostra os números dos meses de 01 a 12 com preenchimento
+ 'MMM':
+ Mostra o nome abreviado do mês no formato padrão
+ Deve fazer parte de um padrão de data completo
+ 'LLL':
+ Mostra o nome abreviado do mês em formato independente
+ Use para formatação somente por mês
+ 'MMMM':
+ Mostra o nome completo do mês no formato padrão
+ Use para datas e carimbos de data e hora
+ 'LLLL':
+ Mostra o nome completo do mês em formato independente
+ Use para formatação somente por mês
Formatos de fuso horário
+ am-pm: use apenas 1 letra
+ ID de zona (V): use apenas 2 letras
+ Nomes de zonas (z):
+ 1-3 letras: mostra o nome curto
+ 4 letras: mostra o nome completo
+ Não use 5 ou mais letras
Formatos de offset
+ X e x:
+ 1 letra: Mostra a hora (\$101) ou hora-minuto (\$10130)
+ 2 letras: Mostra hora-minuto sem dois pontos (\$10130)
+ 3 letras: mostra hora-minuto com dois pontos (\$1 01:30)
+ 4 letras: mostra hour-minute-second sem dois pontos (\$1013015)
+ 5 letras: mostra hour-minute-second com dois pontos (\$1 01:30:15)
+ X usa 'Z' para compensação zero
+ x usa '\$100', '\$10000' ou '\$1 00:00 'para compensação zero
+ U:
+ 1 letra: mostra a forma abreviada (GMT\$18)
+ 4 letras: Mostra o formulário completo (GMT\$1 08:00)
+ Z:
+ 1-3 letras: Mostra hora-minuto sem dois pontos (\$10130)
+ 4 letras: Mostra a forma localizada completa
+ 5 letras: mostra hour-minute-second com dois pontos
Seções opcionais
+ Use colchetes [] para marcar conteúdo opcional
+ Você pode aninhar seções opcionais
+ Todos os dados válidos aparecem na saída
+ A entrada pode omitir seções opcionais inteiras
**nota**
Os símbolos 'E', 'F', 'q' e 'Q' funcionam somente para formatação de data e hora (como date\$1format). Não os use para análise de data e hora (como to\$1timestamp).
# Strings de formato numérico
As sequências de formato numérico a seguir se aplicam a funções como TO\$1NUMBER e TO\$1CHAR.
+ Para obter exemplos de strings de formatação como números, consulte [TO\$1NUMBER](TO_NUMBER.md).
+ Para obter exemplos de números de formatação como strings, consulte [TO\$1CHAR](TO_CHAR.md).
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/clean-rooms/latest/sql-reference/Numeric_formating.html)
# Perfis de data e hora
As funções de data e hora permitem que você execute uma ampla variedade de operações em dados de data e hora, como extrair partes de uma data, realizar cálculos de data, formatar datas e horas e trabalhar com a data e a hora atuais. Essas funções são essenciais para tarefas como análise de dados, relatórios e manipulação de dados envolvendo dados temporais.
AWS Clean Rooms suporta as seguintes funções de data e hora:
**Topics**
+ [Função ADD\$1MONTHS](ADD_MONTHS.md)
+ [Função CONVERT\$1TIMEZONE](s_CONVERT_TIMEZONE.md)
+ [Função CURRENT\$1DATE](CURRENT_DATE_function.md)
+ [função CURRENT\$1TIMESTAMP](CURRENT_TIMESTAMP.md)
+ [função DATE\$1ADD](DATE_ADD_function.md)
+ [função DATE\$1DIFF](DATE_DIFF_function.md)
+ [Função DATE\$1PART](DATE_PART_function.md)
+ [Função DATE\$1TRUNC](DATE_TRUNC.md)
+ [Função DAY](DAY.md)
+ [função DAYOFMONTH](DAYOFMONTH.md)
+ [Função DAYOFWEEK](DAYOFWEEK.md)
+ [Função DAYOFYEAR](DAYOFYEAR.md)
+ [Função EXTRACT](EXTRACT_function.md)
+ [função FROM\$1UTC\$1TIMESTAMP](FROM_UTC_TIMESTAMP.md)
+ [Função HOUR](HOUR.md)
+ [Função MINUTE](MINUTE.md)
+ [Função MÊS](MONTH.md)
+ [SEGUNDA função](SECOND.md)
+ [Função TIMESTAMP](TIMESTAMP.md)
+ [Função TO\$1TIMESTAMP](TO_TIMESTAMP.md)
+ [Função YEAR](YEAR.md)
+ [Partes da data para funções de data ou de timestamp](Dateparts_for_datetime_functions.md)
# Função ADD\$1MONTHS
ADD\$1MONTHS adiciona o número especificado de meses a um valor ou expressão de data ou timestamp. A função [DATE\$1ADD](DATE_ADD_function.md) oferece funcionalidade semelhante.
## Sintaxe
```
ADD_MONTHS( {date | timestamp}, integer)
```
## Argumentos
*date* \$1 *timestamp*
Uma coluna de data ou timestamp ou uma expressão que converta implicitamente em uma data ou timestamp. Se a data for o último dia do mês ou se o mês resultante for mais curto, a função retorna o último dia do mês nos resultados. Para outras datas, o resultado contém o mesmo número de dia que a expressão de data.
*inteiro*
Um número inteiro positivo ou negativo. Use um número negativo para subtrair meses de datas.
## Tipo de retorno
TIMESTAMP
## Exemplo
A seguinte consulta usa a função de ADD\$1MONTHS dentro de uma função TRUNC. A função TRUNC remove o horário do dia dos resultados de ADD\$1MONTHS. A função ADD\$1MONTHS adiciona 12 meses a cada valor da coluna CALDATE.
```
select distinct trunc(add_months(caldate, 12)) as calplus12,
trunc(caldate) as cal
from date
order by 1 asc;
calplus12 | cal
------------+------------
2009-01-01 | 2008-01-01
2009-01-02 | 2008-01-02
2009-01-03 | 2008-01-03
...
(365 rows)
```
Os seguintes exemplos demonstram o comportamento quando a função ADD\$1MONTHS opera em datas com meses que têm diferentes número de dias.
```
select add_months('2008-03-31',1);
add_months
---------------------
2008-04-30 00:00:00
(1 row)
select add_months('2008-04-30',1);
add_months
---------------------
2008-05-31 00:00:00
(1 row)
```
# Função CONVERT\$1TIMEZONE
CONVERT\$1TIMEZONE converte um timestamp de um fuso horário para outro. A função se ajusta automaticamente para o horário de verão.
## Sintaxe
```
CONVERT_TIMEZONE ( ['source_timezone',] 'target_timezone', 'timestamp')
```
## Argumentos
*source\$1timezone*
(Opcional) O fuso horário do timestamp atual. O padrão é UTC.
*target\$1timezone*
O fuso horário do novo timestamp.
*timestamp*
Uma coluna de timestamp ou uma expressão que converta implicitamente para um timestamp.
## Tipo de retorno
TIMESTAMP
## Exemplos
O exemplo a seguir converte o valor de carimbo de data/hora do fuso horário UTC padrão em PST.
```
select convert_timezone('PST', '2008-08-21 07:23:54');
convert_timezone
------------------------
2008-08-20 23:23:54
```
O exemplo a seguir converte o valor do timestamp na coluna LISTTIME do fuso horário UTC padrão para PST. Embora o timestamp esteja no período de horário de verão, ele é convertido para o horário padrão, pois o fuso horário de destino é especificado como uma abreviação (PST).
```
select listtime, convert_timezone('PST', listtime) from listing
where listid = 16;
listtime | convert_timezone
--------------------+-------------------
2008-08-24 09:36:12 2008-08-24 01:36:12
```
O exemplo a seguir converte uma coluna LISTTIME de carimbo de data/hora do fuso horário UTC padrão em fuso horário. US/Pacific A fuso horário de destino usa um nome de fuso horário e o timestamp está no horário de verão, portanto a função retorna o horário de verão.
```
select listtime, convert_timezone('US/Pacific', listtime) from listing
where listid = 16;
listtime | convert_timezone
--------------------+---------------------
2008-08-24 09:36:12 | 2008-08-24 02:36:12
```
O exemplo a seguir converte uma string de timestamp de EST para PST:
```
select convert_timezone('EST', 'PST', '20080305 12:25:29');
convert_timezone
-------------------
2008-03-05 09:25:29
```
O exemplo a seguir converte um timestamp para o horário padrão do Leste dos EUA, pois o fuso horário de destino usa um nome de fuso horário (America/New\$1York) e o timestamp está dentro do período de horário padrão.
```
select convert_timezone('America/New_York', '2013-02-01 08:00:00');
convert_timezone
---------------------
2013-02-01 03:00:00
(1 row)
```
O seguinte exemplo converte o timestamp para o horário de verão do Leste dos EUA, pois o fuso horário de destino usa um nome de fuso horário (America/New\$1York) e o timestamp está dentro do período do horário de verão.
```
select convert_timezone('America/New_York', '2013-06-01 08:00:00');
convert_timezone
---------------------
2013-06-01 04:00:00
(1 row)
```
O seguinte exemplo demonstra o uso de deslocamentos.
```
SELECT CONVERT_TIMEZONE('GMT','NEWZONE +2','2014-05-17 12:00:00') as newzone_plus_2,
CONVERT_TIMEZONE('GMT','NEWZONE-2:15','2014-05-17 12:00:00') as newzone_minus_2_15,
CONVERT_TIMEZONE('GMT','America/Los_Angeles+2','2014-05-17 12:00:00') as la_plus_2,
CONVERT_TIMEZONE('GMT','GMT+2','2014-05-17 12:00:00') as gmt_plus_2;
newzone_plus_2 | newzone_minus_2_15 | la_plus_2 | gmt_plus_2
---------------------+---------------------+---------------------+---------------------
2014-05-17 10:00:00 | 2014-05-17 14:15:00 | 2014-05-17 10:00:00 | 2014-05-17 10:00:00
(1 row)
```
# Função CURRENT\$1DATE
CURRENT\$1DATE retorna uma data no fuso horário da sessão atual (UTC por padrão) no formato padrão:. YYYY-MM-DD
**nota**
CURRENT\$1DATE retorna a data de início para a transação atual, não para o início da instrução atual. Considere o cenário em que você inicia uma transação contendo várias declarações em 10/01/08 23:59, e a declaração contendo CURRENT\$1DATE é executada em 10/02/08 00:00. CURRENT\$1DATE retorna `10/01/08`, não `10/02/08`.
## Sintaxe
```
CURRENT_DATE
```
## Tipo de retorno
DATE
## Exemplo
O exemplo a seguir retorna a data atual (no local em Região da AWS que a função é executada).
```
select current_date;
date
------------
2008-10-01
```
# função CURRENT\$1TIMESTAMP
CURRENT\$1TIMESTAMP retorna a data e a hora atuais, incluindo a data, a hora e (opcionalmente) os milissegundos ou microssegundos.
Essa função é útil quando você precisa obter a data e a hora atuais, por exemplo, para registrar a data e hora de um evento, realizar cálculos com base no tempo ou preencher colunas. date/time
## Sintaxe
```
current_timestamp()
```
## Tipo de retorno
A função CURRENT\$1TIMESTAMP retorna uma DATA.
## Exemplo
O exemplo a seguir retorna a data e a hora atuais no momento em que a consulta é executada, que é 25 de abril de 2020, às 15:49:11.914 (15:49:11.914 PM).
```
SELECT current_timestamp();
2020-04-25 15:49:11.914
```
O exemplo a seguir recupera a data e a hora atuais de cada linha na `squirrels` tabela.
```
SELECT current_timestamp() FROM squirrels
```
# função DATE\$1ADD
Retorna a data que é num\$1days após start\$1date.
## Sintaxe
```
date_add(start_date, num_days)
```
## Argumentos
*data\$1inicial*
O valor da data inicial.
*num\$1dias*
O número de dias a serem adicionados (inteiro). Um número positivo soma dias, um número negativo subtrai dias.
## Tipo de retorno
DATE
## Exemplos
O exemplo a seguir adiciona um dia a uma data:
```
SELECT date_add('2016-07-30', 1);
Result:
2016-07-31
```
O exemplo a seguir adiciona vários dias.
```
SELECT date_add('2016-07-30', 5);
Result:
2016-08-04
```
## Observações de uso
Esta documentação é para a função DATE\$1ADD do Spark SQL, que fornece uma interface mais simples para adicionar dias às datas em comparação com algumas outras variantes do SQL. Para adicionar outros intervalos, como meses ou anos, funções diferentes podem ser necessárias.
# função DATE\$1DIFF
DATE\$1DIFF retorna a diferença entre as partes de data de duas expressões de data ou hora.
## Sintaxe
```
date_diff(endDate, startDate)
```
## Argumentos
*endDate*
Uma expressão DATE.
*startDate*
Uma expressão DATE.
## Tipo de retorno
BIGINT
## Exemplos com uma coluna DATE
O exemplo a seguir encontra a diferença, em número de semanas, entre dois valores de data literais.
```
select date_diff(week,'2009-01-01','2009-12-31') as numweeks;
numweeks
----------
52
(1 row)
```
O exemplo a seguir encontra a diferença, em horas, entre dois valores de data literais. Quando você não fornece o valor de hora para uma data, o padrão é 00:00:00.
```
select date_diff(hour, '2023-01-01', '2023-01-03 05:04:03');
date_diff
----------
53
(1 row)
```
O exemplo a seguir encontra a diferença, em dias, entre dois valores literais de TIMESTAMETZ.
```
Select date_diff(days, 'Jun 1,2008 09:59:59 EST', 'Jul 4,2008 09:59:59 EST')
date_diff
----------
33
```
O exemplo a seguir encontra a diferença, em dias, entre duas datas na mesma linha de uma tabela.
```
select * from date_table;
start_date | end_date
-----------+-----------
2009-01-01 | 2009-03-23
2023-01-04 | 2024-05-04
(2 rows)
select date_diff(day, start_date, end_date) as duration from date_table;
duration
---------
81
486
(2 rows)
```
O exemplo a seguir encontra a diferença, em número de trimestres, entre um valor literal no passado e a data de hoje. Este exemplo presume que a data atual seja 5 de junho de 2008. Você pode nomear as partes da data por completo ou abreviá-las. O nome da coluna padrão para a função DATE\$1DIFF é DATE\$1DIFF.
```
select date_diff(qtr, '1998-07-01', current_date);
date_diff
-----------
40
(1 row)
```
O exemplo a seguir une as tabelas SALES e LISTING para calcular quantos dias os ingressos foram vendidos para as listagens 1000 a 1005 depois de serem listados. A espera mais longa para vendas dessas ofertas foi de 15 dias e a espera mais curta foi de menos de um dia (0 dias).
```
select priceperticket,
date_diff(day, listtime, saletime) as wait
from sales, listing where sales.listid = listing.listid
and sales.listid between 1000 and 1005
order by wait desc, priceperticket desc;
priceperticket | wait
---------------+------
96.00 | 15
123.00 | 11
131.00 | 9
123.00 | 6
129.00 | 4
96.00 | 4
96.00 | 0
(7 rows)
```
Este exemplo calcula o número médio de horas que os vendedores esperaram para todas as vendas de ingressos.
```
select avg(date_diff(hours, listtime, saletime)) as avgwait
from sales, listing
where sales.listid = listing.listid;
avgwait
---------
465
(1 row)
```
## Exemplos com uma coluna TIME
O TIME\$1TEST da tabela a seguir tem uma coluna TIME\$1VAL (tipo TIME) com três valores inseridos.
```
select time_val from time_test;
time_val
---------------------
20:00:00
00:00:00.5550
00:58:00
```
O exemplo a seguir localiza a diferença no número de horas entre a coluna TIME\$1VAL e um literal de tempo.
```
select date_diff(hour, time_val, time '15:24:45') from time_test;
date_diff
-----------
-5
15
15
```
O exemplo a seguir localiza a diferença no número de minutos entre dois valores de tempo literal.
```
select date_diff(minute, time '20:00:00', time '21:00:00') as nummins;
nummins
----------
60
```
## Exemplos com uma coluna TIMETZ
O TIMETZ\$1TEST da tabela de exemplo a seguir tem uma coluna TIMETZ\$1VAL (tipo TIMETZ) com três valores inseridos.
```
select timetz_val from timetz_test;
timetz_val
------------------
04:00:00+00
00:00:00.5550+00
05:58:00+00
```
O exemplo a seguir localiza as diferenças no número de horas, entre um literal TIMETZ e timetz\$1val.
```
select date_diff(hours, timetz '20:00:00 PST', timetz_val) as numhours from timetz_test;
numhours
----------
0
-4
1
```
O exemplo a seguir localiza a diferença no número de horas, entre dois valores TIMETZ literal.
```
select date_diff(hours, timetz '20:00:00 PST', timetz '00:58:00 EST') as numhours;
numhours
----------
1
```
# Função DATE\$1PART
DATE\$1PART extrai os valores de parte da data de uma expressão. DATE\$1PART é sinônimo da função PGDATE\$1PART.
## Sintaxe
```
datepart(field, source)
```
## Argumentos
*Campo*
Qual parte da fonte deve ser extraída e os valores de string suportados são os mesmos dos campos da função equivalente EXTRACT.
*source*
Uma coluna DATE ou INTERVAL de onde o campo deve ser extraído.
## Tipo de retorno
Se o *campo* for 'SEGUNDO', um DECIMAL (8, 6). Em todos os outros casos, um INTEGER.
## Exemplo
O exemplo a seguir extrai o dia do ano (DOY) de um valor de data. A saída mostra que o dia do ano para a data “2019-08-12" é. `224` Isso significa que 12 de agosto de 2019 é o 224º dia do ano de 2019.
```
SELECT datepart('doy', DATE'2019-08-12');
224
```
# Função DATE\$1TRUNC
A função DATE\$1TRUNC trunca uma expressão de timestamp ou literal com base na parte da data especificada, tal como hora, dia ou mês.
## Sintaxe
```
date_trunc(format, datetime)
```
## Argumentos
*format*
O formato que representa a unidade a ser truncada. Os formatos válidos são:
+ “YEAR”, “YYYY”, “YY” - trunque até a primeira data do ano em que o ts cai, a parte do tempo será zero
+ “TRIMESTRE” - trunque para a primeira data do trimestre em que o ts cai, a parte do tempo será zero
+ “MÊS”, “MM”, “SEGUNDA-FEIRA” - trunque para a primeira data do mês em que o ts cai, a parte do tempo será zero
+ “SEMANA” - trunque até a segunda-feira da semana em que o ts cai, a parte do tempo será zero
+ “DAY”, “DD” - zerar a parte do tempo
+ “HORA” - zerar o minuto e o segundo com parte fracionária
+ “MINUTO” - zerar o segundo com parte fracionária
+ “SEGUNDO” - zerar a segunda parte da fração
+ “MILISECOND” - zerar os microssegundos
+ “MICROSECOND” - tudo permanece
*ts*
Um valor de data e hora
## Tipo de retorno
Retorna o timestamp *ts* truncado para a unidade especificada pelo modelo de formato
## Exemplos
O exemplo a seguir trunca um valor de data para o início do ano. A saída mostra que a data “2015-03-05" foi truncada para “2015-01-01", que é o início do ano de 2015.
```
SELECT date_trunc('YEAR', '2015-03-05');
date_trunc
-----------
2015-01-01
```
# Função DAY
A função DAY retorna o dia do mês do carimbo de data/hora.
As funções de extração de data são úteis quando você precisa trabalhar com componentes específicos de uma data ou carimbo de data/hora, como ao realizar cálculos baseados em datas, filtrar dados ou formatar valores de data.
## Sintaxe
```
day(date)
```
## Argumentos
*data*
Uma expressão DATE ou TIMESTAMP.
## Retornos
A função DAY retorna um INTEIRO.
## Exemplos
O exemplo a seguir extrai o dia do mês (`30`) da data `'2009-07-30'` de entrada.
```
SELECT day('2009-07-30');
30
```
O exemplo a seguir extrai o dia do mês da `birthday` coluna da `squirrels` tabela e retorna os resultados como saída da instrução SELECT. O resultado dessa consulta será uma lista de valores de dias, um para cada linha na `squirrels` tabela, representando o dia do mês do aniversário de cada esquilo.
```
SELECT day(birthday) FROM squirrels
```
# função DAYOFMONTH
A função DAYOFMONTH retorna o dia do mês do date/timestamp (um valor entre 1 e 31, dependendo do mês e do ano).
A função DAYOFMONTH é semelhante à função DAY, mas elas têm nomes e comportamentos ligeiramente diferentes. A função DAY é mais comumente usada, mas a função DAYOFMONTH pode ser usada como alternativa. Esse tipo de consulta pode ser útil quando você precisa realizar uma análise ou filtragem com base em datas em uma tabela que contém dados de data ou data e hora, como extrair componentes específicos de uma data para processamento ou geração de relatórios adicionais.
## Sintaxe
```
dayofmonth(date)
```
## Argumentos
*data*
Uma expressão DATE ou TIMESTAMP.
## Retornos
A função DAYOFMONTH retorna um INTEIRO.
## Exemplo
O exemplo a seguir extrai o dia do mês (`30`) da data `'2009-07-30'` de entrada.
```
SELECT dayofmonth('2009-07-30');
30
```
O exemplo a seguir aplica a função DAYOFMONTH à `birthday` coluna da `squirrels` tabela. Para cada linha na `squirrels` tabela, o dia do mês da `birthday` coluna será extraído e retornado como saída da instrução SELECT. O resultado dessa consulta será uma lista de valores de dias, um para cada linha na `squirrels` tabela, representando o dia do mês do aniversário de cada esquilo.
```
SELECT dayofmonth(birthday) FROM squirrels
```
# Função DAYOFWEEK
A função DAYOFWEEK usa uma data ou timestamp como entrada e retorna o dia da semana como um número (1 para domingo, 2 para segunda-feira,..., 7 para sábado).
Essa função de extração de data é útil quando você precisa trabalhar com componentes específicos de uma data ou carimbo de data/hora, como ao realizar cálculos baseados em datas, filtrar dados ou formatar valores de data.
## Sintaxe
```
dayofweek(date)
```
## Argumentos
*data*
Uma expressão DATE ou TIMESTAMP.
## Retornos
A função DAYOFWEEK retorna um INTEGER onde
1 = domingo
2 = segunda-feira
3 = terça-feira
4 = quarta-feira
5 = quinta-feira
6 = sexta-feira
7 = sábado
## Exemplos
O exemplo a seguir extrai o dia da semana dessa data, que é 5 (representando quinta-feira).
```
SELECT dayofweek('2009-07-30');
5
```
O exemplo a seguir extrai o dia da semana da `birthday` coluna da `squirrels` tabela e retorna os resultados como saída da instrução SELECT. O resultado dessa consulta será uma lista dos valores do dia da semana, um para cada linha na `squirrels` tabela, representando o dia da semana do aniversário de cada esquilo.
```
SELECT dayofweek(birthday) FROM squirrels
```
# Função DAYOFYEAR
A função DAYOFYEAR é uma função de extração de data que usa uma data ou carimbo de data/hora como entrada e retorna o dia do ano (um valor entre 1 e 366, dependendo do ano e se é um ano bissexto).
Essa função é útil quando você precisa trabalhar com componentes específicos de uma data ou carimbo de data/hora, como ao realizar cálculos baseados em datas, filtrar dados ou formatar valores de data.
## Sintaxe
```
dayofyear(date)
```
## Argumentos
*data*
Uma expressão DATE ou TIMESTAMP.
## Retornos
A função DAYOFYEAR retorna um INTEIRO (entre 1 e 366, dependendo do ano e se é um ano bissexto).
## Exemplos
O exemplo a seguir extrai o dia do ano (`100`) da data `'2016-04-09'` de entrada.
```
SELECT dayofyear('2016-04-09');
100
```
O exemplo a seguir extrai o dia do ano da `birthday` coluna da `squirrels` tabela e retorna os resultados como saída da instrução SELECT.
```
SELECT dayofyear(birthday) FROM squirrels
```
# Função EXTRACT
A função EXTRACT retorna a parte da data ou hora de um valor de TIMESTAMP, TIMESTAMPTZ, TIME ou TIMETZ. Os exemplos incluem um dia, mês, ano, hora, minuto, segundo, milissegundo ou microssegundo de um timestamp.
## Sintaxe
```
EXTRACT(datepart FROM source)
```
## Argumentos
*datepart*
O subcampo de uma data ou hora que será extraído, como dia, mês, ano, hora, minuto, segundo, milissegundo ou microssegundo. Para os possíveis valores, consulte [Partes da data para funções de data ou de timestamp](Dateparts_for_datetime_functions.md).
*source*
Uma coluna ou expressão que é avaliada como um tipo de dado TIMESTAMP, TIMESTAMPTZ, TIME ou TIMETZ.
## Tipo de retorno
INTEGER se o valor de *source* for avaliado como TIMESTAMP, TIME ou TIMETZ.
DOUBLE PRECISION se o valor de *source* for avaliado como TIMESTAMPTZ.
## Exemplos com TIME
O TIME\$1TEST da tabela a seguir tem uma coluna TIME\$1VAL (tipo TIME) com três valores inseridos.
```
select time_val from time_test;
time_val
---------------------
20:00:00
00:00:00.5550
00:58:00
```
O exemplo a seguir extrai os minutos de cada time\$1val.
```
select extract(minute from time_val) as minutes from time_test;
minutes
-----------
0
0
58
```
O exemplo a seguir extrai as horas de cada time\$1val.
```
select extract(hour from time_val) as hours from time_test;
hours
-----------
20
0
0
```
# função FROM\$1UTC\$1TIMESTAMP
A função FROM\$1UTC\$1TIMESTAMP converte a data de entrada de UTC (Tempo Universal Coordenado) para o fuso horário especificado.
Essa função é útil quando você precisa converter valores de data e hora do UTC para um fuso horário específico. Isso pode ser importante ao trabalhar com dados originários de diferentes partes do mundo e que precisam ser apresentados no horário local apropriado.
## Sintaxe
```
from_utc_timestamp(timestamp, timezone
```
## Argumentos
*timestamp*
Uma expressão TIMESTAMP com um timestamp UTC.
*timezone*
Uma expressão STRING que é um fuso horário válido no qual a data ou o timestamp de entrada devem ser convertidos.
## Retornos
A função FROM\$1UTC\$1TIMESTAMP retorna um TIMESTAMP.
## Exemplo
O exemplo a seguir converte a data de entrada de UTC para o fuso horário especificado (`'Asia/Seoul'`), que nesse caso é 9 horas antes do UTC. A saída resultante é a data e a hora no fuso horário de Seul, qual é`2016-08-31 09:00:00`.
```
SELECT from_utc_timestamp('2016-08-31', 'Asia/Seoul');
2016-08-31 09:00:00
```
# Função HOUR
A função HOUR é uma função de extração de tempo que usa uma hora ou um carimbo de data/hora como entrada e retorna o componente de hora (um valor entre 0 e 23).
Essa função de extração de hora é útil quando você precisa trabalhar com componentes específicos de uma hora ou carimbo de data/hora, como ao realizar cálculos baseados em tempo, filtrar dados ou formatar valores de hora.
## Sintaxe
```
hour(timestamp)
```
## Argumentos
*timestamp*
Uma expressão TIMESTAMP.
## Retornos
A função HOUR retorna um INTEIRO.
## Exemplo
O exemplo a seguir extrai o componente hora (`12`) do `'2009-07-30 12:58:59'` timestamp de entrada.
```
SELECT hour('2009-07-30 12:58:59');
12
```
# Função MINUTE
A função MINUTE é uma função de extração de tempo que usa uma hora ou um carimbo de data/hora como entrada e retorna o componente minuto (um valor entre 0 e 60).
## Sintaxe
```
minute(timestamp)
```
## Argumentos
*timestamp*
Uma expressão TIMESTAMP ou uma STRING de um formato de timestamp válido.
## Retornos
A função MINUTE retorna um INTEIRO.
## Exemplo
O exemplo a seguir extrai o componente minute (`58`) do `'2009-07-30 12:58:59'` timestamp de entrada.
```
SELECT minute('2009-07-30 12:58:59');
58
```
# Função MÊS
A função MONTH é uma função de extração de hora que usa uma hora ou um carimbo de data/hora como entrada e retorna o componente do mês (um valor entre 0 e 12).
## Sintaxe
```
month(date)
```
## Argumentos
*data*
Uma expressão TIMESTAMP ou uma STRING de um formato de timestamp válido.
## Retornos
A função MONTH retorna um INTEIRO.
## Exemplo
O exemplo a seguir extrai o componente month (`7`) do `'2016-07-30'` timestamp de entrada.
```
SELECT month('2016-07-30');
7
```
# SEGUNDA função
A função SECOND é uma função de extração de tempo que usa uma hora ou um timestamp como entrada e retorna o segundo componente (um valor entre 0 e 60).
## Sintaxe
```
second(timestamp)
```
## Argumentos
*timestamp*
Uma expressão TIMESTAMP.
## Retornos
A função SECOND retorna um INTEIRO.
## Exemplo
O exemplo a seguir extrai o segundo componente (`59`) do `'2009-07-30 12:58:59'` timestamp de entrada.
```
SELECT second('2009-07-30 12:58:59');
59
```
# Função TIMESTAMP
A função TIMESTAMP pega um valor (normalmente um número) e o converte em um tipo de dados de carimbo de data/hora.
Essa função é útil quando você precisa converter um valor numérico representando uma hora ou data em um tipo de dados de carimbo de data/hora. Isso pode ser útil quando você está trabalhando com dados armazenados em um formato numérico, como carimbos de data/hora do Unix ou horário de época.
## Sintaxe
```
timestamp(expr)
```
## Argumentos
*expr*
Qualquer expressão que possa ser convertida em TIMESTAMP.
## Retornos
A função TIMESTAMP retorna um TIMESTAMP.
## Exemplo
O exemplo a seguir converte um timestamp numérico Unix (`1632416400`) em seu tipo de dados de timestamp correspondente: 22 de setembro de 2021 às 12:00:00 UTC.
```
SELECT timestamp(1632416400);
2021-09-22 12:00:00 UTC
```
# Função TO\$1TIMESTAMP
TO\$1TIMESTAMP converte uma string de TIMESTAMP em TIMESTAMPTZ.
## Sintaxe
```
to_timestamp (timestamp)
```
```
to_timestamp (timestamp, format)
```
## Argumentos
*timestamp*
Uma string de carimbo de data/hora ou um tipo de dados que pode ser convertido em uma string de carimbo de data/hora.
*format*
Uma string literal que corresponde aos padrões de data e hora do Spark. Para padrões de data e hora válidos, consulte Padrões de [data e hora para formatação](https://spark.apache.org/docs/latest/sql-ref-datetime-pattern.html) e análise.
## Tipo de retorno
TIMESTAMP
## Exemplos
O exemplo a seguir demonstra o uso da função TO\$1TIMESTAMP para converter uma string TIMESTAMP em TIMESTAMP.
```
select current_timestamp() as timestamp, to_timestamp( current_timestamp(), 'YYYY-MM-DD HH24:MI:SS') as second;
timestamp | second
-------------------------- ----------------------
2021-04-05 19:27:53.281812 | 2021-04-05 19:27:53+00
```
É possível enviar parte de uma data com TO\$1TIMESTAMP. As partes restantes da data são definidas como valores padrão. A hora é incluída na saída:
```
SELECT TO_TIMESTAMP('2017','YYYY');
to_timestamp
--------------------------
2017-01-01 00:00:00+00
```
A instrução SQL a seguir converte a string '2011-12-18 24:38:15 'em um TIMESTAMP. O resultado é um TIMESTAMP que cai no dia seguinte porque o número de horas é superior a 24 horas:
```
select to_timestamp('2011-12-18 24:38:15', 'YYYY-MM-DD HH24:MI:SS');
to_timestamp
----------------------
2011-12-19 00:38:15+00
```
# Função YEAR
A função YEAR é uma função de extração de data que usa uma data ou timestamp como entrada e retorna o componente do ano (um número de quatro dígitos).
## Sintaxe
```
year(date)
```
## Argumentos
*data*
Uma expressão DATE ou TIMESTAMP.
## Retornos
A função YEAR retorna um INTEIRO.
## Exemplo
O exemplo a seguir extrai o componente ano (`2016`) da data `'2016-07-30'` de entrada.
```
SELECT year('2016-07-30');
2016
```
O exemplo a seguir extrai o componente ano da `birthday` coluna da `squirrels` tabela e retorna os resultados como saída da instrução SELECT. O resultado dessa consulta será uma lista dos valores do ano, um para cada linha na `squirrels` tabela, representando o ano do aniversário de cada esquilo.
```
SELECT year(birthday) FROM squirrels
```
# Partes da data para funções de data ou de timestamp
A tabela a seguir identifica os nomes e abreviações da parte da data e da hora que são aceitos como argumentos para as seguintes funções:
+ DATE\$1ADD
+ DATE\$1DIFF
+ DATE\$1PART
+ EXTRACT
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/clean-rooms/latest/sql-reference/Dateparts_for_datetime_functions.html)
## Variações nos resultados com segundos, milissegundos e microssegundos
Pequenas diferenças nos resultados de consultas ocorrem quando diferentes funções de data especificam segundos, milissegundos ou microssegundos como partes da data:
+ A função EXTRACT retorna números inteiros somente para a parte da data especificada, ignorando partes de data de níveis superiores e inferiores. Se a parte da data especificada é segundos, os milissegundos e os microssegundos não são incluídos no resultados. Se a parte da data especificada é milissegundos, segundos e microssegundos não são incluídos. Se a parte da data especificada é microssegundos, segundos e milissegundos não são incluídos.
+ A função DATE\$1PART retorna a parte completa de segundos do timestamp, independente da parte de data especificada, retornando um valor decimal ou um número inteiro conforme necessário.
## Observações de CENTURY, EPOCH, DECADE e MIL
CENTURY ou CENTURIES
AWS Clean Rooms interpreta um SÉCULO como começando com o ano *\$1\$1 \$11* e terminando com o ano: `###0`
```
select extract (century from timestamp '2000-12-16 12:21:13');
date_part
-----------
20
(1 row)
select extract (century from timestamp '2001-12-16 12:21:13');
date_part
-----------
21
(1 row)
```
EPOCH
A AWS Clean Rooms implementação do EPOCH é relativa a 1970-01-01 00:00:00.000 000, independente do fuso horário em que o cluster reside. Você pode precisar deslocar os resultados pela diferença em horas dependendo do fuso horário onde o cluster está localizado.
DECADE ou DECADES
AWS Clean Rooms interpreta o DECADE ou DECADES DATEPART com base no calendário comum. Por exemplo, como o calendário comum começa a partir do ano 1, a primeira década (década 1) é 0001-01-01 a 0009-12-31 e a segunda década (década 2) é 0010-01-01 a 0019-12-31. Por exemplo, a década 201 vai de 2000-01-01 a 2009-12-31:
```
select extract(decade from timestamp '1999-02-16 20:38:40');
date_part
-----------
200
(1 row)
select extract(decade from timestamp '2000-02-16 20:38:40');
date_part
-----------
201
(1 row)
select extract(decade from timestamp '2010-02-16 20:38:40');
date_part
-----------
202
(1 row)
```
MIL ou MILS
AWS Clean Rooms interpreta uma MIL para começar com o primeiro dia do ano *\$1001* e terminar com o último dia do ano`#000`:
```
select extract (mil from timestamp '2000-12-16 12:21:13');
date_part
-----------
2
(1 row)
select extract (mil from timestamp '2001-12-16 12:21:13');
date_part
-----------
3
(1 row)
```
# Funções de criptografia e descriptografia
As funções de criptografia e descriptografia ajudam os desenvolvedores de SQL a proteger dados confidenciais contra acesso não autorizado ou uso indevido, convertendo-os entre um formulário de texto simples legível e um formulário de texto cifrado ilegível.
AWS Clean Rooms O Spark SQL é compatível com as seguintes funções de criptografia e decodificação:
**Topics**
+ [função AES\$1ENCRYPT](AES_ENCRYPT.md)
+ [função AES\$1DECRYPT](AES_DECRYPT.md)
# função AES\$1ENCRYPT
A função AES\$1ENCRYPT é usada para criptografar dados usando o algoritmo Advanced Encryption Standard (AES).
## Sintaxe
```
aes_encrypt(expr, key[, mode[, padding[, iv[, aad]]]])
```
## Argumentos
*expr*
O valor binário a ser criptografado.
*chave*
A senha a ser usada para criptografar os dados.
Comprimentos de chave de 16, 24 e 32 bits são suportados.
*modo*
Especifica qual modo de criptografia de bloco deve ser usado para criptografar mensagens.
Modos válidos: ECB (eletrônico CodeBook), GCM (modo Galois/Counter), CBC (Cipher-Block Chaining).
*acolchoamento*
Especifica como preencher mensagens cujo tamanho não seja múltiplo do tamanho do bloco.
Valores válidos: PKCS, NONE, DEFAULT.
O preenchimento DEFAULT significa PKCS (Padrões de Criptografia de Chave Pública) para ECB, NONE para GCM e PKCS para CBC.
As combinações suportadas de (*modo*, *preenchimento*) são ('ECB', 'PKCS'), ('GCM', 'NONE') e ('CBC', 'PKCS').
*iv*
Vetor de inicialização opcional (IV). Compatível apenas com os modos CBC e GCM.
Valores válidos: 12 bytes para GCM e 16 bytes para CBC.
*anúncio*
Dados autenticados adicionais (AAD) opcionais. Compatível apenas com o modo GCM. Isso pode ser qualquer entrada de formato livre e deve ser fornecido tanto para criptografia quanto para decodificação.
## Tipo de retorno
A função AES\$1ENCRYPT retorna um valor criptografado de *expr* usando AES em determinado modo com o preenchimento especificado.
## Exemplos
O exemplo a seguir demonstra como usar a função AES\$1ENCRYPT do Spark SQL para criptografar com segurança uma sequência de dados (nesse caso, a palavra “Spark”) usando uma chave de criptografia especificada. O texto cifrado resultante é então codificado em Base64 para facilitar o armazenamento ou a transmissão.
```
SELECT base64(aes_encrypt('Spark', 'abcdefghijklmnop'));
4A5jOAh9FNGwoMeuJukfllrLdHEZxA2DyuSQAWz77dfn
```
O exemplo a seguir demonstra como usar a função AES\$1ENCRYPT do Spark SQL para criptografar com segurança uma sequência de dados (nesse caso, a palavra “Spark”) usando uma chave de criptografia especificada. O texto cifrado resultante é então representado em formato hexadecimal, o que pode ser útil para tarefas como armazenamento, transmissão ou depuração de dados.
```
SELECT hex(aes_encrypt('Spark', '0000111122223333'));
83F16B2AA704794132802D248E6BFD4E380078182D1544813898AC97E709B28A94
```
O exemplo a seguir demonstra como usar a função AES\$1ENCRYPT do Spark SQL para criptografar com segurança uma sequência de dados (nesse caso, “Spark SQL”) usando uma chave de criptografia, um modo de criptografia e um modo de preenchimento especificados. O texto cifrado resultante é então codificado em Base64 para facilitar o armazenamento ou a transmissão.
```
SELECT base64(aes_encrypt('Spark SQL', '1234567890abcdef', 'ECB', 'PKCS'));
3lmwu+Mw0H3fi5NDvcu9lg==
```
# função AES\$1DECRYPT
A função AES\$1DECRYPT é usada para descriptografar dados usando o algoritmo Advanced Encryption Standard (AES).
## Sintaxe
```
aes_decrypt(expr, key[, mode[, padding[, aad]]])
```
## Argumentos
*expr*
O valor binário a ser decifrado.
*chave*
A frase secreta a ser usada para descriptografar os dados.
A frase secreta deve corresponder à chave originalmente usada para produzir o valor criptografado e ter 16, 24 ou 32 bytes.
*modo*
Especifica qual modo de criptografia de bloco deve ser usado para descriptografar mensagens.
Modos válidos: ECB, GCM, CBC.
*acolchoamento*
Especifica como preencher mensagens cujo tamanho não seja múltiplo do tamanho do bloco.
Valores válidos: PKCS, NONE, DEFAULT.
O preenchimento DEFAULT significa PKCS para ECB, NONE para GCM e PKCS para CBC.
*anúncio*
Dados autenticados adicionais (AAD) opcionais. Compatível apenas com o modo GCM. Isso pode ser qualquer entrada de formato livre e deve ser fornecido tanto para criptografia quanto para decodificação.
## Tipo de retorno
Retorna um valor descriptografado de *expr* usando AES no modo com preenchimento.
## Exemplos
O exemplo a seguir demonstra como usar a função AES\$1ENCRYPT do Spark SQL para criptografar com segurança uma sequência de dados (nesse caso, a palavra “Spark”) usando uma chave de criptografia especificada. O texto cifrado resultante é então codificado em Base64 para facilitar o armazenamento ou a transmissão.
```
SELECT base64(aes_encrypt('Spark', 'abcdefghijklmnop'));
4A5jOAh9FNGwoMeuJukfllrLdHEZxA2DyuSQAWz77dfn
```
O exemplo a seguir demonstra como usar a função AES\$1DECRYPT do Spark SQL para descriptografar dados que foram previamente criptografados e codificados em Base64. O processo de decodificação requer a chave e os parâmetros de criptografia corretos (modo de criptografia e modo de preenchimento) para recuperar com êxito os dados de texto sem formatação originais.
```
SELECT aes_decrypt(unbase64('3lmwu+Mw0H3fi5NDvcu9lg=='), '1234567890abcdef', 'ECB', 'PKCS');
Spark SQL
```
# Funções de hash
Uma função de hash é uma função matemática que converte um valor de entrada numérico em outro valor.
AWS Clean Rooms O Spark SQL é compatível com as seguintes funções de hash:
**Topics**
+ [MD5 função](s_MD5.md)
+ [Função SHA](s_SHA.md)
+ [SHA1 função](s_SHA1.md)
+ [SHA2 função](s_SHA2.md)
+ [HASH64 função xx](xxhash64.md)
# MD5 função
Usa a função hash MD5 criptográfica para converter uma string de comprimento variável em uma string de 32 caracteres que é uma representação em texto do valor hexadecimal de uma soma de verificação de 128 bits.
## Sintaxe
```
MD5(string)
```
## Argumentos
*string*
Uma string de comprimento variável.
## Tipo de retorno
A MD5 função retorna uma cadeia de caracteres de 32 caracteres que é uma representação em texto do valor hexadecimal de uma soma de verificação de 128 bits.
## Exemplos
O seguinte exemplo mostra o valor de 128 bits para a string "AWS Clean Rooms":
```
select md5('AWS Clean Rooms');
md5
----------------------------------
f7415e33f972c03abd4f3fed36748f7a
(1 row)
```
# Função SHA
Sinônimo de SHA1 função.
Consulte [SHA1 função](s_SHA1.md).
# SHA1 função
A SHA1 função usa a função hash SHA1 criptográfica para converter uma string de comprimento variável em uma string de 40 caracteres que é uma representação em texto do valor hexadecimal de uma soma de verificação de 160 bits.
## Sintaxe
SHA1 é sinônimo de. [Função SHA](s_SHA.md)
```
SHA1(string)
```
## Argumentos
*string*
Uma string de comprimento variável.
## Tipo de retorno
A SHA1 função retorna uma string de 40 caracteres que é uma representação em texto do valor hexadecimal de uma soma de verificação de 160 bits.
## Exemplo
O seguinte exemplo retorna o valor de 160 bits para a palavra "AWS Clean Rooms":
```
select sha1('AWS Clean Rooms');
```
# SHA2 função
A SHA2 função usa a função hash SHA2 criptográfica para converter uma cadeia de caracteres de comprimento variável em uma cadeia de caracteres. A string de caracteres é uma representação de texto do valor hexadecimal da soma de verificação com o número especificado de bits.
## Sintaxe
```
SHA2(string, bits)
```
## Argumentos
*string*
Uma string de comprimento variável.
*inteiro*
O número de bits nas funções de hash. Os valores válidos são 0 (igual a 256), 224, 256, 384 e 512.
## Tipo de retorno
A SHA2 função retorna uma cadeia de caracteres que é uma representação em texto do valor hexadecimal da soma de verificação ou uma cadeia vazia se o número de bits for inválido.
## Exemplo
O exemplo a seguir retorna o valor de 256 bits para a palavra “AWS Clean Rooms”:
```
select sha2('AWS Clean Rooms', 256);
```
# HASH64 função xx
A função xxhash64 retorna um valor de hash de 64 bits dos argumentos.
A função xxhash64 () é uma função hash não criptográfica projetada para ser rápida e eficiente. É frequentemente usado em aplicativos de processamento e armazenamento de dados, em que é necessário um identificador exclusivo para uma parte dos dados, mas o conteúdo exato dos dados não precisa ser mantido em segredo.
No contexto de uma consulta SQL, a função xxhash64 () pode ser usada para várias finalidades, como:
+ Gerando um identificador exclusivo para uma linha em uma tabela
+ Particionamento de dados com base em um valor de hash
+ Implementando estratégias personalizadas de indexação ou distribuição de dados
O caso de uso específico dependeria dos requisitos do aplicativo e dos dados que estão sendo processados.
## Sintaxe
```
xxhash64(expr1, expr2, ...)
```
## Argumentos
*expr 1*
Uma expressão de qualquer tipo.
*expr 2*
Uma expressão de qualquer tipo.
## Retornos
Retorna um valor de hash de 64 bits dos argumentos (BIGINT). A semente de haxixe é 42.
## Exemplo
O exemplo a seguir gera um valor de hash de 64 bits (5602566077635097486) com base na entrada fornecida. O primeiro argumento é um valor de string, nesse caso, a palavra “Spark”. O segundo argumento é uma matriz contendo o valor inteiro único 123. O terceiro argumento é um valor inteiro que representa a semente da função hash.
```
SELECT xxhash64('Spark', array(123), 2);
5602566077635097486
```
# Funções do Hyperloglog
As funções HyperLogLog (HLL) no SQL fornecem uma maneira de estimar com eficiência o número de elementos exclusivos (cardinalidade) em um grande conjunto de dados, mesmo quando o conjunto real de elementos exclusivos não está armazenado.
Os principais benefícios do uso das funções HLL são:
+ **Eficiência de memória**: os esboços HLL exigem muito menos memória do que armazenar o conjunto completo de elementos exclusivos, tornando-os adequados para grandes conjuntos de dados.
+ **Computação distribuída**: os esboços do HLL podem ser combinados em várias fontes de dados ou nós de processamento, permitindo uma estimativa de contagem exclusiva distribuída e eficiente.
+ **Resultados aproximados**: o HLL fornece uma estimativa de contagem única aproximada, com uma compensação ajustável entre precisão e uso de memória (por meio do parâmetro de precisão).
Essas funções são particularmente úteis em cenários em que você precisa estimar o número de itens exclusivos, como em aplicativos de análise, armazenamento de dados e processamento de fluxo em tempo real.
AWS Clean Rooms suporta as seguintes funções de HLL.
**Topics**
+ [função HLL\$1SKETCH\$1AGG](HLL_SKETCH_AGG.md)
+ [função HLL\$1SKETCH\$1ESTIMATE](HLL_SKETCH_ESTIMATE.md)
+ [função HLL\$1UNION](HLL_UNION.md)
+ [função HLL\$1UNION\$1AGG](HLL_UNION_AGG.md)
# função HLL\$1SKETCH\$1AGG
A função agregada HLL\$1SKETCH\$1AGG cria um esboço HLL a partir dos valores na coluna especificada. Ele retorna um tipo de dados HLLSKETCH que encapsula os valores da expressão de entrada.
A função agregada HLL\$1SKETCH\$1AGG funciona com qualquer tipo de dados e ignora valores NULL.
Quando não há linhas em uma tabela ou todas as linhas são NULL, o esboço resultante não tem pares de valor de índice, como `{"version":1,"logm":15,"sparse":{"indices":[],"values":[]}}`.
## Sintaxe
```
HLL_SKETCH_AGG (aggregate_expression[, lgConfigK ] )
```
## Argumento
*aggregate\$1expression*
Qualquer expressão do tipo INT, BIGINT, STRING ou BINARY em relação à qual ocorrerá uma contagem exclusiva. Todos `NULL` os valores são ignorados.
*LG ConfigK*
Uma constante INT opcional entre 4 e 21, inclusive com o padrão 12. A base logarítmica 2 de K, onde K é o número de compartimentos ou slots para o esboço.
## Tipo de retorno
A função HLL\$1SKETCH\$1AGG retorna um buffer BINÁRIO não NULL contendo o HyperLogLog esboço calculado devido ao consumo e agregação de todos os valores de entrada no grupo de agregação.
## Exemplos
Os exemplos a seguir usam o algoritmo HyperLogLog (HLL) para estimar a contagem distinta de valores na `col` coluna. A `hll_sketch_agg(col, 12)` função agrega os valores na coluna col, criando um esboço HLL usando uma precisão de 12. A `hll_sketch_estimate()` função é então usada para estimar a contagem distinta de valores com base no esboço HLL gerado. O resultado final da consulta é 3, que representa a contagem distinta estimada de valores na `col` coluna. Nesse caso, os valores distintos são 1, 2 e 3.
```
SELECT hll_sketch_estimate(hll_sketch_agg(col, 12))
FROM VALUES (1), (1), (2), (2), (3) tab(col);
3
```
O exemplo a seguir também usa o algoritmo HLL para estimar a contagem distinta de valores na `col` coluna, mas não especifica um valor de precisão para o esboço do HLL. Nesse caso, ele usa a precisão padrão de 14. A `hll_sketch_agg(col)` função pega os valores na `col` coluna e cria um esboço HyperLogLog (HLL), que é uma estrutura de dados compacta que pode ser usada para estimar a contagem distinta de elementos. A `hll_sketch_estimate(hll_sketch_agg(col))` função pega o esboço HLL criado na etapa anterior e calcula uma estimativa da contagem distinta de valores na coluna. `col` O resultado final da consulta é 3, que representa a contagem distinta estimada de valores na `col` coluna. Nesse caso, os valores distintos são 1, 2 e 3.
```
SELECT hll_sketch_estimate(hll_sketch_agg(col))
FROM VALUES (1), (1), (2), (2), (3) tab(col);
3
```
# função HLL\$1SKETCH\$1ESTIMATE
A função HLL\$1SKETCH\$1ESTIMATE usa um esboço HLL e estima o número de elementos exclusivos representados pelo esboço. Ele usa o algoritmo HyperLogLog (HLL) para contar uma aproximação probabilística do número de valores exclusivos em uma determinada coluna, consumindo uma representação binária conhecida como buffer de esboço gerada anteriormente pela função HLL\$1SKETCH\$1AGG e retornando o resultado como um número inteiro grande.
O algoritmo de esboço HLL fornece uma maneira eficiente de estimar o número de elementos exclusivos, mesmo para grandes conjuntos de dados, sem precisar armazenar o conjunto completo de valores exclusivos.
As `hll_union_agg` funções `hll_union` e também podem combinar esboços consumindo e mesclando esses buffers como entradas.
## Sintaxe
```
HLL_SKETCH_ESTIMATE (hllsketch_expression)
```
## Argumento
*hllsketch\$1expression*
Uma `BINARY` expressão contendo um esboço gerado por HLL\$1SKETCH\$1AGG
## Tipo de retorno
A função HLL\$1SKETCH\$1ESTIMATE retorna um valor BIGINT que é a contagem distinta aproximada representada pelo esboço de entrada.
## Exemplos
Os exemplos a seguir usam o algoritmo de esboço HyperLogLog (HLL) para estimar a cardinalidade (contagem exclusiva) dos valores na coluna. `col` A `hll_sketch_agg(col, 12)` função pega a `col` coluna e cria um esboço HLL usando uma precisão de 12 bits. O esboço do HLL é uma estrutura de dados aproximada que pode estimar com eficiência o número de elementos exclusivos em um conjunto. A `hll_sketch_estimate()` função pega o esboço HLL criado por `hll_sketch_agg` e estima a cardinalidade (contagem única) dos valores representados pelo esboço. O `FROM VALUES (1), (1), (2), (2), (3) tab(col);` gera um conjunto de dados de teste com 5 linhas, em que a `col` coluna contém os valores 1, 1, 2, 2 e 3. O resultado dessa consulta é a contagem exclusiva estimada dos valores na `col` coluna, que é 3.
```
SELECT hll_sketch_estimate(hll_sketch_agg(col, 12))
FROM VALUES (1), (1), (2), (2), (3) tab(col);
3
```
A diferença entre o exemplo a seguir e o anterior é que o parâmetro de precisão (12 bits) não está especificado na chamada da `hll_sketch_agg` função. Nesse caso, a precisão padrão de 14 bits é usada, o que pode fornecer uma estimativa mais precisa para a contagem exclusiva em comparação com o exemplo anterior que usou 12 bits de precisão.
```
SELECT hll_sketch_estimate(hll_sketch_agg(col))
FROM VALUES (1), (1), (2), (2), (3) tab(col);
3
```
# função HLL\$1UNION
A função HLL\$1UNION combina dois esboços HLL em um único esboço unificado. Ele usa o algoritmo HyperLogLog (HLL) para combinar dois esboços em um único esboço. As consultas podem usar os buffers resultantes para calcular contagens exclusivas aproximadas como números inteiros longos com a função. `hll_sketch_estimate`
## Sintaxe
```
HLL_UNION (( expr1, expr2 [, allowDifferentLgConfigK ] ))
```
## Argumento
*Exprn*
Uma `BINARY` expressão contendo um esboço gerado por HLL\$1SKETCH\$1AGG.
*allowDifferentLgConfigK*
Uma expressão BOOLEAN opcional que controla se é permitido mesclar dois esboços com valores LGConfigK diferentes. O valor padrão é `false`.
## Tipo de retorno
A função HLL\$1UNION retorna um buffer BINARY contendo o HyperLogLog esboço calculado como resultado da combinação das expressões de entrada. Quando o `allowDifferentLgConfigK` parâmetro é`true`, o esboço resultante usa o menor dos dois `lgConfigK` valores fornecidos.
## Exemplos
Os exemplos a seguir usam o algoritmo de esboço HyperLogLog (HLL) para estimar a contagem exclusiva de valores em duas colunas `col1` e em um `col2` conjunto de dados.
A `hll_sketch_agg(col1)` função cria um esboço HLL para os valores exclusivos na `col1` coluna.
A `hll_sketch_agg(col2)` função cria um esboço HLL para os valores exclusivos na coluna col2.
A `hll_union(...)` função combina os dois esboços de HLL criados nas etapas 1 e 2 em um único esboço de HLL unificado.
A `hll_sketch_estimate(...)` função pega o esboço combinado do HLL e estima a contagem exclusiva de valores em ambos e. `col1` `col2`
A `FROM VALUES` cláusula gera um conjunto de dados de teste com 5 linhas, onde `col1` contém os valores 1, 1, 2, 2 e 3 e `col2` contém os valores 4, 4, 5, 5 e 6.
O resultado dessa consulta é a contagem exclusiva estimada de valores em ambos `col1` e`col2`, que é 6. O algoritmo de esboço HLL fornece uma maneira eficiente de estimar o número de elementos exclusivos, mesmo para grandes conjuntos de dados, sem precisar armazenar o conjunto completo de valores exclusivos. Neste exemplo, a `hll_union` função é usada para combinar os esboços do HLL das duas colunas, o que permite que a contagem exclusiva seja estimada em todo o conjunto de dados, em vez de apenas para cada coluna individualmente.
```
SELECT hll_sketch_estimate(
hll_union(
hll_sketch_agg(col1),
hll_sketch_agg(col2)))
FROM VALUES
(1, 4),
(1, 4),
(2, 5),
(2, 5),
(3, 6) AS tab(col1, col2);
6
```
A diferença entre o exemplo a seguir e o anterior é que o parâmetro de precisão (12 bits) não está especificado na chamada da `hll_sketch_agg` função. Nesse caso, a precisão padrão de 14 bits é usada, o que pode fornecer uma estimativa mais precisa para a contagem exclusiva em comparação com o exemplo anterior que usou 12 bits de precisão.
```
SELECT hll_sketch_estimate(
hll_union(
hll_sketch_agg(col1, 14),
hll_sketch_agg(col2, 14)))
FROM VALUES
(1, 4),
(1, 4),
(2, 5),
(2, 5),
(3, 6) AS tab(col1, col2);
```
# função HLL\$1UNION\$1AGG
A função HLL\$1UNION\$1AGG combina vários esboços HLL em um único esboço unificado. Ele usa o algoritmo HyperLogLog (HLL) para combinar um grupo de esboços em um único. As consultas podem usar os buffers resultantes para calcular contagens exclusivas aproximadas com a função. `hll_sketch_estimate`
## Sintaxe
```
HLL_UNION_AGG ( expr [, allowDifferentLgConfigK ] )
```
## Argumento
*expr*
Uma `BINARY` expressão contendo um esboço gerado por HLL\$1SKETCH\$1AGG.
*allowDifferentLgConfigK*
Uma expressão BOOLEAN opcional que controla se é permitido mesclar dois esboços com valores LGConfigK diferentes. O valor padrão é `false`.
## Tipo de retorno
A função HLL\$1UNION\$1AGG retorna um buffer BINARY contendo o HyperLogLog esboço calculado como resultado da combinação das expressões de entrada do mesmo grupo. Quando o `allowDifferentLgConfigK` parâmetro é`true`, o esboço resultante usa o menor dos dois `lgConfigK` valores fornecidos.
## Exemplos
Os exemplos a seguir usam o algoritmo de esboço HyperLogLog (HLL) para estimar a contagem exclusiva de valores em vários esboços de HLL.
O primeiro exemplo estima a contagem exclusiva de valores em um conjunto de dados.
```
SELECT hll_sketch_estimate(hll_union_agg(sketch, true))
FROM (SELECT hll_sketch_agg(col) as sketch
FROM VALUES (1) AS tab(col)
UNION ALL
SELECT hll_sketch_agg(col, 20) as sketch
FROM VALUES (1) AS tab(col));
1
```
A consulta interna cria dois esboços de HLL:
+ A primeira instrução SELECT cria um esboço a partir de um único valor de 1.
+ A segunda instrução SELECT cria um esboço a partir de outro valor único de 1, mas com uma precisão de 20.
A consulta externa usa a função HLL\$1UNION\$1AGG para combinar os dois esboços em um único esboço. Em seguida, ele aplica a função HLL\$1SKETCH\$1ESTIMATE a esse esboço combinado para estimar a contagem exclusiva de valores.
O resultado dessa consulta é a contagem exclusiva estimada dos valores na `col` coluna, que é`1`. Isso significa que os dois valores de entrada de 1 são considerados exclusivos, mesmo que tenham o mesmo valor.
O segundo exemplo inclui um parâmetro de precisão diferente para a função HLL\$1UNION\$1AGG. Nesse caso, os dois esboços do HLL são criados com uma precisão de 14 bits, o que permite que sejam combinados com sucesso usando o `hll_union_agg` `true` parâmetro.
```
SELECT hll_sketch_estimate(hll_union_agg(sketch, true))
FROM (SELECT hll_sketch_agg(col, 14) as sketch
FROM VALUES (1) AS tab(col)
UNION ALL
SELECT hll_sketch_agg(col, 14) as sketch
FROM VALUES (1) AS tab(col));
1
```
O resultado final da consulta é a contagem exclusiva estimada, que nesse caso também é`1`. Isso significa que os dois valores de entrada de 1 são considerados exclusivos, mesmo que tenham o mesmo valor.
# Funções JSON
Quando você precisa armazenar um conjunto relativamente pequeno de pares de valores de chave, você pode economizar espaço armazenando os dados em formato JSON. Como strings JSON podem ser armazenados em uma única coluna, o uso de JSON pode ser mais eficiente que armazenar seus dados em formato tabular.
**Example**
Por exemplo, suponha que você tenha uma tabela esparsa, onde você precisa ter muitas colunas para representar totalmente todos os atributos possíveis. No entanto, a maioria dos valores da coluna é NULL para qualquer linha ou coluna. Ao usar JSON para armazenamento, você poderá armazenar os dados de uma linha em pares de valores-chave em uma única string JSON e eliminar as colunas da tabela pouco preenchidas.
Além disso, você pode facilmente modificar strings JSON para armazenar pares de valor:chave sem a necessidade de adicionar colunas à uma tabela.
Recomendamos usar JSON frugalmente. JSON não é uma boa opção para armazenar conjuntos de dados maiores porque, ao armazenar dados díspares em uma única coluna, o JSON não usa a arquitetura de armazenamento de colunas do AWS Clean Rooms .
JSON usa strings de texto codificadas por UTF-8, portanto strings JSON podem ser armazenadas como tipos de dados CHAR ou VARCHAR. Use VARCHAR se as strings incluírem caracteres multibyte.
As strings JSON devem ser adequadamente formatadas como JSON de acordo com as seguintes regras:
+ O nível JSON raiz pode ser um objeto JSON ou uma matriz JSON. Um objeto JSON é um conjunto desordenado de pares de valor:chave separados por vírgula cercado por chaves.
Por exemplo, `{"one":1, "two":2} `.
+ Uma matriz JSON é um conjunto ordenado de valores separados por vírgula cercado por parênteses.
Um exemplo é o seguinte: `["first", {"one":1}, "second", 3, null] `
+ Matrizes JSON usam um índice baseado em zero; o primeiro elemento em uma matriz fica na posição 0. Em um par de valores-chave JSON, a chave é uma string entre aspas duplas.
+ Um valor JSON pode ser qualquer um dos seguintes:
+ Objeto JSON
+ matriz JSON
+ String entre aspas duplas
+ Número (inteiro e flutuante)
+ Booleano
+ Null
+ Objetos vazios e matrizes vazias são valores JSON válidos.
+ Os campos JSON diferenciam maiúsculas e minúsculas.
+ O espaço em branco entre elementos estruturais JSON (tal como `{ }, [ ]`) é ignorado.
**Topics**
+ [função GET\$1JSON\$1OBJECT](GET_JSON_OBJECT.md)
+ [função TO\$1JSON](TO_JSON.md)
# função GET\$1JSON\$1OBJECT
A função GET\$1JSON\$1OBJECT extrai um objeto json de. `path`
## Sintaxe
```
get_json_object(json_txt, path)
```
## Argumentos
*json\$1txt*
Uma expressão STRING contendo JSON bem formado.
*path*
Um literal STRING com uma expressão de caminho JSON bem formada.
## Retornos
Retorna uma STRING.
Um NULL é retornado se o objeto não puder ser encontrado.
## Exemplo
O exemplo a seguir extrai um valor de um objeto JSON. O primeiro argumento é uma string JSON que representa um objeto simples com um único par de valores-chave. O segundo argumento é uma expressão de caminho JSON. O `$` símbolo representa a raiz do objeto JSON e a `.a` parte especifica que queremos extrair o valor associado à chave `a` "”. A saída da função é '`b`', que é o valor associado à chave "`a`" no objeto JSON de entrada.
```
SELECT get_json_object('{"a":"b"}', '$.a');
b
```
# função TO\$1JSON
A função TO\$1JSON converte uma expressão de entrada em uma representação de string JSON. A função manipula a conversão de diferentes tipos de dados (como números, cadeias de caracteres e booleanos) em suas representações JSON correspondentes.
A função TO\$1JSON é útil quando você precisa converter dados estruturados (como linhas de banco de dados ou objetos JSON) em um formato mais portátil e autodescritivo, como JSON. Isso pode ser particularmente útil quando você precisa interagir com outros sistemas ou serviços que esperam dados formatados em JSON.
## Sintaxe
```
to_json(expr[, options])
```
## Argumentos
*expr*
A expressão de entrada que você deseja converter em uma string JSON. Pode ser um valor, uma coluna ou qualquer outra expressão SQL válida.
*options*
Um conjunto opcional de opções de configuração que pode ser usado para personalizar o processo de conversão de JSON. Essas opções podem incluir coisas como o tratamento de valores nulos, a representação de valores numéricos e o tratamento de caracteres especiais.
## Retornos
Retorna uma string JSON com um determinado valor de estrutura
## Exemplos
O exemplo a seguir converte uma estrutura nomeada (um tipo de dados estruturados) em uma string JSON. O primeiro argumento `(named_struct('a', 1, 'b', 2)` () é a expressão de entrada que é passada para a `to_json()` função. Ele cria uma estrutura nomeada com dois campos: “a” com um valor de 1 e “b” com um valor de 2. A função to\$1json () usa a estrutura nomeada como argumento e a converte em uma representação de string JSON. A saída é`{"a":1,"b":2}`, que é uma string JSON válida que representa a estrutura nomeada.
```
SELECT to_json(named_struct('a', 1, 'b', 2));
{"a":1,"b":2}
```
O exemplo a seguir converte uma estrutura nomeada que contém um valor de timestamp em uma string JSON, com um formato de timestamp personalizado. O primeiro argumento (`named_struct('time', to_timestamp('2015-08-26', 'yyyy-MM-dd'))`) cria uma estrutura nomeada com um único campo 'time' que contém o valor do timestamp. O segundo argumento (`map('timestampFormat', 'dd/MM/yyyy')`) cria um mapa (dicionário de valores-chave) com um único par de valores-chave, em que a chave é 'timestampFormat' e o valor é ''. dd/MM/yyyy'. This map is used to specify the desired format for the timestamp value when converting it to JSON. The to\$1json() function converts the named struct into a JSON string. The second argument, the map, is used to customize the timestamp format to 'dd/MM/yyyy A saída é`{"time":"26/08/2015"}`, que é uma string JSON com um único campo 'time' que contém o valor do timestamp no formato '' desejado. dd/MM/yyyy
```
SELECT to_json(named_struct('time', to_timestamp('2015-08-26', 'yyyy-MM-dd')), map('timestampFormat', 'dd/MM/yyyy'));
{"time":"26/08/2015"}
```
# Funções matemáticas
Esta seção descreve os operadores e funções matemáticas compatíveis com o AWS Clean Rooms Spark SQL.
**Topics**
+ [Símbolos de operadores matemáticos](OPERATOR_SYMBOLS.md)
+ [Função ABS](ABS.md)
+ [Função ACOS](ACOS.md)
+ [Função ASIN](ASIN.md)
+ [Função ATAN](ATAN.md)
+ [ATAN2 função](ATAN2.md)
+ [Função CBRT](CBRT.md)
+ [Função CEILING (ou CEIL)](CEILING_FLOOR.md)
+ [Função COS](COS.md)
+ [Função COT](COT.md)
+ [Função DEGREES](DEGREES.md)
+ [Função DIV](DIV.md)
+ [Função EXP](EXP.md)
+ [Função FLOOR](FLOOR.md)
+ [Função LN](LN.md)
+ [Função LOG](LOG.md)
+ [Função MOD](MOD.md)
+ [Função PI](PI.md)
+ [Função POWER](POWER.md)
+ [Função RADIANS](RADIANS.md)
+ [Função RAND](RAND.md)
+ [Função RANDOM](RANDOM.md)
+ [Função ROUND](ROUND.md)
+ [Função SIGN](SIGN.md)
+ [Função SIN](SIN.md)
+ [Função SQRT](SQRT.md)
+ [Função TRUNC](TRUNC.md)
# Símbolos de operadores matemáticos
A tabela a seguir lista os operadores matemáticos compatíveis.
## Operadores compatíveis
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/clean-rooms/latest/sql-reference/OPERATOR_SYMBOLS.html)
## Exemplos
Calcule a comissão paga mais uma taxa de manuseio de US\$1 2,00 para uma determinada transação:
```
select commission, (commission + 2.00) as comm
from sales where salesid=10000;
commission | comm
-----------+-------
28.05 | 30.05
(1 row)
```
Calcule 20 por cento do preço de venda para determinada transação:
```
select pricepaid, (pricepaid * .20) as twentypct
from sales where salesid=10000;
pricepaid | twentypct
----------+-----------
187.00 | 37.400
(1 row)
```
Faça a previsão das vendas de ingressos com base em um padrão de crescimento contínuo. Neste exemplo, a subconsulta retorna o número de ingressos vendidos em 2008. Esse resultado é multiplicado exponencialmente por uma taxa de crescimento contínuo de 5% ao longo de 10 anos.
```
select (select sum(qtysold) from sales, date
where sales.dateid=date.dateid and year=2008)
^ ((5::float/100)*10) as qty10years;
qty10years
------------------
587.664019657491
(1 row)
```
Encontre o preço total pago e a comissão pelas vendas com ID de data maior ou igual a 2.000. Então, subtraia a comissão total do preço total pago.
```
select sum (pricepaid) as sum_price, dateid,
sum (commission) as sum_comm, (sum (pricepaid) - sum (commission)) as value
from sales where dateid >= 2000
group by dateid order by dateid limit 10;
sum_price | dateid | sum_comm | value
-----------+--------+----------+-----------
364445.00 | 2044 | 54666.75 | 309778.25
349344.00 | 2112 | 52401.60 | 296942.40
343756.00 | 2124 | 51563.40 | 292192.60
378595.00 | 2116 | 56789.25 | 321805.75
328725.00 | 2080 | 49308.75 | 279416.25
349554.00 | 2028 | 52433.10 | 297120.90
249207.00 | 2164 | 37381.05 | 211825.95
285202.00 | 2064 | 42780.30 | 242421.70
320945.00 | 2012 | 48141.75 | 272803.25
321096.00 | 2016 | 48164.40 | 272931.60
(10 rows)
```
# Função ABS
ABS calcula o valor absoluto de um número, que pode ser um literal ou uma expressão que avalie para um número.
## Sintaxe
```
ABS (number)
```
## Argumentos
*número*
Número ou expressão que avalia para um número. Pode ser do tipo SMALLINT, INTEGER, BIGINT, DECIMAL ou. FLOAT4 FLOAT8
## Tipo de retorno
ABS retorna o mesmo tipo de dados que seu argumento.
## Exemplos
Calcule o valor absoluto de -38:
```
select abs (-38);
abs
-------
38
(1 row)
```
Calcule o valor absoluto de (14-76):
```
select abs (14-76);
abs
-------
62
(1 row)
```
# Função ACOS
ACOS é uma função trigonométrica que retorna o arco cosseno de um número. O valor de retorno é em radianos, entre `0` e `PI`.
## Sintaxe
```
ACOS(number)
```
## Argumentos
*número*
O parâmetro de entrada é um número `DOUBLE PRECISION`.
## Tipo de retorno
`DOUBLE PRECISION`
## Exemplos
Para retornar o arco cosseno de `-1`, use o exemplo a seguir.
```
SELECT ACOS(-1);
+-------------------+
| acos |
+-------------------+
| 3.141592653589793 |
+-------------------+
```
# Função ASIN
ASIN é uma função trigonométrica que retorna o arco seno de um número. O valor de retorno é em radianos, entre `PI/2` e `-PI/2`.
## Sintaxe
```
ASIN(number)
```
## Argumentos
*número*
O parâmetro de entrada é um número `DOUBLE PRECISION`.
## Tipo de retorno
`DOUBLE PRECISION`
## Exemplos
Para retornar o arco seno de `1`, use o exemplo a seguir.
```
SELECT ASIN(1) AS halfpi;
+--------------------+
| halfpi |
+--------------------+
| 1.5707963267948966 |
+--------------------+
```
# Função ATAN
ATAN é uma função trigonométrica que retorna a arco tangente de um número. O valor de retorno é em radianos, entre `-PI` e `PI`.
## Sintaxe
```
ATAN(number)
```
## Argumentos
*número*
O parâmetro de entrada é um número `DOUBLE PRECISION`.
## Tipo de retorno
`DOUBLE PRECISION`
## Exemplos
Para retornar a arco tangente de `1` e a multiplica por 4, use o exemplo a seguir.
```
SELECT ATAN(1) * 4 AS pi;
+-------------------+
| pi |
+-------------------+
| 3.141592653589793 |
+-------------------+
```
# ATAN2 função
ATAN2 é uma função trigonométrica que retorna o arco tangente de um número dividido por outro número. O valor de retorno é em radianos, entre `PI/2` e `-PI/2`.
## Sintaxe
```
ATAN2(number1, number2)
```
## Argumentos
*number1*
Um número `DOUBLE PRECISION`.
*number2*
Um número `DOUBLE PRECISION`.
## Tipo de retorno
`DOUBLE PRECISION`
## Exemplos
Para retornar a arco tangente de `2/2` e a multiplica por 4, use o exemplo a seguir.
```
SELECT ATAN2(2,2) * 4 AS PI;
+-------------------+
| pi |
+-------------------+
| 3.141592653589793 |
+-------------------+
```
# Função CBRT
A função CBRT é uma função matemática que calcula a raiz cúbica de um número.
## Sintaxe
```
CBRT (number)
```
## Argumento
CBRT assume um número de DOUBLE PRECISION como um argumento.
## Tipo de retorno
CBRT retorna um número de DOUBLE PRECISION.
## Exemplos
Calcule a raiz cúbica da comissão paga para determinada transação:
```
select cbrt(commission) from sales where salesid=10000;
cbrt
------------------
3.03839539048843
(1 row)
```
# Função CEILING (ou CEIL)
A função CEILING ou CEIL é usada para arredondar um número para o número inteiro seguinte. (A função [Função FLOOR](FLOOR.md) arredonda um número para o número inteiro anterior.)
## Sintaxe
```
CEIL | CEILING(number)
```
## Argumentos
*número*
O número ou expressão avaliada como um número. Pode ser do tipo SMALLINT, INTEGER, BIGINT, DECIMAL ou. FLOAT4 FLOAT8
## Tipo de retorno
CEILING e CEIL retornam o mesmo tipo de dados que seu argumento.
## Exemplo
Calcule o teto da comissão paga para determinada transação de vendas:
```
select ceiling(commission) from sales
where salesid=10000;
ceiling
---------
29
(1 row)
```
# Função COS
COS é uma função trigonométrica que retorna o cosseno de um número. O valor de retorno é em radianos, entre `-1` e `1`, incluindo ambos.
## Sintaxe
```
COS(double_precision)
```
## Argumento
*número*
O parâmetro de entrada é um número de precisão dupla.
## Tipo de retorno
A função COS retorna um número de precisão dupla.
## Exemplos
O seguinte exemplo retorna o cosseno de 0:
```
select cos(0);
cos
-----
1
(1 row)
```
O seguinte exemplo retorna o cosseno de PI:
```
select cos(pi());
cos
-----
-1
(1 row)
```
# Função COT
COT é uma função trigonométrica que retorna a cotangente de um número. O parâmetro de entrada deve ser diferente de zero.
## Sintaxe
```
COT(number)
```
## Argumento
*número*
O parâmetro de entrada é um número `DOUBLE PRECISION`.
## Tipo de retorno
`DOUBLE PRECISION`
## Exemplos
Para retornar a cotangente de 1, use o exemplo a seguir.
```
SELECT COT(1);
+--------------------+
| cot |
+--------------------+
| 0.6420926159343306 |
+--------------------+
```
# Função DEGREES
Converte um ângulo em radianos para seu equivalente em graus.
## Sintaxe
```
DEGREES(number)
```
## Argumento
*número*
O parâmetro de entrada é um número `DOUBLE PRECISION`.
## Tipo de retorno
`DOUBLE PRECISION`
## Exemplo
Para retornar o grau equivalente de 0,5 radiano, use o exemplo a seguir.
```
SELECT DEGREES(.5);
+-------------------+
| degrees |
+-------------------+
| 28.64788975654116 |
+-------------------+
```
Para converter PI radianos em graus, use o exemplo a seguir.
```
SELECT DEGREES(pi());
+---------+
| degrees |
+---------+
| 180 |
+---------+
```
# Função DIV
O operador DIV retorna a parte integral da divisão do dividendo por divisor.
## Sintaxe
```
dividend div divisor
```
## Argumentos
*dividendo*
Uma expressão que é avaliada como numérica ou intervalo.
*divisor*
Um tipo de intervalo correspondente se `dividend` for um intervalo, caso contrário, um numérico.
## Tipo de retorno
`BIGINT`
## Exemplos
O exemplo a seguir seleciona duas colunas da tabela de esquilos: a `id` coluna, que contém o identificador exclusivo para cada esquilo, e uma `calculated` coluna,`age div 2`, que representa a divisão inteira da coluna de idade por 2. O `age div 2` cálculo realiza a divisão de números inteiros na `age` coluna, arredondando efetivamente a idade para o número inteiro par mais próximo. Por exemplo, se a `age` coluna contiver valores como 3, 5, 7 e 10, a `age div 2` coluna conterá os valores 1, 2, 3 e 5, respectivamente.
```
SELECT id, age div 2 FROM squirrels
```
Essa consulta pode ser útil em cenários em que você precisa agrupar ou analisar dados com base em faixas etárias e deseja simplificar os valores de idade arredondando-os para o número inteiro par mais próximo. O resultado resultante forneceria a idade `id` e a divisão por 2 para cada esquilo na `squirrels` tabela.
# Função EXP
A função EXP implementa a função exponencial de uma expressão numérica, ou a base de um logaritmo natural, `e`, elevada à potência da expressão. A função EXP é o inverso de [Função LN](LN.md).
## Sintaxe
```
EXP (expression)
```
## Argumento
*expressão*
A expressão deve ser um tipo de dados INTEGER, DECIMAL ou DOUBLE PRECISION.
## Tipo de retorno
EXP retorna um número de DOUBLE PRECISION.
## Exemplo
Use a função EXP para prever as vendas de ingressos com base em um padrão de crescimento contínuo. Neste exemplo, a subconsulta retorna o número de ingressos vendidos em 2008. Esse resultado é multiplicado pelo resultado da função EXP, que especifica uma taxa de crescimento contínuo de 7% por 10 anos.
```
select (select sum(qtysold) from sales, date
where sales.dateid=date.dateid
and year=2008) * exp((7::float/100)*10) qty2018;
qty2018
------------------
695447.483772222
(1 row)
```
# Função FLOOR
A função FLOOR arredonda um número para o número inteiro anterior.
## Sintaxe
```
FLOOR (number)
```
## Argumento
*número*
O número ou expressão avaliada como um número. Pode ser do tipo SMALLINT, INTEGER, BIGINT, DECIMAL ou. FLOAT4 FLOAT8
## Tipo de retorno
FLOOR retorna o mesmo tipo de dados que seu argumento.
## Exemplo
O exemplo mostra o valor da comissão paga por determinada transação de vendas antes e depois de usar a função FLOOR.
```
select commission from sales
where salesid=10000;
floor
-------
28.05
(1 row)
select floor(commission) from sales
where salesid=10000;
floor
-------
28
(1 row)
```
# Função LN
A função LN retorna o logaritmo natural do parâmetro de entrada.
## Sintaxe
```
LN(expression)
```
## Argumento
*expressão*
A coluna ou expressão de destino na qual a função opera.
Essa função retornará um erro para alguns tipos de dados se a expressão fizer referência a uma tabela AWS Clean Rooms criada pelo usuário ou a uma tabela do AWS Clean Rooms sistema STL ou STV.
As expressões com os seguintes tipos de dados produzem um erro se fizerem referência a uma tabela criada por usuário ou uma tabela de sistema.
+ BOOLEAN
+ CHAR
+ DATE
+ DECIMAL ou NUMERIC
+ TIMESTAMP
+ VARCHAR
Expressões com os seguintes tipos de dados executam com êxito em tabelas criadas por usuário ou tabelas de sistema STL ou STV:
+ BIGINT
+ DOUBLE PRECISION
+ INTEGER
+ REAL
+ SMALLINT
## Tipo de retorno
A função LN retorna o mesmo tipo que a expressão.
## Exemplo
O seguinte exemplo retorna o logaritmo natural, ou logaritmo de base e, do número 2,718281828:
```
select ln(2.718281828);
ln
--------------------
0.9999999998311267
(1 row)
```
Observe que a resposta é quase igual a 1.
Este exemplo retorna o logaritmo natural dos valores na coluna USERID da tabela USERS:
```
select username, ln(userid) from users order by userid limit 10;
username | ln
----------+-------------------
JSG99FHE | 0
PGL08LJI | 0.693147180559945
IFT66TXU | 1.09861228866811
XDZ38RDD | 1.38629436111989
AEB55QTM | 1.6094379124341
NDQ15VBM | 1.79175946922805
OWY35QYB | 1.94591014905531
AZG78YIP | 2.07944154167984
MSD36KVR | 2.19722457733622
WKW41AIW | 2.30258509299405
(10 rows)
```
# Função LOG
Retorna o logaritmo de `expr` com. `base`
## Sintaxe
```
LOG(base, expr)
```
## Argumento
*expr*
A expressão deve ter um tipo de dados de número inteiro, decimal ou ponto flutuante.
*base*
A base para o cálculo do logaritmo. Deve ser um número positivo (não igual a 1) do tipo de dados de precisão dupla.
## Tipo de retorno
A função LOG retorna um número de precisão dupla.
## Exemplo
O seguinte exemplo retorna o logaritmo de base 10 do número 100:
```
select log(10, 100);
--------
2
(1 row)
```
# Função MOD
Retorna o resto de dois números, também chamado de operação *modulo*. Para calcular o resultado, o primeiro parâmetro é dividido pelo segundo.
## Sintaxe
```
MOD(number1, number2)
```
## Argumentos
*number1*
O primeiro parâmetro de entrada é um número INTEGER, SMALLINT, BIGINT ou DECIMAL. Se um dos parâmetros for um tipo DECIMAL, os outros parâmetro também devem ser um tipo DECIMAL. Se um dos parâmetros for um INTEGER, os outros parâmetro podem ser INTEGER, SMALLINT ou BIGINT. Ambos os parâmetros também podem ser SMALLINT ou BIGINT, mas um parâmetro não pode ser SMALLINT se o outro for BIGINT.
*number2*
O segundo parâmetro é um número INTEGER, SMALLINT, BIGINT ou DECIMAL. As mesmas regras de tipo de dados são válidas para *number2* e *number1*.
## Tipo de retorno
Os tipos de retorno válidos são DECIMAL, INT, SMALLINT e BIGINT. O tipo de retorno da função MOD é o mesmo tipo numérico que os parâmetros de entrada se ambos os parâmetros de entrada forem do mesmo tipo. Se um dos parâmetro de entrada for INTEGER, porém, o tipo de retorno também será INTEGER.
## Observações de uso
Você pode usar *%* como um operador de modulo.
## Exemplos
O exemplo a seguir retorna o resto da divisão de um número por outro:
```
SELECT MOD(10, 4);
mod
------
2
```
O exemplo a seguir retorna um resultado decimal:
```
SELECT MOD(10.5, 4);
mod
------
2.5
```
Você pode converter valores de parâmetros:
```
SELECT MOD(CAST(16.4 as integer), 5);
mod
------
1
```
Verifique se o primeiro parâmetro é par dividindo-o por 2:
```
SELECT mod(5,2) = 0 as is_even;
is_even
--------
false
```
Você pode usar *%* como um operador de modulo:
```
SELECT 11 % 4 as remainder;
remainder
-----------
3
```
O seguinte exemplo retorna informações para as categorias com números ímpares da tabela CATEGORY:
```
select catid, catname
from category
where mod(catid,2)=1
order by 1,2;
catid | catname
-------+-----------
1 | MLB
3 | NFL
5 | MLS
7 | Plays
9 | Pop
11 | Classical
(6 rows)
```
# Função PI
A função PI retorna o valor de pi para 14 casas decimais.
## Sintaxe
```
PI()
```
## Tipo de retorno
`DOUBLE PRECISION`
## Exemplos
Para retornar o valor de pi, use o exemplo a seguir.
```
SELECT PI();
+-------------------+
| pi |
+-------------------+
| 3.141592653589793 |
+-------------------+
```
# Função POWER
A função POWER é uma função exponencial que eleva uma expressão numérica para a potência de uma segunda expressão numérica. Por exemplo, 2 elevado à terceira potência é calculado como `POWER(2,3)`, com um resultado de `8`.
## Sintaxe
```
{POWER(expression1, expression2)
```
## Argumentos
*expression1*
Expressão numérica a ser elevada. Deve ser um tipo de dados `INTEGER`, `DECIMAL` ou `FLOAT`.
*expression2*
Potência a elevar a *expression1*. Deve ser um tipo de dados `INTEGER`, `DECIMAL` ou `FLOAT`.
## Tipo de retorno
`DOUBLE PRECISION`
## Exemplo
```
SELECT (SELECT SUM(qtysold) FROM sales, date
WHERE sales.dateid=date.dateid
AND year=2008) * POW((1+7::FLOAT/100),10) qty2010;
+-------------------+
| qty2010 |
+-------------------+
| 679353.7540885945 |
+-------------------+
```
# Função RADIANS
A função RADIANS converte um ângulo em graus em seu equivalente em radianos.
## Sintaxe
```
RADIANS(number)
```
## Argumento
*número*
O parâmetro de entrada é um número `DOUBLE PRECISION`.
## Tipo de retorno
`DOUBLE PRECISION`
## Exemplo
Para retornar o radiano equivalente de 180 graus, use o exemplo a seguir.
```
SELECT RADIANS(180);
+-------------------+
| radians |
+-------------------+
| 3.141592653589793 |
+-------------------+
```
# Função RAND
A função RAND gera um número aleatório de ponto flutuante entre 0 e 1. A função RAND gera um novo número aleatório cada vez que é chamada.
## Sintaxe
```
RAND()
```
## Tipo de retorno
RANDOM retorna um DOUBLE.
## Exemplo
O exemplo a seguir gera uma coluna de números aleatórios de ponto flutuante entre 0 e 1 para cada linha na tabela. `squirrels` A saída resultante seria uma única coluna contendo uma lista de valores decimais aleatórios, com um valor para cada linha na tabela de esquilos.
```
SELECT rand() FROM squirrels
```
Esse tipo de consulta é útil quando você precisa gerar números aleatórios, por exemplo, para simular eventos aleatórios ou para introduzir aleatoriedade em sua análise de dados. No contexto da `squirrels` tabela, ela pode ser usada para atribuir valores aleatórios a cada esquilo, que podem então ser usados para processamento ou análise posterior.
# Função RANDOM
A função RANDOM gera um valor aleatório entre 0,0 (inclusive) e 1,0 (exclusivo).
## Sintaxe
```
RANDOM()
```
## Tipo de retorno
RANDOM retorna um número de DOUBLE PRECISION.
## Exemplos
1. Compute um valor aleatório entre 0 e 99. Se o número aleatório é de 0 a 1, essa consulta produz um número aleatório de 0 a 100:
```
select cast (random() * 100 as int);
INTEGER
------
24
(1 row)
```
1. Recupere uma amostra aleatória uniforme de 10 itens:
```
select *
from sales
order by random()
limit 10;
```
Agora recupere uma amostra aleatória de 10 itens, mas escolha os itens em proporção aos preços. Por exemplo, um item cujo preço é o dobro de outro tem duas vezes mais probabilidade de aparecer nos resultados de consulta:
```
select *
from sales
order by log(1 - random()) / pricepaid
limit 10;
```
1. Este exemplo usa o comando SET para definir um valor SEED para que RANDOM gere uma sequência previsível de números.
Primeiro, retorne três inteiros RANDOM sem definir o valor de SEED primeiro:
```
select cast (random() * 100 as int);
INTEGER
------
6
(1 row)
select cast (random() * 100 as int);
INTEGER
------
68
(1 row)
select cast (random() * 100 as int);
INTEGER
------
56
(1 row)
```
Agora, defina o valor de SEED como `.25` e retorne mais três números RANDOM:
```
set seed to .25;
select cast (random() * 100 as int);
INTEGER
------
21
(1 row)
select cast (random() * 100 as int);
INTEGER
------
79
(1 row)
select cast (random() * 100 as int);
INTEGER
------
12
(1 row)
```
Por fim, redefina o valor de SEED como `.25` e verifique se RANDOM retorna os mesmos resultados que as três chamadas anteriores:
```
set seed to .25;
select cast (random() * 100 as int);
INTEGER
------
21
(1 row)
select cast (random() * 100 as int);
INTEGER
------
79
(1 row)
select cast (random() * 100 as int);
INTEGER
------
12
(1 row)
```
# Função ROUND
A função ROUND arredonda números para o inteiro ou decimal mais próximo.
A função ROUND pode incluir opcionalmente um segundo argumento como um inteiro para indicar o número de casas decimais para arredondamento, em qualquer direção. Quando você não fornece o segundo argumento, a função arredonda para o número inteiro mais próximo. Quando o segundo argumento *>n* for especificado, a função arredonda para o número mais próximo com *n* casas decimais de precisão.
## Sintaxe
```
ROUND (number [ , integer ] )
```
## Argumento
*número*
Um número ou expressão avaliada como um número. Pode ser o DECIMAL ou o FLOAT8 tipo. AWS Clean Rooms pode converter outros tipos de dados de acordo com as regras de conversão implícitas.
*inteiro* (opcional)
Um número inteiro que indica o número de casas decimais para arredondamento em ambas as direções.
## Tipo de retorno
ROUND retorna o mesmo tipo de dados numéricos que o(s) argumento(s) de entrada.
## Exemplos
Arredonde a comissão paga para determinada transação para o número inteiro mais próximo.
```
select commission, round(commission)
from sales where salesid=10000;
commission | round
-----------+-------
28.05 | 28
(1 row)
```
Arredonde a comissão paga para determinada transação para a primeira casa decimal.
```
select commission, round(commission, 1)
from sales where salesid=10000;
commission | round
-----------+-------
28.05 | 28.1
(1 row)
```
Para a mesma consulta, estenda a precisão no sentido oposto.
```
select commission, round(commission, -1)
from sales where salesid=10000;
commission | round
-----------+-------
28.05 | 30
(1 row)
```
# Função SIGN
A função SIGN retorna o sinal (positivo ou negativo) de um número. O resultado da função SIGN é `1`, `-1` ou `0` indicando o sinal do argumento.
## Sintaxe
```
SIGN (number)
```
## Argumento
*número*
Número ou expressão que avalia para um número. Pode ser do DECIMALor FLOAT8 tipo. AWS Clean Rooms pode converter outros tipos de dados de acordo com as regras de conversão implícitas.
## Tipo de retorno
SIGN retorna o mesmo tipo de dados numéricos que os argumentos de entrada. Se a entrada for DECIMAL, a saída será DECIMAL(1,0).
## Exemplos
Para determinar o sinal da comissão paga por determinada transação na tabela SALES, use o exemplo a seguir.
```
SELECT commission, SIGN(commission)
FROM sales WHERE salesid=10000;
+------------+------+
| commission | sign |
+------------+------+
| 28.05 | 1 |
+------------+------+
```
# Função SIN
SIN é uma função trigonométrica que retorna o seno de um número. O valor de retorno está entre `-1` e `1`.
## Sintaxe
```
SIN(number)
```
## Argumento
*número*
Um número `DOUBLE PRECISION` em radianos.
## Tipo de retorno
`DOUBLE PRECISION`
## Exemplo
Para retornar o seno de `-PI`, use o exemplo a seguir.
```
SELECT SIN(-PI());
+-------------------------+
| sin |
+-------------------------+
| -0.00000000000000012246 |
+-------------------------+
```
# Função SQRT
A função SQRT retorna a raiz quadrada de um valor numérico. A raiz quadrada é um número multiplicado por si mesmo para obter o valor fornecido.
## Sintaxe
```
SQRT (expression)
```
## Argumento
*expressão*
A expressão deve ter um tipo de dados de número inteiro, decimal ou ponto flutuante. A expressão pode incluir funções. O sistema pode realizar conversões de tipo implícitas.
## Tipo de retorno
SQRT retorna um número de DOUBLE PRECISION.
## Exemplos
O exemplo a seguir retorna a raiz quadrada de um número.
```
select sqrt(16);
sqrt
---------------
4
```
O exemplo a seguir realiza uma conversão de tipo implícita.
```
select sqrt('16');
sqrt
---------------
4
```
O exemplo a seguir aninha funções para realizar uma tarefa mais complexa.
```
select sqrt(round(16.4));
sqrt
---------------
4
```
O exemplo a seguir resulta no comprimento do raio quando dada a área de um círculo. Ele calcula o raio em polegadas, por exemplo, quando dada a área em polegadas quadradas. A área na amostra é 20.
```
select sqrt(20/pi());
```
Isso retorna o valor 5.046265044040321.
O seguinte exemplo retorna a raiz quadrada para valores de COMMISSION da tabela SALES. A coluna COMMISSION é uma coluna DECIMAL. Este exemplo mostra como você pode usar a função em uma consulta com uma lógica condicional mais complexa.
```
select sqrt(commission)
from sales where salesid < 10 order by salesid;
sqrt
------------------
10.4498803820905
3.37638860322683
7.24568837309472
5.1234753829798
...
```
A seguinte consulta retorna raiz quadrada arredondada para o mesmo conjunto de valores de COMMISSION.
```
select salesid, commission, round(sqrt(commission))
from sales where salesid < 10 order by salesid;
salesid | commission | round
--------+------------+-------
1 | 109.20 | 10
2 | 11.40 | 3
3 | 52.50 | 7
4 | 26.25 | 5
...
```
Para obter mais informações sobre dados de amostra em AWS Clean Rooms, consulte Banco de [dados de amostra](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html).
# Função TRUNC
A função TRUNC trunca números para o inteiro ou decimal anterior.
A função TRUNC pode incluir opcionalmente um segundo argumento como um inteiro para indicar o número de casas decimais para arredondamento, em qualquer direção. Quando você não fornece o segundo argumento, a função arredonda para o número inteiro mais próximo. Quando o segundo argumento *>n* for especificado, a função arredonda para o número mais próximo com *>n* casas decimais de precisão. Esta função também trunca um timestamp e retorna uma data.
## Sintaxe
```
TRUNC (number [ , integer ] |
timestamp )
```
## Argumentos
*número*
Um número ou expressão avaliada como um número. Pode ser o DECIMAL ou o FLOAT8 tipo. AWS Clean Rooms pode converter outros tipos de dados de acordo com as regras de conversão implícitas.
*inteiro* (opcional)
Um inteiro que indica o número de casas decimais de precisão, em um dos sentidos. Se nenhum inteiro for fornecido, o número será truncado como um número inteiro; se um inteiro for especificado, o número será truncado para a casa decimal especificada.
*timestamp*
A função também pode retornar a data de um timestamp. (Para retornar um valor de timestamp com `00:00:00` como a hora, converta o resultado da função para um timestamp.)
## Tipo de retorno
TRUNC retorna o mesmo tipo de dados que o primeiro argumento de entrada. Para timestamps, TRUNC retorna uma data.
## Exemplos
Trunque a comissão paga para determinada transação de vendas.
```
select commission, trunc(commission)
from sales where salesid=784;
commission | trunc
-----------+-------
111.15 | 111
(1 row)
```
Trunque o mesmo valor de comissão para a primeira casa decimal.
```
select commission, trunc(commission,1)
from sales where salesid=784;
commission | trunc
-----------+-------
111.15 | 111.1
(1 row)
```
Trunque a comissão com um valor negativo para o segundo argumento; `111.15` é arredondado para `110`.
```
select commission, trunc(commission,-1)
from sales where salesid=784;
commission | trunc
-----------+-------
111.15 | 110
(1 row)
```
Retorna a porção de data do resultado da função SYSDATE (que retorna um timestamp):
```
select sysdate;
timestamp
----------------------------
2011-07-21 10:32:38.248109
(1 row)
select trunc(sysdate);
trunc
------------
2011-07-21
(1 row)
```
Aplique a função TRUNC à uma coluna TIMESTAMP. O tipo de retorno é uma data.
```
select trunc(starttime) from event
order by eventid limit 1;
trunc
------------
2008-01-25
(1 row)
```
# Funções escalares
Esta seção descreve as funções escalares suportadas no AWS Clean Rooms Spark SQL. Uma função escalar é uma função que usa um ou mais valores como entrada e retorna um único valor como saída. As funções escalares operam em linhas ou elementos individuais e produzem um único resultado para cada entrada.
As funções escalares, como SIZE, são diferentes de outros tipos de funções SQL, como funções agregadas (contagem, soma, média) e funções geradoras de tabela (explodir, nivelar). Esses outros tipos de função operam em várias linhas ou geram várias linhas, enquanto as funções escalares funcionam em linhas ou elementos individuais.
**Topics**
+ [Função SIZE](size.md)
# Função SIZE
A função SIZE usa uma matriz, mapa ou string existente como argumento e retorna um único valor representando o tamanho ou o comprimento dessa estrutura de dados. Isso não cria uma nova estrutura de dados. Ele é usado para consultar e analisar as propriedades das estruturas de dados existentes, em vez de criar novas.
Essa função é útil para determinar o número de elementos em uma matriz ou o comprimento de uma string. Isso pode ser particularmente útil ao trabalhar com matrizes e outras estruturas de dados em SQL, pois permite obter informações sobre o tamanho ou a cardinalidade dos dados.
## Sintaxe
```
size(expr)
```
## Argumentos
*expr*
Uma expressão ARRAY, MAP ou STRING.
## Tipo de retorno
A função SIZE retorna um INTEIRO.
## Exemplo
Neste exemplo, a função SIZE é aplicada à matriz `['b', 'd', 'c', 'a']` e retorna o valor`4`, que é o número de elementos na matriz.
```
SELECT size(array('b', 'd', 'c', 'a'));
4
```
Neste exemplo, a função SIZE é aplicada ao mapa `{'a': 1, 'b': 2}` e retorna o valor`2`, que é o número de pares de valores-chave no mapa.
```
SELECT size(map('a', 1, 'b', 2));
2
```
Neste exemplo, a função SIZE é aplicada à string `'hello world'` e retorna o valor`11`, que é o número de caracteres na string.
```
SELECT size('hello world');
11
```
# Funções de string
Funções de string processam e manipulam strings de caracteres ou expressões que avaliam para strings de caracteres. Quando o argumento *string* nessas funções é um valor literal, ele deve ser envolvido por aspas simples. Os tipos de dados compatíveis incluem CHAR e VARCHAR.
A próxima seção fornece os nomes de função, sintaxe e descrições para as funções compatíveis. Todos os deslocamentos em strings são baseados em um.
**Topics**
+ [Operador \$1\$1 (Concatenação)](concat_op.md)
+ [Função BTRIM](BTRIM.md)
+ [Função CONCAT](CONCAT.md)
+ [função FORMAT\$1STRING](FORMAT_STRING.md)
+ [Funções LEFT e RIGHT](LEFT.md)
+ [Função LENGTH](LENGTH.md)
+ [Função LOWER](LOWER.md)
+ [Funções LPAD e RPAD](LPAD.md)
+ [Função LTRIM](LTRIM.md)
+ [Função POSITION](POSITION.md)
+ [Função REGEXP\$1COUNT](REGEXP_COUNT.md)
+ [Função REGEXP\$1INSTR](REGEXP_INSTR.md)
+ [Função REGEXP\$1REPLACE](REGEXP_REPLACE.md)
+ [Função REGEXP\$1SUBSTR](REGEXP_SUBSTR.md)
+ [Função REPEAT](REPEAT.md)
+ [Função REPLACE](REPLACE.md)
+ [Função REVERSE](REVERSE.md)
+ [Função RTRIM](RTRIM.md)
+ [Função SPLIT](split.md)
+ [Função SPLIT\$1PART](SPLIT_PART.md)
+ [Função SUBSTRING](SUBSTRING.md)
+ [Função TRANSLATE](TRANSLATE.md)
+ [Função TRIM](TRIM.md)
+ [Função UPPER](UPPER.md)
+ [Função UUID](UUID.md)
# Operador \$1\$1 (Concatenação)
Concatena duas expressões em ambos os lados do símbolo \$1\$1 e retorna a expressão concatenada.
O operador de concatenação é semelhante a [Função CONCAT](CONCAT.md).
**nota**
Tanto para a função CONCAT como para o operador de concatenação, se uma ou ambas as expressões forem nulas, o resultado da concatenação será null.
## Sintaxe
```
expression1 || expression2
```
## Argumentos
*expression1*, *expression2*
Ambos os argumentos podem ser strings de caracteres ou expressões de comprimento fixo ou variável.
## Tipo de retorno
O operador \$1\$1 retorna uma string. O tipo de string é igual ao tipo dos argumentos de entrada.
## Exemplo
O seguinte exemplo concatena os campos FIRSTNAME e LASTNAME da tabela USERS:
```
select firstname || ' ' || lastname
from users
order by 1
limit 10;
concat
-----------------
Aaron Banks
Aaron Booth
Aaron Browning
Aaron Burnett
Aaron Casey
Aaron Cash
Aaron Castro
Aaron Dickerson
Aaron Dixon
Aaron Dotson
(10 rows)
```
Para concatenar colunas que possam conter nulos, use a expressão [Funções NVL e COALESCE](NVL_function.md). O seguinte exemplo usa NVL para retornar um 0 sempre que NULL for encontrado.
```
select venuename || ' seats ' || nvl(venueseats, 0)
from venue where venuestate = 'NV' or venuestate = 'NC'
order by 1
limit 10;
seating
-----------------------------------
Ballys Hotel seats 0
Bank of America Stadium seats 73298
Bellagio Hotel seats 0
Caesars Palace seats 0
Harrahs Hotel seats 0
Hilton Hotel seats 0
Luxor Hotel seats 0
Mandalay Bay Hotel seats 0
Mirage Hotel seats 0
New York New York seats 0
```
# Função BTRIM
A função BTRIM apara uma string removendo os espaços em branco iniciais e finais ou removendo caracteres iniciais ou finais que correspondem a uma string opcional especificada.
## Sintaxe
```
BTRIM(string [, trim_chars ] )
```
## Argumentos
*string*
A string VARCHAR de entrada a ser cortada.
*trim\$1chars*
A string VARCHAR que contém os caracteres a serem correspondidos.
## Tipo de retorno
A função BTRIM retorna uma string VARCHAR.
## Exemplos
O seguinte exemplo apara espaços em branco inicias e finais da string `' abc '`:
```
select ' abc ' as untrim, btrim(' abc ') as trim;
untrim | trim
----------+------
abc | abc
```
O exemplo a seguir remove a string `'xyz'` inicial e final da string `'xyzaxyzbxyzcxyz'`. As ocorrências inicial e final de `'xyz'` são removidas, mas as ocorrências internas da string não são removidas.
```
select 'xyzaxyzbxyzcxyz' as untrim,
btrim('xyzaxyzbxyzcxyz', 'xyz') as trim;
untrim | trim
-----------------+-----------
xyzaxyzbxyzcxyz | axyzbxyzc
```
O exemplo a seguir remove as partes iniciais e finais da string `'setuphistorycassettes'` que correspondem a qualquer um dos caracteres na lista *trim\$1chars* `'tes'`. Qualquer `t`, `e` ou `s` que ocorra antes que outro caractere que não esteja na lista *trim\$1chars* no início ou no final da string de entrada seja removido.
```
SELECT btrim('setuphistorycassettes', 'tes');
btrim
-----------------
uphistoryca
```
# Função CONCAT
A função CONCAT concatena duas expressões e retorna a expressão resultante. Para concatenar mais de duas strings, use funções CONCAT aninhadas. O operador de concatenação (`||`) entre duas expressões produz os mesmos resultados que a função CONCAT.
**nota**
Tanto para a função CONCAT como para o operador de concatenação, se uma ou ambas as expressões forem nulas, o resultado da concatenação será null.
## Sintaxe
```
CONCAT ( expression1, expression2 )
```
## Argumentos
*expression1*, *expression2*
Os dois argumentos podem ser uma cadeia de caracteres de comprimento fixo, uma cadeia de caracteres de comprimento variável, uma expressão binária ou uma expressão que é avaliada para uma dessas entradas.
## Tipo de retorno
CONCAT retorna uma expressão. O tipo de dados da expressão é o mesmo tipo dos argumentos de entrada.
Se as expressões de entrada forem de tipos diferentes, AWS Clean Rooms tentará digitar implicitamente uma das expressões. Se os valores não puderem ser convertidos, será retornado um erro.
## Exemplos
O seguinte exemplo concatena dois literais de caracteres:
```
select concat('December 25, ', '2008');
concat
-------------------
December 25, 2008
(1 row)
```
A seguinte consulta, usando o operador `||` em vez de CONCAT, produz o mesmo resultado:
```
select 'December 25, '||'2008';
concat
-------------------
December 25, 2008
(1 row)
```
O seguinte exemplo usa duas funções CONCAT para concatenar três strings de caracteres:
```
select concat('Thursday, ', concat('December 25, ', '2008'));
concat
-----------------------------
Thursday, December 25, 2008
(1 row)
```
Para concatenar colunas que possam conter nulos, use a [Funções NVL e COALESCE](NVL_function.md). O seguinte exemplo usa NVL para retornar um 0 sempre que NULL for encontrado.
```
select concat(venuename, concat(' seats ', nvl(venueseats, 0))) as seating
from venue where venuestate = 'NV' or venuestate = 'NC'
order by 1
limit 5;
seating
-----------------------------------
Ballys Hotel seats 0
Bank of America Stadium seats 73298
Bellagio Hotel seats 0
Caesars Palace seats 0
Harrahs Hotel seats 0
(5 rows)
```
A seguinte consulta concatena os valores CITY e STATE da tabela VENUE:
```
select concat(venuecity, venuestate)
from venue
where venueseats > 75000
order by venueseats;
concat
-------------------
DenverCO
Kansas CityMO
East RutherfordNJ
LandoverMD
(4 rows)
```
A seguinte consulta usa funções CONCAT aninhadas. A consulta concatena os valores CITY e STATE da tabela VENUE, mas delimita a string resultante com uma vírgula e um espaço:
```
select concat(concat(venuecity,', '),venuestate)
from venue
where venueseats > 75000
order by venueseats;
concat
---------------------
Denver, CO
Kansas City, MO
East Rutherford, NJ
Landover, MD
(4 rows)
```
# função FORMAT\$1STRING
A função FORMAT\$1STRING cria uma string formatada substituindo os espaços reservados em uma string de modelo pelos argumentos fornecidos. Ele retorna uma string formatada de strings de formato no estilo printf.
A função FORMAT\$1STRING funciona substituindo os espaços reservados na string do modelo pelos valores correspondentes passados como argumentos. Esse tipo de formatação de string pode ser útil quando você precisa construir dinamicamente cadeias de caracteres que incluam uma mistura de texto estático e dados dinâmicos, como ao gerar mensagens de saída, relatórios ou outros tipos de texto informativo. A função FORMAT\$1STRING fornece uma maneira concisa e legível de criar esses tipos de strings formatadas, facilitando a manutenção e a atualização do código que gera a saída.
## Sintaxe
```
format_string(strfmt, obj, ...)
```
## Argumentos
*strfmt*
Uma expressão STRING.
*obj*
Uma STRING ou expressão numérica.
## Tipo de retorno
FORMAT\$1STRING retorna uma STRING.
## Exemplo
O exemplo a seguir contém uma string de modelo que contém dois espaços reservados: `%d` para um valor decimal (inteiro) e `%s` para um valor de string. O `%d` espaço reservado é substituído pelo valor decimal (inteiro) () e o espaço reservado %s é substituído pelo valor da string (`100`). `"days"` A saída é uma string de modelo com os espaços reservados substituídos pelos argumentos fornecidos:`"Hello World 100 days"`.
```
SELECT format_string("Hello World %d %s", 100, "days");
Hello World 100 days
```
# Funções LEFT e RIGHT
Essas funções retornam o número especificado de caracteres mais à esquerda ou mais à direita de uma string de caracteres.
O número é baseado no número de caracteres, e não bytes, de forma que caracteres multibyte são contados como caracteres simples.
## Sintaxe
```
LEFT ( string, integer )
RIGHT ( string, integer )
```
## Argumentos
*string*
Qualquer string de caracteres ou qualquer expressão que avalie para uma string de caracteres.
*inteiro*
Um inteiro positivo.
## Tipo de retorno
LEFT e RIGHT retornam uma string VARCHAR.
## Exemplo
O exemplo a seguir retorna os 5 caracteres mais à esquerda e os 5 caracteres mais à direita de nomes de eventos que têm IDs entre 1000 e 1005:
```
select eventid, eventname,
left(eventname,5) as left_5,
right(eventname,5) as right_5
from event
where eventid between 1000 and 1005
order by 1;
eventid | eventname | left_5 | right_5
--------+----------------+--------+---------
1000 | Gypsy | Gypsy | Gypsy
1001 | Chicago | Chica | icago
1002 | The King and I | The K | and I
1003 | Pal Joey | Pal J | Joey
1004 | Grease | Greas | rease
1005 | Chicago | Chica | icago
(6 rows)
```
# Função LENGTH
# Função LOWER
Converte uma string em letras minúsculas. LOWER é compatível com caracteres UTF-8 multibyte, até o máximo de quatro bytes por caractere.
## Sintaxe
```
LOWER(string)
```
## Argumento
*string*
O parâmetro de entrada é uma string VARCHAR (ou qualquer outro tipo de dados, como CHAR, que pode ser convertido implicitamente para VARCHAR).
## Tipo de retorno
A função LOWER retorna uma string de caractere no mesmo tipo de dados que a string de entrada.
## Exemplos
O exemplo a seguir converte o campo CATNAME em minúsculas:
```
select catname, lower(catname) from category order by 1,2;
catname | lower
----------+-----------
Classical | classical
Jazz | jazz
MLB | mlb
MLS | mls
Musicals | musicals
NBA | nba
NFL | nfl
NHL | nhl
Opera | opera
Plays | plays
Pop | pop
(11 rows)
```
# Funções LPAD e RPAD
Essas funções inserem caracteres no início ou final de uma string com base em um comprimento especificado.
## Sintaxe
```
LPAD (string1, length, [ string2 ])
```
```
RPAD (string1, length, [ string2 ])
```
## Argumentos
*string1*
Uma string de caracteres ou uma expressão que avalie para uma string de caracteres, tal como o nome de uma coluna de caracteres.
*length*
Um inteiro que define o comprimento dos resultados da função. O comprimento de uma string é baseado no número de caracteres, e não bytes, de forma que caracteres multibyte são contados como caracteres simples. Se *string1* for mais longa que o comprimento especificado, ela será truncada (à direita). Se *length* for um número negativo, o resultado da função será uma string vazia.
*string2*
Um ou mais caracteres inseridos no início ou no fim da *string1*. Este argumento é opcional; se ele não é especificado, espaços são usados.
## Tipo de retorno
Essas funções retornam um tipo de dados VARCHAR.
## Exemplos
Trunque um conjunto específico de nomes de eventos para 20 caracteres e insira espaços no início dos nomes mais curtos:
```
select lpad(eventname,20) from event
where eventid between 1 and 5 order by 1;
lpad
--------------------
Salome
Il Trovatore
Boris Godunov
Gotterdammerung
La Cenerentola (Cind
(5 rows)
```
Trunque o mesmo conjunto de nomes de eventos para 20 caracteres, mas insira no início dos nomes mais curtos `0123456789`.
```
select rpad(eventname,20,'0123456789') from event
where eventid between 1 and 5 order by 1;
rpad
--------------------
Boris Godunov0123456
Gotterdammerung01234
Il Trovatore01234567
La Cenerentola (Cind
Salome01234567890123
(5 rows)
```
# Função LTRIM
Corta caracteres do início de uma string. Remove a string mais longa que contém somente caracteres que estão na lista de caracteres de corte. O corte é concluído quando um caractere de corte não aparece na string de entrada.
## Sintaxe
```
LTRIM( string [, trim_chars] )
```
## Argumentos
*string*
Uma coluna, expressão ou literal de string a ser cortado.
*trim\$1chars*
Uma coluna, expressão ou literal de string que representa os caracteres a serem cortados do começo da *string*. Se não for especificado, um espaço será usado como caractere de corte.
## Tipo de retorno
A função LTRIM retorna uma string no mesmo tipo de dado que a *string* de entrada (CHAR ou VARCHAR).
## Exemplos
O exemplo a seguir corta o ano da coluna `listime`. Os caracteres de corte no literal de string `'2008-'` indicam os caracteres a serem cortados da esquerda. Se você usar os caracteres de corte `'028-'`, obterá o mesmo resultado.
```
select listid, listtime, ltrim(listtime, '2008-')
from listing
order by 1, 2, 3
limit 10;
listid | listtime | ltrim
-------+---------------------+----------------
1 | 2008-01-24 06:43:29 | 1-24 06:43:29
2 | 2008-03-05 12:25:29 | 3-05 12:25:29
3 | 2008-11-01 07:35:33 | 11-01 07:35:33
4 | 2008-05-24 01:18:37 | 5-24 01:18:37
5 | 2008-05-17 02:29:11 | 5-17 02:29:11
6 | 2008-08-15 02:08:13 | 15 02:08:13
7 | 2008-11-15 09:38:15 | 11-15 09:38:15
8 | 2008-11-09 05:07:30 | 11-09 05:07:30
9 | 2008-09-09 08:03:36 | 9-09 08:03:36
10 | 2008-06-17 09:44:54 | 6-17 09:44:54
```
LTRIM remove qualquer um dos caracteres em *trim\$1chars* quando eles aparecem no início da *string*. O seguinte exemplo apara os caracteres “C”, “D” e “G” quando eles aparecem no início de VENUENAME, que é uma coluna VARCHAR.
```
select venueid, venuename, ltrim(venuename, 'CDG')
from venue
where venuename like '%Park'
order by 2
limit 7;
venueid | venuename | btrim
--------+----------------------------+--------------------------
121 | ATT Park | ATT Park
109 | Citizens Bank Park | itizens Bank Park
102 | Comerica Park | omerica Park
9 | Dick's Sporting Goods Park | ick's Sporting Goods Park
97 | Fenway Park | Fenway Park
112 | Great American Ball Park | reat American Ball Park
114 | Miller Park | Miller Park
```
O exemplo a seguir usa o caractere de corte `2` que é recuperado da coluna `venueid`.
```
select ltrim('2008-01-24 06:43:29', venueid)
from venue where venueid=2;
ltrim
------------------
008-01-24 06:43:29
```
O exemplo a seguir não corta nenhum caractere porque `2` é encontrado antes do caractere de corte `'0'`.
```
select ltrim('2008-01-24 06:43:29', '0');
ltrim
-------------------
2008-01-24 06:43:29
```
O exemplo a seguir usa o caractere de corte de espaço padrão e corta os dois espaços do início da string.
```
select ltrim(' 2008-01-24 06:43:29');
ltrim
-------------------
2008-01-24 06:43:29
```
# Função POSITION
Retorna a localização da substring especificada dentro de uma string.
## Sintaxe
```
POSITION(substring IN string )
```
## Argumentos
*substring*
A substring a procurar dentro da *string*.
*string*
A string ou coluna a ser procurada.
## Tipo de retorno
A função POSITION retorna um inteiro correspondente à posição da substring (baseada em 1, não baseada em zero). A posição é baseada no número de caracteres, e não bytes, de forma que caracteres multibyte são contados como caracteres simples.
## Observações de uso
POSITION retornará 0 se a substring não for localizada dentro da string:
```
select position('dog' in 'fish');
position
----------
0
(1 row)
```
## Exemplos
O seguinte exemplo mostra a posição da string `fish` na palavra `dogfish`:
```
select position('fish' in 'dogfish');
position
----------
4
(1 row)
```
O seguinte exemplo retorna o número de transações de vendas com uma COMMISSION acima de 999,00 da tabela SALES:
```
select distinct position('.' in commission), count (position('.' in commission))
from sales where position('.' in commission) > 4 group by position('.' in commission)
order by 1,2;
position | count
---------+-------
5 | 629
(1 row)
```
# Função REGEXP\$1COUNT
Pesquisa uma string quanto a um padrão de expressão regular e retorna um inteiro que indica o número de vezes que o padrão ocorre na string. Se nenhuma correspondência for encontrada, a função retornará 0.
## Sintaxe
```
REGEXP_COUNT ( source_string, pattern [, position [, parameters ] ] )
```
## Argumentos
*source\$1string*
Uma expressão de string, tal como um nome de coluna, a ser procurada.
*pattern*
Um literal de string que representa um padrão de expressão regular.
*position*
Um inteiro positivo que indica a posição em *source\$1string* para começar a pesquisar. A posição é baseada no número de caracteres, e não bytes, de forma que caracteres multibyte são contados como caracteres simples. O padrão é um. Se a *posição* for menor que 1, a pesquisa começará no primeiro caractere da *source\$1string*. Se *position* for maior que o número de caracteres na *source\$1string*, o resultado será 0.
*parameters*
Uma ou mais literais de sequências que indicam como a função corresponde o padrão. Os valores possíveis são os seguintes:
+ c – Executa a correspondência diferenciando maiúsculas e minúsculas. O padrão é usar a correspondência diferenciando maiúsculas e minúsculas.
+ i – Executa a correspondência sem diferenciar maiúsculas de minúsculas.
+ p — Interpreta o padrão com o dialeto de expressão regular compatível com Perl (PCRE - Perl Compatible Regular Expression).
## Tipo de retorno
Inteiro
## Exemplo
O seguinte exemplo conta o número de vezes que uma sequência de três letra ocorre.
```
SELECT regexp_count('abcdefghijklmnopqrstuvwxyz', '[a-z]{3}');
regexp_count
--------------
8
```
O seguinte exemplo conta o número de vezes que nome de domínio de nível superior é `org` ou `edu`.
```
SELECT email, regexp_count(email,'@[^.]*\\.(org|edu)')FROM users
ORDER BY userid LIMIT 4;
email | regexp_count
-----------------------------------------------+--------------
Etiam.laoreet.libero@sodalesMaurisblandit.edu | 1
Suspendisse.tristique@nonnisiAenean.edu | 1
amet.faucibus.ut@condimentumegetvolutpat.ca | 0
sed@lacusUtnec.ca | 0
```
O exemplo a seguir conta as ocorrências da string `FOX` usando a correspondência sem diferenciar maiúsculas de minúsculas.
```
SELECT regexp_count('the fox', 'FOX', 1, 'i');
regexp_count
--------------
1
```
O exemplo a seguir usa um padrão escrito no dialeto PCRE para localizar palavras contendo pelo menos um número e uma letra minúscula. Ele usa o operador `?=`, que tem uma conotação específica look-ahead em PCRE. Este exemplo conta o número de ocorrências de tais palavras, com correspondência diferenciando maiúsculas de minúsculas.
```
SELECT regexp_count('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 'p');
regexp_count
--------------
2
```
O exemplo a seguir usa um padrão escrito no dialeto PCRE para localizar palavras contendo pelo menos um número e uma letra minúscula. Ele usa o operador `?=`, que tem uma conotação específica em PCRE. Este exemplo conta o número de ocorrências de tais palavras, mas difere do exemplo anterior na medida em que usa correspondência sem diferenciar maiúsculas dee minúsculas.
```
SELECT regexp_count('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 'ip');
regexp_count
--------------
3
```
# Função REGEXP\$1INSTR
Pesquisa um padrão de expressão regular em uma sequência e retorna um inteiro que indica a posição inicial ou final da subsequência correspondente. Se nenhuma correspondência for encontrada, a função retornará 0. REGEXP\$1INSTR é semelhante à função [POSITION](POSITION.md), mas permite que você pesquise um padrão de expressão regular em uma sequência.
## Sintaxe
```
REGEXP_INSTR ( source_string, pattern [, position [, occurrence] [, option [, parameters ] ] ] ] )
```
## Argumentos
*source\$1string*
Uma expressão de string, tal como um nome de coluna, a ser procurada.
*pattern*
Um literal de string que representa um padrão de expressão regular.
*position*
Um inteiro positivo que indica a posição em *source\$1string* para começar a pesquisar. A posição é baseada no número de caracteres, e não bytes, de forma que caracteres multibyte são contados como caracteres simples. O padrão é um. Se a *posição* for menor que 1, a pesquisa começará no primeiro caractere da *source\$1string*. Se *position* for maior que o número de caracteres na *source\$1string*, o resultado será 0.
*occurrence*
Um inteiro positivo que indica qual ocorrência do padrão usar. REGEXP\$1INSTR ignora as primeiras correspondências de *occurrence* -1. O padrão é um. Se *ocurrence* for menor que 1 ou maior que o número de caracteres em *source\$1string*, a pesquisa será ignorada e o resultado será 0.
*option*
Um valor que indica se retornar a posição do primeiro caractere da correspondência (`0`) ou a posição do primeiro caractere seguinte ao final da correspondência (`1`). Um valor diferente de zero é o mesmo que 1. O valor padrão é 0.
*parameters*
Uma ou mais literais de sequências que indicam como a função corresponde o padrão. Os valores possíveis são os seguintes:
+ c – Executa a correspondência diferenciando maiúsculas e minúsculas. O padrão é usar a correspondência diferenciando maiúsculas e minúsculas.
+ i – Executa a correspondência sem diferenciar maiúsculas de minúsculas.
+ e – Extrai uma subsequência usando uma subexpressão.
Se o *padrão* incluir uma subexpressão, REGEXP\$1INSTR corresponderá uma subsequência usando a primeira subexpressão em *padrão*. REGEXP\$1INSTR considera apenas a primeira subexpressão. As subexpressões adicionais são ignoradas. Se o padrão não tiver uma subexpressão, REGEXP\$1INSTR ignorará o parâmetro 'e'.
+ p — Interpreta o padrão com o dialeto de expressão regular compatível com Perl (PCRE - Perl Compatible Regular Expression).
## Tipo de retorno
Inteiro
## Exemplo
O seguinte exemplo procura pelo caractere `@` que inicia o nome de um domínio e retorna a posição inicial da primeira correspondência.
```
SELECT email, regexp_instr(email, '@[^.]*')
FROM users
ORDER BY userid LIMIT 4;
email | regexp_instr
-----------------------------------------------+--------------
Etiam.laoreet.libero@example.com | 21
Suspendisse.tristique@nonnisiAenean.edu | 22
amet.faucibus.ut@condimentumegetvolutpat.ca | 17
sed@lacusUtnec.ca | 4
```
O seguinte exemplo procura por variações da palavra `Center` e retorna a posição inicial da primeira correspondência.
```
SELECT venuename, regexp_instr(venuename,'[cC]ent(er|re)$')
FROM venue
WHERE regexp_instr(venuename,'[cC]ent(er|re)$') > 0
ORDER BY venueid LIMIT 4;
venuename | regexp_instr
-----------------------+--------------
The Home Depot Center | 16
Izod Center | 6
Wachovia Center | 10
Air Canada Centre | 12
```
O exemplo a seguir encontra a posição inicial da primeira ocorrência da string `FOX` usando lógica de correspondência sem diferenciar maiúsculas de minúsculas.
```
SELECT regexp_instr('the fox', 'FOX', 1, 1, 0, 'i');
regexp_instr
--------------
5
```
O exemplo a seguir usa um padrão escrito em dialeto PCRE para localizar palavras contendo pelo menos um número e uma letra minúscula. Ele usa o operador `?=`, que tem uma conotação específica look-ahead em PCRE. Este exemplo encontra a posição inicial da segunda palavra.
```
SELECT regexp_instr('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 2, 0, 'p');
regexp_instr
--------------
21
```
O exemplo a seguir usa um padrão escrito em dialeto PCRE para localizar palavras contendo pelo menos um número e uma letra minúscula. Ele usa o operador `?=`, que tem uma conotação específica look-ahead em PCRE. Este exemplo localiza a posição inicial da segunda palavra, mas difere do exemplo anterior na medida em que usa correspondência sem diferenciar maiúsculas de minúsculas.
```
SELECT regexp_instr('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 2, 0, 'ip');
regexp_instr
--------------
15
```
# Função REGEXP\$1REPLACE
Pesquisa uma string quanto a um padrão de expressão regular e substitui cada ocorrência do padrão pela string especificada. REGEXP\$1REPLACE é semelhante a [Função REPLACE](REPLACE.md), mas permite que você pesquise uma string quanto a um padrão de expressão regular.
REGEXP\$1REPLACE é semelhante a [Função TRANSLATE](TRANSLATE.md) e [Função REPLACE](REPLACE.md), exceto que TRANSLATE faz várias substituições de caractere único e REPLACE substitui uma string inteira por outra string, enquanto REGEXP\$1REPLACE permite que você pesquise uma string quanto a um padrão de expressão regular.
## Sintaxe
```
REGEXP_REPLACE ( source_string, pattern [, replace_string [ , position [, parameters ] ] ] )
```
## Argumentos
*source\$1string*
Uma expressão de string, tal como um nome de coluna, a ser procurada.
*pattern*
Um literal de string que representa um padrão de expressão regular.
*replace\$1string*
Uma expressão de string, tal como um nome de coluna, que substituirá cada ocorrência do padrão. O padrão é uma string vazia ( "" ).
*position*
Um inteiro positivo que indica a posição em *source\$1string* para começar a pesquisar. A posição é baseada no número de caracteres, e não bytes, de forma que caracteres multibyte são contados como caracteres simples. O padrão é um. Se a *posição* for menor que 1, a pesquisa começará no primeiro caractere da *source\$1string*. Se *position* for maior que o número de caracteres na *source\$1string*, o resultado será *source\$1string*.
*parameters*
Uma ou mais literais de sequências que indicam como a função corresponde o padrão. Os valores possíveis são os seguintes:
+ c – Executa a correspondência diferenciando maiúsculas e minúsculas. O padrão é usar a correspondência diferenciando maiúsculas e minúsculas.
+ i – Executa a correspondência sem diferenciar maiúsculas de minúsculas.
+ p — Interpreta o padrão com o dialeto de expressão regular compatível com Perl (PCRE - Perl Compatible Regular Expression).
## Tipo de retorno
VARCHAR
Se *pattern* ou *replace\$1string* for NULL, o retorno será NULL.
## Exemplo
O seguinte exemplo exclui o `@` e o nome de domínio dos endereços de e-mail.
```
SELECT email, regexp_replace(email, '@.*\\.(org|gov|com|edu|ca)$')
FROM users
ORDER BY userid LIMIT 4;
email | regexp_replace
-----------------------------------------------+----------------
Etiam.laoreet.libero@sodalesMaurisblandit.edu | Etiam.laoreet.libero
Suspendisse.tristique@nonnisiAenean.edu | Suspendisse.tristique
amet.faucibus.ut@condimentumegetvolutpat.ca | amet.faucibus.ut
sed@lacusUtnec.ca | sed
```
O seguinte exemplo substitui os nomes de domínio de endereços de e-mail por esse valor: `internal.company.com`.
```
SELECT email, regexp_replace(email, '@.*\\.[[:alpha:]]{2,3}',
'@internal.company.com') FROM users
ORDER BY userid LIMIT 4;
email | regexp_replace
-----------------------------------------------+--------------------------------------------
Etiam.laoreet.libero@sodalesMaurisblandit.edu | Etiam.laoreet.libero@internal.company.com
Suspendisse.tristique@nonnisiAenean.edu | Suspendisse.tristique@internal.company.com
amet.faucibus.ut@condimentumegetvolutpat.ca | amet.faucibus.ut@internal.company.com
sed@lacusUtnec.ca | sed@internal.company.com
```
O exemplo a seguir conta as ocorrências da string `FOX` no valor `quick brown fox` usando a correspondência sem diferenciar maiúsculas de minúsculas.
```
SELECT regexp_replace('the fox', 'FOX', 'quick brown fox', 1, 'i');
regexp_replace
---------------------
the quick brown fox
```
O exemplo a seguir usa um padrão escrito no dialeto PCRE para localizar palavras contendo pelo menos um número e uma letra minúscula. Ele usa o operador `?=`, que tem uma conotação específica look-ahead em PCRE. Este exemplo substitui cada ocorrência de tal palavra pelo valor `[hidden]`.
```
SELECT regexp_replace('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', '[hidden]', 1, 'p');
regexp_replace
-------------------------------
[hidden] plain A1234 [hidden]
```
O exemplo a seguir usa um padrão escrito no dialeto PCRE para localizar palavras contendo pelo menos um número e uma letra minúscula. Ele usa o operador `?=`, que tem uma conotação específica look-ahead em PCRE. Este exemplo substitui cada ocorrência de tal palavra pelo valor`[hidden]`, mas difere do exemplo anterior na medida em que ele usa correspondência sem diferenciar maiúsculas de minúsculas.
```
SELECT regexp_replace('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', '[hidden]', 1, 'ip');
regexp_replace
----------------------------------
[hidden] plain [hidden] [hidden]
```
# Função REGEXP\$1SUBSTR
Retorna os caracteres de uma string ao procurar por um padrão de expressão regular. REGEXP\$1SUBSTR é semelhante a função [Função SUBSTRING](SUBSTRING.md), mas permite que você pesquise uma string quanto a um padrão de expressão regular. Se a função não conseguir corresponder a expressão regular com nenhum caractere na string, ela retornará uma string vazia.
## Sintaxe
```
REGEXP_SUBSTR ( source_string, pattern [, position [, occurrence [, parameters ] ] ] )
```
## Argumentos
*source\$1string*
Uma expressão de string a ser pesquisada.
*pattern*
Um literal de string que representa um padrão de expressão regular.
*position*
Um inteiro positivo que indica a posição em *source\$1string* para começar a pesquisar. A posição é baseada no número de caracteres, e não bytes, de forma que caracteres multibyte são contados como caracteres simples. O padrão é um. Se a *posição* for menor que 1, a pesquisa começará no primeiro caractere da *source\$1string*. Se *position* for maior que o número de caracteres na *source\$1string*, o resultado será uma string vazia ("").
*occurrence*
Um inteiro positivo que indica qual ocorrência do padrão usar. REGEXP\$1SUBSTR ignora as primeiras correspondências de *occurrence* -1. O padrão é um. Se a *ocorrência* for menor que 1 ou maior que o número de caracteres em *source\$1string*, a pesquisa será ignorada e o resultado será NULL.
*parameters*
Uma ou mais literais de sequências que indicam como a função corresponde o padrão. Os valores possíveis são os seguintes:
+ c – Executa a correspondência diferenciando maiúsculas e minúsculas. O padrão é usar a correspondência diferenciando maiúsculas e minúsculas.
+ i – Executa a correspondência sem diferenciar maiúsculas de minúsculas.
+ e – Extrai uma subsequência usando uma subexpressão.
Se o *padrão* incluir uma subexpressão, REGEXP\$1SUBSTR corresponderá uma subsequência usando a primeira subexpressão em *padrão*. Uma subexpressão é uma expressão dentro do padrão que está entre parênteses. Por exemplo, para o padrão `'This is a (\\w+)'` faz correspondência com a primeira expressão com a string `'This is a '` seguida por uma palavra. Em vez de retornar o *padrão*, REGEXP\$1SUBSTR com o parâmetro `e` retorna somente a string dentro da subexpressão.
REGEXP\$1SUBSTR considera apenas a primeira subexpressão. As subexpressões adicionais são ignoradas. Se o padrão não tiver uma subexpressão, REGEXP\$1SUBSTR ignorará o parâmetro 'e'.
+ p — Interpreta o padrão com o dialeto de expressão regular compatível com Perl (PCRE - Perl Compatible Regular Expression).
## Tipo de retorno
VARCHAR
## Exemplo
O seguinte exemplo retorna a porção de um endereço de e-mail entre o caractere @ e a extensão de domínio.
```
SELECT email, regexp_substr(email,'@[^.]*')
FROM users
ORDER BY userid LIMIT 4;
email | regexp_substr
-----------------------------------------------+--------------------------
Etiam.laoreet.libero@sodalesMaurisblandit.edu | @sodalesMaurisblandit
Suspendisse.tristique@nonnisiAenean.edu | @nonnisiAenean
amet.faucibus.ut@condimentumegetvolutpat.ca | @condimentumegetvolutpat
sed@lacusUtnec.ca | @lacusUtnec
```
O exemplo a seguir retorna a porção da entrada correspondente à primeira ocorrência da string `FOX` com a correspondência sem diferenciar maiúsculas de minúsculas.
```
SELECT regexp_substr('the fox', 'FOX', 1, 1, 'i');
regexp_substr
---------------
fox
```
O exemplo a seguir retorna a primeira parte da entrada que começa com letras minúsculas. Isso é funcionalmente idêntico à mesma instrução SELECT sem o parâmetro `c`.
```
SELECT regexp_substr('THE SECRET CODE IS THE LOWERCASE PART OF 1931abc0EZ.', '[a-z]+', 1, 1, 'c');
regexp_substr
---------------
abc
```
O exemplo a seguir usa um padrão escrito no dialeto PCRE para localizar palavras contendo pelo menos um número e uma letra minúscula. Ele usa o operador `?=`, que tem uma conotação específica look-ahead em PCRE. Este exemplo retorna a parte da entrada correspondente à segunda palavra.
```
SELECT regexp_substr('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 2, 'p');
regexp_substr
---------------
a1234
```
O exemplo a seguir usa um padrão escrito no dialeto PCRE para localizar palavras contendo pelo menos um número e uma letra minúscula. Ele usa o operador `?=`, que tem uma conotação específica look-ahead em PCRE. Este exemplo retorna a parte da entrada correspondente à segunda palavra, mas difere do exemplo anterior na medida em que usa a correspondência sem diferenciar maiúsculas de minúsculas.
```
SELECT regexp_substr('passwd7 plain A1234 a1234', '(?=[^ ]*[a-z])(?=[^ ]*[0-9])[^ ]+', 1, 2, 'ip');
regexp_substr
---------------
A1234
```
O exemplo a seguir usa uma subexpressão para encontrar a segunda string correspondente ao padrão `'this is a (\\w+)'` usando a correspondência que não diferencia letras maiúsculas de minúsculas. Ele retorna a subexpressão dentro dos parênteses.
```
select regexp_substr(
'This is a cat, this is a dog. This is a mouse.',
'this is a (\\w+)', 1, 2, 'ie');
regexp_substr
---------------
dog
```
# Função REPEAT
Repete uma string pelo número especificado de vezes. Se o parâmetro de entrada for numérico, REPEAT o tratará como uma string.
## Sintaxe
```
REPEAT(string, integer)
```
## Argumentos
*string*
O primeiro parâmetro de entrada é a string a ser repetida.
*inteiro*
O segundo parâmetro é um inteiro indicando o número de vezes a repetir a string.
## Tipo de retorno
A função REPEAT retorna uma string.
## Exemplos
O seguinte exemplo repete o valor da coluna CATID na tabela CATEGORY três vezes:
```
select catid, repeat(catid,3)
from category
order by 1,2;
catid | repeat
-------+--------
1 | 111
2 | 222
3 | 333
4 | 444
5 | 555
6 | 666
7 | 777
8 | 888
9 | 999
10 | 101010
11 | 111111
(11 rows)
```
# Função REPLACE
Substitui todas as ocorrências de um conjunto de caracteres em uma string existente por outros caracteres especificados.
REPLACE é semelhante a [Função TRANSLATE](TRANSLATE.md) e [Função REGEXP\$1REPLACE](REGEXP_REPLACE.md), exceto que TRANSLATE faz várias substituições de caractere único e REGEXP\$1REPLACE permite que você pesquise uma string quanto a um padrão de expressão regular, enquanto REPLACE substitui uma string inteira por outra string.
## Sintaxe
```
REPLACE(string1, old_chars, new_chars)
```
## Argumentos
*string*
String CHAR ou VARCHAR a ser procurada.
*old\$1chars*
String CHAR ou VARCHAR a substituir.
*new\$1chars*
Nova string CHAR ou VARCHAR que substitui *old\$1string*.
## Tipo de retorno
VARCHAR
Se *old\$1chars* ou *new\$1chars* for NULL, o retorno será NULL.
## Exemplos
O seguinte exemplo converte a string `Shows` em `Theatre` no campo CATGROUP:
```
select catid, catgroup,
replace(catgroup, 'Shows', 'Theatre')
from category
order by 1,2,3;
catid | catgroup | replace
-------+----------+----------
1 | Sports | Sports
2 | Sports | Sports
3 | Sports | Sports
4 | Sports | Sports
5 | Sports | Sports
6 | Shows | Theatre
7 | Shows | Theatre
8 | Shows | Theatre
9 | Concerts | Concerts
10 | Concerts | Concerts
11 | Concerts | Concerts
(11 rows)
```
# Função REVERSE
A função REVERSE opera em uma string e retorna os caracteres na ordem reversa. Por exemplo, `reverse('abcde')` retorna `edcba`. Essa função funciona em tipos de dados numéricos e de data, assim como nos tipos de dados de caracteres; no entanto, na maioria dos casos ela possui um valor prático para strings de caracteres.
## Sintaxe
```
REVERSE ( expression )
```
## Argumento
*expressão*
Uma expressão com um tipo de dados de caractere, data, timestamp ou numérico que representa o destino da reversão de caracteres. Todas as expressões são convertidas implicitamente em strings de comprimento variável. Os espaços em branco finais em strings de caracteres de largura fixa são ignorados.
## Tipo de retorno
REVERSE retorna um VARCHAR.
## Exemplos
Selecione cinco nomes de cidade distintos e seus nomes invertidos correspondentes da tabela USERS:
```
select distinct city as cityname, reverse(cityname)
from users order by city limit 5;
cityname | reverse
---------+----------
Aberdeen | needrebA
Abilene | enelibA
Ada | adA
Agat | tagA
Agawam | mawagA
(5 rows)
```
Selecione cinco vendas IDs e seu IDs elenco invertido correspondente como sequências de caracteres:
```
select salesid, reverse(salesid)::varchar
from sales order by salesid desc limit 5;
salesid | reverse
--------+---------
172456 | 654271
172455 | 554271
172454 | 454271
172453 | 354271
172452 | 254271
(5 rows)
```
# Função RTRIM
A função RTRIM apara um conjunto específico de caracteres do final de uma string. Remove a string mais longa que contém somente caracteres que estão na lista de caracteres de corte. O corte é concluído quando um caractere de corte não aparece na string de entrada.
## Sintaxe
```
RTRIM( string, trim_chars )
```
## Argumentos
*string*
Uma coluna, expressão ou literal de string a ser cortado.
*trim\$1chars*
Uma coluna, expressão ou literal de string que representa os caracteres a serem cortados do final da *string*. Se não for especificado, um espaço será usado como caractere de corte.
## Tipo de retorno
Uma string no mesmo tipo de dados que o argumento da *string*.
## Exemplo
O seguinte exemplo apara espaços em branco inicias e finais da string `' abc '`:
```
select ' abc ' as untrim, rtrim(' abc ') as trim;
untrim | trim
----------+------
abc | abc
```
O exemplo a seguir remove a string `'xyz'` final da string `'xyzaxyzbxyzcxyz'`. As ocorrências iniciais de `'xyz'` são removidas, mas as ocorrências internas da string não são removidas.
```
select 'xyzaxyzbxyzcxyz' as untrim,
rtrim('xyzaxyzbxyzcxyz', 'xyz') as trim;
untrim | trim
-----------------+-----------
xyzaxyzbxyzcxyz | xyzaxyzbxyzc
```
O exemplo a seguir remove as partes finais da string `'setuphistorycassettes'` que correspondem a qualquer um dos caracteres na lista *trim\$1chars* `'tes'`. Qualquer `t`, `e` ou `s` que ocorra antes que outro caractere que não esteja na lista *trim\$1chars* no final da string de entrada é removido.
```
SELECT rtrim('setuphistorycassettes', 'tes');
rtrim
-----------------
setuphistoryca
```
O seguinte exemplo apara os caracteres "Park" do final de VENUENAME, onde presente:
```
select venueid, venuename, rtrim(venuename, 'Park')
from venue
order by 1, 2, 3
limit 10;
venueid | venuename | rtrim
--------+----------------------------+-------------------------
1 | Toyota Park | Toyota
2 | Columbus Crew Stadium | Columbus Crew Stadium
3 | RFK Stadium | RFK Stadium
4 | CommunityAmerica Ballpark | CommunityAmerica Ballp
5 | Gillette Stadium | Gillette Stadium
6 | New York Giants Stadium | New York Giants Stadium
7 | BMO Field | BMO Field
8 | The Home Depot Center | The Home Depot Cente
9 | Dick's Sporting Goods Park | Dick's Sporting Goods
10 | Pizza Hut Park | Pizza Hut
```
Observe que RTRIM remove qualquer um dos caracteres `P`, `a`, `r` ou `k` que aparecem no final de um VENUENAME.
# Função SPLIT
A função SPLIT permite extrair substrings de uma string maior e trabalhar com elas como uma matriz. A função SPLIT é útil quando você precisa dividir uma string em componentes individuais com base em um delimitador ou padrão específico.
## Sintaxe
```
split(str, regex, limit)
```
## Argumentos
*str*
Uma expressão de string para dividir.
*regex*
Uma string representando uma expressão regular. A string *regex* deve ser uma expressão regular Java.
*limit*
Uma expressão inteira que controla o número de vezes que o *regex é aplicado*.
+ limite > 0: o comprimento da matriz resultante não será maior que o limite, e a última entrada da matriz resultante conterá todas as entradas além da última *regex* correspondente.
+ limit <= 0: o *regex* será aplicado quantas vezes for possível, e a matriz resultante pode ser de qualquer tamanho.
## Tipo de retorno
A função SPLIT retorna um ARRAY.
Se`limit > 0`: O comprimento da matriz resultante não será maior que o limite, e a última entrada da matriz resultante conterá todas as entradas além da última regex correspondente.
If`limit <= 0`: regex será aplicado quantas vezes for possível e a matriz resultante poderá ser de qualquer tamanho.
## Exemplo
Neste exemplo, a função SPLIT divide a string de entrada `'oneAtwoBthreeC'` sempre que encontra os caracteres `'A'``'B'`, ou `'C'` (conforme especificado pelo padrão de expressão regular). `'[ABC]'` A saída resultante é uma matriz de quatro elementos:`"one"`, `"two"``"three"`, e uma string vazia`""`.
```
SELECT split('oneAtwoBthreeC', '[ABC]');
["one","two","three",""]
```
# Função SPLIT\$1PART
Divide uma string no delimitador especificado e retorna a parte na posição especificada.
## Sintaxe
```
SPLIT_PART(string, delimiter, position)
```
## Argumentos
*string*
Uma coluna, expressão ou literal de string a ser dividido. A string pode ser CHAR ou VARCHAR.
*delimitador*
A string delimitadora que indica seções da *string* de entrada.
Se o *delimitador* for um literal, coloque-o entre aspas simples.
*position*
Posição da porção da *string* a retornar (contando de 1). Deve ser um número inteiro maior que 0. Se *position* for maior que o número de porções de string, SPLIT\$1PART retornará uma string vazia. Se *delimiter* não for encontrado em *string*, o valor retornado conterá o conteúdo da parte especificada, que poderá ser toda a *string* ou um valor vazio.
## Tipo de retorno
Uma string CHAR ou VARCHAR, o mesmo que o parâmetro da *string*.
## Exemplos
O exemplo a seguir divide uma string literal em partes usando o delimitador `$` e retorna a segunda parte.
```
select split_part('abc$def$ghi','$',2)
split_part
----------
def
```
O exemplo a seguir divide uma string literal em partes usando o delimitador `$`. Ele retorna uma string vazia porque a parte `4` não foi encontrada.
```
select split_part('abc$def$ghi','$',4)
split_part
----------
```
O exemplo a seguir divide uma string literal em partes usando o delimitador `#`. Ele retorna a string inteira, que é a primeira parte, porque o delimitador não foi encontrado.
```
select split_part('abc$def$ghi','#',1)
split_part
------------
abc$def$ghi
```
O exemplo a seguir divide o campo de timestamp LISTTIME em componentes de ano, mês e dia.
```
select listtime, split_part(listtime,'-',1) as year,
split_part(listtime,'-',2) as month,
split_part(split_part(listtime,'-',3),' ',1) as day
from listing limit 5;
listtime | year | month | day
---------------------+------+-------+------
2008-03-05 12:25:29 | 2008 | 03 | 05
2008-09-09 08:03:36 | 2008 | 09 | 09
2008-09-26 05:43:12 | 2008 | 09 | 26
2008-10-04 02:00:30 | 2008 | 10 | 04
2008-01-06 08:33:11 | 2008 | 01 | 06
```
O seguinte exemplo seleciona o campo de timestamp LISTTIME e o divide no caractere `'-'` para obter o mês (a segunda parte da string LISTTIME) e, então, conta o número de entradas para cada mês:
```
select split_part(listtime,'-',2) as month, count(*)
from listing
group by split_part(listtime,'-',2)
order by 1, 2;
month | count
-------+-------
01 | 18543
02 | 16620
03 | 17594
04 | 16822
05 | 17618
06 | 17158
07 | 17626
08 | 17881
09 | 17378
10 | 17756
11 | 12912
12 | 4589
```
# Função SUBSTRING
Retorna o subconjunto de uma string com base na posição inicial especificada da string.
Se a entrada for uma cadeia de caracteres, a posição inicial e o número de caracteres extraídos são baseados nos caracteres, e não bytes, de forma que caracteres multibyte são contados como caracteres simples. Se a entrada for uma expressão binária, a posição inicial e a substring extraída são baseadas em bytes. Você não pode especificar um comprimento negativo, mas pode especificar uma posição inicial negativa.
## Sintaxe
```
SUBSTRING(charactestring FROM start_position [ FOR numbecharacters ] )
```
```
SUBSTRING(charactestring, start_position, numbecharacters )
```
```
SUBSTRING(binary_expression, start_byte, numbebytes )
```
```
SUBSTRING(binary_expression, start_byte )
```
## Argumentos
*cadeia de caracteres*
A string a ser pesquisada. Tipos de dados não caracteres são tratados como uma string.
*start\$1position*
A posição dentro da sequência para começar a extração, começando em 1. A *start\$1position* é baseada no número de caracteres, e não bytes, de forma que caracteres multibyte são contados como caracteres simples. Esse número pode ser negativo.
*caracteres numéricos*
O número de caracteres a extrair (o comprimento da substring). Os *caracteres numéricos* são baseados no número de caracteres, não em bytes, de modo que os caracteres de vários bytes sejam contados como caracteres únicos. Esse número não pode ser negativo.
*start\$1byte*
A posição dentro da expressão binária para começar a extração, começando por 1. Esse número pode ser negativo.
*número de bytes*
O número de bytes a serem extraídos, ou seja, o comprimento da substring. Esse número não pode ser negativo.
## Tipo de retorno
VARCHAR
## Notas de uso para cadeias de caracteres
O seguinte exemplo retorna uma string de quatro caracteres começando com o sexto caractere.
```
select substring('caterpillar',6,4);
substring
-----------
pill
(1 row)
```
*Se os caracteres *start\$1position* \$1 *numbecharacters* excederem o comprimento da *string, SUBSTRING retornará uma substring* começando da start\$1position até o final da string.* Por exemplo:
```
select substring('caterpillar',6,8);
substring
-----------
pillar
(1 row)
```
Se `start_position` for negativa ou 0, a função SUBSTRING retornará uma substring começando no primeiro caractere da string com um comprimento de `start_position` \$1 `numbecharacters` -1. Por exemplo:
```
select substring('caterpillar',-2,6);
substring
-----------
cat
(1 row)
```
Se `start_position` \$1 `numbecharacters` -1 for menor ou igual a zero, a SUBSTRING retornará uma string vazia. Por exemplo:
```
select substring('caterpillar',-5,4);
substring
-----------
(1 row)
```
## Exemplos
O seguinte exemplo retorna o mês da string LISTTIME na tabela LISTING:
```
select listid, listtime,
substring(listtime, 6, 2) as month
from listing
order by 1, 2, 3
limit 10;
listid | listtime | month
--------+---------------------+-------
1 | 2008-01-24 06:43:29 | 01
2 | 2008-03-05 12:25:29 | 03
3 | 2008-11-01 07:35:33 | 11
4 | 2008-05-24 01:18:37 | 05
5 | 2008-05-17 02:29:11 | 05
6 | 2008-08-15 02:08:13 | 08
7 | 2008-11-15 09:38:15 | 11
8 | 2008-11-09 05:07:30 | 11
9 | 2008-09-09 08:03:36 | 09
10 | 2008-06-17 09:44:54 | 06
(10 rows)
```
O seguinte exemplo é o mesmo que o exemplo acima, mas usa a opção FROM...FOR:
```
select listid, listtime,
substring(listtime from 6 for 2) as month
from listing
order by 1, 2, 3
limit 10;
listid | listtime | month
--------+---------------------+-------
1 | 2008-01-24 06:43:29 | 01
2 | 2008-03-05 12:25:29 | 03
3 | 2008-11-01 07:35:33 | 11
4 | 2008-05-24 01:18:37 | 05
5 | 2008-05-17 02:29:11 | 05
6 | 2008-08-15 02:08:13 | 08
7 | 2008-11-15 09:38:15 | 11
8 | 2008-11-09 05:07:30 | 11
9 | 2008-09-09 08:03:36 | 09
10 | 2008-06-17 09:44:54 | 06
(10 rows)
```
Não é possível usar a SUBSTRING para extrair previsivelmente o prefixo de uma string que possa conter caracteres multibyte, pois é necessário especificar o comprimento de uma string multibyte com base no número de bytes, e não no número de caracteres. Para extrair o segmento inicial de uma sequência com base no comprimento em bytes, você pode CAST a string como VARCHAR (*byte\$1length*) para truncar a string, onde *byte\$1length* é o tamanho exigido. O seguinte exemplo extrai os primeiros cinco bytes da string `'Fourscore and seven'`.
```
select cast('Fourscore and seven' as varchar(5));
varchar
-------
Fours
```
O exemplo a seguir retorna o nome `Ana` que aparece após o último espaço na string de entrada `Silva, Ana`.
```
select reverse(substring(reverse('Silva, Ana'), 1, position(' ' IN reverse('Silva, Ana'))))
reverse
-----------
Ana
```
# Função TRANSLATE
Para dada expressão, substitui todas as ocorrências dos caracteres especificados pelos substitutos especificados. Os caracteres existentes são mapeados aos caracteres de substituição pelas suas posições nos argumentos *characters\$1to\$1replace* e *characters\$1to\$1substitute*. Se mais caracteres estiverem especificados no argumento *characters\$1to\$1replace* que no argumento *characters\$1to\$1substitute*, os caracteres adicionais do argumento *characters\$1to\$1replace* serão omitidos do valor de retorno.
TRANSLATE é semelhante a [Função REPLACE](REPLACE.md) e [Função REGEXP\$1REPLACE](REGEXP_REPLACE.md), exceto que REPLACE substitui uma string inteira por outra string e REGEXP\$1REPLACE permite que você pesquise uma string quanto a um padrão de expressão regular, enquanto TRANSLATE faz várias substituições de caracteres simples.
Se qualquer um dos argumentos for nulo, o retorno será NULL.
## Sintaxe
```
TRANSLATE ( expression, characters_to_replace, characters_to_substitute )
```
## Argumentos
*expressão*
A expressão a ser traduzida.
*characters\$1to\$1replace*
Uma string contendo os caracteres a serem substituídos.
*characters\$1to\$1substitute*
Uma string contendo os caracteres a substituir.
## Tipo de retorno
VARCHAR
## Exemplos
O seguinte exemplo substitui vários caracteres em uma string:
```
select translate('mint tea', 'inea', 'osin');
translate
-----------
most tin
```
O seguinte exemplo substitui o sinal (@) por um ponto final para todos os valores em uma coluna:
```
select email, translate(email, '@', '.') as obfuscated_email
from users limit 10;
email obfuscated_email
-------------------------------------------------------------------------------------------
Etiam.laoreet.libero@sodalesMaurisblandit.edu Etiam.laoreet.libero.sodalesMaurisblandit.edu
amet.faucibus.ut@condimentumegetvolutpat.ca amet.faucibus.ut.condimentumegetvolutpat.ca
turpis@accumsanlaoreet.org turpis.accumsanlaoreet.org
ullamcorper.nisl@Cras.edu ullamcorper.nisl.Cras.edu
arcu.Curabitur@senectusetnetus.com arcu.Curabitur.senectusetnetus.com
ac@velit.ca ac.velit.ca
Aliquam.vulputate.ullamcorper@amalesuada.org Aliquam.vulputate.ullamcorper.amalesuada.org
vel.est@velitegestas.edu vel.est.velitegestas.edu
dolor.nonummy@ipsumdolorsit.ca dolor.nonummy.ipsumdolorsit.ca
et@Nunclaoreet.ca et.Nunclaoreet.ca
```
O seguinte exemplo substitui espaços por sublinhados e remove pontos finais de todos os valores em uma coluna:
```
select city, translate(city, ' .', '_') from users
where city like 'Sain%' or city like 'St%'
group by city
order by city;
city translate
--------------+------------------
Saint Albans Saint_Albans
Saint Cloud Saint_Cloud
Saint Joseph Saint_Joseph
Saint Louis Saint_Louis
Saint Paul Saint_Paul
St. George St_George
St. Marys St_Marys
St. Petersburg St_Petersburg
Stafford Stafford
Stamford Stamford
Stanton Stanton
Starkville Starkville
Statesboro Statesboro
Staunton Staunton
Steubenville Steubenville
Stevens Point Stevens_Point
Stillwater Stillwater
Stockton Stockton
Sturgis Sturgis
```
# Função TRIM
Apara uma string removendo os espaços em branco iniciais e finais ou removendo caracteres iniciais ou finais que correspondem a uma string opcional especificada.
## Sintaxe
```
TRIM( [ BOTH ] [ trim_chars FROM ] string
```
## Argumentos
*trim\$1chars*
(Opcional) Os caracteres a serem aparados da string. Se este parâmetro for omitido, espaços em branco serão aparados.
*string*
A string a ser aparada.
## Tipo de retorno
A função TRIM retorna uma string VARCHAR ou CHAR. Se você usar a função TRIM com um comando SQL, converte AWS Clean Rooms implicitamente os resultados em VARCHAR. Se você usar a função TRIM na lista SELECT para uma função SQL, AWS Clean Rooms isso não converte implicitamente os resultados e talvez seja necessário realizar uma conversão explícita para evitar um erro de incompatibilidade de tipos de dados. Consulte a [Função CAST](CAST_function.md) função para obter informações sobre conversões explícitas.
## Exemplo
O seguinte exemplo apara espaços em branco inicias e finais da string `' abc '`:
```
select ' abc ' as untrim, trim(' abc ') as trim;
untrim | trim
----------+------
abc | abc
```
O seguinte exemplo remove as aspas duplas que cercam a string `"dog"`:
```
select trim('"' FROM '"dog"');
btrim
-------
dog
```
TRIM remove qualquer um dos caracteres em *trim\$1chars* quando eles aparecem no início da *string*. O seguinte exemplo apara os caracteres “C”, “D” e “G” quando eles aparecem no início de VENUENAME, que é uma coluna VARCHAR.
```
select venueid, venuename, trim(venuename, 'CDG')
from venue
where venuename like '%Park'
order by 2
limit 7;
venueid | venuename | btrim
--------+----------------------------+--------------------------
121 | ATT Park | ATT Park
109 | Citizens Bank Park | itizens Bank Park
102 | Comerica Park | omerica Park
9 | Dick's Sporting Goods Park | ick's Sporting Goods Park
97 | Fenway Park | Fenway Park
112 | Great American Ball Park | reat American Ball Park
114 | Miller Park | Miller Park
```
# Função UPPER
Converte uma string em letras maiúsculas. UPPER é compatível com caracteres UTF-8 multibyte, até o máximo de quatro bytes por caractere.
## Sintaxe
```
UPPER(string)
```
## Argumentos
*string*
O parâmetro de entrada é uma string VARCHAR (ou qualquer outro tipo de dados, como CHAR, que pode ser convertido implicitamente para VARCHAR).
## Tipo de retorno
A função UPPER retorna uma string de caracteres que é o mesmo tipo de dados da string de entrada.
## Exemplos
O seguinte exemplo converte o campo CATNAME para maiúsculas:
```
select catname, upper(catname) from category order by 1,2;
catname | upper
----------+-----------
Classical | CLASSICAL
Jazz | JAZZ
MLB | MLB
MLS | MLS
Musicals | MUSICALS
NBA | NBA
NFL | NFL
NHL | NHL
Opera | OPERA
Plays | PLAYS
Pop | POP
(11 rows)
```
# Função UUID
A função UUID gera um Identificador Único Universal (UUID).
UUIDs são identificadores globais exclusivos que são comumente usados para fornecer identificadores exclusivos para várias finalidades, como:
+ Identificação de registros de banco de dados ou outras entidades de dados.
+ Gerando nomes ou chaves exclusivos para arquivos, diretórios ou outros recursos.
+ Rastreamento e correlação de dados em sistemas distribuídos.
+ Fornecendo identificadores exclusivos para pacotes de rede, componentes de software ou outros ativos digitais.
A função UUID gera um valor de UUID que é exclusivo com uma probabilidade muito alta, mesmo em sistemas distribuídos e por longos períodos de tempo. UUIDs normalmente são gerados usando uma combinação do timestamp atual, do endereço de rede do computador e outros dados aleatórios ou pseudo-aleatórios, garantindo que é altamente improvável que cada UUID gerado entre em conflito com qualquer outro UUID.
No contexto de uma consulta SQL, a função UUID pode ser usada para gerar identificadores exclusivos para novos registros inseridos em um banco de dados ou para fornecer chaves exclusivas para particionamento de dados, indexação ou outras finalidades em que um identificador exclusivo seja necessário.
**nota**
A função UUID não é determinística.
## Sintaxe
```
uuid()
```
## Argumentos
A função UUID não aceita argumentos.
## Tipo de retorno
O UUID retorna uma string de identificador exclusivo universal (UUID). O valor é retornado como uma string canônica de 36 caracteres do UUID.
## Exemplo
O exemplo a seguir gera um Identificador Único Universal (UUID). A saída é uma string de 36 caracteres representando um identificador universal exclusivo.
```
SELECT uuid();
46707d92-02f4-4817-8116-a4c3b23e6266
```
# Funções relacionadas à privacidade
AWS Clean Rooms fornece funções para ajudá-lo a cumprir a conformidade relacionada à privacidade com as seguintes especificações.
+ **Global Privacy Platform (GPP)** — Uma especificação do Interactive Advertising Bureau (IAB) que estabelece uma estrutura global e padronizada para privacidade on-line e uso de dados. Para obter mais informações sobre as especificações técnicas do GPP, consulte a [documentação da Global Privacy Platform em GitHub](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform).
+ **Estrutura de Transparência e Consentimento (TCF)** — Um componente essencial do GPP, lançado em 2020, que fornece uma estrutura técnica padronizada para ajudar as empresas a cumprir os regulamentos de privacidade, como o Regulamento Geral de Proteção de Dados (GDPR) da UE. O TCF permite que os clientes concedam ou neguem o consentimento para a coleta e processamento de dados. Para obter mais informações sobre as especificações técnicas do TCF, consulte a [documentação do TCF](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/tree/master/TCFv2) em. GitHub
**Topics**
+ [função consent\$1gpp\$1v1\$1decode](consent_gpp_v1_decode.md)
+ [função consent\$1tcf\$1v2\$1decode](consent_tcf_v2_decode.md)
# função consent\$1gpp\$1v1\$1decode
A `consent_gpp_v1_decode` função é usada para decodificar os dados de consentimento da Global Privacy Platform (GPP) v1. Ele usa a string de consentimento codificada como entrada e retorna os dados de consentimento decodificados, que incluem informações sobre as preferências de privacidade e as opções de consentimento do usuário. Essa função é útil ao trabalhar com dados que incluem informações de consentimento do GPP v1, pois permite acessar e analisar os dados de consentimento em um formato estruturado.
## Sintaxe
```
consent_gpp_v1_decode(gpp_string)
```
## Argumentos
*cadeia de caracteres gpp*
A string de consentimento codificada do GPP v1.
## Retornos
O dicionário retornado inclui os seguintes pares de valores-chave:
+ `version`: A versão da especificação GPP usada (atualmente 1).
+ `cmpId`: o ID da Plataforma de Gerenciamento de Consentimento (CMP) que codificou a sequência de caracteres de consentimento.
+ `cmpVersion`: a versão do CMP que codificou a sequência de caracteres de consentimento.
+ `consentScreen`: o ID da tela na interface do usuário do CMP em que o usuário forneceu consentimento.
+ `consentLanguage`: O código do idioma das informações de consentimento.
+ `vendorListVersion`: a versão da lista de fornecedores usada.
+ `publisherCountryCode`: O código do país da editora.
+ `purposeConsent`: uma lista de números inteiros representando as finalidades com as quais o usuário consentiu.
+ `purposeLegitimateInterest`: Uma lista de propósitos IDs para os quais o interesse legítimo do usuário foi comunicado de forma transparente.
+ `specialFeatureOptIns`: uma lista de números inteiros representando os recursos especiais pelos quais o usuário optou.
+ `vendorConsent`: uma lista de fornecedores com os IDs quais o usuário consentiu.
+ `vendorLegitimateInterest`: uma lista de fornecedores IDs para os quais o interesse legítimo do usuário foi comunicado de forma transparente.
## Exemplo
O exemplo a seguir usa um único argumento, que é a string de consentimento codificada. Ele retorna um dicionário contendo os dados de consentimento decodificados, incluindo informações sobre as preferências de privacidade do usuário, as opções de consentimento e outros metadados.
```
SELECT * FROM consent_gpp_v1_decode('ABCDEFGHIJK');
```
A estrutura básica dos dados de consentimento retornados inclui informações sobre a versão da cadeia de consentimento, os detalhes da CMP (Plataforma de Gerenciamento de Consentimento), o consentimento do usuário e as escolhas de interesse legítimo para diferentes finalidades e fornecedores e outros metadados.
```
{
"version": 1,
"cmpId": 12,
"cmpVersion": 34,
"consentScreen": 5,
"consentLanguage": "en",
"vendorListVersion": 89,
"publisherCountryCode": "US",
"purposeConsent": [1],
"purposeLegitimateInterests": [1],
"specialFeatureOptins": [1],
"vendorConsent": [1],
"vendorLegitimateInterests": [1]}
}
```
# função consent\$1tcf\$1v2\$1decode
A `consent_tcf_v2_decode` função é usada para decodificar os dados de consentimento do Transparency and Consent Framework (TCF) v2. Ele usa a string de consentimento codificada como entrada e retorna os dados de consentimento decodificados, que incluem informações sobre as preferências de privacidade e as opções de consentimento do usuário. Essa função é útil ao trabalhar com dados que incluem informações de consentimento do TCF v2, pois permite acessar e analisar os dados de consentimento em um formato estruturado.
## Sintaxe
```
consent_tcf_v2_decode(tcf_string)
```
## Argumentos
*string tcf*
A string de consentimento codificada do TCF v2.
## Retornos
A `consent_tcf_v2_decode` função retorna um dicionário contendo os dados de consentimento decodificados de uma string de consentimento do Transparency and Consent Framework (TCF) v2.
O dicionário retornado inclui os seguintes pares de valores-chave:
**Segmento principal**
+ `version`: A versão da especificação TCF usada (atualmente 2).
+ `created`: a data e a hora em que a sequência de consentimento foi criada.
+ `lastUpdated`: a data e a hora em que a sequência de consentimento foi atualizada pela última vez.
+ `cmpId`: o ID da Plataforma de Gerenciamento de Consentimento (CMP) que codificou a sequência de caracteres de consentimento.
+ `cmpVersion`: a versão do CMP que codificou a sequência de caracteres de consentimento.
+ `consentScreen`: o ID da tela na interface do usuário do CMP em que o usuário forneceu consentimento.
+ `consentLanguage`: O código do idioma das informações de consentimento.
+ `vendorListVersion`: a versão da lista de fornecedores usada.
+ `tcfPolicyVersion`: a versão da política do TCF na qual a string de consentimento se baseia.
+ `isServiceSpecific`: um valor booleano que indica se o consentimento é específico para um determinado serviço ou se aplica a todos os serviços.
+ `useNonStandardStacks`: um valor booleano que indica se pilhas não padrão são usadas.
+ `specialFeatureOptIns`: uma lista de números inteiros representando os recursos especiais pelos quais o usuário optou.
+ `purposeConsent`: uma lista de números inteiros representando as finalidades com as quais o usuário consentiu.
+ `purposesLITransparency`: uma lista de números inteiros representando as finalidades para as quais o usuário deu transparência aos interesses legítimos.
+ `purposeOneTreatment`: um valor booleano que indica se o usuário solicitou o “tratamento de propósito único” (ou seja, todos os propósitos são tratados igualmente).
+ `publisherCountryCode`: O código do país da editora.
+ `vendorConsent`: uma lista de fornecedores com os IDs quais o usuário consentiu.
+ `vendorLegitimateInterest`: uma lista de fornecedores IDs para os quais o interesse legítimo do usuário foi comunicado de forma transparente.
+ `pubRestrictionEntry`: Uma lista de restrições do editor. Esse campo contém a ID da finalidade, o tipo de restrição e a lista de fornecedores IDs sob essa restrição de finalidade.
**Segmento de fornecedores divulgado**
+ `disclosedVendors`: uma lista de números inteiros representando os fornecedores que foram divulgados ao usuário.
**Segmento de propósitos do editor**
+ `pubPurposesConsent`: uma lista de números inteiros representando as finalidades específicas do editor para as quais o usuário deu consentimento.
+ `pubPurposesLITransparency`: uma lista de números inteiros representando as finalidades específicas do editor para as quais o usuário deu transparência aos interesses legítimos.
+ `customPurposesConsent`: uma lista de números inteiros representando as finalidades personalizadas para as quais o usuário deu consentimento.
+ `customPurposesLITransparency`: uma lista de números inteiros representando as finalidades personalizadas para as quais o usuário deu transparência aos interesses legítimos.
Esses dados de consentimento detalhados podem ser usados para entender e respeitar as preferências de privacidade do usuário ao trabalhar com dados pessoais.
## Exemplo
O exemplo a seguir usa um único argumento, que é a string de consentimento codificada. Ele retorna um dicionário contendo os dados de consentimento decodificados, incluindo informações sobre as preferências de privacidade do usuário, as opções de consentimento e outros metadados.
```
from aws_clean_rooms.functions import consent_tcf_v2_decode
consent_string = "CO1234567890abcdef"
consent_data = consent_tcf_v2_decode(consent_string)
print(consent_data)
```
A estrutura básica dos dados de consentimento retornados inclui informações sobre a versão da cadeia de consentimento, os detalhes da CMP (Plataforma de Gerenciamento de Consentimento), o consentimento do usuário e as escolhas de interesse legítimo para diferentes finalidades e fornecedores e outros metadados.
```
/** core segment **/
version: 2,
created: "2023-10-01T12:00:00Z",
lastUpdated: "2023-10-01T12:00:00Z",
cmpId: 1234,
cmpVersion: 5,
consentScreen: 1,
consentLanguage: "en",
vendorListVersion: 2,
tcfPolicyVersion: 2,
isServiceSpecific: false,
useNonStandardStacks: false,
specialFeatureOptIns: [1, 2, 3],
purposeConsent: [1, 2, 3],
purposesLITransparency: [1, 2, 3],
purposeOneTreatment: true,
publisherCountryCode: "US",
vendorConsent: [1, 2, 3],
vendorLegitimateInterest: [1, 2, 3],
pubRestrictionEntry: [
{ purpose: 1, restrictionType: 2, restrictionDescription: "Example restriction" },
],
/** disclosed vendor segment **/
disclosedVendors: [1, 2, 3],
/** publisher purposes segment **/
pubPurposesConsent: [1, 2, 3],
pubPurposesLITransparency: [1, 2, 3],
customPurposesConsent: [1, 2, 3],
customPurposesLITransparency: [1, 2, 3],
};
```
# Funções de janela
Usando funções da janela, é possível criar consultas analíticas empresariais de forma mais eficiente. Funções de janela operam em uma partição ou “janela” de um conjunto de resultados e retornam um valor para cada linha naquela janela. Por outro lado, funções sem janela executam seus cálculos em relação a cada linha no conjunto de resultados. Diferente de funções de grupo que agregam linhas de resultado, as funções de janela retêm todas as linhas na expressão da tabela.
Os valores retornados são calculados usando valores dos conjuntos de linhas dessa janela. Para cada linha da tabela, a janela define um conjunto de linhas que é usado para computar atributos adicionais. Um janela é definida usando uma especificação de janela (a cláusula OVER) se baseia em três conceitos principais:
+ *Particionamento da janela,* que forma grupos de linhas (cláusula PARTITION)
+ *Ordenação da janela*, que define uma ordem ou sequência de linhas dentro de cada partição (cláusula ORDER BY)
+ *Quadros da janela*, que são definidos em relação a cada linha para restringir ainda mais o conjunto de linhas (especificação de ROWS)
As funções da janela são o último conjunto de operações executadas em uma consulta, exceto pela cláusula ORDER BY final. Todas as junções e todas as cláusulas WHERE, GROUP BY e HAVING são concluídas antes do processamento das funções da janela. Portanto, as funções da janela podem aparecer somente na lista de seleção ou na cláusula ORDER BY. Você pode usar várias funções da janela em uma única consulta com diferentes cláusulas de quadro. Você também pode usar funções da janela em outras expressões escalares, tal como CASE.
## Resumo da sintaxe de funções da janela
As funções de janela seguem uma sintaxe padrão, mostrada a seguir.
```
function (expression) OVER (
[ PARTITION BY expr_list ]
[ ORDER BY order_list [ frame_clause ] ] )
```
Aqui, *function* é uma das funções descritas nesta seção.
A *expr\$1list* é como indicado a seguir.
```
expression | column_name [, expr_list ]
```
A *order\$1list* é como a seguir.
```
expression | column_name [ ASC | DESC ]
[ NULLS FIRST | NULLS LAST ]
[, order_list ]
```
O *frame\$1clause* é como a seguir.
```
ROWS
{ UNBOUNDED PRECEDING | unsigned_value PRECEDING | CURRENT ROW } |
{ BETWEEN
{ UNBOUNDED PRECEDING | unsigned_value { PRECEDING | FOLLOWING } | CURRENT ROW}
AND
{ UNBOUNDED FOLLOWING | unsigned_value { PRECEDING | FOLLOWING } | CURRENT ROW }}
```
### Argumentos
*função*
A função de janela. Para obter detalhes, consulte as descrições individuais da função.
OVER
A cláusula que define a especificação da janela. A cláusula OVER é obrigatória para funções da janela e diferencia funções da janela de outras funções SQL.
PARTITION BY *expr\$1list*
(Opcional) A cláusula PARTITION BY subdivide o conjunto de resultados em partições, bem como a cláusula GROUP BY. Se uma cláusula de partição estiver presente, a função será calculada para as linhas em cada partição. Se nenhuma cláusula de partição estiver especificada, uma única partição contém a tabela inteira e a função é computada para esta tabela completa.
As funções de classificação DENSE\$1RANK, NTILE, RANK e ROW\$1NUMBER exigem uma comparação global de todas as linhas no conjunto de resultados. Quando uma cláusula PARTITION BY é utilizada, o otimizador de consulta pode executar cada agregação em paralelo, distribuindo a workload em várias fatias de acordo com as partições. Se a cláusula PARTITION BY não estiver presente, a etapa de agregação deverá ser executada em série em uma única fatia, o que poderá ter um impacto negativo considerável na performance, sobretudo para grandes clusters.
AWS Clean Roomsnão oferece suporte a literais de string nas cláusulas PARTITION BY.
ORDER BY *order\$1list*
(Opcional) A função da janela é aplicada às linhas dentro de cada partição classificada de acordo com a especificação do pedido em ORDER BY. Esta cláusula ORDER BY é diferente e totalmente não relacionada a uma cláusula ORDER BY na *frame\$1clause*. A cláusula ORDER BY pode ser usada sem a cláusula PARTITION BY.
Para as funções de classificação, a cláusula ORDER BY identifica as medidas para os valores de classificação. Para funções de agregação, as linhas particionadas devem ser ordenadas antes que a função agregada seja computada para cada quadro. Para obter mais informações sobre os tipos de função da janela, consulte [Funções de janela](#Window_functions).
Os identificadores de coluna ou expressões que avaliam os identificadores de coluna são obrigatórios na lista de ordenação. Nem constantes ou expressões constantes podem ser usadas como substitutos para nomes de coluna.
Valores NULL são tratados como seu próprio grupo, ordenados e classificados de acordo com a opção NULLS FIRST ou NULLS LAST. Por padrão, os valores NULL são ordenados e classificados por último na ordem ASC e são ordenados e classificados primeiro na ordem DESC.
AWS Clean Roomsnão oferece suporte a literais de string nas cláusulas ORDER BY.
Se a cláusula ORDER BY for omitida, a ordem das linhas não será determinística.
Em qualquer sistema paraleloAWS Clean Rooms, como quando uma cláusula ORDER BY não produz uma ordenação exclusiva e total dos dados, a ordem das linhas não é determinística. Ou seja, se a expressão ORDER BY produzir valores duplicados (uma ordenação parcial), a ordem de retorno dessas linhas poderá variar de uma sequência AWS Clean Rooms para outra. Por sua vez, funções da janela podem retornar resultados inesperados ou inconsistentes. Para obter mais informações, consulte [Ordenação exclusiva de dados para funções da janela](#Examples_order_by_WF).
*column\$1name*
Nome de uma coluna a ser particionada por ou ordenada por.
ASC \$1 DESC
Opção que define a ordem de classificação para a expressão, da seguinte forma:
+ ASC: ascendente (por exemplo, de valores numéricos menores para maiores e de "A" a "Z" para strings de caracteres). Se nenhuma opção é especificada, os dados são classificados na ordem ascendente por padrão.
+ DESC: descendente (de valores numéricos maiores para menores; de "Z" a "A" para strings).
NULLS FIRST \$1 NULLS LAST
Opção que especifica se NULLS devem ser ordenados primeiro, antes de valores não nulos, ou por último, após valores não nulos. Por padrão, NULLs são ordenados e classificados por último na ordem ASC e ordenados e classificados primeiro na ordem DESC.
*frame\$1clause*
Para funções agregadas, a cláusula do quadro refina ainda mais o conjunto de linhas na janela de uma função ao usar ORDER BY. Ele permite que você inclua ou exclua conjuntos de linhas no resultado ordenado. A cláusula de quadro consiste na palavra-chave ROWS e nos especificadores associados.
A cláusula frame não se aplica a funções de classificação. Além disso, a cláusula frame não é necessária quando nenhuma cláusula ORDER BY é usada na cláusula OVER para uma função agregada. Se uma cláusula ORDER BY é usada para uma função agregada, uma cláusula de quadro explícita é necessária.
Quando nenhuma cláusula ORDER BY é especificada, o quadro implícito é ilimitado, equivalente a ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING.
ROWS
Especificando um deslocamento físico da linha atual especificando um deslocamento físico da linha atual.
Essa cláusula especifica as linhas na janela ou particionamento atual ao qual o valor da linha atual dever ser combinado. Ela usa os argumentos que especificam a posição da linha, que pode ser antes ou depois da linha atual. O ponto de referência para todos os quadros de janela é a linha atual. Cada linha se torna a linha atual, por sua vez, à medida que o quadro de janela avança pela partição.
O quadro pode ser um conjunto simples de linhas até e incluindo a linha atual.
```
{UNBOUNDED PRECEDING | offset PRECEDING | CURRENT ROW}
```
Ou pode ser um conjunto de linhas entre dois limites.
```
BETWEEN
{ UNBOUNDED PRECEDING | offset { PRECEDING | FOLLOWING } | CURRENT ROW }
AND
{ UNBOUNDED FOLLOWING | offset { PRECEDING | FOLLOWING } | CURRENT ROW }
```
UNBOUNDED PRECEDING indica que a janela começa na primeira linha da partição; *deslocamento* PRECEDING indica que a janela começa um número de linhas equivalentes ao valor do deslocamento antes da linha atual. UNBOUNDED PRECEDING é o padrão.
CURRENT ROW indica que a janela começa ou termina na linha atual.
UNBOUNDED FOLLOWING indica que a janela termina na última linha da partição; *deslocamento* FOLLOWING indica que a janela termina um número de linhas equivalentes ao valor do deslocamento depois da linha atual.
O *offset* identifica um número físico de linhas antes ou depois da linha atual. Nesse caso, o *deslocamento* deve ser uma constante que retorna um valor numérico positivo. Por exemplo, 5 FOLLOWING termina o quadro 5 linhas após a linha atual.
Onde BETWEEN não é especificado, o quadro é limitado implicitamente pela linha atual. Por exemplo, `ROWS 5 PRECEDING` é igual a `ROWS BETWEEN 5 PRECEDING AND CURRENT ROW`. Além disso, `ROWS UNBOUNDED FOLLOWING` é igual a `ROWS BETWEEN CURRENT ROW AND UNBOUNDED FOLLOWING`.
Você não pode especificar um quadro em que o limite inicial seja maior do que o limite final. Por exemplo, você não pode especificar nenhum dos quadros a seguir.
```
between 5 following and 5 preceding
between current row and 2 preceding
between 3 following and current row
```
## Ordenação exclusiva de dados para funções da janela
Se uma cláusula ORDER BY para uma função da janela não produz uma ordem única e total dos dados, a ordem das linhas não é determinística. Se a expressão ORDER BY produzir valores duplicados (uma ordenação parcial), a ordem de retorno dessas linhas pode variar em várias execuções. Nesse caso, as funções da janela também podem retornar resultados inesperados ou inconsistentes.
Por exemplo, a consulta a seguir retorna resultados diferentes ao longo de várias execuções. Esses resultados diferentes ocorrem porque `order by dateid` não produz uma ordenação exclusiva dos dados para a função da janela SUM.
```
select dateid, pricepaid,
sum(pricepaid) over(order by dateid rows unbounded preceding) as sumpaid
from sales
group by dateid, pricepaid;
dateid | pricepaid | sumpaid
--------+-----------+-------------
1827 | 1730.00 | 1730.00
1827 | 708.00 | 2438.00
1827 | 234.00 | 2672.00
...
select dateid, pricepaid,
sum(pricepaid) over(order by dateid rows unbounded preceding) as sumpaid
from sales
group by dateid, pricepaid;
dateid | pricepaid | sumpaid
--------+-----------+-------------
1827 | 234.00 | 234.00
1827 | 472.00 | 706.00
1827 | 347.00 | 1053.00
...
```
Nesse caso, adicionar uma segunda coluna ORDER BY à função da janela pode resolver o problema.
```
select dateid, pricepaid,
sum(pricepaid) over(order by dateid, pricepaid rows unbounded preceding) as sumpaid
from sales
group by dateid, pricepaid;
dateid | pricepaid | sumpaid
--------+-----------+---------
1827 | 234.00 | 234.00
1827 | 337.00 | 571.00
1827 | 347.00 | 918.00
...
```
## Funções compatíveis
AWS Clean RoomsO Spark SQL suporta dois tipos de funções de janela: agregação e classificação.
Veja a seguir as funções agregadas compatíveis:
+ [Função de janela CUME\$1DIST](WF_CUME_DIST.md)
+ [Função de janela DENSE\$1RANK](WF_DENSE_RANK.md)
+ [Função FIRST window](WF_FIRST.md)
+ [Função de janela FIRST\$1VALUE](WF_first_value.md)
+ [Função de janela LAG](WF_LAG.md)
+ [Função LAST window](WF-LAST.md)
+ [Função de janela LAST\$1VALUE](WF_last_value.md)
+ [Função de janela LEAD](WF_LEAD.md)
Veja a seguir as funções de classificação compatíveis:
+ [Função de janela DENSE\$1RANK](WF_DENSE_RANK.md)
+ [Função de janela PERCENT\$1RANK](WF_PERCENT_RANK.md)
+ [Função de janela RANK](WF_RANK.md)
+ [Função de janela ROW\$1NUMBER](WF_ROW_NUMBER.md)
## Amostra de tabela para exemplos de funções de janela
É possível encontrar exemplos de função de janela específicos com cada descrição de função. Alguns dos exemplos usam uma tabela chamada WINSALES, que contém 11 linhas, conforme mostrado na tabela a seguir.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/clean-rooms/latest/sql-reference/Window_functions.html)
# Função de janela CUME\$1DIST
Calcula a distribuição cumulativa de um valor em uma janela ou partição. Assumindo uma ordem ascendente, a distribuição cumulativa é determinada usando esta fórmula:
`count of rows with values <= x / count of rows in the window or partition`
onde *x* é igual ao valor na linha atual da coluna especificada na cláusula ORDER BY. O seguinte conjunto de dados ilustra O uso desta fórmula:
```
Row# Value Calculation CUME_DIST
1 2500 (1)/(5) 0.2
2 2600 (2)/(5) 0.4
3 2800 (3)/(5) 0.6
4 2900 (4)/(5) 0.8
5 3100 (5)/(5) 1.0
```
O intervalo de valor de retorno é >0 a 1, inclusive.
## Sintaxe
```
CUME_DIST ()
OVER (
[ PARTITION BY partition_expression ]
[ ORDER BY order_list ]
)
```
## Argumentos
OVER
Uma cláusula que especifica o particionamento da janela. A cláusula OVER não pode conter uma especificação de quadro da janela.
PARTITION BY *partition\$1expression*
Opcional. Uma expressão que define o intervalo de registros para cada grupo na cláusula OVER.
ORDER BY *order\$1list*
A expressão na qual calcular a distribuição cumulativa. A expressão deve ter um tipo de dados numérico ou ser implicitamente conversível para um. Se ORDER BY for omitida, o valor de retorno será 1 para todas as linhas.
Se ORDER BY não produzir uma ordem única, a ordem das linhas não é determinística. Para obter mais informações, consulte [Ordenação exclusiva de dados para funções da janela](Window_functions.md#Examples_order_by_WF).
## Tipo de retorno
FLOAT8
## Exemplos
O seguinte exemplo calcula a distribuição cumulativa da quantidade para cada vendedor:
```
select sellerid, qty, cume_dist()
over (partition by sellerid order by qty)
from winsales;
sellerid qty cume_dist
--------------------------------------------------
1 10.00 0.33
1 10.64 0.67
1 30.37 1
3 10.04 0.25
3 15.15 0.5
3 20.75 0.75
3 30.55 1
2 20.09 0.5
2 20.12 1
4 10.12 0.5
4 40.23 1
```
Para uma descrição da tabela WINSALES, consulte [Amostra de tabela para exemplos de funções de janela](Window_functions.md#Window_function_example).
# Função de janela DENSE\$1RANK
A função de janela DENSE\$1RANK determina a classificação de um valor em um grupo de valores com base na expressão ORDER BY da cláusula OVER. Se a cláusula opcional PARTITION BY estiver presente, as classificações são redefinidas para cada grupo de linhas. Linhas com valores iguais para os critérios de classificação recebem a mesma classificação. A função DENSE\$1RANK difere de RANK em um aspecto: se duas ou mais linhas empatarem, não há uma lacuna na sequência de valores classificados. Por exemplo, se duas linhas são classificadas como 1, a classificação seguinte é 2.
Você pode ter funções de classificação com diferentes cláusulas PARTITION BY e ORDER BY na mesma consulta.
## Sintaxe
```
DENSE_RANK () OVER
(
[ PARTITION BY expr_list ]
[ ORDER BY order_list ]
)
```
## Argumentos
( )
A função não aceita argumentos, mas os parênteses vazios são necessários.
OVER
As cláusulas de janela para a função DENSE\$1RANK.
PARTITION BY *expr\$1list*
Opcional. Uma ou várias expressões que definem a janela.
ORDER BY *order\$1list*
Opcional. A expressão na qual os valores de classificação se baseiam. Se nenhuma PARTITION BY for especificada, ORDER BY usa a tabela completa. Se ORDER BY for omitida, o valor de retorno será 1 para todas as linhas.
Se ORDER BY não produzir uma ordem única, a ordem das linhas não é determinística. Para obter mais informações, consulte [Ordenação exclusiva de dados para funções da janela](Window_functions.md#Examples_order_by_WF).
## Tipo de retorno
INTEGER
## Exemplos
O exemplo a seguir ordena a mesa pela quantidade vendida (em ordem decrescente) e atribui uma classificação densa e uma classificação regular a cada linha. Os resultados são classificados após a aplicação dos resultados da função de janela.
```
select salesid, qty,
dense_rank() over(order by qty desc) as d_rnk,
rank() over(order by qty desc) as rnk
from winsales
order by 2,1;
salesid | qty | d_rnk | rnk
---------+-----+-------+-----
10001 | 10 | 5 | 8
10006 | 10 | 5 | 8
30001 | 10 | 5 | 8
40005 | 10 | 5 | 8
30003 | 15 | 4 | 7
20001 | 20 | 3 | 4
20002 | 20 | 3 | 4
30004 | 20 | 3 | 4
10005 | 30 | 2 | 2
30007 | 30 | 2 | 2
40001 | 40 | 1 | 1
(11 rows)
```
Observe a diferença nas classificações atribuídas ao mesmo conjunto de linhas quando as funções DENSE\$1RANK e RANK são usadas lado a lado na mesma consulta. Para uma descrição da tabela WINSALES, consulte [Amostra de tabela para exemplos de funções de janela](Window_functions.md#Window_function_example).
O exemplo a seguir particiona a tabela por SELLERID e ordena cada partição pela quantidade (em ordem decrescente) e atribui uma classificação densa a cada linha. Os resultados são classificados após a aplicação dos resultados da função de janela.
```
select salesid, sellerid, qty,
dense_rank() over(partition by sellerid order by qty desc) as d_rnk
from winsales
order by 2,3,1;
salesid | sellerid | qty | d_rnk
---------+----------+-----+-------
10001 | 1 | 10 | 2
10006 | 1 | 10 | 2
10005 | 1 | 30 | 1
20001 | 2 | 20 | 1
20002 | 2 | 20 | 1
30001 | 3 | 10 | 4
30003 | 3 | 15 | 3
30004 | 3 | 20 | 2
30007 | 3 | 30 | 1
40005 | 4 | 10 | 2
40001 | 4 | 40 | 1
(11 rows)
```
Para uma descrição da tabela WINSALES, consulte [Amostra de tabela para exemplos de funções de janela](Window_functions.md#Window_function_example).
# Função FIRST window
Dado um conjunto ordenado de linhas, FIRST retorna o valor da expressão especificada em relação à primeira linha na moldura da janela.
Para obter informações sobre como selecionar a última linha no quadro, consulte [Função LAST window](WF-LAST.md).
## Sintaxe
```
FIRST( expression )[ IGNORE NULLS | RESPECT NULLS ]
OVER (
[ PARTITION BY expr_list ]
[ ORDER BY order_list frame_clause ]
)
```
## Argumentos
*expressão*
A coluna ou expressão de destino na qual a função opera.
IGNORE NULLS
Quando essa opção é usada com FIRST, a função retorna o primeiro valor no quadro que não é NULL (ou NULL se todos os valores forem NULL).
RESPECT NULLS
Indica que AWS Clean Rooms deve incluir valores nulos na determinação de qual linha usar. RESPECT NULLS é compatível por padrão se você não especificar IGNORE NULLS.
OVER
Introduz as cláusulas de janela para a função.
PARTITION BY *expr\$1list*
Define a janela para a função em termos de uma ou mais expressões.
ORDER BY *order\$1list*
Classifica as linhas dentro de cada partição. Se nenhuma cláusula PARTITION BY for especificada, ORDER BY classifica a tabela inteira. Se você especificar uma cláusula ORDER BY, você também deve especificar uma *frame\$1clause*.
Os resultados da função FIRST dependem da ordem dos dados. Os resultados são não determinísticos nos seguintes casos:
+ Quando uma cláusula ORDER BY é especificada e uma partição contém dois valores diferentes para uma expressão
+ Quando uma expressão avalia para valores diferentes que correspondem ao mesmo valor na lista ORDER BY.
*frame\$1clause*
Se uma cláusula ORDER BY é usada para uma função agregada, uma cláusula de quadro explícita é necessária. A cláusula de quadro refina o conjunto de linhas na janela de uma função, incluindo ou excluindo conjuntos de linhas no resultado ordenado. A cláusula de quadro consiste na palavra-chave ROWS e nos especificadores associados. Consulte [Resumo da sintaxe de funções da janela](Window_functions.md#Window_function_synopsis).
## Tipo de retorno
Essas funções oferecem suporte a expressões que usam tipos de AWS Clean Rooms dados primitivos. O tipo de retorno é igual ao tipo de dados da *expressão*.
## Exemplos
O seguinte exemplo retorna a capacidade de acomodação para cada local de evento da tabela VENUE com os resultados ordenados por capacidade (alta a baixa). A função FIRST é usada para selecionar o nome do local que corresponde à primeira fila no quadro: nesse caso, a fila com o maior número de assentos. Os resultados são particionados por estado, portanto quando o valor VENUESTATE muda, um novo primeiro valor é selecionado. O quadro da janela não é vinculado, portanto o mesmo primeiro valor é selecionado para cada linha em cada partição.
Para a Califórnia, `Qualcomm Stadium` tem mais alto número de assentos (`70561`), portanto esse nome é o primeiro valor para todas as linhas da partição `CA`.
```
select venuestate, venueseats, venuename,
first(venuename)
over(partition by venuestate
order by venueseats desc
rows between unbounded preceding and unbounded following)
from (select * from venue where venueseats >0)
order by venuestate;
venuestate | venueseats | venuename | first
-----------+------------+--------------------------------+------------------------------
CA | 70561 | Qualcomm Stadium | Qualcomm Stadium
CA | 69843 | Monster Park | Qualcomm Stadium
CA | 63026 | McAfee Coliseum | Qualcomm Stadium
CA | 56000 | Dodger Stadium | Qualcomm Stadium
CA | 45050 | Angel Stadium of Anaheim | Qualcomm Stadium
CA | 42445 | PETCO Park | Qualcomm Stadium
CA | 41503 | AT&T Park | Qualcomm Stadium
CA | 22000 | Shoreline Amphitheatre | Qualcomm Stadium
CO | 76125 | INVESCO Field | INVESCO Field
CO | 50445 | Coors Field | INVESCO Field
DC | 41888 | Nationals Park | Nationals Park
FL | 74916 | Dolphin Stadium | Dolphin Stadium
FL | 73800 | Jacksonville Municipal Stadium | Dolphin Stadium
FL | 65647 | Raymond James Stadium | Dolphin Stadium
FL | 36048 | Tropicana Field | Dolphin Stadium
...
```
# Função de janela FIRST\$1VALUE
Considerando um conjunto de linhas ordenado, FIRST\$1VALUE retorna o valor da expressão especificada em relação à primeira linha no quadro de janela.
Para obter informações sobre como selecionar a última linha no quadro, consulte [Função de janela LAST\$1VALUE](WF_last_value.md).
## Sintaxe
```
FIRST_VALUE( expression )[ IGNORE NULLS | RESPECT NULLS ]
OVER (
[ PARTITION BY expr_list ]
[ ORDER BY order_list frame_clause ]
)
```
## Argumentos
*expressão*
A coluna ou expressão de destino na qual a função opera.
IGNORE NULLS
Quando essa opção é usada com FIRST\$1VALUE, a função retorna o primeiro valor no quadro que não seja NULL (ou NULL se todos os valores forem NULL).
RESPECT NULLS
Indica que AWS Clean Rooms deve incluir valores nulos na determinação de qual linha usar. RESPECT NULLS é compatível por padrão se você não especificar IGNORE NULLS.
OVER
Introduz as cláusulas de janela para a função.
PARTITION BY *expr\$1list*
Define a janela para a função em termos de uma ou mais expressões.
ORDER BY *order\$1list*
Classifica as linhas dentro de cada partição. Se nenhuma cláusula PARTITION BY for especificada, ORDER BY classifica a tabela inteira. Se você especificar uma cláusula ORDER BY, você também deve especificar uma *frame\$1clause*.
Os resultados da função FIRST\$1VALUE dependem da ordem dos dados. Os resultados são não determinísticos nos seguintes casos:
+ Quando uma cláusula ORDER BY é especificada e uma partição contém dois valores diferentes para uma expressão
+ Quando uma expressão avalia para valores diferentes que correspondem ao mesmo valor na lista ORDER BY.
*frame\$1clause*
Se uma cláusula ORDER BY é usada para uma função agregada, uma cláusula de quadro explícita é necessária. A cláusula de quadro refina o conjunto de linhas na janela de uma função, incluindo ou excluindo conjuntos de linhas no resultado ordenado. A cláusula de quadro consiste na palavra-chave ROWS e nos especificadores associados. Consulte [Resumo da sintaxe de funções da janela](Window_functions.md#Window_function_synopsis).
## Tipo de retorno
Essas funções oferecem suporte a expressões que usam tipos de AWS Clean Rooms dados primitivos. O tipo de retorno é igual ao tipo de dados da *expressão*.
## Exemplos
O seguinte exemplo retorna a capacidade de acomodação para cada local de evento da tabela VENUE com os resultados ordenados por capacidade (alta a baixa). A função FIRST\$1VALUE é usada para selecionar o local de evento que corresponde à primeira linha no quadro: nesse caso, a linha com o mais alto número de assentos. Os resultados são particionados por estado, portanto quando o valor VENUESTATE muda, um novo primeiro valor é selecionado. O quadro da janela não é vinculado, portanto o mesmo primeiro valor é selecionado para cada linha em cada partição.
Para a Califórnia, `Qualcomm Stadium` tem mais alto número de assentos (`70561`), portanto esse nome é o primeiro valor para todas as linhas da partição `CA`.
```
select venuestate, venueseats, venuename,
first_value(venuename)
over(partition by venuestate
order by venueseats desc
rows between unbounded preceding and unbounded following)
from (select * from venue where venueseats >0)
order by venuestate;
venuestate | venueseats | venuename | first_value
-----------+------------+--------------------------------+------------------------------
CA | 70561 | Qualcomm Stadium | Qualcomm Stadium
CA | 69843 | Monster Park | Qualcomm Stadium
CA | 63026 | McAfee Coliseum | Qualcomm Stadium
CA | 56000 | Dodger Stadium | Qualcomm Stadium
CA | 45050 | Angel Stadium of Anaheim | Qualcomm Stadium
CA | 42445 | PETCO Park | Qualcomm Stadium
CA | 41503 | AT&T Park | Qualcomm Stadium
CA | 22000 | Shoreline Amphitheatre | Qualcomm Stadium
CO | 76125 | INVESCO Field | INVESCO Field
CO | 50445 | Coors Field | INVESCO Field
DC | 41888 | Nationals Park | Nationals Park
FL | 74916 | Dolphin Stadium | Dolphin Stadium
FL | 73800 | Jacksonville Municipal Stadium | Dolphin Stadium
FL | 65647 | Raymond James Stadium | Dolphin Stadium
FL | 36048 | Tropicana Field | Dolphin Stadium
...
```
# Função de janela LAG
A função de janela LAG retorna os valores para uma linha em determinado deslocamento acima (antes) da linha atual na partição.
## Sintaxe
```
LAG (value_expr [, offset ])
[ IGNORE NULLS | RESPECT NULLS ]
OVER ( [ PARTITION BY window_partition ] ORDER BY window_ordering )
```
## Argumentos
*value\$1expr*
A coluna ou expressão de destino na qual a função opera.
*deslocamento*
Um parâmetro opcional que especifica o número de linhas antes da linha atual para as quais retornar valores. Este deslocamento pode ser um inteiro constante ou uma expressão que avalia para um inteiro. Se você não especificar um deslocamento, AWS Clean Rooms usa `1` como valor padrão. Um deslocamento de `0` indica a linha atual.
IGNORE NULLS
Uma especificação opcional que indica que os valores nulos AWS Clean Rooms devem ser ignorados na determinação de qual linha usar. Valores nulos são incluídos se IGNORE NULLS não for listada.
Você pode usar uma expressão NVL ou COALESCE para substituir os valores nulos por outro valor.
RESPECT NULLS
Indica que AWS Clean Rooms deve incluir valores nulos na determinação de qual linha usar. RESPECT NULLS é compatível por padrão se você não especificar IGNORE NULLS.
OVER
Especifica o particionamento e ordem da janela. A cláusula OVER não pode conter uma especificação de quadro da janela.
PARTITION BY *window\$1partition*
Um argumento ideal que define o intervalo de registros para cada grupo na cláusula OVER.
ORDER BY *window\$1ordering*
Classifica as linhas dentro de cada partição.
A função de janela LAG suporta expressões que usam qualquer um dos tipos de AWS Clean Rooms dados. O tipo de retorno é igual ao tipo de *value\$1expr*.
## Exemplos
O seguinte exemplo mostra a quantidade de ingressos vendidos para o comprador com ID de comprador 3 e a hora que o comprador 3 adquiriu os ingressos. Para comparar cada venda com venda anterior para o comprador 3, a consulta retorna a quantidade anterior vendida em cada venda. Já que não há compras antes de 1/16/2008, o primeiro valor de quantidade vendida anteriormente é nulo:
```
select buyerid, saletime, qtysold,
lag(qtysold,1) over (order by buyerid, saletime) as prev_qtysold
from sales where buyerid = 3 order by buyerid, saletime;
buyerid | saletime | qtysold | prev_qtysold
---------+---------------------+---------+--------------
3 | 2008-01-16 01:06:09 | 1 |
3 | 2008-01-28 02:10:01 | 1 | 1
3 | 2008-03-12 10:39:53 | 1 | 1
3 | 2008-03-13 02:56:07 | 1 | 1
3 | 2008-03-29 08:21:39 | 2 | 1
3 | 2008-04-27 02:39:01 | 1 | 2
3 | 2008-08-16 07:04:37 | 2 | 1
3 | 2008-08-22 11:45:26 | 2 | 2
3 | 2008-09-12 09:11:25 | 1 | 2
3 | 2008-10-01 06:22:37 | 1 | 1
3 | 2008-10-20 01:55:51 | 2 | 1
3 | 2008-10-28 01:30:40 | 1 | 2
(12 rows)
```
# Função LAST window
Dado um conjunto ordenado de linhas, a função LAST retorna o valor da expressão em relação à última linha no quadro.
Para obter informações sobre como selecionar a primeira linha no quadro, consulte [Função FIRST window](WF_FIRST.md).
## Sintaxe
```
LAST( expression )[ IGNORE NULLS | RESPECT NULLS ]
OVER (
[ PARTITION BY expr_list ]
[ ORDER BY order_list frame_clause ]
)
```
## Argumentos
*expressão*
A coluna ou expressão de destino na qual a função opera.
IGNORE NULLS
A função retorna o último valor no quadro que não seja NULL (ou NULL se todos os valores forem NULL).
RESPECT NULLS
Indica que AWS Clean Rooms deve incluir valores nulos na determinação de qual linha usar. RESPECT NULLS é compatível por padrão se você não especificar IGNORE NULLS.
OVER
Introduz as cláusulas de janela para a função.
PARTITION BY *expr\$1list*
Define a janela para a função em termos de uma ou mais expressões.
ORDER BY *order\$1list*
Classifica as linhas dentro de cada partição. Se nenhuma cláusula PARTITION BY for especificada, ORDER BY classifica a tabela inteira. Se você especificar uma cláusula ORDER BY, você também deve especificar uma *frame\$1clause*.
Os resultados dependem da ordem dos dados. Os resultados são não determinísticos nos seguintes casos:
+ Quando uma cláusula ORDER BY é especificada e uma partição contém dois valores diferentes para uma expressão
+ Quando uma expressão avalia para valores diferentes que correspondem ao mesmo valor na lista ORDER BY.
*frame\$1clause*
Se uma cláusula ORDER BY é usada para uma função agregada, uma cláusula de quadro explícita é necessária. A cláusula de quadro refina o conjunto de linhas na janela de uma função, incluindo ou excluindo conjuntos de linhas no resultado ordenado. A cláusula de quadro consiste na palavra-chave ROWS e nos especificadores associados. Consulte [Resumo da sintaxe de funções da janela](Window_functions.md#Window_function_synopsis).
## Tipo de retorno
Essas funções oferecem suporte a expressões que usam tipos de AWS Clean Rooms dados primitivos. O tipo de retorno é igual ao tipo de dados da *expressão*.
## Exemplos
O seguinte exemplo retorna a capacidade de acomodação para cada local de evento da tabela VENUE com os resultados ordenados por capacidade (alta a baixa). A função LAST é usada para selecionar o nome do local que corresponde à última linha no quadro: nesse caso, a linha com o menor número de assentos. Os resultados são particionados por estado, portanto quando o valor VENUESTATE muda, um novo último valor é selecionado. O quadro da janela não é vinculado, portanto o mesmo último valor é selecionado para cada linha em cada partição.
Para a Califórnia, `Shoreline Amphitheatre` será retornado para cada linha na partição, pois tem o menor número de assentos (`22000`).
```
select venuestate, venueseats, venuename,
last(venuename)
over(partition by venuestate
order by venueseats desc
rows between unbounded preceding and unbounded following)
from (select * from venue where venueseats >0)
order by venuestate;
venuestate | venueseats | venuename | last
-----------+------------+--------------------------------+------------------------------
CA | 70561 | Qualcomm Stadium | Shoreline Amphitheatre
CA | 69843 | Monster Park | Shoreline Amphitheatre
CA | 63026 | McAfee Coliseum | Shoreline Amphitheatre
CA | 56000 | Dodger Stadium | Shoreline Amphitheatre
CA | 45050 | Angel Stadium of Anaheim | Shoreline Amphitheatre
CA | 42445 | PETCO Park | Shoreline Amphitheatre
CA | 41503 | AT&T Park | Shoreline Amphitheatre
CA | 22000 | Shoreline Amphitheatre | Shoreline Amphitheatre
CO | 76125 | INVESCO Field | Coors Field
CO | 50445 | Coors Field | Coors Field
DC | 41888 | Nationals Park | Nationals Park
FL | 74916 | Dolphin Stadium | Tropicana Field
FL | 73800 | Jacksonville Municipal Stadium | Tropicana Field
FL | 65647 | Raymond James Stadium | Tropicana Field
FL | 36048 | Tropicana Field | Tropicana Field
...
```
# Função de janela LAST\$1VALUE
Considerando um conjunto de linhas ordenadas, a função LAST\$1VALUE retorna o valor da expressão em relação à última linha no quadro.
Para obter informações sobre como selecionar a primeira linha no quadro, consulte [Função de janela FIRST\$1VALUE](WF_first_value.md).
## Sintaxe
```
LAST_VALUE( expression )[ IGNORE NULLS | RESPECT NULLS ]
OVER (
[ PARTITION BY expr_list ]
[ ORDER BY order_list frame_clause ]
)
```
## Argumentos
*expressão*
A coluna ou expressão de destino na qual a função opera.
IGNORE NULLS
A função retorna o último valor no quadro que não seja NULL (ou NULL se todos os valores forem NULL).
RESPECT NULLS
Indica que AWS Clean Rooms deve incluir valores nulos na determinação de qual linha usar. RESPECT NULLS é compatível por padrão se você não especificar IGNORE NULLS.
OVER
Introduz as cláusulas de janela para a função.
PARTITION BY *expr\$1list*
Define a janela para a função em termos de uma ou mais expressões.
ORDER BY *order\$1list*
Classifica as linhas dentro de cada partição. Se nenhuma cláusula PARTITION BY for especificada, ORDER BY classifica a tabela inteira. Se você especificar uma cláusula ORDER BY, você também deve especificar uma *frame\$1clause*.
Os resultados dependem da ordem dos dados. Os resultados são não determinísticos nos seguintes casos:
+ Quando uma cláusula ORDER BY é especificada e uma partição contém dois valores diferentes para uma expressão
+ Quando uma expressão avalia para valores diferentes que correspondem ao mesmo valor na lista ORDER BY.
*frame\$1clause*
Se uma cláusula ORDER BY é usada para uma função agregada, uma cláusula de quadro explícita é necessária. A cláusula de quadro refina o conjunto de linhas na janela de uma função, incluindo ou excluindo conjuntos de linhas no resultado ordenado. A cláusula de quadro consiste na palavra-chave ROWS e nos especificadores associados. Consulte [Resumo da sintaxe de funções da janela](Window_functions.md#Window_function_synopsis).
## Tipo de retorno
Essas funções oferecem suporte a expressões que usam tipos de AWS Clean Rooms dados primitivos. O tipo de retorno é igual ao tipo de dados da *expressão*.
## Exemplos
O seguinte exemplo retorna a capacidade de acomodação para cada local de evento da tabela VENUE com os resultados ordenados por capacidade (alta a baixa). A função LAST\$1VALUE é usada para selecionar o local de evento que corresponde à última linha no quadro: nesse caso, a linha com o mais baixo número de assentos. Os resultados são particionados por estado, portanto quando o valor VENUESTATE muda, um novo último valor é selecionado. O quadro da janela não é vinculado, portanto o mesmo último valor é selecionado para cada linha em cada partição.
Para a Califórnia, `Shoreline Amphitheatre` será retornado para cada linha na partição, pois tem o menor número de assentos (`22000`).
```
select venuestate, venueseats, venuename,
last_value(venuename)
over(partition by venuestate
order by venueseats desc
rows between unbounded preceding and unbounded following)
from (select * from venue where venueseats >0)
order by venuestate;
venuestate | venueseats | venuename | last_value
-----------+------------+--------------------------------+------------------------------
CA | 70561 | Qualcomm Stadium | Shoreline Amphitheatre
CA | 69843 | Monster Park | Shoreline Amphitheatre
CA | 63026 | McAfee Coliseum | Shoreline Amphitheatre
CA | 56000 | Dodger Stadium | Shoreline Amphitheatre
CA | 45050 | Angel Stadium of Anaheim | Shoreline Amphitheatre
CA | 42445 | PETCO Park | Shoreline Amphitheatre
CA | 41503 | AT&T Park | Shoreline Amphitheatre
CA | 22000 | Shoreline Amphitheatre | Shoreline Amphitheatre
CO | 76125 | INVESCO Field | Coors Field
CO | 50445 | Coors Field | Coors Field
DC | 41888 | Nationals Park | Nationals Park
FL | 74916 | Dolphin Stadium | Tropicana Field
FL | 73800 | Jacksonville Municipal Stadium | Tropicana Field
FL | 65647 | Raymond James Stadium | Tropicana Field
FL | 36048 | Tropicana Field | Tropicana Field
...
```
# Função de janela LEAD
A função de janela LEAD retorna os valores para uma linha em determinado deslocamento abaixo (depois) da linha atual na partição.
## Sintaxe
```
LEAD (value_expr [, offset ])
[ IGNORE NULLS | RESPECT NULLS ]
OVER ( [ PARTITION BY window_partition ] ORDER BY window_ordering )
```
## Argumentos
*value\$1expr*
A coluna ou expressão de destino na qual a função opera.
*deslocamento*
Um parâmetro opcional que especifica o número de linhas abaixo da linha atual para as quais retornar valores. Este deslocamento pode ser um inteiro constante ou uma expressão que avalia para um inteiro. Se você não especificar um deslocamento, AWS Clean Rooms usa `1` como valor padrão. Um deslocamento de `0` indica a linha atual.
IGNORE NULLS
Uma especificação opcional que indica que os valores nulos AWS Clean Rooms devem ser ignorados na determinação de qual linha usar. Valores nulos são incluídos se IGNORE NULLS não for listada.
Você pode usar uma expressão NVL ou COALESCE para substituir os valores nulos por outro valor.
RESPECT NULLS
Indica que AWS Clean Rooms deve incluir valores nulos na determinação de qual linha usar. RESPECT NULLS é compatível por padrão se você não especificar IGNORE NULLS.
OVER
Especifica o particionamento e ordem da janela. A cláusula OVER não pode conter uma especificação de quadro da janela.
PARTITION BY *window\$1partition*
Um argumento ideal que define o intervalo de registros para cada grupo na cláusula OVER.
ORDER BY *window\$1ordering*
Classifica as linhas dentro de cada partição.
A função de janela LEAD oferece suporte a expressões que usam qualquer um dos tipos de AWS Clean Rooms dados. O tipo de retorno é igual ao tipo de *value\$1expr*.
## Exemplos
O seguinte exemplo fornece a comissão para eventos na tabela SALES para os quais ingressos foram vendidos em 1º de janeiro de 2008 e 2 de janeiro de 2008, assim como a comissão paga por vendas de ingressos para a venda subsequente.
```
select eventid, commission, saletime,
lead(commission, 1) over (order by saletime) as next_comm
from sales where saletime between '2008-01-01 00:00:00' and '2008-01-02 12:59:59'
order by saletime;
eventid | commission | saletime | next_comm
---------+------------+---------------------+-----------
6213 | 52.05 | 2008-01-01 01:00:19 | 106.20
7003 | 106.20 | 2008-01-01 02:30:52 | 103.20
8762 | 103.20 | 2008-01-01 03:50:02 | 70.80
1150 | 70.80 | 2008-01-01 06:06:57 | 50.55
1749 | 50.55 | 2008-01-01 07:05:02 | 125.40
8649 | 125.40 | 2008-01-01 07:26:20 | 35.10
2903 | 35.10 | 2008-01-01 09:41:06 | 259.50
6605 | 259.50 | 2008-01-01 12:50:55 | 628.80
6870 | 628.80 | 2008-01-01 12:59:34 | 74.10
6977 | 74.10 | 2008-01-02 01:11:16 | 13.50
4650 | 13.50 | 2008-01-02 01:40:59 | 26.55
4515 | 26.55 | 2008-01-02 01:52:35 | 22.80
5465 | 22.80 | 2008-01-02 02:28:01 | 45.60
5465 | 45.60 | 2008-01-02 02:28:02 | 53.10
7003 | 53.10 | 2008-01-02 02:31:12 | 70.35
4124 | 70.35 | 2008-01-02 03:12:50 | 36.15
1673 | 36.15 | 2008-01-02 03:15:00 | 1300.80
...
(39 rows)
```
# Função de janela PERCENT\$1RANK
Calcula a classificação percentual de dada linha. A classificação percentual é determinada usando esta fórmula:
`(x - 1) / (the number of rows in the window or partition - 1)`
onde *x* é a classificação da linha atual. O seguinte conjunto de dados ilustra O uso desta fórmula:
```
Row# Value Rank Calculation PERCENT_RANK
1 15 1 (1-1)/(7-1) 0.0000
2 20 2 (2-1)/(7-1) 0.1666
3 20 2 (2-1)/(7-1) 0.1666
4 20 2 (2-1)/(7-1) 0.1666
5 30 5 (5-1)/(7-1) 0.6666
6 30 5 (5-1)/(7-1) 0.6666
7 40 7 (7-1)/(7-1) 1.0000
```
O intervalo de valor de retorno é 0 a 1, inclusive. A primeira linha em qualquer conjunto tem um PERCENT\$1RANK de 0.
## Sintaxe
```
PERCENT_RANK ()
OVER (
[ PARTITION BY partition_expression ]
[ ORDER BY order_list ]
)
```
## Argumentos
( )
A função não aceita argumentos, mas os parênteses vazios são necessários.
OVER
Uma cláusula que especifica o particionamento da janela. A cláusula OVER não pode conter uma especificação de quadro da janela.
PARTITION BY *partition\$1expression*
Opcional. Uma expressão que define o intervalo de registros para cada grupo na cláusula OVER.
ORDER BY *order\$1list*
Opcional. A expressão na qual calcular a classificação percentual. A expressão deve ter um tipo de dados numérico ou ser implicitamente conversível para um. Se ORDER BY for omitida, o valor de retorno será 0 para todas as linhas.
Se ORDER BY não produzir uma ordenação exclusiva, a ordem das linhas será não determinística. Para obter mais informações, consulte [Ordenação exclusiva de dados para funções da janela](Window_functions.md#Examples_order_by_WF).
## Tipo de retorno
FLOAT8
## Exemplos
O seguinte exemplo calcula a classificação percentual das quantidades de vendas para cada vendedor:
```
select sellerid, qty, percent_rank()
over (partition by sellerid order by qty)
from winsales;
sellerid qty percent_rank
----------------------------------------
1 10.00 0.0
1 10.64 0.5
1 30.37 1.0
3 10.04 0.0
3 15.15 0.33
3 20.75 0.67
3 30.55 1.0
2 20.09 0.0
2 20.12 1.0
4 10.12 0.0
4 40.23 1.0
```
Para uma descrição da tabela WINSALES, consulte [Amostra de tabela para exemplos de funções de janela](Window_functions.md#Window_function_example).
# Função de janela RANK
A função de janela RANK determina a classificação de um valor em um grupo de valores com base na expressão ORDER BY da cláusula OVER. Se a cláusula opcional PARTITION BY estiver presente, as classificações são redefinidas para cada grupo de linhas. As linhas com valores iguais para os critérios de classificação recebem a mesma classificação. AWS Clean Roomsadiciona o número de linhas empatadas à classificação empatada para calcular a próxima classificação e, portanto, as classificações podem não ser números consecutivos. Por exemplo, se duas linhas são classificadas como 1, a classificação seguinte é 3.
RANK difere de [Função de janela DENSE\$1RANK](WF_DENSE_RANK.md) em um aspecto: para DENSE\$1RANK, se duas ou mais linhas empatarem, não há uma lacuna na sequência de valores classificados. Por exemplo, se duas linhas são classificadas como 1, a classificação seguinte é 2.
Você pode ter funções de classificação com diferentes cláusulas PARTITION BY e ORDER BY na mesma consulta.
## Sintaxe
```
RANK () OVER
(
[ PARTITION BY expr_list ]
[ ORDER BY order_list ]
)
```
## Argumentos
( )
A função não aceita argumentos, mas os parênteses vazios são necessários.
OVER
As cláusulas de janela para a função RANK.
PARTITION BY *expr\$1list*
Opcional. Uma ou várias expressões que definem a janela.
ORDER BY *order\$1list*
Opcional. Define as colunas nas quais os valores de classificação se baseiam. Se nenhuma PARTITION BY for especificada, ORDER BY usa a tabela completa. Se ORDER BY for omitida, o valor de retorno será 1 para todas as linhas.
Se ORDER BY não produzir uma ordenação exclusiva, a ordem das linhas será não determinística. Para obter mais informações, consulte [Ordenação exclusiva de dados para funções da janela](Window_functions.md#Examples_order_by_WF).
## Tipo de retorno
INTEGER
## Exemplos
O exemplo a seguir ordena a tabela pela quantidade vendida (padrão crescente) e atribui uma classificação a cada linha. O valor de classificação de 1 é o valor de classificação mais alto. Os resultados são classificados após a aplicação dos resultados da função de janela:
```
select salesid, qty,
rank() over (order by qty) as rnk
from winsales
order by 2,1;
salesid | qty | rnk
--------+-----+-----
10001 | 10 | 1
10006 | 10 | 1
30001 | 10 | 1
40005 | 10 | 1
30003 | 15 | 5
20001 | 20 | 6
20002 | 20 | 6
30004 | 20 | 6
10005 | 30 | 9
30007 | 30 | 9
40001 | 40 | 11
(11 rows)
```
Observe que a cláusula ORDER BY externa neste exemplo inclui as colunas 2 e 1 para garantir que AWS Clean Rooms retorne resultados classificados de forma consistente sempre que essa consulta for executada. Por exemplo, linhas com vendas IDs 10001 e 10006 têm valores idênticos de QTY e RNK. Ordenar o conjunto de resultados final pela coluna 1 garante que a linha 10.001 sempre caia antes de 10.006. Para uma descrição da tabela WINSALES, consulte [Amostra de tabela para exemplos de funções de janela](Window_functions.md#Window_function_example).
No exemplo a seguir, a ordenação é revertida para a função da janela (`order by qty desc`). Agora, o valor de classificação mais alto se aplica ao valor de QTY mais alto.
```
select salesid, qty,
rank() over (order by qty desc) as rank
from winsales
order by 2,1;
salesid | qty | rank
---------+-----+-----
10001 | 10 | 8
10006 | 10 | 8
30001 | 10 | 8
40005 | 10 | 8
30003 | 15 | 7
20001 | 20 | 4
20002 | 20 | 4
30004 | 20 | 4
10005 | 30 | 2
30007 | 30 | 2
40001 | 40 | 1
(11 rows)
```
Para uma descrição da tabela WINSALES, consulte [Amostra de tabela para exemplos de funções de janela](Window_functions.md#Window_function_example).
O exemplo a seguir particiona a tabela por SELLERID e ordena cada partição pela quantidade (em ordem decrescente) e atribui uma classificação a cada linha. Os resultados são classificados após a aplicação dos resultados da função de janela.
```
select salesid, sellerid, qty, rank() over
(partition by sellerid
order by qty desc) as rank
from winsales
order by 2,3,1;
salesid | sellerid | qty | rank
--------+----------+-----+-----
10001 | 1 | 10 | 2
10006 | 1 | 10 | 2
10005 | 1 | 30 | 1
20001 | 2 | 20 | 1
20002 | 2 | 20 | 1
30001 | 3 | 10 | 4
30003 | 3 | 15 | 3
30004 | 3 | 20 | 2
30007 | 3 | 30 | 1
40005 | 4 | 10 | 2
40001 | 4 | 40 | 1
(11 rows)
```
# Função de janela ROW\$1NUMBER
Determina o número ordinal da linha atual em um grupo de linhas, começando com 1, com base na expressão ORDER BY da cláusula OVER. Se a cláusula opcional PARTITION BY estiver presente, os números ordinais são redefinidos para cada grupo de linhas. As linhas com valores iguais para as expressões ORDER BY recebem os diferentes números de linha de forma não determinística.
## Sintaxe
```
ROW_NUMBER () OVER
(
[ PARTITION BY expr_list ]
[ ORDER BY order_list ]
)
```
## Argumentos
( )
A função não aceita argumentos, mas os parênteses vazios são necessários.
OVER
As cláusulas de janela para a função ROW\$1NUMBER.
PARTITION BY *expr\$1list*
Opcional. Uma ou mais expressões que definem a função ROW\$1NUMBER.
ORDER BY *order\$1list*
Opcional. A expressão que define as colunas nas quais os números de linha se baseiam. Se nenhuma PARTITION BY for especificada, ORDER BY usa a tabela completa.
Se ORDER BY não produzir uma ordenação exclusiva ou for omitido, a ordem das linhas será não determinística. Para obter mais informações, consulte [Ordenação exclusiva de dados para funções da janela](Window_functions.md#Examples_order_by_WF).
## Tipo de retorno
BIGINT
## Exemplos
O seguinte exemplo particiona a tabela por SELLERID e ordena cada partição por QTY (na ordem ascendente) e, então, atribui um número de linha para cada linha. Os resultados são classificados após a aplicação dos resultados da função de janela.
```
select salesid, sellerid, qty,
row_number() over
(partition by sellerid
order by qty asc) as row
from winsales
order by 2,4;
salesid | sellerid | qty | row
---------+----------+-----+-----
10006 | 1 | 10 | 1
10001 | 1 | 10 | 2
10005 | 1 | 30 | 3
20001 | 2 | 20 | 1
20002 | 2 | 20 | 2
30001 | 3 | 10 | 1
30003 | 3 | 15 | 2
30004 | 3 | 20 | 3
30007 | 3 | 30 | 4
40005 | 4 | 10 | 1
40001 | 4 | 40 | 2
(11 rows)
```
Para uma descrição da tabela WINSALES, consulte [Amostra de tabela para exemplos de funções de janela](Window_functions.md#Window_function_example).