標準 SQL 関数と演算子

このページでは、関数や演算子などを含む BigQuery の式について説明します。

関数呼び出しルール

関数の表記内に特に明示的な指示がない限り、以下の規則はすべての関数に適用されます。

  • 数値型を受け入れる関数は、1 つのオペランドが浮動小数点値オペランドであり、他のオペランドが別の数値型である場合、両方のオペランドが FLOAT64 に変換されてから関数が評価されます。
  • オペランドが NULL の場合、結果は IS 演算子を除いて NULL となります。

  • タイムゾーンの影響を受ける関数(そのように関数の説明に示されています)の場合、タイムゾーンが指定されていなければ、デフォルトのタイムゾーンである UTC が使用されます。

SAFE. 接頭辞

構文:

SAFE.function_name()

説明

関数の先頭に SAFE. 接頭辞を付けると、エラーの代わりに NULL が返されます。SAFE. 接頭辞では、接頭辞が付いている関数自体のエラーが防止されるのみで、引数の式を評価するときに発生するエラーは防止されません。SAFE. 接頭辞では、範囲外の値を示すエラーなど、関数入力の値によって発生するエラーのみが防止されます。内部エラーやシステムエラーなどのその他のエラーは、依然として発生する可能性があります。エラーを返さない関数の出力には、SAFE. は影響を及ぼしません。エラーを返さない、RAND のような関数には、SAFE. は影響を及ぼしません。

+= などの演算子は、SAFE. 接頭辞をサポートしません。除算によるエラーを防ぐには、SAFE_DIVIDE を使用します。INARRAYUNNEST などの演算子は関数に似ていますが、SAFE. 接頭辞をサポートしません。CAST 関数と EXTRACT 関数も SAFE. 接頭辞をサポートしません。キャスティングのエラーを防ぐには、SAFE_CAST を使用します。

次に示す最初の例のように SUBSTR 関数を使用すると、通常はエラーが返されます。これは、この関数が負の値を持つ長さ引数をサポートしていないためです。ただし、SAFE. 接頭辞があるため、代わりに NULL が返されます。SUBSTR 関数の 2 番目の使用例では、想定される出力が提供され、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 では、エラーを発生できるほとんどのスカラー関数(STRING 関数数学的関数DATE 関数DATETIME 関数TIMESTAMP 関数など)で SAFE. 接頭辞の使用がサポートされています。集計関数分析関数ユーザー定義関数での SAFE. 接頭辞の使用はサポートされていません。

変換ルール

「変換」にはキャスティングや強制型変換などがあります。ただし、これらに限定されるわけではありません。

  • キャスティングは明示的変換であり、CAST() 関数を使用します。
  • 強制型変換は暗黙的変換であり、以下で説明されている状態の場合に BigQuery によって自動的に実行されます。
  • UNIX_DATE() などの独自の関数名を持つ、変換関数の 3 番目のグループがあります。

以下の表に、考えられるすべての CAST と、BigQuery データ型に対する強制型変換の可能性の要約を示します。「強制型変換後」は所定のデータ型(列など)のすべてのに適用されますが、リテラルとパラメータも強制型変換されます。詳細については、リテラル強制型変換およびパラメータ強制型変換をご覧ください。

元の型 キャスト先 強制型変換後
INT64 BOOL
INT64
FLOAT64
STRING
FLOAT64
FLOAT64 INT64
FLOAT64
STRING
 
BOOL BOOL
INT64
STRING
 
STRING BOOL
INT64
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)

これは、x1 の場合は "true"、その他の非 NULL 値の場合は "false"xNULL の場合は NULL になります。

元の値からターゲット ドメインに正常にマッピングされないサポートされた型の間でキャストすると、ランタイム エラーが発生します。たとえば、バイト列が有効な UTF-8 ではない場合に BYTES を STRING キャスティングするとランタイム エラーが発生します。

次の型の x 式をキャスティングする場合、以下の規則が適用されます。

元の型 変換後 x をキャスティングする場合の規則
INT64 FLOAT64 近似値だが厳密には正確でない可能性のある FLOAT64 値を返します。
INT64 BOOL x0 の場合は FALSE、それ以外では TRUE を返します。
FLOAT64 INT64 最も近い INT64 値を返します。
1.5 や -0.5 などの中間値の場合は、ゼロから離れるように丸められます。
FLOAT64 STRING 近似する文字列表現を返します。
BOOL INT64 1x の場合は TRUE、それ以外では 0 を返します。
BOOL STRING "true"x の場合は TRUE、それ以外では "false" を返します。
STRING FLOAT64 有効な FLOAT64 リテラルと同じ形式を持つと解釈して、FLOAT64 値として x を返します。
また、"inf""+inf""-inf" および "nan" からのキャストをサポートします。
変換は大文字と小文字を区別しません。
STRING BOOL x"true" の場合は TRUEx"false" の場合は FALSE を返します。
x のその他の値はすべて無効であり、BOOL にキャスティングするのではなく、エラーをスローします。
BOOL に変換するときに、STRING は大文字と小文字が区別されません。
STRING BYTES STRING は UTF-8 エンコーディングを使用して BYTES にキャストされます。たとえば、STRING "©" は BYTES にキャストされると、16 進数 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. 2 つの STRUCT が同じ数のフィールドを持っている。
  2. 元の STRUCT フィールド型を、対応する目的の STRUCT のフィールドの型に(フィールド名ではなく、フィールド順序によって定義されるように)明示的にキャストできる。

Safe キャスティング

CAST を使用したときに、BigQuery がキャストできない場合はクエリが失敗します。たとえば、次のクエリはエラーとなります。

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

このタイプのエラーからクエリを守るには、SAFE_CAST を使用します。SAFE_CASTCAST と同じですが、エラーの代わりに NULL を返します。

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

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

バイトから文字列にキャストする場合は、SAFE_CONVERT_BYTES_TO_STRING 関数も使用できます。無効な UTF-8 文字は、Unicode 置換文字 U+FFFD に置換されます。詳細については、SAFE_CONVERT_BYTES_TO_STRING をご覧ください。

16 進文字列から整数へのキャスティング

