Mapeamentos de tipos de dados entre linguagens do manipulador e SQL

Neste tópico:

Um procedimento armazenado ou função definida pelo usuário que você escreve é chamado a partir do SQL e assim recebe e retorna valores em tipos de dados SQL. No entanto, seu manipulador subjacente usará tipos de dados da linguagem do manipulador, como Java, Python ou Scala. No tempo de execução, o Snowflake converte entre os tipos SQL e tipos de manipulador para argumentos e valores de retorno.

Observe que Snowflake faz estas conversões também nos seguintes casos:

  • Ao construir dinamicamente uma instrução SQL que usa um valor em uma variável do manipulador.

  • Ao vincular o valor de uma variável a uma instrução preparada.

Este tópico descreve mapeamentos válidos entre dados e tipos SQL e aqueles das linguagens do manipulador suportadas. Use este conteúdo para escolher os tipos de dados ao escrever um manipulador.

Para obter mais informações sobre tipos de dados SQL do Snowflake, consulte Resumo dos tipos de dados.

Mapeamentos de tipos de dados SQL-Java

A tabela abaixo mostra os mapeamentos de tipo entre SQL e Java. Esses mapeamentos geralmente se aplicam aos argumentos passados para o procedimento ou função e aos valores retornados por ele. No entanto, existem algumas exceções, listadas em notas de rodapé.

Observe que alguns tipos de dados de SQL (por exemplo, NUMBER) são compatíveis com vários tipos de dados de Java (por exemplo, int, long etc.). Nesses casos, você pode usar qualquer tipo de dados de Java que tenha capacidade suficiente para manter os valores reais que serão passados. Se você passar um valor de SQL para um tipo de dados de Java incompatível (ou vice-versa), o Snowflake gerará um erro.

Tipo de SQL

Tipo de Java

Notas

ARRAY

String[]

Formata os elementos da array como cadeias de caracteres.

ARRAY

String

Formata a matriz como uma cadeia de cadeia de caracteres JSON (por exemplo, [1, "foo", null]).

BINARY

byte[]

BINARY

String

Codifica a cadeia de caracteres binária em hexadecimal. [4]

BINARY

InputStream

Expõe o valor BINARY como uma sequência de bytes.

BOOLEAN

boolean

Não pode ser nulo.

BOOLEAN

Boolean

BOOLEAN

String

[4]

DATE

java.sql.Date

DATE

String

Formata a data como YYYY-MM-DD. [4]

FLOAT

double

Não pode ser nulo.

FLOAT

Double

FLOAT

float

Não pode ser nulo. Pode resultar em perda de precisão.

FLOAT

Float

Pode resultar em perda de precisão.

FLOAT

String

Pode resultar em perda de precisão (a conversão float -> string causa perdas).

GEOGRAPHY

String

Formata a geografia como GeoJSON.

GEOGRAPHY

Geography

[5]

NUMBER

short

Não pode ser nulo. Deve caber na faixa de valores do short (nenhuma parte fracionária, e a parte inteira não pode exceder os valores máximos/minutos do short).

NUMBER

Short

Deve caber na faixa de valores do short (nenhuma parte fracionária, e a parte inteira não pode exceder os valores máximos/minutos do short).

NUMBER

int

Não pode ser nulo. Deve caber na faixa do int (nenhuma parte fracionária, e a parte inteira não pode exceder os valores máximos/mínimos do int).

NUMBER

Integer

Deve caber na faixa do int (nenhuma parte fracionária, e a parte inteira não pode exceder os valores máximos/mínimos do int).

NUMBER

long

Não pode ser nulo. Deve caber na faixa do long (nenhuma parte fracionária, e a parte inteira não pode exceder os valores máximos/mínimos do long).

NUMBER

Long

Deve caber na faixa do long (nenhuma parte fracionária, e a parte inteira não pode exceder os valores máximos/mínimos do long).

NUMBER

java.math.BigDecimal

NUMBER

java.math.BigInteger

Deve caber na faixa do BigInteger (nenhuma parte fracionária).

NUMBER

String

