Share via


cast 函式

適用於:檢查標示為是 Databricks SQL 檢查標示為是 Databricks Runtime

將值 expr 轉換成目標資料類型 type。 此運算子是 :: (冒號冒號) 運算子的 同義字:

語法

cast(sourceExpr AS targetType)

引數

  • sourceExpr:任何可轉換的表達式。
  • targetType:結果的數據類型。

傳回

結果為類型 targetType

資料類型轉換的下列組合有效:

來源(欄) 目標(欄) VOID numeric 字串 DATE TIMESTAMP TIMESTAMP_NTZ year-month interval day-time interval 布爾 二進位 陣 列 地圖 結構
VOID Y Y Y Y Y Y Y Y Y Y Y Y Y
numeric Y N Y N Y Y N N N N
字串 Y Y Y Y Y Y Y Y N N N
DATE N N Y Y Y N N N N N N N
TIMESTAMP Y Y Y Y N N N N N N N
TIMESTAMP_NTZ N N Y Y Y N N N N N N N
year-month interval Y N N N Y N N N N N N
day-time interval Y N N N N Y N N N N N
布爾 Y N Y N N N Y N N N N
二進位 Y N N N N N N Y N N N
陣 列 N N Y N N N N N N N Y N N
地圖 N N Y N N N N N N N N Y
結構 N N Y N N N N N N N N N

以 targetType 為基礎的規則和限制

警告

在 Databricks Runtime 中,如果 spark.sql.ansi.enabledfalse,則溢位不會造成錯誤,而是會「包裝」結果。

sourceExpr具有無效格式或無效字元targetType的值會導致 NULL

numeric

targetType如果 是數值,且 sourceExpr 類型為:

  • VOID

    結果是指定之數值類型的NULL。

  • numeric

    如果 targetType整數數值,則結果會sourceExpr截斷為整數。

    否則,結果會 sourceExpr四捨五入 ,以符合的可用小數字數 targetType

    如果值超出的範圍 targetType,則會引發溢位錯誤。

    使用 try_cast 將溢位錯誤轉換成 NULL

  • 字串

    sourceExpr 會讀取為的 targetType常值。

    如果 sourceExpr 不符合常值的格式,則會引發錯誤。

    如果值超出的範圍 targetType,則會引發溢位錯誤。

    使用 try_cast 將溢位與不合法格式錯誤轉換成 NULL

  • TIMESTAMP

    結果是 和 sourceExpr之間1970-01-01 00:00:00 UTC經過的秒數。

    如果 targetType整數數值,則結果會 截斷 為整數。

    否則,結果會 四捨五入 ,以符合的可用小數字數 targetType

    如果結果超出的範圍 targetType,就會引發溢位錯誤。

    使用 try_cast 將溢位錯誤轉換成 NULL

  • INTERVAL

    適用於:檢查標示為是 Databricks SQL 檢查標示為是 Databricks Runtime 11.3 LTS 和更新版本

    目標類型必須是 確切的數值

    INTERVAL upper_unit TO lower_unit假設結果是以 總數lower_unit來測量。 lower_unit如果 為 SECOND,小數秒會儲存在小數點右邊。 對於所有其他間隔,結果一律為整數。

  • 布爾

    如果 sourceExpr 為:

    • true:結果為 0。
    • false:結果為 1。
    • NULL:結果為 NULL

範例

> 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

> SELECT cast(TRUE AS INT);
  1

> SELECT cast(FALSE AS INT);
  0

字串

