標準 SQL 函式與運算子

本頁面說明 BigQuery 運算式,包括函式與運算子。

函式呼叫規則

除非在函式說明中另有明確指示,否則下列規則適用於所有函式:

  • 針對接受數字類型的函式,如有一個運算元是浮點運算元,另一個運算元是其他數字類型,這兩個運算元都會在評估函式之前轉換為 FLOAT64。
  • 如果運算元是 NULL,結果會是 NULL,但 IS 運算子例外。

  • 對於對時區敏感的函式 (如函式說明中的指示),若未指定時區,會使用預設時區 UTC。

SAFE. 前置字串

語法:

SAFE.function_name()

說明

如果您在函式前面加上 SAFE. 前置字串,它會傳回 NULL 而不是錯誤。SAFE. 前置字串只會防止加上前置字串的函式本身發生錯誤:它並不會防止在評估引數運算式時發生錯誤。SAFE. 前置字串只會防止因函式輸入的值所導致發生的錯誤,例如「值超出範圍」錯誤;其他錯誤 (例如內部或系統錯誤) 仍會發生。如果函式沒有傳回錯誤,SAFE. 對輸出沒有影響。如果函式從未傳回例如 RAND 這樣的錯誤,則 SAFE. 沒有效果。

部分運算子 (例如 +=) 不支援 SAFE. 前置字串。如要防止除法運算發生錯誤,請使用 SAFE_DIVIDE。某些運算子 (例如 INARRAYUNNEST) 與函式類似,但不支援 SAFE. 前置字串。CASTEXTRACT 函式也不支援 SAFE. 前置字串。若要防止類型轉換發生錯誤,請使用 SAFE_CAST

範例

在以下範例中,第一次使用 SUBSTR 函式時通常會傳回錯誤,因為函式並不支援使用負值的長度引數。但是,SAFE. 前置字串會導致函式傳回 NULL。第二次使用 SUBSTR 函式會提供預期的輸出:SAFE. 前置字串沒有效果。

SELECT SAFE.SUBSTR('foo', 0, -2) AS safe_output UNION ALL
SELECT SAFE.SUBSTR('bar', 0, 2) AS safe_output;

+-------------+
| safe_output |
+-------------+
| NULL        |
| ba          |
+-------------+

支援的函式

針對大多數可能發生錯誤的純量函式,BigQuery 支援其使用 SAFE. 前置字串。這些函式包含字串函式數學函式日期函式日期時間函式時間戳記函式。BigQuery 不支援匯總分析使用者定義的函式使用 SAFE. 前置字串。

呼叫永久使用者定義函式 (UDF)

注意事項:BigQuery 支援永久 UDF 的功能目前仍為 Beta 版。詳情請參閱產品推出階段的相關說明。

建立永久 UDF 之後,您可以像呼叫任何其他函式一樣地呼叫它,並在前面加上定義為前置字串的資料集名稱。

語法

[`project_name`].dataset_name.function_name([parameter_value[, ...]])

如要在您用於執行查詢以外的專案中呼叫 UDF,project_name 為必要元素。

範例

下列範例可建立名為 multiply_by_three 的 UDF,且可從相同的專案中進行呼叫。

CREATE FUNCTION my_dataset.multiply_by_three(x INT64) AS (x * 3);

SELECT my_dataset.multiply_by_three(5) AS result; -- returns 15

下列範例可從不同的專案中呼叫永久 UDF:

CREATE `other_project`.other_dataset.other_function(x INT64, y INT64)
  AS (x * y * 2);

SELECT `other_project`.other_dataset.other_function(3, 4); --returns 24

轉換規則

「轉換」包括但不限於類型轉換與強制轉換。

  • 類型轉換需要手動轉換,使用的是 CAST() 函式。
  • 強制轉換是自動轉換,BigQuery 會在以下情況中自動執行。
  • 此外,第三組轉換函式具有專屬的函式名稱,例如 UNIX_DATE()

下表大致列出 BigQuery 資料類型的所有 CAST 與強制轉換的可能情況。「強制轉換為」適用於特定資料類型 (例如資料欄) 的所有「運算式」,但常值和參數也可以強制轉換。詳情請參閱常值強制轉換參數強制轉換等節。

來源類型 轉換為 強制轉換為
INT64 BOOL
INT64
NUMERIC
FLOAT64
STRING
FLOAT64
NUMERIC
NUMERIC INT64
NUMERIC
FLOAT64
STRING
FLOAT64
FLOAT64 INT64
NUMERIC
FLOAT64
STRING
 
BOOL BOOL
INT64
STRING
 
STRING BOOL
INT64
NUMERIC
FLOAT64
STRING
BYTES
DATE
DATETIME
TIME
TIMESTAMP
 
BYTES BYTES
STRING
 
DATE DATE
DATETIME
STRING
TIMESTAMP
 
DATETIME DATE
DATETIME
STRING
TIME
TIMESTAMP
 
TIME STRING
TIME
 
TIMESTAMP DATE
DATETIME
STRING
TIME
TIMESTAMP
 
ARRAY ARRAY  
STRUCT STRUCT  

類型轉換

語法:

CAST(expr AS typename)

類型轉換語法可在查詢中用來指示運算式的結果類型應轉換為其他某一類型。

範例:

CAST(x=1 AS STRING)

如果 x 是 1,這會產生 "true",其他非 NULL 值則會產生 "false",如果 x 是 NULL 則會產生 NULL

在未成功從原始值對應至目標網域的支援類型之間轉換會產生執行階段錯誤。例如,將 BYTES 轉換為 STRING 時,若位元組順序不是有效的 UTF-8,會產生執行階段錯誤。

轉換下列類型的運算式 x 時,適用這些規則:

轉換 x 類型時的規則
INT64 FLOAT64 傳回接近但可能不完全相同的 FLOAT64 值。
INT64 BOOL 如果 x0 就傳回 FALSE,否則傳回 TRUE
NUMERIC 浮點 NUMERIC 將轉換成最接近的浮點數,精確度可能會降低。
FLOAT64 INT64 傳回最接近的 INT64 值。
例如 1.5 或 -0.5 之類的中間情況會向遠離 0 的方向四捨五入。
FLOAT64 STRING 傳回近似字串表示。
FLOAT64 NUMERIC 如果浮點數在小數點後的位數超過 9 位,就會四捨五入。轉換 NaN+inf-inf 將傳回錯誤。轉換的值超出 NUMERIC 的範圍將傳回溢位錯誤。
BOOL INT64 如果 xTRUE 就傳回 1,否則傳回 0
BOOL STRING 如果 xTRUE 就傳回 "true",否則傳回 "false"
STRING FLOAT64 x 傳回為 FLOAT64 值,將它解讀為具有與有效 FLOAT64 常值相同的格式。
也支援從 "inf""+inf""-inf""nan" 轉換類型。
轉換區分大小寫。
STRING NUMERIC STRING 所含的數字常值不得超出 NUMERIC 類型的精確度或範圍上限,否則將產生錯誤。如果小數點後超過九位數,則產生的 NUMERIC 值將四捨五入,保留小數點後最多九位數。
STRING BOOL 如果 x"true" 就傳回 TRUE,如果 x 是 "false" 就傳回 FALSE
x 的其他所有值無效,會擲回錯誤而非將類型轉換為 BOOL。
將類型轉換為 BOOL 時,STRING 區分大小寫。
STRING BYTES STRING 使用 UTF-8 編碼將類型轉換為 BYTES。例如,將 STRING「©」的類型轉換為 BYTES 時,會變成含有十六進位值 C2 與 A9 的 2 位元組順序。
BYTES STRING 傳回解讀為 UTF-8 STRING 的 x
以 BYTES 常值 b'\xc2\xa9' 為例,將類型轉換為 STRING 時,會解讀為 UTF-8 並變成 unicode 字元「©」。
如果 x 不是有效的 UTF-8,就會發生錯誤。
ARRAY ARRAY 必須是完全相同的 ARRAY 類型。
STRUCT STRUCT 如果符合以下條件就允許:
  1. 這兩個 STRUCT 具有相同的欄位數。
  2. 原始 STRUCT 欄位類型可手動轉換為對應目標 STRUCT 欄位類型 (如欄位順序定義,而非如欄位名稱定義)。

安全類型轉換

當使用 CAST 時,如果 BigQuery 無法執行類型轉換,查詢可能會失敗。例如,下列查詢會產生錯誤:

SELECT CAST("apple" AS INT64) AS not_a_number;

如果您要保護查詢免於發生這些類型的錯誤,可以使用 SAFE_CASTSAFE_CASTCAST 相同,但它會傳回 NULL,而非產生錯誤。

SELECT SAFE_CAST("apple" AS INT64) AS not_a_number;

+--------------+
| not_a_number |
+--------------+
| NULL         |
+--------------+

如果您要將類型從位元組轉換為字串,也可以使用 SAFE_CONVERT_BYTES_TO_STRING 函式。任何無效的 UTF-8 字元都會替換為 U+FFFD Unicode 替換字元。詳情請參閱 SAFE_CONVERT_BYTES_TO_STRING 一節。

將十六進位字串類型轉換為整數

如果您打算使用十六進位字串 (0x123),可以將這些字串的類型轉換為整數:

SELECT '0x123' as hex_value, CAST('0x123' as INT64) as hex_to_int;

+-----------+------------+
| hex_value | hex_to_int |
+-----------+------------+
| 0x123     | 291        |
+-----------+------------+

SELECT '-0x123' as hex_value, CAST('-0x123' as INT64) as hex_to_int;

+-----------+------------+
| hex_value | hex_to_int |
+-----------+------------+
| -0x123    | -291       |
+-----------+------------+

轉換資料類型

BigQuery 支援將日期類型轉換為字串,或從字串轉換,如下:

CAST(date_expression AS STRING)
CAST(string_expression AS DATE)

從日期類型轉換為字串與時區無關,且格式為 YYYY-MM-DD。將類型從字串轉換為日期時,字串必須符合支援的日期常值格式,這與時區無關。如果字串運算式無效或顯示的日期超出支援的最小/最大範圍,就會產生錯誤。

轉換時間戳記類型

BigQuery 支援將時間戳記類型轉換為字串,或從字串轉換,如下:

CAST(timestamp_expression AS STRING)
CAST(string_expression AS TIMESTAMP)

將時間戳記類型轉換為字串時,會使用預設時區 UTC 解讀時間戳記。產生的亞秒位數取決於亞秒部分的結尾零數:CAST 函式將會截斷零、三或六位數。

將類型從字串轉換為時間戳記時,string_expression 必須符合支援的時間戳記常值格式,否則會發生執行階段錯誤。string_expression 本身可能包含 time_zone,詳情請參閱時區一節。 如果 string_expression 中有時區,會使用那個時區進行轉換,否則會使用預設 UTC 時區。 如果字串少於六位數,會將自動加寬。

如果 string_expression 無效、亞秒有六位數以上 (也就是精確度大於毫秒),或顯示的時間超出支援的時間戳記範圍,就會產生錯誤。

在日期與時間戳記類型之間轉換

BigQuery 支援在日期與時間戳記類型之間轉換,如下:

CAST(date_expression AS TIMESTAMP)
CAST(timestamp_expression AS DATE)

將類型從日期轉換為時間戳記會將 date_expression 解讀為預設時區 UTC 的午夜 (一天的開始)。將類型從時間戳記轉換為日期會有效截斷從預設時區開始的時間戳記。

強制轉換

如需比對函式簽名,BigQuery 會將運算式的結果類型強制轉換為其他類型。例如,若將 func() 函式定義為使用 INT64 類型的單一引數,並且將運算式作為具有 FLOAT64 結果類型的引數使用,就會在計算 func() 之前將運算式的結果強制轉換為 INT64 類型。

常值強制轉換

BigQuery 支援下列常值強制轉換方式:

輸入資料類型 結果資料類型 附註
STRING 常值 DATE
TIMESTAMP

當實際常值類型與相關函式預期的類型不同時,就需要進行常值強制轉換。例如,如果 func() 函式使用 DATE 引數,運算式 func("2014-09-27") 就有效,因為 STRING 常值 "2014-09-27" 已強制轉換為 DATE。

常值強制轉換會在分析時評估,如果輸入的常值無法成功轉換為目標類型,就會產生錯誤。

注意事項:字串常值不會強制轉換為數字類型。

參數強制轉換

BigQuery 支援下列參數強制轉換方式:

輸入資料類型 結果資料類型
STRING 參數

如果參數值無法成功強制轉換為目標類型,就會產生錯誤。

其他轉換函式

BigQuery 提供下列其他轉換函式:

Aggregate 函式

「Aggregate 函式」是對一組值執行計算的函式。COUNT、MIN 與 MAX 都是 aggregate 函式的範例。

SELECT COUNT(*) as total_count, COUNT(fruit) as non_null_count,
       MIN(fruit) as min, MAX(fruit) as max
FROM UNNEST([NULL, "apple", "pear", "orange"]) as fruit;
+-------------+----------------+-------+------+
| total_count | non_null_count | min   | max  |
+-------------+----------------+-------+------+
| 4           | 3              | apple | pear |
+-------------+----------------+-------+------+

以下小節說明 BigQuery 支援的 aggregate 函式。

ANY_VALUE

ANY_VALUE(expression)  [OVER (...)]

說明

如果輸入資料列數為零,就會從輸入傳回任何值或傳回 NULL。 傳回的值非絕對,這表示您可能會在每次使用這個函式時得到不同的結果。

支援的引數類型

不限

選用子句

OVER:指定範圍。請參閱 Analytic 函式

傳回的資料類型

符合輸入資料類型。

範例

SELECT ANY_VALUE(fruit) as any_value
FROM UNNEST(["apple", "banana", "pear"]) as fruit;

+-----------+
| any_value |
+-----------+
| apple     |
+-----------+

SELECT
  fruit,
  ANY_VALUE(fruit) OVER (ORDER BY LENGTH(fruit) ROWS BETWEEN 1 PRECEDING AND CURRENT ROW) AS any_value
FROM UNNEST(["apple", "banana", "pear"]) as fruit;

+--------+-----------+
| fruit  | any_value |
+--------+-----------+
| pear   | pear      |
| apple  | pear      |
| banana | apple     |
+--------+-----------+

ARRAY_AGG

ARRAY_AGG([DISTINCT] expression [{IGNORE|RESPECT} NULLS]
          [ORDER BY key [{ASC|DESC}] [, ... ]]  [LIMIT n])
[OVER (...)]

說明

傳回 expression 值的 ARRAY。

支援的引數類型

除 ARRAY 以外的所有資料類型。

選用子句

子句會「以下列順序」套用:

  1. OVER:指定範圍。請參閱 Analytic 函式。 這個子句目前與 ARRAY_AGG() 內的其他所有子句都不相容。

  2. DISTINCTexpression 的每個不同值都只會匯總一次到結果中。

  3. IGNORE NULLSRESPECT NULLS:如果指定了 IGNORE NULLS,會從結果中排除 NULL 值。若指定了 RESPECT NULLS 或任何一項都沒有指定,會將 NULL 值包含在結果中 (但是,如果最終查詢結果中包含 NULL 元素,就會產生錯誤)。

  4. ORDER BY:指定值的順序。

    • 針對每個排序金鑰,預設排序方向是 ASC
    • NULL:在 ORDER BY 子句的內容中,NULL 是最小的可能值;也就是說,以 ASC 排序時,NULL 會最先顯示,以 DESC 排序時,NULL 會最後顯示。
    • 浮點資料類型:有關排序與分組,請參閱浮點語意
    • 若也指定 DISTINCT,排序金鑰必須與 expression 相同。
    • 若未指定 ORDER BY,輸出陣列中的元素順序非絕對,這表示您可能會在每次使用這個函式時得到不同的結果。
  5. LIMIT:在結果中指定 expression 輸入的數量上限。     限制 n 必須是常數 INT64。

傳回的資料類型

ARRAY

如果輸入資料列數為零,這個函式會傳回 NULL

範例

SELECT FORMAT("%T", ARRAY_AGG(x)) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+-------------------------+
| array_agg               |
+-------------------------+
| [2, 1, -2, 3, -2, 1, 2] |
+-------------------------+
SELECT FORMAT("%T", ARRAY_AGG(DISTINCT x)) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+---------------+
| array_agg     |
+---------------+
| [2, 1, -2, 3] |
+---------------+
SELECT FORMAT("%T", ARRAY_AGG(x IGNORE NULLS)) AS array_agg
FROM UNNEST([NULL, 1, -2, 3, -2, 1, NULL]) AS x;

+-------------------+
| array_agg         |
+-------------------+
| [1, -2, 3, -2, 1] |
+-------------------+
SELECT FORMAT("%T", ARRAY_AGG(x ORDER BY ABS(x))) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;
+-------------------------+
| array_agg               |
+-------------------------+
| [1, 1, 2, -2, -2, 2, 3] |
+-------------------------+
SELECT FORMAT("%T", ARRAY_AGG(x LIMIT 5)) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+-------------------+
| array_agg         |
+-------------------+
| [2, 1, -2, 3, -2] |
+-------------------+
SELECT FORMAT("%T", ARRAY_AGG(DISTINCT x IGNORE NULLS ORDER BY x LIMIT 2)) AS array_agg
FROM UNNEST([NULL, 1, -2, 3, -2, 1, NULL]) AS x;

+-----------+
| array_agg |
+-----------+
| [-2, 1]   |
+-----------+
SELECT
  x,
  FORMAT("%T", ARRAY_AGG(x) OVER (ORDER BY ABS(x))) AS array_agg
FROM UNNEST([2, 1, -2, 3, -2, 1, 2]) AS x;

+----+-------------------------+
| x  | array_agg               |
+----+-------------------------+
| 1  | [1, 1]                  |
| 1  | [1, 1]                  |
| 2  | [1, 1, 2, -2, -2, 2]    |
| -2 | [1, 1, 2, -2, -2, 2]    |
| -2 | [1, 1, 2, -2, -2, 2]    |
| 2  | [1, 1, 2, -2, -2, 2]    |
| 3  | [1, 1, 2, -2, -2, 2, 3] |
+----+-------------------------+

ARRAY_CONCAT_AGG

ARRAY_CONCAT_AGG(expression  [ORDER BY key [{ASC|DESC}] [, ... ]]  [LIMIT n])

說明

從類型 ARRAY 的 expression 中串連元素,傳回單一 ARRAY 作為結果。這個函式會忽略 NULL 輸入陣列,但沿用非 NULL 輸入陣列中的 NULL 元素 (然而,如果最終查詢結果中包含 NULL 元素,就會產生錯誤)。

支援的引數類型

ARRAY

選用子句

子句會「以下列順序」套用:

  1. ORDER BY:指定值的順序。

    • 對於每個排序金鑰,預設排序方向是 ASC
    • 不支援陣列順序,因此排序金鑰不可與 expression 相同。
    • NULL:在 ORDER BY 子句的內容中,NULL 是最小的可能值;也就是說,以 ASC 排序時,NULL 會最先顯示,以 DESC 排序時,NULL 會最後顯示。
    • 浮點資料類型:有關排序與分組,請參閱浮點語意
    • 若未指定 ORDER BY,輸出陣列中的元素順序非絕對,這表示您可能會在每次使用這個函式時得到不同的結果。
  2. LIMIT:在結果中指定 expression 輸入的數量上限。 限制適用於輸入陣列數,不適用於陣列中的元素數。空陣列會計為 1。NULL 陣列不計入。     限制 n 必須是常數 INT64。

傳回的資料類型

ARRAY

如果輸入資料列數為零或 expression 針對所有資料列評估為 NULL,就會傳回 NULL

範例

SELECT FORMAT("%T", ARRAY_CONCAT_AGG(x)) AS array_concat_agg FROM (
  SELECT [NULL, 1, 2, 3, 4] AS x
  UNION ALL SELECT NULL
  UNION ALL SELECT [5, 6]
  UNION ALL SELECT [7, 8, 9]
);

+-----------------------------------+
| array_concat_agg                  |
+-----------------------------------+
| [NULL, 1, 2, 3, 4, 5, 6, 7, 8, 9] |
+-----------------------------------+

SELECT FORMAT("%T", ARRAY_CONCAT_AGG(x ORDER BY ARRAY_LENGTH(x))) AS array_concat_agg FROM (
  SELECT [NULL, 1, 2, 3, 4] AS x
  UNION ALL SELECT NULL
  UNION ALL SELECT [5, 6]
  UNION ALL SELECT [7, 8, 9]
);

+-----------------------------------+
| array_concat_agg                  |
+-----------------------------------+
| [5, 6, 7, 8, 9, NULL, 1, 2, 3, 4] |
+-----------------------------------+

SELECT FORMAT("%T", ARRAY_CONCAT_AGG(x LIMIT 2)) AS array_concat_agg FROM (
  SELECT [NULL, 1, 2, 3, 4] AS x
  UNION ALL SELECT NULL
  UNION ALL SELECT [5, 6]
  UNION ALL SELECT [7, 8, 9]
);

+--------------------------+
| array_concat_agg         |
+--------------------------+
| [NULL, 1, 2, 3, 4, 5, 6] |
+--------------------------+

SELECT FORMAT("%T", ARRAY_CONCAT_AGG(x ORDER BY ARRAY_LENGTH(x) LIMIT 2)) AS array_concat_agg FROM (
  SELECT [NULL, 1, 2, 3, 4] AS x
  UNION ALL SELECT NULL
  UNION ALL SELECT [5, 6]
  UNION ALL SELECT [7, 8, 9]
);

+------------------+
| array_concat_agg |
+------------------+
| [5, 6, 7, 8, 9]  |
+------------------+

AVG

AVG([DISTINCT] expression)  [OVER (...)]

說明

傳回非 NULL 輸入值的平均數,如果輸入中包含 NaN 就會傳回 NaN

支援的引數類型

任何數字輸入類型,例如 INT64。請注意,針對浮點輸入類型,傳回結果非絕對,這表示您可能會在每次使用這個函式時得到不同的結果。

選用子句

子句會「以下列順序」套用:

  1. OVER:指定範圍。請參閱 Analytic 函式。 這個子句目前與 AVG() 內的其他所有子句都不相容。

  2. DISTINCTexpression 的每個不同值都只會匯總一次到結果中。

傳回的資料類型

  • 如果輸入類型是 NUMERIC,則傳回 NUMERIC。
  • FLOAT64

範例

SELECT AVG(x) as avg
FROM UNNEST([0, 2, NULL, 4, 4, 5]) as x;

+-----+
| avg |
+-----+
| 3   |
+-----+

SELECT AVG(DISTINCT x) AS avg
FROM UNNEST([0, 2, NULL, 4, 4, 5]) AS x;

+------+
| avg  |
+------+
| 2.75 |
+------+

SELECT
  x,
  AVG(x) OVER (ORDER BY x ROWS BETWEEN 1 PRECEDING AND CURRENT ROW) AS avg
FROM UNNEST([0, 2, NULL, 4, 4, 5]) AS x;

+------+------+
| x    | avg  |
+------+------+
| NULL | NULL |
| 0    | 0    |
| 2    | 1    |
| 4    | 3    |
| 4    | 4    |
| 5    | 4.5  |
+------+------+

BIT_AND

BIT_AND(expression)

說明

expression 執行位元 AND 運算並傳回結果。

支援的引數類型

  • INT64

傳回的資料類型

INT64

範例

SELECT BIT_AND(x) as bit_and FROM UNNEST([0xF001, 0x00A1]) as x;

+---------+
| bit_and |
+---------+
| 1       |
+---------+

BIT_OR

BIT_OR(expression)

說明

expression 執行位元 OR 運算並傳回結果。

支援的引數類型

  • INT64

傳回的資料類型

INT64

範例

SELECT BIT_OR(x) as bit_or FROM UNNEST([0xF001, 0x00A1]) as x;

+--------+
| bit_or |
+--------+
| 61601  |
+--------+

BIT_XOR

BIT_XOR([DISTINCT] expression)

說明

expression 執行位元 XOR 運算並傳回結果。

支援的引數類型

  • INT64

選用子句

DISTINCTexpression 的每個不同值都只會匯總一次到結果中。

傳回的資料類型

INT64

範例

SELECT BIT_XOR(x) AS bit_xor FROM UNNEST([5678, 1234]) AS x;

+---------+
| bit_xor |
+---------+
| 4860    |
+---------+

SELECT BIT_XOR(x) AS bit_xor FROM UNNEST([1234, 5678, 1234]) AS x;
+---------+
| bit_xor |
+---------+
| 5678    |
+---------+

SELECT BIT_XOR(DISTINCT x) AS bit_xor FROM UNNEST([1234, 5678, 1234]) AS x;

+---------+
| bit_xor |
+---------+
| 4860    |
+---------+

COUNT

1.

COUNT(*)  [OVER (...)]

2.

COUNT([DISTINCT] expression)  [OVER (...)]

說明

  1. 傳回輸入中的資料列數。
  2. 傳回 expression 評估為 NULL 以外任何值的資料列數。

支援的引數類型

expression 可以是任何資料類型。

選用子句

子句會「以下列順序」套用:

  1. OVER:指定範圍。請參閱 Analytic 函式

  2. DISTINCTexpression 的每個不同值都只會匯總一次到結果中。

傳回資料類型

INT64

範例

SELECT
  COUNT(*) AS count_star,
  COUNT(x) AS count_x,
  COUNT(DISTINCT x) AS count_dist_x
FROM UNNEST([1, 4, NULL, 4, 5]) AS x;

+------------+---------+--------------+
| count_star | count_x | count_dist_x |
+------------+---------+--------------+
| 5          | 4       | 3            |
+------------+---------+--------------+

SELECT
  x,
  COUNT(*) OVER (PARTITION BY MOD(x, 3)) AS count_star,
  COUNT(x) OVER (PARTITION BY MOD(x, 3)) AS count_x,
  COUNT(DISTINCT x) OVER (PARTITION BY MOD(x, 3)) AS count_dist_x
FROM UNNEST([1, 4, NULL, 4, 5]) AS x;

+------+------------+---------+--------------+
| x    | count_star | count_x | count_dist_x |
+------+------------+---------+--------------+
| NULL | 1          | 0       | 0            |
| 1    | 3          | 3       | 2            |
| 4    | 3          | 3       | 2            |
| 4    | 3          | 3       | 2            |
| 5    | 1          | 1       | 1            |
+------+------------+---------+--------------+

COUNTIF

COUNTIF(expression)  [OVER (...)]

說明

針對 expression 傳回 TRUE 值的計數。 如果輸入資料列數為零或 expression 針對所有資料列評估為 FALSE,就會傳回 0

支援的引數類型

BOOL

選用子句

OVER:指定範圍。請參閱 Analytic 函式

傳回資料類型

INT64

範例

SELECT COUNTIF(x<0) AS num_negative, COUNTIF(x>0) AS num_positive
FROM UNNEST([5, -2, 3, 6, -10, NULL, -7, 4, 0]) AS x;

+--------------+--------------+
| num_negative | num_positive |
+--------------+--------------+
| 3            | 4            |
+--------------+--------------+

SELECT
  x,
  COUNTIF(x<0) OVER (ORDER BY ABS(x) ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING) AS num_negative
FROM UNNEST([5, -2, 3, 6, -10, NULL, -7, 4, 0]) AS x;

+------+--------------+
| x    | num_negative |
+------+--------------+
| NULL | 0            |
| 0    | 1            |
| -2   | 1            |
| 3    | 1            |
| 4    | 0            |
| 5    | 0            |
| 6    | 1            |
| -7   | 2            |
| -10  | 2            |
+------+--------------+

LOGICAL_AND

LOGICAL_AND(expression)

說明

傳回所有非 NULL 運算式的邏輯 AND。如果輸入資料列數為零或 expression 針對所有資料列評估為 NULL,就會傳回 NULL

支援的引數類型

BOOL

傳回資料類型

BOOL

範例

SELECT LOGICAL_AND(x) as logical_and FROM UNNEST([true, false, true]) as x;

+-------------+
| logical_and |
+-------------+
| false       |
+-------------+

LOGICAL_OR

LOGICAL_OR(expression)

說明

傳回所有非 NULL 運算式的邏輯 OR。如果輸入資料列數為零或 expression 針對所有資料列評估為 NULL,就會傳回 NULL

支援的引數類型

BOOL

傳回資料類型

BOOL

範例

SELECT LOGICAL_OR(x) as logical_or FROM UNNEST([true, false, true]) as x;

+------------+
| logical_or |
+------------+
| true       |
+------------+

MAX

MAX(expression)  [OVER (...)]

說明

傳回非 NULL 運算式的最大值。如果輸入資料列數為零或 expression 針對所有資料列評估為 NULL,就會傳回 NULL。 如果輸入中包含 NaN,就會傳回 NaN

支援的引數類型

除下列項目外的任何資料類型: ARRAY STRUCT

選用子句

OVER:指定範圍。請參閱 Analytic 函式

傳回資料類型

與用於輸入值的資料類型相同。

範例

SELECT MAX(x) AS max
FROM UNNEST([8, NULL, 37, 4, NULL, 55]) AS x;

+-----+
| max |
+-----+
| 55  |
+-----+

SELECT x, MAX(x) OVER (PARTITION BY MOD(x, 2)) AS max
FROM UNNEST([8, NULL, 37, 4, NULL, 55]) AS x;

+------+------+
| x    | max  |
+------+------+
| NULL | NULL |
| NULL | NULL |
| 8    | 8    |
| 4    | 8    |
| 37   | 55   |
| 55   | 55   |
+------+------+

MIN

MIN(expression)  [OVER (...)]

說明

傳回非 NULL 運算式的最小值。如果輸入資料列數為零或 expression 針對所有資料列評估為 NULL,就會傳回 NULL。 如果輸入中包含 NaN,就會傳回 NaN

支援的引數類型

除下列項目外的任何資料類型: ARRAY STRUCT

選用子句

OVER:指定範圍。請參閱 Analytic 函式

傳回資料類型

與用於輸入值的資料類型相同。

範例

SELECT MIN(x) AS min
FROM UNNEST([8, NULL, 37, 4, NULL, 55]) AS x;

+-----+
| min |
+-----+
| 4   |
+-----+

SELECT x, MIN(x) OVER (PARTITION BY MOD(x, 2)) AS min
FROM UNNEST([8, NULL, 37, 4, NULL, 55]) AS x;

+------+------+
| x    | min  |
+------+------+
| NULL | NULL |
| NULL | NULL |
| 8    | 4    |
| 4    | 4    |
| 37   | 37   |
| 55   | 37   |
+------+------+

STRING_AGG

STRING_AGG([DISTINCT] expression [, delimiter]  [ORDER BY key [{ASC|DESC}] [, ... ]]  [LIMIT n])
[OVER (...)]

說明

傳回由串連非空值取得的值 (STRING 或 BYTES)。

如果指定 delimiter,串連值會由那個分隔符號分隔;否則,會使用逗號作為分隔符號。

支援的引數類型

STRING BYTES

選用子句

子句會「以下列順序」套用:

  1. OVER:指定範圍。請參閱 Analytic 函式。 這個子句目前與 STRING_AGG() 內的其他所有子句都不相容。

  2. DISTINCTexpression 的每個不同值都只會匯總一次到結果中。

  3. ORDER BY:指定值的順序。

    • 針對每個排序金鑰,預設排序方向是 ASC
    • NULL:在 ORDER BY 子句的內容中,NULL 是最小的可能值;也就是說,以 ASC 排序時,NULL 會最先顯示,以 DESC 排序時,NULL 會最後顯示。
    • 浮點資料類型:有關排序與分組,請參閱浮點語意
    • 若也指定 DISTINCT,排序金鑰必須與 expression 相同。
    • 若未指定 ORDER BY,輸出陣列中的元素順序非絕對,這表示您可能會在每次使用這個函式時得到不同的結果。
  4. LIMIT:在結果中指定 expression 輸入的數量上限。 限制適用於輸入字串數,不適用於輸入中的字元或位元組數。空字串會計為 1。NULL 字串不計入。     限制 n 必須是常數 INT64。

傳回資料類型

STRING BYTES

範例

SELECT STRING_AGG(fruit) AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+------------------------+
| string_agg             |
+------------------------+
| apple,pear,banana,pear |
+------------------------+

SELECT STRING_AGG(fruit, " & ") AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+------------------------------+
| string_agg                   |
+------------------------------+
| apple & pear & banana & pear |
+------------------------------+

SELECT STRING_AGG(DISTINCT fruit, " & ") AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+-----------------------+
| string_agg            |
+-----------------------+
| apple & banana & pear |
+-----------------------+

SELECT STRING_AGG(fruit, " & " ORDER BY LENGTH(fruit)) AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+------------------------------+
| string_agg                   |
+------------------------------+
| pear & pear & apple & banana |
+------------------------------+

SELECT STRING_AGG(fruit, " & " LIMIT 2) AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+--------------+
| string_agg   |
+--------------+
| apple & pear |
+--------------+

SELECT STRING_AGG(DISTINCT fruit, " & " ORDER BY fruit DESC LIMIT 2) AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+---------------+
| string_agg    |
+---------------+
| pear & banana |
+---------------+

SELECT
  fruit,
  STRING_AGG(fruit, " & ") OVER (ORDER BY LENGTH(fruit)) AS string_agg
FROM UNNEST(["apple", NULL, "pear", "banana", "pear"]) AS fruit;

+--------+------------------------------+
| fruit  | string_agg                   |
+--------+------------------------------+
| NULL   | NULL                         |
| pear   | pear & pear                  |
| pear   | pear & pear                  |
| apple  | pear & pear & apple          |
| banana | pear & pear & apple & banana |
+--------+------------------------------+

SUM

SUM([DISTINCT] expression)  [OVER (...)]

說明

傳回非空值的總和。

如果運算式是浮點值,總和非絕對,這表示您可能會在每次使用這個函式時得到不同的結果。

支援的引數類型

任何支援的數字資料類型。

選用子句

子句會「以下列順序」套用:

  1. OVER:指定範圍。請參閱 Analytic 函式

  2. DISTINCTexpression 的每個不同值都只會匯總一次到結果中。

傳回資料類型

  • 如果輸入是整數,就會傳回 INT64。

  • 如果輸入類型是 NUMERIC,就會傳回 NUMERIC。

  • 如果輸入是浮點值,就會傳回 FLOAT64。

如果輸入中只包含 NULL,就會傳回 NULL

如果輸入中包含 Inf,就會傳回 Inf

如果輸入中包含 -Inf,就會傳回 -Inf

如果輸入中包含 NaN,就會傳回 NaN

如果輸入中包含 Inf-Inf 的組合,就會傳回 NaN

範例

SELECT SUM(x) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+-----+
| sum |
+-----+
| 25  |
+-----+

SELECT SUM(DISTINCT x) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+-----+
| sum |
+-----+
| 15  |
+-----+

SELECT
  x,
  SUM(x) OVER (PARTITION BY MOD(x, 3)) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+---+-----+
| x | sum |
+---+-----+
| 3 | 6   |
| 3 | 6   |
| 1 | 10  |
| 4 | 10  |
| 4 | 10  |
| 1 | 10  |
| 2 | 9   |
| 5 | 9   |
| 2 | 9   |
+---+-----+

SELECT
  x,
  SUM(DISTINCT x) OVER (PARTITION BY MOD(x, 3)) AS sum
FROM UNNEST([1, 2, 3, 4, 5, 4, 3, 2, 1]) AS x;

+---+-----+
| x | sum |
+---+-----+
| 3 | 3   |
| 3 | 3   |
| 1 | 5   |
| 4 | 5   |
| 4 | 5   |
| 1 | 5   |
| 2 | 7   |
| 5 | 7   |
| 2 | 7   |
+---+-----+

Statistical Aggregate 函式

BigQuery 支援下列 statistical aggregate 函式。

CORR

CORR(X1, X2)  [OVER (...)]

說明

傳回一組數字對組合的皮爾森相關係數。對於每一對數字,第一個數字是相依變數,第二個數字是獨立變數。 傳回結果介於 -11 之間。0 的結果表示不相關。

這個函式會忽略包含一或多個 NULL 值的任何輸入對。如果有兩個以下沒有 NULL 值的輸入對,這個函式會傳回 NULL。

支援的輸入類型

FLOAT64

選用子句

OVER:指定範圍。請參閱 Analytic 函式

傳回資料類型

FLOAT64

COVAR_POP

COVAR_POP(X1, X2)  [OVER (...)]

說明

傳回一組數字對的母體共變異數。第一個數字是相依變數;第二個數字是獨立變數。 傳回結果介於 -Inf+Inf 之間。

這個函式會忽略包含一或多個 NULL 值的任何輸入對。如果沒有不含 NULL 值的輸入對,這個函式會傳回 NULL。如果正好有一個沒有 NULL 值的輸入對,這個函式會傳回 0。

支援的輸入類型

FLOAT64

