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. Elementos FLOAT. Elementos de ponto fixo (com qualquer escala).
`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:

número
cadeia de caracteres
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.

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.