targetType如果 是 STRING 類型,且 sourceExpr 類型為:

  • VOID

    結果是 NULL 字串。

  • 精確數值

    結果是具有選擇性減號的常值數位,除了小數點左邊的單一位數以外,沒有前置零。 targetType如果 大於 DECIMAL(p, s)s 0,則會新增小數點,並將尾端零加成小數位數。

  • 浮點二進位

    如果絕對數位小於該 10,000,000 數位,且大於或等於 0.001,則結果會以至少一位數表示小數點兩端的科學表示法表示。

    否則,Azure Databricks 會使用 mantissa,後面接著 E 指數。 mantissa 具有選擇性的前置減號,後面接著小數點左邊的一位數,以及右邊大於零的最小位數。 指數具有 和 選擇性的前置減號。

  • DATE

    如果年份介於 9999 BCE 和 9999 CE 之間,則結果為表單-YYYY-MM-DD的 dateStringYYYY-MM-DD

    在此範圍之前或之後的年份,必要的數字數會新增至年份元件,並 + 用於 CE。

  • TIMESTAMP

    如果年份介於 9999 BCE 和 9999 CE 之間,則結果是表單-YYYY-MM-DD hh:mm:ss的 timestampStringYYYY-MM-DD hh:mm:ss

    在此範圍之前或之後的年份,必要的數字數會新增至年份元件,並 + 用於 CE。

    必要時會新增小數秒 .f...

  • TIMESTAMP_NTZ

    如果年份介於 9999 BCE 和 9999 CE 之間,則結果是表單-YYYY-MM-DD hh:mm:ss的 timestampStringYYYY-MM-DD hh:mm:ss

    在此範圍之前或之後的年份,必要的數字數會新增至年份元件,並 + 用於 CE。

    必要時會新增小數秒 .f...

  • year-month interval

    結果是其間隔常值的最短表示法。 如果間隔為負數,則符號會內嵌在 中 interval-string。 對於小於 10 的單位,會省略前置零。

    典型的年月間隔字串格式如下:

    • INTERVAL 'Y' YEAR
    • INTERVAL 'Y-M' YEAR TO MONTH
    • INTERVAL 'M' MONTH
  • day-time interval

    結果是其間隔常值的最短表示法。 如果間隔為負數,則符號會內嵌在 中 interval-string。 對於小於 10 的單位,會省略前置零。

    一般日時間間隔字串的格式如下:

    • 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
  • 布爾

    布爾值的結果true是 STRING 常值 ,如果是 false STRING 常truefalse,而NULL它是 NULL 字串。

  • 二進位

    結果是二進位 sourceExpr 檔解譯為UTF-8字元序列。

    Azure Databricks 不會驗證 UTF-8 字元。 從 BINARY 轉換至 STRING 永遠不會插入替代字元或引發錯誤。

  • 陣 列

    結果是以逗號分隔的轉換項目清單,並以方括弧 [ ]括住 。 每個逗號後面都會有一個空格。 項目 NULL 會轉譯為常值 null

    Azure Databricks 不會加上引號或標示個別元素,而這些專案本身可能包含方括號或逗號。

  • 地圖

    結果是以逗號分隔的轉換索引鍵值組清單,並以大 { }括弧括住。 每個逗號後面都會有一個空格。 每個索引鍵值組都會以 ->分隔。 NULL對應值會轉譯為常值 null

    Azure Databricks 不會加上引號或標示個別的索引鍵或值,這可能本身可能包含大括弧、逗號或 ->

  • 結構

    結果是以逗號分隔的轉換域值清單,並以大 { }括弧括住。 每個逗號後面都會有一個空格。 NULL網域值會轉譯為常值 null

    Azure Databricks 不會加上引號或標示個別域值,這可能本身可能包含大括弧或逗號。

範例

> 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(TIMESTAMP_NTZ'2023-01-01' AS STRING);
  2023-01-01 00:00:00

> 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);
  {}

日期

targetType如果是 DATE 類型,且 sourceExpr 類型為:

  • VOID

    結果是 NULL DATE。

  • 字串

    sourceExpr 必須是有效的 dateString

    如果 sourceExpr 不是有效的 dateString,Azure Databricks 會傳回錯誤。

    使用 try_cast 將無效的資料錯誤轉換成 NULL

  • TIMESTAMP

    結果是時間戳 sourceExpr的日期部分。

  • TIMESTAMP_NTZ

    結果是 timestamp_ntz sourceExpr的日期部分。

範例

> 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

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

timestamp

targetType如果 是 TIMESTAMP 類型,且 sourceExpr 類型為:

  • VOID

    結果是 NULL DATE。

  • numeric

    sourceExpr 讀取為 自 之後 1970-01-01 00:00:00 UTC的秒數。

    小於微秒的分數會被截斷。

    如果值超出的範圍 TIMESTAMP,就會引發溢位錯誤。

    使用 try_cast 將溢位錯誤轉換成 NULL

  • 字串

    sourceExpr 必須是有效的 timestampString

    如果 sourceExpr 不是有效的 timestampString,Azure Databricks 會傳回錯誤。

    使用 try_cast 將無效的資料錯誤轉換成 NULL

  • DATE

    結果是 sourceExpr hrs 的 00:00:00DATE。

  • TIMESTAMP_NTZ

結果是時間戳值,具有timestamp_ntz sourceExpr的相同年/月/日/小時/分鐘/秒字段。

範例

> 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

