매개 변수 표식
매개 변수 표식은 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입니다.
- 해당 org.apache.spark.sql.SparkSession.sql() API를 사용하는 Java.
명명된 매개 변수 표식
적용 대상: Databricks Runtime 
12.1 이상
명명된 매개 변수 표식은 형식화된 자리 표시자 변수입니다. SQL 문을 호출하는 API는 각 매개 변수 마커를 값과 연결하기 위해 이름-값 쌍을 제공해야 합니다.
구문
:parameter_name
매개 변수
-
정규화되지 않은 식별자 형식의 제공된 매개 변수 표식에 대한 참조입니다.
주의
동일한 SQL 문 내에서 동일한 매개 변수 표식을 여러 번 참조할 수 있습니다. 매개 변수 표식 에 값이 바인딩되지 않은 경우 UNBOUND_SQL_PARAMETER 오류가 발생합니다. 제공된 모든 매개 변수 마커를 참조할 필요는 없습니다.
필수 선행 : (콜론)은 명명된 매개 변수 표식의 네임스페이스를 열 이름 및 SQL 매개 변수의 네임스페이스와 구분합니다.
예제
다음 예제에서는 두 매개 변수 표식을 정의합니다.
- later: 값이
INTERVAL HOUR3인 경우 - x: 값이 15.0인 A
DOUBLE
x 은 한 번 참조되는 동안 later 여러 번 참조됩니다.
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인
INTERVAL HOUR값입니다. DOUBLE각각 값이 15.0인 2개입니다.
매개 변수는 이름이 지정되지 않으므로 제공된 각 값은 최대 하나의 매개 변수에서 사용됩니다.
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|
// +------+