Partilhar via

Marcadores de parâmetros

Os marcadores de parâmetro são nomeados ou não nomeados, variáveis de espaço reservado usadas para fornecer valores digitados do 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, pois separa claramente os valores fornecidos 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 coluna gerada ou DEFAULT definição, 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 usados para parametrizar nomes de tabelas ou colunas 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 especificadas. 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

Parâmetros

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 do namespace de nomes de colunas e parâmetros SQL.

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

Python

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

 ?

Parâmetros

  • ?: 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. Não é necessário consumir todos os valores fornecidos.

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 parâmetros 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|
// +------+
  • Last updated on