関数呼び出しルール

関数の説明で特に明示しない限り、以下の規則はすべての関数に適用されます。

  • 数値型を受け入れる関数は、1 つのオペランドが浮動小数点値オペランドであり、他のオペランドが別の数値型である場合、両方のオペランドが FLOAT64 に変換されてから関数が評価されます。
  • オペランドが NULL の場合、結果は IS 演算子を除いて NULL となります。
  • (関数の表記内に示されているとおりに)タイムゾーンの影響を受ける関数の場合、タイムゾーンが指定されていなければ、デフォルトのタイムゾーンである America/Los_Angeles が使用されます。

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