Partilhar via

Marcadores de parâmetros

  • Artigo

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

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

Os marcadores de parâmetros podem ser fornecidos por:

Marcadores de parâmetros nomeados

Aplica-se a: Databricks Runtime check marked yes 12.1 e 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

Parâmetros

  • named_parameter_name

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

Notas

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 precedente : 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:

  • mais tarde: Um INTERVAL HOUR com valor 3.
  • x: A 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 check marked yes 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.

Notas

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