Marcadores de parâmetro

Aplica-se a: seleção marcada como sim Databricks SQL Databricks Runtime

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 da estrutura das instruções SQL.

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

Você também pode usar marcadores de parâmetro na IDENTIFIER cláusula, que podem ser usados para parametrizar nomes de objeto. Consulte a cláusula IDENTIFIER.

Os marcadores de parâmetro podem ser fornecidos por:

Python usando sua API pyspark.sql.SparkSession.sql( ).
Scala usando sua API org.apache.spark.sql.SparkSession.sql( ).
Java usando sua API org.apache.spark.sql.SparkSession.sql( ).

As seguintes regras se aplicam:

Aplica-se a: Databricks SQL Databricks Runtime 17.3 LTS e anteriores
- Você pode referenciar um marcador de parâmetro em uma expressão
- 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 referências a marcadores de parâmetro na cláusula IDENTIFIER, que podem ser usadas para parametrizar o tema de determinadas instruções DDL. Consulte a cláusula IDENTIFIER.
Aplica-se a: Databricks Runtime 18.0 e versões superiores
- Você pode referenciar um marcador de parâmetro sempre que puder usar um literal do tipo do marcador de parâmetro.

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

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

> EXECUTE IMMEDIATE 'SELECT 1::DECIMAL(:precision, :scale)' USING 6 AS precision, 4 AS scale;
  1.0000

> EXECUTE IMMEDIATE 'CREATE VIEW v(c1 INT) AS SELECT :val AS c1' USING 10 AS val;
> SELECT * FROM v;
  10

> EXECUTE IMMEDIATE 'CREATE TABLE T(c1 INT DEFAULT :def COMMENT \'This is a \' :com)' USING 17 AS def, 'comment' as com;

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

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

> EXECUTE IMMEDIATE 'SELECT 1::DECIMAL(?, ?)' USING 6, 4;
  1.0000

> EXECUTE IMMEDIATE 'CREATE VIEW v(c1 INT) AS SELECT ? AS c1' USING 10;
> SELECT * FROM v;
  10

> EXECUTE IMMEDIATE 'CREATE TABLE T(c1 INT DEFAULT ? COMMENT \'This is a \' ?)' USING 17 AS def, ? as com;

Comentários

Esta página foi útil?

Last updated on 2026-01-17

Compartilhar via

Marcadores de parâmetro

Marcadores de parâmetro nomeados

Sintaxe

Parâmetros

Anotações

Exemplos

SQL

Scala

Java

Python

Marcadores de parâmetro sem nome

Sintaxe

Parâmetros

Anotações

Exemplos

SQL

Scala

Java

Python

Artigos relacionados

Comentários

Recursos adicionais