Partilhar via

Marcadores de parâmetros

  • Artigo

Os marcadores de parâmetro são nomeados ou variáveis de espaço reservado sem nome digitadas usadas para fornecer values da API que invoca a instrução SQL.

O uso de marcadores de parâmetro protege seu código contra ataques de injeção de SQL, uma vez que separa claramente as instruções values fornecidas das instruções SQL.

Não é possível misturar marcadores de parâmetros nomeados e não nomeados na mesma instrução SQL.

Você não deve fazer referência a um marcador de parâmetro em uma instrução DDL, como uma definição de column ou DEFAULT gerada, uma exibição ou uma função SQL.

As exceções são referências a marcadores de parâmetros na cláusula IDENTIFIER, que podem ser usadas para parametrizar nomes de table ou column em determinadas instruções DDL. Ver IDENTIFIER cláusula.

Os marcadores de parâmetros podem ser fornecidos por:

Marcadores de parâmetros nomeados

Aplica-se a: Databricks Runtime marcado como sim 12.1 ou superior

Os marcadores de parâmetros nomeados são variáveis de espaço reservado digitadas. A API que invoca a instrução SQL deve fornecer pares nome-valor para associar cada marcador de parâmetro a um valor.

Sintaxe

 :parameter_name

Parameters

Observações

Você pode fazer referência ao mesmo marcador de parâmetro várias vezes dentro da mesma instrução SQL. Se nenhum valor tiver sido vinculado ao marcador de parâmetro, um erro de UNBOUND_SQL_PARAMETER será gerado. Não é necessário fazer referência a todos os marcadores de parâmetros fornecidos.

O : anterior obrigatório (dois pontos) diferencia o namespace de marcadores de parâmetros nomeados daquele de nomes de column e SQL parameters.

Exemplos

O exemplo a seguir define dois marcadores de parâmetro:

  • depois: Uma INTERVAL HOUR com valor 3.
  • x: Um DOUBLE com valor 15,0

x é referenciado várias vezes, enquanto later é referenciado uma vez.

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

Píton

spark.sql("SELECT :x * :y * :z AS volume", args = { "x" : 3, "y" : 4, "z"  : 5 }).show()
// +------+
// |volume|
// +------+
// |    60|
// +------+

Marcadores de parâmetros sem nome

Aplica-se a: Databricks Runtime confirmado 13.3 e superior

Marcadores de parâmetro sem nome são variáveis de espaço reservado digitadas. A API que invoca a instrução SQL deve fornecer uma matriz de argumentos para associar cada marcador de parâmetro a um valor na ordem em que aparecem.

Sintaxe

 ?

Parameters

  • ?: Uma referência a um marcador de parâmetro fornecido sob a forma de um ponto de interrogação.

Observações

Cada ocorrência de um marcador de parâmetro sem nome consome um valor fornecido pela API invocando a instrução SQL em ordem. Se nenhum valor tiver sido vinculado ao marcador de parâmetro, um erro de UNBOUND_SQL_PARAMETER será gerado. Você não é obrigado a consumir todos os valuesfornecidos.

Exemplos

O exemplo a seguir define três marcadores de parâmetro:

  • Um INTERVAL HOUR com valor 3.
  • Dois DOUBLE com valor 15.0 cada.

Como os parameters não têm nome, cada valor fornecido é consumido por, no máximo, um parâmetro.

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