OBJECT

Map<String, String>

As chaves do mapa são as chaves do objeto e os valores são formatados como cadeias de caracteres.

OBJECT

String

Formata o objeto como uma cadeia de caracteres JSON (por exemplo, {"x": 3, "y": true}).

TIME

java.sql.Time

[3]

TIME

String

Formata o tempo como HH:MI:SS.SSSSSSSSS, onde a parte fracionária dos segundos depende da precisão do tempo. [3]

TIMESTAMP_LTZ

java.sql.Timestamp

Deve caber na faixa do java.sql.Timestamp. [3]

TIMESTAMP_LTZ

String

O formato de saída é DY, DD MON YYYY HH24:MI:SS TZHTZM. [1] , [3] , [4]

TIMESTAMP_NTZ

java.sql.Timestamp

Deve caber no intervalo de java.sql.Timestamp. Trata o tempo real como uma compensação da época Unix (efetivamente impondo um fuso horário UTC). [3]

TIMESTAMP_NTZ

String

Trata o tempo real como uma compensação da época Unix (efetivamente impondo um fuso horário UTC). O formato de saída é DY, DD MON YYYY HH:MI:SS. [2], [3], [4]

TIMESTAMP_TZ

java.sql.Timestamp

Deve caber na faixa do java.sql.Timestamp. [3]

TIMESTAMP_TZ

String

O formato de saída é DY, DD MON YYYY HH24:MI:SS TZHTZM. [1] , [3] , [4]

VARCHAR

String

VARIANT

Variant

O tipo de dados Variant é uma classe no pacote Snowpark. Para obter mais informações, consulte Tipos de pacotes Snowpark suportados para funções definidas pelo usuário. Para obter um exemplo, consulte Como passar um valor VARIANT para uma UDF de Java inline.

Matrizes

UDFs de Java podem receber arrays de qualquer um dos seguintes tipos de dados de Java:

Tipo de dados

Notas

String

boolean

A ARRAY do Snowflake deve conter somente elementos BOOLEAN, e não deve conter nenhum valor NULL.

double

float

A ARRAY do Snowflake deve conter um dos seguintes valores e não deve conter nenhum valor NULL.

int

long

short

A ARRAY do Snowflake deve conter somente elementos de ponto fixo com uma escala de 0, e não deve conter nenhum valor NULL.

Valores NULL

O Snowflake oferece suporte para dois valores NULL distintos: SQL NULL e JSON de VARIANT null. (Para obter mais informações sobre o VARIANT NULL do Snowflake, consulte Valores NULL).

O Java oferece suporte para um valor null, que é apenas para tipos de dados não-primitivos.

Um argumento SQL NULL para um manipulador de Java é convertido para o valor de Java null, mas somente para tipos de dados de Java que oferecem suporte para null.

Um valor de Java null retornado é convertido de volta para um NULL de SQL.

Valores TIMESTAMP_LTZ e fusos horários

Uma UDF de Java fica bastante isolada do ambiente no qual é chamada. Entretanto, o fuso horário é herdado do ambiente de chamada. Se a sessão do chamador definir um fuso horário padrão antes de chamar a UDF de Java, a UDF de Java tem o mesmo fuso horário padrão. A UDF de Java utiliza os mesmos dados da base de dados de fuso horário IANA usados pelo TIMEZONE SQL do Snowflake nativo (isso é, dados do lançamento 2021a do banco de dados de fuso horário).

Tipos de pacotes Snowpark suportados para funções definidas pelo usuário

Em uma função definida pelo usuário, você pode usar um subconjunto específico de tipos incluídos no pacote Snowflake Snowpark Java. Embora esses tipos sejam projetados para uso no código do Snowpark, alguns também são suportados para uso em UDFs pela conveniência que podem proporcionar. (Para saber mais sobre o Snowpark, consulte a Documentação do Snowpark.)

Nota

A biblioteca do Snowpark é um requisito para procedimentos armazenados escritos em Java, Python e Scala. Como resultado, você pode usar os tipos do Snowpark sem restrições.