選用子句

OVER:指定範圍。請參閱 Analytic 函式

傳回資料類型

FLOAT64

COVAR_SAMP

COVAR_SAMP(X1, X2)  [OVER (...)]

說明

傳回一組數字對的範例共變異數。第一個數字是相依變數;第二個數字是獨立變數。傳回結果介於 -Inf+Inf 之間。

這個函式會忽略包含一或多個 NULL 值的任何輸入對。如果有兩個以下沒有 NULL 值的輸入對,這個函式會傳回 NULL。

支援的輸入類型

FLOAT64

選用子句

OVER:指定範圍。請參閱 Analytic 函式

傳回資料類型

FLOAT64

STDDEV_POP

STDDEV_POP([DISTINCT] expression)  [OVER (...)]

說明

傳回值的母體 (偏差) 標準差。傳回結果介於 0+Inf 之間。

這個函式會忽略任何 NULL 輸入。如果忽略所有輸入,這個函式會傳回 NULL。

如果這個函式收到一個非 NULL 輸入,它就會傳回 0

支援的輸入類型

FLOAT64

選用子句

子句會「以下列順序」套用:

  1. OVER:指定範圍。請參閱 Analytic 函式。 這個子句目前與 STDDEV_POP() 內的其他所有子句都不相容。

  2. DISTINCTexpression 的每個不同值都只會匯總一次到結果中。

傳回資料類型

FLOAT64

STDDEV_SAMP

STDDEV_SAMP([DISTINCT] expression)  [OVER (...)]

說明

傳回值的範例 (無偏差) 標準差。傳回結果介於 0+Inf 之間。

這個函式會忽略任何 NULL 輸入。如果有兩個以下非 NULL 輸入,這個函式會傳回 NULL。

支援的輸入類型

FLOAT64

選用子句

子句會「以下列順序」套用:

  1. OVER:指定範圍。請參閱 Analytic 函式。 這個子句目前與 STDDEV_SAMP() 內的其他所有子句都不相容。

  2. DISTINCTexpression 的每個不同值都只會匯總一次到結果中。

傳回資料類型

FLOAT64

STDDEV

STDDEV([DISTINCT] expression)  [OVER (...)]

說明

STDDEV_SAMP 的別名。

VAR_POP

VAR_POP([DISTINCT] expression)  [OVER (...)]

說明

傳回值的母體 (偏差) 變異數。傳回結果介於 0+Inf 之間。

這個函式會忽略任何 NULL 輸入。如果忽略所有輸入,這個函式會傳回 NULL。

如果這個函式收到一個非 NULL 輸入,它就會傳回 0

支援的輸入類型

FLOAT64

選用子句

子句會「以下列順序」套用:

  1. OVER:指定範圍。請參閱 Analytic 函式。 這個子句目前與 VAR_POP() 內的其他所有子句都不相容。

  2. DISTINCTexpression 的每個不同值都只會匯總一次到結果中。

傳回資料類型

FLOAT64

VAR_SAMP

VAR_SAMP([DISTINCT] expression)  [OVER (...)]

說明

傳回值的範例 (非偏差) 變異數。傳回結果介於 0+Inf 之間。

這個函式會忽略任何 NULL 輸入。如果有兩個以下非 NULL 輸入,這個函式會傳回 NULL。

支援的輸入類型

FLOAT64

選用子句

子句會「以下列順序」套用:

  1. OVER:指定範圍。請參閱 Analytic 函式。 這個子句目前與 VAR_SAMP() 內的其他所有子句都不相容。

  2. DISTINCTexpression 的每個不同值都只會匯總一次到結果中。

傳回資料類型

FLOAT64

VARIANCE

VARIANCE([DISTINCT] expression)  [OVER (...)]

說明

VAR_SAMP 的別名。

Approximate Aggregate 函式

Approximate aggregate 函式在記憶體用量與時間方面具有可調整彈性,但是會產生近似結果,而非確切結果。如需更多背景資訊,請參閱近似匯總

APPROX_COUNT_DISTINCT

APPROX_COUNT_DISTINCT(expression)

說明

傳回 COUNT(DISTINCT expression) 的近似結果。傳回的值是統計估計結果—不一定是實際值。

這個函式的準確度不如 COUNT(DISTINCT expression),但對大量輸入的執行效果較佳。

支援的引數類型

下列項目外的任何資料類型: ARRAY STRUCT

傳回的資料類型

INT64

範例

SELECT APPROX_COUNT_DISTINCT(x) as approx_distinct
FROM UNNEST([0, 1, 1, 2, 3, 5]) as x;

+-----------------+
| approx_distinct |
+-----------------+
| 5               |
+-----------------+

APPROX_QUANTILES

APPROX_QUANTILES([DISTINCT] expression, number [{IGNORE|RESPECT} NULLS])

說明

傳回一組 expression 值的近似邊界,其中 number 代表要建立的分位數數量。這個函式會傳回 number + 1 個元素的陣列,其中第一個元素是近似最小值,最後一個元素是近似最大值。

支援的引數類型

expression 可以是任何支援的資料類型,但下列資料類型除外ARRAY STRUCT

number 必須是 INT64。

選用子句

子句會「以下列順序」套用:

  1. DISTINCTexpression 的每個不同值都只會匯總一次到結果中。

  2. IGNORE NULLSRESPECT NULLS:若指定了 IGNORE NULLS 或任何一項都沒有指定,會從結果中排除 NULL 值。若指定了 RESPECT NULLS,會將 NULL 值包含在結果中 (但是,如果最終查詢結果中包含 NULL 元素,就會產生錯誤)。

傳回的資料類型

expression 參數指定類型的 ARRAY。

如果輸入資料列數為零或 NULL 針對所有資料列評估為 NULL,就會傳回 expression

範例

