Fonction cast

S’applique à :coche marquée oui Databricks SQL coche marquée oui Databricks Runtime

Convertit la valeur expr dans le type de données cible type.

Syntaxe

cast(sourceExpr AS targetType)

Arguments

  • sourceExpr : toute expression convertible.
  • targetType : Le type de données du résultat.

Retours

Le résultat est de type targetType.

Les combinaisons suivantes de cast de type de données sont valides :

Source (ligne) Cible (colonne) VOID numeric STRING DATE TIMESTAMP intervalle année-mois intervalle jour-heure BOOLEAN BINARY ARRAY MAP STRUCT
VOID Y O O O O O O O O O O Y
numeric N O O N O O O O N N N N
STRING N O O O O O O O O N N N
DATE N N O O O N N N N N N N
TIMESTAMP N O O O O N N N N N N N
intervalle année-mois N O O N N O N N N N N N
intervalle jour-heure N O O N N N O N N N N N
BOOLEAN N O O N O N N O N N N N
BINARY N O O N N N N N O N N N
ARRAY N N O N N N N N N O N N
MAP N N O N N N N N N N O N
STRUCT N N O N N N N N N N N Y

Règles et limitations basées sur targetType

Avertissement

Dans Databricks Runtime, si spark.sql.ansi.enabled est false, un dépassement de capacité ne provoque pas d’erreur, mais « enveloppe » le résultat.

Une valeur sourceExpr avec un format non valide ou des caractères non valides pour targetType donnera lieu à un NULL.

numeric

Si targetType est un numérique et que sourceExpr est de type :

  • VOID

    Le résultat est une valeur NULL du type numérique spécifié.

  • numeric

    Si targetType est un numérique entier, le résultat est sourceExprtronqué à un nombre entier.

    Sinon, le résultat est sourceExprarrondi à une échelle disponible de targetType.

    Si la valeur est en dehors de l’intervalle targetType, une erreur de dépassement est levée.

    Utilisez try_cast pour transformer les erreurs de dépassement en NULL.

  • STRING

    sourceExpr est lu comme une valeur littérale de targetType.

    Si sourceExpr ne respecte pas le format des valeurs littérales, une erreur est levée.

    Si la valeur est en dehors de la plage targetType, une erreur de dépassement est levée.

    Utilisez try_cast pour transformer les erreurs de débordement et de format non valide en NULL.

  • TIMESTAMP

    Le résultat est le nombre de secondes écoulées entre 1970-01-01 00:00:00 UTC et sourceExpr.

    Si targetType est un numérique entier, le résultat est tronqué à un nombre entier.

    Sinon, le résultat est arrondi à une échelle disponible de targetType.

    Si le résultat est en dehors de l’intervalle targetType, une erreur de dépassement est levée.

    Utilisez try_cast pour transformer les erreurs de dépassement en NULL.

  • INTERVALLE

    S’applique à :coche marquée oui Databricks SQL coche marquée oui Databricks Runtime 11.2 et versions ultérieures

    Le type de cible doit être un numérique exact.

    Pour un INTERVAL upper_unit TO lower_unit donné, le résultat est mesuré en nombre total de lower_unit. Si lower_unit est SECOND, les fractions de seconde sont stockées à droite du point décimal. Pour tous les autres intervalles, le résultat est toujours un nombre intégral.

  • BOOLEAN

    Si sourceExpr est :

    • true : Le résultat est 0.
    • false : Le résultat est 1.
    • NULL : Le résultat est NULL.

Exemples

> SELECT cast(NULL AS INT);
  NULL

> SELECT cast(5.6 AS INT);
  5

> SELECT cast(5.6 AS DECIMAL(2, 0));
  6

> SELECT cast(-5.6 AS INT);
  -5

> SELECT cast(-5.6 AS DECIMAL(2, 0));
  -6

> SELECT cast(128 AS TINYINT);
  Overflow

> SELECT cast(128 AS DECIMAL(2, 0));
  Overflow

> SELECT cast('123' AS INT);
  123

> SELECT cast('123.0' AS INT);
  Invalid format