16 進数(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 関数によって、0、3、または 6 桁に切り捨てられます。

文字列からタイムスタンプにキャスティングする場合、string_expression はサポートされるタイムスタンプのリテラル形式に従う必要があります。従わない場合、ランタイム エラーが発生します。string_expression 自体に time_zone が含まれる場合があります。詳細については、タイムゾーンをご覧ください。string_expression にタイムゾーンがある場合、そのタイムゾーンが変換に使用されます。それ以外の場合、デフォルトのタイムゾーンである UTC が使用されます。文字列が 6 桁未満の場合、暗黙的に拡大されます。

string_expression が無効である、サブ秒が 6 桁よりも多い(マイクロ秒よりも精度が高い)、またはサポートされるタイムスタンプ範囲外にある時刻を表している場合、エラーが発生します。

日付型とタイムスタンプ型の間のキャスティング

BigQuery では、次のように日付型とタイムスタンプ型の間のキャスティングがサポートされています。

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

日付からタイムスタンプへのキャスティングでは、date_expression はデフォルトのタイムゾーンである UTC の午前 0 時(1 日が開始する時刻)を基点として解釈されます。タイムスタンプから日付へのキャスティングでは、タイムスタンプはデフォルトのタイムゾーンを基点にして効率的に切り捨てられます。

強制型変換

BigQuery は、関数のシグネチャを一致させる必要がある場合、式の結果の型を別の型に強制的に変換します。たとえば、関数 func() が型 INT64 の単一の引数を取るように定義され、式が FLOAT64 の結果の形式を持つ引数として使用される場合、その式の結果が INT64 型に強制変換されてから、func() が計算されます。

リテラル強制型変換

BigQuery では、次のリテラル強制型変換がサポートされています。

入力データ型 結果のデータ型 メモ
STRING リテラル DATE
TIMESTAMP

リテラル強制型変換は、実際のリテラル型が、対象の関数によって要求される型と異なる場合に必要です。たとえば、関数 func() が DATE 引数を取る場合、STRING リテラル "2014-09-27" は DATE に強制変換されるため、式 func("2014-09-27") は有効です。

リテラル変換は解析時に評価され、入力リテラルを目的の型に正常に変換できない場合、エラーが発生します。

注: 文字列リテラルが数値型に強制変換されることはありません。

パラメータ強制型変換

BigQuery では、次のパラメータ強制型変換がサポートされています。

入力データ型 結果のデータ型
STRING パラメータ

パラメータ値を目的の型に正常に強制変換できない場合は、エラーが発生します。

その他の変換関数

BigQuery では、次の変換関数も使用できます。

集計関数

集計関数は、一連の値に対して計算を実行する関数です。集計関数には、COUNT、MIN、および MAX などがあります。

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 でサポートされている集計関数について説明します。

ANY_VALUE

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

説明

ゼロ入力行がある場合、入力値から任意の値を返すか、NULL を返します。返される値は変動する可能性があります。つまり、この関数を使用するたびに異なる結果を受け取る可能性があります。

サポートされる引数の型

ANY

省略可能な句

OVER: ウィンドウを指定します。分析関数をご覧ください。

返されるデータ型

入力データ形式と一致します。

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 を除くすべてのデータ型。

省略可能な句

次の順番で句が適用されます。

  1. OVER: ウィンドウを指定します。分析関数をご覧ください。この句は現在、ARRAY_AGG() 内の他の句と互換性がありません。

  2. DISTINCT: expression で重複した値を除いて結果を返します。

  3. IGNORE NULLS または RESPECT NULLS: IGNORE NULLS を指定すると、結果から NULL 値が除外されます。RESPECT NULLS を指定した場合あるいは両方とも指定しない場合、結果に NULL 値が含まれます。ただし、最終的なクエリ結果の配列に NULL 要素が含まれる場合にはエラーが発生します。

  4. ORDER BY: 値の順序を指定します。

    • それぞれの並べ替えキーで、デフォルトの並べ替え方向は ASC になります。
    • NULL: ORDER BY 句のコンテキストの場合、NULL が最小の候補値です。つまり、NULL は昇順(ASC)では最初になり、降順(DESC)では最後になります。
    • 浮動小数点データ型の場合は、順序とグループ化について、浮動小数点のセマンティックスをご覧ください。
    • DISTINCT も指定する場合には、並べ替えキーは expression と同じにする必要があります。
    • ORDER BY を指定しないと、出力配列内の要素の順序は変わる可能性があります。つまり、この関数を使用するたびに、異なる結果を受け取る可能性があります。
  5. LIMIT: 結果の expression 入力の最大数を指定します。 制限 n は INT64 型の定数にする必要があります。

返されるデータ型

ARRAY

ゼロ入力行がある場合、この関数は NULL を返します。

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

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

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

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

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([NULL, 1, -2, 3, -2, 1, NULL]) AS x;
+-------------------------------+
| array_agg                     |
+-------------------------------+
| [NULL, NULL, 1, 1, -2, -2, 3] |
+-------------------------------+

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

+----------------------+
| array_agg            |
+----------------------+
| [NULL, 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([NULL, 1, -2, 3, -2, 1, NULL]) AS x;

+------+-------------------------------+
| x    | array_agg                     |
+------+-------------------------------+
| NULL | [NULL, NULL]                  |
| NULL | [NULL, NULL]                  |
| 1    | [NULL, NULL, 1, 1]            |
| 1    | [NULL, NULL, 1, 1]            |
| -2   | [NULL, NULL, 1, 1, -2, -2]    |
| -2   | [NULL, NULL, 1, 1, -2, -2]    |
| 3    | [NULL, NULL, 1, 1, -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 が最小の候補値です。つまり、NULL は昇順(ASC)では最初になり、降順(DESC)では最後になります。
    • 浮動小数点データ型の場合は、順序とグループ化について、浮動小数点のセマンティックスをご覧ください。
    • ORDER BY を指定しないと、出力配列内の要素の順序は変わる可能性があります。つまり、この関数を使用するたびに、異なる結果を受け取る可能性があります。
  2. LIMIT: 結果の expression 入力の最大数を指定します。 この制限は、入力配列の数に適用されます。配列内の要素数には適用されません。空の配列には 1 が含まれます。NULL 配列はカウントされません。 制限 n は INT64 型の定数にする必要があります。

返されるデータ型

ARRAY

ゼロ入力行がある場合に NULL を返すか、expression によってすべての行が 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: ウィンドウを指定します。分析関数をご覧ください。この句は現在、AVG() 内の他の句と互換性がありません。

  2. DISTINCT: expression で重複した値を除いて結果を返します。

返されるデータ型

  • 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 でビット積演算を実行し、結果を返します。

サポートされる引数の型

INT64

返されるデータ型

INT64

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

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

BIT_OR

BIT_OR(expression)

説明

expression でビット和演算を実行し、結果を返します。

サポートされる引数の型

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 でビット排他論理和演算を実行し、結果を返します。

サポートされる引数の型

INT64

省略可能な句

DISTINCT: expression で重複した値を除いて結果を返します。

返されるデータ型

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. expressionNULL 以外の値と評価された行数を返します。

サポートされる引数の型

expression には、任意のデータ型を指定できます。

省略可能な句

次の順番で句が適用されます。

  1. OVER: ウィンドウを指定します。分析関数をご覧ください。

  2. DISTINCT: expression で重複した値を除いて結果を返します。

戻りデータの型

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 の値の数を返します。ゼロ入力行がある場合に 0 を返すか、expression によってすべての行が FALSE と評価されます。

サポートされる引数の型

BOOL

省略可能な句

OVER: ウィンドウを指定します。分析関数をご覧ください。

戻りデータの型

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 を返します。ゼロ入力行がある場合は NULL を返すか、expression によってすべての行が 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 を返します。ゼロ入力行がある場合は NULL を返すか、expression によってすべての行が 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 式の最大値を返します。ゼロ入力行がある場合は NULL を返すか、expression によってすべての行が NULL と評価されます。入力に NaN が含まれている場合、NaN を返します。

サポートされる引数の型

STRUCT、ARRAY を除くすべてのデータ型

省略可能な句

OVER: ウィンドウを指定します。分析関数をご覧ください。

戻りデータの型

入力値として使用されるデータ型と同じ型。

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 式の最小値を返します。ゼロ入力行がある場合は NULL を返すか、expression によってすべての行が NULL と評価されます。入力に NaN が含まれている場合、NaN を返します。

サポートされる引数の型

STRUCT、ARRAY を除くすべてのデータ型

省略可能な句

OVER: ウィンドウを指定します。分析関数をご覧ください。

戻りデータの型

入力値として使用されるデータ型と同じ型。

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 (...)]

説明

非 NULL 値を結合して得られた値(STRING または BYTES のいずれか)を返します。

delimiter が指定された場合、連結された値はその区切り文字で区切られ、それ以外の場合は区切り文字としてカンマが使用されます。

サポートされる引数の型

STRING BYTES

省略可能な句

次の順番で句が適用されます。

  1. OVER: ウィンドウを指定します。分析関数をご覧ください。この句は現在、STRING_AGG() 内の他の句と互換性がありません。

  2. DISTINCT: expression で重複した値を除いて結果を返します。

  3. ORDER BY: 値の順序を指定します。

    • それぞれの並べ替えキーで、デフォルトの並べ替え方向は ASC になります。
    • NULL: ORDER BY 句のコンテキストの場合、NULL が最小の候補値です。つまり、NULL は昇順(ASC)では最初になり、降順(DESC)では最後になります。
    • 浮動小数点データ型の場合は、順序とグループ化について、浮動小数点のセマンティックスをご覧ください。
    • 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 (...)]

説明

非 NULL 値の合計を返します。

式が浮動小数点値である場合、合計は変動する可能性があります。つまり、この関数を使用するたびに異なる結果を受け取る可能性があります。

サポートされる引数の型

サポートされているすべての数値データ型。

省略可能な句

次の順番で句が適用されます。

  1. OVER: ウィンドウを指定します。分析関数をご覧ください。

  2. DISTINCT: expression で重複した値を除いて結果を返します。

戻りデータの型

  • 入力が整数の場合、INT64 を返します。

  • 入力が浮動小数点値の場合、FLOAT64 を返します。

入力が NULL のみの場合、NULL を返します。

入力に Inf が含まれる場合、Inf を返します。

入力に -Inf が含まれる場合、-Inf を返します。

入力に NaN が含まれている場合、NaN を返します。

入力に NaNInf の組み合わせが含まれている場合、-Inf を返します。

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   |
+---+-----+

統計集計関数

BigQuery は、次の統計集計関数をサポートします。

CORR

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

説明

一連の数値ペアのピアソン相関係数を返します。それぞれの数値ペアについて、最初の数値が依存変数となり、2 番目の数値が独立変数となります。返される結果は、-11 のあいだになります。結果が 0 の場合は、相関がないことを示しています。

入力されたペアに NULL の値が 1 つ以上あると、この関数はこれを無視します。NULL 値のない入力ペアが 1 つしかない場合、この関数は NULL を返します。

サポートされる入力型

FLOAT64

省略可能な句

OVER: ウィンドウを指定します。分析関数をご覧ください。

戻りデータの型

FLOAT64

COVAR_POP

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

説明

一連の数値ペアの共分散母数を返します。最初の数値は依存変数です。2 番目の数値は独立変数です。返される結果は -Inf+Inf の間になります。

入力されたペアに NULL の値が 1 つ以上あると、この関数はこれを無視します。NULL 値のない入力ペアがない場合、この関数は NULL を返します。NULL 値のない入力ペアが 1 つだけの場合には 0 を返します。

サポートされる入力型

FLOAT64

省略可能な句

OVER: ウィンドウを指定します。分析関数をご覧ください。

戻りデータの型

FLOAT64

COVAR_SAMP

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

説明

一連の数値ペアの共分散サンプルを返します。最初の数値は依存変数です。2 番目の数値は独立変数です。返される結果は -Inf+Inf の間になります。

入力されたペアに NULL の値が 1 つ以上あると、この関数はこれを無視します。NULL 値のない入力ペアが 1 つしかない場合、この関数は NULL を返します。

サポートされる入力型

FLOAT64

省略可能な句

OVER: ウィンドウを指定します。分析関数をご覧ください。

戻りデータの型

FLOAT64

STDDEV_POP

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

説明

バイアスをかけた母集団の標準偏差を返します。返される結果は 0 から +Inf の間になります。

この関数は NULL 入力を無視します。すべての入力が無視されると、この関数は NULL を返します。

この関数は、NULL 以外の入力を 1 つ受信すると 0 を返します。

サポートされる入力型

FLOAT64

省略可能な句

次の順番で句が適用されます。

  1. OVER: ウィンドウを指定します。分析関数をご覧ください。この句は現在、STDDEV_POP() 内の他の句と互換性がありません。

  2. DISTINCT: expression で重複した値を除いて結果を返します。

戻りデータの型

FLOAT64

STDDEV_SAMP

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

説明

値のサンプル(偏りのない)標準偏差を返します。返される結果は 0 から +Inf の間になります。

この関数は NULL 入力を無視します。NULL 以外の入力が 2 つ未満の場合、この関数は NULL を返します。

サポートされる入力型

FLOAT64

省略可能な句

次の順番で句が適用されます。

  1. OVER: ウィンドウを指定します。分析関数をご覧ください。この句は現在、STDDEV_SAMP() 内の他の句と互換性がありません。

  2. DISTINCT: expression で重複した値を除いて結果を返します。

戻りデータの型

FLOAT64

STDDEV

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

説明

STDDEV_SAMP のエイリアス。

VAR_POP

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

説明

バイアスをかけた母分散を返します。返される結果は 0 から +Inf の間になります。

この関数は NULL 入力を無視します。すべての入力が無視されると、この関数は NULL を返します。

この関数は、NULL 以外の入力を 1 つ受信すると 0 を返します。

サポートされる入力型

FLOAT64

省略可能な句

次の順番で句が適用されます。

  1. OVER: ウィンドウを指定します。分析関数をご覧ください。この句は現在、VAR_POP() 内の他の句と互換性がありません。

  2. DISTINCT: expression で重複した値を除いて結果を返します。

戻りデータの型

FLOAT64

VAR_SAMP

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

説明

バイアスをかけない値の標本分散を返します。返される結果は 0 から +Inf の間になります。

この関数は NULL 入力を無視します。NULL 以外の入力が 2 つ未満の場合、この関数は NULL を返します。

サポートされる入力型

FLOAT64

省略可能な句

次の順番で句が適用されます。

  1. OVER: ウィンドウを指定します。分析関数をご覧ください。この句は現在、VAR_SAMP() 内の他の句と互換性がありません。

  2. DISTINCT: expression で重複した値を除いて結果を返します。

戻りデータの型

FLOAT64

VARIANCE

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

説明

VAR_SAMP のエイリアス。

近似集計関数

近似集計関数は、メモリ使用量と時間においてはスケーラブルですが、正確な結果ではなく、近似的な結果を生成します。詳しい背景情報については、近似集計をご覧ください。

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. DISTINCT: expression で重複した値を除いて結果を返します。

  2. IGNORE NULLS または RESPECT NULLS: IGNORE NULLS が指定されている場合、またはどちらも指定されていない場合、NULL 値は結果から除外されます。RESPECT NULLS を指定した場合、結果に NULL 値が含まれます。ただし、最終的なクエリ結果の配列に NULL 要素が含まれる場合にはエラーが発生します。

返されるデータ型

expression パラメータで指定された型の ARRAY。

ゼロ入力行がある場合に NULL を返すか、expression によってすべての行が NULL と評価されます。

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(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 パラメータによって、返される要素の数が指定されます。

サポートされる引数の型

expressionGROUP BY 句がサポートしているどのデータ型のものにすることもできます。

number は INT64 にする必要があります。

返されるデータ型

STRUCT 型の ARRAY。STRUCT には 2 つのフィールドが含まれています。最初のフィールドには input 値が含まれています。2 番目のフィールドには、input が返された回数を指定する 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 の場合、この関数はエラーを返します。

サポートされる引数の型

expressionGROUP BY 句がサポートしているどのデータ型のものにすることもできます。

weight は、以下のいずれかにする必要があります。

  • INT64
  • FLOAT64

number は INT64 にする必要があります。

返されるデータ型

STRUCT 型の ARRAY。 STRUCT は、valuesum の 2 つのフィールドから構成されます。 value フィールドには入力式の値が含まれます。sum フィールドは weight と同じ型で、value フィールドに関連付けらた weight 入力の近似値の合計になります。

ゼロ入力行がある場合、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 は、expression パラメータと weight パラメータの 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++ アルゴリズムを使用する次の近似集計関数がサポートされています。近似集計関数の機能については、近似集計をご覧ください。

HLL_COUNT.INIT

HLL_COUNT.INIT(input [, precision])

説明

1 つ以上の input 値を取り、それらの値を HyperLogLog++ スケッチに集約するスカラー関数です。各スケッチは BYTES データ型で表現されます。これらのスケッチは、HLL_COUNT.MERGE または HLL_COUNT.MERGE_PARTIAL で結合できます。結合の必要がない場合は、HLL_COUNT.EXTRACT で個別の値の最終結果に変換できます。

input は、以下のいずれかになります。

  • INT64
  • STRING
  • BYTES

この関数では、省略可能なパラメータ precision を使用できます。このパラメータは概算値の精度を定義します。スケッチを処理したり、ディスクに保存したりするため、追加のメモリが必要になります。以下の表に、使用可能な精度、グループごとの最大スケッチサイズ、標準精度の信頼区間(CI)を示します。

精度 最大スケッチサイズ(KiB) 65% CI 95% CI 99% 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 1,024 ±0.05% ±0.10% ±0.20%
21 2,048 ±0.04% ±0.07% ±0.14%
22 4,096 ±0.03% ±0.05% ±0.10%
23 8,192 ±0.02% ±0.04% ±0.07%
24 16,384 ±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++ セットスケッチを結合してカーディナリティを返す集計関数です。

それぞれの 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)

説明

1 つ以上の 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)

説明

1 つの 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               |
+------------+---------+-----------------+

分析関数

データベースでは、分析関数は行のグループ全体に対して集計値を計算する関数です。行のグループに対して単一の集計値を返す集計関数とは異なり、分析関数は入力行のグループに対して分析関数を計算することで、行ごとに単一の値を返します。

分析関数は複雑な分析オペレーションを簡潔に表す強力なメカニズムであり、分析関数を使用しなければコストの高いセルフ JOIN や SQL クエリ外での計算を行う必要が生じる評価を効率的に行えます。

分析関数は、SQL 標準や一部の商用データベースで「(分析)ウィンドウ関数」とも呼ばれています。これは、分析関数が windowwindow frame と呼ばれる行のグループに対して評価されるためです。その他の一部のデータベースでは、オンライン分析処理(OLAP)関数と呼ばれることもあります。

簡単な構文:

analytic_function_name ( [ argument_list ] )
  OVER (
    [ PARTITION BY partition_expression_list ]
    [ ORDER BY expression [{ ASC | DESC }] [, ...] ]
    [ window_frame_clause ]
  )

分析関数には OVER 句が必要です。この句は、分析関数の評価対象になる window frame を定義します。OVER 句には、次の 3 つのオプションの句が含まれています。BigQuery は、OVER 句のサブ句を、それらが書き込まれる順番で評価します。

  • PARTITION BY 句は、入力行を複数のパーティションに分割します。これは GROUP BY と似ていますが、実際に行を同じキーに結合する作業は行われません。
  • ORDER BY 句は、各パーティション内の順序付けを指定します。
  • window_frame_clause は、現在のパーティション内の window frame を定義します。

OVER 句は空(OVER())にすることもできます。この場合、window frame にはすべての入力行が含まれます。

分析関数は集約(GROUP BY および非分析関数)の後に評価されます。

たとえば、ある会社が各従業員の「勤続ランク」を示す、つまり勤務年数が最も長い従業員を示す、各部門のスコアボードを作成するとします。Employees テーブルには、NameStartDate、および Department という列が含まれています。

次のクエリは、部門内の各従業員のランクを計算します。

SELECT firstname, department, startdate,
  RANK() OVER ( PARTITION BY department ORDER BY startdate ) AS rank
FROM Employees;

図 1 に概念的な計算プロセスを示します。

マークダウン イメージ 図 1: 分析関数の図

BigQuery は、OVER 句内のサブ句を、出現する順序で評価します。

  1. PARTITION BY: テーブルは最初に department ごとに 2 つのパーティションに分割されます。
  2. ORDER BY: 各パーティション内の従業員の行は startdate によって順序付けされます。
  3. フレーミング: なし。ウィンドウ フレーム句を RANK() に対して使用することはできません。これはすべての番号付け関数を対象にしているためです。
  4. RANK(): 勤続ランクは、window frame に対して行ごとに計算されます。

分析関数の構文

analytic_function_name ( [ argument_list ] )
  OVER { window_name | ( [ window_specification ] ) }

window_specification:
  [ window_name ]
  [ PARTITION BY partition_expression_list ]
  [ ORDER BY expression [{ ASC | DESC }] [, ...] ]
  [ window_frame_clause ]

window_frame_clause:
{ ROWS | RANGE }
{
  { UNBOUNDED PRECEDING | numeric_expression PRECEDING | CURRENT ROW }
  |
  { BETWEEN window_frame_boundary_start AND window_frame_boundary_end }
}

window_frame_boundary_start:
{ UNBOUNDED PRECEDING | numeric_expression { PRECEDING | FOLLOWING } | CURRENT ROW }

window_frame_boundary_end:
{ UNBOUNDED FOLLOWING | numeric_expression { PRECEDING | FOLLOWING } | CURRENT ROW }

分析関数はスカラー式またはスカラー式のオペランドとしてクエリ内の次の 2 か所のみに使用できます。

  • SELECT リスト。分析関数が SELECT リスト内で使用されると、その argument_list は同じ SELECT リストで導入された別名を参照できません。
  • ORDER BY。分析関数がクエリの ORDER BY 句で使用されると、その argument_list は SELECT リスト別名を参照できます。

また、分析関数は別名を間接的に介する場合でも、その argument_list または OVER 句内の別の分析関数を参照できません。

無効:

SELECT ROW_NUMBER() OVER () AS alias1
FROM Singers
ORDER BY ROW_NUMBER() OVER(PARTITION BY alias1)

上記のクエリでは、分析関数 alias1 が分析関数 ROW_NUMBER() OVER() に解決されます。

