パラメーター マーカーは、SQL ステートメントを呼び出す API から値を指定するために使用される 名前付き または 名前のない 型指定されたプレースホルダー変数です。
パラメーター マーカーを使用すると、指定された値が SQL ステートメントから明確に分離されるため、SQL インジェクション攻撃からコードが保護されます。
名前付きパラメーター マーカーと名前なしパラメーター マーカーを同じ SQL ステートメントに混在させることはできません。
生成された列や DEFAULT 定義、ビュー、SQL 関数など、DDL ステートメントでパラメーター マーカーを参照することはできません。
例外は、特定の DDL ステートメントでテーブル名または列名をパラメーター化するために使用できる、 IDENTIFIER 句のパラメーター マーカーへの参照です。
IDENTIFIER の条項を参照してください。
パラメーター マーカーは、次の方法で指定できます。
- pyspark.sql.SparkSession.sql() API を使用する Python。
- org.apache.spark.sql.SparkSession.sql() API を使用する Scala。
- Java の org.apache.spark.sql.SparkSession.sql() API を使用して。
名前付きパラメーター マーカー
適用対象: Databricks Runtime 
12.1 以上" とマークされている
名前付きパラメーター マーカーは、型指定されたプレースホルダー変数です。 SQL ステートメントを呼び出す API は、各パラメーター マーカーを値に関連付けるために、名前と値のペアを指定する必要があります。
構文
: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 13.3 以上" とマークされている
名前のないパラメーター マーカーは、型指定されたプレースホルダー変数です。 SQL ステートメントを呼び出す API は、各パラメーター マーカーを表示順序の値に関連付けるために、引数の配列を指定する必要があります。
構文
?
パラメーター
-
?: 指定されたパラメーター マーカーへの参照 (疑問符の形式)。
注記
名前のないパラメーター マーカーが出現するたびに、SQL ステートメントを呼び出す API によって提供される値が順番に使用されます。 パラメーター マーカーに値がバインドされていない場合は、 UNBOUND_SQL_PARAMETER エラーが発生します。 指定されたすべての値を使用する必要はありません。
例示
次の例では、3 つのパラメーター マーカーを定義します。
- 値 3 の
INTERVAL HOUR。 - 各値が15.0の
DOUBLEが2つあります。
パラメーターは名前が付いていないため、指定された各値は最大 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|
// +------+