Marcadores de parâmetros

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

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âmetros protege o seu código de ataques de injeção SQL, pois separa claramente os valores fornecidos da estrutura das instruções SQL.

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

Também pode usar marcadores de parâmetros na IDENTIFIER cláusula, que podem ser usados para parametrizar nomes de objetos. Ver IDENTIFIER cláusula.

Os marcadores de parâmetros podem ser fornecidos por:

Databricks SQL através da API de Execução de Instruções.
Python utilizando a sua API pyspark.sql.SparkSession.sql().
Scala utilizando a sua API org.apache.spark.sql.SparkSession.sql().
Java usando a sua API org.apache.spark.sql.SparkSession.sql().

Aplicam-se as seguintes regras:

Aplica-se a: Databricks SQL Databricks Runtime 17.3 LTS e anteriores
- Pode referenciar um marcador de parâmetro numa expressão
- 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. Exceções são referências a marcadores de parâmetros na cláusula IDENTIFIER, que podem ser usados para parametrizar o sujeito de certas instruções DDL. Ver IDENTIFIER cláusula.
Aplica-se a: Runtime Databricks 18.0 e superiores
- Poderás referenciar um marcador de parâmetro sempre que utilizares um literal do tipo do marcador de parâmetro. Isto elimina a restrição DDL anterior, permitindo marcadores de parâmetros em colunas geradas, DEFAULT definições, vistas, funções SQL e cláusulas DDL com valores em string, como LOCATION.

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

nome_do_parâmetro_nomeado

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

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 current_timestamp() + :later, :x * :x AS square",
  args = { "later": datetime.timedelta(hours=3), "x": 15.0 }).show()
// +----------------------------------------+------+
// |current_timestamp() + INTERVAL '03' HOUR|square|
// +----------------------------------------+------+
// |                    2023-02-27 17:48:...|225.00|
// +----------------------------------------+------+

Aplica-se a: Databricks Runtime assinalado como sim 18.0 e acima

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

Aplica-se a: Databricks Runtime assinalado como sim 18.0 e acima

> 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, 'comment';

Marcadores de parâmetros em cláusulas de cadeia DDL

Algumas cláusulas DDL, como a LOCATION cláusula em CREATE TABLE, aceitam literais de cadeia em vez de identificadores. Não podes usar a IDENTIFIER cláusula para estas cláusulas porque não são nomes de objetos.

Aplica-se a: Databricks Runtime assinalado como sim 18.0 e acima

No Databricks Runtime 18.0 e superiores, pode usar marcadores de parâmetros diretamente nestas cláusulas porque o Databricks Runtime suporta marcadores de parâmetros sempre que aceita um literal do mesmo tipo. Por exemplo:

SQL

> CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path;

Python

spark.sql(
  "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = {"path": "abfss://container@account.dfs.core.windows.net/data"})

Scala

val argMap = Map("path" -> "abfss://container@account.dfs.core.windows.net/data")
spark.sql(
  sqlText = "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = argMap)

Java

Map<String, String> argMap = Map.ofEntries(
  entry("path", "abfss://container@account.dfs.core.windows.net/data")
);

spark.sql(
  sqlText = "CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path",
  args = argMap);

Para Databricks Versões em tempo de execução anteriores à 18.0

Aplica-se a: assinalado Databricks SQL assinalado sim Databricks Runtime 14.3 a 17.3 LTS

Nas versões anteriores ao Databricks Runtime 18.0, o Databricks Runtime não permite marcadores de parâmetros diretamente nas instruções DDL (exceto através da IDENTIFIER cláusula). Podes usar EXECUTE IMMEDIATE para construir a instrução SQL dinamicamente, concatenando o valor do caminho como um literal de cadeia:

> DECLARE path STRING DEFAULT 'abfss://container@account.dfs.core.windows.net/data';
> EXECUTE IMMEDIATE 'CREATE EXTERNAL TABLE my_table USING DELTA LOCATION \'' || path || '\'';

Observação

Não pode incorporar um marcador de parâmetro dentro de um literal de cadeia (por exemplo, 'abfss://:param/path'). Em vez disso, passa toda a cadeia como um único parâmetro, ou usa concatenação de cadeias para construir o valor antes de o passar. Por exemplo, use SET VARIABLE com CONCAT() para construir o caminho completo numa variável, depois passe a variável para EXECUTE IMMEDIATE.

Comentários

Esta página foi útil?

Last updated on 2026-06-01

Marcadores de parâmetros

Marcadores de parâmetros nomeados

Sintaxe

Parâmetros

Observações

Exemplos

SQL

Scala

Java

Python

Marcadores de parâmetros sem nome

Sintaxe

Parâmetros

Observações

Exemplos

SQL

Scala

Java

Python

Marcadores de parâmetros em cláusulas de cadeia DDL

SQL

Python

Scala

Java

Para Databricks Versões em tempo de execução anteriores à 18.0

Artigos relacionados

Comentários

Recursos adicionais