> SELECT cast(TIMESTAMP'1970-01-01 00:00:01' AS LONG);
  1

> SELECT cast(TIMESTAMP'1970-01-01 00:00:00.000001' AS DOUBLE);
  1.0E-6

> SELECT cast(TIMESTAMP'2022-02-01 00:00:00' AS SMALLINT);
  error: overflow
> SELECT cast(true AS BOOLEAN);
  1

> SELECT cast(INTERVAL '1-2' YEAR TO MONTH AS INTEGER);
  14

> SELECT cast(INTERVAL '1:30.5' MINUTE TO SECOND AS DECIMAL(5, 2));
  90.50

STRING

Si targetType est de type STRING et que sourceExpr est de type :

  • VOID

    Le résultat est une chaîne NULL.

  • exact numeric

    Le résultat est le nombre littéral avec un signe moins facultatif et aucun zéro de début à l’exception du chiffre unique à gauche de la virgule décimale. Si targetType est DECIMAL(p, s) avec s supérieur à 0, un point décimal est ajouté et les zéros de queue sont ajoutés à l’échelle.

  • binaire à virgule flottante

    Si le nombre absolu est inférieur à 10,000,000 et supérieur ou égal à 0.001, le résultat est exprimé sans notation scientifique avec au moins un chiffre de part et d’autre de la virgule.

    Sinon, Azure Databricks utilise une mantisse suivie de E et d’un exposant. La mantisse comporte un signe moins de tête facultatif, suivi d’un chiffre à gauche de la virgule, et du nombre minimal de chiffres supérieurs à zéro à droite. L’exposant a un signe moins de début facultatif.

  • DATE

    Si l’année est comprise entre 9999 BCE et 9999 CE, le résultat est un dateString de la forme -YYYY-MM-DD et YYYY-MM-DD respectivement.

    Pour les années avant ou après cette plage, le nombre nécessaire de chiffres est ajouté au composant d’année et + est utilisé pour CE.

  • TIMESTAMP

    Si l’année est comprise entre 9999 BCE et 9999 CE, le résultat est un timestampString de la forme -YYYY-MM-DD hh:mm:ss et YYYY-MM-DD hh:mm:ss respectivement.

    Pour les années avant ou après cette plage, le nombre nécessaire de chiffres est ajouté au composant d’année et + est utilisé pour CE.

    Les secondes fractionnaires .f... sont ajoutées si nécessaire.

  • intervalle année-mois

    Le résultat est sa représentation la plus courte du littéral d’intervalle. Si l’intervalle est négatif, le signe est incorporé dans interval-string. Pour les unités inférieures à 10, les zéros de gauche sont omis.

    Une chaîne d’intervalle d’année standard a la forme suivante :

    • INTERVAL 'Y' YEAR
    • INTERVAL 'Y-M' YEAR TO MONTH
    • INTERVAL 'M' MONTH
  • intervalle jour-heure

    Le résultat est sa représentation la plus courte du littéral d’intervalle. Si l’intervalle est négatif, le signe est incorporé dans interval-string. Pour les unités inférieures à 10, les zéros de gauche sont omis.

    Une chaîne d’intervalle de jour-heure standard a la forme suivante :

    • INTERVAL 'D' DAY
    • INTERVAL 'D h' DAY TO HOUR
    • INTERVAL 'D h:m' DAY TO MINUTE
    • INTERVAL 'D h:m:s' DAY TO SECOND
    • INTERVAL 'h' HOUR
    • INTERVAL 'h:m' HOUR TO MINUTE
    • INTERVAL 'm:s' MINUTE TO SECOND
    • INTERVAL 's' SECOND
  • BOOLEAN

    Le résultat du booléen true est le littéral de chaîne true, pour false, c’est le littéral de chaîne false, et pour NULL, c’est la chaîne NULL.

  • BINARY

    Un résultat est le binaire sourceExpr interprété comme une séquence de caractères UTF-8.

    Azure Databricks ne valide pas les caractères UTF-8. Un cast de BINARY vers STRING n’injectera jamais de caractères de substitution et ne provoquera pas d’erreur.

  • ARRAY

    Le résultat est une liste d’éléments de cast séparés par des virgules, qui est encadrée par des crochets [ ]. Un espace suit chaque virgule. Un élément NULL est traduit en null littéral.

    Azure Databricks n’ajoute pas de guillemets ou ne marque pas d’une autre manière les éléments individuels, qui peuvent eux-mêmes contenir des parenthèses ou des virgules.

  • MAP

    Le résultat est une liste séparée par des virgules de paires de valeurs de clé de cast, entourée d’accolades { }. Un espace suit chaque virgule. Chaque paire clé-valeur est séparée par ->. Une valeur de carte NULL est traduite en null littéral.

    Azure Databricks n’ajoute pas de guillemets ou ne marque pas d’une autre manière les clés ou valeurs individuelles, qui peuvent eux-mêmes contenir des crochets, des virgules ou des ->.

  • STRUCT

    Le résultat est une liste séparée par des virgules de valeurs de champ cast, entourée d’accolades { }. Un espace suit chaque virgule. La valeur d’un champ NULL est convertie en un null littéral.

    Azure Databricks n’ajoute pas de guillemets ou ne marque pas d’une autre manière les champs individuels, qui peuvent eux-mêmes contenir des crochets ou des virgules.

