資料表函式

資料表函式 (也稱為資料表值函式，簡稱 TVF) 是一種會傳回資料表的使用者定義函式。您可以在任何可使用資料表的地方使用資料表函式。資料表函式的行為類似於檢視畫面，但資料表函式可接受參數。

建立資料表函式

如要建立資料表函式，請使用 CREATE TABLE FUNCTION 陳述式。資料表函式包含產生資料表的查詢。函式會傳回查詢結果。以下表格函式會採用 INT64 參數，並在 bigquery-public-data.usa_names.usa_1910_current 的公開資料集查詢中，使用 WHERE 子句中的這個值：

CREATE OR REPLACE TABLE FUNCTION mydataset.names_by_year(y INT64)
AS (
  SELECT year, name, SUM(number) AS total
  FROM `bigquery-public-data.usa_names.usa_1910_current`
  WHERE year = y
  GROUP BY year, name
);

如要以其他方式篩選，您可以將多個參數傳遞至表格函式。下列表格函式會根據年份和名稱前置字元篩選資料：

CREATE OR REPLACE TABLE FUNCTION mydataset.names_by_year_and_prefix(
  y INT64, z STRING)
AS (
  SELECT year, name, SUM(number) AS total
  FROM `bigquery-public-data.usa_names.usa_1910_current`
  WHERE
    year = y
    AND STARTS_WITH(name, z)
  GROUP BY year, name
);

參數名稱

如果資料表函式參數與資料表欄的名稱相符，可能會造成參照不明確。在這種情況下，BigQuery 會將名稱解讀為資料表資料欄的參照，而非參數。建議您使用與任何參照資料表欄位名稱不同的參數名稱。

使用資料表函式

您可以在任何有效的資料表內容中呼叫資料表函式。以下範例會在 SELECT 陳述式的 FROM 子句中呼叫 mydataset.names_by_year 函式：

SELECT * FROM mydataset.names_by_year(1950)
  ORDER BY total DESC
  LIMIT 5

結果如下所示：

+------+--------+-------+
| year |  name  | total |
+------+--------+-------+
| 1950 | James  | 86447 |
| 1950 | Robert | 83717 |
| 1950 | Linda  | 80498 |
| 1950 | John   | 79561 |
| 1950 | Mary   | 65546 |
+------+--------+-------+

您可以將資料表函式的輸出結果與其他資料表彙整：

SELECT *
  FROM `bigquery-public-data.samples.shakespeare` AS s
  JOIN mydataset.names_by_year(1950) AS n
  ON n.name = s.word

您也可以在子查詢中使用表格函式：

SELECT ARRAY(
  SELECT name FROM mydataset.names_by_year(1950)
  ORDER BY total DESC
  LIMIT 5)

列出資料表函式

表格函式是一種處理常式。如要列出資料集中的所有常式，請參閱「列出常式」一文。

刪除資料表函式

如要刪除資料表函式，請使用 DROP TABLE FUNCTION 陳述式：

DROP TABLE FUNCTION mydataset.names_by_year

授權處理常式

您可以將資料表函式授權為例行程序。授權例行程序可讓您與特定使用者或群組分享查詢結果，而不用為他們提供產生結果的基礎資料表存取權。舉例來說，授權例行程序可以計算資料的匯總值，或查詢資料表值，並在計算中使用該值。詳情請參閱「已授權的日常生活動作」。

限制

  • 參數必須是純量值。BigQuery 中的資料表函式無法將資料表做為輸入參數。

  • 查詢主體必須是 SELECT 陳述式，且不得修改任何內容。舉例來說，資料定義語言 (DDL) 和資料操縱語言 (DML) 陳述式不允許在資料表函式中使用。如果需要副作用，建議改為撰寫程序。

  • 資料表函式必須儲存在參照的資料表所在位置。

配額

如要進一步瞭解表格函式配額和限制，請參閱「配額與限制」。