Parametre işaretçileri

Şunun için geçerlidir: Databricks SQL Databricks Runtime

Parametre işaretçileri, SQL deyimini çağıran API'den değer sağlamak için kullanılan, belirtilmiş türde, adlı veya adsız yer tutucu değişkenlerdir.

Parametre işaretçilerinin kullanılması, sağlanan değerleri SQL deyimlerinin yapısından açıkça ayırdığından kodunuzu SQL ekleme saldırılarına karşı korur.

Adlandırılmış ve adlandırılmamış parametre işaretçilerini aynı SQL deyiminde karıştıramazsınız.

Yan tümcesinde IDENTIFIER , nesne adlarını parametreleştirmek için kullanılabilen parametre işaretleyicilerini de kullanabilirsiniz. bkz. Madde IDENTIFIER.

Parametre işaretçileri şu şekilde sağlanabilir:

• Deyimi Yürütme API'sini kullanarak Databricks SQL.
• Pythonpyspark.sql.SparkSession.sql() API'sini kullanarak.
• Scala kullanarak org.apache.spark.sql.SparkSession.sql() API'sini.
• Javaorg.apache.spark.sql.SparkSession.sql() API'sini kullanarak.

Aşağıdaki kurallar geçerlidir:

• Şunun için geçerlidir: Databricks SQL Databricks Runtime 17.3 LTS ve öncesi

  • bir ifadede bir parametre işaretçisine başvurabilirsiniz
  • Oluşturulan sütun veya DEFAULT tanımı, görünüm veya SQL işlevi gibi bir DDL deyimindeki parametre işaretçilerine başvurmamalısınız. Özel durumlar, IDENTIFIER yan tümcesindeki parametre işaretçilerine yapılan başvurulardır ve bu, belirli DDL deyimlerinin konusunu parametreleştirmek için kullanılabilir. bkz. Madde IDENTIFIER.

• Şunun için geçerlidir: Databricks Runtime 18.0 ve üzeri

  • Parametre işaretçisinin türüne ait bir değişmez değeri kullanabileceğiniz her yerde parametre işaretçisini de kullanabilirsiniz. Bu, yukarıdaki DDL kısıtlamasını kaldırarak oluşturulan sütunlarda, tanımlarda, görünümlerde, DEFAULT SQL işlevlerinde ve gibi LOCATIONdize değerli DDL yan tümcelerinde parametre işaretçilerine izin verir.

Adlandırılmış parametre işaretçileri

Şunlar için geçerlidir: Databricks Runtime 12.1 ve üzeri

Adlandırılmış parametre işaretçileri, yazılan yer tutucu değişkenleridir. SQL deyimini çağıran API'nin, her parametre işaretçisini bir değerle ilişkilendirmek için ad-değer çiftleri sağlaması gerekir.

Sözdizimi

 :parameter_name

Parametreler

• adlandırılmış_parametre_adı

  Sağlanan parametre işaretçisine, nitelenmemiş bir tanımlayıcı biçiminde yapılan başvuru.

Notlar

Aynı SQL Deyimi içinde aynı parametre işaretçisine birden çok kez başvurabilirsiniz. Parametre işaretçisine hiçbir değer bağlanmadıysa bir UNBOUND_SQL_PARAMETER hatası oluşur. Sağlanan tüm parametre işaretçilerine başvurmanız gerekmez.

Yukarıdaki zorunlu : (iki nokta üst üste), adlandırılmış parametre işaretleyicilerinin ad alanını sütun adları ve SQL parametrelerinin ad alanından ayırır.

Örnekler

Aşağıdaki örnek iki parametre işaretçisini tanımlar:

• daha sonra: Değeri 3 olan bir INTERVAL HOUR.
• x: 15.0 değerine sahip bir DOUBLE

x birden çok kez başvurulurken, later bir kez başvurulur.

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|
// +----------------------------------------+------+

Piton

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|
// +----------------------------------------+------+

Şunlar için geçerlidir: Databricks Runtime 18.0 ve üzeri

> 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;

Adsız parametre işaretçileri

Şunlar için geçerlidir: Databricks Runtime 13.3 ve üzeri

Adsız parametre işaretçileri, yazılan yer tutucu değişkenleridir. SQL deyimini çağıran API, her parametre işaretçisini göründükleri sırada bir değerle ilişkilendirmek için bir dizi bağımsız değişken sağlamalıdır.

Sözdizimi

 ?

Parametreler

• ?: Soru işareti biçiminde sağlanan parametre işaretçisine başvuru.

Notlar

Adsız parametre işaretçisinin her oluşumu, SQL deyimini sırayla çağıran API tarafından sağlanan bir değeri kullanır. Parametre işaretçisine hiçbir değer bağlanmadıysa, bir UNBOUND_SQL_PARAMETER hatası oluşur. Sağlanan tüm değerleri kullanmanız gerekmez.

Örnekler

Aşağıdaki örnek üç parametre işaretçisini tanımlar:

• 3 değerine sahip bir INTERVAL HOUR.
• Her birinin değeri 15,0 olan iki DOUBLE.

Parametreler adlandırılmadığından sağlanan her değer en fazla bir parametre tarafından tüketilir.

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|
// +----------------------------------------+------+

Piton

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

Şunlar için geçerlidir: Databricks Runtime 18.0 ve üzeri

> 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 dize yan tümcelerindeki parametre işaretçileri

içindeki yan tümcesi LOCATIONgibi CREATE TABLE bazı DDL yan tümceleri tanımlayıcılar yerine dize değişmez değerlerini kabul eder. Nesne adları olmadıklarından, bu yan tümceler için yan tümcesini kullanamazsınız IDENTIFIER .

Şunlar için geçerlidir: Databricks Runtime 18.0 ve üzeri

Databricks Runtime 18.0 ve üzerinde, Databricks Runtime aynı türde bir değişmez değeri kabul ettiği her yerde parametre işaretçilerini desteklediğinden, parametre işaretçilerini doğrudan bu yan tümcelerde kullanabilirsiniz. Örneğin:

SQL

> CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path;

Piton

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

Scala

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)

Java

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 öncesi Databricks Runtime sürümleri için

Şunun için geçerlidir: Databricks SQL Databricks Runtime 14.3 - 17.3 LTS

Databricks Runtime 18.0'ın önceki sürümlerinde Databricks Runtime, parametre işaretçilerine doğrudan DDL deyimlerinde (yan tümcesi dışında IDENTIFIER ) izin vermez. SQL deyimini dinamik olarak derlemek ve yol değerini dize değişmez değeri olarak birleştirmek için kullanabilirsiniz 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 || '\'';

İlgili makaleler

• pyspark.sql.SparkSession.sql()
• org.apache.spark.sql.SparkSession.sql()
• IDENTIFIER cümle
• EXECUTE IMMEDIATE
• İsimler
• SET değişken