OVER 句

構文:

OVER { window_name | ( [ window_specification ] ) }

window_specification:
  [ window_name ]
  [ PARTITION BY partition_expression_list ]
  [ ORDER BY sort_specification_list ]
  [ window_frame_clause ]

OVER 句には、次の 3 つのコンポーネントがあります。

  • PARTITION BY
  • ORDER BY
  • window_frame_clause または window_name。これは、WINDOW 句に定義されている window_specification を参照します。

OVER 句が空(OVER())の場合、すべての入力行を含む単一のパーティションに対して分析関数が計算されます。つまり、出力行ごとに同じ結果が生成されます。

PARTITION BY 句

構文:

PARTITION BY expression [, ... ]

PARTITION BY 句は入力行を別個のパーティションに分割します。それらに対して、分析関数が個別に評価されます。PARTITION BY 句では複数の expressions を使用できます。

expression のデータ型は Groupable で、かつパーティショニングをサポートしている必要があります。つまり、expression を次のデータ型にすることはできません

  • 浮動小数点数
  • STRUCT
  • ARRAY

このリストは、GROUP BY でサポートされていないデータ型のリストとほぼ同じですが、追加で浮動小数点型も除外されています(BigQuery のデータ型の上部にあるデータ型のプロパティの表の「Groupable」を参照)。

PARTITION BY 句がない場合、BigQuery は入力全体を単一のパーティションとして処理します。

ORDER BY 句

構文:

ORDER BY expression [ ASC | DESC ] [, ... ]

ORDER BY 句は各パーティション内の順序を定義します。ORDER BY 句がない場合、パーティション内の行の順番は変わる可能性があります。一部の分析関数には ORDER BY が必要です。これは、分析関数の各ファミリーのセクションに示されています。ORDER BY 句が存在しても、一部の関数は window frame 内の順番から影響を受けません(COUNT など)。

OVER 句内の ORDER BY 句は、次の点で標準の ORDER BYと一致します。

  • 複数の expressions が存在する可能性があります。
  • expression には、順序付けをサポートするタイプが必要です。
  • オプションの ASC/DESC 仕様を各 expression に使用できます。
  • NULL 値は可能な最小値として順序付けされます(ASC の場合は最初、DESC の場合は最後)。

データ型のサポートは、次の型が順序付けをサポートしていないという点で、標準の ORDER BYと同じです。

  • ARRAY
  • STRUCT

OVER 句に ORDER BY 句が含まれているが、window_frame_clause は含まれていない場合、ORDER BY は暗黙的に window_frame_clause を次のように定義します。

RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW

window_frame_clauseORDER BY 句のいずれも存在しない場合、window frame はデフォルトでパーティション全体に設定されます。

Window Frame 句

構文:

{ ROWS | RANGE }
{
  { UNBOUNDED PRECEDING | numeric_expression PRECEDING | CURRENT ROW }
  |
  { BETWEEN window_frame_boundary_start AND window_frame_boundary_end }
}

window_frame_boundary_start:
{ UNBOUNDED PRECEDING | numeric_expression { PRECEDING | FOLLOWING } | CURRENT ROW }

window_frame_boundary_end:
{ UNBOUNDED FOLLOWING | numeric_expression { PRECEDING | FOLLOWING } | CURRENT ROW }

window_frame_clause はパーティション内の現在の行の周囲に window frame を定義し、その範囲を対象に分析関数が評価されます。 window_frame_clause には、物理ウィンドウ フレーム(ROWS によって定義)と論理ウィンドウ フレーム(RANGE によって定義)の両方を使用できます。OVER 句に ORDER BY 句は含まれているが、window_frame_clause は含まれていない場合、ORDER BY は暗黙的に window_frame_clause を次のように定義します。

RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW

window_frame_clauseORDER BY 句のいずれも存在しない場合、window frame はデフォルトでパーティション全体に設定されます。

numeric_expression は定数またはクエリ パラメータにのみすることができます。これらは両方とも負ではない値を持つ必要があります。負の値を持つ場合、BigQuery はエラーが発生します。

Window Frame 句の例:

ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
  • パーティション全体を含めます。
  • パーティション全体の総計の計算などに使用されます。
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
  • 現在の行の前、または現在の行を含む、パーティション内のすべての行を含めます。
  • 累積合計の計算などに使用されます。
ROWS BETWEEN 2 PRECEDING AND 2 FOLLOWING
  • 現在の行の 2 つ前と 2 つ後の行の間のすべての行を含めます。
  • 移動平均の計算などに使用されます。

window_frame_specBETWEEN 句を使用する場合:

  • window_frame_boundary_start で、window_frame_boundary_end の境界よりも後で開始しない境界を指定する必要があります。これを使用すると、次のようになります。
    1. window_frame_boundary_startCURRENT ROW が含まれる場合、window_frame_boundary_endPRECEDING を含めることはできません。
    2. window_frame_boundary_startFOLLOWING が含まれる場合、window_frame_boundary_endCURRENT ROW または PRECEDING を含めることはできません。
  • window_frame_boundary_start にデフォルト値はありません。

上記以外の場合、指定された window_frame_spec 境界はウィンドウ フレームの開始点を表し、ウィンドウ フレーム境界の終了点はデフォルトで 'CURRENT ROW' に設定されます。つまり、

ROWS 10 PRECEDING

は、次と等価です。

ROWS BETWEEN 10 PRECEDING AND CURRENT ROW
ROWS

ROWS ベースのウィンドウ フレームは、現在の行からの物理オフセットに基づいて window frame を計算します。たとえば、以下のウィンドウ フレームは現在の行の周りのサイズ 5(最大)のウィンドウ フレームを定義します。

ROWS BETWEEN 2 PRECEDING and 2 FOLLOWING

window_frame_clause 内の numeric_expression は現在の行からの行数として解釈され、定数の負ではない整数である必要があります。これはクエリ パラメータにすることもできます。

所定の行の window frame がパーティションの開始点または終了点を越える場合、window frame はそのパーティション内の行のみを含めます。

たとえば、列 zx、および y を持つ次のテーブルの場合を考えてみます。

z x y
1 5 AA
2 2 AA
3 11 AB
4 2 AA
5 8 AC
6 10 AB
7 1 AB

次の分析関数の場合を考えてみます。

SUM(x) OVER (PARTITION BY y ORDER BY z ROWS BETWEEN 1 PRECEDING AND 1
FOLLOWING)

PARTITION BY 句は y 値に基づいてテーブルを 3 つのパーティションに分割し、ORDER BYz 値によって各パーティション内の行を順序付けします。

パーティション 1/3:

z x y
1 5 AA
2 2 AA
4 2 AA

パーティション 2/3:

z x y
3 11 AB
6 10 AB
7 1 AB

パーティション 3/3:

z x y
5 8 AC

以下のテーブルでは、太字は現在評価されている行を示し、色付きのセルはその行の window frame 内のすべての行を示します。

  • y = AA パーティション内の最初の行については、window frame には 2 行しか含まれません。これは、window_frame_spec によってウィンドウのサイズが 3 であると示されていても、先行する行がないからです。最初の行については、分析関数の結果は 7 になります。
z x y
1 5 AA
2 2 AA
4 2 AA
  • パーティション内の 2 番目の行については、window frame には 3 つすべての行が含まれます。2 番目の行については、分析関数の結果は 9 になります。
z x y
1 5 AA
2 2 AA
4 2 AA
  • パーティション内の最後の行については、後続の行がないため、window frame には 2 行しか含まれません。3 番目の行については、分析関数の結果は 4 になります。
z x y
1 5 AA
2 2 AA
4 2 AA
RANGE

RANGE ベースのウィンドウ フレームは、現在の行の window frame キー値に基づき、現在の行の周りの行の論理範囲に基づいて ORDER BY を計算します。 指定した範囲の値を現在の行のキー値に加算、またはキー値から除算して、window frame の開始または終了範囲の境界を定義します。

ORDER BY 句は、ウィンドウが次の状態である場合を除き、指定する必要があります。

RANGE BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING.

window_frame_clause 内の numeric_expression は、ORDER BY キーの現在行の値からのオフセットとして解釈されます。numeric_expression には数値型が必要です。DATE および TIMESTAMP は現在サポートされていません。また、numeric_expression は負ではない定数の整数またはパラメータにする必要があります。

RANGE ベースのウィンドウ フレームには、ORDER BY 句に最大で 1 つの expression が存在する可能性があり、expression には数値型が必要です。

単一のパーティションを持つ、RANGE ベースのウィンドウ フレームの例を以下に示します。

SELECT x, COUNT(*) OVER ( ORDER BY x
  RANGE BETWEEN 2 PRECEDING AND 2 FOLLOWING ) AS count_x
FROM T;

以下のテーブルでは、太字は現在評価されている行を示し、色付きのセルはその行の window frame 内のすべての行を示します。

  • 行 1 では x = 5 であるため、COUNT(*) には 3 <=x <= 7 の行のみが含まれます。
x count_x
5 1
2
11
2
8
10
1
  • 行 2 では x = 2 であるため、COUNT(*) には 0 <= x <= 4 の行のみが含まれます。
x count_x
5 1
2 3
11
2
8
10
1
  • 行 3 では x = 11 であるため、COUNT(*) には 9 <= x <= 13 の行のみが含まれます。
x count_x
5 1
2 3
11 2
2
8
10
1

WINDOW 句

構文:

WINDOW window_definition [, ...]
window_definition: window_name AS ( window_specification )

WINDOW 句は名前付きウィンドウのリストを定義します。その window_nameSELECT リストの分析関数で参照できます。これは、複数の分析関数に同じ window_frame_clause を使用する場合に便利です。

WINDOW 句は、クエリ構文に示されているように、SELECT 句の最後にのみ使用できます。

名前付きウィンドウ

WINDOW 句の定義後は、分析関数で名前付きのウィンドウを使用できるようになりますが、SELECT リストの場合に限り、ORDER BY 句で名前付きウィンドウを使用できません。名前付きウィンドウは単独で使用することも、OVER 句に埋め込むことができます。名前付きウィンドウは SELECT リストのエイリアスを参照できます。

例:

SELECT SUM(x) OVER window_name FROM ...
SELECT SUM(x) OVER (
  window_name
  PARTITION BY...
  ORDER BY...
  window_frame_clause)
FROM ...

OVER 句に埋め込んだ場合、window_name に関連付けられた window_specification は、同じ OVER 句内にある PARTITION BYORDER BY、および window_frame_clause と互換性を持つ必要があります。

名前付きウィンドウには次の規則が適用されます。

  • SELECT リストでのみ名前付きウィンドウを参照できます。つまり、ORDER BY 句、外側のクエリ、またはサブクエリでそれらを参照することはできません。
  • ウィンドウ W1(名前付きまたは名前なし)は、次の規則に従って名前付きウィンドウ NW2 を参照できます。
    1. W1 が名前付きウィンドウである場合、参照される名前付きウィンドウ NW2 は同じ WINDOW 句内で W1 よりも前にある必要があります。
    2. W1 に PARTITION BY 句を含めることはできません。
    3. W1 と NW2 の両方に ORDER BY 句が含まれる状態を true にすることはできません。
    4. NW2 に window_frame_clause を含めることはできません。
  • (名前付きまたは名前なし)ウィンドウ W1 が名前付きウィンドウ NW2 を参照する場合、結果となるウィンドウの指定は次を使用して定義されます。
    1. 存在する場合、NW2 からの PARTITION BY
    2. W1 または NW2 からの ORDER BY。いずれかが指定されている場合、両方に ORDER BY 句を使用することはできません。
    3. 存在する場合、W1 からの window_frame_clause

サポートされる関数

番号付け関数

番号付け関数は、指定されたウィンドウ内の行の位置に基づいて、各行に整数値を割り当てます。

OVER 句の要件:

  • PARTITION BY: 省略可。
  • ORDER BY: ROW_NUMBER() 以外必須。
  • window_frame_clause: 無効。

順序付けで 2 つの行が結合されている場合、ピアになります。ピアの概念は、関数 RANK()DENSE_RANK()、および CUME_DIST に関連します。

構文 結果のデータ型 説明
RANK() INT64 順序付けされたパーティション内の各行の序数(1 ベース)ランクを返します。 すべてのピア行は同じランク値を受け取ります。次の行、またはピア行のセットは、常に 1 ずつ増加するランク値ではなく、前のランク値を持つピアの数だけ増加するランク値を受け取ります。この表の下にある RANK() をご覧ください。
DENSE_RANK() INT64 ウィンドウ パーティション内の各行の序数(1 ベース)ランクを返します。すべてのピア行は同じランク値を受け取り、後続のランク値は 1 ずつ増加されます。
PERCENT_RANK() FLOAT64 (RK-1)/(NR-1)として定義される行のパーセンタイル ランクを返します。RK は行の RANK であり、NR はパーティション内の行数です。NR=1 の場合、0 を返します。
CUME_DIST() FLOAT64 NP/NR として定義される行の相対的ランクを返します。NP は、現在の行に先行するか、ピアになっている行数に定義されます。NR はパーティション内の行数です。
NTILE(constant_integer_expression) INT64 この関数は行の順序付けに基づいて行を constant_integer_expression で指定された数のバケットに分割し、各行に割り当てられた 1 ベースのバケット番号を返します。バケット内の行数は、最大で 1 ずつ変えることができます。余りの値(行数をバケットで割った余り)は、バケット 1 で開始するバケットごとに 1 が分配されます。constant_integer_expression が NULL、0、または負の値に評価されると、エラーが出されます。
ROW_NUMBER() INT64 ORDER BY 句は必要ありません。順序付けされた各パーティションの各行の順次行序数(1 ベース)を返します。ORDER BY 句が指定されていない場合、結果は変動する可能性があります。

RANK()DENSE_RANK()、および ROW_NUMBER() の例:

SELECT x,
 RANK() OVER (ORDER BY x ASC) AS rank,
 DENSE_RANK() OVER (ORDER BY x ASC) AS dense_rank,
 ROW_NUMBER() OVER (PARTITION BY x ORDER BY y) AS row_num