Exemples

> SELECT cast(NULL AS STRING);
  NULL

> SELECT cast(-3Y AS STRING);
  -3

> SELECT cast(5::DECIMAL(10, 5) AS STRING);
  5.00000

> SELECT cast(12345678e-4 AS STRING);
  1234.5678

> SELECT cast(1e7 as string);
  1.0E7

> SELECT cast(1e6 as string);
  1000000.0

> SELECT cast(1e-4 as string);
  1.0E-4

> SELECT cast(1e-3 as string);
  0.001

> SELECT cast(12345678e7 AS STRING);
  1.2345678E14

> SELECT cast(DATE'1900-12-31' AS STRING);
  1900-12-31

-- Caesar no more
> SELECT cast(DATE'-0044-03-15' AS STRING);
  -0044-03-15

> SELECT cast(DATE'100000-12-31' AS STRING);
  +100000-12-31

> SELECT cast(current_timestamp() AS STRING);
  2022-04-02 22:29:09.783

> SELECT cast(INTERVAL -'13-02' YEAR TO MONTH AS STRING);
  INTERVAL '-13-2' YEAR TO MONTH

> SELECT cast(INTERVAL '12:04.9900' MINUTE TO SECOND AS STRING);
  INTERVAL '12:04.99' MINUTE TO SECOND

> SELECT cast(true AS STRING);
  true

> SELECT cast(false AS STRING);
  false

-- A bad UTF-8 string
> SELECT cast(x'33800033' AS STRING);
  3�3

> SELECT hex(cast(x'33800033' AS STRING));
  33800033

> SELECT cast(array('hello', NULL, 'world') AS STRING);
  [hello, null, world]

> SELECT cast(array('hello', 'wor, ld') AS STRING);
  [hello, wor, ld]

> SELECT cast(array() AS STRING);
  []

> SELECT cast(map('hello', 1, 'world', null) AS STRING);
  {hello -> 1, world -> null}

> SELECT cast(map('hello -> 1', DATE'2022-01-01') AS STRING);
  {hello -> 1 -> 2022-01-01}

> SELECT cast(map() AS STRING);
  {}

> SELECT cast(named_struct('a', 5, 'b', 6, 'c', NULL) AS STRING);
  {5, 6, null}

> SELECT cast(named_struct() AS STRING);
  {}

DATE

Si targetType est un type DATE et que sourceExpr est de type :

  • VOID

    Le résultat est une NULL DATE.

  • STRING

    sourceExpr doit être un dateString valide.

    Si sourceExpr n’est pas valide dateString, Azure Databricks retourne une erreur.

    Utilisez try_cast pour transformer les erreurs de données non valides en NULL.

  • TIMESTAMP

    Le résultat est la partie date du timestamp sourceExpr.

Exemples

> SELECT cast(NULL AS DATE);
  NULL