Os tipos do Snowpark na tabela a seguir são suportados no código da UDF. Você não deve usar outros tipos do Snowpark no código da UDF; eles não são suportados lá.

Tipo do Snowpark

Versão necessária do Snowpark

Descrição

Geography

1.2.0 e superior

Representa o tipo GEOGRAPHY do Snowflake. Para obter o exemplo que usa o tipo de dados Geography, consulte Como passar um valor GEOGRAPHY para uma UDF de Java inline.

Variant

1.4.0 e superior

Representa os dados VARIANT do Snowflake. Para obter um exemplo que usa o tipo de dados Variant, consulte Como passar um valor VARIANT para uma UDF de Java inline.

Como especificar o pacote Snowpark como uma dependência

Ao desenvolver o código de uma UDF que utiliza o pacote Snowpark, você precisará configurar seu ambiente de desenvolvimento para que possa compilar e executar o código com dependências do Snowpark. Para mais detalhes, consulte Como configurar outros ambientes de desenvolvimento para o Snowpark Java.

Ao implantar uma UDF executando a instrução CREATE FUNCTION, você pode especificar o pacote Snowpark como uma dependência sem carregar o arquivo JAR para um estágio (a biblioteca já está no Snowflake). Para fazer isso, especifique o nome e a versão do pacote na cláusula PACKAGES. Para obter um exemplo de sintaxe, consulte Como passar um valor GEOGRAPHY para uma UDF de Java inline.

Mapeamentos de tipos de dados SQL-JavaScript

A tabela a seguir mostra os tipos de dados SQL do Snowflake e os tipos de dados JavaScript correspondentes:

Tipo de dados SQL

Tipo de dados JavaScript

Notas

ARRAY

JSON

BOOLEAN

boolean

DATE

date

GEOGRAPHY, GEOMETRY

JSON

REAL, FLOAT, FLOAT8, FLOAT4, DOUBLE, DOUBLE PRECISION

number

TIME

string

TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ

date ou SfDate

Quando um carimbo de data/hora é passado como argumento para um procedimento armazenado, o carimbo de data/hora é convertido em um objeto JavaScript date. Em outras situações (por exemplo, ao recuperar de ResultSet), um carimbo de data/hora é convertido em um objeto SfDate. Para obter mais detalhes sobre o tipo de dados SfDate, que não é um tipo de dados JavaScript padrão, consulte API de procedimentos armazenados em JavaScript.

VARCHAR, CHAR, CHARACTER, STRING, TEXT

string

VARIANT

JSON

Notas

Nem todos os tipos de dados SQL do Snowflake têm um tipo de dados de JavaScript correspondente. Por exemplo, JavaScript não suporta diretamente os tipos de dados INTEGER ou NUMBER. Nesses casos, você deve converter o tipo de dados SQL para um tipo de dados alternativo apropriado. Por exemplo, você pode converter um SQL INTEGER em SQL FLOAT, que pode ser convertido em um valor JavaScript do tipo de dados number.

A tabela abaixo mostra as conversões apropriadas para os tipos de dados SQL incompatíveis:

Tipos de dados SQL incompatíveis

Tipos de dados SQL compatíveis

BINARY

Uint8Array

INTEGER

FLOAT

NUMBER, NUMERIC, DECIMAL

FLOAT

OBJECT

Uint8Array

Ao retornar valores

Se a instrução return em JavaScript retornar um tipo de dados diferente do tipo de retorno declarado no procedimento armazenado, o valor JavaScript é convertido no tipo de dados SQL, se possível. Por exemplo, se um número é retornado, mas o procedimento armazenado é declarado como o retorno de uma cadeia de caracteres, o número é convertido em uma cadeia de caracteres dentro do JavaScript e então copiado para a cadeia de caracteres retornada na instrução SQL. (Lembre-se de que alguns erros de progração de JavaScript, como o retorno do tipo de dados incorreto, podem ser ocultaos por este comportamento).

Se não houver uma conversão válida para a conversão, então ocorre um erro.

Ao vincular valores