FROM
 (SELECT 1 AS x, 'A' AS y
  UNION ALL SELECT 2 AS x, 'A' AS y
  UNION ALL SELECT 2 AS x, 'B' AS y
  UNION ALL SELECT 5 AS x, 'A' AS y
  UNION ALL SELECT 8 AS x, 'B' AS y
  UNION ALL SELECT 10 AS x, 'A' AS y
  UNION ALL SELECT 10 AS x, 'B' AS y);
x rank dense_rank row_num
1 1 1 1
2 2 2 1
2 2 2 2
5 4 3 1
8 5 4 1
10 6 5 1
10 6 5 2
  • RANK(): x=5 の場合、rank は 4 を返します。これは、RANK() が前のウィンドウ順序付けグループ内のピアの数によって増加するからです。
  • DENSE_RANK(): x=5 の場合、dense_rank は 3 を返します。これは、DENSE_RANK() は値をスキップせずに常に 1 だけ増加するからです。
  • ROW_NUMBER(): x=5 の場合、row_num は 1 を返します。

一般に、ナビゲーション関数は現在の行からウィンドウ フレーム内の別の行に対して、いくつかの value_expression を計算します。OVER 句の構文は、ナビゲーション関数によって異なります。

OVER 句の要件:

  • PARTITION BY: 省略可。
  • ORDER BY:
    1. PERCENTILE_CONTPERCENTILE_DISC には許可されません。
    2. FIRST_VALUELAST_VALUENTH_VALUELEAD および LAG については必須です。
  • window_frame_clause:
    1. PERCENTILE_CONTPERCENTILE_DISCLEAD、および LAG には許可されません。
    2. FIRST_VALUELAST_VALUE、および NTH_VALUE についてはオプションです。

すべてのナビゲーション関数について、結果のデータ型は value_expression と同じ型になります。

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

説明

現在のウィンドウ フレーム内の最初の行の value_expression の値を返します。

この関数は、IGNORE NULLS が使用されていない場合は、計算に NULL 値が含まれます。IGNORE NULLS が使用されている場合、関数は計算から NULL 値を除外します。

サポートされる引数の型

value_expression は、式によって返すことができるあらゆるデータ型が可能です。

戻りデータの型

ANY

以下は、各部門について最速時間を計算した例です。

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 の値を返します。

この関数は、IGNORE NULLS が使用されていない場合は、計算に NULL 値が含まれます。IGNORE NULLS が使用されている場合、関数は計算から NULL 値を除外します。

サポートされる引数の型

value_expression は、式によって返すことができるあらゆるデータ型が可能です。

戻りデータの型

ANY

以下は、各部門について最遅時間を計算した例です。

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 を返します。

この関数は、IGNORE NULLS が使用されていない場合は、計算に NULL 値が含まれます。IGNORE NULLS が使用されている場合、関数は計算から NULL 値を除外します。

サポートされる引数の型

  • value_expression は、式から返すことができる任意のデータ型を指定できます。
  • constant_integer_expression は、整数を返す任意の定数式にすることができます。

戻りデータの型

ANY

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 は、値の式の型と互換性が必要です。

戻りデータの型

ANY

次の例は、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 は、値の式の型と互換性が必要です。

戻りデータの型

ANY

次の例は、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 が存在する場合:

  • 2 つの NULL 値の間の補間は NULL を返します。
  • NULL 値と非 NULL 値の間の補間は非 NULL 値を返します。

サポートされる引数の型

  • value_expression は数値式です。
  • percentile は範囲 [0, 1]DOUBLE リテラルです。

戻りデータの型

DOUBLE

次の例では、NULL を無視して、値の列からいくつかのパーセンタイルの値を計算します。

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   |
+-----+-------------+--------+--------------+-----+

次の例では、NULL を尊重しながら、値の列からいくつかのパーセンタイルの値を計算します。

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 に対して指定されたパーセンタイル値を計算します。返される値は、指定された percentile と等しいかそれ以上の累積分布を持つ value_expression の最初に並べ替えられた値です。

この関数は、RESPECT NULLS が存在しない限り、NULL 値を無視します。

サポートされる引数の型

  • value_expression は任意の順序付け可能な型にすることができます。
  • percentile は範囲 [0, 1]DOUBLE リテラルです。

戻りデータの型

ANY

次の例では、NULL を無視して、値の列からいくつかのパーセンタイルの値を計算します。

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   |
+------+-----+--------+-----+

次の例では、NULL を尊重しながら、値の列からいくつかのパーセンタイルの値を計算します。

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   |
+------+------+--------+-----+

集計分析関数

BigQuery では、分析関数として次の集計関数がサポートされています。

これらの関数を使用して、OVER 句は集計関数呼び出しに単純に追加されますが、その他の点では関数呼び出し構文は変更されません。それらの集計関数と対応するものと同様に、これらの分析関数は集約を実行しますが、具体的に各行の関連するウィンドウ フレームを対象に実行します。これらの分析関数の結果データ型は、それらの集計関数に対応するものと同じです。

OVER 句の要件:

  • PARTITION BY: 省略可。
  • ORDER BY: オプション。DISTINCT がある場合は使用できません。
  • window_frame_clause: オプション。DISTINCT がある場合は使用できません。

例:

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

ビット関数

BigQuery は、次のビット関数をサポートしています。

BIT_COUNT

BIT_COUNT(expression)

説明

入力 expression は整数または BYTES にする必要があります。

入力 expression で設定されたビット数を返します。 整数の場合、2 の補数形式になります。

戻りデータの型

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     |
+-------+--------+---------------------------------------------+--------+

数学関数

数学関数:

  • いずれかの入力パラメータが NULL の場合、NULL を返します。
  • 引数のいずれかが NaN の場合 NaN を返します。
関数 説明
ABS(X) 絶対値を計算します。整数の引数で値を同じ型として表せない場合、エラーを生成します(これは、正の表記が含まれていない最大の負の入力値に対してのみ発生します)。+/-inf 引数に対して +inf を返します。
SIGN(X) 負、ゼロ、正の引数に対してそれぞれ -1、0、+1 を返します。浮動小数点引数では正と負のゼロは区別されません。NaN 引数に対して NaN を返します。
IS_INF(X) 値が正または負の無限大の場合に TRUE を返します。NULL 入力に対しては NULL を返します。
IS_NAN(X) 値が NaN 値である場合、TRUE を返します。NULL 入力に対しては NULL を返します。
IEEE_DIVIDE(X, Y)

Y で X を除算します、失敗することはありません。FLOAT64 を返します。除算演算子(/)とは異なり、ゼロまたはオーバーフローによる除算エラーを生成しません。

特殊ケース:

  • 結果がオーバーフローする場合、+/-inf を返します。
  • Y=0 かつ X=0 の場合、NaN を返します。
  • Y=0 かつ X!=0 の場合、+/-inf を返します。
  • X=+/-inf かつ Y=+/-inf の場合、NaN を返します。
IEEE_DIVIDE の動作については、下の表で詳細に説明しています。
RAND() FLOAT64 型の疑似ランダム値を生成します。0 と 1 を含めて 0 と 1 の間の数値です。
SQRT(X) X の平方根を計算します。X が 0 より小さい場合、エラーを出します。X が +inf の場合は +inf を返します。
POW(X, Y) 指数関数: X の Y 乗の値を返します。結果がアンダーフローして表示できない場合、ゼロ値が返されます。次のいずれかに該当する場合、エラーを生成することがあります。X が 0 未満の有限の値でかつ Y が整数値でない場合、X は 0 でかつ Y が 0 未満の有限の値の場合、結果がオーバーフローする場合。POW() の動作については、下の表で詳細に説明しています。
POWER(X, Y) POW() と同義。POWER() の動作は、下の表で詳細に説明しています。
EXP(X) 自然指数関数式を計算します。結果がアンダーフローした場合、ゼロが返されます。結果がオーバーフローする場合は、エラーになります。X が +/-inf の場合は、+inf(または 0)が返されます。
LN(X) X の自然対数を計算します。X がゼロ以下の場合は、エラーになります。X が +inf の場合は、+inf が返されます。
LOG(X) LN(X) と同義
LOG(X, Y) Y を底とする X の対数を計算します。X がゼロ以下で、Y が 1.0、Y がゼロ以下の場合、エラーになります。LOG(X, Y) の動作は、下の表で詳細に説明しています。
LOG10(X) LOG(X) と似ていますが、10 を底とする対数を計算します。
GREATEST(X1,...,XN) 入力のいずれかが NULL の場合 NULL を返します。それ以外では、入力のいずれかが NaN の場合 NaN を返します。それ以外では、< 比較によって X1,...,XN の間の最大値を返します。
LEAST(X1,...,XN) 入力のいずれかが NULL の場合 NULL を返します。それ以外では、入力のいずれかが NaN の場合 NaN を返します。それ以外では、> 比較によって X1,...,XN の間の最小値を返します。
DIV(X, Y) Y による X の整数除算の結果を返します。ゼロ除算はエラーを返します。-1 による除算はオーバーフローする可能性があります。可能な結果の型については、下の表を参照してください。
SAFE_DIVIDE(X, Y)除算演算子(/)と同じですが、ゼロで割った場合など、エラーがあると NULL を返します。
MOD(X, Y) モジュロ関数: Y による X の除算の剰余を返します。返された値は X と同じ符号を持ちます。Y が 0 の場合、エラーが発生します。可能な結果の型については、下の表を参照してください。

IEEE_DIVIDE(X, Y) の特殊なケース

次の表は、IEEE_DIVIDE(X,Y) の特殊なケースを示しています。

分子データ型(X) 分母データ型(Y) 結果値
0 以外 0 +/-inf
0 0 NaN
0 NaN NaN
NaN 0 NaN
+/-inf +/-inf NaN

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

LOG(X, Y) の特殊なケース

X Y LOG(X, Y)
-inf 任意値 NaN
任意値 +inf NaN
+inf 0.0 Y < 1.0 -inf
+inf Y > 1.0 +inf

丸め関数

構文 説明
ROUND(X) X を最も近い整数に丸めます。中間の値の場合は、ゼロから遠ざかるように丸められます。
ROUND(X, N) 小数点以下の N 小数位に X を丸めます。N は負にすることができ、小数点の左側に数字を四捨五入します。中間の値の場合は、ゼロから遠ざかるように丸められます。オーバーフローが発生した場合は、エラーが発生します。
TRUNC(X) 絶対値が X 以下で最も近い整数に X を丸めます。
TRUNC(X, N) ROUND(X, N) に似ていますが、常にゼロに近づくように丸めます。ROUND(X, N) とは異なり、オーバーフローすることはありません。
CEIL(X) X 以上で最小の整数値を(FLOAT64 型で)返します。
CEILING(X) CEIL(X) と同義です。
FLOOR(X) X よりも大きくない最大の整数値を(FLOAT64 の形式で)返します。

BigQuery 丸め関数の動作例:

入力「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(X) X のコサインを計算します。失敗することはありません。
COSH(X) X の双曲線コサインを計算します。オーバーフローが発生した場合、エラーになります。
ACOS(X) X のアークコサインの主値を計算します。戻り値は [0] の範囲内になります。X が [-1, 1] の範囲外の有限の値である場合、エラーになります。
ACOSH(X) X の逆双曲線コサインを計算します。X が 1 未満の有限値の場合、エラーになります。
SIN(X) X のサインを計算します。失敗することはありません。
SINH(X) X の双曲線サインを計算します。オーバーフローが発生した場合、エラーになります。
ASIN(X) X のアークサインの主値を計算します。戻り値は [-π/2,π/2] の範囲内になります。X が [-1, 1] の範囲外の有限の値である場合、エラーになります。
ASINH(X) X の逆双曲線正サインを計算します。失敗することはありません。
TAN(X) X のタンジェントを計算します。オーバーフローが発生した場合、エラーになります。
TANH(X) X の双曲線タンジェントを計算します。失敗することはありません。
ATAN(X) X のアークタンジェントの主値を計算します。戻り値は [-π/2,π/2] の範囲内になります。失敗することはありません。
ATANH(X) X の逆双曲線タンジェントを計算します。X の絶対値が 1 以上の場合、エラーになります。
ATAN2(Y, X) 象限を判断するために 2 つの引数の符号を用いて、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

三角関数と双曲線丸め関数の特殊なケース

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

ハッシュ関数

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;

文字列関数

これらの文字列関数は、2 種類のデータ型 STRING と BYTE の値に使用できます。文字列値は、正しい形式の UTF-8 にする必要があります。

STRPOS のような位置の値を返す関数は、それらの位置として INT64 を返します。値 1 は最初の文字(またはバイト)を参照し、2 は 2 番目のものを参照し、以下同様に続きます。値 0 は無効なインデックスを参照します。STRING 型で処理する場合、返される位置は文字位置を参照します。

すべての文字列比較は、Unicode の標準的な同値に関係なく、バイト単位で行われます。

BYTE_LENGTH

BYTE_LENGTH(value)

説明

値のタイプが STRING または BYTES のどちらであるかに関係なく、value の長さをバイト単位で返します。

戻り値の型

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  |
+-------+

次の例では、ROT13 アルゴリズム(アルファベットの文字列をすべて 13 ずつずれた別の文字に変換する手法)を使用して文字列をエンコードします。

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[, ...])

説明

単一の結果に 1 つ以上の value を連結します。

戻り値の型

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)

説明

2 つの value を取ります。2 番目の value が最初の value の接尾辞である場合、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+
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> 式には、ゼロ以上の形式指定子を含めることができます。各形式指定子は % 記号によって導入され、残りの 1 つ以上の引数にマップする必要があります。大部分でこれは 1 対 1 のマッピングになりますが、* 指定子がある場合のみ異なります。たとえば、%.*i は、長さ引数と符号付き整数引数という 2 つの引数にマップします。形式指定子に関連する引数の数が、これらの引数の数と異なる場合、エラーが発生します。

サポートされる形式指定子

FORMAT() 関数の形式指定子は、次のプロトタイプに従います。

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

次の表にサポートされる形式指定子が示されています。printf() からの拡張子はイタリック体で示されています。

指定子 説明
d または i 10 進の整数 392 INT64
o 8 進数 610
INT64*
x 16 進の整数 7fa
INT64*
X 16 進の整数(大文字) 7FA
INT64*
f 10 進の浮動小数点数(小文字) 392.65
inf
NaN

FLOAT64
F 10 進の浮動小数点数(大文字) 392.65
inf
NAN

