매개변수 표식은 명명된 또는 명명되지 않은 형식화된 자리 표시자 변수이며, 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 런타임 
12.1 이상
명명된 매개 변수 표식은 형식화된 자리 표시자 변수입니다. SQL 문을 호출하는 API는 각 매개 변수 마커를 값과 연결하기 위해 이름-값 쌍을 제공해야 합니다.
통사론
:parameter_name
매개 변수
-
정규화되지 않은 식별자 형태로 제공된 매개변수 표시에 대한 참조입니다.
메모
동일한 SQL 문 내에서 동일한 매개 변수 표식을 여러 번 참조할 수 있습니다. 매개 변수 표식에 값이 바인딩되지 않은 경우 UNBOUND_SQL_PARAMETER 오류가 발생합니다. 제공된 모든 매개 변수 마커를 참조할 필요는 없습니다.
앞의 필수 :(콜론)는 명명된 매개 변수 표식의 네임스페이스를 열 이름 및 SQL 매개 변수의 네임스페이스와 구분합니다.
예제
다음 예제에서는 두 매개 변수 표식을 정의합니다.
-
이후: 값이 3인
INTERVAL HOUR입니다. -
x: 값이 15.0인
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
스칼라
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|
// +----------------------------------------+------+
자바
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|
// +----------------------------------------+------+
파이썬
spark.sql("SELECT :x * :y * :z AS volume", args = { "x" : 3, "y" : 4, "z" : 5 }).show()
// +------+
// |volume|
// +------+
// | 60|
// +------+
명명되지 않은 매개 변수 표식
적용 대상: Databricks 런타임 13.3 및 이상
명명되지 않은 매개 변수 표식은 형식화된 자리 표시자 변수입니다. SQL 문을 호출하는 API는 각 매개 변수 표식을 나타나는 순서대로 값과 연결하는 인수 배열을 제공해야 합니다.
통사론
?
매개 변수
-
?: 물음표 형식의 제공된 매개 변수 표식에 대한 참조입니다.
메모
명명되지 않은 매개 변수 표식이 발생할 때마다 SQL 문을 순서대로 호출하는 API에서 제공하는 값이 소비됩니다. 매개 변수 표식에 바인딩된 값이 없으면 UNBOUND_SQL_PARAMETER 오류가 발생합니다. 제공된 모든 값을 사용할 필요는 없습니다.
예제
다음 예제에서는 세 가지 매개 변수 표식을 정의합니다.
-
INTERVAL HOUR의 값이 3. - 각각 값이 15.0인 두 개의
DOUBLE.
매개 변수는 이름이 지정되지 않으므로 제공된 각 값은 최대 하나의 매개 변수에서 사용됩니다.
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
스칼라
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|
// +----------------------------------------+------+
자바
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|
// +----------------------------------------+------+
파이썬
spark.sql("SELECT ? * ? * ? AS volume", args = [ 3, 4, 5 ]).show()
// +------+
// |volume|
// +------+
// | 60|
// +------+