Quando você vincula variáveis JavaScript a instruções SQL, o Snowflake converte dos tipos de dados JavaScript nos tipos de dados SQL. Você pode vincular variáveis dos seguintes tipos de dados JavaScript:

Para obter mais informações sobre vinculação, incluindo alguns exemplos, consulte Variáveis de vinculação.

Você também pode achar os seguintes tópicos úteis:

Mapeamentos de tipos de dados SQL-Python

A tabela abaixo mostra os mapeamentos de tipo entre SQL e Python. Esses mapeamentos geralmente se aplicam aos argumentos passados para o manipulador Python e aos valores retornados dele.

Tipo de SQL

Tipo Python

Notas

ARRAY

list

Quando um tipo de dados Python é convertido em ARRAY, se houver algum dado decimal Python embutido, o decimal Python embutido será convertido em uma cadeia de caracteres no ARRAY.

BINARY

bytes

BOOLEAN

bool

DATE

datetime.date

FLOAT

float

Operações de ponto flutuante podem ter pequenos erros de arredondamento, que podem se acumular, especialmente quando funções agregadas processam um grande número de linhas. Erros de arredondamento podem variar cada vez que uma consulta é executada se as linhas forem processadas em uma ordem diferente. Para obter mais informações, consulte Tipos de dados numéricos: float.

GEOGRAPHY, GEOMETRY

dict

Formata a geografia como GeoJSON e depois o converte em um dict de Python.

NUMBER

int ou decimal.Decimal

Se a escala do tipo NUMBER for 0, então o tipo int Python será usado. Caso contrário, o tipo decimal.Decimal é usado.

OBJECT

dict

Quando um tipo de dados Python é convertido em OBJECT, se houver algum dado decimal Python embutido, o decimal Python embutido será convertido em uma cadeia de caracteres no OBJECT.

TIME

datetime.time

Embora o Snowflake possa armazenar valores de tempo com precisão de nanossegundos, o tipo datetime.time do Python mantém apenas a precisão de milissegundos. A conversão entre os tipos de dados Snowflake e Python pode reduzir a precisão efetiva para milissegundos.

TIMESTAMP_LTZ

datetime.datetime

Use o fuso horário local para converter a hora interna UTC para um datetime “ingênuo” local. Isso exige um datetime “ingênuo” como tipo de retorno.

TIMESTAMP_NTZ

datetime.datetime

Converta diretamente para um datetime “ingênuo”. Requer um datetime “ingênuo” como tipo de retorno.

TIMESTAMP_TZ

datetime.datetime

Converta para datetime “ciente” com informações de fuso horário. Requer um datetime “ciente” como tipo de retorno.

VARCHAR

str

VARIANT

dict, list, int, float, str ou bool

Cada linha de variante é convertida dinamicamente para um tipo do Python para argumentos e vice-versa para valores de retorno. Os seguintes tipos são convertidos em cadeias de caracteres em vez de tipos nativos do Python: decimal, binary, date, time, timestamp_ltz, timestamp_ntz, timestamp_tz. Quando um tipo de dados Python é convertido em VARIANT, se houver algum dado decimal Python embutido, o decimal Python embutido será convertido em uma cadeia de caracteres em VARIANT.

Mapeamentos de tipos de dados SQL-Scala

O Snowflake oferece suporte aos seguintes tipos de dados Scala além dos tipos de Java listados em Mapeamentos de tipos de dados SQL-Java:

Tipo de dados SQL

Tipo do Scala

Notas

ARRAY

Array[String]

BINARY

Array[Byte]

BOOLEAN

Boolean ou Option[Boolean]

DOUBLE

Double ou Option[Double]

FLOAT

Float ou Option[Float]

NUMBER

Os seguintes tipos são suportados:

  • Int ou Option[Int]

  • Long ou Option[Long]

OBJECT

Map[String, String]

VARCHAR

String

VARIANT

String

Formata o valor de acordo com o tipo que é representado. Variant null é formatada como a cadeia de caracteres “null”.

Para DATE e TIMESTAMP, use os tipos de Java listados em Mapeamentos de tipos de dados SQL-Java.