パラメーターマーカー

[アーティクル]
03/01/2024

パラメーターマーカーは、SQL ステートメントを呼び出す API から値を供給するために使用される名前付きまたは名前のない型指定付きプレースホルダー変数です。

パラメーターマーカーを使用すると、指定された値が SQL ステートメントから明確に分離されるため、SQL インジェクション攻撃からコードが保護されます。

名前付きパラメーターマーカーと名前のないパラメーターマーカーを同じ SQL ステートメント内に混在させることはできません。

生成される列や DEFAULT 定義、ビュー、SQL 関数などの DDL ステートメントでパラメーターマーカーを参照することはできません。

例外は、特定の DDL ステートメントでテーブル名または列名をパラメーター化するのに使用できる IDENTIFIER 句内のパラメーターマーカーへの参照です。「IDENTIFIER 句」を参照してください。

パラメーターマーカーは、次の方法で指定できます。

Python pyspark.sql.SparkSession.sql() API を使用します。
Scala org.apache.spark.sql.SparkSession.sql() API を使用します。
Java org.apache.spark.sql.SparkSession.sql() API を使用します。

名前付きパラメーターマーカー

適用対象: Databricks Runtime check marked yes 12.1 以降

名前付きパラメーターマーカーは、型指定付きのプレースホルダー変数です。 SQL ステートメントを呼び出す API は、各パラメーターマーカーを値に関連付ける名前と値のペアを指定する必要があります。

構文

 :parameter_name

パラメーター

named_parameter_name

修飾されていない識別子の形式で指定されるパラメーターマーカーへの参照。

メモ

同じ SQL ステートメント内で同じパラメーターマーカーを複数回参照できます。パラメーターマーカーに値がバインドされていない場合は、UNBOUND_SQL_PARAMETER エラーが発生します。指定されたすべてのパラメーターマーカーを参照する必要はありません。

必須の先頭の : (コロン) は、名前付きパラメーターマーカーの名前空間を列名および SQL パラメーターの名前空間と区別します。

例

次の例では、2 つのパラメーターマーカーを定義しています。

later: 値が 3 の INTERVAL HOUR。
x: 値が 15.0 の DOUBLE。

x は複数回参照され、later は 1 回参照されます。

SQL

> DECLARE stmtStr = 'SELECT current_timestamp() + :later, :x * :x AS square';
> EXECUTE IMMEDIATE stmtStr USING INTERVAL '3' HOURS AS later, 15.0 AS x;
  2024-01-19 16:17:16.692303  225.00

Scala

import org.apache.spark.sql.SparkSession

val spark = SparkSession
  .builder()
  .appName("Spark named parameter marker example")
  .getOrCreate()

val argMap = Map("later" -> java.time.Duration.ofHours(3), "x" -> 15.0)
spark.sql(
  sqlText = "SELECT current_timestamp() + :later, :x * :x AS square",
  args = argMap).show()
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

Java

import org.apache.spark.sql.*;
import static java.util.Map.entry;

SparkSession spark = SparkSession
  .builder()
  .appName("Java Spark named parameter marker example")
  .getOrCreate();

Map<String, String> argMap = Map.ofEntries(
  entry("later", java.time.Duration.ofHours(3)),
  entry("x", 15.0)
);

spark.sql(
  sqlText = "SELECT current_timestamp() + :later, :x * :x AS square",
  args = argMap).show();
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

Python

spark.sql("SELECT :x * :y * :z AS volume", args = { "x" : 3, "y" : 4, "z"  : 5 }).show()
// +------+
// |volume|
// +------+
// |    60|
// +------+

名前のないパラメーターマーカー

適用対象: Databricks Runtime check marked yes 13.3 以降

名前のないパラメーターマーカーは、型指定付きのプレースホルダー変数です。 SQL ステートメントを呼び出す API は、各パラメーターマーカーを出現順に値に関連付ける引数の配列を指定する必要があります。

構文

パラメーター

?: 疑問符の形式で指定されたパラメーターマーカーへの参照。

メモ

名前のないパラメーターマーカーが出現するたびに、SQL ステートメントを順番に呼び出す API によって提供される値が使用されます。パラメーターマーカーに値がバインドされていない場合は、UNBOUND_SQL_PARAMETER エラーが発生します。指定されたすべての値を使用する必要はありません。

例

次の例では、3 つのパラメーターマーカーを定義しています。

値が 3 の 1つの INTERVAL HOUR。
値が 15.0 の 2 つの DOUBLE。

パラメーターに名前がないため、指定された各値は最大 1 つのパラメーターによって使用されます。

SQL

> DECLARE stmtStr = 'SELECT current_timestamp() + ?, ? * ? AS square';
> EXECUTE IMMEDIATE stmtStr USING INTERVAL '3' HOURS, 15.0, 15.0;
  2024-01-19 16:17:16.692303  225.00

Scala

import org.apache.spark.sql.SparkSession

val spark = SparkSession
  .builder()
  .appName("Spark unnamed parameter marker example")
  .getOrCreate()

val argArr = Array(java.time.Duration.ofHours(3), 15.0, 15.0)

spark.sql(
  sqlText = "SELECT current_timestamp() + ?, ? * ? AS square", args = argArr).show()
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

Java

import org.apache.spark.sql.*;

SparkSession spark = SparkSession
  .builder()
  .appName("Java Spark unnamed parameter marker example")
  .getOrCreate();

Object[] argArr = new Object[] { java.time.Duration.ofHours(3), 15.0, 15.0 }

spark.sql(
  sqlText = "SELECT current_timestamp() + ?, ? * ? AS square",
  args = argArr).show();
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

Python

spark.sql("SELECT ? * ? * ? AS volume", args = { 3, 4, 5 }).show()
// +------+
// |volume|
// +------+
// |    60|
// +------+