> SELECT cast('1900-10-01' AS DATE);
  1900-10-01

> SELECT cast('1900-10-01' AS DATE);
  1900-10-01

-- There is no February 30.
> SELECT cast('1900-02-30' AS DATE);
  Error

> SELECT cast(TIMESTAMP'1900-10-01 12:13:14' AS DATE);
  1900-10-01

timestamp

Si targetType est de type TIMESTAMP est que sourceExpr est de type :

  • VOID

    Le résultat est une NULL DATE.

  • numeric

    sourceExpr est le nombre de secondes écoulées depuis 1970-01-01 00:00:00 UTC.

    Les fractions inférieures aux microsecondes sont tronquées.

    Si la valeur est en dehors de l’intervalle TIMESTAMP, une erreur de dépassement est levée.

    Utilisez try_cast pour transformer les erreurs de dépassement en NULL.

  • STRING

    sourceExpr doit être un timestampString valide.

    Si sourceExpr n’est pas valide timestampString, Azure Databricks retourne une erreur.

    Utilisez try_cast pour transformer les erreurs de données non valides en NULL.

  • DATE

    Le résultat est la DATE sourceExpr à 00:00:00h.

Exemples

> SELECT cast(NULL AS TIMESTAMP);
  NULL

> SET TIME ZONE '+00:00';
> SELECT cast(0.0 AS TIMESTAMP);
  1970-01-01 00:00:00

> SELECT cast(0.0000009 AS TIMESTAMP);
  1970-01-01 00:00:00

> SELECT cast(1e20 AS TIMESTAMP);
  Error: overflow

> SELECT cast('1900' AS TIMESTAMP);
  1900-01-01 00:00:00

> SELECT cast('1900-10-01 12:13:14' AS TIMESTAMP);
  1900-10-01 12:13:14

> SELECT cast('1900-02-30 12:13:14' AS TIMESTAMP);
  Error

> SELECT cast(DATE'1900-10-01' AS TIMESTAMP);
  1900-10-01 00:00:00

intervalle année-mois

Si targetType est un intervalle année-mois et que sourceExpr est de type :

  • VOID

    Le résultat est un intervalle année-mois NULL.

  • integral_numeric

    S’applique à :coche marquée oui Databricks SQL coche marquée oui Databricks Runtime 11.2 et versions ultérieures

    Le nombre numérique est interprété comme un nombre d’unités inférieures de targetTypeyearmonthIntervalQualifier.

  • STRING

    sourceExpr doit être un yearMonthIntervalString valide.

    Si sourceExpr n’est pas valide yearMonthIntervalString, Azure Databricks retourne une erreur.

    Utilisez try_cast pour transformer les erreurs de données non valides en NULL.

  • intervalle année-mois

    Si targetTypeyearMonthIntervalQualifier inclut MONTH, la valeur reste inchangée, mais est réinterpréciée pour correspondre au type cible.

    Sinon, si le type source yearMonthIntervalQualifier inclut MONTH, le résultat est tronqué à des années complètes.

Exemples

> SELECT cast(NULL AS INTERVAL YEAR);
  NULL

> SELECT cast('1-4' AS INTERVAL YEAR TO MONTH)::STRING;
  INTERVAL '1-4' YEAR TO MONTH

> SELECT cast('1' AS INTERVAL YEAR TO MONTH);
  error

> SELECT cast(INTERVAL '1-4' YEAR TO MONTH AS INTERVAL MONTH)::STRING;
  INTERVAL '16' MONTH

> SELECT cast(14 AS INTERVAL YEAR TO MONTH)::STRING;
  INTERVAL '1-2' YEAR TO MONTH

> SELECT cast(INTERVAL '1-11' YEAR TO MONTH AS INTERVAL YEAR)::STRING;
  INTERVAL '1' YEAR

intervalle jour-heure