FLOAT64
e 科学的記数法(仮数/指数)(小文字) 3.9265e+2
inf
NaN

FLOAT64
E 科学的記数法(仮数/指数)(大文字) 3.9265E+2
inf
NAN

FLOAT64
g 最短の表記 %e または %f を使用します 392.65
FLOAT64
G 最短の表記 %E または %F を使用します 392.65
FLOAT64
s 文字列 sample STRING
t 値を表す印刷可能な文字列を返します。多くの場合、引数を STRING にキャストするのに似ています。後述の %t セクションをご覧ください。 sample
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 を返します
  • このフラグは、10 進数、16 進数、および 8 進数の値のみが対象になります。

フラグは任意の順序で指定できます。フラグを重複して使用しても、エラーになりません。なんらかの要素タイプにフラグが関連しない場合、それらは無視されます。

説明
<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 リテラルになります。非定形の浮動小数点値の特殊なケースを除き、リテラルには CAST または型名は含まれません。

STRING は次のように形式設定されます。

タイプ %t %T
任意の型の NULL NULL NULL
INT64
123 123
FLOAT64 123.0(常に .0 が付く)
123e+10
inf
-inf
NaN
123.0(常に .0 が付く)
123e+10
CAST("inf" AS <type>)
CAST("-inf" AS <type>)
CAST("nan" AS <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 [value, value, ...]
値は %t で形式設定される
[value, value, ...]
値は %T で形式設定される
STRUCT (value, value, ...)
フィールドは %t で形式設定される
(value, value, ...)
フィールドは %T で形式設定される

特殊なケース:
ゼロフィールド: STRUCT()
1 フィールド: STRUCT(value)

エラー条件

形式指定子が無効な場合や関連する引数型と互換性がない場合、あるいは間違った数や引数が指定されている場合、エラーが出ます。たとえば、次の <format_string> 式は無効です。

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

NULL 引数の処理

NULL 形式文字列は NULL 出力 STRING になります。この場合、その他の引数はすべて無視されます。

NULL 引数がある場合、通常、関数によって NULL 値が生成されます。たとえば、FORMAT('%i', <NULL expression>) では出力として NULL が生成されます。

ただし、形式設定子が %t または %T である場合(これらはどちらも実際上 CAST とリテラル値セマンティックと一致する STRING を生成する)、NULL 値によって結果の STRING 内に 'NULL'(引用符なし)が生成されます。たとえば、次の関数の場合、

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

戻り値

00-NULL-00

その他のセマンティック ルール

FLOAT64 は +/-inf または NaN にすることができます。引数にこれらのいずれかの値が含まれている場合、形式指定子 %f%F%e%E%g%G および %t の結果は、必要に応じて inf-inf または nan(または同じ文字の大文字)になります。これは、BigQuery がこれらの値を STRING にキャストする動作と整合します。%T の場合、BigQuery は文字列ではないリテラル表記を持たない FLOAT64 値に対して符号付きの文字列を返します。

FROM_BASE64

FROM_BASE64(string_expr)

説明

Base-64 でエンコードされた入力 string_expr を BYTES 形式に変換します。BYTES を Base-64 でエンコードされた文字列に変換するには、TO_BASE64() を使用します。

戻り値の型

BYTES

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

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

FROM_HEX

FROM_HEX(string)

説明

16 進数でエンコードされた STRING を BYTES 形式に変換します。入力 STRING に次の範囲外の文字が含まれている場合、エラーを返します。(0..9, A..F, a..f)。文字の大文字と小文字は区別されません。BYTES を 16 進数でエンコードされた 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)

説明

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])

説明

original_value の前に pattern を付加したを返します。return_length は、戻り値の長さを指定する INT64 です。original_value が BYTES の場合、return_length はバイト数になります。original_value が STRING の場合、return_length 文字数です。

pattern のデフォルト値は空白です。

original_valuepattern は同じデータ型にする必要があります。

return_lengthoriginal_value 以下の場合、この関数は return_length の値まで切り捨てて original_value 値を返します。たとえば、LPAD("hello world", 7);"hello w" を返します。

original_valuereturn_length または pattern が 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 をとり、正規化された文字列として返します。

正規化は、2 つの文字列を同等にするために使用されます。正規化は、2 つの文字列が画面上で同じように表示され、異なる Unicode コードポイントを持つ状況でよく使用されます。

NORMALIZE は、4 つのオプション正規化モードをサポートしています。

名前 説明
NFC 正規化形式 C 標準的な同値によって文字を分解し、再構成する。
NFKC 正規化形式 KC 互換性によって文字を分解し、標準的な同値によって再構成する。
NFD 正規化形式 D 標準的な同値によって文字を分解し、複数の結合文字を特定の順序で並べる。
NFKD 正規化形式 KD 互換性によって文字を分解し、複数の結合文字を特定の順序で並べる。

デフォルトの正規化モードは 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 は、4 つのオプション正規化モードをサポートしています。

名前 説明
NFC 正規化形式 C 標準的な同値によって文字を分解し、再構成する。
NFKC 正規化形式 KC 互換性によって文字を分解し、標準的な同値によって再構成する。
NFD 正規化形式 D 標準的な同値によって文字を分解し、複数の結合文字を特定の順序で並べる。
NFKD 正規化形式 KD 互換性によって文字を分解し、複数の結合文字を特定の順序で並べる。

デフォルトの正規化モードは 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 $.
SELECT
  email,
  REGEXP_CONTAINS(email, r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$")
    AS valid_email_address
FROM
  (SELECT
    ["foo@example.com", "bar@example.org", "www.example.net"]
    AS addresses),
  UNNEST(addresses) AS email;

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

REGEXP_EXTRACT

REGEXP_EXTRACT(value, regex)

説明

正規表現 regex と一致する value 内の最初の部分文字列を返します。一致がない場合、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)

説明

正規表現 value と一致する regex のすべての部分文字列の配列を返します。

REGEXP_EXTRACT_ALL 関数は、重複しない一致のみを返します。たとえば、この関数を使用して anabanana から抽出した場合、返される部分文字列は 2 つではなく、1 つのみです。

注: 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)

説明

正規表現 value と一致する regex のすべての部分文字列が replacement で置き換えられて、STRING が返されます。

バックスラッシュ エスケープ数字(\1~\9)を replacement 引数内で使用し、regex パターン内の対応する括弧で囲まれたグループに一致するテキストを挿入できます。一致するテキスト全体を参照するには、\0 を使用します。

注: 正規表現にバックスラッシュを追加するには、あらかじめエスケープしておく必要があります。たとえば、SELECT REGEXP_REPLACE("abc", "b(.)", "X\\1");aXc を返します。

REGEXP_REPLACE 関数は、重複しない一致のみを置き換えます。たとえば、ana 内の banana を置き換えた場合、置き換えられるのは 2 つではなく、1 つのみです。

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 ですべての from_valueto_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_value または repetitions のいずれかが 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 REPEAT
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])

説明

original_value の後に pattern を付加したを返します。return_length は、戻り値の長さを指定する INT64 です。original_value が BYTES の場合、return_length はバイト数になります。original_value が STRING の場合、return_length 文字数です。

pattern のデフォルト値は空白です。

original_valuepattern は同じデータ型にする必要があります。

return_lengthoriginal_value 以下の場合、この関数は return_length の値まで切り捨てて original_value 値を返します。たとえば、RPAD("hello world", 7);"hello w" を返します。

original_valuereturn_length または pattern が 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 pattern 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 pattern 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])

説明

value 引数を使用して delimiter を分割します。

STRING の場合、デフォルトの区切り文字はカンマ(,)です。

BYTES の場合、区切り文字を指定する必要があります。

空の区切り文字で分割すると、STRING 値の場合は UTF-8 文字の配列が生成され、BYTES 値の場合は BYTES の配列が生成されます。

空の STRING を分割すると、1 つの空の STRING で ARRAY を返します。

戻り値の型

STRING 型の 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)

説明

2 つの value を取ります。2 番目の値が 1 番目の接頭辞である場合に 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])

説明

提供された value の部分文字列を返します。position 引数は、部分文字列の最初の文字またはバイトを指定する整数であり、position = 1 は最初の文字またはバイトを指します。length 引数は、STRING 引数では文字、または BYTES 引数ではバイトの最大数です。

position が負の場合、この関数は value の後ろからカウントします。-1 は最後の文字を指します。

position が STRING の左側にある場合(position = 0 または position < -LENGTH(value))、この関数は position = 1 から開始します。lengthvalue の長さを超える場合は、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_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)

説明

value をとって、INT64 の配列を返します。

  • value が STRING の場合、返される配列の各要素はコードポイントを示します。各コードポイントは、[0, 0xD7FF] から [0xE000, 0x10FFFF] の範囲になります。
  • value が BYTES の場合は、配列内の各要素は拡張 ASCII 文字の値で、範囲は [0, 255] になります。

コードポイントの配列を 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]    |
+------------+----------+

Ā の文字が 2 バイトの Unicode で示されていることにご注意ください。この結果として、BYTES バージョンの TO_CODE_POINTS が 2 つの要素を返し、STRING バージョンは 1 つの要素の配列を返しています。

TO_HEX

TO_HEX(bytes)

説明

BYTES のシーケンスを 16 進 STRING に変換します。STRING の各バイトを範囲(0..9, a..f) 内の 2 つの 16 進文字に変換します。16 進数でエンコードされた 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 である場合、2 番目の引数は必須です。

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) は、JSON 値を STRING として返します。

JSON_EXTRACT_SCALAR(json_string_expr, json_path_string_literal) は、スカラー JSON 値を STRING として返します。

説明

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              |
| {"first":"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 true または false
INT64

value が [-253, 253] の範囲内にある場合は、CAST(value AS STRING) と同じです。この範囲は IEEE 754 倍精度浮動小数点数としてロスレスで表現できる整数の範囲です。この範囲外となる値は、引用符付きの文字列で表されます。例:

-1
0
12345678901
9007199254740992
-9007199254740992
"9007199254740993"

9007199254740993 は 253 より大きいため、引用符付きの文字列として表されます。

FLOAT64 +/-inf および NaN は、それぞれ Infinity-Infinity、および NaN として表されます。

それ以外の場合は、CAST(value AS STRING) と同じです。

STRING 引用符付きの文字列値。JSON 標準に従ってエスケープされます。具体的には "\ で、U+0000 から U+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 の場合、要素は適切なレベルにインデントされます。空の STRUCT は {} と表されます。

名前が重複しているフィールドは、JSON で解析できなくなる可能性があります。匿名のフィールドは "" と表されます。

無効な UTF-8 フィールド名は、JSON で解析できなくなる可能性があります。文字列値は、JSON 標準に従ってエスケープされます。具体的には "\ で、U+0000 から U+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 関数は、サブクエリの各行に対して 1 つの要素を含む ARRAY を返します。

subquery によって標準 SQL テーブルが生成される場合、テーブルの列数は厳密に 1 つである必要があります。出力 ARRAY の各要素は、テーブルの行の単一列の値です。

subquery によって値テーブルが生成される場合、出力 ARRAY の各要素は、値テーブルの対応する行全体となります。

制約

  • サブクエリは順序付けされていないため、出力 ARRAY の要素は、サブクエリのソーステーブルの順序を保証するものではありません。ただし、サブクエリに ORDER BY 句が含まれている場合、ARRAY 関数はその句を使用する ARRAY を返します。
  • サブクエリが複数の列を返す場合、ARRAY 関数はエラーを返します。
  • サブクエリが、ARRAY 型の列または ARRAY 型の行を返す場合、ARRAY 関数は、「BigQuery は型 ARRAY の要素を含む ARRAY はサポートしていない」というエラーを返します。
  • サブクエリがゼロ行を返す場合、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 関数は STRUCTARRAY を返します。ARRAY では、サブクエリの各行に 1 つの 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}] |
+------------------------+

同様に、1 つ以上の 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])

説明

同じ要素型の 1 つまたは複数の配列を 1 つの配列に連結します。

戻り値の型

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
  • 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_expressionend_expression よりも大きく、step_expression が正の値であるため、空の配列を返します。

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

+---------------+
| example_array |
+---------------+
| []            |
+---------------+

end_expressionNULL であるため、以下は NULL 配列を返します。

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 値が含まれている配列。

以下の場合、日付の配列を返します。デフォルトのステップは 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_dateend_date よりも大きく、step が正の値であるため、空の配列を返します。

SELECT GENERATE_DATE_ARRAY('2016-10-05',
  '2016-10-01', INTERVAL 1 DAY) AS example;

+---------+
| example |
+---------+
| []      |
+---------+

以下の場合、入力値の 1 つが NULL であるため、NULL の配列を返します。

SELECT GENERATE_DATE_ARRAY('2016-10-05', NULL) AS example;

+---------+
| example |
+---------+
| NULL    |
+---------+

以下の場合、date_part の間隔に MONTH を使用して、日付の配列を返します。

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] |
+--------------------------------------------------------------+

OFFSET と ORDINAL

array_expression[OFFSET(zero_based_offset)]
array_expression[ORDINAL(one_based_offset)]

説明

位置によって ARRAY 要素にアクセスし、その要素を返します。OFFSET は番号付けがゼロから始まることを意味し、ORDINAL は番号付けが 1 から始まることを意味します。

指定した配列は、0 ベースまたは 1 ベースのいずれかとして解釈できます。配列要素にアクセスする場合、配列位置の前に OFFSET または ORDINAL をそれぞれ入れる必要があります。デフォルトの動作はありません。

インデックスが範囲外の場合、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)]

説明

OFFSETORDINAL と同じですが、インデックスが範囲外の場合に 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

次の例では、EXTRACTDAY 時間部分に対応する値を返します。

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 は、日曜日から始まる週を使用して最初の列を計算し、月曜日から始まる週を使用して 2 番目の列を計算します。

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. 年、月、および日を表す DATE を INT64 値から構築します。
  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)

説明

2 つの date_expression の間にある date_part 境界の数を返します。最初の日付が 2 番目の日付よりも前にある場合、結果は負以外の値になります。

DATE_DIFF は、次の date_part 値をサポートしています。

  • DAY
  • WEEK: この日付パーツは日曜日から始まります。
  • 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          |
+-----------+------------+

