Compartilhar via

Marcadores de parâmetro

Os marcadores de parâmetro são variáveis tipadas de espaço reservado nomeadas ou sem nome usadas para fornecer valores da API invocando a instrução SQL.

O uso de marcadores de parâmetro protege seu código contra ataques de injeção de SQL, pois ele separa claramente os valores fornecidos das instruções SQL.

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

Você não deve referenciar um marcador de parâmetro em uma instrução DDL, como uma coluna ou DEFAULT definição gerada, uma exibição ou uma função SQL.

Exceções são as referências a marcadores de parâmetro na cláusula IDENTIFIER, que podem ser usadas para parametrizar nomes de tabelas ou colunas em determinadas instruções DDL. Consulte a cláusula IDENTIFIER.

Os marcadores de parâmetro podem ser fornecidos por:

Marcadores de parâmetro nomeados

Aplica-se a: Verificação do Databricks Runtime marcada como sim 12.1 e superior

Marcadores de parâmetro nomeados são variáveis de substituição tipadas. 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

  • named_parameter_name

    Uma referência a um marcador de parâmetro fornecido na forma de um identificador não qualificado.

Anotações

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

O precedência : obrigatória (dois-pontos) diferencia o namespace de marcadores de parâmetro nomeados dos nomes de coluna e parâmetros SQL.

Exemplos

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

  • ** depois: Um INTERVAL HOUR com o valor 3.
  • x: A DOUBLE com o 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âmetro sem nome

Aplica-se a: Databricks Runtime marcado com 'sim' 13.3 ou superior

Marcadores de parâmetro sem nome são variáveis de marcador de posição tipadas. 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 eles aparecem.

Sintaxe

 ?

Parâmetros

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

Anotaçõ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 associado ao marcador de parâmetro, um erro UNBOUND_SQL_PARAMETER será gerado. Você não precisa consumir todos os valores fornecidos.

Exemplos

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

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

Como os parâmetros não são nomeados, cada valor fornecido é consumido pelo 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