Si targetType est un intervalle jour-heure et que sourceExpr est de type :

  • VOID

    Le résultat est un intervalle jour-heure NUL.

  • exact_numeric

    S’applique à :coche marquée oui Databricks SQL coche marquée oui Databricks Runtime 11.2 et versions ultérieures

    Le nombre numérique est interprété comme un nombre d’unités inférieures de targetTypedayTimeIntervalQualifier. Si l’unité est SECOND, toutes les fractions sont interprétées comme des fractions de secondes.

  • STRING

    sourceExpr doit être un dayTimeIntervalString valide.

    Si sourceExpr n’est pas valide dayTimeIntervalString, Azure Databricks retourne une erreur.

    Utilisez try_cast pour transformer les erreurs de données non valides en NULL.

  • intervalle jour-heure

    Si targetTypedayTimeIntervalQualifier inclut la plus petite unité du type source dayTimeIntervalQualifier, la valeur reste inchangée, mais elle est réinterprétée pour correspondre au type cible.

    Sinon, l’intervalle sourceExpr est tronqué pour tenir dans le targetType.

> SELECT cast(NULL AS INTERVAL HOUR);
  NULL

> SELECT cast('1 4:23' AS INTERVAL DAY TO MINUTE)::STRING;
  INTERVAL '1 04:23' DAY TO MINUTE

> SELECT cast('1' AS INTERVAL DAY TO MINUTE);
  error

> SELECT cast(INTERVAL '1 4:23' DAY TO MINUTE AS INTERVAL MINUTE)::STRING;
  INTERVAL '1703' MINUTE

> SELECT cast(INTERVAL '1 4:23' DAY TO MINUTE AS INTERVAL HOUR)::STRING;
  INTERVAL '28' HOUR

> SELECT cast(125.3 AS INTERVAL MINUTE TO SECOND)::STRING;
  INTERVAL '2:5.3' MINUTE TO SECOND

BOOLEAN

Si la valeur targetType est BOOLEAN et que sourceExpr est de type :

  • VOID

    Le résultat est une valeur booléenne NULL.

  • numeric

    Si sourceExpr est :

    • 0 : Le résultat est false.

      Sinon, le résultat est true.

  • STRING

    Si sourcEexpr ne respecte pas la casse :

    • 'T', 'TRUE', 'Y', 'YES', or '1' : Le résultat est true
    • 'F', 'FALSE', 'N', 'NO', or '0' : Le résultat est false
    • NULL : Le résultat est NULL

    Sinon, Azure Databricks retourne une erreur de syntaxe d’entrée non valide pour le type booléen.

    Utilisez try_cast pour transformer les erreurs de données non valides en NULL.

Exemples

> SELECT cast(NULL AS BOOLEAN);
  NULL

> SELECT cast('T' AS BOOLEAN);
  true

> SELECT cast('True' AS BOOLEAN);
  true

> SELECT cast('1' AS BOOLEAN);
  true

> SELECT cast('0' AS BOOLEAN);
  false

> SELECT cast('n' AS BOOLEAN);
  false

> SELECT cast('on' AS BOOLEAN);
  error: invalid input syntax for type boolean

> SELECT cast(0 AS BOOLEAN);
  false

> SELECT cast(0.0E10 AS BOOLEAN);
  false

> SELECT cast(1 AS BOOLEAN);
  true

> SELECT cast(0.1 AS BOOLEAN);
  true

> SELECT cast('NaN'::FLOAT AS BOOLEAN);
  true

BINARY

Si targetType est un BINARY et que sourceExpr est de type :

  • VOID

    Le résultat est une valeur binaire NULL.

  • STRING

    Le résultat est l’encodage UTF-8 de surceExpr.

Exemples

> SELECT cast(NULL AS BINARY);
  NULL

> SELECT hex(cast('Spark SQL' AS BINARY));
  537061726B2053514C

> SELECT hex(cast('Oдesa' AS BINARY));
  4FD0B4657361

ARRAY

Si targetType est un ARRAY < targetElementType > et que sourceExpr est de type :

  • VOID

    Le résultat est une valeur NULL de targeType.

  • ARRAY < sourceElementType >

    Si le cast de sourceElementType vers targetElementType est pris en charge, le résultat est un ARRAY<targetElementType> avec tous les éléments convertis en targetElementType.

    Azure Databricks génère une erreur si le cast n’est pas pris en charge ou si l’un des éléments ne peut pas être casté.

    Utilisez try_cast pour transformer les erreurs de dépassement ou de données non valides en NULL.