上記の例は、2 つの日付に対する DATE_DIFF の結果を連続して示しています。 DATE_DIFF は、これらの日付の範囲内で日付パーツの境界の数をカウントするため、日付パーツ WEEK が指定された DATE_DIFF は 1 を返します。各 WEEK は日曜日から始まるため、2017 年 10 月 14 日土曜日と 2017 年 10 月 15 日日曜日の間には日付パーツの境界が 1 つあります。

次の例は、異なる年の 2 つの日付に対する DATE_DIFF の結果を示しています。日付パーツ YEAR が指定された DATE_DIFF は、2 つの日付間のグレゴリオ暦年の境界の数をカウントするため、3 を返します。2 番目の日付は ISO 基準の 2015 年に属しているため、日付パーツ ISOYEAR が指定された DATE_DIFF は 2 を返します。2015 年の最初の木曜日が 2015 年 1 月 1 日であったため、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            |
+-----------+--------------+

次の例は、2 つの日付に対する DATE_DIFF の結果を連続して示しています。最初の日付は月曜日で、2 番目の日付は日曜日になります。この時間パーツは日曜日から始まる週を使用するため、日付パーツ WEEK が指定された DATE_DIFF は 0 を返します。ISO 週は月曜日から始まるため、日付パーツ ISOWEEK が指定された DATE_DIFF は 1 を返します。

SELECT
  DATE_DIFF('2017-12-18', '2017-12-17', WEEK) AS week_diff,
  DATE_DIFF('2017-12-18', '2017-12-17', ISOWEEK) AS isoweek_diff;

+-----------+--------------+
| week_diff | isoweek_diff |
+-----------+--------------+
| 0         | 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_expressionISO 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 年 1 月 1 日であったため、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 などの名前は、大文字と小文字が区別されません。
  • 空白文字。 形式設定文字列内の 1 つ以上の連続する空白文字は、日付文字列内のゼロ以上の連続する空白文字と同じです。また、日付文字列内の先頭および末尾の空白文字は、それらが形式設定文字列内にない場合でも常に許可されます。
  • 形式設定の優先度。 2 つ(またはそれ以上)の形式設定要素が重複する情報を持つ場合(たとえば、%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 10 進数として表示される世紀(年を 100 で割って、整数値になるよう切り捨てる)(00~99)。
%D %m/%d/%y 形式の日付。
%d 10 進数として表示される、月内の日付(01~31)。
%e 10 進数として表示される、月内の日付(1~31)。1 桁の場合は前にスペースが入れられます。
%F %Y-%m-%d 形式の日付。
%G 10 進数として表示される、世紀を含む ISO 8601 年。
%g 10 進数として表示される、世紀を含まない ISO 8601 年(00~99)。
%j 10 進数として表示される、年内の日付(001~366)。
%m 10 進数として表示される月(01~12)。
%n 改行文字。
%t タブ文字。
%U 10 進数として表示される、年内の週番号(週の 1 日目が日曜日)(00~53)。
%u 10 進数として表示される曜日(週の 1 日目が月曜日)(1~7)。
%V 10 進数として表示される、年内の週番号(週の 1 日目が月曜日)(01~53)。新しい年の 1 月 1 日を含む週に 4 日以上の日数がある場合、その週は week 1 になります。それ以外の場合、その週は前の年の week 53 になり、次の週が新しい年の week 1 になります。
%W 10 進数として表示される、年内の週番号(週の 1 日目が月曜日)(00~53)。
%w 10 進数として表示される曜日(週の 1 日目が日曜日)(0~6)。
%x MM/DD/YY 形式の日付表記。
%Y 10 進数として表示される、世紀を含む年。
%y 10 進数として表示される、世紀を含まない年(00~99)。オプションの先頭ゼロを使用します。%C と混在できます。%C が指定されていない場合、年 00~68 は 2000 年代になり、年 69~99 は 1900 年代になります。
%E4Y 4 文字の年(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)

説明

DATETIME オブジェクトに partINT64_expr 単位を追加します。

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 から INT64_exprpart 単位を差し引きます。

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)

説明

2 つの datetime_expression の間にある part の境界の数を返します。最初の DATETIME が 2 番目の DATETIME よりも前にある場合、結果は正以外の値になります。計算によって得られた型がオーバーフローする場合、エラーをスローします。たとえば、2 つの DATETIME オブジェクト間のマイクロ秒単位の差異が INT64 値をオーバーフローする場合などです。

DATETIME_DIFF は、part に対して次の値をサポートしています。

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR
  • DAY
  • WEEK: この日付パーツは日曜日から始まります。
  • 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 時間離れている 2 つの DATETIME に対する DATETIME_DIFF の結果を示しています。DATETIME_DIFF は、これらの DATETIME の範囲内でパーツの境界の数をカウントするため、パーツ WEEK が指定された DATETIME_DIFF は 1 を返します。各 WEEK は日曜日から始まるため、2017-10-14 00:00:00 土曜日と 2017-10-15 00:00:00 日曜日の間にはパーツの境界が 1 つあります。

次の例は、異なる年の 2 つの日付に対する DATETIME_DIFF の結果を示しています。日付パーツ YEAR が指定された DATETIME_DIFF は、2 つの DATETIME 間のグレゴリオ暦年の境界の数をカウントするため、3 を返します。2 番目の DATETIME は ISO 基準の 2015 年に属しているため、日付パーツ ISOYEAR が指定された DATETIME_DIFF は 2 を返します。2015 年の最初の木曜日が 2015 年 1 月 1 日であったため、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            |
+-----------+--------------+

次の例は、2 つの日付に対する DATETIME_DIFF の結果を連続して示しています。最初の日付は月曜日で、2 番目の日付は日曜日になります。この時間パーツは日曜日から始まる週を使用するため、日付パーツ WEEK が指定された DATETIME_DIFF は 0 を返します。ISO 週は月曜日から始まるため、日付パーツ ISOWEEK が指定された DATETIME_DIFF は 1 を返します。

SELECT
  DATETIME_DIFF('2017-12-18', '2017-12-17', WEEK) AS week_diff,
  DATETIME_DIFF('2017-12-18', '2017-12-17', ISOWEEK) AS isoweek_diff;

+-----------+--------------+
| week_diff | isoweek_diff |
+-----------+--------------+
| 0         | 1            |
+-----------+--------------+

DATETIME_TRUNC

DATETIME_TRUNC(datetime_expression, part)

説明

part の粒度で DATETIME オブジェクトを切り詰めます。

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_expressionISO 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 年 1 月 1 日であったため、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 および文字列表記を使用して、TIMESTAMP オブジェクトを返します。この関数でサポートされる形式設定要素のリストについては、DATETIME でサポートされる形式設定要素をご覧ください。

PARSE_DATETIME を使用する場合、次の点に注意してください。

  • 指定されていないフィールド。 指定されていないフィールドはすべて、1970-01-01 00:00:00.0 から初期設定されます。たとえば、年が指定されていない場合、デフォルトで 1970 に設定されます。
  • 大文字と小文字の区別がない名前。 MondayFebruary などの名前は、大文字と小文字が区別されません。
  • 空白文字。 形式設定文字列内の 1 つ以上の連続する空白文字は、DATETIME 文字列内のゼロ以上の連続する空白文字と同じです。また、DATETIME 文字列内の先頭および末尾の空白文字は、それらが形式設定文字列内にない場合でも常に許可されます。
  • 形式設定の優先度。 2 つ以上の形式設定要素に重複する情報がある場合(たとえば、%F%Y の両方が年に影響を及ぼす場合など)、一部の例外を除き、最後の設定によって前の設定がオーバーライドされます(%s%C、および %y の説明を参照)。

戻りデータの型

DATETIME

DATETIME に使用できる形式設定要素

特に指定されていない限り、形式設定文字列を使用する DATETIME 関数は次の要素をサポートします。

形式設定要素 説明
%A 完全な曜日名。
%a 省略された曜日名。
%B 完全な月の名前。
%b または %h 省略された月の名前。
%C 10 進数として表示される世紀(年を 100 で割って、整数値になるよう切り捨てる)(00~99)。
%c 日付および時刻の表記。
%D %m/%d/%y 形式の日付。
%d 10 進数として表示される、月内の日付(01~31)。
%e 10 進数として表示される、月内の日付(1~31)。1 桁の場合は前にスペースが入れられます。
%F %Y-%m-%d 形式の日付。
%G 10 進数として表示される、世紀を含む ISO 8601 年。
%g 10 進数として表示される、世紀を含まない ISO 8601 年(00~99)。
%H 10 進数で表示される時間(24 時間制)(00~23)。
%I 10 進数で表示される時間(12 時間制)(00~12)。
%j 10 進数として表示される、年内の日付(001~366)。
%k 10 進数として表示される時間(24 時間制)(0~23)。1 桁の場合は前にスペースが入れられます。
%l 10 進数として表示される時間(12 時間制)(1~12)。1 桁の場合は前にスペースが入れられます。
%M 10 進数として表示される分(00~59)。
%m 10 進数として表示される月(01~12)。
%n 改行文字。
%P am または pm のいずれか。
%p AM または PM のいずれか。
%R %H:%M 形式の時刻。
%r AM/PM 表記を使用する 12 時間制の時刻。
%S 10 進数として表示される分(00~60)。
%s 1970 年 1 月 1 日 00:00:00 からの秒数。文字列内に示される %s の位置とは無関係に、形式要素を常に上書きします。複数の %s 要素が使用されている場合、最後のものが優先されます。
%T %H:%M:%S 形式の時刻。
%t タブ文字。
%U 10 進数として表示される、年内の週番号(週の 1 日目が日曜日を週)(00~53)。
%u 10 進数として表示される曜日(週の 1 日目が月曜日)(1~7)。
%V 10 進数として表示される、年内の週番号(週の 1 日目が月曜日)(01~53)。新しい年の 1 月 1 日を含む週に 4 日以上の日数がある場合、その週は week 1 になります。それ以外の場合、その週は前の年の week 53 になり、次の週が新しい年の week 1 になります。
%W 10 進数として表示される、年内の週番号(週の 1 日目が月曜日)(00~53)。
%w 10 進数として表示される曜日(週の 1 日目が日曜日)(0~6)。
%X HH:MM:SS 形式の時刻表記。
%x MM/DD/YY 形式の日付表記。
%Y 10 進数として表示される、世紀を含む年。
%y 10 進数として表示される、世紀を含まない年(00~99)。オプションの先頭ゼロを使用します。%C と混在できます。%C が指定されていない場合、年 00~68 は 2000 年代になり、年 69~99 は 1900 年代になります。
%% 単一の % 文字。
%E#S 小数第 # 位の精度で示される秒。
%E*S 完全な小数の精度で示される秒(リテラル '*')。
%E4Y 4 文字の年(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)

説明

INT64_exprpart 単位を TIME オブジェクトに追加します。

TIME_ADD は、part に対して次の値をサポートしています。

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR

この関数は、値が 00:00:00 から 24:00:00 の外にある場合に自動調整します。たとえば、23:30:00 に 1 時間を追加すると、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 オブジェクトから INT64_exprpart 単位を減算します。

TIME_SUB は、part に対して次の値をサポートしています。

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR

この関数は、値が 00:00:00 から 24:00:00 の外にある場合に自動調整します。たとえば、00:30:00 から 1 時間を減算すると、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)

説明

2 つの TIME オブジェクト間の、全体が指定された part の間隔を示す数を返します。計算によって得られた型がオーバーフローする場合、エラーをスローします。たとえば、2 つの TIME オブジェクト間のマイクロ秒単位の差異が 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)

説明

part の粒度で TIME オブジェクトを切り詰めます。

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 が使用されます。
  • 空白文字。 形式設定文字列内の 1 つ以上の連続する空白文字は、TIME 文字列内のゼロ以上の連続する空白文字と同じです。また、TIME 文字列内の先頭および末尾の空白文字は、それらが形式設定文字列内にない場合でも常に許可されます。
  • 形式設定の優先度。 2 つ以上の形式設定要素に重複する情報がある場合、最後の設定によって前の設定がオーバーライドされます。

戻りデータの型

TIME

SELECT PARSE_TIME("%H", "15") as parsed_time;

+-------------+
| parsed_time |
+-------------+
| 15:00:00    |
+-------------+

TIME に使用できる形式設定要素

特に指定されていない限り、形式設定文字列を使用する TIME 関数は次の要素をサポートします。

形式設定要素 説明
%H 10 進数で表示される時間(24 時間制)(00~23)。
%I 10 進数で表示される時間(12 時間制)(00~12)。
%j 10 進数として表示される、年内の日付(001~366)。
%k 10 進数として表示される時間(24 時間制)(0~23)。1 桁の場合は前にスペースが入れられます。
%l 10 進数として表示される時間(12 時間制)(1~12)。1 桁の場合は前にスペースが入れられます。
%M 10 進数として表示される分(00~59)。
%n 改行文字。
%P am または pm のいずれか。
%p AM または PM のいずれか。
%R %H:%M 形式の時刻。
%r AM/PM 表記を使用する 12 時間制の時刻。
%S 10 進数として表示される分(00~60)。
%T %H:%M:%S 形式の時刻。
%t タブ文字。
%X HH:MM:SS 形式の時刻表記。
%% 単一の % 文字。
%E#S 小数第 # 位の精度で示される秒。
%E*S 完全な小数の精度で示される秒(リテラル '*')。

タイムスタンプ関数

BigQuery は、以下の TIMESTAMP 関数をサポートします。

注: オーバーフローが生じると、これらの関数によってランタイム エラーが返されます。結果の値は定義済みの日付とタイムスタンプの最小 / 最大値によって制限されます。

CURRENT_TIMESTAMP

CURRENT_TIMESTAMP()

説明

括弧は省略可能です。この関数は、挿入されたうるう秒の前後 20 時間にわたってうるう秒を分散することで、うるう秒を処理します。 CURRENT_TIMESTAMP() は、連続し、明確であり、1 分あたり正確に 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 から指定された part に対応する INT64 値を返します。

使用可能な 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 はミリ秒とマイクロ秒の値を切り捨てます。

タイムゾーンの指定方法の詳細については、タイムゾーンの定義をご覧ください。

戻りデータの型

通常、INT64partDATE の場合、DATE が返されます。

