매개 변수 표식

적용 대상: Databricks SQL Databricks Runtime

매개변수 표식은 명명된 또는 명명되지 않은 형식화된 자리 표시자 변수이며, SQL 문을 호출하는 API로부터 값을 제공하는 데 사용됩니다.

매개 변수 표식을 사용하면 제공된 값을 SQL 문의 구조와 명확하게 구분하기 때문에 SQL 삽입 공격으로부터 코드를 보호합니다.

동일한 SQL 문에는 명명된 매개 변수 표식과 명명되지 않은 매개 변수 표식을 혼합할 수 없습니다.

개체 IDENTIFIER 매개 변수화하는 데 사용할 수 있는 절에서 매개 변수 표식을 사용할 수도 있습니다. IDENTIFIER 절 참조하세요.

매개 변수 표식은 다음을 통해 제공할 수 있습니다.

• 문 실행 API를 통한 Databricks SQL.
• Python은 pyspark.sql.SparkSession.sql() API를 사용합니다.
• Scala는 org.apache.spark.sql.SparkSession.sql() API를 사용하여.
• Java는 org.apache.spark.sql.SparkSession.sql() API를 사용합니다.

다음 규칙이 적용됩니다.

• 적용 대상: Databricks SQL Databricks Runtime 17.3 LTS 및 이전 버전에 적용됨

  • 식에서 매개 변수 마커를 참조할 수 있습니다.
  • 생성된 열 또는 DEFAULT 정의, 뷰 또는 SQL 함수와 같은 DDL 문에서 매개 변수 마커를 참조해서는 안 됩니다. IDENTIFIER 절의 매개 변수 표시자에 대한 참조는 특정 DDL 문 주체를 매개 변수화하는 데 사용할 수 있는 예외입니다. IDENTIFIER 절 참조하세요.

• 적용 대상: Databricks Runtime 18.0 이상

  • 매개변수 마커 형식의 리터럴을 사용할 수 있는 모든 위치에서 매개변수 마커를 참조할 수 있습니다. 이렇게 하면 이전 DDL 제한이 해제되어 생성된 열, 정의, 뷰, DEFAULT SQL 함수 및 문자열 반환 DDL 절(예: LOCATION)의 매개 변수 표식이 허용됩니다.

명명된 매개변수 표시자

적용 대상: Databricks 런타임 12.1 이상

명명된 매개 변수 표식은 형식화된 자리 표시자 변수입니다. SQL 문을 호출하는 API는 각 매개 변수 마커를 값과 연결하기 위해 이름-값 쌍을 제공해야 합니다.

통사론

 :parameter_name

매개 변수

• named_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 current_timestamp() + :later, :x * :x AS square",
  args = { "later": datetime.timedelta(hours=3), "x": 15.0 }).show()
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

적용 대상: Databricks 런타임 18.0 이상

> EXECUTE IMMEDIATE 'SELECT 1::DECIMAL(:precision, :scale)' USING 6 AS precision, 4 AS scale;
  1.0000

> EXECUTE IMMEDIATE 'CREATE VIEW v(c1 INT) AS SELECT :val AS c1' USING 10 AS val;
> SELECT * FROM v;
  10

> EXECUTE IMMEDIATE 'CREATE TABLE T(c1 INT DEFAULT :def COMMENT \'This is a \' :com)' USING 17 AS def, 'comment' AS com;

명명되지 않은 매개 변수 표식

적용 대상: 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|
// +------+

적용 대상: Databricks 런타임 18.0 이상

> EXECUTE IMMEDIATE 'SELECT 1::DECIMAL(?, ?)' USING 6, 4;
  1.0000

> EXECUTE IMMEDIATE 'CREATE VIEW v(c1 INT) AS SELECT ? AS c1' USING 10;
> SELECT * FROM v;
  10

> EXECUTE IMMEDIATE 'CREATE TABLE T(c1 INT DEFAULT ? COMMENT \'This is a \' ?)' USING 17, 'comment';

DDL 문자열 절의 매개 변수 표식

의 절CREATE TABLE과 같은 LOCATION 일부 DDL 절은 식별자가 아닌 문자열 리터럴을 허용합니다. 이러한 절은 IDENTIFIER 개체 이름이 아니므로 사용할 수 없습니다.

적용 대상: Databricks 런타임 18.0 이상

Databricks Runtime 18.0 이상에서는 Databricks 런타임이 동일한 형식의 리터럴을 허용하는 모든 위치에서 매개 변수 마커를 지원하므로 이러한 절에서 직접 매개 변수 마커를 사용할 수 있습니다. 다음은 그 예입니다.

SQL

> CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path;

파이썬

spark.sql(
  "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = {"path": "abfss://container@account.dfs.core.windows.net/data"})

스칼라

val argMap = Map("path" -> "abfss://container@account.dfs.core.windows.net/data")
spark.sql(
  sqlText = "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = argMap)

자바

Map<String, String> argMap = Map.ofEntries(
  entry("path", "abfss://container@account.dfs.core.windows.net/data")
);

spark.sql(
  sqlText = "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = argMap);

18.0 이전 Databricks 런타임 버전의 경우

적용 대상: Databricks SQL Databricks Runtime 14.3 ~ 17.3 LTS로 표시

Databricks Runtime 18.0 이전 버전에서는 Databricks 런타임이 DDL 문에서 직접 매개 변수 마커를 허용하지 않습니다(절을 제외 IDENTIFIER ). 경로 값을 문자열 리터럴로 연결하여 SQL 문을 동적으로 빌드하는 데 사용할 EXECUTE IMMEDIATE 수 있습니다.

> DECLARE path STRING DEFAULT 'abfss://container@account.dfs.core.windows.net/data';
> EXECUTE IMMEDIATE 'CREATE EXTERNAL TABLE my_table USING DELTA LOCATION \'' || path || '\'';

메모

문자열 리터럴(예 'abfss://:param/path': )에 매개 변수 표식을 포함할 수 없습니다. 대신 전체 문자열을 단일 매개 변수로 전달하거나 문자열 연결을 사용하여 값을 전달하기 전에 빌드합니다. 예를 들어 변수 SET VARIABLECONCAT() 의 전체 경로를 빌드한 다음 변수를 전달합니다 EXECUTE IMMEDIATE.

관련 문서

• pyspark.sql.SparkSession.sql()
• org.apache.spark.sql.SparkSession.sql()
• IDENTIFIER 절
• EXECUTE IMMEDIATE
• 이름
• SET 변수