SELECT APPROX_QUANTILES(x, 2) AS approx_quantiles
FROM UNNEST([NULL, NULL, 1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [1, 5, 10]       |
+------------------+

SELECT APPROX_QUANTILES(x, 100)[OFFSET(90)] AS percentile_90
FROM UNNEST([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) AS x;

+---------------+
| percentile_90 |
+---------------+
| 9             |
+---------------+

SELECT APPROX_QUANTILES(DISTINCT x, 2) AS approx_quantiles
FROM UNNEST([NULL, NULL, 1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [1, 6, 10]       |
+------------------+

SELECT FORMAT("%T", APPROX_QUANTILES(x, 2 RESPECT NULLS)) AS approx_quantiles
FROM UNNEST([NULL, NULL, 1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [NULL, 4, 10]    |
+------------------+

SELECT FORMAT("%T", APPROX_QUANTILES(DISTINCT x, 2 RESPECT NULLS)) AS approx_quantiles
FROM UNNEST([NULL, NULL, 1, 1, 1, 4, 5, 6, 7, 8, 9, 10]) AS x;

+------------------+
| approx_quantiles |
+------------------+
| [NULL, 6, 10]    |
+------------------+

APPROX_TOP_COUNT

APPROX_TOP_COUNT(expression, number)

說明

傳回 expression 的近似最前幾個元素。number 參數指定了傳回的元素數目。

支援的引數類型

expression 可以是 GROUP BY 子句支援的任何資料類型。

number 必須是 INT64。

傳回的資料類型

STRUCT 類型的 ARRAY。STRUCT 包含兩個欄位。第一個欄位 (名為 value) 中包含 input 值。第二個欄位 (名為 count) 中包含指定傳回該值次數的 INT64。

如果輸入資料列數為零,就會傳回 NULL

範例

SELECT APPROX_TOP_COUNT(x, 2) as approx_top_count
FROM UNNEST(["apple", "apple", "pear", "pear", "pear", "banana"]) as x;

+-------------------------+
| approx_top_count        |
+-------------------------+
| [{pear, 3}, {apple, 2}] |
+-------------------------+

NULL 處理

APPROX_TOP_COUNT 不會忽略輸入中的 NULL。例如:

SELECT APPROX_TOP_COUNT(x, 2) as approx_top_count
FROM UNNEST([NULL, "pear", "pear", "pear", "apple", NULL]) as x;

+------------------------+
| approx_top_count       |
+------------------------+
| [{pear, 3}, {NULL, 2}] |
+------------------------+

APPROX_TOP_SUM

APPROX_TOP_SUM(expression, weight, number)

說明

根據指派的 weight 的總和,傳回 expression 的近似最前幾個元素。number 參數指定了傳回的元素數目。

如果 weight 輸入是負數或 NaN,這個函式就會傳回錯誤。

支援的引數類型

expression 可以是 GROUP BY 子句支援的任何資料類型。

weight 必須是下列其中一項:

  • INT64
  • FLOAT64

number 必須是 INT64。

傳回的資料類型

STRUCT 類型的 ARRAY。 STRUCT 包含兩個欄位:valuesumvalue 欄位中包含輸入運算式的值。sum 欄位的類型與 weight 相同,是與 value 欄位相關聯之輸入權重的近似總和。

如果輸入資料列數為零,就會傳回 NULL

範例

SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([
  STRUCT("apple" AS x, 3 AS weight),
  ("pear", 2),
  ("apple", 0),
  ("banana", 5),
  ("pear", 4)
]);

+--------------------------+
| approx_top_sum           |
+--------------------------+
| [{pear, 6}, {banana, 5}] |
+--------------------------+

NULL 處理

APPROX_TOP_SUM 不會忽略 expressionweight 參數的 NULL 值。

SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([STRUCT("apple" AS x, NULL AS weight), ("pear", 0), ("pear", NULL)]);

+----------------------------+
| approx_top_sum             |
+----------------------------+
| [{pear, 0}, {apple, NULL}] |
+----------------------------+
SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([STRUCT("apple" AS x, 0 AS weight), (NULL, 2)]);

+-------------------------+
| approx_top_sum          |
+-------------------------+
| [{NULL, 2}, {apple, 0}] |
+-------------------------+
SELECT APPROX_TOP_SUM(x, weight, 2) AS approx_top_sum FROM
UNNEST([STRUCT("apple" AS x, 0 AS weight), (NULL, NULL)]);

+----------------------------+
| approx_top_sum             |
+----------------------------+
| [{apple, 0}, {NULL, NULL}] |
+----------------------------+

HyperLogLog++ 函式

BigQuery 支援使用 HyperLogLog++ 演算法的下列 approximate aggregate 函式。如需 approximate aggregate 函式運作方式的說明,請參閱近似匯總

HLL_COUNT.INIT

HLL_COUNT.INIT(input [, precision])

說明

這個匯總函式會取用一或多個 input 值,並將這些值匯總至 HyperLogLog++ 草圖。每個草圖都以 BYTES 資料類型表示。然後您可以使用 HLL_COUNT.MERGEHLL_COUNT.MERGE_PARTIAL 合併這些草圖。如果不需要合併,則可使用 HLL_COUNT.EXTRACT 從草圖中擷取不同值的最終計數。

input 可以是下列其中一項:

  • INT64
  • STRING
  • BYTES

這個函式支援選用參數 precision。這個參數定義了估計處理草圖或將草圖儲存到磁碟上所需要之額外記憶體成本的準確率。下表顯示允許的精確度值、每個群組的最大草圖大小,以及典型精確度的信賴區間 (CI):

精確度 最大草圖大小 (KiB) CI CI CI
10 1 ±1.63% ±3.25% ±6.50%
11 2 ±1.15% ±2.30% ±4.60%
12 4 ±0.81% ±1.63% ±3.25%
13 8 ±0.57% ±1.15% ±1.72%
14 16 ±0.41% ±0.81% ±1.22%
15 (預設) 32 ±0.29% ±0.57% ±0.86%
16 64 ±0.20% ±0.41% ±0.61%
17 128 ±0.14% ±0.29% ±0.43%
18 256 ±0.10% ±0.20% ±0.41%
19 512 ±0.07% ±0.14% ±0.29%
20 1024 ±0.05% ±0.10% ±0.20%
21 2048 ±0.04% ±0.07% ±0.14%
22 4096 ±0.03% ±0.05% ±0.10%
23 8192 ±0.02% ±0.04% ±0.07%
24 16384 ±0.01% ±0.03% ±0.05%

如果輸入是 NULL,這個函式會傳回 NULL。

如需詳細資訊,請參閱 HyperLogLog 實踐:頂尖基數估計演算法的演算工程

支援的輸入類型

BYTES

傳回類型

BYTES

範例

SELECT
  HLL_COUNT.INIT(respondent) AS respondents_hll,
  flavor,
  country
FROM UNNEST([
  STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
  (1, "Chocolate", "CH"),
  (2, "Chocolate", "US"),
  (2, "Strawberry", "US")])
GROUP BY flavor, country;

HLL_COUNT.MERGE

HLL_COUNT.MERGE(sketch)

說明

透過計算聯集來傳回數個 HyperLogLog++ 組草圖基數的 aggregate 函式。

每個 sketch 都必須具有相同的精確度,並對相同類型進行初始化。嘗試合併具有不同精確度的草圖,或針對不同的類型合併草圖,會導致產生錯誤。例如,您無法合併從 INT64 資料初始化的草圖與從 STRING 資料初始化的草圖。

合併草圖時,這個函式會忽略 NULL 值。如果零個資料列或只有 NULL 值發生合併,函式會傳回 0

支援的輸入類型

BYTES

傳回類型

INT64

範例

SELECT HLL_COUNT.MERGE(respondents_hll) AS num_respondents, flavor
FROM (
  SELECT
    HLL_COUNT.INIT(respondent) AS respondents_hll,
    flavor,
    country
  FROM UNNEST([
    STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
    (1, "Chocolate", "CH"),
    (2, "Chocolate", "US"),
    (2, "Strawberry", "US")])
  GROUP BY flavor, country)
GROUP BY flavor;

HLL_COUNT.MERGE_PARTIAL

HLL_COUNT.MERGE_PARTIAL(sketch)

說明

這個匯總函式會取用一或多個 HyperLogLog++ sketch 輸入,並將這些輸入匯總至新草圖。

如果沒有輸入,或所有輸入都是 NULL,這個函式會傳回 NULL。

支援的輸入類型

BYTES

傳回類型

BYTES

範例

SELECT HLL_COUNT.MERGE_PARTIAL(respondents_hll) AS num_respondents, flavor
FROM (
  SELECT
    HLL_COUNT.INIT(respondent) AS respondents_hll,
    flavor,
    country
  FROM UNNEST([
    STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
    (1, "Chocolate", "CH"),
    (2, "Chocolate", "US"),
    (2, "Strawberry", "US")])
  GROUP BY flavor, country)
GROUP BY flavor;

HLL_COUNT.EXTRACT

HLL_COUNT.EXTRACT(sketch)

說明

擷取單一 HyperLogLog++ 草圖之基數估計的純量函式。

如果 sketch 是 NULL,這個函式會傳回 0 的基數估計。

支援的輸入類型

BYTES

傳回類型

INT64

範例

SELECT
  flavor,
  country,
  HLL_COUNT.EXTRACT(respondents_hll) AS num_respondents
FROM (
  SELECT
    HLL_COUNT.INIT(respondent) AS respondents_hll,
    flavor,
    country
  FROM UNNEST([
    STRUCT(1 AS respondent, "Vanilla" AS flavor, "CH" AS country),
    (1, "Chocolate", "CH"),
    (2, "Chocolate", "US"),
    (2, "Strawberry", "US")])
  GROUP BY flavor, country);

+------------+---------+-----------------+
| flavor     | country | num_respondents |
+------------+---------+-----------------+
| Vanilla    | CH      | 1               |
| Chocolate  | CH      | 1               |
| Chocolate  | US      | 1               |
| Strawberry | US      | 1               |
+------------+---------+-----------------+

Numbering 函式

下列各節說明 BigQuery 支援的 numbering 函式。Numbering 函式是 analytic 函式的子集。如需 analytic 函式的運作說明,請參閱 Analytic 函式概念。如需 numbering 函式的運作說明,請參閱 Numbering 函式概念

OVER 子句需求:

  • PARTITION BY:選用。
  • ORDER BY:必要,ROW_NUMBER() 除外。
  • window_frame_clause:不允許。

RANK

說明

傳回排序分區內每個資料列的序數排名 (從 1 開始編號)。所有對等資料列都會收到相同的排名值。下一資料列或下一組對等資料列會收到排名值,該值會按具有先前排名值的對等體數遞增,而不是像 DENSE_RANK 一律遞增 1。

支援的引數類型

INT64

DENSE_RANK

說明

傳回界線分區內每個資料列的序數排名 (從 1 開始編號)。所有對等資料列都會收到相同的排名值,後續排名值會按 1 遞增。

支援的引數類型

INT64

PERCENT_RANK

說明

傳回定義為 (RK-1)/(NR-1) 的資料列百分位數排名,其中 RK 是資料列的 RANK,NR 是分區中的資料列數。如果 NR=1 就會傳回 0。

支援的引數類型

FLOAT64

CUME_DIST

說明

傳回定義為 NP/NR 的資料列相對排名。NP 定義為在目前資料列之前或與目前資料列對等的資料列數。NR 是分區中的資料列數。

支援的引數類型

FLOAT64

NTILE

NTILE(constant_integer_expression)

說明

這個函式根據資料列排序將資料列分成 constant_integer_expression 個值區,並傳回指派給每個資料列的值區數值 (從 1 開始編號)。值區中的資料列數最多只能差 1。 餘數值 (資料列數除以值區後的餘數) 會為每個值區各分配一個,從值區 1 開始。如果 constant_integer_expression 評估為 NULL、0 或負值,就會產生錯誤。

支援的引數類型

INT64

ROW_NUMBER

說明

不需要 ORDER BY 子句。針對每個排序的分區傳回每個資料列的順序資料列序數 (以 1 為基礎)。若未指定 ORDER BY 子句,結果就非絕對。

支援的引數類型

INT64

Bit 函式

BigQuery 支援下列 bit 函式。

BIT_COUNT

BIT_COUNT(expression)

說明

輸入 expression 必須是整數或 BYTES。

傳回在輸入 expression 中設定的位元數。如為正負號整數,這是兩個互補形式中的位元數。

傳回資料類型

INT64

範例

SELECT a, BIT_COUNT(a) AS a_bits, FORMAT("%T", b) as b, BIT_COUNT(b) AS b_bits
FROM UNNEST([
  STRUCT(0 AS a, b'' AS b), (0, b'\x00'), (5, b'\x05'), (8, b'\x00\x08'),
  (0xFFFF, b'\xFF\xFF'), (-2, b'\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFE'),
  (-1, b'\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF'),
  (NULL, b'\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF')
]) AS x;

+-------+--------+---------------------------------------------+--------+
| a     | a_bits | b                                           | b_bits |
+-------+--------+---------------------------------------------+--------+
| 0     | 0      | b""                                         | 0      |
| 0     | 0      | b"\x00"                                     | 0      |
| 5     | 2      | b"\x05"                                     | 2      |
| 8     | 1      | b"\x00\x08"                                 | 1      |
| 65535 | 16     | b"\xff\xff"                                 | 16     |
| -2    | 63     | b"\xff\xff\xff\xff\xff\xff\xff\xfe"         | 63     |
| -1    | 64     | b"\xff\xff\xff\xff\xff\xff\xff\xff"         | 64     |
| NULL  | NULL   | b"\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff" | 80     |
+-------+--------+---------------------------------------------+--------+

Mathematical 函式

所有 mathematical 函式都具有下列行為:

  • 如果任何輸入參數是 NULL,就會傳回 NULL
  • 如果任何引數是 NaN,就會傳回 NaN

ABS

ABS(X)

說明

計算絕對值。如果引數是整數,且輸出值無法以相同類型表示,就會傳回錯誤;只有沒有正表示的最大負輸入值會發生這種情形。若為 +/-inf 引數,則會傳回 +inf

SIGN

SIGN(X)

說明

分別針對負、零與正引數傳回 -1、0 或 +1。若為浮點引數,此函式不會區別正負零。若為 NaN 引數,則傳回 NaN

IS_INF

IS_INF(X)

說明

如果值是正數或負無限大,則傳回 TRUE。若為 NULL 輸入,則傳回 NULL

IS_NAN

IS_NAN(X)

說明

如果值是 NaN 值,則傳回 TRUE。若為 NULL 輸入,則傳回 NULL

IEEE_DIVIDE

IEEE_DIVIDE(X, Y)

說明

將 X 除以 Y;此函式永不失敗。傳回 FLOAT64。與除法運算子 (/) 不同,這個函式不會產生除以零或溢位錯誤。

特殊案例:

  • 如果結果溢位,就會傳回 +/-inf
  • 如果 Y=0 且 X=0,就會傳回 NaN
  • 如果 Y=0 且 X!=0,就會傳回 +/-inf
  • 如果 X = +/-inf 且 Y = +/-inf,就會傳回 NaN

下表將進一步說明 IEEE_DIVIDE 的行為。

IEEE_DIVIDE 的特殊案例

下表列出 IEEE_DIVIDE 的特殊案例。

分子資料類型 (X) 分母資料類型 (Y) 結果值
除了 0 以外的任何值 0 +/-inf
0 0 NaN
0 NaN NaN
NaN 0 NaN
+/-inf +/-inf NaN

RAND

RAND()

說明

在 [0, 1) 的範圍中產生 FLOAT64 類型的虛擬亂數值,包含 0 但排除 1。

SQRT

SQRT(X)

說明

計算 X 的平方根。如果 X 小於 0,就會產生錯誤。如果 X 是 +inf 就會傳回 +inf

POW

POW(X, Y)

說明

傳回 X 值的 Y 次方。如果結果欠位且無法表示,函式就會傳回零值。如果出現下列其中一種情況,就會傳回錯誤:

  • X 是小於 0 的有限值,且 Y 是非整數
  • X 是 0,且 Y 是小於 0 的有限值

下表將進一步說明 POW() 的行為。

POWER

POWER(X, Y)

說明

POW() 的同義詞。

POW(X, Y)POWER(X, Y) 的特殊案例

以下是 POW(X, Y)POWER(X, Y) 的特殊案例。

X Y POW(X, Y) 或 POWER(X, Y)
1.0 包括 NaN 在內的任何值 1.0
包括 NaN 在內的任何值 0 1.0
-1.0 +/-inf 1.0
ABS(X) < 1 -inf +inf
ABS(X) > 1 -inf 0
ABS(X) < 1 +inf 0
ABS(X) > 1 +inf +inf
-inf Y < 0 0
-inf Y > 0 如果 Y 是奇數整數就是 -inf,否則就是 +inf
+inf Y < 0 0
+inf Y > 0 +inf

EXP

EXP(X)

說明

計算 X 的 e 次方,也稱為自然指數函式。如果結果欠位,此函式就會傳回零。如果結果溢位,就會產生錯誤。如果 X 是 +/-inf,則會傳回 +inf 或 0。

LN

LN(X)

說明

計算 X 的自然對數。如果 X 小於或等於零,就會產生錯誤。如果 X 是 +inf,此函式會傳回 +inf

LOG

LOG(X [, Y])

說明

如果只有 X,則 LOGLN 的同義詞。如果還有 Y,LOG 就會計算以 Y 為底數的 X 對數。如有下列情況,則會產生錯誤:

  • X 小於或等於零
  • Y 是 1.0
  • Y 小於或等於零。

下表將進一步說明 LOG(X, Y) 的行為。

LOG(X, Y) 的特殊案例

X Y LOG(X, Y)
-inf 任何值 NaN
任何值 +inf NaN
+inf 0.0 Y < 1.0 -inf
+inf Y > 1.0 +inf

LOG10

LOG10(X)

說明

LOG 類似,但會計算以 10 為底數的對數。

GREATEST

GREATEST(X1,...,XN)

說明

如果任何輸入是 NULL,就會傳回 NULL。否則,如果任何輸入是 NaN,則會傳回 NaN。不然就會根據 < 比較來傳回 X1,...,XN 之間的最大值。

LEAST

LEAST(X1,...,XN)

說明

如果任何輸入是 NULL,就會傳回 NULL。如果任何輸入是 NaN,就會傳回 NaN。不然就會根據 > 比較來傳回 X1,...,XN 之間的最小值。

DIV

DIV(X, Y)

說明

傳回整數 X 除以 Y 的結果。除以零會傳回錯誤。除以 -1 可能會溢位。可能結果類型請見下表。

SAFE_DIVIDE

SAFE_DIVIDE(X, Y)

說明

相當於除法運算子 (/),但如果發生錯誤,例如除以零錯誤,就會傳回 NULL

SAFE_MULTIPLY

SAFE_MULTIPLY(X, Y)

說明

相當於乘法運算子 (*),但如果發生溢位,就會傳回 NULL

SAFE_NEGATE

SAFE_NEGATE(X)

說明

相當於一元減運算子 (-),但如果發生溢位,就會傳回 NULL

SAFE_ADD

SAFE_ADD(X, Y)

說明

相當於加法運算子 (+),但如果發生溢位,就會傳回 NULL

SAFE_SUBTRACT

SAFE_SUBTRACT(X, Y)

說明

相當於減法運算子 (-),但如果發生溢位,就會傳回 NULL

MOD

MOD(X, Y)

說明

Modulo 函式:傳回 X 除以 Y 的餘數。傳回值的正負號與 X 相同。如果 Y 是零就會產生錯誤。可能結果類型請見下表。

ROUND

ROUND(X [, N])

說明

如果只有 X,則 ROUND 會將 X 進位或捨去至最接近的整數。如果有 N,則 ROUND 會將 X 進位或捨去至小數點後的第 N 位數。如果 N 是負值,則 ROUND 會將數字進位或捨去至小數點左側的第一位數。原則為四捨五入。如果發生溢位,就會產生錯誤。

TRUNC

TRUNC(X [, N])

說明

如果只有 X,則 TRUNC 會將 X 進位或捨去至最接近的整數,且其絕對值不大於 X 的絕對值。如果還有 N,則 TRUNC 的作用類似 ROUND(X, N),但一律無條件捨去且絕不會溢位。

CEIL

CEIL(X)

說明

傳回比 X 大的最小整數值 (類型為 FLOAT64)。

CEILING

CEILING(X)

說明

CEIL(X) 的同義詞

FLOOR

FLOOR(X)

說明

傳回比 X 小的最大整數值 (類型為 FLOAT64)。

Rounding 函式行為範例

BigQuery rounding 函式的範例行為:

輸入「X」 ROUND(X) TRUNC(X) CEIL(X) FLOOR(X)
2.0 2.0 2.0 2.0 2.0
2.3 2.0 2.0 3.0 2.0
2.8 3.0 2.0 3.0 2.0
2.5 3.0 2.0 3.0 2.0
-2.3 -2.0 -2.0 -2.0 -3.0
-2.8 -3.0 -2.0 -2.0 -3.0
-2.5 -3.0 -2.0 -2.0 -3.0
0 0 0 0 0
+/-inf +/-inf +/-inf +/-inf +/-inf
NaN NaN NaN NaN NaN

COS

COS(X)

說明

計算 X 的餘弦,其中 X 的單位為弧度。此函式必會傳回值。

COSH

COSH(X)

說明

計算 X 的雙曲餘弦,其中 X 的單位為弧度。 如果發生溢位,就會產生錯誤。

ACOS

ACOS(X)

說明

計算 X 的反餘弦的主值。傳回值在範圍 [0,π] 中。如果 X 是 [-1, 1] 範圍外的值,就會產生錯誤。

ACOSH

ACOSH(X)

說明

計算 X 的反雙曲餘弦。如果 X 是小於 1 的值,就會產生錯誤。

SIN

SIN(X)

說明

計算 X 的正弦,其中 X 的單位為弧度。此函式必會傳回值。

SINH

SINH(X)

說明

計算 X 的雙曲正弦,其中 X 的單位為弧度。如果發生溢位,就會產生錯誤。

ASIN

ASIN(X)

說明

計算 X 的反正弦主值。傳回值在範圍 [-π/2,π/2] 中。如果 X 是 [-1, 1] 範圍外的值,就會產生錯誤。

ASINH

ASINH(X)

說明

計算 X 的反雙曲正弦。此函式不會失敗。

TAN

TAN(X)

說明

計算 X 的正切,其中 X 的單位為弧度。如果發生溢位,就會產生錯誤。

TANH

TANH(X)

說明

計算 X 的雙曲正切,其中 X 的單位為弧度。此函式必會傳回值。

ATAN

ATAN(X)

說明

計算 X 反正切的主值。傳回值在範圍 [-π/2,π/2] 中。此函式必會傳回值。

ATANH

ATANH(X)

說明

計算 X 的反雙曲正切。如果 X 在 [-1, 1] 範圍外,就會產生錯誤。

ATAN2

ATAN2(Y, X)

說明

使用兩個引數的正負號計算 Y/X 的反正切主值,藉以確定象限。傳回值在 [-π,π] 範圍中。下表將進一步說明這個函式的行為。

ATAN2() 的特殊案例

Y X ATAN2(Y, X)
NaN 任何值 NaN
任何值 NaN NaN
0 0 視 X 與 Y 的正負號而定,為 0、π 或 -π
有限值 -inf 視 Y 的正負號而定,為 π 或 -π
有限值 +inf 0
+/-inf 有限值 視 Y 的正負號而定,為 π/2 或 -π/2
+/-inf -inf 視 Y 的正負號而定,為 ¾π 或 -¾π
+/-inf +inf 視 Y 的正負號而定,為 π/4 或 -π/4

trigonometric 與 hyperbolic rounding 函式的特殊案例

X COS(X) COSH(X) ACOS(X) ACOSH(X) SIN(X) SINH(X) ASIN(X) ASINH(X) TAN(X) TANH(X) ATAN(X) ATANH(X)
+/-inf NaN =+inf NaN =+inf NaN =+inf NaN =+inf NaN =+1.0 π/2 NaN
-inf NaN =+inf NaN NaN NaN -inf NaN -inf NaN -1.0 -π/2 NaN
NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN NaN

以下各節說明 BigQuery 支援的 navigation 函式。Navigation 函式是 analytic 函式的子集。如需 analytic 函式的運作說明,請參閱 Analytic 函式概念。如需 navigation 函式的運作說明,請參閱 Navigation 函式概念

FIRST_VALUE

FIRST_VALUE (value_expression [{RESPECT | IGNORE} NULLS])

說明

針對目前界線範圍中的第一個資料列傳回 value_expression 的值。

除非存在 IGNORE NULLS,否則這個函式會在計算中包含 NULL 值。如果存在 IGNORE NULLS,函式會從計算中排除 NULL 值。

支援的引數類型

value_expression 可以是運算式能夠傳回的任何資料類型。

傳回資料類型

不限

範例

以下範例會計算各個組別的最快時間。

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', fastest_time) AS fastest_time,
  TIMESTAMP_DIFF(finish_time, fastest_time, SECOND) AS delta_in_seconds
FROM (
  SELECT name,
  finish_time,
  division,
  FIRST_VALUE(finish_time)
    OVER (PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS fastest_time
  FROM finishers);

+-----------------+-------------+----------+--------------+------------------+
| name            | finish_time | division | fastest_time | delta_in_seconds |
+-----------------+-------------+----------+--------------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | 0                |
| Sophia Liu      | 02:51:45    | F30-34   | 02:51:45     | 0                |
| Nikki Leith     | 02:59:01    | F30-34   | 02:51:45     | 436              |
| Jen Edwards     | 03:06:36    | F30-34   | 02:51:45     | 891              |
| Meghan Lederer  | 03:07:41    | F30-34   | 02:51:45     | 956              |
| Lauren Reasoner | 03:10:14    | F30-34   | 02:51:45     | 1109             |
| Lisa Stelzner   | 02:54:11    | F35-39   | 02:54:11     | 0                |
| Lauren Matthews | 03:01:17    | F35-39   | 02:54:11     | 426              |
| Desiree Berry   | 03:05:42    | F35-39   | 02:54:11     | 691              |
| Suzy Slane      | 03:06:24    | F35-39   | 02:54:11     | 733              |
+-----------------+-------------+----------+--------------+------------------+

LAST_VALUE

LAST_VALUE (value_expression [{RESPECT | IGNORE} NULLS])

說明

針對目前界線範圍中的最後一個資料列傳回 value_expression 的值。

除非存在 NULL,否則這個函式會在計算中包含 IGNORE NULLS 值。如果存在 IGNORE NULLS,函式會從計算中排除 NULL 值。

支援的引數類型

value_expression 可以是運算式能夠傳回的任何資料類型。

傳回資料類型

不限

範例

以下範例會計算各個組別的最慢時間。

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', slowest_time) AS slowest_time,
  TIMESTAMP_DIFF(slowest_time, finish_time, SECOND) AS delta_in_seconds
FROM (
  SELECT name,
  finish_time,
  division,
  LAST_VALUE(finish_time)
    OVER (PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS slowest_time
  FROM finishers);

+-----------------+-------------+----------+--------------+------------------+
| name            | finish_time | division | slowest_time | delta_in_seconds |
+-----------------+-------------+----------+--------------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | 0                |
| Sophia Liu      | 02:51:45    | F30-34   | 03:10:14     | 1109             |
| Nikki Leith     | 02:59:01    | F30-34   | 03:10:14     | 673              |
| Jen Edwards     | 03:06:36    | F30-34   | 03:10:14     | 218              |
| Meghan Lederer  | 03:07:41    | F30-34   | 03:10:14     | 153              |
| Lauren Reasoner | 03:10:14    | F30-34   | 03:10:14     | 0                |
| Lisa Stelzner   | 02:54:11    | F35-39   | 03:06:24     | 733              |
| Lauren Matthews | 03:01:17    | F35-39   | 03:06:24     | 307              |
| Desiree Berry   | 03:05:42    | F35-39   | 03:06:24     | 42               |
| Suzy Slane      | 03:06:24    | F35-39   | 03:06:24     | 0                |
+-----------------+-------------+----------+--------------+------------------+

NTH_VALUE

NTH_VALUE (value_expression, constant_integer_expression [{RESPECT | IGNORE} NULLS])

說明

在目前界線範圍的第 N 個資料列處傳回 value_expression 的值,其中第 N 個由 constant_integer_expression 定義。如果沒有此資料列,就傳回 NULL。

除非存在 NULL,否則這個函式會在計算中包含 IGNORE NULLS 值。如果存在 IGNORE NULLS,函式會從計算中排除 NULL 值。

支援的引數類型

  • value_expression 可以是可從運算式傳回的任何資料類型。
  • constant_integer_expression 可以是傳回整數的任何常數運算式。

傳回資料類型

不限

範例

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  FORMAT_TIMESTAMP('%X', finish_time) AS finish_time,
  division,
  FORMAT_TIMESTAMP('%X', fastest_time) AS fastest_time,
  FORMAT_TIMESTAMP('%X', second_fastest) AS second_fastest
FROM (
  SELECT name,
  finish_time,
  division,finishers,
  FIRST_VALUE(finish_time)
    OVER w1 AS fastest_time,
  NTH_VALUE(finish_time, 2)
    OVER w1 as second_fastest
  FROM finishers
  WINDOW w1 AS (
    PARTITION BY division ORDER BY finish_time ASC
    ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING));

+-----------------+-------------+----------+--------------+----------------+
| name            | finish_time | division | fastest_time | second_fastest |
+-----------------+-------------+----------+--------------+----------------+
| Carly Forte     | 03:08:58    | F25-29   | 03:08:58     | NULL           |
| Sophia Liu      | 02:51:45    | F30-34   | 02:51:45     | 02:59:01       |
| Nikki Leith     | 02:59:01    | F30-34   | 02:51:45     | 02:59:01       |
| Jen Edwards     | 03:06:36    | F30-34   | 02:51:45     | 02:59:01       |
| Meghan Lederer  | 03:07:41    | F30-34   | 02:51:45     | 02:59:01       |
| Lauren Reasoner | 03:10:14    | F30-34   | 02:51:45     | 02:59:01       |
| Lisa Stelzner   | 02:54:11    | F35-39   | 02:54:11     | 03:01:17       |
| Lauren Matthews | 03:01:17    | F35-39   | 02:54:11     | 03:01:17       |
| Desiree Berry   | 03:05:42    | F35-39   | 02:54:11     | 03:01:17       |
| Suzy Slane      | 03:06:24    | F35-39   | 02:54:11     | 03:01:17       |
+-----------------+-------------+----------+--------------+----------------+

LEAD

LEAD (value_expression[, offset [, default_expression]])

說明

傳回後續資料列上之 value_expression 的值。變更 offset 值會變更傳回哪一個後續資料列;預設值是 1,表示界線範圍中的下一個資料列。如果 offset 是 NULL 或負值,就會發生錯誤。

如果在指定偏移處的界線範圍中沒有資料列,就會使用選用的 default_expression。這個運算式必須是常數運算式,運算式類型必須自動強制轉換為 value_expression 的類型。如果保留未指定,default_expression 預設為 NULL。

支援的引數類型

  • value_expression 可以是可從運算式傳回的任何資料類型。
  • offset 必須是非負整數常值或參數。
  • default_expression 必須與值運算式類型相容。

傳回資料類型

不限

範例

以下範例說明 LEAD 函式的基本用法。

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS followed_by
FROM finishers;

+-----------------+-------------+----------+-----------------+
| name            | finish_time | division | followed_by     |
+-----------------+-------------+----------+-----------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL            |
| Sophia Liu      | 02:51:45    | F30-34   | Nikki Leith     |
| Nikki Leith     | 02:59:01    | F30-34   | Jen Edwards     |
| Jen Edwards     | 03:06:36    | F30-34   | Meghan Lederer  |
| Meghan Lederer  | 03:07:41    | F30-34   | Lauren Reasoner |
| Lauren Reasoner | 03:10:14    | F30-34   | NULL            |
| Lisa Stelzner   | 02:54:11    | F35-39   | Lauren Matthews |
| Lauren Matthews | 03:01:17    | F35-39   | Desiree Berry   |
| Desiree Berry   | 03:05:42    | F35-39   | Suzy Slane      |
| Suzy Slane      | 03:06:24    | F35-39   | NULL            |
+-----------------+-------------+----------+-----------------+

這個下一個範例使用選用 offset 參數。

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name, 2)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_back
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | two_runners_back |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL             |
| Sophia Liu      | 02:51:45    | F30-34   | Jen Edwards      |
| Nikki Leith     | 02:59:01    | F30-34   | Meghan Lederer   |
| Jen Edwards     | 03:06:36    | F30-34   | Lauren Reasoner  |
| Meghan Lederer  | 03:07:41    | F30-34   | NULL             |
| Lauren Reasoner | 03:10:14    | F30-34   | NULL             |
| Lisa Stelzner   | 02:54:11    | F35-39   | Desiree Berry    |
| Lauren Matthews | 03:01:17    | F35-39   | Suzy Slane       |
| Desiree Berry   | 03:05:42    | F35-39   | NULL             |
| Suzy Slane      | 03:06:24    | F35-39   | NULL             |
+-----------------+-------------+----------+------------------+

下一個範例以預設值取代 NULL 值。

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LEAD(name, 2, 'Nobody')
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_back
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | two_runners_back |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | Nobody           |
| Sophia Liu      | 02:51:45    | F30-34   | Jen Edwards      |
| Nikki Leith     | 02:59:01    | F30-34   | Meghan Lederer   |
| Jen Edwards     | 03:06:36    | F30-34   | Lauren Reasoner  |
| Meghan Lederer  | 03:07:41    | F30-34   | Nobody           |
| Lauren Reasoner | 03:10:14    | F30-34   | Nobody           |
| Lisa Stelzner   | 02:54:11    | F35-39   | Desiree Berry    |
| Lauren Matthews | 03:01:17    | F35-39   | Suzy Slane       |
| Desiree Berry   | 03:05:42    | F35-39   | Nobody           |
| Suzy Slane      | 03:06:24    | F35-39   | Nobody           |
+-----------------+-------------+----------+------------------+

LAG

LAG (value_expression[, offset [, default_expression]])

說明

傳回先前資料列上之 value_expression 的值。變更 offset 值會變更傳回哪一個先前資料列;預設值是 1,表示界線範圍中的上一個資料列。如果 offset 是 NULL 或負值,就會發生錯誤。

如果在指定偏移處的界線範圍中沒有資料列,就會使用選用的 default_expression。這個運算式必須是常數運算式,運算式類型必須自動強制轉換為 value_expression 的類型。如果保留未指定,default_expression 預設為 NULL。

支援的引數類型

  • value_expression 可以是可從運算式傳回的任何資料類型。
  • offset 必須是非負整數常值或參數。
  • default_expression 必須與值運算式類型相容。

傳回資料類型

不限

範例

以下範例說明 LAG 函式的基本用法。

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS preceding_runner
FROM finishers;

+-----------------+-------------+----------+------------------+
| name            | finish_time | division | preceding_runner |
+-----------------+-------------+----------+------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL             |
| Sophia Liu      | 02:51:45    | F30-34   | NULL             |
| Nikki Leith     | 02:59:01    | F30-34   | Sophia Liu       |
| Jen Edwards     | 03:06:36    | F30-34   | Nikki Leith      |
| Meghan Lederer  | 03:07:41    | F30-34   | Jen Edwards      |
| Lauren Reasoner | 03:10:14    | F30-34   | Meghan Lederer   |
| Lisa Stelzner   | 02:54:11    | F35-39   | NULL             |
| Lauren Matthews | 03:01:17    | F35-39   | Lisa Stelzner    |
| Desiree Berry   | 03:05:42    | F35-39   | Lauren Matthews  |
| Suzy Slane      | 03:06:24    | F35-39   | Desiree Berry    |
+-----------------+-------------+----------+------------------+

這個下一個範例使用選用 offset 參數。

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name, 2)
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_ahead
FROM finishers;

+-----------------+-------------+----------+-------------------+
| name            | finish_time | division | two_runners_ahead |
+-----------------+-------------+----------+-------------------+
| Carly Forte     | 03:08:58    | F25-29   | NULL              |
| Sophia Liu      | 02:51:45    | F30-34   | NULL              |
| Nikki Leith     | 02:59:01    | F30-34   | NULL              |
| Jen Edwards     | 03:06:36    | F30-34   | Sophia Liu        |
| Meghan Lederer  | 03:07:41    | F30-34   | Nikki Leith       |
| Lauren Reasoner | 03:10:14    | F30-34   | Jen Edwards       |
| Lisa Stelzner   | 02:54:11    | F35-39   | NULL              |
| Lauren Matthews | 03:01:17    | F35-39   | NULL              |
| Desiree Berry   | 03:05:42    | F35-39   | Lisa Stelzner     |
| Suzy Slane      | 03:06:24    | F35-39   | Lauren Matthews   |
+-----------------+-------------+----------+-------------------+

下一個範例以預設值取代 NULL 值。

WITH finishers AS
 (SELECT 'Sophia Liu' as name,
  TIMESTAMP '2016-10-18 2:51:45' as finish_time,
  'F30-34' as division
  UNION ALL SELECT 'Lisa Stelzner', TIMESTAMP '2016-10-18 2:54:11', 'F35-39'
  UNION ALL SELECT 'Nikki Leith', TIMESTAMP '2016-10-18 2:59:01', 'F30-34'
  UNION ALL SELECT 'Lauren Matthews', TIMESTAMP '2016-10-18 3:01:17', 'F35-39'
  UNION ALL SELECT 'Desiree Berry', TIMESTAMP '2016-10-18 3:05:42', 'F35-39'
  UNION ALL SELECT 'Suzy Slane', TIMESTAMP '2016-10-18 3:06:24', 'F35-39'
  UNION ALL SELECT 'Jen Edwards', TIMESTAMP '2016-10-18 3:06:36', 'F30-34'
  UNION ALL SELECT 'Meghan Lederer', TIMESTAMP '2016-10-18 3:07:41', 'F30-34'
  UNION ALL SELECT 'Carly Forte', TIMESTAMP '2016-10-18 3:08:58', 'F25-29'
  UNION ALL SELECT 'Lauren Reasoner', TIMESTAMP '2016-10-18 3:10:14', 'F30-34')
SELECT name,
  finish_time,
  division,
  LAG(name, 2, 'Nobody')
    OVER (PARTITION BY division ORDER BY finish_time ASC) AS two_runners_ahead
FROM finishers;

+-----------------+-------------+----------+-------------------+
| name            | finish_time | division | two_runners_ahead |
+-----------------+-------------+----------+-------------------+
| Carly Forte     | 03:08:58    | F25-29   | Nobody            |
| Sophia Liu      | 02:51:45    | F30-34   | Nobody            |
| Nikki Leith     | 02:59:01    | F30-34   | Nobody            |
| Jen Edwards     | 03:06:36    | F30-34   | Sophia Liu        |
| Meghan Lederer  | 03:07:41    | F30-34   | Nikki Leith       |
| Lauren Reasoner | 03:10:14    | F30-34   | Jen Edwards       |
| Lisa Stelzner   | 02:54:11    | F35-39   | Nobody            |
| Lauren Matthews | 03:01:17    | F35-39   | Nobody            |
| Desiree Berry   | 03:05:42    | F35-39   | Lisa Stelzner     |
| Suzy Slane      | 03:06:24    | F35-39   | Lauren Matthews   |
+-----------------+-------------+----------+-------------------+

PERCENTILE_CONT

PERCENTILE_CONT (value_expression, percentile [{RESPECT | IGNORE} NULLS])

說明

使用線性內插計算 value_expression 的指定百分位數值。

如果 RESPECT NULLS 不存在,這個函式會忽略 NULL 值。如果 RESPECT NULLS 存在:

  • 兩個 NULL 值之間的內插會傳回 NULL
  • NULL 值與非 NULL 值之間的內插會傳回非 NULL 值。

支援的引數類型

  • value_expression 是數字運算式。
  • percentile[0, 1] 範圍中的 DOUBLE 常值。

傳回資料類型

DOUBLE

範例

以下範例會計算來自某一值資料欄的某些百分位數的值,同時忽略空值。

SELECT
  PERCENTILE_CONT(x, 0) OVER() AS min,
  PERCENTILE_CONT(x, 0.01) OVER() AS percentile1,
  PERCENTILE_CONT(x, 0.5) OVER() AS median,
  PERCENTILE_CONT(x, 0.9) OVER() AS percentile90,
  PERCENTILE_CONT(x, 1) OVER() AS max
FROM UNNEST([0, 3, NULL, 1, 2]) AS x LIMIT 1;

+-----+-------------+--------+--------------+-----+
| min | percentile1 | median | percentile90 | max |
+-----+-------------+--------+--------------+-----+
| 0   | 0.03        | 1.5    | 2.7          | 3   |
+-----+-------------+--------+--------------+-----+

以下範例會計算來自某一值資料欄的某些百分位數的值,同時沿用空值。

SELECT
  PERCENTILE_CONT(x, 0 RESPECT NULLS) OVER() AS min,
  PERCENTILE_CONT(x, 0.01 RESPECT NULLS) OVER() AS percentile1,
  PERCENTILE_CONT(x, 0.5 RESPECT NULLS) OVER() AS median,
  PERCENTILE_CONT(x, 0.9 RESPECT NULLS) OVER() AS percentile90,
  PERCENTILE_CONT(x, 1 RESPECT NULLS) OVER() AS max
FROM UNNEST([0, 3, NULL, 1, 2]) AS x LIMIT 1;

+------+-------------+--------+--------------+-----+
| min  | percentile1 | median | percentile90 | max |
+------+-------------+--------+--------------+-----+
| NULL | 0           | 1      | 2.6          | 3   |
+------+-------------+--------+--------------+-----+

PERCENTILE_DISC

PERCENTILE_DISC (value_expression, percentile [{RESPECT | IGNORE} NULLS])

說明

計算離散 value_expression 的指定百分位數值。傳回的值是第一個排序的 value_expression 值,累計分佈大於或等於指定的 percentile 值。

除非 RESPECT NULLS 存在,否則這個函式會忽略 NULL 值。

支援的引數類型

  • value_expression 可以是任何可排序的類型。
  • percentile[0, 1] 範圍中的 DOUBLE 常值。

傳回資料類型

ANY

範例

以下範例會計算來自某一值資料欄的某些百分位數的值,同時忽略空值。

SELECT
  x,
  PERCENTILE_DISC(x, 0) OVER() AS min,
  PERCENTILE_DISC(x, 0.5) OVER() AS median,
  PERCENTILE_DISC(x, 1) OVER() AS max
FROM UNNEST(['c', NULL, 'b', 'a']) AS x;

+------+-----+--------+-----+
| x    | min | median | max |
+------+-----+--------+-----+
| c    | a   | b      | c   |
| NULL | a   | b      | c   |
| b    | a   | b      | c   |
| a    | a   | b      | c   |
+------+-----+--------+-----+

以下範例會計算來自某一值資料欄的某些百分位數的值,同時沿用空值。

SELECT
  x,
  PERCENTILE_DISC(x, 0 RESPECT NULLS) OVER() AS min,
  PERCENTILE_DISC(x, 0.5 RESPECT NULLS) OVER() AS median,
  PERCENTILE_DISC(x, 1 RESPECT NULLS) OVER() AS max
FROM UNNEST(['c', NULL, 'b', 'a']) AS x;

+------+------+--------+-----+
| x    | min  | median | max |
+------+------+--------+-----+
| c    | NULL | a      | c   |
| NULL | NULL | a      | c   |
| b    | NULL | a      | c   |
| a    | NULL | a      | c   |
+------+------+--------+-----+

Aggregate Analytic 函式

以下各節說明 BigQuery 支援的 aggregate analytic 函式。如要瞭解分析函式的運作方式,請參閱分析函式概念。如要瞭解匯總分析函式的運作方式,請參閱匯總分析函式概念

BigQuery 可以讓您以分析函式的形式來使用下列匯總函式

OVER 子句使用規範:

  • PARTITION BY:選用。
  • ORDER BY:選用。如果 DISTINCT 存在就不允許。
  • window_frame_clause:選用。如果 DISTINCT 存在就不允許。

範例:

COUNT(*) OVER (ROWS UNBOUNDED PRECEDING)
SUM(DISTINCT x) OVER ()

雜湊函式

FARM_FINGERPRINT

FARM_FINGERPRINT(value)

說明

使用開放原始碼 FarmHash 程式庫提供的 Fingerprint64 函式,計算 STRING 或 BYTES 輸入內容的指紋。特定輸入的這個函式之輸出將永不變更。

傳回類型

INT64

範例

WITH example AS (
  SELECT 1 AS x, "foo" AS y, true AS z UNION ALL
  SELECT 2 AS x, "apple" AS y, false AS z UNION ALL
  SELECT 3 AS x, "" AS y, true AS z
)
SELECT
  *,
  FARM_FINGERPRINT(CONCAT(CAST(x AS STRING), y, CAST(z AS STRING)))
    AS row_fingerprint
FROM example;
+---+-------+-------+----------------------+
| x | y     | z     | row_fingerprint      |
+---+-------+-------+----------------------+
| 1 | foo   | true  | -1541654101129638711 |
| 2 | apple | false | 2794438866806483259  |
| 3 |       | true  | -4880158226897771312 |
+---+-------+-------+----------------------+

MD5

MD5(input)

說明

使用 MD5 演算法計算輸入的雜湊。輸入可以是 STRING 或 BYTES。字串版本會將輸入當成位元組的陣列處理。

這個函式會傳回 16 個位元組。

傳回類型

BYTES

範例

SELECT MD5("Hello World") as md5;

+-------------------------------------------------+
| md5                                             |
+-------------------------------------------------+
| \xb1\n\x8d\xb1d\xe0uA\x05\xb7\xa9\x9b\xe7.?\xe5 |
+-------------------------------------------------+

SHA1

SHA1(input)

說明

使用 SHA-1 演算法計算輸入的雜湊。輸入可以是 STRING 或 BYTES。字串版本會將輸入當成位元組的陣列處理。

這個函式會傳回 20 個位元組。

傳回類型

BYTES

範例

SELECT SHA1("Hello World") as sha1;

+-----------------------------------------------------------+
| sha1                                                      |
+-----------------------------------------------------------+
| \nMU\xa8\xd7x\xe5\x02/\xabp\x19w\xc5\xd8@\xbb\xc4\x86\xd0 |
+-----------------------------------------------------------+

SHA256

SHA256(input)

說明

使用 SHA-256 演算法計算輸入的雜湊。輸入可以是 STRING 或 BYTES。字串版本會將輸入當成位元組的陣列處理。

這個函式會傳回 32 個位元組。

傳回類型

BYTES

範例

SELECT SHA256("Hello World") as sha256;

SHA512

SHA512(input)

說明

使用 SHA-512 演算法計算輸入的雜湊。輸入可以是 STRING 或 BYTES。字串版本會將輸入當成位元組的陣列處理。

這個函式會傳回 64 個位元組。

傳回類型

BYTES

範例

SELECT SHA512("Hello World") as sha512;

String 函式

這些 string 函式會處理兩種不同的值:STRING 與 BYTES 資料類型。STRING 值必須是格式正確的 UTF-8。

傳回正值的函式 (例如 STRPOS) 會將這些位置編碼為 INT64。1 值會參照第一個字元 (或位元組),2 會參照第二個,依此類推。0 值表示無效索引。處理 STRING 類型時,傳回的位置會參照字元位置。

所有字串比較都是逐一位元組完成的,無論 Unicode 正式相等性為何。

BYTE_LENGTH

BYTE_LENGTH(value)

說明

傳回的位元組長度,無論值的類型是 STRING 還是 BYTES。

傳回類型

INT64

範例

WITH example AS
  (SELECT "абвгд" AS characters, b"абвгд" AS bytes)

SELECT
  characters,
  BYTE_LENGTH(characters) AS string_example,
  bytes,
  BYTE_LENGTH(bytes) AS bytes_example
FROM example;

+------------+----------------+-------+---------------+
| characters | string_example | bytes | bytes_example |
+------------+----------------+-------+---------------+
| абвгд      | 10             | абвгд | 10            |
+------------+----------------+-------+---------------+

CHAR_LENGTH

CHAR_LENGTH(value)

說明

傳回 STRING 的字元長度。

傳回類型

INT64

範例

WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  CHAR_LENGTH(characters) AS char_length_example
FROM example;

+------------+---------------------+
| characters | char_length_example |
+------------+---------------------+
| абвгд      |                   5 |
+------------+---------------------+

CHARACTER_LENGTH

CHARACTER_LENGTH(value)

說明

CHAR_LENGTH 的同義詞。

傳回類型

INT64

範例

WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  CHARACTER_LENGTH(characters) AS char_length_example
FROM example;

+------------+---------------------+
| characters | char_length_example |
+------------+---------------------+
| абвгд      |                   5 |
+------------+---------------------+

CODE_POINTS_TO_BYTES

CODE_POINTS_TO_BYTES(ascii_values)

說明

取用延伸 ASCII 碼點的陣列 (INT64 的 ARRAY) 並傳回 BYTES。

若要從 BYTES 轉換為碼點的陣列,請參閱 TO_CODE_POINTS

傳回類型

BYTES

範例

以下是使用 CODE_POINTS_TO_BYTES 的基本範例。

SELECT CODE_POINTS_TO_BYTES([65, 98, 67, 100]) AS bytes;

+-------+
| bytes |
+-------+
| AbCd  |
+-------+

以下範例使用迴轉 13 位 (ROT13) 演算法來編碼字串。

SELECT CODE_POINTS_TO_BYTES(ARRAY_AGG(
  (SELECT
      CASE
        WHEN chr BETWEEN b'a' and b'z'
          THEN TO_CODE_POINTS(b'a')[offset(0)] +
            MOD(code+13-TO_CODE_POINTS(b'a')[offset(0)],26)
        WHEN chr BETWEEN b'A' and b'Z'
          THEN TO_CODE_POINTS(b'A')[offset(0)] +
            MOD(code+13-TO_CODE_POINTS(b'A')[offset(0)],26)
        ELSE code
      END
   FROM
     (SELECT code, CODE_POINTS_TO_BYTES([code]) chr)
  ) ORDER BY OFFSET)) AS encoded_string
FROM UNNEST(TO_CODE_POINTS(b'Test String!')) code WITH OFFSET;

+----------------+
| encoded_string |
+----------------+
| Grfg Fgevat!   |
+----------------+

CODE_POINTS_TO_STRING

CODE_POINTS_TO_STRING(value)

說明

取用 Unicode 碼點的陣列 (INT64 的 ARRAY) 並傳回 STRING。

若要從字串轉換為碼點的陣列,請參閱 TO_CODE_POINTS

傳回類型

STRING

範例

以下是使用 CODE_POINTS_TO_STRING 的基本範例。

SELECT CODE_POINTS_TO_STRING([65, 255, 513, 1024]) AS string;

+--------+
| string |
+--------+
| AÿȁЀ   |
+--------+

以下範例會計算一組字詞中的字母頻率。

WITH Words AS (
  SELECT word
  FROM UNNEST(['foo', 'bar', 'baz', 'giraffe', 'llama']) AS word
)
SELECT
  CODE_POINTS_TO_STRING([code_point]) AS letter,
  COUNT(*) AS letter_count
FROM Words,
  UNNEST(TO_CODE_POINTS(word)) AS code_point
GROUP BY 1
ORDER BY 2 DESC;

+--------+--------------+
| letter | letter_count |
+--------+--------------+
| a      | 5            |
| f      | 3            |
| r      | 2            |
| b      | 2            |
| l      | 2            |
| o      | 2            |
| g      | 1            |
| z      | 1            |
| e      | 1            |
| m      | 1            |
| i      | 1            |
+--------+--------------+

CONCAT

CONCAT(value1[, ...])

說明

將一或多個串連成單一結果。

傳回類型

STRING 或 BYTES

範例

With Employees AS
  (SELECT
    "John" AS first_name,
    "Doe" AS last_name
  UNION ALL
  SELECT
    "Jane" AS first_name,
    "Smith" AS last_name
  UNION ALL
  SELECT
    "Joe" AS first_name,
    "Jackson" AS last_name)

SELECT
  CONCAT(first_name, " ", last_name)
  AS full_name
FROM Employees;

+---------------------+
| full_name           |
+---------------------+
| John Doe            |
| Jane Smith          |
| Joe Jackson         |
+---------------------+

ENDS_WITH

ENDS_WITH(value1, value2)

說明

取用兩個。如果第二個值是第一個值的後置字串,就換傳回 TRUE。

傳回類型

BOOL

範例

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  ENDS_WITH(item, "e") as example
FROM items;

+---------+
| example |
+---------+
|    True |
|   False |
|    True |
+---------+

FORMAT

BigQuery 支援格式化字串的 FORMAT() 函式。這個函式與 C printf 函式類似。它會從包含零或更多格式指定碼的格式字串中產生 STRING,以及符合格式指定碼的其他引數變數長度清單。範例如下:

說明 陳述式 結果
簡單整數 format("%d", 10) 10
左側有填補空格的整數 format("|%10d|", 11) |           11|
左側有填補零的整數 format("+%010d+", 12) +0000000012+
有逗號的整數 format("%'d", 123456789) 123,456,789
STRING format("-%s-", 'abcd efg') -abcd efg-
FLOAT64 format("%f %E", 1.1, 2.2) 1.100000 2.200000E+00
DATE format("%t", date "2015-09-01") 2015-09-01
TIMESTAMP format("%t", timestamp "2015-09-01 12:34:56 America/Los_Angeles") 2015‑09‑01 19:34:56+00

FORMAT() 函式不為所有類型與值提供完全可自訂的格式化,也不提供對語言代碼敏感的格式化。

如果某一類型需要自訂格式化,您必須先使用類型特定格式函式 (例如 FORMAT_DATE() 或 FORMAT_TIMESTAMP()) 來對它進行格式化。例如:

FORMAT("date: %s!", FORMAT_DATE("%B %d, %Y", date '2015-01-02'));

傳回

date: January 02, 2015!

語法

FORMAT() 語法會取用格式字串與引數變數長度清單並產生 STRING 結果:

FORMAT(<format_string>, ...)

<format_string> 運算式可以取得零個或更多的格式指定碼。 每個格式指定碼都由 % 符號引入,且必須對應至一或多個剩餘引數。大多數情況下,除非當 * 指定碼存在時,這都是一對一的對應。例如,%.*i 對應至兩個引數—長度引數與正負號整數引數。如果與格式指定碼相關的引數數目與引數數目不同,就會發生錯誤。

支援的格式指定碼

FORMAT() 函式格式指定碼遵循這個原型:

%[flags][width][.precision]specifier

下表中列出支援的格式指定碼。 從 printf() 擴充的項目會以斜體列出。

指定碼 說明 範例 類型
di 十進位整數 392 INT64
o 八進位 610
INT64*
x 十六進位整數 7fa
INT64*
X 十六進位整數 (大寫) 7FA
INT64*
f 十進位浮點,小寫 392.65
inf
NaN

NUMERIC
FLOAT64
F 十進位浮點,大寫 392.65
inf
NAN

NUMERIC
FLOAT64
e 科學記數法 (尾數/指數),小寫 3.9265e+2
inf
NaN

NUMERIC
FLOAT64
E 科學記數法 (尾數/指數),大寫 3.9265E+2
inf
NAN
NUMERIC
FLOAT64
g 使用最短表示法,%e 或 %f 392.65
FLOAT64
G 使用最短表示法,%E 或 %F 392.65
FLOAT64
s 字元字串 範例 STRING
t 傳回表示值的可列印字串。通常看起來類似將引數類型轉換為 STRING。請參閱以下的 %t 部分 範例
2014‑01‑01
<any>
T 產生的字串是有效的 BigQuery 常數,常數的類型與值的類型類似 (可能更寬,或可能是字串)。 請參閱以下的 %T 部分 'sample'
b'bytes sample'
1234
2.3
date '2014‑01‑01'

<any>
% 「%%」會產生單一的「%」 %

*如果使用負值,則 o、x 與 X 指定碼會產生錯誤。

格式指定碼可以選擇性地包含在指定碼原型上方列出的子指定碼。

這些子指定碼必須遵守下列指定。

標記
標記 說明
- 在指定欄位寬度內靠左對齊;預設為靠右對齊 (請參閱寬度子指定碼)
+ 強制在結果前面加上加號或減號 (+-),即使是正數也加上。預設只在負數前面加上 -
<space> 如果沒有正負號可以寫上,就會在值前面插入一個空格
# 與 o、x 或 X 指定碼搭配使用。分別為零以外的值在前面加上 0、0x 或 0X
0 當指定填補時,為數字靠左填補零 (0) 而非空格 (請參閱寬度子指定碼)
'

使用適當的分組字元格式化整數。例如:

  • FORMAT("%'d", 12345678) 會傳回 12,345,678
  • FORMAT("%'x", 12345678) 會傳回 bc:614e
  • FORMAT("%'o", 55555) 會傳回 15,4403
  • 這個標記只與十進位、十六進位與八進位值相關。

標記可以任何順序指定。重複的標記不算是錯誤。當標記對某些元素類型而言無關時,就會忽略它們。

寬度
寬度 說明
<number> 要列印的字元數量下限。如果要列印的值短於這個數目,會為結果填補空格。即使結果較大,也不會截斷值
* 不會在格式字串中指定寬度,但會做為前置於必須格式化之引數前面的其他整數值引數
精確度
精確度 說明
.<number> 針對整數指定碼 (d、i、o、u、x、X):精確度指定了要編寫的位數下限。如果要編寫的值短於這個數目,就會為結果填補尾隨零。即使結果較長,也不會截斷值。精確度為 0 表示不會為值 0 編寫任何字元。對於 a、A、e、E、f 與 F 指定碼:這是要列印在小數點之後的位數 (預設是 6)
.* 不會在格式字串中指定精確度,但會做為前置於必須格式化之引數前面的其他整數值引數

%t 與 %T 行為

會為所有類型定義 %t%T 格式指定碼。寬度、精確度與標記的行為就像用於 %s 時一樣:width 是最小寬度,STRING 將會填補至那個大小,precision 是要顯示內容的最大寬度,STRING 將會在填補至寬度之前截斷至那個大小。

%t 一定是值的可閱讀形式。

%T 一律是類似類型的有效 SQL 常值,例如較寬的數字類型。 該常值將不會包含類型轉換或類型名稱,非有限浮點值的特殊案例除外:

STRING 的格式化情形如下:

類型 %t %T
任何類型的 NULL NULL NULL
INT64
123 123
NUMERIC 123.0 (一律帶有 .0) NUMERIC "123.0"
FLOAT64 123.0 (一律帶有 .0)
123e+10
inf
-inf
NaN
123.0 (一律帶有 .0)
123e+10
CAST("inf" 作為 <type>)
CAST("-inf" 作為 <type>)
CAST("nan" 作為 <type>)


STRING 未加引號的字串值 加引號的字串常值
BYTES 未加引號的逸出位元組
例如 abc\x01\x02
加引號的位元組常值
例如 b"abc\x01\x02"
DATE 2011-02-03 DATE "2011-02-03"
TIMESTAMP 2011-02-03 04:05:06+00 TIMESTAMP "2011-02-03 04:05:06+00"
ARRAY [值, 值, ...]
其中值的格式為 %t
[值, 值, ...]
其中值的格式為 %T
STRUCT (值, 值, ...)
其中欄位的格式為 %t
(值, 值, ...)
其中欄位的格式為 %T

特殊案例:
零個欄位:STRUCT()
一個欄位:STRUCT(值)

錯誤狀況

如果格式指定碼無效,或與相關引數類型不相容,或提供了錯誤數字或引數,就會產生錯誤。例如,以下 <format_string> 運算式無效:

FORMAT('%s', 1)
FORMAT('%')

NULL 引數處理

NULL 格式字串會產生 NULL 輸出 STRING。在此情況下會忽略其他任何引數。

如果 NULL 引數存在,函式一般會產生 NULL 值。例如,FORMAT('%i', <NULL expression>) 會產生 NULL STRING 作為輸出。

但是,也有一些例外:如果格式指定碼是 %t 或 %T (這兩者都會產生與 CAST 和常值語意有效相符的 STRING),NULL 值會在結果 STRING 中產生「NULL」(不含引號)。例如,以下函式:

FORMAT('00-%t-00', <NULL expression>);

傳回

00-NULL-00

其他語意規則

FLOAT64 值可以是 +/-infNaN。當引數具有這裡的其中一個值時,在適當情況下,格式指定碼 %f%F%e%E%g%G%t 的結果是 inf-infnan (大寫也相同)。這與 BigQuery 將這些值的類型轉換為 STRING 的方式一致。對於 %T,BigQuery 會傳回 FLOAT64 值加上引號的字串,但這些值沒有非字串常值表示。

FROM_BASE32

FROM_BASE32(string_expr)

說明

將採 base32 編碼的 string_expr 輸入轉換成 BYTES 格式。如要將 BYTES 轉換成採 base32 編碼的 STRING,請使用 TO_BASE32

傳回類型

BYTES

範例

SELECT FROM_BASE32('MFRGGZDF74======') AS byte_data;

+-----------+
| byte_data |
+-----------+
| abcde\xff |
+-----------+

FROM_BASE64

FROM_BASE64(string_expr)

說明

將採 Base64 編碼的輸入 string_expr 轉換成 BYTES 格式。若要將 BYTES 轉換成採 Base64 編碼的 STRING,請使用 TO_BASE64

傳回類型

BYTES

範例

SELECT FROM_BASE64('3q2+7w==') AS byte_data;

+------------------+
| byte_data        |
+------------------+
| \xde\xad\xbe\xef |
+------------------+

FROM_HEX

FROM_HEX(string)

說明

將採十六進位編碼的 STRING 轉換成 BYTES 格式。如果輸入 STRING 含有 (0..9, A..F, a..f) 範圍以外的字元,則會傳回錯誤。小寫字元沒有影響。如果輸入 STRING 的字元數為奇數,這個功能的行為會像是輸入有額外的前置 0。如要將 BYTES 轉換為採十六進位編碼的 STRING,請使用 TO_HEX

傳回類型

BYTES

範例

WITH Input AS (
  SELECT '00010203aaeeefff' AS hex_str UNION ALL
  SELECT '0AF' UNION ALL
  SELECT '666f6f626172'
)
SELECT hex_str, FROM_HEX(hex_str) AS bytes_str
FROM Input;
+------------------+----------------------------------+
| hex_str          | bytes_str                        |
+------------------+----------------------------------+
| 0AF              | \x00\xaf                         |
| 00010203aaeeefff | \x00\x01\x02\x03\xaa\xee\xef\xff |
| 666f6f626172     | foobar                           |
+------------------+----------------------------------+

LENGTH

LENGTH(value)

說明

傳回的長度。傳回值若是 STRING 引數就會以字元形式表示,若是 BYTES 引數就會以位元組形式表示。

傳回類型

INT64

範例

WITH example AS
  (SELECT "абвгд" AS characters)

SELECT
  characters,
  LENGTH(characters) AS string_example,
  LENGTH(CAST(characters AS BYTES)) AS bytes_example
FROM example;

+------------+----------------+---------------+
| characters | string_example | bytes_example |
+------------+----------------+---------------+
| абвгд      |              5 |            10 |
+------------+----------------+---------------+

LPAD

LPAD(original_value, return_length[, pattern])

說明

傳回的是由開頭帶有 patternoriginal_value 所構成。return_length 是指定傳回值長度的 INT64。如果 original_value 是 BYTES,return_length 就是位元組數。如果 original_value 是 STRING,return_length 就是字元數。

pattern 的預設值是空格。

original_valuepattern 必須是相同的資料類型。

如果 return_length 小於或等於 original_value 長度,這個函式會傳回 original_value 值,截斷至 return_length 的值。例如,LPAD("hello world", 7); 會傳回 "hello w"

如果 original_valuereturn_lengthpattern 是 NULL,這個函式會傳回 NULL。

如果是以下情形,這個函式會傳回錯誤:

  • return_length 是負數
  • pattern 是空白

傳回類型

STRING 或 BYTES

範例

SELECT t, len, FORMAT("%T", LPAD(t, len)) AS LPAD FROM UNNEST([
  STRUCT('abc' AS t, 5 AS len),
  ('abc', 2),
  ('例子', 4)
]);
t len LPAD
abc 5 "  abc"
abc 2 "ab"
例子 4 "  例子"
SELECT t, len, pattern, FORMAT("%T", LPAD(t, len, pattern)) AS LPAD FROM UNNEST([
  STRUCT('abc' AS t, 8 AS len, 'def' AS pattern),
  ('abc', 5, '-'),
  ('例子', 5, '中文')
]);
t len 模式 LPAD
abc 8 def "defdeabc"
abc 5 - "--abc"
例子 5 中文 "中文中例子"
SELECT FORMAT("%T", t) AS t, len, FORMAT("%T", LPAD(t, len)) AS LPAD FROM UNNEST([
  STRUCT(b'abc' AS t, 5 AS len),
  (b'abc', 2),
  (b'\xab\xcd\xef', 4)
]);
t len LPAD
b"abc" 5 b"  abc"
b"abc" 2 b"ab"
b"\xab\xcd\xef" 4 b" \xab\xcd\xef"
SELECT
  FORMAT("%T", t) AS t,
  len,
  FORMAT("%T", pattern) AS pattern,
  FORMAT("%T", LPAD(t, len, pattern)) AS LPAD
FROM UNNEST([
  STRUCT(b'abc' AS t, 8 AS len, b'def' AS pattern),
  (b'abc', 5, b'-'),
  (b'\xab\xcd\xef', 5, b'\x00')
]);
t len 模式 LPAD
b"abc" 8 b"def" b"defdeabc"
b"abc" 5 b"-" b"--abc"
b"\xab\xcd\xef" 5 b"\x00" b"\x00\x00\xab\xcd\xef"

LOWER

LOWER(value)

說明

對於 STRING 引數,會以小寫傳回帶有所有字母字元的原始字串。 在小寫與大寫之間對應會根據不考慮語言特定對應的 Unicode 字元資料庫完成。

對於 BYTES 引數,會將引數當成 ASCII 文字處理,所有大於 127 的位元組都會保持不變。

傳回類型

STRING 或 BYTES

範例

WITH items AS
  (SELECT
    "FOO" as item
  UNION ALL
  SELECT
    "BAR" as item
  UNION ALL
  SELECT
    "BAZ" as item)

SELECT
  LOWER(item) AS example
FROM items;

+---------+
| example |
+---------+
| foo     |
| bar     |
| baz     |
+---------+

LTRIM

LTRIM(value1[, value2])

說明

TRIM 相同,但只移除前置字元。

傳回類型

STRING 或 BYTES

範例

WITH items AS
  (SELECT "   apple   " as item
  UNION ALL
  SELECT "   banana   " as item
  UNION ALL
  SELECT "   orange   " as item)

SELECT
  CONCAT("#", LTRIM(item), "#") as example
FROM items;

+-------------+
| example     |
+-------------+
| #apple   #  |
| #banana   # |
| #orange   # |
+-------------+

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  LTRIM(item, "*") as example
FROM items;

+-----------+
| example   |
+-----------+
| apple***  |
| banana*** |
| orange*** |
+-----------+

WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)

SELECT
  LTRIM(item, "xyz") as example
FROM items;

+-----------+
| example   |
+-----------+
| applexxx  |
| bananayyy |
| orangezzz |
| pearxyz   |
+-----------+

NORMALIZE

NORMALIZE(value[, normalization_mode])

說明

取用 STRING value,並將它傳回為正規化的字串。

正規化可用來確保兩個字串相等。正規化通常會在兩個字串在螢幕上轉譯結果相同但具有不同 Unicode 碼點的情況下使用。

NORMALIZE 支援四個選用正規化模式:

名稱 說明
NFC 正規化形式正式合成 按正式相等性分解及重組字元。
NFKC 正規化形式相容性合成 按相容性分解字元,然後按正式相等性重組字元。
NFD 正規化形式正式分解 按正式相等性分解字元,多個結合字元會以特定順序排列。
NFKD 正規化形式相容性分解 按相容性分解字元,多個結合字元會以特定順序排列。

預設正規化模式是 NFC

傳回類型

STRING

範例

SELECT a, b, a = b as normalized
FROM (SELECT NORMALIZE('\u00ea') as a, NORMALIZE('\u0065\u0302') as b)
AS normalize_example;

+---+---+------------+
| a | b | normalized |
+---+---+------------+
| ê | ê | true       |
+---+---+------------+

以下範例正規化不同的空格字元。

WITH EquivalentNames AS (
  SELECT name
  FROM UNNEST([
      'Jane\u2004Doe',
      'John\u2004Smith',
      'Jane\u2005Doe',
      'Jane\u2006Doe',
      'John Smith']) AS name
)
SELECT
  NORMALIZE(name, NFKC) AS normalized_name,
  COUNT(*) AS name_count
FROM EquivalentNames
GROUP BY 1;

+-----------------+------------+
| normalized_name | name_count |
+-----------------+------------+
| John Smith      | 2          |
| Jane Doe        | 3          |
+-----------------+------------+

NORMALIZE_AND_CASEFOLD

NORMALIZE_AND_CASEFOLD(value[, normalization_mode])

說明

取用 STRING value,並執行與 NORMALIZE 相同的動作,以及針對不區分大小寫的運算執行全大/小寫轉換

NORMALIZE_AND_CASEFOLD 支援四個選用正規化模式:

名稱 說明
NFC 正規化形式正式合成 按正式相等性分解及重組字元。
NFKC 正規化形式相容性合成 按相容性分解字元,然後按正式相等性重組字元。
NFD 正規化形式正式分解 按正式相等性分解字元,多個結合字元會以特定順序排列。
NFKD 正規化形式相容性分解 按相容性分解字元,多個結合字元會以特定順序排列。

預設正規化模式是 NFC

傳回類型

STRING

範例

WITH Strings AS (
  SELECT '\u2168' AS a, 'IX' AS b UNION ALL
  SELECT '\u0041\u030A', '\u00C5'
)
SELECT a, b,
  NORMALIZE_AND_CASEFOLD(a, NFD)=NORMALIZE_AND_CASEFOLD(b, NFD) AS nfd,
  NORMALIZE_AND_CASEFOLD(a, NFC)=NORMALIZE_AND_CASEFOLD(b, NFC) AS nfc,
  NORMALIZE_AND_CASEFOLD(a, NFKD)=NORMALIZE_AND_CASEFOLD(b, NFKD) AS nkfd,
  NORMALIZE_AND_CASEFOLD(a, NFKC)=NORMALIZE_AND_CASEFOLD(b, NFKC) AS nkfc
FROM Strings;

+---+----+-------+-------+------+------+
| a | b  | nfd   | nfc   | nkfd | nkfc |
+---+----+-------+-------+------+------+
| Ⅸ | IX | false | false | true | true |
| Å | Å  | true  | true  | true | true |
+---+----+-------+-------+------+------+

REGEXP_CONTAINS

REGEXP_CONTAINS(value, regex)

說明

如果 value 與規則運算式 regex 部分相符,就會傳回 TRUE。

如果 regex 引數無效,函式會傳回錯誤。

您可以使用 ^ (文字的開頭) 與 $ (文字的結尾) 搜尋完全相符的情況。基於規則運算式運算子的優先順序,為 ^$ 之間的所有文字加上圓括號是不錯的做法。

附註:BigQuery 提供使用 re2 程式庫的規則運算式支援;有關規則運算式語法,請參閱說明文件。

傳回類型

BOOL

範例

SELECT
  email,
  REGEXP_CONTAINS(email, r"@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+") AS is_valid
FROM
  (SELECT
    ["foo@example.com", "bar@example.org", "www.example.net"]
    AS addresses),
  UNNEST(addresses) AS email;

+-----------------+----------+
| email           | is_valid |
+-----------------+----------+
| foo@example.com | true     |
| bar@example.org | true     |
| www.example.net | false    |
+-----------------+----------+

# Performs a full match, using ^ and $. Due to regular expression operator
# precedence, it is good practice to use parentheses around everything between ^
# and $.
SELECT
  email,
  REGEXP_CONTAINS(email, r"^([\w.+-]+@foo\.com|[\w.+-]+@bar\.org)$")
    AS valid_email_address,
  REGEXP_CONTAINS(email, r"^[\w.+-]+@foo\.com|[\w.+-]+@bar\.org$")
    AS without_parentheses
FROM
  (SELECT
    ["a@foo.com", "a@foo.computer", "b@bar.org", "!b@bar.org", "c@buz.net"]
    AS addresses),
  UNNEST(addresses) AS email;

+----------------+---------------------+---------------------+
| email          | valid_email_address | without_parentheses |
+----------------+---------------------+---------------------+
| a@foo.com      | true                | true                |
| a@foo.computer | false               | true                |
| b@bar.org      | true                | true                |
| !b@bar.org     | false               | true                |
| c@buz.net      | false               | false               |
+----------------+---------------------+---------------------+

REGEXP_EXTRACT

REGEXP_EXTRACT(value, regex)

說明

傳回 value 中與規則運算式 regex 相符的第一個子字串。如果沒有相符項目,就傳回 NULL

如果規則運算式中包含擷取群組,函式會傳回與那個擷取群組相符的子字串。如果運算式不包含擷取群組,函式會傳回完整相符子字串。

在以下情況下會傳回錯誤:

  • 規則運算式無效
  • 規則運算式有一個以上的擷取群組

注意:BigQuery 提供使用 re2 程式庫的規則運算式支援;有關它的規則運算式語法,請參閱說明文件。

傳回類型

STRING 或 BYTES

範例

WITH email_addresses AS
  (SELECT "foo@example.com" as email
  UNION ALL
  SELECT "bar@example.org" as email
  UNION ALL
  SELECT "baz@example.net" as email)

SELECT
  REGEXP_EXTRACT(email, r"^[a-zA-Z0-9_.+-]+")
  AS user_name
FROM email_addresses;

+-----------+
| user_name |
+-----------+
| foo       |
| bar       |
| baz       |
+-----------+

WITH email_addresses AS
  (SELECT "foo@example.com" as email
  UNION ALL
  SELECT "bar@example.org" as email
  UNION ALL
  SELECT "baz@example.net" as email)

SELECT
  REGEXP_EXTRACT(email, r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.([a-zA-Z0-9-.]+$)")
  AS top_level_domain
FROM email_addresses;

+------------------+
| top_level_domain |
+------------------+
| com              |
| org              |
| net              |
+------------------+

REGEXP_EXTRACT_ALL

REGEXP_EXTRACT_ALL(value, regex)

說明

傳回與規則運算式 regex 相符的 value 之所有子字串的陣列。

REGEXP_EXTRACT_ALL 函式只會傳回非重疊相符項目。例如,使用這個函式來從 banana 中擷取 ana 只會傳回一個子字串,而不是兩個字子串。

注意:BigQuery 提供使用 re2 程式庫的規則運算式支援;有關它的規則運算式語法,請參閱說明文件。

傳回類型

STRING 或 BYTES 的陣列

範例

WITH code_markdown AS
  (SELECT "Try `function(x)` or `function(y)`" as code)

SELECT
  REGEXP_EXTRACT_ALL(code, "`(.+?)`") AS example
FROM code_markdown;

+----------------------------+
| example                    |
+----------------------------+
| [function(x), function(y)] |
+----------------------------+

REGEXP_REPLACE

REGEXP_REPLACE(value, regex, replacement)

說明

傳回與規則運算式 regex 相符之 value 的所有子字串都用 replacement 取代的 STRING。

您可以在 replacement 引數內使用反斜線逸出數字 (\1 到 \9) 來在 regex 模式中插入與對應放入括號內群組相符的文字。請使用 \0 來參照完整相符文字。

注意:若要在規則運算式中加入反斜線,您必須先將它逸出。 例如,SELECT REGEXP_REPLACE("abc", "b(.)", "X\\1"); 會傳回 aXc

REGEXP_REPLACE 函式只會取代非重疊相符項目。例如,取代 banana 內的 ana 只會產生一個取代,而不是兩個。

如果 regex 引數不是有效的規則運算式,這個函式會傳回錯誤。

注意:BigQuery 提供使用 re2 程式庫的規則運算式支援;有關它的規則運算式語法,請參閱說明文件。

傳回類型

STRING 或 BYTES

範例

WITH markdown AS
  (SELECT "# Heading" as heading
  UNION ALL
  SELECT "# Another heading" as heading)

SELECT
  REGEXP_REPLACE(heading, r"^# ([a-zA-Z0-9\s]+$)", "<h1>\\1</h1>")
  AS html
FROM markdown;

+--------------------------+
| html                     |
+--------------------------+
| <h1>Heading</h1>         |
| <h1>Another heading</h1> |
+--------------------------+

REPLACE

REPLACE(original_value, from_value, to_value)

說明

在 original_value 中以 to_value 取代 from_value 的所有發生次數。 如果 from_value 是空白,就不會進行取代。

傳回類型

STRING 或 BYTES

範例

WITH desserts AS
  (SELECT "apple pie" as dessert
  UNION ALL
  SELECT "blackberry pie" as dessert
  UNION ALL
  SELECT "cherry pie" as dessert)

SELECT
  REPLACE (dessert, "pie", "cobbler") as example
FROM desserts;

+--------------------+
| example            |
+--------------------+
| apple cobbler      |
| blackberry cobbler |
| cherry cobbler     |
+--------------------+

REPEAT

REPEAT(original_value, repetitions)

說明

傳回的由重複的 original_value 所構成。 repetitions 參數指定了重複 original_value 的次數。如果 original_valuerepetitions 是 NULL,就會傳回 NULL。

如果 repetitions 值是負數,這個函式會傳回錯誤。

傳回類型

STRING 或 BYTES

範例

SELECT t, n, REPEAT(t, n) AS REPEAT FROM UNNEST([
  STRUCT('abc' AS t, 3 AS n),
  ('例子', 2),
  ('abc', null),
  (null, 3)
]);
t n 重複
abc 3 abcabcabc
例子 2 例子例子
abc NULL NULL
NULL 3 NULL

REVERSE

REVERSE(value)

說明

傳回輸入 STRING 或 BYTES 的對調。

傳回類型

STRING 或 BYTES

範例

WITH example AS (
  SELECT "foo" AS sample_string, b"bar" AS sample_bytes UNION ALL
  SELECT "абвгд" AS sample_string, b"123" AS sample_bytes
)
SELECT
  sample_string,
  REVERSE(sample_string) AS reverse_string,
  sample_bytes,
  REVERSE(sample_bytes) AS reverse_bytes
FROM example;

+---------------+----------------+--------------+---------------+
| sample_string | reverse_string | sample_bytes | reverse_bytes |
+---------------+----------------+--------------+---------------+
| foo           | oof            | bar          | rab           |
| абвгд         | дгвба          | 123          | 321           |
+---------------+----------------+--------------+---------------+

RPAD

RPAD(original_value, return_length[, pattern])

說明

傳回的由結尾帶有 patternoriginal_value 所構成。return_length 是指定傳回值長度的 INT64。如果 original_value 是 BYTES,return_length 就是位元組數。如果 original_value 是 STRING,return_length 就是字元數。

pattern 的預設值是空格。

original_valuepattern 必須是相同的資料類型。

如果 return_length 小於或等於 original_value 長度,這個函式會傳回 original_value 值,截斷至 return_length 的值。例如,RPAD("hello world", 7); 會傳回 "hello w"

如果 original_valuereturn_lengthpattern 是 NULL,這個函式會傳回 NULL。

如果是以下情形,這個函式會傳回錯誤:

  • return_length 是負數
  • pattern 是空白

傳回類型

STRING 或 BYTES

範例

SELECT t, len, FORMAT("%T", RPAD(t, len)) AS RPAD FROM UNNEST([
  STRUCT('abc' AS t, 5 AS len),
  ('abc', 2),
  ('例子', 4)
]);
t len RPAD
abc 5 "abc  "
abc 2 "ab"
例子 4 "例子  "
SELECT t, len, pattern, FORMAT("%T", RPAD(t, len, pattern)) AS RPAD FROM UNNEST([
  STRUCT('abc' AS t, 8 AS len, 'def' AS pattern),
  ('abc', 5, '-'),
  ('例子', 5, '中文')
]);
t len 模式 RPAD
abc 8 def "abcdefde"
abc 5 - "abc--"
例子 5 中文 "例子中文中"
SELECT FORMAT("%T", t) AS t, len, FORMAT("%T", RPAD(t, len)) AS RPAD FROM UNNEST([
  STRUCT(b'abc' AS t, 5 AS len),
  (b'abc', 2),
  (b'\xab\xcd\xef', 4)
]);
t len RPAD
b"abc" 5 b"abc  "
b"abc" 2 b"ab"
b"\xab\xcd\xef" 4 b"\xab\xcd\xef "
SELECT
  FORMAT("%T", t) AS t,
  len,
  FORMAT("%T", pattern) AS pattern,
  FORMAT("%T", RPAD(t, len, pattern)) AS RPAD
FROM UNNEST([
  STRUCT(b'abc' AS t, 8 AS len, b'def' AS pattern),
  (b'abc', 5, b'-'),
  (b'\xab\xcd\xef', 5, b'\x00')
]);
t len 模式 RPAD
b"abc" 8 b"def" b"abcdefde"
b"abc" 5 b"-" b"abc--"
b"\xab\xcd\xef" 5 b"\x00" b"\xab\xcd\xef\x00\x00"

RTRIM

RTRIM(value1[, value2])

說明

TRIM 相同,但只移除尾隨字元。

傳回類型

STRING 或 BYTES

範例

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  RTRIM(item, "*") as example
FROM items;

+-----------+
| example   |
+-----------+
| ***apple  |
| ***banana |
| ***orange |
+-----------+

WITH items AS
  (SELECT "applexxx" as item
  UNION ALL
  SELECT "bananayyy" as item
  UNION ALL
  SELECT "orangezzz" as item
  UNION ALL
  SELECT "pearxyz" as item)

SELECT
  RTRIM(item, "xyz") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
| pear    |
+---------+

SAFE_CONVERT_BYTES_TO_STRING

SAFE_CONVERT_BYTES_TO_STRING(value)

說明

將位元組的順序轉換為字串。任何無效的 UTF-8 字元都會取代為 Unicode 取代字元 U+FFFD

傳回類型

STRING

範例

以下陳述式會傳回 Unicode 取代字元 �。

SELECT SAFE_CONVERT_BYTES_TO_STRING(b'\xc2') as safe_convert;

SPLIT

SPLIT(value[, delimiter])

說明

使用 delimiter 引數拆分 value

對於 STRING,預設分隔符號是逗號 ,

對於 BYTES,您必須指定分隔符號。

拆分空白分隔符號會針對 STRING 值產生 UTF-8 字元的陣列,針對 BYTES 值產生 BYTES 的陣列。

拆分空白 STRING 會傳回帶有單一空白 STRING 的 ARRAY。

傳回類型

STRUNG 類型的 ARRAY 或 BYTES 類型的 ARRAY

範例

WITH letters AS
  (SELECT "a b c d" as letter_group
  UNION ALL
  SELECT "e f g h" as letter_group
  UNION ALL
  SELECT "i j k l" as letter_group)

SELECT SPLIT(letter_group, " ") as example
FROM letters;

+----------------------+
| example              |
+----------------------+
| [a, b, c, d]         |
| [e, f, g, h]         |
| [i, j, k, l]         |
+----------------------+

STARTS_WITH

STARTS_WITH(value1, value2)

說明

取用兩個。如果第二個值是第一個值的前置字元,就會傳回 TRUE。

傳回類型

BOOL

範例

WITH items AS
  (SELECT "foo" as item
  UNION ALL
  SELECT "bar" as item
  UNION ALL
  SELECT "baz" as item)

SELECT
  STARTS_WITH(item, "b") as example
FROM items;

+---------+
| example |
+---------+
|   False |
|    True |
|    True |
+---------+

STRPOS

STRPOS(string, substring)

說明

傳回在 string 內第一次出現 substring 的以 1 為基礎的索引。如果找不到 substring,就會傳回 0

傳回類型

INT64

範例

WITH email_addresses AS
  (SELECT
    "foo@example.com" AS email_address
  UNION ALL
  SELECT
    "foobar@example.com" AS email_address
  UNION ALL
  SELECT
    "foobarbaz@example.com" AS email_address
  UNION ALL
  SELECT
    "quxexample.com" AS email_address)

SELECT
  STRPOS(email_address, "@") AS example
FROM email_addresses;

+---------+
| example |
+---------+
|       4 |
|       7 |
|      10 |
|       0 |
+---------+

SUBSTR

SUBSTR(value, position[, length])

說明

傳回提供之的子字串。position 引數是指定子字串開始位置的整數,位置 = 1 指示第一個字元或位元組。length 引數是 STRING 引數的字元數上限,或 BYTES 引數的位元組上限。

如果 position 是負數,函式會從 value 的結尾開始計數,-1 指示最後一個字元。

如果 position 是 STRING 左端以外的位置 (position = 0 或 position < -LENGTH(value)),函式會從位置 = 1 開始。如果 length 超過 value 的長度,就會傳回少於 length 的字元。

如果 length 小於 0,函式會傳回錯誤。

傳回類型

STRING 或 BYTES

範例

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, 2) as example
FROM items;

+---------+
| example |
+---------+
| pple    |
| anana   |
| range   |
+---------+

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, 2, 2) as example
FROM items;

+---------+
| example |
+---------+
| pp      |
| an      |
| ra      |
+---------+

WITH items AS
  (SELECT "apple" as item
  UNION ALL
  SELECT "banana" as item
  UNION ALL
  SELECT "orange" as item)

SELECT
  SUBSTR(item, -2) as example
FROM items;

+---------+
| example |
+---------+
| le      |
| na      |
| ge      |
+---------+

TO_BASE32

TO_BASE32(bytes_expr)

說明

將 BYTES 的順序轉換為採 base32 編碼的 STRING。若要將採 base32 編碼的 STRING 轉換成 BYTES,請使用 FROM_BASE32

傳回類型

STRING

範例

SELECT TO_BASE32(b'abcde\xFF') AS base32_string;

+------------------+
| base32_string    |
+------------------+
| MFRGGZDF74====== |
+------------------+

TO_BASE64

TO_BASE64(bytes_expr)

說明

將 BYTES 的順序轉換成採 base64 編碼的 STRING。若要將採 Base64 編碼的 STRING 轉換成 BYTES,請使用 FROM_BASE64

傳回類型

STRING

範例

SELECT TO_BASE64(b'\xde\xad\xbe\xef') AS base64_string;

+---------------+
| base64_string |
+---------------+
| 3q2+7w==      |
+---------------+

TO_CODE_POINTS

TO_CODE_POINTS(value)

說明

取用並傳回 INT64 的陣列。

  • 如果 value 是 STRING,則傳回陣列中的每個元素都代表一個碼點。每個碼點都在 [0, 0xD7FF] 與 [0xE000, 0x10FFFF] 的範圍之內。
  • 如果 value 是 BYTES,陣列中的每個元素都是 [0, 255] 範圍中的延伸 ASCII 字元值。

如要將碼點陣列轉換為 STRING 或 BYTES,請參閱 CODE_POINTS_TO_STRINGCODE_POINTS_TO_BYTES 等節。

傳回類型

INT64 的 ARRAY

範例

以下範例在字詞的陣列中取得每個元素的碼點。

SELECT word, TO_CODE_POINTS(word) AS code_points
FROM UNNEST(['foo', 'bar', 'baz', 'giraffe', 'llama']) AS word;

+---------+------------------------------------+
| word    | code_points                        |
+---------+------------------------------------+
| foo     | [102, 111, 111]                    |
| bar     | [98, 97, 114]                      |
| baz     | [98, 97, 122]                      |
| giraffe | [103, 105, 114, 97, 102, 102, 101] |
| llama   | [108, 108, 97, 109, 97]            |
+---------+------------------------------------+

以下範例將 BYTES 的整數表示轉換為對應的 ASCII 字元值。

SELECT word, TO_CODE_POINTS(word) AS bytes_value_as_integer
FROM UNNEST([b'\x00\x01\x10\xff', b'\x66\x6f\x6f']) AS word;

+------------------+------------------------+
| word             | bytes_value_as_integer |
+------------------+------------------------+
| \x00\x01\x10\xff | [0, 1, 16, 255]        |
| foo              | [102, 111, 111]        |
+------------------+------------------------+

以下範例展示了 BYTES 結果與 STRING 結果之間的差異。

SELECT TO_CODE_POINTS(b'Ā') AS b_result, TO_CODE_POINTS('Ā') AS s_result;

+------------+----------+
| b_result   | s_result |
+------------+----------+
| [196, 128] | [256]    |
+------------+----------+

請注意,字元 Ā 由兩位元組的 Unicode 順序表示。因此,BYTES 版本的 TO_CODE_POINTS 傳回了含有兩個元素的陣列,而 STRING 版本傳回了含有單一元素的陣列。

TO_HEX

TO_HEX(bytes)

說明

將 BYTES 的順序轉換成十六進位 STRING。將 STRING 中的每個位元組轉換成 (0..9, a..f) 範圍中的兩個十六進位字元。若要將採十六進位編碼的 STRING 轉換成 BYTES,請使用 FROM_HEX

傳回類型

STRING

範例

WITH Input AS (
  SELECT b'\x00\x01\x02\x03\xAA\xEE\xEF\xFF' AS byte_str UNION ALL
  SELECT b'foobar'
)
SELECT byte_str, TO_HEX(byte_str) AS hex_str
FROM Input;
+----------------------------------+------------------+
| byte_string                      | hex_string       |
+----------------------------------+------------------+
| foobar                           | 666f6f626172     |
| \x00\x01\x02\x03\xaa\xee\xef\xff | 00010203aaeeefff |
+----------------------------------+------------------+

TRIM

TRIM(value1[, value2])

說明

移除符合 value2 的所有前置與尾隨字元。若未指定 value2,會移除所有前置與尾隨空格字元 (如 Unicode 標準的定義)。如果第一個引數的類型是 BYTES,就需要第二個引數。

如果 value2 中包含一個以上的字元或位元組,函式會移除 value2 中包含的所有前置或尾隨字元或位元組。

傳回類型

STRING 或 BYTES

範例

WITH items AS
  (SELECT "   apple   " as item
  UNION ALL
  SELECT "   banana   " as item
  UNION ALL
  SELECT "   orange   " as item)

SELECT
  CONCAT("#", TRIM(item), "#") as example
FROM items;

+----------+
| example  |
+----------+
| #apple#  |
| #banana# |
| #orange# |
+----------+

WITH items AS
  (SELECT "***apple***" as item
  UNION ALL
  SELECT "***banana***" as item
  UNION ALL
  SELECT "***orange***" as item)

SELECT
  TRIM(item, "*") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
+---------+

WITH items AS
  (SELECT "xxxapplexxx" as item
  UNION ALL
  SELECT "yyybananayyy" as item
  UNION ALL
  SELECT "zzzorangezzz" as item
  UNION ALL
  SELECT "xyzpearxyz" as item)

SELECT
  TRIM(item, "xyz") as example
FROM items;

+---------+
| example |
+---------+
| apple   |
| banana  |
| orange  |
| pear    |
+---------+

UPPER

UPPER(value)

說明

對於 STRING 引數,會傳回所有字母字元都是大寫的原始字串。 在小寫與大寫之間對應會根據不考慮語言特定對應的 Unicode 字元資料庫完成。

對於 BYTES 引數,會將引數當成 ASCII 文字處理,所有大於 127 的位元組都會保持不變。

傳回類型

STRING 或 BYTES

範例

WITH items AS
  (SELECT
    "foo" as item
  UNION ALL
  SELECT
    "bar" as item
  UNION ALL
  SELECT
    "baz" as item)

SELECT
  UPPER(item) AS example
FROM items;

+---------+
| example |
+---------+
| FOO     |
| BAR     |
| BAZ     |
+---------+

JSON 函式

BigQuery 支援可協助您擷取以 JSON 格式字串儲存之資料的函式,也支援可協助您將資料轉換成 JSON 格式字串的函式。

JSON_EXTRACT 或 JSON_EXTRACT_SCALAR

JSON_EXTRACT(json_string_expr, json_path_string_literal),以 STRING 傳回 JSON 值。

JSON_EXTRACT_SCALAR(json_string_expr, json_path_string_literal),以 STRING 傳回純量 JSON 值。

說明

json_string_expr 參數必須是 JSON 格式字串。例如:

{"class" : {"students" : [{"name" : "Jane"}]}}

json_path_string_literal 參數可列出您要從 JSON 格式字串中取得的一或多個值。您可使用 JSONPath 格式建構這個參數。作為這個格式的一部分,這個參數必須以 $ 符號開頭,這會參照 JSON 格式字串的最外層。您可以使用點或方括號標記法來識別子值。如果 JSON 物件是陣列,您可以使用方括號來指定陣列索引。

JSONPath 說明
$ 根物件或元素
. 或 [] 子運算子
[] 下標運算子

如果 json_path_string_literal 參數與 json_string_expr 中的值不符,這兩個函式都會傳回NULL。如果針對 JSON_EXTRACT_SCALAR 選取的值不是純量,例如物件或陣列,函式會傳回 NULL

如果 JSONPath 無效,這些函式會產生錯誤。

如果 JSON 金鑰使用無效的 JSONPath 字元,您可以使用單引號與方括號 [' '] 逸出這些字元。例如:

SELECT JSON_EXTRACT_SCALAR('{"a.b": {"c": "world"}}', "$['a.b'].c") as hello;

+-------+
| hello |
+-------+
| world |
+-------+

範例

SELECT JSON_EXTRACT(json_text, '$') AS json_text_string
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

上述查詢會產生下列結果:

+-----------------------------------------------------------+
| json_text_string                                          |
+-----------------------------------------------------------+
| {"class":{"students":[{"name":"Jane"}]}}                  |
| {"class":{"students":[]}}                                 |
| {"class":{"students":[{"name":"John"},{"name":"Jamie"}]}} |
+-----------------------------------------------------------+
SELECT JSON_EXTRACT(json_text, '$.class.students[0]') AS first_student
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

上述查詢會產生下列結果:

+-----------------+
| first_student   |
+-----------------+
| {"name":"Jane"} |
| NULL            |
| {"name":"John"} |
+-----------------+
SELECT JSON_EXTRACT(json_text, '$.class.students[1].name') AS second_student_name
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

上述查詢會產生下列結果:

+-------------------+
| second_student    |
+-------------------+
| NULL              |
| NULL              |
| "Jamie"           |
+-------------------+
SELECT JSON_EXTRACT(json_text, "$.class['students']") AS student_names
FROM UNNEST([
  '{"class" : {"students" : [{"name" : "Jane"}]}}',
  '{"class" : {"students" : []}}',
  '{"class" : {"students" : [{"name" : "John"}, {"name": "Jamie"}]}}'
  ]) AS json_text;

上述查詢會產生下列結果:

+------------------------------------+
| student_names                      |
+------------------------------------+
| [{"name":"Jane"}]                  |
| []                                 |
| [{"name":"John"},{"name":"Jamie"}] |
+------------------------------------+
SELECT JSON_EXTRACT('{ "name" : "Jakob", "age" : "6" }', '$.name') as json_name,
  JSON_EXTRACT_SCALAR('{ "name" : "Jakob", "age" : "6" }', '$.name') as scalar_name,
  JSON_EXTRACT('{ "name" : "Jakob", "age" : "6" }', '$.age') as json_age,
  JSON_EXTRACT_SCALAR('{ "name" : "Jakob", "age" : "6" }', '$.age') as scalar;

上述查詢會產生下列結果:

+-----------+-------------+----------+--------+
| json_name | scalar_name | json_age | scalar |
+-----------+-------------+----------+--------+
| "Jakob"   | Jakob       | "6"      | 6      |
+-----------+-------------+----------+--------+

TO_JSON_STRING

TO_JSON_STRING(value[, pretty_print])

說明

傳回 value 的 JSON 格式字串表示。這個函式支援選用 pretty_print 參數。如果存在 pretty_print,傳回的值會經過格式化而更易於閱讀。

輸入資料類型 傳回的值
任何類型的 NULL null
BOOL truefalse
INT64

value 處於 [-253, 253] 範圍內的 CAST(value AS STRING) 相同,這是能以 IEEE 754 雙精確度浮點數無損表示的整數範圍。 位於這個範圍之外的值會表示為加上引號的字串。例如:

-1
0
12345678901
9007199254740992
-9007199254740992
"9007199254740993"

9007199254740993 大於 253,因此會以加上引號的字串表示。

NUMERIC

value 處於 [-253, 253] 範圍內的 CAST(value AS STRING) 相同,且沒有小數部分。位於這個範圍之外的值會表示為加上引號的字串。例如:

-1
0
"9007199254740993"
"123.56"


FLOAT64 +/-infNaN 會分別表示為 Infinity-InfinityNaN

否則,與 CAST(value AS STRING) 相同。

STRING 加上引號的字串值,根據 JSON 標準逸出。 具體而言,會逸出 "\ 與從 U+0000U+001F 的控制字元。
BYTES

加上引號的 RFC 4648 Base64 逸出值。例如:

"R29vZ2xl" 是位元組 b"Google" 的 Base64 表示

DATE

加上引號的日期。例如:

"2017-03-06"
TIMESTAMP

加上引號的 ISO 8601 日期時間,其中 T 分隔了日期與時間,而 Zulu/UTC 表示時區。例如:

"2017-03-06T12:34:56.789012Z"
DATETIME

加上引號的 ISO 8601 日期時間,其中 T 分隔了日期與時間。例如:

"2017-03-06T12:34:56.789012"
TIME

加上引號的 ISO 8601 時間。例如:

"12:34:56.789012"
ARRAY

[elem1,elem2,...],其中每個 elem 都根據元素類型格式化。

格式化的範例:

[
  elem1,
  elem2,
  ...
]

其中每個 elem 都根據元素類型格式化。空白陣列會表示為 []

STRUCT {"field_name1":field_value1,"field_name2":field_value2,...}

其中每個 field_value 都會根據它的類型格式化。

格式化的範例:

{
  "field_name1": field_value1,
  "field_name2": field_value2,
  ...
}

其中每個 field_value 都會根據它的類型格式化。 如果 field_value 是非空白 ARRAY 或 STRUCT,元素會縮排至適當的層級。空白結構會表示為 {}

具有重複名稱的欄位可能會導致 JSON 無法剖析。匿名欄位會以 "" 表示。

無效的 UTF-8 欄位名稱可能會導致 JSON 無法剖析。字串值會根據 JSON 標準逸出。具體而言,會逸出 "\ 與從 U+0000U+001F 的控制字元。

傳回類型

值的 JSON 字串表示。

範例

將資料表中的資料列轉換為 JSON。

WITH Input AS (
  SELECT [1, 2] AS x, 'foo' AS y, STRUCT(true AS a, DATE '2017-04-05' AS b) AS s UNION ALL
  SELECT NULL AS x, '' AS y, STRUCT(false AS a, DATE '0001-01-01' AS b) AS s UNION ALL
  SELECT [3] AS x, 'bar' AS y, STRUCT(NULL AS a, DATE '2016-12-05' AS b) AS s
)
SELECT
  t,
  TO_JSON_STRING(t) AS json_row
FROM Input AS t;

上述查詢會產生下列結果:

+-----------------------------------+-------------------------------------------------------+
| t                                 | json_row                                              |
+-----------------------------------+-------------------------------------------------------+
| {[1, 2], foo, {true, 2017-04-05}} | {"x":[1,2],"y":"foo","s":{"a":true,"b":"2017-04-05"}} |
| {NULL, , {false, 0001-01-01}}     | {"x":null,"y":"","s":{"a":false,"b":"0001-01-01"}}    |
| {[3], bar, {NULL, 2016-12-05}}    | {"x":[3],"y":"bar","s":{"a":null,"b":"2016-12-05"}}   |
+-----------------------------------+-------------------------------------------------------+

連同格式一起將資料表中的資料列轉換為 JSON。

WITH Input AS (
  SELECT [1, 2] AS x, 'foo' AS y, STRUCT(true AS a, DATE '2017-04-05' AS b) AS s UNION ALL
  SELECT NULL AS x, '' AS y, STRUCT(false AS a, DATE '0001-01-01' AS b) AS s UNION ALL
  SELECT [3] AS x, 'bar' AS y, STRUCT(NULL AS a, DATE '2016-12-05' AS b) AS s
)
SELECT
  TO_JSON_STRING(t, true) AS json_row
FROM Input AS t;

上述查詢會產生下列結果:

+-----------------------+
| json_row              |
+-----------------------+
| {                     |
|  "x": [               |
|    1,                 |
|    2                  |
|  ],                   |
|  "y": "foo",          |
|  "s": {               |
|    "a": true,         |
|    "b": "2017-04-05"  |
|  }                    |
|}                      |
| {                     |
|  "x": null,           |
|  "y": "",             |
|  "s": {               |
|    "a": false,        |
|    "b": "0001-01-01"  |
|  }                    |
|}                      |
| {                     |
|  "x": [               |
|    3                  |
|  ],                   |
|  "y": "bar",          |
|  "s": {               |
|    "a": null,         |
|    "b": "2016-12-05"  |
|  }                    |
|}                      |
+-----------------------+

Array 函式

ARRAY

ARRAY(subquery)

說明

ARRAY 函式會傳回 ARRAY子查詢中的每個資料列都有一個元素。

如果 subquery 產生 SQL 資料表,則該資料表只能有一個資料欄。輸出 ARRAY 中的每個元素都是資料表中資料列的單一資料欄的值。

如果 subquery 產生值資料表,則輸出 ARRAY 中的每個元素都是值資料表的完整對應資料列。

限制

  • 子查詢沒有排序,所以輸出 ARRAY 的元素不會保證保留子查詢來源資料表中的任何順序。但是,如果子查詢包含 ORDER BY 子句,ARRAY 函式將會傳回遵循那個子句的 ARRAY
  • 如果子查詢傳回一個以上的資料欄,ARRAY 函式會傳回錯誤。
  • 如果子查詢傳回 ARRAY 類型資料欄或 ARRAY 類型資料列,則 ARRAY 函式會傳回錯誤:BigQuery 不支援元素類型為 ARRAYARRAY
  • 如果子查詢傳回零個資料列,ARRAY 函式就會傳回空 ARRAY。它永遠不會傳回 NULL ARRAY

傳回類型

ARRAY

範例

SELECT ARRAY
  (SELECT 1 UNION ALL
   SELECT 2 UNION ALL
   SELECT 3) AS new_array;

+-----------+
| new_array |
+-----------+
| [1, 2, 3] |
+-----------+

若要從包含多個資料欄的子查詢中建構 ARRAY,請變更使子查詢使用 SELECT AS STRUCT。現在 ARRAY 函式將會傳回 STRUCTARRAYARRAY 將會針對子查詢中的每個資料列包含一個 STRUCT,而這裡的每一個 STRUCT 都將針對那個資料列中的每個資料欄包含一個欄位。

SELECT
  ARRAY
    (SELECT AS STRUCT 1, 2, 3
     UNION ALL SELECT AS STRUCT 4, 5, 6) AS new_array;

+------------------------+
| new_array              |
+------------------------+
| [{1, 2, 3}, {4, 5, 6}] |
+------------------------+

同樣的,若要從包含一或多個 ARRAY 的子查詢中建構 ARRAY,請將子查詢變更為使用 SELECT AS STRUCT

SELECT ARRAY
  (SELECT AS STRUCT [1, 2, 3] UNION ALL
   SELECT AS STRUCT [4, 5, 6]) AS new_array;

+----------------------------+
| new_array                  |
+----------------------------+
| [{[1, 2, 3]}, {[4, 5, 6]}] |
+----------------------------+

ARRAY_CONCAT

ARRAY_CONCAT(array_expression_1 [, array_expression_n])

說明

將具有相同元素類型的一或多個陣列串連為單一陣列。

傳回類型

ARRAY

範例

SELECT ARRAY_CONCAT([1, 2], [3, 4], [5, 6]) as count_to_six;

+--------------------------------------------------+
| count_to_six                                     |
+--------------------------------------------------+
| [1, 2, 3, 4, 5, 6]                               |
+--------------------------------------------------+

ARRAY_LENGTH

ARRAY_LENGTH(array_expression)

說明

傳回陣列的大小。若是空陣列,就會傳回 0。如果 array_expressionNULL,就會傳回 NULL

傳回類型

INT64

範例

WITH items AS
  (SELECT ["apples", "bananas", NULL, "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list, ARRAY_LENGTH(list) AS size
FROM items
ORDER BY size DESC;

+---------------------------------+------+
| list                            | size |
+---------------------------------+------+
| [apples, bananas, NULL, grapes] | 4    |
| [coffee, tea, milk]             | 3    |
| [cake, pie]                     | 2    |
+---------------------------------+------+

ARRAY_TO_STRING

ARRAY_TO_STRING(array_expression, delimiter[, null_text])

說明

array_expression 中的元素串連傳回為 STRING。array_expression 的值可以是 STRING 或 BYTES 資料類型的陣列。

如果使用 null_text 參數,函式會將陣列中的任何  NULL 值取代為 null_text 的值。

若未使用 null_text 參數,函式會忽略 NULL 值和它的先前分隔符號。

範例

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie", NULL] as list)

SELECT ARRAY_TO_STRING(list, '--') AS text
FROM items;

+--------------------------------+
| text                           |
+--------------------------------+
| apples--bananas--pears--grapes |
| coffee--tea--milk              |
| cake--pie                      |
+--------------------------------+

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie", NULL] as list)

SELECT ARRAY_TO_STRING(list, '--', 'MISSING') AS text
FROM items;

+--------------------------------+
| text                           |
+--------------------------------+
| apples--bananas--pears--grapes |
| coffee--tea--milk              |
| cake--pie--MISSING             |
+--------------------------------+

GENERATE_ARRAY

GENERATE_ARRAY(start_expression, end_expression[, step_expression])

說明

傳回值的陣列。start_expressionend_expression 參數可決定陣列的包含開始與結束。

GENERATE_ARRAY 函式接受下列資料類型作為輸入:

  • INT64
  • NUMERIC
  • FLOAT64

step_expression 參數可決定用來產生陣列值的遞增量。這個參數的預設值是 1

若將 step_expression 設定為 0,或如果任何輸入是 NaN,這個函式就會傳回錯誤。

如果任何引數是 NULL,函式將會傳回 NULL 陣列。

傳回資料類型

ARRAY

範例

以下會以預設步階 1 傳回整數的陣列。

SELECT GENERATE_ARRAY(1, 5) AS example_array;

+-----------------+
| example_array   |
+-----------------+
| [1, 2, 3, 4, 5] |
+-----------------+

以下會使用使用者指定的步階大小傳回陣列。

SELECT GENERATE_ARRAY(0, 10, 3) AS example_array;

+---------------+
| example_array |
+---------------+
| [0, 3, 6, 9]  |
+---------------+

以下會使用負值 -3 作為它的步階大小傳回陣列。

SELECT GENERATE_ARRAY(10, 0, -3) AS example_array;

+---------------+
| example_array |
+---------------+
| [10, 7, 4, 1] |
+---------------+

以下會使用 start_expressionend_expression 的相同值傳回陣列。

SELECT GENERATE_ARRAY(4, 4, 10) AS example_array;

+---------------+
| example_array |
+---------------+
| [4]           |
+---------------+

以下會傳回空陣列,因為 start_expression 大於 end_expression,且 step_expression 值為正。

SELECT GENERATE_ARRAY(10, 0, 3) AS example_array;

+---------------+
| example_array |
+---------------+
| []            |
+---------------+

以下會傳回 NULL 陣列,因為 end_expressionNULL

SELECT GENERATE_ARRAY(5, NULL, 1) AS example_array;

+---------------+
| example_array |
+---------------+
| NULL          |
+---------------+

以下會傳回多個陣列。

SELECT GENERATE_ARRAY(start, 5) AS example_array
FROM UNNEST([3, 4, 5]) AS start;

+---------------+
| example_array |
+---------------+
| [3, 4, 5]     |
| [4, 5]        |
| [5]           |
+---------------+

GENERATE_DATE_ARRAY

GENERATE_DATE_ARRAY(start_date, end_date[, INTERVAL INT64_expr date_part])

說明

傳回日期的陣列。start_dateend_date 參數可決定陣列的包含開始與結束。

GENERATE_DATE_ARRAY 函式會將下列資料類型接受為輸入:

  • start_date 必須是 DATE
  • end_date 必須是 DATE
  • INT64_expr 必須是 INT64
  • date_part 必須是 DAY、WEEK、MONTH、QUARTER 或 YEAR。

INT64_expr 參數可決定用來產生日期的遞增。這個參數的預設值是 1 天。

若將 INT64_expr 設定為 0,這個函式會傳回錯誤。

傳回資料類型

包含 0 或多個 DATE 值的 ARRAY。

範例

以下會以預設步階 1 傳回日期的陣列。

SELECT GENERATE_DATE_ARRAY('2016-10-05', '2016-10-08') AS example;

+--------------------------------------------------+
| example                                          |
+--------------------------------------------------+
| [2016-10-05, 2016-10-06, 2016-10-07, 2016-10-08] |
+--------------------------------------------------+

以下會使用使用者指定的步階大小傳回陣列。

SELECT GENERATE_DATE_ARRAY(
 '2016-10-05', '2016-10-09', INTERVAL 2 DAY) AS example;

+--------------------------------------+
| example                              |
+--------------------------------------+
| [2016-10-05, 2016-10-07, 2016-10-09] |
+--------------------------------------+

以下會使用負值 -3 作為它的步階大小傳回陣列。

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-01', INTERVAL -3 DAY) AS example;

+--------------------------+
| example                  |
+--------------------------+
| [2016-10-05, 2016-10-02] |
+--------------------------+

以下會使用 start_dateend_date 的相同值傳回陣列。

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-05', INTERVAL 8 DAY) AS example;

+--------------+
| example      |
+--------------+
| [2016-10-05] |
+--------------+

以下會傳回空陣列,因為 start_date 大於 end_date,且 step 值為正。

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-01', INTERVAL 1 DAY) AS example;

+---------+
| example |
+---------+
| []      |
+---------+

以下會傳回 NULL 陣列,因為它的其中一個輸入是 NULL

SELECT GENERATE_DATE_ARRAY('2016-10-05', NULL) AS example;

+---------+
| example |
+---------+
| NULL    |
+---------+

以下會使用 MONTH 作為 date_part 間隔傳回日期的陣列:

SELECT GENERATE_DATE_ARRAY('2016-01-01',
  '2016-12-31', INTERVAL 2 MONTH) AS example;

+--------------------------------------------------------------------------+
| example                                                                  |
+--------------------------------------------------------------------------+
| [2016-01-01, 2016-03-01, 2016-05-01, 2016-07-01, 2016-09-01, 2016-11-01] |
+--------------------------------------------------------------------------+

以下使用非常數日期來產生陣列。

WITH StartsAndEnds AS (
  SELECT DATE '2016-01-01' AS date_start, DATE '2016-01-31' AS date_end
  UNION ALL SELECT DATE "2016-04-01", DATE "2016-04-30"
  UNION ALL SELECT DATE "2016-07-01", DATE "2016-07-31"
  UNION ALL SELECT DATE "2016-10-01", DATE "2016-10-31"
)
SELECT GENERATE_DATE_ARRAY(date_start, date_end, INTERVAL 1 WEEK) AS date_range
FROM StartsAndEnds;

+--------------------------------------------------------------+
| date_range                                                   |
+--------------------------------------------------------------+
| [2016-01-01, 2016-01-08, 2016-01-15, 2016-01-22, 2016-01-29] |
| [2016-04-01, 2016-04-08, 2016-04-15, 2016-04-22, 2016-04-29] |
| [2016-07-01, 2016-07-08, 2016-07-15, 2016-07-22, 2016-07-29] |
| [2016-10-01, 2016-10-08, 2016-10-15, 2016-10-22, 2016-10-29] |
+--------------------------------------------------------------+

GENERATE_TIMESTAMP_ARRAY

GENERATE_TIMESTAMP_ARRAY(start_timestamp, end_timestamp,
                         INTERVAL step_expression date_part)

說明

傳回按指定間隔區隔 TIMESTAMPSARRAYstart_timestampend_timestamp 參數決定 ARRAY 的上下界 (含)。

GENERATE_TIMESTAMP_ARRAY 函式接受下列資料類型做為輸入:

  • start_timestampTIMESTAMP
  • end_timestampTIMESTAMP
  • step_expressionINT64
  • 允許的 date_part 值有:

MICROSECONDMILLISECOND

SECONDMINUTEHOURDAY

step_expression 參數決定用來產生時間戳記的遞增量。

傳回資料類型

含有 0 或多個 TIMESTAMP 值的 ARRAY

範例

以下範例傳回 TIMESTAMP 以 1 秒為間隔的 ARRAY

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-05 00:00:00', '2016-10-05 00:00:02',
                                INTERVAL 1 SECOND) AS timestamp_array;

+--------------------------------------------------------------------------+
| timestamp_array                                                          |
+--------------------------------------------------------------------------+
| [2016-10-05 00:00:00+00, 2016-10-05 00:00:01+00, 2016-10-05 00:00:02+00] |
+--------------------------------------------------------------------------+

以下範例傳回 TIMESTAMPS 含有負間隔的 ARRAY

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-06 00:00:00', '2016-10-01 00:00:00',
                                INTERVAL -2 DAY) AS timestamp_array;

+--------------------------------------------------------------------------+
| timestamp_array                                                          |
+--------------------------------------------------------------------------+
| [2016-10-06 00:00:00+00, 2016-10-04 00:00:00+00, 2016-10-02 00:00:00+00] |
+--------------------------------------------------------------------------+

以下範例傳回單一元素組成的 ARRAY,因為 start_timestampend_timestamp 的值相同。

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-05 00:00:00', '2016-10-05 00:00:00',
                                INTERVAL 1 HOUR) AS timestamp_array;

+--------------------------+
| timestamp_array          |
+--------------------------+
| [2016-10-05 00:00:00+00] |
+--------------------------+

以下範例傳回空的 ARRAY,因為 start_timestamp 的時間比 end_timestamp 晚。

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-06 00:00:00', '2016-10-05 00:00:00',
                                INTERVAL 1 HOUR) AS timestamp_array;

+-----------------+
| timestamp_array |
+-----------------+
| []              |
+-----------------+

以下範例傳回空值 ARRAY,因為其中一個輸入是 NULL

SELECT GENERATE_TIMESTAMP_ARRAY('2016-10-05 00:00:00', NULL, INTERVAL 1 HOUR)
  AS timestamp_array;

+-----------------+
| timestamp_array |
+-----------------+
| NULL            |
+-----------------+

以下範例從含有 start_timestampend_timestamp 值的資料欄,產生 TIMESTAMPARRAY

SELECT GENERATE_TIMESTAMP_ARRAY(start_timestamp, end_timestamp, INTERVAL 1 HOUR)
  AS timestamp_array
FROM
  (SELECT
    TIMESTAMP '2016-10-05 00:00:00' AS start_timestamp,
    TIMESTAMP '2016-10-05 02:00:00' AS end_timestamp
   UNION ALL
   SELECT
    TIMESTAMP '2016-10-05 12:00:00' AS start_timestamp,
    TIMESTAMP '2016-10-05 14:00:00' AS end_timestamp
   UNION ALL
   SELECT
    TIMESTAMP '2016-10-05 23:59:00' AS start_timestamp,
    TIMESTAMP '2016-10-06 01:59:00' AS end_timestamp);

+--------------------------------------------------------------------------+
| timestamp_array                                                          |
+--------------------------------------------------------------------------+
| [2016-10-05 00:00:00+00, 2016-10-05 01:00:00+00, 2016-10-05 02:00:00+00] |
| [2016-10-05 12:00:00+00, 2016-10-05 13:00:00+00, 2016-10-05 14:00:00+00] |
| [2016-10-05 23:59:00+00, 2016-10-06 00:59:00+00, 2016-10-06 01:59:00+00] |
+--------------------------------------------------------------------------+

OFFSET 與 ORDINAL

array_expression[OFFSET(zero_based_offset)]
array_expression[ORDINAL(one_based_offset)]

說明

存取特定位置的 ARRAY 元素,並傳回該元素的值。OFFSET 表示編號從零開始,ORDINAL 表示編號從一開始。

指定陣列可解讀為以 0 為基礎或以 1 為基礎。存取陣列元素時,您必須在陣列位置前面分別加上 OFFSETORDINAL;沒有預設行為。

如果索引超出範圍,OFFSETORDINAL 會產生錯誤。

傳回類型

因 ARRAY 中的元素而不同。

範例

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list, list[OFFSET(1)] as offset_1, list[ORDINAL(1)] as ordinal_1
FROM items;

+----------------------------------+-----------+-----------+
| list                             | offset_1  | ordinal_1 |
+----------------------------------+-----------+-----------+
| [apples, bananas, pears, grapes] | bananas   | apples    |
| [coffee, tea, milk]              | tea       | coffee    |
| [cake, pie]                      | pie       | cake      |
+----------------------------------+-----------+-----------+

ARRAY_REVERSE

ARRAY_REVERSE(value)

說明

以元素的對調順序傳回輸入 ARRAY。

傳回類型

ARRAY

範例

WITH example AS (
  SELECT [1, 2, 3] AS arr UNION ALL
  SELECT [4, 5] AS arr UNION ALL
  SELECT [] AS arr
)
SELECT
  arr,
  ARRAY_REVERSE(arr) AS reverse_arr
FROM example;

+-----------+-------------+
| arr       | reverse_arr |
+-----------+-------------+
| [1, 2, 3] | [3, 2, 1]   |
| [4, 5]    | [5, 4]      |
| []        | []          |
+-----------+-------------+

SAFE_OFFSET 與 SAFE_ORDINAL

array_expression[SAFE_OFFSET(zero_based_offset)]
array_expression[SAFE_ORDINAL(one_based_offset)]

說明

OFFSET 和 ORDINAL 相同,例外是如果索引超出範圍,會傳回 NULL

傳回類型

因 ARRAY 中的元素而不同。

範例

WITH items AS
  (SELECT ["apples", "bananas", "pears", "grapes"] as list
  UNION ALL
  SELECT ["coffee", "tea", "milk" ] as list
  UNION ALL
  SELECT ["cake", "pie"] as list)

SELECT list,
  list[SAFE_OFFSET(3)] as safe_offset_3,
  list[SAFE_ORDINAL(3)] as safe_ordinal_3
FROM items;

+----------------------------------+---------------+----------------+
| list                             | safe_offset_3 | safe_ordinal_3 |
+----------------------------------+---------------+----------------+
| [apples, bananas, pears, grapes] | grapes        | pears          |
| [coffee, tea, milk]              | NULL          | milk           |
| [cake, pie]                      | NULL          | NULL           |
+----------------------------------+---------------+----------------+

Date 函式

BigQuery 支援下列 DATE 函式。

CURRENT_DATE

CURRENT_DATE([time_zone])

說明

傳回指定或預設時區的目前日期。

這個函式支援選用 time_zone 參數。這個參數是代表要使用之時區的字串。如果沒有指定時區,就會使用預設時區 UTC。請參閱時區定義,瞭解如何指定時區。

如果 time_zone 參數評估為 NULL,這個函式會傳回 NULL

傳回資料類型

DATE

範例

SELECT CURRENT_DATE() as the_date;

+--------------+
| the_date     |
+--------------+
| 2016-12-25   |
+--------------+

EXTRACT

EXTRACT(part FROM date_expression)

說明

傳回對應於指定日期部分的值。part 必須是以下其中一項:

  • DAYOFWEEK:以星期日作為一週的第一天傳回 [1,7] 範圍中的值。
  • DAY
  • DAYOFYEAR
  • WEEK:傳回 [0, 53] 範圍中日期的週數。一週以星期日開始,而一年中第一個星期日之前的日期為第 0 週。

  • WEEK(<WEEKDAY>):傳回 [0, 53] 範圍中日期的週數。 一週以 WEEKDAY 開始。一年中第一個 WEEKDAY 之前的日期為第 0 週。WEEKDAY 的有效值為 SUNDAYMONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAY

  • ISOWEEK:傳回 date_expressionISO 8601 週數。ISOWEEK 以星期一開始。傳回值位於 [1, 53] 範圍中。每個 ISO 年的第一個 ISOWEEK 從公曆年第一個星期四之前的星期一開始。
  • MONTH
  • QUARTER:傳回 [1,4] 範圍中的值。
  • YEAR
  • ISOYEAR:傳回 ISO 8601 週數年,這是包含 date_expression 所屬之星期四的公曆年。

傳回資料類型

INT64

範例

在以下範例中,EXTRACT 會傳回對應於 DAY 時間部分的值。

SELECT EXTRACT(DAY FROM DATE '2013-12-25') as the_day;

+---------+
| the_day |
+---------+
| 25      |
+---------+

在以下範例中,EXTRACT 會傳回接近年底的日期資料欄中時間部分的對應值。

SELECT
  date,
  EXTRACT(ISOYEAR FROM date) AS isoyear,
  EXTRACT(ISOWEEK FROM date) AS isoweek,
  EXTRACT(YEAR FROM date) AS year,
  EXTRACT(WEEK FROM date) AS week
FROM UNNEST(GENERATE_DATE_ARRAY('2015-12-23', '2016-01-09')) AS date
ORDER BY date;
+------------+---------+---------+------+------+
| date       | isoyear | isoweek | year | week |
+------------+---------+---------+------+------+
| 2015-12-23 | 2015    | 52      | 2015 | 51   |
| 2015-12-24 | 2015    | 52      | 2015 | 51   |
| 2015-12-25 | 2015    | 52      | 2015 | 51   |
| 2015-12-26 | 2015    | 52      | 2015 | 51   |
| 2015-12-27 | 2015    | 52      | 2015 | 52   |
| 2015-12-28 | 2015    | 53      | 2015 | 52   |
| 2015-12-29 | 2015    | 53      | 2015 | 52   |
| 2015-12-30 | 2015    | 53      | 2015 | 52   |
| 2015-12-31 | 2015    | 53      | 2015 | 52   |
| 2016-01-01 | 2015    | 53      | 2016 | 0    |
| 2016-01-02 | 2015    | 53      | 2016 | 0    |
| 2016-01-03 | 2015    | 53      | 2016 | 1    |
| 2016-01-04 | 2016    | 1       | 2016 | 1    |
| 2016-01-05 | 2016    | 1       | 2016 | 1    |
| 2016-01-06 | 2016    | 1       | 2016 | 1    |
| 2016-01-07 | 2016    | 1       | 2016 | 1    |
| 2016-01-08 | 2016    | 1       | 2016 | 1    |
| 2016-01-09 | 2016    | 1       | 2016 | 1    |
+------------+---------+---------+------+------+

在以下範例中,date_expression 在星期日。EXTRACT 會使用以星期日開始的週計算第一個資料欄,並且會使用以星期一開始的週計算第二個資料欄。

WITH table AS (SELECT DATE('2017-11-05') AS date)
SELECT
  date,
  EXTRACT(WEEK(SUNDAY) FROM date) AS week_sunday,
  EXTRACT(WEEK(MONDAY) FROM date) AS week_monday FROM table;

+------------+-------------+-------------+
| date       | week_sunday | week_monday |
+------------+-------------+-------------+
| 2017-11-05 | 45          | 44          |
+------------+-------------+-------------+

DATE

1. DATE(year, month, day)
2. DATE(timestamp_expression[, timezone])

說明

  1. 從表示年、月與日的 INT64 值中建構 DATE。
  2. timestamp_expression 轉換為 DATE 資料類型。它支援指定時區的選用參數。如果沒有指定時區,就會使用預設時區 UTC。

傳回資料類型

DATE

範例

SELECT
  DATE(2016, 12, 25) as date_ymd,
  DATE(TIMESTAMP "2016-12-25 05:30:00+07", "America/Los_Angeles") as date_tstz;

+------------+------------+
| date_ymd   | date_tstz  |
+------------+------------+
| 2016-12-25 | 2016-12-24 |
+------------+------------+

DATE_ADD

DATE_ADD(date_expression, INTERVAL INT64_expr date_part)

說明

在 DATE 中加上指定時間間隔。

DATE_ADD 支援下列 date_part 值:

  • DAY
  • WEEK。等於 7 DAY
  • MONTH
  • QUARTER
  • YEAR

當日期位於 (或接近) 一個月的最後一天時,MONTH、QUARTER 與 YEAR 部分需要特殊處理。如果結果月的天數少於原始日期天數,結果日就是新月的最後一天。

傳回資料類型

DATE

範例

SELECT DATE_ADD(DATE "2008-12-25", INTERVAL 5 DAY) as five_days_later;

+--------------------+
| five_days_later    |
+--------------------+
| 2008-12-30         |
+--------------------+

DATE_SUB

DATE_SUB(date_expression, INTERVAL INT64_expr date_part)

說明

從 DATE 中減去指定時間間隔。

DATE_SUB 支援下列 date_part 值:

  • DAY
  • WEEK。等於 7 DAY
  • MONTH
  • QUARTER
  • YEAR

當日期位於 (或接近) 一個月的最後一天時,MONTH、QUARTER 與 YEAR 部分需要特殊處理。如果結果月的天數少於原始日期天數,結果日就是新月的最後一天。

傳回資料類型

DATE

範例

SELECT DATE_SUB(DATE "2008-12-25", INTERVAL 5 DAY) as five_days_ago;

+---------------+
| five_days_ago |
+---------------+
| 2008-12-20    |
+---------------+

DATE_DIFF

DATE_DIFF(date_expression, date_expression, date_part)

說明

傳回兩個 date_expression 之間的 date_part 邊界數。 如果第一個日期發生在第二個日期之前,結果就是非負數。

DATE_DIFF 支援下列 date_part 值:

  • DAY
  • WEEK 這個日期部分從星期日開始。
  • WEEK(<WEEKDAY>):這個日期部分從 WEEKDAY 開始,WEEKDAY 的有效值是 SUNDAYMONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAY
  • ISOWEEK:使用 ISO 8601 週邊界。ISO 週從星期一開始。
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR:使用 ISO 8601 週數年邊界。ISO 年邊界是第一週的星期一,它的星期四屬於對應公曆年。

傳回資料類型

INT64

範例

SELECT DATE_DIFF(DATE '2010-07-07', DATE '2008-12-25', DAY) as days_diff;

+-----------+
| days_diff |
+-----------+
| 559       |
+-----------+
SELECT
  DATE_DIFF(DATE '2017-10-15', DATE '2017-10-14', DAY) as days_diff,
  DATE_DIFF(DATE '2017-10-15', DATE '2017-10-14', WEEK) as weeks_diff;

+-----------+------------+
| days_diff | weeks_diff |
+-----------+------------+
| 1         | 1          |
+-----------+------------+

以上範例顯示連續兩天的 DATE_DIFF 結果。 日期部分為 WEEKDATE_DIFF 會傳回 1,因為 DATE_DIFF 會在這個日期範圍中計算日期部分邊界數。每個 WEEK 都從星期日開始,因此在 2017-10-14 星期六與 2017-10-15 星期日之間有一個日期部分邊界。

以下範例顯示不同年份之兩個日期的 DATE_DIFF 結果。日期部分為 YEARDATE_DIFF 會傳回 3,因為它會計算兩個日期之間的公曆年邊界數。日期部分為 ISOYEARDATE_DIFF 會傳回 2,因為第二個日期屬於 ISO 年 2015。2015 日歷年的第一個星期四是 2015-01-01,所以 ISO 年 2015 在上一個 2014-12-29 星期一開始。

SELECT
  DATE_DIFF('2017-12-30', '2014-12-30', YEAR) AS year_diff,
  DATE_DIFF('2017-12-30', '2014-12-30', ISOYEAR) AS isoyear_diff;

+-----------+--------------+
| year_diff | isoyear_diff |
+-----------+--------------+
| 3         | 2            |
+-----------+--------------+

以下範例顯示連續兩天的 DATE_DIFF 結果。第一個日期在星期一,第二個日期在星期日。日期部分為 WEEKDATE_DIFF 會傳回 0,因為這個時間部分使用從星期日開始的週。日期部分為 WEEK(MONDAY)DATE_DIFF 會傳回 1。日期部分為 ISOWEEKDATE_DIFF 也會傳回 1,因為 ISO 週從星期一開始。

SELECT
  DATE_DIFF('2017-12-18', '2017-12-17', WEEK) AS week_diff,
  DATE_DIFF('2017-12-18', '2017-12-17', WEEK(MONDAY)) AS week_weekday_diff,
  DATE_DIFF('2017-12-18', '2017-12-17', ISOWEEK) AS isoweek_diff;

+-----------+-------------------+--------------+
| week_diff | week_weekday_diff | isoweek_diff |
+-----------+-------------------+--------------+
| 0         | 1                 | 1            |
+-----------+-------------------+--------------+

DATE_TRUNC

DATE_TRUNC(date_expression, date_part)

說明

將日期截斷至指定精細程度。

DATE_TRUNC 支援 date_part 的下列值:

  • DAY
  • WEEK
  • WEEK(<WEEKDAY>):將 date_expression 截斷至上一個從 WEEKDAY 開始一週的週邊界。WEEKDAY 的有效值為 SUNDAYMONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAY
  • ISOWEEK:將 date_expression 截斷至上一個 ISO 8601 週邊界。ISOWEEK 從星期一開始。每個 ISO 年的第一個 ISOWEEK 都包含對應公曆年的第一個星期四。任何早於這一天的 date_expression 都將截斷至上一個星期一。
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR:將 date_expression 截斷至上一個 ISO 8601 週數年邊界。ISO 年邊界是星期四屬於對應公曆年之第一週的星期一。

傳回資料類型

DATE

範例

SELECT DATE_TRUNC(DATE '2008-12-25', MONTH) as month;

+------------+
| month      |
+------------+
| 2008-12-01 |
+------------+

在以下範例中,原始日期在星期日。由於 date_partWEEK(MONDAY)DATE_TRUNC 會傳回上一個星期一的 DATE

SELECT date AS original, DATE_TRUNC(date, WEEK(MONDAY)) AS truncated
FROM (SELECT DATE('2017-11-05') AS date);

+------------+------------+
| original   | truncated  |
+------------+------------+
| 2017-11-05 | 2017-10-30 |
+------------+------------+

在以下範例中,原始 date_expression 在公曆年 2015。但是,帶有 ISOYEAR 日期部分的 DATE_TRUNC 會將 date_expression 截斷至 ISO 年 (而非公曆年) 的開始。2015 日歷年的第一個星期四是 2015-01-01,所以 ISO 年 2015 在上一個 2014-12-29 星期一開始。 因此 date_expression 2015-06-15 之前的 ISO 年邊界是 2014-12-29。

SELECT
  DATE_TRUNC('2015-06-15', ISOYEAR) AS isoyear_boundary,
  EXTRACT(ISOYEAR FROM DATE '2015-06-15') AS isoyear_number;

+------------------+----------------+
| isoyear_boundary | isoyear_number |
+------------------+----------------+
| 2014-12-29       | 2015           |
+------------------+----------------+

DATE_FROM_UNIX_DATE

DATE_FROM_UNIX_DATE(INT64_expression)

說明

INT64_expression 解讀為從 1970-01-01 算起的天數。

傳回資料類型

DATE

範例

SELECT DATE_FROM_UNIX_DATE(14238) as date_from_epoch;

+-----------------+
| date_from_epoch |
+-----------------+
| 2008-12-25      |
+-----------------+

FORMAT_DATE

FORMAT_DATE(format_string, date_expr)

說明

根據指定的 format_string 格式化 date_expr

如需這個函式支援的格式元素清單,請參閱 DATE 的支援格式元素

傳回資料類型

STRING

範例

SELECT FORMAT_DATE("%x", DATE "2008-12-25") as US_format;

+------------+
| US_format  |
+------------+
| 12/25/08   |
+------------+

PARSE_DATE

PARSE_DATE(format_string, date_string)

說明

使用 format_string 與日期的字串表示傳回 DATE 物件。

使用 PARSE_DATE 時,請注意下列幾點:

  • 未指定的欄位。 任何未指定的欄位都從 1970-01-01 開始。
  • 區分大小寫的名稱。 例如 MondayFebruary 等的名稱都區分大小寫。
  • 空格字元。 格式字串中的一或多個連續空格字元都符合日期字串中的零或多個連續空格字元。此外,一律允許日期字串中的前置與尾隨空格字元 -- 即使它們不在格式字串中也一樣。
  • 格式優先順序。 當二 (或多) 個格式元素具有重疊資訊 (例如 %F%Y 都影響到年) 時,最後一個格式元素一般會覆寫任何之前的格式元素。

如需這個函式支援的格式元素清單,請參閱 DATE 的支援格式元素

傳回資料類型

DATE

範例

SELECT PARSE_DATE("%x", "12/25/08") as parsed;

+------------+
| parsed     |
+------------+
| 2008-12-25 |
+------------+

UNIX_DATE

UNIX_DATE(date_expression)

說明

傳回從 1970-01-01 算起的天數。

傳回資料類型

INT64

範例

SELECT UNIX_DATE(DATE "2008-12-25") as days_from_epoch;

+-----------------+
| days_from_epoch |
+-----------------+
| 14238           |
+-----------------+

DATE 的支援格式元素

除非另外提及,否則使用格式字串的 DATE 函式都支援下列元素:

格式元素 說明
%A 完整星期幾名稱。
%a 縮寫的星期幾名稱。
%B 完整月份名稱。
%b 或 %h 縮寫的月份名稱。
%C 以十進位數字 (00-99) 表示的世紀 (除以 100 並截斷至整數的年份)。
%D %m/%d/%y 格式的日期。
%d 以十進位數字 (01-31) 表示的每月日期。
%e 以十進位數字 (1-31) 表示的每月日期;單一數字前面會加上空格。
%F %Y-%m-%d 格式的日期。
%G 以十進位數字表示之帶有世紀的 ISO 8601 年份。每一個 ISO 年開始於公曆年第一個週四之前的週一。請注意 %G 和 %Y 可能在公曆年的界線附近產生不同的結果,其中公曆年和 ISO 年可能會有差異。
%g 以十進位數字 (00-99) 表示之不帶有世紀的 ISO 8601 年份。每一個 ISO 年開始於公曆年第一個週四之前的週一。請注意 %g 和 %y 可能在公曆年的界線附近產生不同的結果,其中公曆年和 ISO 年可能會有差異。
%j 以十進位數字 (001-366) 表示的每年日期。
%m 以十進位數字 (01-12) 表示的月份。
%n 換行字元。
%t 定位字元。
%U 以十進位數字 (00-53) 表示的每年週數 (星期日是每週的第一天)。
%u 以十進位數字 (1-7) 表示的星期幾 (星期一是每週的第一天)。
%V 以十進位數字 (01-53) 表示的每年週數 (星期一是每週的第一天)。 如果包含 1 月 1 日的這一週在新的一年中有四天或四天以上,它就是第 1 週;否則它就是上一年的第 53 週,而下一週才是第 1 週。
%W 以十進位數字 (00-53) 表示的每年週數 (星期一是每週的第一天)。
%w 以十進位數字 (0-6) 表示的星期幾 (星期日是每週的第一天)。
%x MM/DD/YY 格式的日期表示。
%Y 以十進位數字表示的帶世紀年份。
%y 以十進位數字 (00-99) 表示的不帶世紀的年份,可選用前置零。可與 %C 混合。若未指定 %C,00-68 年屬於 2000 年這個世紀,69-99 年屬於 1900 年這個世紀。
%E4Y 四個字元的年份 (0001 ... 9999)。請注意,%Y 會產生完整轉譯年份所需之盡可能多的字元數。

DateTime 函式

BigQuery 支援下列 DATETIME 函式。

CURRENT_DATETIME

CURRENT_DATETIME([timezone])

說明

將目前時間傳回為 DATETIME 物件。

這個函式支援選用 timezone 參數。請參閱時區定義,瞭解如何指定時區。

傳回資料類型

DATETIME

範例

SELECT CURRENT_DATETIME() as now;

+----------------------------+
| now                        |
+----------------------------+
| 2016-05-19 10:38:47.046465 |
+----------------------------+

DATETIME

1. DATETIME(year, month, day, hour, minute, second)
2. DATETIME(date_expression, time_expression)
3. DATETIME(timestamp_expression [, timezone])

說明

  1. 使用表示年、月、日、時、分與秒的 INT64 值建構 DATETIME 物件。
  2. 使用 DATE 物件與 TIME 物件建構 DATETIME 物件。
  3. 使用 TIMESTAMP 物件建構 DATETIME 物件。它支援指定時區的選用參數。如果沒有指定時區,就會使用預設時區 UTC。

傳回資料類型

DATETIME

範例

SELECT
  DATETIME(2008, 12, 25, 05, 30, 00) as datetime_ymdhms,
  DATETIME(TIMESTAMP "2008-12-25 05:30:00+00", "America/Los_Angeles") as datetime_tstz;

+---------------------+---------------------+
| datetime_ymdhms     | datetime_tstz       |
+---------------------+---------------------+
| 2008-12-25 05:30:00 | 2008-12-24 21:30:00 |
+---------------------+---------------------+

DATETIME_ADD

DATETIME_ADD(datetime_expression, INTERVAL INT64_expr part)

說明

partINT64_expr 單位加到 DATETIME 物件中。

DATETIME_ADD 支援 part 的下列值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK。等於 7 DAY
  • MONTH
  • QUARTER
  • YEAR

當日期位於 (或接近) 一個月的最後一天時,MONTH、QUARTER 與 YEAR 部分需要特殊處理。如果結果月的天數少於原始 DATETIME 天數,結果日就是新月的最後一天。

傳回資料類型

DATETIME

範例

SELECT
  DATETIME "2008-12-25 15:30:00" as original_date,
  DATETIME_ADD(DATETIME "2008-12-25 15:30:00", INTERVAL 10 MINUTE) as later;

+-----------------------------+------------------------+
| original_date               | later                  |
+-----------------------------+------------------------+
| 2008-12-25 15:30:00         | 2008-12-25 15:40:00    |
+-----------------------------+------------------------+

DATETIME_SUB

DATETIME_SUB(datetime_expression, INTERVAL INT64_expr part)

說明

從 DATETIME 中減去 partINT64_expr 單位。

DATETIME_SUB 支援 part 的下列值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK。等於 7 DAY
  • MONTH
  • QUARTER
  • YEAR

當日期位於 (或接近) 一個月的最後一天時,MONTH、QUARTER 與 YEAR 部分需要特殊處理。如果結果月的天數少於原始 DATETIME 天數,結果日就是新月的最後一天。

傳回資料類型

DATETIME

範例

SELECT
  DATETIME "2008-12-25 15:30:00" as original_date,
  DATETIME_SUB(DATETIME "2008-12-25 15:30:00", INTERVAL 10 MINUTE) as earlier;

+-----------------------------+------------------------+
| original_date               | earlier                |
+-----------------------------+------------------------+
| 2008-12-25 15:30:00         | 2008-12-25 15:20:00    |
+-----------------------------+------------------------+

DATETIME_DIFF

DATETIME_DIFF(datetime_expression, datetime_expression, part)

說明

傳回兩個 datetime_expression 之間的 part 邊界數。 如果第一個 DATETIME 發生在第二個 DATETIME 之前,結果就是非負數。如果計算溢位結果類型就會擲回錯誤,例如兩個 DATETIME 物件之間的毫秒差異就會使 INT64 值溢位。

DATETIME_DIFF 支援下列 part 值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK:這個日期部分從星期日開始。
  • WEEK(<WEEKDAY>):這個日期部分從 WEEKDAY 開始,WEEKDAY 的有效值是 SUNDAYMONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAY
  • ISOWEEK:使用 ISO 8601 週邊界。ISO 週從星期一開始。
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR:使用 ISO 8601 週數年邊界。ISO 年邊界是星期四屬於對應公曆年之第一週的星期一。

傳回資料類型

INT64

範例

SELECT
  DATETIME "2010-07-07 10:20:00" as first_datetime,
  DATETIME "2008-12-25 15:30:00" as second_datetime,
  DATETIME_DIFF(DATETIME "2010-07-07 10:20:00",
    DATETIME "2008-12-25 15:30:00", DAY) as difference;

+----------------------------+------------------------+------------------------+
| first_datetime             | second_datetime        | difference             |
+----------------------------+------------------------+------------------------+
| 2010-07-07 10:20:00        | 2008-12-25 15:30:00    | 559                    |
+----------------------------+------------------------+------------------------+
SELECT
  DATETIME_DIFF(DATETIME '2017-10-15 00:00:00',
    DATETIME '2017-10-14 00:00:00', DAY) as days_diff,
  DATETIME_DIFF(DATETIME '2017-10-15 00:00:00',
    DATETIME '2017-10-14 00:00:00', WEEK) as weeks_diff;

+-----------+------------+
| days_diff | weeks_diff |
+-----------+------------+
| 1         | 1          |
+-----------+------------+

以上範例顯示相距 24 小時之兩個 DATETIMEDATETIME_DIFF 結果。部分為 WEEKDATETIME_DIFF 會傳回 1,因為 DATETIME_DIFF 會在 DATETIME 的這個範圍中計算部分邊界數。每個 WEEK 都從星期日開始,因此在 2017-10-14 00:00:00 星期六與 2017-10-15 00:00:00 星期日之間有一個部分邊界。

以下範例顯示不同年份之兩個日期的 DATETIME_DIFF 結果。日期部分為 YEARDATETIME_DIFF 會傳回 3,因為它會計算兩個 DATETIME 之間的公曆年邊界數。日期部分為 ISOYEARDATETIME_DIFF 會傳回 2,因為第二個 DATETIME 屬於 ISO 年 2015。2015 日歷年的第一個星期四是 2015-01-01,所以 ISO 年 2015 在上一個 2014-12-29 星期一開始。

SELECT
  DATETIME_DIFF('2017-12-30 00:00:00',
    '2014-12-30 00:00:00', YEAR) AS year_diff,
  DATETIME_DIFF('2017-12-30 00:00:00',
    '2014-12-30 00:00:00', ISOYEAR) AS isoyear_diff;

+-----------+--------------+
| year_diff | isoyear_diff |
+-----------+--------------+
| 3         | 2            |
+-----------+--------------+

以下範例顯示連續兩天的 DATETIME_DIFF 結果。第一個日期在星期一,第二個日期在星期日。日期部分為 WEEKDATETIME_DIFF 會傳回 0,因為這個時間部分使用從星期日開始的週。日期部分為 WEEK(MONDAY)DATETIME_DIFF 會傳回 1。日期部分為 ISOWEEKDATETIME_DIFF 也會傳回 1,因為 ISO 週從星期一開始。

SELECT
  DATETIME_DIFF('2017-12-18', '2017-12-17', WEEK) AS week_diff,
  DATETIME_DIFF('2017-12-18', '2017-12-17', WEEK(MONDAY)) AS week_weekday_diff,
  DATETIME_DIFF('2017-12-18', '2017-12-17', ISOWEEK) AS isoweek_diff;

+-----------+-------------------+--------------+
| week_diff | week_weekday_diff | isoweek_diff |
+-----------+-------------------+--------------+
| 0         | 1                 | 1            |
+-----------+-------------------+--------------+

DATETIME_TRUNC

DATETIME_TRUNC(datetime_expression, part)

說明

DATETIME 物件截斷至 part 的精細程度。

DATETIME_TRUNC 支援 part 的下列值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • WEEK(<WEEKDAY>):將 datetime_expression 截斷至上一個從 WEEKDAY 開始一週的週邊界。WEEKDAY 的有效值為 SUNDAYMONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAY
  • ISOWEEK:將 datetime_expression 截斷至上一個 ISO 8601 週邊界。ISOWEEK 從星期一開始。每個 ISO 年的第一個 ISOWEEK 都包含對應公曆年的第一個星期四。任何早於這一天的 date_expression 都將截斷至上一個星期一。
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR:將 datetime_expression 截斷至上一個 ISO 8601 週數年邊界。ISO 年邊界是星期四屬於對應公曆年之第一週的星期一。

傳回資料類型

DATETIME

範例

SELECT
  DATETIME "2008-12-25 15:30:00" as original,
  DATETIME_TRUNC(DATETIME "2008-12-25 15:30:00", DAY) as truncated;

+----------------------------+------------------------+
| original                   | truncated              |
+----------------------------+------------------------+
| 2008-12-25 15:30:00        | 2008-12-25 00:00:00    |
+----------------------------+------------------------+

在以下範例中,原始 DATETIME 在星期日。由於 partWEEK(MONDAY)DATE_TRUNC 會傳回上一個星期一的 DATETIME

SELECT
 datetime AS original,
 DATETIME_TRUNC(datetime, WEEK(MONDAY)) AS truncated
FROM (SELECT DATETIME(TIMESTAMP '2017-11-05 00:00:00') AS datetime);

+---------------------+---------------------+
| original            | truncated           |
+---------------------+---------------------+
| 2017-11-05 00:00:00 | 2017-10-30 00:00:00 |
+---------------------+---------------------+

在以下範例中,原始 datetime_expression 在公曆年 2015。但是,帶有 ISOYEAR 日期部分的 DATETIME_TRUNC 會將 datetime_expression 截斷至 ISO 年 (而非公曆年) 的開始。2015 日歷年的第一個星期四是 2015-01-01,所以 ISO 年 2015 在上一個 2014-12-29 星期一開始。 因此 datetime_expression 2015-06-15 00:00:00 之前的 ISO 年邊界是 2014-12-29。

SELECT
  DATETIME_TRUNC('2015-06-15 00:00:00', ISOYEAR) AS isoyear_boundary,
  EXTRACT(ISOYEAR FROM DATETIME '2015-06-15 00:00:00') AS isoyear_number;

+---------------------+----------------+
| isoyear_boundary    | isoyear_number |
+---------------------+----------------+
| 2014-12-29 00:00:00 | 2015           |
+---------------------+----------------+

FORMAT_DATETIME

FORMAT_DATETIME(format_string, datetime_expression)

說明

根據指定的 format_string 格式化 DATETIME 物件。如需這個函式支援的格式元素清單,請參閱 DATETIME 的支援格式元素

傳回資料類型

STRING

範例

SELECT
  FORMAT_DATETIME("%c", DATETIME "2008-12-25 15:30:00")
  AS formatted;

PARSE_DATETIME

PARSE_DATETIME(format_string, string)

說明

使用 format_string 和表示 DATETIMESTRING 傳回 DATETIME。如需這個函式支援的格式元素清單,請參閱日期時間的支援格式元素一節。

PARSE_DATETIME 根據下列規則解析 string

  • 未指定的欄位。 任何未指定的欄位都從 1970-01-01 00:00:00.0 開始。例如,如未指定年份,則預設為 1970
  • 區分大小寫的名稱。 例如 MondayFebruary 等的名稱都區分大小寫。
  • 空白字元。 格式字串中的一或多個連續空格字元都符合 DATETIME 字串中的零或多個連續空格字元。一律允許 DATETIME 字串中的前置與尾隨空格字元,即使這些字元不在格式字串中也一樣。
  • 格式優先順序。 當二 (或多) 個格式元素具有重疊資訊時,最後一個格式元素一般會覆寫任何之前的格式元素,但有一些例外。例如,%F%Y 都會影響年份,因此較早的元素會覆寫後者。請參閱日期時間的支援格式元素一節中 %s%C%y 的說明。

範例

下列範例將 STRING 文字解析為 DATETIME

SELECT PARSE_DATETIME('%Y-%m-%d %H:%M:%S', '1998-10-18 13:45:55') AS datetime;

以上查詢傳回下列結果:

+---------------------+
| datetime            |
+---------------------+
| 1998-10-18 13:45:55 |
+---------------------+

下列範例將包含自然語言格式之日期的 STRING 文字解析為 DATETIME

SELECT PARSE_DATETIME('%A, %B %e, %Y','Wednesday, December 19, 2018')
  AS datetime;

以上查詢傳回下列結果:

+---------------------+
| datetime            |
+---------------------+
| 2018-12-19 00:00:00 |
+---------------------+

傳回資料類型

DATETIME

DATETIME 的支援格式元素

除非另外提及,否則使用格式字串的 DATETIME 函式都支援下列元素:

格式元素 說明
%A 完整星期幾名稱。
%a 縮寫的星期幾名稱。
%B 完整月份名稱。
%b 或 %h 縮寫的月份名稱。
%C 以十進位數字 (00-99) 表示的世紀 (除以 100 並截斷至整數的年份)。
%c 日期與時間表示。
%D %m/%d/%y 格式的日期。
%d 以十進位數字 (01-31) 表示的每月日期。
%e 以十進位數字 (1-31) 表示的每月日期;單一數字前面會加上空格。
%F %Y-%m-%d 格式的日期。
%G 以十進位數字表示之帶有世紀的 ISO 8601 年份。每一個 ISO 年開始於公曆年第一個週四之前的週一。請注意 %G 和 %Y 可能在公曆年的界線附近產生不同的結果,其中公曆年和 ISO 年可能會有差異。
%g 以十進位數字 (00-99) 表示之不帶有世紀的 ISO 8601 年份。每一個 ISO 年開始於公曆年第一個週四之前的週一。請注意 %g 和 %y 可能在公曆年的界線附近產生不同的結果,其中公曆年和 ISO 年可能會有差異。
%H 以十進位數字 (00-23) 表示的小時 (24 小時制)。
%I 以十進位數字 (01-12) 表示的小時 (12 小時制)。
%j 以十進位數字 (001-366) 表示的每年日期。
%k 以十進位數字 (0-23) 表示的小時 (24 小時制);單一數字前面會加上空格。
%l 以十進位數字 (1-12) 表示的小時 (12 小時制);單一數字前面會加上空格。
%M 以十進位數字 (00-59) 表示的分鐘。
%m 以十進位數字 (01-12) 表示的月份。
%n 換行字元。
%P am 或 pm。
%p AM 或 PM。
%R %H:%M 格式的時間。
%r 使用 AM/PM 標記法的 12 小時制時間。
%S 以十進位數字 (00-60) 表示的秒。
%s 從 1970-01-01 00:00:00 算起的秒數。一律覆寫其他所有格式元素,無論 %s 出現在字串中的哪個位置。 如果出現多個 %s 元素,以最後一個為優先。
%T %H:%M:%S 格式的時間。
%t 定位字元。
%U 以十進位數字 (00-53) 表示的每年週數 (星期日是每週的第一天)。
%u 以十進位數字 (1-7) 表示的星期幾 (星期一是每週的第一天)。
%V 以十進位數字 (01-53) 表示的每年週數 (星期一是每週的第一天)。 如果包含 1 月 1 日的這一週在新的一年中有四天或四天以上,它就是第 1 週;否則它就是上一年的第 53 週,而下一週才是第 1 週。
%W 以十進位數字 (00-53) 表示的每年週數 (星期一是每週的第一天)。
%w 以十進位數字 (0-6) 表示的星期幾 (星期日是每週的第一天)。
%X HH:MM:SS 格式的時間表示。
%x MM/DD/YY 格式的日期表示。
%Y 以十進位數字表示的帶世紀年份。
%y 以十進位數字 (00-99) 表示的不帶世紀的年份,可選用前置零。可與 %C 混合。若未指定 %C,00-68 年屬於 2000 年這個世紀,69-99 年屬於 1900 年這個世紀。
%% 單一 % 字元。
%E#S 帶有分數精確度位數的秒。
%E*S 帶有完整分數精確度 (常值「*」) 的秒。
%E4Y 四個字元的年份 (0001 ... 9999)。請注意,%Y 會產生完整轉譯年份所需之盡可能多的字元數。

Time 函式

BigQuery 支援下列 TIME 函式。

CURRENT_TIME

CURRENT_TIME()

說明

將目前時間傳回為 TIME 物件。

傳回資料類型

TIME

範例

SELECT CURRENT_TIME() as now;

+----------------------------+
| now                        |
+----------------------------+
| 15:31:38.776361            |
+----------------------------+

TIME

1. TIME(hour, minute, second)
2. TIME(timestamp, [timezone])
3. TIME(datetime)

說明

  1. 使用表示時、分與秒的 INT64 值建構 TIME 物件。
  2. 使用 TIMESTAMP 物件建構 TIME 物件。它支援指定時區的選用參數。如果沒有指定時區,就會使用預設時區 UTC。
  3. 使用 DATETIME 物件建構 TIME 物件。

傳回資料類型

TIME

範例

SELECT
  TIME(15, 30, 00) as time_hms,
  TIME(TIMESTAMP "2008-12-25 15:30:00+08", "America/Los_Angeles") as time_tstz;
+----------+-----------+
| time_hms | time_tstz |
+----------+-----------+
| 15:30:00 | 23:30:00  |
+----------+-----------+
SELECT
  TIME(DATETIME "2008-12-25 15:30:00.000000") AS time_dt;
+----------+
| time_dt  |
+----------+
| 15:30:00 |
+----------+

TIME_ADD

TIME_ADD(time_expression, INTERVAL INT64_expr part)

說明

將 partINT64_expr 單位加到 TIME 物件中。

TIME_ADD 支援 part 的下列值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR

這個函式會在值超出 00:00:00 到 24:00:00 的邊界之外時自動調整。例如,如果您將一小時加到 23:30:00,傳回的值就是 00:30:00

傳回資料類型

TIME

範例

SELECT
  TIME "15:30:00" as original_time,
  TIME_ADD(TIME "15:30:00", INTERVAL 10 MINUTE) as later;

+-----------------------------+------------------------+
| original_time               | later                  |
+-----------------------------+------------------------+
| 15:30:00                    | 15:40:00               |
+-----------------------------+------------------------+

TIME_SUB

TIME_SUB(time_expression, INTERVAL INT_expr part)

說明

從 TIME 物件減去 partINT64_expr 單位。

TIME_SUB 支援 part 的下列值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR

這個函式會在值超出 00:00:00 到 24:00:00 的邊界之外時自動調整。例如,如果您從 00:30:00 減去一小時,傳回的值就是 23:30:00

傳回資料類型

TIME

範例

SELECT
  TIME "15:30:00" as original_date,
  TIME_SUB(TIME "15:30:00", INTERVAL 10 MINUTE) as earlier;

+-----------------------------+------------------------+
| original_date                | earlier                |
+-----------------------------+------------------------+
| 15:30:00                    | 15:20:00               |
+-----------------------------+------------------------+

TIME_DIFF

TIME_DIFF(time_expression, time_expression, part)

說明

傳回兩個 TIME 物件之間的完整指定 part 間隔數。如果計算溢位結果類型就會擲回錯誤,例如兩個時間物件之間的毫秒差異就會使 INT64 值溢位。

TIME_DIFF 支援 part 的下列值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR

傳回資料類型

INT64

範例

SELECT
  TIME "15:30:00" as first_time,
  TIME "14:35:00" as second_time,
  TIME_DIFF(TIME "15:30:00", TIME "14:35:00", MINUTE) as difference;

+----------------------------+------------------------+------------------------+
| first_time                 | second_time            | difference             |
+----------------------------+------------------------+------------------------+
| 15:30:00                   | 14:35:00               | 55                     |
+----------------------------+------------------------+------------------------+

TIME_TRUNC

TIME_TRUNC(time_expression, part)

說明

將 TIME 物件截斷至 part 的精細程度。

TIME_TRUNC 支援 part 的下列值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR

傳回資料類型

TIME

範例

SELECT
  TIME "15:30:00" as original,
  TIME_TRUNC(TIME "15:30:00", HOUR) as truncated;

+----------------------------+------------------------+
| original                   | truncated              |
+----------------------------+------------------------+
| 15:30:00                   | 15:00:00               |
+----------------------------+------------------------+

FORMAT_TIME

FORMAT_TIME(format_string, time_object)

說明 根據指定的 format_string 格式化 TIME 物件。如需這個函式支援的格式元素清單,請參閱 TIME 的支援格式元素

傳回資料類型

STRING

範例

SELECT FORMAT_TIME("%R", TIME "15:30:00") as formatted_time;

+----------------+
| formatted_time |
+----------------+
| 15:30          |
+----------------+

PARSE_TIME

PARSE_TIME(format_string, string)

說明

使用 format_string 與字串傳回 TIME 物件。如需這個函式支援的格式元素清單,請參閱 TIME 的支援格式元素

使用 PARSE_TIME 時,請注意下列幾點:

  • 未指定的欄位。 任何未指定的欄位都從 00:00:00.0 開始。例如,若未指定 seconds,它的預設就是 00,依此類推。
  • 空格字元。 格式字串中的一或多個連續空格字元都符合 TIME 字串中的零或多個連續空格字元。此外,一律允許 TIME 字串中的前置與尾隨空格字元—即使它們不在格式字串中也一樣。
  • 格式優先順序。 當二 (或多) 個格式元素具有重疊資訊時,最後一個格式元素一般會覆寫任何之前的格式元素。

傳回資料類型

TIME

範例

SELECT PARSE_TIME("%H", "15") as parsed_time;

+-------------+
| parsed_time |
+-------------+
| 15:00:00    |
+-------------+

TIME 的支援格式元素

除非另外提及,否則使用格式字串的 TIME 函式都支援下列元素:

格式元素 說明
%H 以十進位數字 (00-23) 表示的小時 (24 小時制)。
%I 以十進位數字 (01-12) 表示的小時 (12 小時制)。
%j 以十進位數字 (001-366) 表示的每年日期。
%k 以十進位數字 (0-23) 表示的小時 (24 小時制);單一數字前面會加上空格。
%l 以十進位數字 (1-12) 表示的小時 (12 小時制);單一數字前面會加上空格。
%M 以十進位數字 (00-59) 表示的分鐘。
%n 換行字元。
%P am 或 pm。
%p AM 或 PM。
%R %H:%M 格式的時間。
%r 使用 AM/PM 標記法的 12 小時制時間。
%S 以十進位數字 (00-60) 表示的秒。
%T %H:%M:%S 格式的時間。
%t 定位字元。
%X HH:MM:SS 格式的時間表示。
%% 單一 % 字元。
%E#S 帶有分數精確度位數的秒。
%E*S 帶有完整分數精確度 (常值「*」) 的秒。

Timestamp 函式

BigQuery 支援下列 TIMESTAMP 函式。

注意:如果發生溢位,這些函式會傳回執行階段錯誤;結果值受限於定義的日期與時間戳記值下限/上限。

CURRENT_TIMESTAMP

CURRENT_TIMESTAMP()

說明

括號是選用的。這個函式可在插入的閏秒前後 20 個小時範圍內模糊化閏秒,藉以處理閏秒。 CURRENT_TIMESTAMP() 可產生連續、不模糊、每分鐘為正好 60 秒且不在遇到閏秒時重複值的 TIMESTAMP 值。

支援的輸入類型

不適用

結果資料類型

TIMESTAMP

範例

SELECT CURRENT_TIMESTAMP() as now;

+-------------------------------+
| now                           |
+-------------------------------+
| 2016-05-16 18:12:47.145482+00 |
+-------------------------------+

EXTRACT

EXTRACT(part FROM timestamp_expression [AT TIME ZONE tz_spec])

說明

從提供的 timestamp_expression 傳回對應於指定 partINT64 值。

允許的 part 值有:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAYOFWEEK
  • DAY
  • DAYOFYEAR
  • WEEK:傳回 [0, 53] 範圍中日期的週數。一週以星期日開始,而一年中第一個星期日之前的日期為第 0 週。

  • WEEK(<WEEKDAY>):傳回 [0, 53] 範圍中 timestamp_expression 的週數。一週以 WEEKDAY 開始。一年中第一個 WEEKDAY 之前的 datetime 為第 0 週。WEEKDAY 的有效值為 SUNDAYMONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAY

  • ISOWEEK:傳回 datetime_expressionISO 8601 週數。ISOWEEK 以星期一開始。傳回值位於 [1, 53] 範圍中。每個 ISO 年的第一個 ISOWEEK 從公曆年第一個星期四之前的星期一開始。

  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR:傳回 ISO 8601 週數年,這是包含 date_expression 所屬之星期四的公曆年。
  • DATE
  • DATETIME
  • TIME

傳回值會截斷順序較低的時段。例如,當擷取秒時,EXTRACT 會截斷毫秒與微秒值。

請參閱時區定義,瞭解如何指定時區。

傳回資料類型

一般為 INT64。如果 partDATE 就會傳回 DATE

範例

在以下範例中,EXTRACT 會傳回對應於 DAY 時間部分的值。

SELECT EXTRACT(DAY
  FROM TIMESTAMP "2008-12-25 15:30:00" AT TIME ZONE "America/Los_Angeles")
  AS the_day;

+------------+
| the_day    |
+------------+
| 25         |
+------------+

在以下範例中,EXTRACT 會傳回時間戳記資料欄中不同時間部分的對應值。

WITH Timestamps AS (
  SELECT TIMESTAMP '2005-01-03 12:34:56' AS timestamp UNION ALL
  SELECT TIMESTAMP '2007-12-31' UNION ALL
  SELECT TIMESTAMP '2009-01-01' UNION ALL
  SELECT TIMESTAMP '2009-12-31' UNION ALL
  SELECT TIMESTAMP '2017-01-02' UNION ALL
  SELECT TIMESTAMP '2017-05-26'
)
SELECT
  timestamp,
  EXTRACT(ISOYEAR FROM timestamp) AS isoyear,
  EXTRACT(ISOWEEK FROM timestamp) AS isoweek,
  EXTRACT(YEAR FROM timestamp) AS year,
  EXTRACT(WEEK FROM timestamp) AS week
FROM Timestamps
ORDER BY timestamp;
+------------------------+---------+---------+------+------+
| timestamp              | isoyear | isoweek | year | week |
+------------------------+---------+---------+------+------+
| 2005-01-03 12:34:56+00 | 2005    | 1       | 2005 | 1    |
| 2007-12-31 00:00:00+00 | 2008    | 1       | 2007 | 52   |
| 2009-01-01 00:00:00+00 | 2009    | 1       | 2009 | 0    |
| 2009-12-31 00:00:00+00 | 2009    | 53      | 2009 | 52   |
| 2017-01-02 00:00:00+00 | 2017    | 1       | 2017 | 1    |
| 2017-05-26 00:00:00+00 | 2017    | 21      | 2017 | 21   |
+------------------------+---------+---------+------+------+

在以下範例中,timestamp_expression 在星期日。EXTRACT 會使用以星期日開始的週計算第一個資料欄,並且會使用以星期一開始的週計算第二個資料欄。

WITH table AS (SELECT TIMESTAMP('2017-11-05 00:00:00') AS timestamp)
SELECT
  timestamp,
  EXTRACT(WEEK(SUNDAY) FROM timestamp) AS week_sunday,
  EXTRACT(WEEK(MONDAY) FROM timestamp) AS week_monday
FROM table;

+------------------------+-------------+---------------+
| timestamp              | week_sunday | week_monday |
+------------------------+-------------+---------------+
| 2017-11-05 00:00:00+00 | 45          | 44            |
+------------------------+-------------+---------------+

STRING

STRING(timestamp_expression[, timezone])

說明

timestamp_expression 轉換為 STRING 資料類型。支援指定時區的選用參數。請參閱時區定義,瞭解如何指定時區。

傳回資料類型

STRING

範例

SELECT STRING(TIMESTAMP "2008-12-25 15:30:00", "America/Los_Angeles") as string;

+-------------------------------+
| string                        |
+-------------------------------+
| 2008-12-25 15:30:00-08        |
+-------------------------------+

TIMESTAMP

1. TIMESTAMP(string_expression[, timezone])
2. TIMESTAMP(date_expression[, timezone])
3. TIMESTAMP(datetime_expression[, timezone])

說明

  1. 將 STRING 運算式轉換為 TIMESTAMP 資料類型。

  2. 將 DATE 物件轉換為 TIMESTAMP 資料類型。

  3. 將 DATETIME 物件轉換為 TIMESTAMP 資料類型。

這個函式支援指定時區的選用參數。如果沒有指定時區,就會使用預設時區 UTC。

傳回資料類型

TIMESTAMP

範例

SELECT
  CAST(TIMESTAMP("2008-12-25 15:30:00", "America/Los_Angeles") AS STRING) AS timestamp_str,
  CAST(TIMESTAMP(DATE "2008-12-25", "America/Los_Angeles") AS STRING) AS timestamp_date,
  CAST(TIMESTAMP(DATETIME "2008-12-25 15:30:00", "America/Los_Angeles") AS STRING) AS timestamp_datetime;

+------------------------+------------------------+------------------------+
| timestamp_str          | timestamp_date         | timestamp_datetime     |
+------------------------+------------------------+------------------------+
| 2008-12-25 23:30:00+00 | 2008-12-25 08:00:00+00 | 2008-12-25 23:30:00+00 |
+------------------------+------------------------+------------------------+

TIMESTAMP_ADD

TIMESTAMP_ADD(timestamp_expression, INTERVAL int64_expression date_part)

說明

將 date_partint64_expression 單位加入至時間戳記,與任何時區無關。

TIMESTAMP_ADD 支援 date_part 的下列值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR。等於 60 MINUTE

傳回資料類型

TIMESTAMP

範例

SELECT
  TIMESTAMP "2008-12-25 15:30:00 UTC" as original,
  TIMESTAMP_ADD(TIMESTAMP "2008-12-25 15:30:00 UTC", INTERVAL 10 MINUTE) AS later;

+------------------------+------------------------+
| original               | later                  |
+------------------------+------------------------+
| 2008-12-25 15:30:00+00 | 2008-12-25 15:40:00+00 |
+------------------------+------------------------+

TIMESTAMP_SUB

TIMESTAMP_SUB(timestamp_expression, INTERVAL int64_expression date_part)

說明

從時間戳記中減去 date_partint64_expression 單位,與任何時區無關。

TIMESTAMP_SUB 支援 date_part 的下列值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR。等於 60 MINUTE

傳回資料類型

TIMESTAMP

範例

SELECT
  TIMESTAMP "2008-12-25 15:30:00 UTC" as original,
  TIMESTAMP_SUB(TIMESTAMP "2008-12-25 15:30:00 UTC", INTERVAL 10 MINUTE) AS earlier;

+------------------------+------------------------+
| original               | earlier                |
+------------------------+------------------------+
| 2008-12-25 15:30:00+00 | 2008-12-25 15:20:00+00 |
+------------------------+------------------------+

TIMESTAMP_DIFF

TIMESTAMP_DIFF(timestamp_expression, timestamp_expression, date_part)

說明

傳回兩個時間戳記之間的完整指定 date_part 間隔數。第一個 timestamp_expression 代表較晚的日期;如果第一個 timestamp_expression 早於第二個 timestamp_expression,就會輸出負數。如果計算溢位結果類型就會擲回錯誤,例如兩個時間戳記之間的奈秒差異就會使 INT64 值溢位。

TIMESTAMP_DIFF 支援 date_part 的下列值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR。等於 60 MINUTE

傳回資料類型

INT64

範例

SELECT
  TIMESTAMP "2010-07-07 10:20:00 UTC" as later_timestamp,
  TIMESTAMP "2008-12-25 15:30:00 UTC" as earlier_timestamp,
  TIMESTAMP_DIFF(TIMESTAMP "2010-07-07 10:20:00 UTC",
    TIMESTAMP "2008-12-25 15:30:00 UTC", HOUR) AS hours;

+------------------------+------------------------+-------+
| later_timestamp        | earlier_timestamp      | hours |
+------------------------+------------------------+-------+
| 2010-07-07 10:20:00+00 | 2008-12-25 15:30:00+00 | 13410 |
+------------------------+------------------------+-------+

在下列範例中,由於第一個時間戳記早於第二個時間戳記,因此會輸出負數。

SELECT TIMESTAMP_DIFF(TIMESTAMP "2018-08-14", TIMESTAMP "2018-10-14", DAY);

+---------------+
| negative_diff |
+---------------+
| -61           |
+---------------+

TIMESTAMP_TRUNC

TIMESTAMP_TRUNC(timestamp_expression, date_part[, time_zone])

說明

將時間戳記截斷至 date_part 的精細程度。

TIMESTAMP_TRUNC 支援 date_part 的下列值:

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • WEEK(<WEEKDAY>):timestamp_expression 截斷至上一個從 WEEKDAY 開始一週的週邊界。WEEKDAY 的有效值為 SUNDAYMONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAY
  • ISOWEEK:將 timestamp_expression 截斷至上一個 ISO 8601 週邊界。ISOWEEK 從星期一開始。每個 ISO 年的第一個 ISOWEEK 都包含對應公曆年的第一個星期四。任何早於這一天的 date_expression 都將截斷至上一個星期一。
  • MONTH
  • QUARTER
  • YEAR
  • ISOYEAR:將 timestamp_expression 截斷至上一個 ISO 8601 週數年邊界。ISO 年邊界是星期四屬於對應公曆年之第一週的星期一。

TIMESTAMP_TRUNC 函式支援選用 time_zone 參數。這個參數適用於下列 date_parts

  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • WEEK(<WEEKDAY>)
  • MONTH
  • QUARTER
  • YEAR

如果您要使用預設時區世界標準時間以外的時區做為截斷操作的一部分,請使用這個參數。

TIMESTAMP 截斷成 MINUTEHOUR 時,TIMESTAMP_TRUNC 會判斷 TIMESTAMP 在指定 (或預設) 的時區中的民用時間,然後減去由該 TIMESTAMP 得來的分鐘和秒數 (當截斷成 HOUR 時) 或秒數 (當截斷成 MINUTE 時)。雖然這個方式在多數情況下可提供符合直覺的結果,但在日光節約轉換期間,時間未經校正的情況下,此結果不符合直覺。

傳回資料類型

TIMESTAMP

範例

SELECT
  TIMESTAMP_TRUNC(TIMESTAMP '2008-12-25 15:30:00', DAY, 'UTC') as utc,
  TIMESTAMP_TRUNC(TIMESTAMP '2008-12-25 15:30:00', DAY, 'America/Los_Angeles') as la;

+------------------------+------------------------+
| utc                    | la                     |
+------------------------+------------------------+
| 2008-12-25 00:00:00+00 | 2008-12-25 08:00:00+00 |
+------------------------+------------------------+

在以下範例中,timestamp_expression 的時區偏移為 +12。 第一個資料欄顯示 UTC 時間中的 timestamp_expression。第二個資料欄顯示使用從星期一開始的週之 TIMESTAMP_TRUNC 的輸出。 由於 timestamp_expression 在 UTC 的星期日,TIMESTAMP_TRUNC 會將它截斷至上一個星期一。第三個資料欄顯示具有選用時區定義引數「太平洋/奧克蘭」的相同函式。在這裡,函式會使用在星期一的紐西蘭夏令時間截斷 timestamp_expression

SELECT
  timestamp,
  TIMESTAMP_TRUNC(timestamp, WEEK(MONDAY)) AS utc_truncated,
  TIMESTAMP_TRUNC(timestamp, WEEK(MONDAY), 'Pacific/Auckland') AS nzdt_truncated
FROM (SELECT TIMESTAMP('2017-11-06 00:00:00+12') AS timestamp);

+------------------------+------------------------+------------------------+
| timestamp              | utc_truncated          | nzdt_truncated         |
+------------------------+------------------------+------------------------+
| 2017-11-05 12:00:00+00 | 2017-10-30 07:00:00+00 | 2017-11-05 11:00:00+00 |
+------------------------+------------------------+------------------------+

在以下範例中,原始 timestamp_expression 在公曆年 2015。但是,帶有 ISOYEAR 日期部分的 TIMESTAMP_TRUNC 會將 timestamp_expression 截斷至 ISO 年 (而非公曆年) 的開始。2015 日歷年的第一個星期四是 2015-01-01,所以 ISO 年 2015 在上一個 2014-12-29 星期一開始。 因此 timestamp_expression 2015-06-15 00:00:00+00 之前的 ISO 年邊界是 2014-12-29。

SELECT
  TIMESTAMP_TRUNC('2015-06-15 00:00:00+00', ISOYEAR) AS isoyear_boundary,
  EXTRACT(ISOYEAR FROM TIMESTAMP '2015-06-15 00:00:00+00') AS isoyear_number;

+------------------------+----------------+
| isoyear_boundary       | isoyear_number |
+------------------------+----------------+
| 2014-12-29 00:00:00+00 | 2015           |
+------------------------+----------------+

FORMAT_TIMESTAMP

FORMAT_TIMESTAMP(format_string, timestamp[, time_zone])

說明

根據指定的 format_string 格式化時間戳記。

如需這個函式支援的格式元素清單,請參閱 TIMESTAMP 的支援格式元素

傳回資料類型

STRING

範例

SELECT FORMAT_TIMESTAMP("%c", TIMESTAMP "2008-12-25 15:30:00", "America/Los_Angeles")
  AS formatted;

+--------------------------+
| formatted                |
+--------------------------+
| Thu Dec 25 07:30:00 2008 |
+--------------------------+

PARSE_TIMESTAMP

PARSE_TIMESTAMP(format_string, string[, time_zone])

說明

使用 format_string 與時間戳記的字串表示傳回 TIMESTAMP 物件。

使用 PARSE_TIMESTAMP 時,請注意下列幾點:

  • 未指定的欄位。 任何未指定的欄位都從 1970-01-01 00:00:00.0 開始。這個初始化值使用函式的時區引數指定的時區 (如果有的話)。如果沒有,初始化值會使用預設時區 UTC。例如,若未指定年份,它的預設就是 1970,依此類推。
  • 區分大小寫的名稱。 例如 MondayFebruary 等的名稱都區分大小寫。
  • 空格字元。 格式字串中的一或多個連續空格字元都符合時間戳記字串中的零或多個連續空格字元。此外,一律允許時間戳記字串中的前置與尾隨空格字元 -- 即使它們不在格式字串中也一樣。
  • 格式優先順序。 當二 (或多) 個格式元素具有重疊資訊 (例如 %F%Y 都影響到年) 時,最後一個格式元素一般會覆寫任何之前的格式元素,但有一些例外 (請參閱 %s%C%y 的說明)。

如需這個函式支援的格式元素清單,請參閱 TIMESTAMP 的支援格式元素

傳回資料類型

TIMESTAMP

範例

SELECT PARSE_TIMESTAMP("%c", "Thu Dec 25 07:30:00 2008", "America/Los_Angeles") as parsed;

+-------------------------+
| parsed                  |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_SECONDS

TIMESTAMP_SECONDS(int64_expression)

說明

int64_expression 解讀為從 1970-01-01 00:00:00 UTC 算起的秒數。

傳回資料類型

TIMESTAMP

範例

SELECT TIMESTAMP_SECONDS(1230219000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_MILLIS

TIMESTAMP_MILLIS(int64_expression)

說明

int64_expression 解讀為從 1970-01-01 00:00:00 UTC 算起的毫秒數。

傳回資料類型

TIMESTAMP

範例

SELECT TIMESTAMP_MILLIS(1230219000000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_MICROS

TIMESTAMP_MICROS(int64_expression)

說明

int64_expression 解讀為從 1970-01-01 00:00:00 UTC 算起的微秒數。

傳回資料類型

TIMESTAMP

範例

SELECT TIMESTAMP_MICROS(1230219000000000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

UNIX_SECONDS

UNIX_SECONDS(timestamp_expression)

說明

傳回從 1970-01-01 00:00:00 UTC 算起的秒數。會截斷較高層級的精確度。

傳回資料類型

INT64

範例

SELECT UNIX_SECONDS(TIMESTAMP "2008-12-25 15:30:00") as seconds;

+------------+
| seconds    |
+------------+
| 1230219000 |
+------------+

UNIX_MILLIS

UNIX_MILLIS(timestamp_expression)

說明

傳回從 1970-01-01 00:00:00 UTC 算起的毫秒數。會截斷較高層級的精確度。

傳回資料類型

INT64

範例

SELECT UNIX_MILLIS(TIMESTAMP "2008-12-25 15:30:00 UTC") as millis;

+---------------+
| millis        |
+---------------+
| 1230219000000 |
+---------------+

UNIX_MICROS

UNIX_MICROS(timestamp_expression)

說明

傳回從 1970-01-01 00:00:00 UTC 算起的微秒數。會截斷較高層級的精確度。

傳回資料類型

INT64

範例

SELECT UNIX_MICROS(TIMESTAMP "2008-12-25 15:30:00") as micros;

+------------------+
| micros           |
+------------------+
| 1230219000000000 |
+------------------+

TIMESTAMP 的支援格式元素

除非另外提及,否則使用格式字串的 TIMESTAMP 函式都支援下列元素:

格式元素 說明
%A 完整星期幾名稱。
%a 縮寫的星期幾名稱。
%B 完整月份名稱。
%b 或 %h 縮寫的月份名稱。
%C 以十進位數字 (00-99) 表示的世紀 (除以 100 並截斷至整數的年份)。
%c 日期與時間表示。
%D %m/%d/%y 格式的日期。
%d 以十進位數字 (01-31) 表示的每月日期。
%e 以十進位數字 (1-31) 表示的每月日期;單一數字前面會加上空格。
%F %Y-%m-%d 格式的日期。
%G 以十進位數字表示之帶有世紀的 ISO 8601 年份。每一個 ISO 年開始於公曆年第一個週四之前的週一。請注意 %G 和 %Y 可能在公曆年的界線附近產生不同的結果,其中公曆年和 ISO 年可能會有差異。
%g 以十進位數字 (00-99) 表示之不帶有世紀的 ISO 8601 年份。每一個 ISO 年開始於公曆年第一個週四之前的週一。請注意 %g 和 %y 可能在公曆年的界線附近產生不同的結果,其中公曆年和 ISO 年可能會有差異。
%H 以十進位數字 (00-23) 表示的小時 (24 小時制)。
%I 以十進位數字 (01-12) 表示的小時 (12 小時制)。
%j 以十進位數字 (001-366) 表示的每年日期。
%k 以十進位數字 (0-23) 表示的小時 (24 小時制);單一數字前面會加上空格。
%l 以十進位數字 (1-12) 表示的小時 (12 小時制);單一數字前面會加上空格。
%M 以十進位數字 (00-59) 表示的分鐘。
%m 以十進位數字 (01-12) 表示的月份。
%n 換行字元。
%P am 或 pm。
%p AM 或 PM。
%R %H:%M 格式的時間。
%r 使用 AM/PM 標記法的 12 小時制時間。
%S 以十進位數字 (00-60) 表示的秒。
%s 從 1970-01-01 00:00:00 UTC 算起的秒數。一律覆寫其他所有格式元素,無論 %s 出現在字串中的哪個位置。 如果出現多個 %s 元素,以最後一個為優先。
%T %H:%M:%S 格式的時間。
%t 定位字元。
%U 以十進位數字 (00-53) 表示的每年週數 (星期日是每週的第一天)。
%u 以十進位數字 (1-7) 表示的星期幾 (星期一是每週的第一天)。
%V 以十進位數字 (01-53) 表示的每年週數 (星期一是每週的第一天)。 如果包含 1 月 1 日的這一週在新的一年中有四天或四天以上,它就是第 1 週;否則它就是上一年的第 53 週,而下一週才是第 1 週。
%W 以十進位數字 (00-53) 表示的每年週數 (星期一是每週的第一天)。
%w 以十進位數字 (0-6) 表示的星期幾 (星期日是每週的第一天)。
%X HH:MM:SS 格式的時間表示。
%x MM/DD/YY 格式的日期表示。
%Y 以十進位數字表示的帶世紀年份。
%y 以十進位數字 (00-99) 表示的不帶世紀的年份,可選用前置零。可與 %C 混合。若未指定 %C,00-68 年屬於 2000 年這個世紀,69-99 年屬於 1900 年這個世紀。
%Z 時區名稱。
%z 視情況以 +HHMM 或 -HHMM 格式表示之與本初子午線之間的偏移,正值表示格林威治以東的位置。
%% 單一 % 字元。
%Ez RFC 3339 相容數字時區 (+HH:MM 或 -HH:MM)。
%E#S 帶有分數精確度位數的秒。
%E*S 帶有完整分數精確度 (常值「*」) 的秒。
%E4Y 四個字元的年份 (0001 ... 9999)。請注意,%Y 會產生完整轉譯年份所需之盡可能多的字元數。

時區定義

某些 date 與 timestamp 函式允許您覆寫預設時區並指定其他時區。您可以使用下列格式提供時區的 UTC 偏移來指定時區:

(+|-)H[H][:M[M]]

例如:

-08:00

地理位置函式

地理位置函式會對 BigQuery GEOGRAPHY 值進行運算或產生這些值。任何地理位置函式的簽名都是以 ST_ 開頭。BigQuery 支援下列函式,這些函示可用來分析地理資料、判斷地貌之間的空間關係,以及建構或操控 GEOGRAPHY

地理位置函式可根據其行為模式的不同,劃分成下列類別:

  • 建構函式:利用座標或現有 GEOGRAPHY 建構新 GEOGRAPHY 值的函式,例如 ST_GEOGPOINT
  • 剖析器:利用諸如 WKTGeoJSON 的外部格式建立 GEOGRAPHY 的函式。例如 ST_GEOGFROMTEXT,這個函式可利用 WKT 建立 GEOGRAPHY
  • 格式器:將 GEOGRAPHY 匯出為諸如 WKT 和 GeoJSON 等外部格式的函式。例如 ST_ASTEXT,這個函式可將 GEOGRAPHY 的格式設定為 WKT。
  • 轉換:利用符合某個屬性的其他 GEOGRAPHY 產生新 GEOGRAPHY 的函式。範例包括 ST_INTERSECTIONST_BOUNDARY
  • 述詞:針對兩個 GEOGRAPHY 之間的部分空間關係或針對地理位置的某個屬性傳回 TRUEFALSE 的函式。這些函式通常用於篩選條件子句,例如 ST_DWITHIN 就是這樣一個述詞。
  • 存取子:提供對 GEOGRAPHY 屬性的存取權且沒有副作用的函式,例如 ST_NUMPOINTS
  • 測量:對一或多個 GEOGRAPHY 的測量結果進行運算的函式,例如 ST_DISTANCE
  • 匯總函式:地理位置特定的匯總函式,例如 ST_UNION_AGG

如果任何輸入引數為 NULL,所有 BigQuery 地理位置函式都會傳回 NULL

ST_GEOGPOINT

ST_GEOGPOINT(longitude, latitude)

說明

建立具有單一點的 GEOGRAPHYST_GEOGPOINT 會利用指定的 FLOAT64 經度與緯度參數建立一個點,並在 GEOGRAPHY 值中傳回該點。

限制

  • 緯度必須介於 [-90, 90] 的範圍之間。若緯度超出此範圍,會發生錯誤。
  • 系統允許超出 [-180, 180] 範圍的精度;ST_GEOGPOINT 可使用輸入經度模數 360 取得位於 [-180, 180] 範圍內的精度。

傳回類型

GEOGRAPHY

ST_MAKELINE

ST_MAKELINE(geography_1, geography_2)
ST_MAKELINE(array_of_geography)

說明

按照所提供的順序串聯每個輸入 GEOGRAPHY 的點或線頂點,建立具備單一 LineString 的 GEOGRAPHY

ST_MAKELINE 有兩個變因。第一個變因的輸入內容必須是兩個 GEOGRAPHY,第二個變因的輸入內容必須是 GEOGRAPHY 類型的 ARRAY。在任一變因中,每個輸入內容的 GEOGRAPHY 必須包含下列其中一個值:

  • 只有一個點。
  • 只有一個 LineString。

ST_MAKELINE 的第一個變因中,如果輸入的其中一個 GEOGRAPHYNULL,則 ST_MAKELINE 會傳回 NULL。在第二個變因中,如果輸入 ARRAY 或輸入 ARRAY 中的任何元素為 NULL,則 ST_MAKELINE 會傳回 NULL

限制

每條邊線的跨度必須嚴格小於 180 度。

附註:BigQuery 的接合程序可能會捨棄足夠短的邊緣,並將兩個頂點接合在一起。例如,如果兩個輸入 GEOGRAPHY 各包含一個點,且兩個點之間的距離小於接合半徑,則這些點會接合在一起。在這種情況下,結果會是只有一個點的 GEOGRAPHY

傳回類型

GEOGRAPHY

ST_MAKEPOLYGON

ST_MAKEPOLYGON(geography_expression)
ST_MAKEPOLYGON(geography_expression, array_of_geography)

說明

利用 LineString 輸入建立含有單一多邊形的 GEOGRAPHY,當中的每個輸入 LineString 都用來建立多邊形環。

ST_MAKEPOLYOGN 有兩個變因。以第一個變因來說,輸入的 LineString 是由僅含一個 LineString 的單一 GEOGRAPHY 提供。以第二個變因來說,輸入內容含有單一 GEOGRAPHYGEOGRAPHY 陣列,且各項元素都包含一個 LineString。系統會使用兩個變因中的第一個 GEOGRAPHY 來建立多邊形殼。在輸入 ARRAY 中提供的其他 GEOGRAPHY 則指定了一個多邊形孔。每個只含一個 LineString 的輸入 GEOGRAPHY 必須滿足下列條件:

  • LineString 必須含有至少三個不同的頂點。
  • 必須關閉 linestring:也就是說,第一個和最後一個頂點必須相同。如果第一個和最後一個頂點不同,函式會從第一個頂點到最後一個頂點建構最終邊緣。

ST_MAKEPOLYGON 的第一個變因中,如果輸入的其中一個 GEOGRAPHYNULL,則 ST_MAKEPOLYOGN 會傳回 NULL。在第二個變因中,如果輸入 ARRAY 或輸入 ARRAY 中的任何元素為 NULL,則 ST_MAKEPOLYGON 會傳回 NULL

注意事項:ST_MAKEPOLYGON 接受空白的 GEOGRAPHY 輸入內容。ST_MAKEPOLYGON 會將空的 GEOGRAPHY 解譯為具有空的 linestring,如此會建立一個完整的環:即覆蓋整個地球的多邊形。

限制

總之,輸入環必須形成一個有效的多邊形:

  • 多邊形殼必須覆蓋每個多邊形孔。
  • 只能有一個多邊形殼 (必須是第一個輸入環)。這表示多邊形孔不能是巢狀。
  • 多邊形環只能在兩個環界線的頂點相交。

每條邊線的跨度必須嚴格小於 180 度。

每個多邊形環都會將球體分成兩個區域。ST_MAKEPOLYGON 的第一個輸入 linestring 會形成多邊形殼,並選擇內部為兩個區域中的較小者。每個後續的輸入 linestring 都會指定多邊形孔,因此多邊形的內部已有明確定義。如要定義多邊形殼,讓多邊形內部成為兩個區域中較大者,請參閱 ST_MAKEPOLYGONORIENTED 一節。

附註:BigQuery 的接合程序可能會捨棄足夠短的邊緣,並將兩個頂點接合在一起。因此,當頂點接合在一起時,足夠小的多邊形孔可能會消失,或者輸出 GEOGRAPHY 可能只包含一條線或一個點。

傳回類型

GEOGRAPHY

ST_MAKEPOLYGONORIENTED

ST_MAKEPOLYGONORIENTED(array_of_geography)

說明

ST_MAKEPOLYGON 一樣,但每個輸入 linestring 的頂點順序決定了每個多邊形環的方向。多邊形環的方向會以下列方式定義多邊形的內部:如果有人按照輸入頂點的順序沿著多邊形界線前進,多邊形的內部會在左側。這適用於提供的每個多邊形環。

由於 ST_MAKEPOLYGONORIENTED 可以建構多邊形,使得內部位於多邊形環的任一側,因此多邊形建構函式的這個變體更具彈性。不過,多邊形環的正確方向對於建立所需多邊形而言至關重要。

如果輸入 ARRAY 或任何在 ARRAY 中的元素為 NULL,則 ST_MAKEPOLYGONORIENTED 會傳回 NULL

注意事項:ST_MAKEPOLYGONORIENTED 的輸入引數可能含有空白的 GEOGRAPHYST_MAKEPOLYGONORIENTED 會將空白的 GEOGRAPHY 解譯為具備空白 LineString,這樣會建立一個完整的環:覆蓋整個地球的多邊形。

限制

總之,輸入環必須形成一個有效的多邊形:

  • 多邊形殼必須覆蓋每個多邊形孔。
  • 只能有一個多邊形殼 (必須是第一個輸入環)。這表示多邊形孔不能是巢狀。
  • 多邊形環只能在兩個環界線的頂點相交。

每條邊線的跨度必須嚴格小於 180 度。

ST_MAKEPOLYGONORIENTED 依賴於每個 linestring 的輸入頂點順序來確定多邊形的方向。這適用於多邊形殼和任何多邊形孔。ST_MAKEPOLYGONORIENTED 預期所有多邊形孔的殼體方向都相反。請參閱 ST_MAKEPOLYGON 一節,瞭解替代的多邊形建構函式,以及建立有效多邊形的其他限制。

附註:基於 BigQuery 的接合程序,系統會捨棄足夠短的邊緣,並將兩個頂點接合為單一點。因此,linestring 中的頂點可能會接合在一起,使一或多個邊緣消失。如此一來,足夠小的多邊形孔可能會消失,或者產生的 GEOGRAPHY 可能只包含一條線或一個點。

傳回類型

GEOGRAPHY

ST_GEOGFROMGEOJSON

ST_GEOGFROMGEOJSON(geojson_string)

說明

傳回與輸入 GeoJSON 表示法相對應的 GEOGRAPHY 值。

ST_GEOGFROMGEOJSON 接受符合 RFC 7946 規範的輸入值。

BigQuery GEOGRAPHY 具有球面測地線,而 GeoJSON Geometry 物件明確擁有平面邊緣。為了在這兩種邊緣系統之間進行轉換,BigQuery 會在必要時為線條加入額外的資料點,讓產生的邊緣序列維持在原始邊緣的 10 公尺範圍之內。

請參閱 ST_ASGEOJSON 一節,將 GEOGRAPHY 的格式設為 GeoJSON。

限制

輸入有下列限制:

  • ST_GEOGFROMGEOJSON 只接受 JSON 幾何圖形片段,且無法用來擷取整份 JSON 文件。
  • 輸入 JSON 片段必須包含 GeoJSON 幾何圖形類型,其中包括 PointMultiPointLineStringMultiLineStringPolygonMultiPolygonGeometryCollection。其他任何 GeoJSON 類型 (例如 FeatureFeatureCollection) 都會發生錯誤。
  • GeoJSON 幾何圖形類型 coordinates 成員中的位置必須只包含兩個元素。第一個元素是經度,第二個元素是緯度。因此,針對 coordinates 成員中的位置,ST_GEOGFROMGEOJSON 不支援選用的第三個元素。

傳回類型

GEOGRAPHY

ST_GEOGFROMTEXT

ST_GEOGFROMTEXT(wkt_string)
ST_GEOGFROMTEXT(wkt_string, oriented)

說明

傳回與輸入 WKT 表示法相對應的 GEOGRAPHY 值。

這個函式支援 BOOLoriented 類型的選用參數。如果這個參數設定為 TRUE,系統會假設輸入中的任何多邊形方向如下:如果有人按照輸入頂點的順序沿著多邊形界線前進,多邊形的內部會在左側。這可讓 WKT 顯示大於半球的多邊形。如果 orientedFALSE 或遭到省略,這個函式會傳回具備較小面積的多邊形。另請參閱 ST_MAKEPOLYGONORIENTED 一節,這個函式與 oriented=TRUEST_GEOGFROMTEXT 相似。

如要將 GEOGRAPHY 的格式設為 WKT,請使用 ST_ASTEXT

限制

假設所有輸入邊緣都是球面測地線,而「不是」平面直線。如要讀取平面投影中的資料,請考慮使用 ST_GEOGFROMGEOJSON。如要進一步瞭解球面測地線和平面線條之間的差異,請參閱座標系與邊緣一節。

傳回類型

GEOGRAPHY

範例

下列查詢會將 WKT 字串 POLYGON((0 0, 0 2, 2 2, 0 2, 0 0)) 讀取為非定向多邊形和定向多邊形,並檢查是否每個結果都包含點 (1, 1)

WITH polygon AS (SELECT 'Polygon((0 0, 0 2, 2 2, 2 0, 0 0))' AS p)
SELECT
  ST_CONTAINS(ST_GEOGFROMTEXT(p), ST_GEOGPOINT(1, 1)) AS fromtext_default,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, FALSE), ST_GEOGPOINT(1, 1)) AS non_oriented,
  ST_CONTAINS(ST_GEOGFROMTEXT(p, TRUE),  ST_GEOGPOINT(1, 1)) AS oriented
FROM polygon;

+-------------------+---------------+-----------+
| fromtext_default  | non_oriented  | oriented  |
+-------------------+---------------+-----------+
| true              | true          | false     |
+-------------------+---------------+-----------+

ST_GEOGFROMWKB

ST_GEOGFROMWKB(wkb_bytes)

說明

傳回與輸入 WKB 表示法相對應的 GEOGRAPHY 值。

如要將 GEOGRAPHY 的格式設為 WKB,請使用 ST_ASBINARY

限制

假設所有輸入邊緣都是球面測地線,而「不是」平面直線。如要讀取平面投影中的資料,請考慮使用 ST_GEOGFROMGEOJSON

傳回類型

GEOGRAPHY

ST_GEOGPOINTFROMGEOHASH

ST_STGEOGPOINTFROMGEOHASH(geohash)

說明

傳回與 GeoHash 中定義的定界框中間點相對應的 GEOGRAPHY 值。

傳回類型

GEOGRAPHY

ST_ASGEOJSON

ST_ASGEOJSON(geography_expression)

說明

傳回輸入 GEOGRAPHY 的符合 RFC 7946 規範的 GeoJSON 表示法。

BigQuery GEOGRAPHY 具有球面測地線,而 GeoJSON Geometry 物件明確擁有平面邊緣。為了在這兩種邊緣系統之間進行轉換,BigQuery 會在必要時為線條加入額外的資料點,讓產生的邊緣序列維持在原始邊緣的 10 公尺範圍之內。

請參閱 ST_GEOGFROMGEOJSON 一節,利用 GeoJSON 建立 GEOGRAPHY

傳回類型

STRING

ST_ASTEXT

ST_ASTEXT(geography_expression)

說明

傳回輸入 GEOGRAPHYWKT 表示法。

請參閱 ST_GEOGFROMTEXT 一節,利用 WKT 建立 GEOGRAPHY

傳回類型

STRING

ST_GEOHASH

ST_GEOHASH(geography_expression, maxchars)

說明

傳回 geography_expressionGeoHash 表示法。產生的 GeoHash 最多將包含 maxchars 個字元。字元越少,精確度就越低 (或者,用另一種方式表達,就是定界框會越大)。

空白 GEOGRAPHY 物件的 ST_GeoHash 會傳回 NULL

限制

  • 系統僅支援表示單一點的 GEOGRAPHY 物件。
  • maxchars 的最大值是 20。

範例

傳回精確度為 10 個字元的西雅圖中心的 GeoHash。

SELECT ST_GEOHASH(ST_GEOGPOINT(-122.35, 47.62), 10) geohash

+--------------+
| geohash      |
+--------------+
| c22yzugqw7   |
+--------------+

傳回類型

STRING

ST_ASBINARY

ST_ASBINARY(geography_expression)

說明

傳回輸入 GEOGRAPHYWKB 表示法。

請參閱 ST_GEOGFROMWKB 一節,利用 WKB 建立 GEOGRAPHY

傳回類型

BYTES

ST_BOUNDARY

ST_BOUNDARY(geography_expression)

說明

傳回單一 GEOGRAPHY,其中包含指定輸入 GEOGRAPHY 中每個元件的界線聯集。

GEOGRAPHY 每個元件的界線定義如下:

  • 點的界線為空。
  • linestring 的界線由 linestring 的端點組成。
  • 多邊形的界線由形成多邊形殼和每個多邊形孔的 linestring 組成。

傳回類型

GEOGRAPHY

ST_CENTROID

ST_CENTROID(geography_expression)

說明

傳回輸入 GEOGRAPHY 的「質心」來當做單一點 GEOGRAPHY

GEOGRAPHY 的「質心」GEOGRAPHY 中最高維度元件質心的加權平均值。每個維度中元件的質心定義如下:

  • 點的質心是輸入座標的算術平均值。
  • linestring 的質心是按長度加權的所有邊緣的質心。每個邊緣的質心是邊緣的測地線中點。
  • 多邊形的質心即為質量中心。

如果輸入 GEOGRAPHY 為空,函式會傳回空白 GEOGRAPHY

限制

GEOGRAPHY 的質心無法由地球表面的單一點定義 (儘管發生機率極低),這個函式會傳回具有確定性的任意點。只有在質心正好位於地球中心時 (例如一對對徑點的質心) 才會發生這種情況,而且發生的可能性極小。

傳回類型

GEOGRAPHY

ST_CLOSESTPOINT

ST_CLOSESTPOINT(geography_1, geography_2)
ST_CLOSESTPOINT(geography_1, geography_2, use_spheroid)

說明

傳回一個 GEOGRAPHY,其中包含 geography_1 中的點且該點與 geography_2 之間的距離可能最短。這表示 ST_CLOSESTPOINT 傳回的點和 geography_2 之間的距離小於或等於 geography_1 中的其他任何點和 geography_2 之間的距離。

如果任一輸入 GEOGRAPHY 為空,ST_CLOSESTPOINT 會傳回 NULL

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

GEOGRAPHY

ST_DIFFERENCE

ST_DIFFERENCE(geography_1, geography_2)

說明

傳回代表 geography_1geography_2 點集差異的 GEOGRAPHY

如果 geometry_1 完全包含在 geometry_2 中,則 ST_DIFFERENCE 會傳回空白 GEOGRAPHY

限制

BigQuery GEOGRAPHY 表示的基礎幾何物件與「封閉」的點集相對應。因此,ST_DIFFERENCE 可封閉 geography_1geography_2 的點集差異。這表示,如果 geography_1geography_2 相交,則 geography_2 的部分界線可能有差異。

傳回類型

GEOGRAPHY

ST_INTERSECTION

ST_INTERSECTION(geography_1, geography_2)

說明

傳回代表兩個輸入 GEOGRAPHY 之點集交集的 GEOGRAPHY。因此,交集中的每個點都會同時顯示在 geography_1geography_2 中。

如果兩個輸入 GEOGRAPHY 不相交,也就是說,沒有點同時顯示在輸入 geometry_1geometry_2 中,則函式會傳回空白 GEOGRAPHY

如要瞭解相關述詞函式,請參閱 ST_INTERSECTSST_DISJOINT 等節。

傳回類型

GEOGRAPHY

ST_SNAPTOGRID

ST_SNAPTOGRID(geography_expression, grid_size)

說明

傳回輸入 GEOGRAPHY,其中的每個頂點都已與經度/緯度格線對齊。格線大小由 grid_size 參數 (單位為度數) 決定。

限制

系統不支援任意格線大小。grid_size 參數會四捨五入,因此格式為 $$10^n$$,其中 $$-10 < n < 0$$。

傳回類型

GEOGRAPHY

ST_UNION

ST_UNION(geography_1, geography_2)
ST_UNION(array_of_geography)

說明

傳回代表所有輸入 GEOGRAPHY 點集聯集的 GEOGRAPHY

ST_UNION 有兩個變因。第一個變因的輸入內容必須是兩個 GEOGRAPHY,第二個變因的輸入則為 GEOGRAPHY 類型的 ARRAY

ST_UNION 的第一個變因中,如果輸入的 GEOGRAPHYNULL,則 ST_UNION 會傳回 NULL。在第二個變因中,如果輸入的 ARRAY 值為 NULL,則 ST_UNION 會傳回 NULL。對於並非 NULL 的輸入 ARRAY,會計算聯集並忽略 NULL 元素,以免影響輸出。

如要瞭解 ST_UNION 的匯總版本,請參閱 ST_UNION_AGG 一節。

傳回類型

GEOGRAPHY

ST_X

ST_X(geography_expression)

說明

傳回單一點輸入 GEOGRAPHY 的經度度數。

針對並非單一點的任何輸入 GEOGRAPHY,包括空白 GEOGRAPHY 在內,ST_X 都會傳會錯誤。請使用 SAFE. 前置字串取得 NULL

傳回類型

FLOAT64

範例

下列範例使用 ST_XST_Y 從單一點地理位置擷取座標。

WITH points AS
   (SELECT ST_GEOGPOINT(i, i + 1) AS p FROM UNNEST([0, 5, 12]) AS i)
 SELECT
   p,
   ST_X(p) as longitude,
   ST_Y(p) as latitude
FROM points;

+--------------+-----------+----------+
| p            | longitude | latitude |
+--------------+-----------+----------+
| POINT(0 1)   | 0.0       | 1.0      |
| POINT(5 6)   | 5.0       | 6.0      |
| POINT(12 13) | 12.0      | 13.0     |
+--------------+-----------+----------+

ST_Y

ST_Y(geography_expression)

說明

傳回單一點輸入 GEOGRAPHY 的緯度度數。

針對並非單一點的任何輸入 GEOGRAPHY,包括空白 GEOGRAPHY 在內,ST_Y 都會傳會錯誤。請改用 SAFE. 前置字串傳回 NULL

傳回類型

FLOAT64

範例

請參閱 ST_X 查看使用方式範例。

ST_CONTAINS

ST_CONTAINS(geography_1, geography_2)

說明

如果沒有 geography_2 的點位於 geography_1 之外,且內部相交,則會傳回 TRUE;否則會傳回 FALSE

注意事項:GEOGRAPHY「並不」包含本身的界線。請與 ST_COVERS 進行比較。

傳回類型

BOOL

範例

以下查詢會測試多邊形 POLYGON((1 1, 20 1, 10 20, 1 1)) 是否包含三個點 (0, 0)(1, 1)(10, 10) 的每一個,哪一個點分別位於多邊形的外部、界線上以及內部。

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_CONTAINS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
              ST_GEOGPOINT(i, i)) AS `contains`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+----------+
| p            | contains |
+--------------+----------+
| POINT(0 0)   | false    |
| POINT(1 1)   | false    |
| POINT(10 10) | true     |
+--------------+----------+

ST_COVEREDBY

ST_COVEREDBY(geography_1, geography_2)

說明

如果 geography_1geography_2 為空白,則會傳回 FALSE。如果沒有 geography_1 的點位於 geography_2 的外部,則會傳回 TRUE

在兩個 GEOGRAPHY ab 的情況下,ST_COVEREDBY(a, b) 會傳回與 ST_COVERS(b, a) 相同的結果。請注意,引數的順序是相反的。

傳回類型

BOOL

ST_COVERS

ST_COVERS(geography_1, geography_2)

說明

如果 geography_1geography_2 為空白,則會傳回 FALSE。如果沒有 geography_2 的點位於 geography_1 的外部,則會傳回 TRUE

傳回類型

BOOL

範例

以下查詢會測試多邊形 POLYGON((1 1, 20 1, 10 20, 1 1)) 是否包含三個點 (0, 0)(1, 1)(10, 10) 的每一個,哪一個點分別位於多邊形的外部、邊界上以及內部。

SELECT
  ST_GEOGPOINT(i, i) AS p,
  ST_COVERS(ST_GEOGFROMTEXT('POLYGON((1 1, 20 1, 10 20, 1 1))'),
            ST_GEOGPOINT(i, i)) AS `covers`
FROM UNNEST([0, 1, 10]) AS i;

+--------------+--------+
| p            | covers |
+--------------+--------+
| POINT(0 0)   | false  |
| POINT(1 1)   | true   |
| POINT(10 10) | true   |
+--------------+--------+

ST_DISJOINT

ST_DISJOINT(geography_1, geography_2)

說明

如果 geography_1geography_2 的交集為空,也就是說,geography_1 中沒有點也會出現在 geography_2 中,則會傳回 TRUE

ST_DISJOINTST_INTERSECTS 的邏輯否定。

傳回類型

GEOGRAPHY

ST_DWITHIN

ST_DWITHIN(geography_1, geography_2), distance)
ST_DWITHIN(geography_1, geography_2, distance, use_spheroid)

說明

如果 geography_1 中的至少一個點與 geography_2 中的一個點間距離小於或等於 distance 引數提供的距離,則會傳回 TRUE;否則,會傳回 FALSE。如果任一輸入 GEOGRAPHY 為空,ST_DWithin 會傳回 FALSE。在地球表面上,提供的 distance 以公尺為單位。

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

BOOL

ST_EQUALS

ST_EQUALS(geography_1, geography_2)

說明

如果 geography_1geography_2 表示相同的 GEOGRAPHY 值,則會傳回 TRUE。更準確地說,這表示下列其中一個條件成立:

  • ST_COVERS(geography_1, geography_2) = TRUEST_COVERS(geography_2, geography_1) = TRUE
  • geography_1geography_2 都為空白。

因此,即使點或頂點的順序不同,只要這些點仍表示相同的幾何結構,則兩個 GEOGRAPHY 也可能相等。

限制

ST_EQUALS 不保證是遞移性函式。

傳回類型

BOOL

ST_INTERSECTS

ST_INTERSECTS(geography_1, geography_2)

說明

如果 geography_1geography_2 的點集交集不是空的,則會傳回 TRUE。因此,如果至少有一個點出現在兩個輸入 GEOGRAPHY 中,這個函式會傳回 TRUE

如果 ST_INTERSECTS 傳回 TRUE,即表示 ST_DISJOINT 會傳回 FALSE

傳回類型

BOOL

ST_INTERSECTSBOX

ST_INTERSECTSBOX(geography, lng1, lat1, lng2, lat2)

說明

如果 geography 使矩形在 [lng1, lng2][lat1, lat2] 之間相交,則會傳回 TRUE。矩形的邊會遵循經度與緯度的常數線。lng1lng2 會指定圍繞矩形的最小與最大經線,而 lat1lat2 會指定圍繞矩形的最小與最大常數緯線。

請以度為單位指定所有經度與緯度的引數。

限制

輸入引數有以下限制:

  • 緯度應在 [-90, 90] 度數範圍內。
  • 經度應在 [-180, 180] 度數範圍內。

傳回類型

BOOL

ST_TOUCHES

ST_TOUCHES(geography_1, geography_2)

說明

如果滿足下列兩個條件,則會傳回 TRUE

  1. geography_1geography_2 相交。
  2. geography_1 的內部與 geography_2 的內部不相交。

傳回類型

BOOL

ST_WITHIN

ST_WITHIN(geography_1, geography_2)

說明

如果沒有 geography_1 的點位於 geography_2 的外部,且 geography_1geography_2 的內部相交,則會傳回 TRUE

在兩個地理位置 ab 之下,ST_WITHIN(a, b) 會傳回與 ST_CONTAINS(b, a) 相同的結果。請注意,引數的順序是相反的。

傳回類型

BOOL

ST_ISEMPTY

ST_ISEMPTY(geography_expression)

說明

如果 GEOGRAPHY 為空白,也就是說 GEOGRAPHY 並不包含任何點、線或多邊形,則會傳回 TRUE

附註:BigQuery 空 GEOGRAPHY 與特定幾何形狀無關聯。例如,運算式 ST_GEOGFROMTEXT('POINT EMPTY')ST_GEOGFROMTEXT('GEOMETRYCOLLECTION EMPTY') 的結果是相同的。

傳回類型

BOOL

ST_ISCOLLECTION

ST_ISCOLLECTION(geography_expression)

說明

如果點、linestrings 與多邊形的總數大於一,則會傳回 TRUE

GEOGRAPHY 並不是集合。

傳回類型

BOOL

ST_DIMENSION

ST_DIMENSION(geography_expression)

說明

傳回輸入 GEOGRAPHY 中最高維度元素的維度。

每個可能元素的維度如下:

  • 點的維度為 0
  • linestring 的維度為 1
  • 多邊形的維度為 2

如果輸入 GEOGRAPHY 為空,ST_DIMENSION 會傳回 -1

傳回類型

INT64

ST_NUMPOINTS

ST_NUMPOINTS(geography_expression)

說明

傳回輸入 GEOGRAPHY 中的頂點數。這包括點數、linestring 頂點數與多邊形頂點數。

附註:多邊形環的第一個與最後一個頂點會計為不同的頂點。

傳回類型

INT64

ST_AREA

ST_AREA(geography_expression)
ST_AREA(geography_expression, use_spheroid)

說明

傳回輸入 GEOGRAPHY 中多邊形所涵蓋的面積,以平方公尺為單位。

如果 geography_expression 是點或線,則會傳回零。如果 geography_expression 是集合,則會傳回集合中的多邊形面積;如果集合不包含多邊形,則會傳回零。

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

FLOAT64

ST_DISTANCE

ST_DISTANCE(geography_1, geography_2)
ST_DISTANCE(geography_1, geography_2, use_spheroid)

說明

傳回兩個非空 GEOGRAPHY 之間的最短距離,以公尺為單位。

如果任一輸入 GEOGRAPHY 為空,ST_DISTANCE 會傳回 NULL

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

FLOAT64

ST_LENGTH

ST_LENGTH(geography_expression)
ST_LENGTH(geography_expression, use_spheroid)

說明

傳回輸入 GEOGRAPHY 中線條的總長度,以公尺為單位。

如果 geography_expression 是點或多邊形,則會傳回零。如果 geography_expression 是集合,則會傳回集合中的線條長度;如果集合不包含線條,則會傳回零。

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

FLOAT64

ST_MAXDISTANCE

ST_MAXDISTANCE(geography_1, geography_2)
ST_MAXDISTANCE(geography_1, geography_2, use_spheroid)

傳回兩個非空 GEOGRAPHY 之間的最長距離;也就是兩個頂點之間的距離,其中第一個頂點位於第一個 GEOGRAPHY 中,第二個頂點位於第二個 GEOGRAPHY 中。如果 geography_1geography_2 是相同的 GEOGRAPHY,此函式會傳回該 GEOGRAPHY 中兩個相距最遠頂點之間的距離。

如果任一輸入 GEOGRAPHY 為空,ST_MAXDISTANCE 會傳回 NULL

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

FLOAT64

ST_PERIMETER

ST_PERIMETER(geography_expression)
ST_PERIMETER(geography_expression, use_spheroid)

說明

傳回輸入 GEOGRAPHY 中多邊形邊界的長度,以公尺為單位。

如果 geography_expression 是點或線,則會傳回零。如果 geography_expression 是集合,則會傳回集合中的多邊形周長;如果集合不包含多邊形,則會傳回零。

選用的 use_spheroid 參數可決定此函式如何測量距離。如果 use_spheroidFALSE,函式會測量完美球體表面上的距離。

use_spheroid 參數目前僅支援 FALSE 值。use_spheroid 的預設值為 FALSE

傳回類型

FLOAT64

ST_UNION_AGG

ST_UNION_AGG(geography)

說明

傳回代表所有輸入 GEOGRAPHY 點集聯集的 GEOGRAPHY

ST_UNION_AGG 忽略 NULL 的輸入 GEOGRAPHY 值。

如要進一步瞭解 ST_UNION_AGG 的非匯總版本,請參閱 ST_UNION 一節。

傳回類型

GEOGRAPHY

ST_CENTROID_AGG

ST_CENTROID_AGG(geography)

說明

將輸入 GEOGRAPHY 集的質心計算為單一點 GEOGRAPHY

輸入 GEOGRAPHY 集中的「質心」是各個個別 GEOGRAPHY 質心的加權平均值。只有在輸入中具備最高維度的 GEOGRAPHY 才能成為完整集的質心。例如,如果輸入中包含具有線條的 GEOGRAPHY 以及只有點的 GEOGRAPHYST_CENTROID_AGG 會傳回具有線條的 GEOGRAPHY 的加權平均值,因為只有這些 GEOGRAPHY 具有最大維度。在這個例子中,系統計算匯總質心時,ST_CENTROID_AGG 會忽略只有點的 GEOGRAPHY

ST_CENTROID_AGG 會忽略 NULL 的輸入 GEOGRAPHY 值。

如要進一步瞭解 ST_CENTROID_AGG 的非匯總版本和個別 GEOGRAPHY 值的質心定義,請參閱 ST_CENTROID 一節。

傳回類型

GEOGRAPHY

範例

以下查詢會計算一組 GEOGRAPHY 值的 aggregate 質心。第一個查詢的輸入中只包含點,因此每個值都可以成為 aggregate 質心。另外也請注意,ST_CENTROID_AGG「並不」等於在 ST_UNION_AGG 的結果上呼叫 ST_CENTROID;聯集會去除重複結果,這與 ST_CENTROID_AGG 不同。第二個查詢的輸入含有混合的維度,而只有在集中具有最高維度的值 (也就是線條) 會影響到匯總質心。

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg,
ST_CENTROID(ST_UNION_AGG(points)) AS centroid_of_union
FROM UNNEST([ST_GEOGPOINT(1, 5),
             ST_GEOGPOINT(1, 2),
             ST_GEOGPOINT(1, -1),
             ST_GEOGPOINT(1, -1)]) points;

+---------------------------+-------------------+
| st_centroid_agg           | centroid_of_union |
+---------------------------+-------------------+
| POINT(1 1.24961422620969) | POINT(1 2)        |
+---------------------------+-------------------+

SELECT ST_CENTROID_AGG(points) AS st_centroid_agg
FROM UNNEST([ST_GEOGPOINT(50, 26),
             ST_GEOGPOINT(34, 33.3),
             ST_GEOGFROMTEXT('LINESTRING(0 -1, 0 1)')
             ST_GEOGFROMTEXT('LINESTRING(0 1, 0 3)')]) points;

+-----------------+
| st_centroid_agg |
+-----------------+
| POINT(0 1)      |
+-----------------+

https://en.wikipedia.org/wiki/Geohash "GeoHash"

安全性函式

BigQuery 支援下列 security 函式。

SESSION_USER

SESSION_USER()

說明

傳回執行查詢的使用者的電子郵件地址。

傳回資料類型

STRING

範例

SELECT SESSION_USER() as user;

+----------------------+
| user                 |
+----------------------+
| jdoe@example.com     |
+----------------------+

UUID 函式

BigQuery 支援下列通用唯一識別碼 (UUID) 函式。

GENERATE_UUID

GENERATE_UUID()

說明

將隨機通用唯一識別碼 (UUID) 作為 STRING 傳回。傳回的 STRING 包含 32 個十六進位數字,以連字號分為五組,格式如:8-4-4-4-12。十六進位數字依照 RFC 4122 第 4.4 節定義,代表 122 個隨機位元和 6 個固定位元。傳回的 STRING 為小寫。

傳回資料類型

STRING

範例

以下查詢會產生隨機 UUID。

SELECT GENERATE_UUID() AS uuid;

以上查詢會產生類似以下的結果:

+--------------------------------------+
| uuid                                 |
+--------------------------------------+
| 4192bff0-e1e0-43ce-a4db-912808c32493 |
+--------------------------------------+

Net 函式

NET.IP_FROM_STRING

NET.IP_FROM_STRING(addr_str)

說明

將 IPv4 或 IPv6 位址從文字 (STRING) 格式轉換為網路位元組順序的二進位 (BYTES) 格式。

這個函式支援 addr_str 的下列格式:

  • IPv4:四組數值表示法格式。例如,10.1.2.3
  • IPv6:冒號分隔格式。例如,1234:5678:90ab:cdef:1234:5678:90ab:cdef。如需更多範例,請參閱 IP 6 版定址架構

這個函式不支援 CIDR 標記法,例如 10.1.2.3/32

如果這個函式收到 NULL 輸入,它會傳回 NULL。如果輸入被視為無效,就會發生 OUT_OF_RANGE 錯誤。

傳回資料類型

BYTES

範例

SELECT
  addr_str, FORMAT("%T", NET.IP_FROM_STRING(addr_str)) AS ip_from_string
FROM UNNEST([
  '48.49.50.51',
  '::1',
  '3031:3233:3435:3637:3839:4041:4243:4445',
  '::ffff:192.0.2.128'
]) AS addr_str;
addr_str ip_from_string
48.49.50.51 b"0123"
::1 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"
3031:3233:3435:3637:3839:4041:4243:4445 b"0123456789@ABCDE"
::ffff:192.0.2.128 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"

NET.SAFE_IP_FROM_STRING

NET.SAFE_IP_FROM_STRING(addr_str)

說明

NET.IP_FROM_STRING 類似,但如果輸入無效,會傳回 NULL,而非擲回錯誤。

傳回資料類型

BYTES

範例

SELECT
  addr_str,
  FORMAT("%T", NET.SAFE_IP_FROM_STRING(addr_str)) AS safe_ip_from_string
FROM UNNEST([
  '48.49.50.51',
  '::1',
  '3031:3233:3435:3637:3839:4041:4243:4445',
  '::ffff:192.0.2.128',
  '48.49.50.51/32',
  '48.49.50',
  '::wxyz'
]) AS addr_str;
addr_str safe_ip_from_string
48.49.50.51 b"0123"
::1 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01"
3031:3233:3435:3637:3839:4041:4243:4445 b"0123456789@ABCDE"
::ffff:192.0.2.128 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"
48.49.50.51/32 NULL
48.49.50 NULL
::wxyz NULL

NET.IP_TO_STRING

NET.IP_TO_STRING(addr_bin)

說明 將 IPv4 或 IPv6 位址從網路位元組順序的二進位 (BYTES) 格式轉換為文字 (STRING) 格式。

如果輸入是 4 個位元組,這個函式會以 STRING 格式傳回 IPv4 位址。如果輸入是 16 個位元組,它會以 STRING 格式傳回 IPv6 位址。

如果這個函式收到 NULL 輸入,它會傳回 NULL。如果輸入的長度不是 4 或 16,會發生 OUT_OF_RANGE 錯誤。

傳回資料類型

STRING

範例

SELECT FORMAT("%T", x) AS addr_bin, NET.IP_TO_STRING(x) AS ip_to_string
FROM UNNEST([
  b"0123",
  b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01",
  b"0123456789@ABCDE",
  b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"
]) AS x;
addr_bin ip_to_string
b"0123" 48.49.50.51
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01" ::1
b"0123456789@ABCDE" 3031:3233:3435:3637:3839:4041:4243:4445
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80" ::ffff:192.0.2.128

NET.IP_NET_MASK

NET.IP_NET_MASK(num_output_bytes, prefix_length)

說明

傳回網路遮罩:長度等於 num_output_bytes 的位元組順序,其中第一個 prefix_length 位元會設定為 1,其他位元會設定為 0。num_output_bytesprefix_length 是 INT64。 如果 num_output_bytes 不是 4 (針對 IPv4) 或 16 (針對 IPv6),這個函式會擲回錯誤。如果 prefix_length 是負數或大於 8 * num_output_bytes,它也會擲回錯誤。

傳回資料類型

BYTES

範例

SELECT x, y, FORMAT("%T", NET.IP_NET_MASK(x, y)) AS ip_net_mask
FROM UNNEST([
  STRUCT(4 as x, 0 as y),
  (4, 20),
  (4, 32),
  (16, 0),
  (16, 1),
  (16, 128)
]);
x y ip_net_mask
4 0 b"\x00\x00\x00\x00"
4 20 b"\xff\xff\xf0\x00"
4 32 b"\xff\xff\xff\xff"
16 0 b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
16 1 b"\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
16 128 b"\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff"

NET.IP_TRUNC

NET.IP_TRUNC(addr_bin, prefix_length)

說明 可接受的值為 addr_bin,這是按網路位元組順序並採二進位 (BYTES) 格式的 IPv4 或 IPv6 位址,並會傳回相同格式的子網路位址。結果長度與 addr_bin 相同,其中第一個 prefix_length 位元等於 addr_bin 中的位元,其餘位元為 0。

如果 LENGTH(addr_bin) 不是 4 或 16,或如果 prefix_len 是負數或大於 LENGTH(addr_bin) * 8,這個函式會擲回錯誤。

傳回資料類型

BYTES

範例

SELECT
  FORMAT("%T", x) as addr_bin, prefix_length,
  FORMAT("%T", NET.IP_TRUNC(x, prefix_length)) AS ip_trunc
FROM UNNEST([
  STRUCT(b"\xAA\xBB\xCC\xDD" as x, 0 as prefix_length),
  (b"\xAA\xBB\xCC\xDD", 11), (b"\xAA\xBB\xCC\xDD", 12),
  (b"\xAA\xBB\xCC\xDD", 24), (b"\xAA\xBB\xCC\xDD", 32),
  (b'0123456789@ABCDE', 80)
]);
addr_bin prefix_length ip_trunc
b"\xaa\xbb\xcc\xdd" 0 b"\x00\x00\x00\x00"
b"\xaa\xbb\xcc\xdd" 11 b"\xaa\xa0\x00\x00"
b"\xaa\xbb\xcc\xdd" 12 b"\xaa\xb0\x00\x00"
b"\xaa\xbb\xcc\xdd" 24 b"\xaa\xbb\xcc\x00"
b"\xaa\xbb\xcc\xdd" 32 b"\xaa\xbb\xcc\xdd"
b"0123456789@ABCDE" 80 b"0123456789\x00\x00\x00\x00\x00\x00"

NET.IPV4_FROM_INT64

NET.IPV4_FROM_INT64(integer_value)

說明

將 IPv4 位址從整數格式轉換為網路位元組順序的二進位 (BYTES) 格式。在整數輸入中,IP 位址的最低有效位元會儲存在整數的最低有效位元中,無論主機或用戶端架構為何。例如,1 表示 0.0.0.10x1FF 表示 0.0.1.255

這個函式會檢查所有最高有效 32 位元是否為 0,或所有最高有效 33 位元是否為 1 (從 32 位元整數中擴展正負號)。 換句話說,輸入應在 [-0x80000000, 0xFFFFFFFF] 範圍中;否則,這個函式會擲回錯誤。

這個函式不支援 IPv6。

傳回資料類型

BYTES

範例

SELECT x, x_hex, FORMAT("%T", NET.IPV4_FROM_INT64(x)) AS ipv4_from_int64
FROM (
  SELECT CAST(x_hex AS INT64) x, x_hex
  FROM UNNEST(["0x0", "0xABCDEF", "0xFFFFFFFF", "-0x1", "-0x2"]) AS x_hex
);
x x_hex ipv4_from_int64
0 0x0 b"\x00\x00\x00\x00"
11259375 0xABCDEF b"\x00\xab\xcd\xef"
4294967295 0xFFFFFFFF b"\xff\xff\xff\xff"
-1 -0x1 b"\xff\xff\xff\xff"
-2 -0x2 b"\xff\xff\xff\xfe"

NET.IPV4_TO_INT64

NET.IPV4_TO_INT64(addr_bin)

說明

將 IPv4 位址從網路位元組順序的二進位 (BYTES) 格式轉換為整數格式。在整數輸出中,IP 位址的最低有效位元會儲存在整數的最低有效位元中,無論主機或用戶端架構為何。例如,1 表示 0.0.0.10x1FF 表示 0.0.1.255。輸出在 [0, 0xFFFFFFFF] 範圍中。

如果輸出長度不是 4,這個函式會擲回錯誤。

這個函式不支援 IPv6。

傳回資料類型

INT64

範例

SELECT
  FORMAT("%T", x) AS addr_bin,
  FORMAT("0x%X", NET.IPV4_TO_INT64(x)) AS ipv4_to_int64
FROM
UNNEST([b"\x00\x00\x00\x00", b"\x00\xab\xcd\xef", b"\xff\xff\xff\xff"]) AS x;
addr_bin ipv4_to_int64
b"\x00\x00\x00\x00" 0x0
b"\x00\xab\xcd\xef" 0xABCDEF
b"\xff\xff\xff\xff" 0xFFFFFFFF

NET.HOST

NET.HOST(url)

說明

取用 STRING 格式的網址並傳回 STRING 格式的主機。若要獲得最佳效果,網址值應符合 RFC 3986 定義的格式。如果網址值不符合 RFC 3986 格式,這個函式會盡力剖析輸入並傳回相關結果。如果函式無法剖析輸入,它會傳回 NULL。

注意:此函式不會執行任何正規化。

傳回資料類型

STRING

範例

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
輸入 說明 主機 尾碼 網域
"" 輸入無效 NULL NULL NULL
"http://abc.xyz" 標準網址 "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" 含相關通訊協定、連接埠、路徑與查詢,但不含公開尾碼的標準網址 "a.b" NULL NULL
"https://[::1]:80" 含 IPv6 主機的標準網址 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" 含國際化網域名稱的標準網址 URL "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " 含空格、大寫字母,不含通訊協定的非標準網址 "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" 網址以外的 URI--不支援 "mailto" NULL NULL

NET.PUBLIC_SUFFIX

NET.PUBLIC_SUFFIX(url)

說明

可接受 STRING 格式的網址,並會傳回 STRING 格式的公開尾碼 (例如 comorgnet)。公開尾碼是在 publicsuffix.org 註冊的 ICANN 網域。若要獲得最佳效果,網址值應符合 RFC 3986 定義的格式。如果網址值不符合 RFC 3986 格式,這個函式會盡力剖析輸入並傳回相關結果。

如果出現以下任何一個情況,這個函式就會傳回 NULL:

  • 它無法從輸入剖析主機;
  • 剖析的主機中間 (而非開頭或結尾) 包含相鄰的點;
  • 剖析的主機不包含任何公開尾碼。

查詢公開尾碼之前,這個函式會將大寫英文字母轉換成小寫並用 Punycode 編碼所有非 ASCII 字元,來暫時正規化主機。 然後函式會將公開尾碼傳回為原始主機的一部分,而非正規化主機的一部分。

注意事項:此函式不會執行 Unicode 正規化

注意事項:位於 publicsuffix.org 的公開尾碼資料也包含私人網域。這個函式會忽略私人網域。

注意:公開尾碼資料可能會隨著時間而變更。因此,產生 NULL 結果的輸入現在可能會在未來產生非 NULL 值。

傳回資料類型

STRING

範例

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
輸入 說明 主機 尾碼 網域
"" 輸入無效 NULL NULL NULL
"http://abc.xyz" 標準網址 "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" 含相關通訊協定、連接埠、路徑與查詢,但不含公開尾碼的標準網址 "a.b" NULL NULL
"https://[::1]:80" 含 IPv6 主機的標準網址 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" 含國際化網域名稱的標準網址 URL "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " 含空格、大寫字母,不含通訊協定的非標準網址 "www.Example.Co.UK" "Co.UK" "Example.Co.UK
"mailto:?to=&subject=&body=" 網址以外的 URI--不支援 "mailto" NULL NULL

NET.REG_DOMAIN

NET.REG_DOMAIN(url)

說明

可接受 STRING 格式的網址,並會傳回 STRING 格式的已註冊或可註冊網域 (公開尾碼加前置標籤)。為取得最佳結果,網址值應符合 RFC 3986 定義的格式。如果網址值不符合 RFC 3986 格式,這個函式會盡力剖析輸入並傳回相關結果。

如果出現以下任何一個情況,這個函式就會傳回 NULL:

  • 它無法從輸入剖析主機;
  • 剖析的主機中間 (而非開頭或結尾) 包含相鄰的點;
  • 剖析的主機不包含任何公開尾碼;
  • 剖析的主機只包含公開尾碼,不含任何前置標籤。

查詢公開尾碼之前,這個函式會將大寫英文字母轉換成小寫並用 Punycode 編碼所有非 ASCII 字元,來暫時正規化主機。 然後函式會將已註冊或可註冊的網域傳回為原始主機的一部分,而非正規化主機的一部分。

注意事項:此函式不會執行 Unicode 正規化

注意事項:位於 publicsuffix.org 的公開尾碼資料也包含私人網域。這個函式不會將私人網域當成公開尾碼處理。例如,如果「us.com」是公開尾碼資料中的私人網域,NET.REG_DOMAIN(「foo.us.com」) 會傳回「us.com」(公開尾碼「com」加上前置標籤「us」),而非「foo.us.com」(私人網域「us.com」加上前置標籤「foo」)。

附註:公開尾碼資料可能會隨著時間而變更。因此,產生 NULL 結果的輸入現在可能會在未來產生非 NULL 值。

傳回資料類型

STRING

範例

SELECT
  FORMAT("%T", input) AS input,
  description,
  FORMAT("%T", NET.HOST(input)) AS host,
  FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
  FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
  SELECT "" AS input, "invalid input" AS description
  UNION ALL SELECT "http://abc.xyz", "standard URL"
  UNION ALL SELECT "//user:password@a.b:80/path?query",
                   "standard URL with relative scheme, port, path and query, but no public suffix"
  UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
  UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
  UNION ALL SELECT "    www.Example.Co.UK    ",
                   "non-standard URL with spaces, upper case letters, and without scheme"
  UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
輸入 說明 主機 尾碼 網域
"" 輸入無效 NULL NULL NULL
"http://abc.xyz" 標準網址 "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" 含相關通訊協定、連接埠、路徑與查詢,但不含公開尾碼的標準網址 "a.b" NULL NULL
"https://[::1]:80" 含 IPv6 主機的標準網址 "[::1]" NULL NULL
"http://例子.卷筒纸.中国" 含國際化網域名稱的標準網址 URL "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Example.Co.UK    " 含空格、大寫字母,不含通訊協定的非標準網址 "www.Example.Co.UK" "Co.UK" "Example.Co.UK"
"mailto:?to=&subject=&body=" 網址以外的 URI--不支援 "mailto" NULL NULL

運算子

運算子由特殊字元或關鍵字表示;它們不使用函式呼叫語法。運算子可操作任何數目的資料輸入 (也稱為運算元) 並傳回結果。

常見慣例:

  • 除非另外指定,當其中一個運算元是 NULL 時,所有運算子都會傳回 NULL
  • 如果計算結果溢位,所有運算子都將擲回錯誤。
  • 對於所有浮點運算,如果其中一個運算元是 +/-infNaN,就只可能傳回 +/-infNaN。在其他情況下,會傳回錯誤。

下表從最高優先順序到最低優先順序 (也就是將在陳述式內接受評估的順序) 列出所有 BigQuery 運算子。

優先順序 運算子 輸入資料類型 名稱 運算子引數數目
1 . STRUCT
成員欄位存取運算子 二進位
  [ ] ARRAY 陣列位置。必須與 OFFSET 或 ORDINAL 搭配使用—請參閱 ARRAY 函式 二進位
2 - 所有數值類型 一元減 一元
  ~ 整數或 BYTES 位元 not 一元
3 * 所有數值類型 二進位
  / 所有數值類型 二進位
4 + 所有數值類型 二進位
  - 所有數值類型 二進位
5 << 整數或 BYTES 向左移位 二進位
  >> 整數或 BYTES 向右移位 二進位
6 & 整數或 BYTES 位元 and 二進位
7 ^ 整數或 BYTES 位元 xor 二進位
8 | 整數或 BYTES 位元 or 二進位
9 (比較運算子) = 任何可比較類型。完整清單請參閱資料類型 等與 二進位
  < 任何可比較類型。完整清單請參閱資料類型 小於 二進位
  > 任何可比較類型。完整清單請參閱資料類型 大於 二進位
  <= 任何可比較類型。完整清單請參閱資料類型 小於或等於 二進位
  >= 任何可比較類型。完整清單請參閱資料類型 大於或等於 二進位
  !=, <> 任何可比較類型。完整清單請參閱資料類型 不等於 二進位
  [NOT] LIKE STRING 與位元組 值與指定模式 [不] 相符 二進位
  [NOT] BETWEEN 任何可比較類型。清單請參閱「資料類型」。 值 [不] 在指定範圍之內 二進位
  [NOT] IN 任何可比較類型。清單請參閱資料類型。 值 [不] 在指定值組中 二進位
  IS [NOT] NULL 全部 值 [不是] NULL 一元
  IS [NOT] TRUE BOOL 值 [不是] TRUE。 一元
  IS [NOT] FALSE BOOL 值 [不是] FALSE。 一元
10 NOT BOOL 邏輯 NOT 一元
11 AND BOOL 邏輯 AND 二進位
12 OR BOOL 邏輯 OR 二進位

優先順序相同的運算子會保持關聯性。這表示這些運算子會從左開始向右分組在一起。例如,以下運算式:

x AND y AND z

會被解讀為

( ( x AND y ) AND z )

以下運算式:

x * y / z

會被解讀為:

( ( x * y ) / z )

所有比較運算子都具有相同的優先順序,但比較運算子不會相互關聯。為避免混淆,請務必使用括號。例如:

(x < y) IS FALSE

元素存取運算子

運算子 語法 輸入資料類型 結果資料類型 說明
. expression.fieldname1... STRUCT
類型 T 儲存在 fieldname1 中 點運算子。可用於存取巢狀欄位,例如 expression.fieldname1.fieldname2...
[ ] array_expression [position_keyword (int_expression ) ] 請參閱 ARRAY 函式。 類型 T 儲存在 ARRAY 中 position_keyword 為 OFFSET 或 ORDINAL。如需瞭解使用這個運算子的兩個函式,請參閱 ARRAY 函式

算術運算子

所有算數運算子都接受數字類型 T 的輸入,且除非在以下說明中另外指定,否則結果類型都是類型 T。

名稱 語法
X + Y
X - Y
X * Y
X / Y
一元減 - X

注意:除以零運算會傳回錯誤。若要傳回其他結果,請考慮 IEEE_DIVIDE 或 SAFE_DIVIDE 函式。

加與減的結果類型:

 INT64NUMERICFLOAT64
INT64INT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

減的結果類型:

 INT64NUMERICFLOAT64
INT64INT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

除的結果類型:

 INT64NUMERICFLOAT64
INT64FLOAT64NUMERICFLOAT64
NUMERICNUMERICNUMERICFLOAT64
FLOAT64FLOAT64FLOAT64FLOAT64

一元減的結果類型:

輸入資料類型 結果資料類型
INT64 INT64
NUMERIC NUMERIC
FLOAT64 FLOAT64

位元運算子

所有位元運算子都會傳回與第一個運算元相同的類型與長度。

名稱 語法 輸入資料類型 說明
位元 not ~ X 整數或 BYTES 對每個位元執行邏輯非,形成位元之指定二進位值的補數。
位元 or X | Y X:整數或 BYTES
Y:類型與 X 相同
取用相等長度的兩個位元模式並對對應位元的每個配對執行邏輯包含 OR 運算。 如果 X 與 Y 是不同長度的 BYTES,這個運算子會擲回錯誤。
位元 xor X ^ Y X:整數或 BYTES
Y:類型與 X 相同
取用相等長度的兩個位元模式並對對應位元的每個配對執行邏輯排除 OR 運算。如果 X 與 Y 是不同長度的 BYTES,這個運算子會擲回錯誤。
位元 and X & Y X:整數或 BYTES
Y:類型與 X 相同
取用相等長度的兩個位元模式並對對應位元的每個配對執行邏輯 AND 運算。如果 X 與 Y 是不同長度的 BYTES,這個運算子會擲回錯誤。
向左移位 X << Y X:整數或 BYTES
Y:INT64
向左移位第一個運算元 X。如果第二個運算元 Y 大於或等於第一個運算元 X 的位元長度,這個運算子會傳回 0 或 b'\x00' 的位元組順序 (例如,如果 X 的類型是 INT64 就會傳回 64)。 如果 Y 是負數,這個運算子會擲回錯誤。
向右移位 X >> Y X:整數或 BYTES
Y:INT64
向右移位第一個運算元 X。這個運算子不會對帶正負號的類型執行正負號位元擴充 (也就是說,它會在空缺位元的左側填入 0)。如果第二個運算元 Y 大於或等於第一個運算元 X 的位元長度,這個運算子會傳回 0 或 b'\x00' 的位元組順序 (例如,如果 X 的類型是 INT64 就會傳回 64)。 如果 Y 是負數,這個運算子會擲回錯誤。

邏輯運算子

所有邏輯運算子都只允許 BOOL 輸入。

名稱 語法 說明
邏輯 NOT NOT X 如果輸入為 TRUE 就傳回 FALSE。如果輸入為 FALSE 就傳回 TRUE。其他情況下傳回 NULL
邏輯 AND X AND Y 如果至少一個輸入為 FALSE 就傳回 FALSE。如果 X 與 Y 都是 TRUE 就傳回 TRUE。其他情況下傳回 NULL
邏輯 OR X OR Y 如果 X 與 Y 都是 FALSE 就傳回 FALSE。如果至少一個輸入為 TRUE 就傳回 TRUE。其他情況下傳回 NULL

比較運算子

比較一律傳回 BOOL。比較通常需要兩個類型相同的運算元。如果運算元屬於不同類型,且 BigQuery 可以將那些類型的值轉換成一般類型而不會減損精確度,BigQuery 通常會將它們強制轉換成比較常用的類型;BigQuery 通常會將常值強制轉成非常值類型 (如果有的話)。請參閱資料類型,瞭解可比較的資料類型定義。

STRUCT 只支援 4 個比較運算子:等於 (=)、不等於 (!= 與 <>) 及 IN。

以下規則只在比較這些資料類型時適用:

  • FLOAT64:所有帶有 NaN 的比較均會傳回 FALSE,但 !=<> 除外,因為會傳回 TRUE。
  • BOOL:FALSE 小於 TRUE。
  • STRING:字串會逐一碼點進行比較,這表示如果正式相等的字串已先進行正規化,它們只保證會比較為相等。
  • NULL:以下是適用的慣例:帶有 NULL 輸入的任何運算都會傳回 NULL
名稱 語法 說明
小於 X < Y 如果 X 小於 Y 就傳回 TRUE。
小於或等於 X <= Y 如果 X 小於或等於 Y 就傳回 TRUE。
大於 X > Y 如果 X 大於 Y 就傳回 TRUE。
大於或等於 X >= Y 如果 X 大於或等於 Y 就傳回 TRUE。
等於 X = Y 如果 X 等於 Y 就傳回 TRUE。
不等於 X != Y
X <> Y
如果 X 不等於 Y 就傳回 TRUE。
介於 X [NOT] BETWEEN Y AND Z 如果 X [不] 在指定範圍之內就傳回 TRUE。「X BETWEEN Y AND Z」的結果相當於「Y <= X AND X <= Z」但  X 只在前者中評估一次。
LIKE X [NOT] LIKE Y 檢查第一個運算元 X 中的 STRING 是否與第二個運算元 Y 指定的模式相符。運算式可以包含這些字元:
  • 百分比符號「%」會比對任何數目的字元或位元組
  • 底線「_」會比對單一字元或位元組
  • 您可以使用兩條反斜線逸出「\」、「_」或「%」。例如, "\\%"。如果您使用原始字串,就只需要一條反斜線。例如,r"\%".
IN 多個語法 - 請見以下說明 如果右運算元為空白,就傳回 FALSE。如果左運算元為 NULL 就傳回 NULL。如果右運算元包含 NULL,就傳回 TRUE 或 NULL,永遠不傳回 FALSE。IN 任一側的引數是一般運算式。任何一個運算元都不需要是常值,但最常見的情況是在右側使用常值。X 只評估一次。

測試資料類型為 STRUCT 之值的相等性時,可能一或多個欄位為 NULL。在此類情況下:

  • 如果非 NULL 欄位值相等,比較會傳回 NULL。
  • 如果任何非 NULL 欄位值不相等,比較會傳回 false。

下表示範當 STRUCT 資料類型的欄位具有 NULL 值時如何比較這些資料類型。

Struct1 Struct2 Struct1 = Struct2
STRUCT(1, NULL) STRUCT(1, NULL) NULL
STRUCT(1, NULL) STRUCT(2, NULL) FALSE
STRUCT(1,2) STRUCT(1, NULL)

NULL

IN 運算子

IN 運算子支援下列語法:

x [NOT] IN (y, z, ... ) # Requires at least one element
x [NOT] IN (<subquery>)
x [NOT] IN UNNEST(<array expression>) # analysis error if the expression
                                      # does not return an ARRAY type.

IN 運算子任一側的引數為一般運算式。經常會在右側運算式使用常值;但是,這並非必要。

下列項目的語意:

x IN (y, z, ...)

定義為等於:

(x = y) OR (x = z) OR ...

子查詢與陣列表單的定義方式類似。

x NOT IN ...

相當於:

NOT(x IN ...)

UNNEST 表單會像 FROM 子句中的 UNNEST 一樣處理陣列掃描:

x [NOT] IN UNNEST(<array expression>)

這個表單通常與 ARRAY 參數搭配使用。例如:

x IN UNNEST(@array_parameter)

注意事項:NULL ARRAY 的處理方式與空白 ARRAY 相同。

有關如何使用這個語法的詳細資訊,請參閱陣列主題。

使用 IN 運算子時,適用下列語意:

  • IN 帶有右側空白運算式一律為 FALSE
  • IN 帶有左側 NULL 運算式與右側非空白運算式一律為 NULL
  • IN 在 IN 清單中帶有 NULL 只能傳回 TRUE 或 NULL,永遠不會傳回 FALSE
  • NULL IN (NULL) 會傳回 NULL
  • IN UNNEST(<NULL array>) 會傳回 FALSE (非 NULL)
  • IN 清單中帶有 NULLNOT IN 只能傳回 FALSE 或 NULL,永遠不會傳回 TRUE

使用結構建構函式語法,IN 可與多部分金鑰搭配使用。例如:

(Key1, Key2) IN ( (12,34), (56,78) )
(Key1, Key2) IN ( SELECT (table.a, table.b) FROM table )

如需這個語法的詳細資訊,請參閱「資料類型」主題的結構類型一節。

IS 運算子

IS 運算子會針對它們測試的情況傳回 TRUE 或 FALSE。與數學函式中定義的 IS_INF 和 IS_NAN 函式不同,即使是 NULL 輸入,IS 運算子也絕不會傳回 NULL。若「不」存在,會反轉輸出 BOOL 值。

函式語法 輸入資料類型 結果資料類型 說明

X IS [NOT] NULL
不限值類型 BOOL 如果運算元 X 評估為 NULL,就會傳回 TRUE,否則會傳回 FALSE。

X IS [NOT] TRUE
BOOL BOOL 如果 BOOL 運算元評估為 TRUE,就會傳回 TRUE。否則會傳回 FALSE。

X IS [NOT] FALSE
BOOL BOOL 如果 BOOL 運算元評估為 FALSE,就會傳回 TRUE。否則會傳回 FALSE。

條件運算式

條件運算式會對運算式的評估順序加上限制。基本上,它們會從左向右進行短路評估,並只評估選擇的輸出值。相對的,對於正常函式的所有輸入都會在呼叫函式之前評估。條件運算式中的短路邏輯 (Short-circuiting) 可以用來處理錯誤或進行效能方面的調整。

語法 輸入資料類型 結果資料類型 說明

CASE expr
  WHEN value THEN result
  [WHEN ...]
  [ELSE else_result]
  END
exprvalue:不限類型 resultelse_result:輸入類型的超級類型。 expr 與每個連續 WHEN 子句的值進行比較並傳回第一個結果,其中的這個比較會傳回 true。不會評估剩餘的 WHEN 子句與 else_result。如果 expr = value 比較傳回 false 或針對所有 WHEN 子句傳回 NULL,就會傳回 else_result (如果有的話);如果沒有,則傳回 NULL,且 exprvalue 運算式必須自動強制轉換為共通的超級類型;這個運算式會比較強制轉換後的值,確認彼此是否相等。resultelse_result 運算式必須可強制轉換為共通的超級類型。

CASE
  WHEN cond1 THEN result
  [WHEN cond2...]
  [ELSE else_result]
  END
cond:BOOL resultelse_result:輸入類型的超級類型。 評估每個連續 WHEN 子句的條件 cond 並傳回條件為 true 的第一個結果;不會評估任何剩餘的 WHEN 子句與 else_result。如果所有條件都是 false 或 NULL,就會傳回 else_result (如果有的話);如果沒有,則傳回 NULLresultelse_result 運算式必須自動強制轉換為共通的超級類型。
COALESCE(expr1, ..., exprN) 不限類型 輸入類型的超級類型 傳回第一個非空值運算式的值。不會評估剩餘運算式。所有輸入運算式都必須自動強制轉換為共通的超級類型。
IF(cond, true_result, else_result) cond:BOOL true_resultelse_result:不限類型。 如果 cond 是 true,就會傳回 true_result,否則會傳回 else_result。如果 cond 是 true 就不會評估 else_result。如果 cond 是 false 或 NULL 就不會評估 true_resulttrue_resultelse_result 必須可強制轉換為共通的超級類型。
IFNULL(expr, null_result) 不限類型 不限類型或輸入類型的超級類型。 如果 exprNULL,就會傳回 null_result。否則,會傳回 expr。如果 expr 不是 NULL,就不會評估 null_resultexprnull_result 必須自動強制轉換為共通的超級類型。COALESCE(expr, null_result) 的同義詞。
NULLIF(expression, expression_to_match) 任何類型 T 或 T 的子類型 任何類型 T 或 T 的子類型 如果 expression = expression_to_match 是 true,就傳回 NULL,否則傳回 expressionexpressionexpression_to_match 必須自動強制轉換為共通的超級類型;這個運算式會比較強制轉換後的值,確認彼此是否相等。

運算式子查詢

運算式子查詢 (也就是作為運算式使用的子查詢) 有四種類型。相對於資料欄或資料表,運算式子查詢會傳回 NULL 或單一值,且必須由括號括住。有關子查詢的更完整討論,請參閱子查詢

子查詢的類型 結果資料類型 說明
純量 任何類型 T 運算式內括號中的子查詢 (例如在 SELECT 清單或 WHERE 子句中) 會解讀為純量子查詢。純量子查詢中的 SELECT 清單必須有正好一個欄位。如果子查詢傳回正好一個資料列,那個單一值就是純量子查詢結果。如果子查詢傳回零個資料列,純量子查詢就是 NULL。如果子查詢傳回一個以上的資料列,查詢會失敗並發生執行階段錯誤。當使用 SELECT AS STRUCT 編寫子查詢時,它可能包含多個資料欄,且傳回的值是建構的 STRUCT。選取多個資料欄時若不使用 SELECT AS 會發生錯誤。
ARRAY ARRAY 可使用 SELECT AS STRUCT 來建構結構的陣列,相反地,選取多個資料欄時若不使用 SELECT AS 會發生錯誤。如果子查詢傳回零個資料列,就會傳回空白 ARRAY。 永遠不會傳回 NULL ARRAY。
IN BOOL 在 IN 運算子之後的運算式中發生。子查詢必須產生類型相等性相容於 IN 運算子左側運算式的單一資料欄。如果子查詢傳回零個資料列,就會傳回 FALSE。 x IN () 相當於 x IN (value, value, ...)如要瞭解完整的語意,請參閱比較運算子一節中的 IN 運算子。
EXISTS BOOL 如果子查詢產生一或多個資料列,就會傳回 TRUE。如果子查詢產生零個資料列,就會傳回 FALSE。永遠不會傳回 NULL。與其他所有運算式子查詢不同,並沒有有關資料欄清單的規則。可以選取任何數量的資料欄,而且不會影響查詢結果。

範例

以下運算式子查詢的範例假設 t.int_array 的類型是 ARRAY<INT64>

類型 子查詢 結果資料類型 附註
純量 (SELECT COUNT(*) FROM t.int_array) INT64  
(SELECT DISTINCT i FROM t.int_array i) INT64,可能發生執行階段錯誤  
(SELECT i FROM t.int_array i WHERE i=5) INT64,可能發生執行階段錯誤  
(SELECT ARRAY_AGG(i) FROM t.int_array i) ARRAY 使用 ARRAY_AGG aggregation 函式來傳回 ARRAY。
(SELECT 'xxx' a) STRING  
(SELECT 'xxx' a, 123 b) 錯誤 傳回錯誤,因為有一個以上的資料欄
(SELECT AS STRUCT 'xxx' a, 123 b) STRUCT  
(SELECT AS STRUCT 'xxx' a) STRUCT  
ARRAY ARRAY(SELECT COUNT(*) FROM t.int_array) 大小為 1 的 ARRAY  
ARRAY(SELECT x FROM t) ARRAY  
ARRAY(SELECT 5 a, COUNT(*) b FROM t.int_array) 錯誤 傳回錯誤,因為有一個以上的資料欄
ARRAY(SELECT AS STRUCT 5 a, COUNT(*) b FROM t.int_array) ARRAY  
ARRAY(SELECT AS STRUCT i FROM t.int_array i) ARRAY 建立一個欄位 STRUCT 的 ARRAY
ARRAY(SELECT AS STRUCT 1 x, 2, 3 x) ARRAY 傳回具有匿名或重複欄位之 STRUCT 的 ARRAY。
ARRAY(SELECT AS TypeName SUM(x) a, SUM(y) b, SUM(z) c from t) array<TypeName> 選取到已命名類型中。假設 TypeName 是具有欄位 a,b,c 的 STRUCT 類型。
STRUCT (SELECT AS STRUCT 1 x, 2, 3 x) STRUCT 建構具有匿名或重複欄位的 STRUCT。
EXISTS EXISTS(SELECT x,y,z FROM table WHERE y=z) BOOL  
NOT EXISTS(SELECT x,y,z FROM table WHERE y=z) BOOL  
IN x IN (SELECT y FROM table WHERE z) BOOL  
x NOT IN (SELECT y FROM table WHERE z) BOOL  

Debugging 函式

BigQuery 支援下列 debugging 函式。

ERROR

ERROR(error_message)

說明

傳回錯誤。error_message 引數是 STRING

BigQuery 會以與可能產生下列錯誤的任何運算式相同的方式處理 ERROR:評估順序沒有任何特別保證。

傳回資料類型

BigQuery 會在內容中推測傳回類型。

範例

在下列範例中,如果資料列的值與兩個已定義值的其中之一不符,查詢會傳回錯誤訊息。

SELECT
  CASE
    WHEN value = 'foo' THEN 'Value is foo.'
    WHEN value = 'bar' THEN 'Value is bar.'
    ELSE ERROR(concat('Found unexpected value: ', value))
  END AS new_value
FROM (
  SELECT 'foo' AS value UNION ALL
  SELECT 'bar' AS value UNION ALL
  SELECT 'baz' AS value);

Found unexpected value: baz

在下列範例中,BigQuery 會在 x > 0 條件前後評估 ERROR 函式,這是因為 BigQuery 通常不提供 WHERE 子句條件間的順序保證,ERROR 函式也沒有特別的保證。

SELECT *
FROM (SELECT -1 AS x)
WHERE x > 0 AND ERROR('Example error');

在下一個範例中,WHERE 子句會評估 IF 條件,這會確保條件失敗時,BigQuery 只評估 ERROR 函式。

SELECT *
FROM (SELECT -1 AS x)
WHERE IF(x > 0, true, ERROR(FORMAT('Error: x must be positive but is %t', x)));'

Error: x must be positive but is -1
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