Marcadores de parâmetro

  • Artigo

Os marcadores de parâmetro são variáveis de espaço reservado tipada nomeadas ou não nomeadas 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 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 gerada ou definição DEFAULT, uma exibição ou uma função SQL.

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

Os marcadores de parâmetro podem ser fornecidos por:

Marcadores de parâmetro nomeados

Aplica-se a: Databricks Runtime check marked yes12.1 e superior

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

Observaçõ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.

Os : (dois-pontos) de precedência obrigatória diferenciam 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:

  • posterior: um INTERVAL HOUR com o valor 3.
  • x: um 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 check marked yes13.3 e superior

Marcadores de parâmetro sem nome são variáveis de espaço reservado 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.

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