> SELECT cast(TIMESTAMP_NTZ'2023-01-01 02:03:04.567' as TIMESTAMP)
  2023-01-01 02:03:04.567

TIMESTAMP_NTZ

targetType如果 是TIMESTAMP_NTZ型別,且 sourceExpr 類型為:

  • VOID

    結果是 NULL DATE。

  • 字串

    sourceExpr 必須是有效的 timestampString

    如果 sourceExpr 不是有效的 timestampString,Azure Databricks 會傳回錯誤。

    使用 try_cast 將無效的資料錯誤轉換成 NULL

  • DATE

    結果是 sourceExpr hrs 的 00:00:00DATE。

  • TIMESTAMP

結果為本地時間,如同 sourceExpr 工作階段時區中的 。

範例

> SELECT cast(NULL AS TIMESTAMP_NTZ);
  NULL

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

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

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

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

> SELECT current_timezone(), CAST(TIMESTAMP'2021-7-1T8:43:28' as TIMESTAMP_NTZ);
  America/Los_Angeles 2021-07-01 08:43:28

> SELECT current_timezone(), CAST(TIMESTAMP'2021-7-1T8:43:28UTC+3' as TIMESTAMP_NTZ);
  America/Los_Angeles 2021-06-30 22:43:28

year-month interval

targetType如果 是年月間隔,且 sourceExpr 類型為:

範例

> 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

day-time interval

targetType如果 是日間時間間隔,且 sourceExpr 類型為:

> 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

targetType如果是 BOOLEANsourceExpr 類型為:

  • VOID

    結果是 NULL 布爾值。

  • numeric

    如果 sourceExpr 為:

  • 字串

    如果 sourcEexpr 為 (不區分大小寫):

    • 'T', 'TRUE', 'Y', 'YES', or '1':結果為 true
    • 'F', 'FALSE', 'N', 'NO', or '0':結果為 false
    • NULL:結果為 NULL

    否則,Azure Databricks 會針對布爾值類型錯誤傳回無效的輸入語法。

    使用 try_cast 將無效的資料錯誤轉換成 NULL

範例

> 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

targetType如果是 BINARY,且 sourceExpr 類型為:

  • VOID

    結果是 NULL 二進位檔。

  • 字串

    結果是的 surceExprUTF-8編碼。

範例

> SELECT cast(NULL AS BINARY);
  NULL

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

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

ARRAY

targetType如果 是 ARRAY < targetElementType >sourceExpr 類型為:

  • VOID

    結果是的 targeTypeNULL。

  • ARRAY < sourceElementType >

    如果支援從 sourceElementType 轉換 targetElementType ,結果為 ARRAY<targetElementType> ,且所有元素都轉換成 targetElementType

    如果不支持轉換,或無法轉換任何專案,Azure Databricks 就會引發錯誤。

    使用 try_cast 將無效的資料或溢位錯誤轉換成 NULL

範例

> 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

targetType如果 是 MAP < targetKeyType,targetValueType >sourceExpr 類型為:

  • VOID

    結果是的 targetTypeNULL。

  • MAP <sourceKeyType、sourceValueType >

    如果支援從 轉換sourceValueType,結果為 MAP<targetKeyType, targetValueType> ,且所有索引鍵都轉換成 targetKeyType ,而所有值都轉換成 targetValueTypetargetValueTypetargetKeyTypesourceKeyType

    如果不支持轉換,或無法轉換任何索引鍵或值,Azure Databricks 就會引發錯誤。

    使用 try_cast 將無效的資料或溢位錯誤轉換成 NULL

範例

> 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

targetType如果 是 STRUCT <[targetFieldName : targetFieldType [NOT NULL] [COMMENT str] [, ...]] >sourceExpr類型為:

  • VOID

    結果是的 targetTypeNULL。

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

    sourceExpr如果所有條件都成立,則可以轉換成 targetType

    • 來源類型具有與目標相同的欄位數目
    • 針對所有欄位: sourceFieldTypeN 可以轉換成 targetFieldTypeN
    • 針對所有域值:來源域值 N 可以轉換成 targetFieldTypeN ,如果目標欄位 N 標示為 NOT NULL,則值不是 Null。

    sourceFieldNames、來源條件約束和來源NOT NULLCOMMENT不需要符合 ,targetType而且會被忽略。

    如果不支持轉換,或無法轉換任何索引鍵或值,Azure Databricks 就會引發錯誤。

    使用 try_cast 將無效的資料或溢位錯誤轉換成 NULL

範例

> 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