次の例では、EXTRACTDAY 時間部分に対応する値を返します。

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 は、日曜日から始まる週を使用して最初の列を計算し、月曜日から始まる週を使用して 2 番目の列を計算します。

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)

説明

2 つのタイムスタンプ間の、全体が指定された date_part の間隔を示す数を返します。計算によって得られた型がオーバーフローする場合、エラーをスローします。たとえば、2 つのタイムスタンプの間のマイクロ秒単位の差異が INT64 値をオーバーフローする場合などです。

TIMESTAMP_DIFF は、date_part に対して次の値をサポートしています。

  • MICROSECOND
  • MILLISECOND
  • SECOND
  • MINUTE
  • HOUR。60 MINUTE と等価。

戻りデータの型

INT64

SELECT
  TIMESTAMP "2010-07-07 10:20:00 UTC" as first_timestamp,
  TIMESTAMP "2008-12-25 15:30:00 UTC" as second_timestamp,
  TIMESTAMP_DIFF(TIMESTAMP "2010-07-07 10:20:00 UTC",
    TIMESTAMP "2008-12-25 15:30:00 UTC", HOUR) AS hours;

+------------------------+------------------------+-------+
| first_timestamp        | second_timestamp       | hours |
+------------------------+------------------------+-------+
| 2010-07-07 10:20:00+00 | 2008-12-25 15:30:00+00 | 13410 |
+------------------------+------------------------+-------+

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_expressionISO 8601 週番号が付けられた前の年の境界に切り詰めます。ISO 年の境界は、木曜日が対応するグレゴリオ暦年に属している最初の週の月曜日です。

TIMESTAMP_TRUNC 関数はオプションの time_zone パラメータをサポートします。このパラメータは次の date_parts に適用されます。

  • MINUTE
  • HOUR
  • DAY
  • WEEK
  • WEEK(<WEEKDAY>)
  • MONTH
  • QUARTER
  • YEAR

このパラメータは、デフォルトのタイムゾーン UTC 以外のタイムゾーンを切り詰めオペレーションの一部として使用する場合に使用します。

戻りデータの型

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 が表示されています。2 番目の列には、月曜日から始まる週を使用した TIMESTAMP_TRUNC の出力が表示されています。timestamp_expression は UTC では日曜日になるため、TIMESTAMP_TRUNC はそれを前の月曜日に切り詰めます。3 番目の列には、オプションのタイムゾーン定義引数の 'Pacific/Auckland' が指定された同じ関数が表示されています。この関数は、ニュージーランド夏時間を使用して 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 年 1 月 1 日であったため、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 などの名前は、大文字と小文字が区別されません。
  • 空白文字。 形式設定文字列内の 1 つ以上の連続する空白文字は、タイムスタンプ文字列内のゼロ以上の連続する空白文字と同じです。また、タイムスタンプ文字列内の先頭および末尾の空白文字は、それらが形式設定文字列内にない場合でも常に許可されます。
  • 形式設定の優先度。 2 つ以上の形式設定要素に重複する情報がある場合(たとえば、%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)

説明

1970-01-01 00:00:00 UTC 以降の秒数として int64_expression を解釈します。

戻りデータの型

TIMESTAMP

SELECT TIMESTAMP_SECONDS(1230219000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_MILLIS

TIMESTAMP_MILLIS(int64_expression)

説明

1970-01-01 00:00:00 UTC 以降のミリ秒数として int64_expression を解釈します。

戻りデータの型

TIMESTAMP

SELECT TIMESTAMP_MILLIS(1230219000000) as timestamp;

+-------------------------+
| timestamp               |
+-------------------------+
| 2008-12-25 15:30:00 UTC |
+-------------------------+

TIMESTAMP_MICROS

TIMESTAMP_MICROS(int64_expression)

説明

1970-01-01 00:00:00 UTC 以降のマイクロ秒数として int64_expression を解釈します。

戻りデータの型

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 10 進数として表示される世紀(年を 100 で割って、整数値になるよう切り捨てる)(00~99)。
%c 日付および時刻の表記。
%D %m/%d/%y 形式の日付。
%d 10 進数として表示される、月内の日付(01~31)。
%e 10 進数として表示される、月内の日付(1~31)。1 桁の場合は前にスペースが入れられます。
%F %Y-%m-%d 形式の日付。
%G 10 進数として表示される、世紀を含む ISO 8601 年。
%g 10 進数として表示される、世紀を含まない ISO 8601 年(00~99)。
%H 10 進数で表示される時間(24 時間制)(00~23)。
%I 10 進数で表示される時間(12 時間制)(00~12)。
%j 10 進数として表示される、年内の日付(001~366)。
%k 10 進数として表示される時間(24 時間制)(0~23)。1 桁の場合は前にスペースが入れられます。
%l 10 進数として表示される時間(12 時間制)(1~12)。1 桁の場合は前にスペースが入れられます。
%M 10 進数として表示される分(00~59)。
%m 10 進数として表示される月(01~12)。
%n 改行文字。
%P am または pm のいずれか。
%p AM または PM のいずれか。
%R %H:%M 形式の時刻。
%r AM/PM 表記を使用する 12 時間制の時刻。
%S 10 進数として表示される分(00~60)。
%s 1970-01-01 00:00:00 UTC 以降の秒数。文字列内で %s が使用されている場所に関係なく、その他のすべての形式設定要素を常にオーバーライドします。複数の %s 要素が使用されている場合、最後のものが優先されます。
%T %H:%M:%S 形式の時刻。
%t タブ文字。
%U 10 進数として表示される、年内の週番号(週の 1 日目が日曜日を週)(00~53)。
%u 10 進数として表示される曜日(週の 1 日目が月曜日)(1~7)。
%V 10 進数として表示される、年内の週番号(週の 1 日目が月曜日)(01~53)。新しい年の 1 月 1 日を含む週に 4 日以上の日数がある場合、その週は week 1 になります。それ以外の場合、その週は前の年の week 53 になり、次の週が新しい年の week 1 になります。
%W 10 進数として表示される、年内の週番号(週の 1 日目が月曜日)(00~53)。
%w 10 進数として表示される曜日(週の 1 日目が日曜日)(0~6)。
%X HH:MM:SS 形式の時刻表記。
%x MM/DD/YY 形式の日付表記。
%Y 10 進数として表示される、世紀を含む年。
%y 10 進数として表示される、世紀を含まない年(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 4 文字の年(0001 ... 9999)。%Y によって、年を完全に表現するために必要な数の文字が生成されます。

タイムゾーンの定義

特定の日付およびタイムスタンプ関数を使用して、デフォルトのタイムゾーンをオーバーライドし、別の値を指定できます。次の形式を使用し、UTC オフセットを指定してタイムゾーンを指定できます。

(+|-)H[H][:M[M]]

次に例を示します。

-08:00

セキュリティ関数

BigQuery は、次のセキュリティ関数をサポートしています。

SESSION_USER

SESSION_USER()

説明

クエリを実行しているユーザー全員のメールアドレスを返します。

戻りデータの型

STRING

SELECT SESSION_USER() as user;

+----------------------+
| user                 |
+----------------------+
| jdoe@example.com     |
+----------------------+

Net 関数

NET.IP_FROM_STRING

NET.IP_FROM_STRING(addr_str)

説明

IPv4 または IPv6 アドレスをネットワーク バイト順でテキスト形式(STRING)からバイナリ形式(BYTES)に変換します。

この関数は、addr_str で次の形式をサポートします。

この関数は、10.1.2.3/32 のような CIDR 表記をサポートしていません。

この関数は、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 バイトの場合、この関数は IPv4 アドレスを STRING として返します。入力が 16 バイトの場合、IPv6 アドレスを STRING として返します。

この関数は、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)

説明: IPv4 または IPv6 アドレスをネットワーク バイト順のバイナリ形式(BYTES)で表した addr_bin を取り、同じ形式でサブネット アドレスを返します。結果の長さは 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 アドレスの最下位ビットが整数の最下位ビットに保存されます。たとえば、10.0.0.1 を意味し、0x1FF0.0.1.255 を意味します。

この関数は、最上位の 32 ビットがすべて 0 またはすべて 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 アドレスの最下位ビットが整数の最下位ビットに保存されます。たとえば、10.0.0.1 を意味し、0x1FF0.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)

説明

URL を STRING として取得し、ホストを STRING として返します。最適な結果を得るには、URL 値を RFC 3986 で定義されている形式に一致させる必要があります。URL 値が 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.Google.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" 標準の URL "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" 相対スキーム、ポート、パス、クエリを含む標準の URL。ただし、パブリック サフィックスはありません。 "a.b" NULL NULL
"https://[::1]:80" IPv6 ホスト付きの標準 URL "[::1]" NULL NULL
"http://例子.卷筒纸.中国" 国際化ドメイン名付きの標準 URL "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Google.Co.UK    " スペース、大文字を含み、スキームのない非標準 URL "www.Google.Co.UK" "Co.UK" "Google.Co.UK"
"mailto:?to=&subject=&body=" URL ではなく URI(サポート対象外) "mailto" NULL NULL

NET.PUBLIC_SUFFIX

NET.PUBLIC_SUFFIX(url)

説明

STRING の URL を受け取り、パブリック サフィックス(comorgnet など)を STRING として返します。パブリック サフィックスは、publicsuffix.org に登録されている ICANN ドメインです。最適な結果を得るには、URL 値を RFC 3986 で定義されている形式に一致させる必要があります。URL 値が RFC 3986 の形式設定に準拠していない場合、この関数は入力を解析し、関連する結果を返すために最善の努力を行います。

次の条件を満たす場合、この関数は NULL を返します。

  • 入力からホストを解析できない。
  • 解析したホストで、先頭または末尾以外の場所でドットが連続している。
  • 解析したホストにパブリック サフィックスが含まれていない。

パブリック サフィックスを検索する前に、この関数はホストを一時的に正規化します。大文字の英字を小文字に変換し、ASCII 以外の文字を Punycode でエンコードします。 次に、正規化されたホストではなく、元のホストの一部としてパブリック サフィックスを返します。

注: この関数は 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.Google.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" 標準の URL "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" 相対スキーム、ポート、パス、クエリを含む標準の URL。ただし、パブリック サフィックスはありません。 "a.b" NULL NULL
"https://[::1]:80" IPv6 ホスト付きの標準 URL "[::1]" NULL NULL
"http://例子.卷筒纸.中国" 国際化ドメイン名付きの標準 URL "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Google.Co.UK    " スペース、大文字を含み、スキームのない非標準 URL "www.Google.Co.UK" "Co.UK" "Google.Co.UK"
"mailto:?to=&subject=&body=" URL ではなく URI(サポート対象外) "mailto" NULL NULL

NET.REG_DOMAIN

NET.REG_DOMAIN(url)

説明

STRING の URL を受け取り、登録済みまたは登録可能なドメイン(1 つの先行ラベルが付加されたパブリック サフィックス)を STRING として返します。最適な結果を得るには、URL 値を RFC 3986 で定義されている形式に一致させる必要があります。URL 値が RFC 3986 の形式設定に準拠していない場合、この関数は入力を解析し、関連する結果を返します。

次の条件を満たす場合、この関数は NULL を返します。

  • 入力からホストを解析できない。
  • 解析したホストで、先頭または末尾以外の場所でドットが連続している。
  • 解析したホストにパブリック サフィックスが含まれていない。
  • 解析したホストにパブリック サフィックスが含まれているが、先頭にラベルがない。

パブリック サフィックスを検索する前に、この関数はホストを一時的に正規化します。大文字の英字を小文字に変換し、ASCII 以外のすべての文字を Punycode でエンコードします。次に、正規化されたホストではなく、元のホストの一部として登録済みまたは登録可能なドメインを返します。

注: この関数は Unicode の正規化を行いません。

注: publicsuffix.org のパブリック サフィックス データにはプライベート ドメインも含まれています。この関数は、プライベート ドメインをパブリック サフィックスとして扱いません。たとえば、「us.com」がパブリック サフィックス データのプライベート ドメインである場合、NET.REG_DOMAIN(「foo.us.com」)は、「foo.us.com」(プライベート ドメイン「us.com」と先行するラベル「foo」)ではなく、「us.com」(パブリック サフィックス「com」と先行するラベル「us」)を返します。

注: パブリック サフィックス データは変更される可能性があります。今後、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.Google.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" 標準の URL "abc.xyz" "xyz" "abc.xyz"
"//user:password@a.b:80/path?query" 相対スキーム、ポート、パス、クエリを含む標準の URL。ただし、パブリック サフィックスはありません。 "a.b" NULL NULL
"https://[::1]:80" IPv6 ホスト付きの標準 URL "[::1]" NULL NULL
"http://例子.卷筒纸.中国" 国際化ドメイン名付きの標準 URL "例子.卷筒纸.中国" "中国" "卷筒纸.中国"
"    www.Google.Co.UK    " スペース、大文字を含み、スキームのない非標準 URL "www.Google.Co.UK" "Co.UK" "Google.Co.UK"
"mailto:?to=&subject=&body=" URL ではなく URI(サポート対象外) "mailto" NULL NULL

演算子

演算子は特殊文字やキーワードによって表されます。関数の呼び出し構文は使用しません。また、演算子は、オペランドとも呼ばれる任意の数のデータ入力を操作し、結果を返します。

一般的な慣例:

  • 特記のない限り、オペランドの 1 つが NULL の場合、すべての演算子は NULL を返します。
  • 演算結果がオーバーフローした場合、すべての演算子は、エラーをスローします。
  • 浮動小数点演算で、オペランドの 1 つが +/-inf または NaN の場合、+/-inf または NaN が返されます。それ以外の場合には、エラーが返されます。

次の表は、すべての BigQuery オペレータを最も優先順位の高い方から最も低い方に、つまり、それらがステートメント内で評価される順序で表示しています。

優先順位 演算子 入力データ型 名前 演算子の項数
1 . STRUCT
メンバーのフィールド アクセス演算子 2 項
  [ ] ARRAY 配列位置。OFFSET または ORDINAL とともに使用する必要があります。ARRAY 関数を参照。 2 項
2 - すべての数値型 単項マイナス 単項
  ~ 整数または BYTES ビット演算 NOT 単項
3 * すべての数値型 乗算 2 項
  / すべての数値型 除算 2 項