Exemples

> SELECT cast(NULL AS ARRAY<INT>);
  NULL

> SELECT cast(array('t', 'f', NULL) AS ARRAY<BOOLEAN>);
  [true, false, NULL]

> SELECT cast(array('t', 'f', NULL) AS INTERVAL YEAR);
  error: cannot cast array<string> to interval year

> SELECT cast(array('t', 'f', 'o') AS ARRAY<BOOLEAN>);
  error: invalid input syntax for type boolean: o.

MAP

Si targetType est un MAP < targetKeyType, targetValueType> et que sourceExpr est de type :

  • VOID

    Le résultat est une valeur NULL de targetType.

  • MAP <sourceKeyType, sourceValueType >

    Si les casts de sourceKeyType vers targetKeyType et sourceValueType vers targetValueType sont pris en charge, le résultat est un MAP<targetKeyType, targetValueType> avec toutes les clés converties en valeurs targetKeyType et toutes les valeurs converties en targetValueType.

    Azure Databricks génère une erreur si le cast n’est pas pris en charge ou si l’une des clés ou valeurs ne peut pas être castée.

    Utilisez try_cast pour transformer les erreurs de dépassement ou de données non valides en NULL.

Exemples

> SELECT cast(NULL AS MAP<STRING, INT>);
  NULL

> SELECT cast(map('10', 't', '15', 'f', '20', NULL) AS MAP<INT, BOOLEAN>);
  {10:true,15:false,20:null}

> SELECT cast(map('10', 't', '15', 'f', '20', NULL) AS MAP<INT, ARRAY<INT>>);
  error: cannot cast map<string,string> to map<int,array<int>>

> SELECT cast(map('10', 't', '15', 'f', '20', 'o') AS MAP<INT, BOOLEAN>);
  error: invalid input syntax for type boolean: o.

STRUCT

Si la valeur targetType est un STRUCT <[targetFieldName : targetFieldType [NOT NULL] [COMMENT str] [, …]] > et que sourceExpr est de type :

  • VOID

    Le résultat est une valeur NULL de targetType.

  • STRUCT < [sourceFieldName : sourceFieldType [NOT NULL] [COMMENT str] [, …]] >

    sourceExpr peut être casté en targetType si toutes ces conditions sont remplies :

    • Le type source a le même nombre de champs que la cible
    • Pour tous les champs : sourceFieldTypeN peut être converti en targetFieldTypeN.
    • Pour toutes les valeurs de champ : la valeur de champ source N peut être castée en targetFieldTypeN et la valeur n’est pas null si le champ cible N est marqué comme NOT NULL.

    Les sourceFieldName, les contraintes sources NOT NULL et les COMMENT sources n’ont pas à correspondre à targetType et sont ignorés.

    Azure Databricks génère une erreur si le cast n’est pas pris en charge ou si l’une des clés ou valeurs ne peut pas être castée.

    Utilisez try_cast pour transformer les erreurs de dépassement ou de données non valides en NULL.

Exemples

> SELECT cast(NULL AS STRUCT<a:INT>);
  NULL

> SELECT cast(named_struct('a', 't', 'b', '1900') AS STRUCT<b:BOOLEAN, c:DATE NOT NULL COMMENT 'Hello'>);
  {"b":true,"c":1900-01-01}

> SELECT cast(named_struct('a', 't', 'b', NULL::DATE) AS STRUCT<b:BOOLEAN, c:DATE NOT NULL COMMENT 'Hello'>);
  error: cannot cast struct<a:string,b:date> to struct<b:boolean,c:date>

> SELECT cast(named_struct('a', 't', 'b', '1900') AS STRUCT<b:BOOLEAN, c:ARRAY<INT>>);
  error: cannot cast struct<a:string,b:string> to struct<b:boolean,c:array<int>>

> SELECT cast(named_struct('a', 't', 'b', 'hello') AS STRUCT<b:BOOLEAN, c:DATE>);
  error: Cannot cast hello to DateType