4 + すべての数値型 加算 2 項
  - すべての数値型 減算 2 項
5 << 整数または BYTES ビット演算左シフト 2 項
  >> 整数または BYTES ビット演算右シフト 2 項
6 整数または BYTES ビット演算 AND 2 項
7 ^ 整数または BYTES ビット演算 XOR 2 項
8 | 整数または BYTES ビット演算 OR 2 項
9(比較演算子) = 任意の比較可能型。全リストはデータ型を参照。 等しい 2 項
  < 任意の比較可能型。全リストはデータ型を参照。 より小さい 2 項
  > 任意の比較可能型。全リストはデータ型を参照。 より大きい 2 項
  <= 任意の比較可能型。全リストはデータ型を参照。 以下 2 項
  >= 任意の比較可能型。全リストはデータ型を参照。 以上 2 項
  !=、<> 任意の比較可能型。全リストはデータ型を参照。 不等号 2 項
  [NOT] LIKE STRING とバイト 値が指定されたパターンと一致 [しない] 2 項
  [NOT] BETWEEN 互換性のある任意の型。データ型のリスト参照。 値が指定された範囲内に [ない]。 2 項
  [NOT]IN 互換性のある任意の型。データ型のリスト参照。 値が指定された値のセットに [ない]。 2 項
  IS [NOT] NULL すべて 値が NULL で [ない] 単項
  IS [NOT] TRUE BOOL 値が TRUE で [ない]。 単項
  IS [NOT] FALSE BOOL 値が FALSE で [ない]。 単項
10 NOT BOOL 論理 NOT 単項
11 AND BOOL 論理 AND 2 項
12 OR BOOL 論理 OR 2 項

優先順位が同じ演算子は左結合です。つまり、左側から開始して右側に移動しながらグループ化されます。次の式があるとします。

x AND y AND z

これは、次のように解釈されます。

( ( x AND y ) AND z )

次の式があるとします。

x * y / z

これは、次のように解釈されます。

( ( x * y ) / z )

すべての比較演算子の優先順位は同じであり、左結合を使用してグループ化されます。しかし、比較演算子は非結合です。このため、読みやすく、希望どおりに式が処理されるように、括弧を使用することをおすすめします。次に例を示します。

(x < y) IS FALSE

下の例よりも、上の例のようにすることをおすすめします。

x < y IS FALSE

要素アクセス演算子

演算子 構文 入力データ型 結果のデータ型 説明
. expression.fieldname1... STRUCT
fieldname1 に格納された型 T ドット演算子。ネストされたフィールドにアクセスするために使用できます。例: expression.fieldname1.fieldname2...
[ ] array_expression [position_keyword (int_expression ) ] ARRAY 関数を参照してください。 ARRAY に保存された型 T position_keyword は、OFFSET または ORDINAL のいずれかです。この演算子を使用する 2 つの関数用の ARRAY 関数を参照ください。

算術演算子

以下の説明に示されていない限り、すべての算術演算子で数値型 T が受け入れられ、結果の型には型 T が含まれます。

名前 構文
加算 X + Y
減算 X - Y
乗算 X * Y
除算 X / Y
単項マイナス - X

注: ゼロ除算はエラーを返します。異なる結果を取得するには、IEEE_DIVIDE または SAFE_DIVIDE 関数を使用してください。

加算と乗算の結果の型:

 INT64FLOAT64
INT64INT64FLOAT64
FLOAT64FLOAT64FLOAT64

減算の結果の型:

 INT64FLOAT64
INT64INT64FLOAT64
FLOAT64FLOAT64FLOAT64

除算の結果の型:

 INT64FLOAT64
INT64FLOAT64FLOAT64
FLOAT64FLOAT64FLOAT64

単項マイナスの結果の型:

入力データ型 結果のデータ型
INT64 INT64
FLOAT64 FLOAT64

ビット演算子

すべてのビット演算子は、第 1 オペランドと同じ型と同じ長さを返します。

氏名 構文 入力データ型 説明
ビット演算 NOT ~ X 整数または BYTES 与えられた変数値の補数を形成し、各ビットの論理否定を実行します。
ビット演算 OR X | Y X: 整数または BYTES
Y: X と同じ
同じ長さの 2 つのビットパターンをとり、対応するビットの各ペアに論理包含的和演算を実行します。X と Y が BYTES で長さが異なる場合、この演算子はエラーを返します。
ビット演算 XOR X ^ Y X: 整数または BYTES
Y: X と同じ
同じ長さの 2 つのビットパターンをとり、対応するビットの各ペアに排他的論理和演算を実行します。X と Y が BYTES で長さが異なる場合、この演算子はエラーを返します。
ビット演算 AND X & Y X: 整数または BYTES
Y: X と同じ
同じ長さの 2 つのビットパターンをとり、対応するビットの各ペアに論理 AND 演算を実行します。X と Y が BYTES で長さが異なる場合、この演算子はエラーを返します。
左シフト X << Y X: 整数または BYTES
Y: INT64
第 1 オペランド X を左にシフトします。第 2 オペランド Y が第 1 オペランド X のビット長(たとえば、INT64 型の場合は 64)以上の場合、この演算子は 0 または b'\x00' のバイト シーケンスを返します。Y が負の数の場合、この演算子はエラーを返します。
右シフト X >> Y X: 整数または BYTES
Y: INT64
第 1 オペランド X を右方にシフトします。この演算子は、符号付きの型で符号ビット拡張を行いません(左側の空いたビットを 0 で埋めます)。第 2 オペランド Y が第 1 オペランド X のビット長(たとえば、X が INT64 型の場合は 64)以上の場合、この演算子は 0 または b'\x00' のバイト シーケンスを返します。Y が負の数の場合、この演算子はエラーを返します。

論理演算子

すべての論理演算子は BOOL 入力のみ許可します。

名前 構文 説明
論理 NOT NOT X 入力が TRUE の場合は FALSE を返します。入力が FALSE の場合は TRUE を返します。それ以外では NULL を返します。
論理 AND X AND Y 少なくとも 1 つの入力が FALSE の場合、FALSE を返します。X と Y の両方が TRUE の場合、TRUE を返します。それ以外では NULL を返します。
論理 OR X OR Y X と Y の両方が FALSE であれば FALSE を返します。少なくとも 1 つの入力が TRUE の場合、TRUE を返します。それ以外では NULL を返します。

比較演算子

比較演算子は常に BOOL を返します。比較では両方のオペランドが同じ型である必要があります。異なる場合、強制的に共通の型に設定され、比較されます。比較可能なデータ型はデータ型に定義されています。

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 を返します。
BETWEEN X [NOT] BETWEEN Y AND Z X が指定された範囲内に [ない] 場合、TRUE を返します。「X BETWEEN Y AND Z」の結果は「Y <= X AND X <= Z」と等価ですが、前者では X は一度しか評価されません。
LIKE X [NOT] LIKE Y 第 1 オペランド X の文字列が第 2 オペランド Y によって指定されたパターンと一致するかどうかをチェックします。式にはこれらの文字を含めることができます。
  • パーセント記号「%」は、任意の数の文字またはバイトと一致します。
  • アンダースコア「_」は、単一の文字またはバイトと一致します。
  • "\"、"_" または "%" は、2 つのバックスラッシュを使用してエスケープします。たとえば、 "\\%" のようにします。文字列をそのまま使用する場合には、バックスラッシュを 1 つだけ使用します。たとえば、r"\%". のようにします。
IN 複数 - 以下を参照 右オペランドが空の場合、FALSE を返します。左のオペランドが NULL の場合は NULL を返します。右のオペランドに NULL が含まれる場合、TRUE または NULL を返します。IN のいずれかの側の引数は、一般式です。どちらのオペランドもリテラルにする必要はありませんが、右側にリテラルを使用するのが一般的です。X は一度だけ評価されます。

STRUCT データ型の値が等価かどうかテストする場合、1 つ以上のフィールドが 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 です
  • NULL の左辺式を持ち、空ではない右辺式を持つ NULL は常に IN です
  • IN リスト内に NULL を持つ IN は TRUE または NULL のみを返すことができます。FALSE は返されません
  • NULL IN (NULL)NULL を返します
  • IN UNNEST(<NULL array>) は FALSE(NULL ではない)を返します

IN は STRUCT のコンストラクタ構文を使用してマルチパート キーと共に使用できます。次に例を示します。

(Key1, Key2) IN ( (12,34), (56,78) )
(Key1, Key2) IN ( SELECT (table.a, table.b) FROM table )

この構文の詳細については、データ型トピックの Struct 型セクションをご覧ください。

IS 演算子

IS 演算子は、テストしている条件に対して TRUE または FALSE を返します。数学的関数に定義されている IS_INF 関数や IS_NAN 関数とは異なり、入力が NULL であっても、この演算子が NULL を返すことはありません。NOT がある場合、出力 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 を返します。

条件式

条件式は、入力の評価順序に制約を課します。基本的に、これらは短絡を使用して左から右に評価され、選択された出力のみを評価します。対照的に、正規関数へのすべての入力は関数の呼び出し前に評価されます。条件式での短絡は、エラー処理やパフォーマンス チューニングに利用できます。

構文 入力データ型 結果のデータ型 説明

CASE expr
  WHEN value THEN result
  [WHEN ...]
  [ELSE else_result]
  END
exprvalue: 任意の型 resultelse_result: 入力型のスーパータイプ expr と、連続する各 WHEN 句を比較し、この比較で TRUE が返される最初の結果を返します。残りの WHEN 句と else_result は評価されません。expr = value 比較ですべての NULL 句に対して FALSE または WHEN が返される場合、else_result が返されます。expr および value 式は共通のスーパータイプに暗黙的に強制型変換できる必要があります。等価比較は強制型変換された値に対して行われます。result および else_result 式は共通のスーパータイプに強制的に型変換できる必要があります。

CASE
  WHEN cond1 THEN result
  [WHEN cond2...]
  [ELSE else_result]
  END
cond: ブール値 resultelse_result: 入力型のスーパータイプ 連続する各 WHEN 句の条件 cond を評価し、条件が TRUE になる最初の結果を返します。残りのすべての WHEN 句と else_result は評価されません。すべての条件が FALSE または NULL である場合、else_result を返します。result および else_result 式は共通のスーパータイプに暗黙的に強制型変換できる必要があります。
COALESCE(expr1, ..., exprN) 任意の形式 入力型のスーパータイプ 最初の非 NULL 式の値を返します。残りの式は評価されません。すべての入力式は共通のスーパータイプに暗黙的に強制型変換できる必要があります。
IF(cond, true_result, else_result) cond: ブール値 true_resultelse_result: 任意の型 cond が TRUE の場合、true_result を返します。それ以外の場合は else_result を返します。cond が TRUE の場合、else_result は評価されません。cond が FALSE または NULL の場合、true_result は評価されません。true_resultelse_result は共通のスーパータイプに強制型変換できる必要があります。
IFNULL(expr, null_result) 任意の形式 任意の型または入力型のスーパータイプ exprNULL の場合、null_result を返します。それ以外の場合は、expr を返します。exprNULL ではない場合、null_result は評価されません。exprnull_result は共通のスーパータイプに暗黙的に強制型変換できる必要があります。COALESCE(expr, null_result) と同義です。
NULLIF(expression, expression_to_match) 任意の型 T または T のサブタイプ 任意の型 T または T のサブタイプ expression = expression_to_match が TRUE の場合、NULL を返します。それ以外の場合、expression を返します。expressionexpression_to_match は共通のスーパータイプに暗黙的に強制型変換できる必要があります。等価比較は、強制型変換された値に対して行われます。

式のサブクエリ

4 種類の式のサブクエリ、つまり、式として使用されるサブクエリがあります。式のサブクエリは、列または表とは対照的に、NULL または単一の値を返します。また、括弧で囲む必要があります。サブクエリの詳細については、サブクエリをご覧ください。

サブクエリの型 結果のデータ型 説明
Scalar 任意の型 T 式で括弧に囲まれているサブクエリ(SELECT リストや WHERE 句内など)は、Scalar サブクエリとして解釈されます。Scalar サブクエリ内の SELECT リストには、厳密に 1 つのフィールドがある必要があります。サブクエリによって正確に 1 行が返される場合、その単一の値が Scalar サブクエリの結果になります。サブクエリによってゼロ行が返される場合、Scalar サブクエリの値は NULL になります。サブクエリによって複数の行が返される場合、クエリはランタイム エラーで失敗します。サブクエリが SELECT AS STRUCT で作成されている場合、複数の列を含めることができます。また、戻り値は構造化された STRUCT になります。SELECT AS を使用せずに複数の列を選択すると、エラーが発生します。
ARRAY ARRAY SELECT AS STRUCT を使用して STRUCT の配列を作成できます。SELECT AS を使用せずに複数の列を選択すると、エラーが発生します。サブクエリがゼロ行を返す場合、空の ARRAY が返されます。NULL ARRAY が返されることはありません。
IN BOOL IN 演算子に続く式で使用されます。サブクエリによって、IN 演算子の左側の式と型が等式互換性を持つ単一の列を生成する必要があります。サブクエリによってゼロ行が返される場合、FALSE が返されます。 x IN ()x IN (value, value, ...) と等価です。完全なセマンティクスについては、比較演算子IN 演算子をご覧ください。
EXISTS BOOL サブクエリによって 1 つ以上の行が生成される場合、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 集計関数を使用して、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 1フィールドの 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  

デバッグ関数

BigQuery は、次のデバッグ関数をサポートします。

ERROR

ERROR(error_message)

説明

エラーを返します。error_message 引数は STRING です。

BigQuery は、エラーが発生する可能性のある式と同じ方法で ERROR を処理します。評価順序の特別な保証はありません。

戻りデータの型

BigQuery によってコンテキスト内で戻り値の型が推論されます。

次の例では、行の値が 2 つの定義された値のいずれかと一致しない場合、クエリはエラー メッセージを返します。

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

次の例では、ERROR 関数は x < 0 条件の前または後に評価されます。これは、BigQuery では通常、WHERE 句の条件間の順序が保証されず、ERROR 関数に対する特別な保証もないためです。

SELECT *
FROM (SELECT -1 AS x)
WHERE x > 0 AND ERROR('Example error');

次の例では、WHERE 句で IF 条件が評価されるため、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

フィードバックを送信...