Utiliser des marqueurs de paramètre nommés

Les marqueurs de parameter nommés vous permettent d'insérer des valeurs variables dans les query SQL lors de l'exécution. Au lieu de coder en dur des valeurs spécifiques, vous définissez des espaces réservés typés que les utilisateurs remplissent lorsque la query s'exécute. Cela améliore la réutilisation des query, prévient les injections SQL et facilite la création de query flexibles et interactives.

Les marqueurs de parameter nommés fonctionnent dans les environnements Databricks suivants :

• Éditeur SQL (nouveau et hérité)
• Notebooks
• Éditeur de dataset AI/BI dashboard
• Agents Genie

Ajouter un marqueur de paramètre nommé

Insérez un paramètre en saisissant deux points suivis d'un nom de paramètre, par exemple :parameter_name. Lorsque vous ajoutez un marqueur de paramètre nommé à une requête, un widget s'affiche dans lequel vous pouvez définir le type et la valeur du paramètre. Voir Travailler avec des widgets de paramètre.

Cet exemple convertit une requête codée en dur pour utiliser un paramètre nommé.

Démarrage de la query :

SQL

SELECT
  trip_distance,
  fare_amount
FROM
  samples.nyctaxi.trips
WHERE
  fare_amount < 5

1. Supprimez 5 de la clause WHERE.
2. Tapez :fare_parameter à sa place. La dernière ligne devrait lire fare_amount < :fare_parameter.
3. Cliquez sur l'icône d'engrenage près du widget de parameter.
4. Définissez le Type sur Décimal .
5. Saisissez une valeur dans le widget de paramètre et cliquez sur **Appliquer les modifications**.
6. Cliquez sur Enregistrer .

Types de paramètres

Définissez le type de paramètre dans le panneau des paramètres. Le type détermine comment Databricks interprète et gère la valeur à l'exécution.

Type	Description
Chaîne	Texte libre. La barre oblique inverse, les guillemets simples et doubles sont automatiquement échappés. Databricks ajoute des guillemets autour de la valeur.
Entier	Valeur du nombre entier.
Décimal	Valeur numérique prenant en charge les valeurs fractionnaires.
Date	Valeur de date. Utilise un sélecteur de calendrier et default à la date actuelle.
Horodatage	Valeur de date et d’heure. Utilise un sélecteur de calendrier et s’initialise par default à la date et à l’heure actuelles.

Type	Description
Chaîne	Texte libre. La barre oblique inverse, les guillemets simples et doubles sont automatiquement échappés. Databricks ajoute des guillemets autour de la valeur.
Entier	Valeur du nombre entier.
Décimal	Valeur numérique prenant en charge les valeurs fractionnaires.
Date	Valeur de date. Utilise un sélecteur de calendrier et default à la date actuelle.
Horodatage	Valeur de date et d’heure. Utilise un sélecteur de calendrier et s’initialise par default à la date et à l’heure actuelles.

Exemples de syntaxe de parameter nommés

Les exemples suivants illustrent des modèles courants pour les marqueurs de paramètres nommés.

Insérer une date

SQL

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  sum(o_totalprice) AS `Total Price`
FROM
  samples.tpch.orders
WHERE
  o_orderdate > :date_param
GROUP BY 1, 2

Insérer un nombre

SQL

SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  o_totalprice AS Price
FROM
  samples.tpch.orders
WHERE
  o_totalprice > :num_param

Insérer un nom de champ

Utilisez la fonction IDENTIFIER pour passer un nom de colonne en tant que parameter. La valeur du parameter doit être un nom de colonne de la table utilisée dans la query.

SQL

SELECT * FROM samples.tpch.orders
WHERE IDENTIFIER(:field_param) < 10000

Insérer des objets de base de données

Utilisez la fonction IDENTIFIER avec plusieurs paramètres pour spécifier un catalogue, un schéma et une table à l'exécution.

SQL

SELECT *
FROM IDENTIFIER(:catalog || '.' || :schema || '.' || :table)

Consultez la clause IDENTIFIER.

Concaténer plusieurs paramètres

Utilisez format_string pour combiner des paramètres en une seule chaîne formatée. Voir fonction format_string.

SQL

SELECT o_orderkey, o_clerk
FROM samples.tpch.orders
WHERE o_clerk LIKE format_string('%s%s', :title, :emp_number)

Travailler avec les chaînes JSON

Utilisez la fonctionfrom_json pour extraire une valeur d'une chaîne JSON à l'aide d'un paramètre comme clé. La substitution de a en tant que valeur pour :param renvoie 1.

SQL

SELECT from_json('{"a": 1}', 'map<string, int>') [:param]

Créer un intervalle

Utiliser CAST pour convertir une valeur de paramètre en type INTERVAL pour les calculs temporels. Voir type d'intervalle.

SQL

SELECT CAST(:param AS INTERVAL MINUTE)

Ajouter une plage de dates à l'aide de .min et .max

Les paramètres de date et de Timestamp prennent en charge un widget de plage. Utilisez .min et .max pour accéder au start et à la fin de la plage.

SQL

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN :date_range.min AND :date_range.max

Définissez le type de parameter sur Date ou Timestamp et le type de widget sur **Plage**.

Ajoutez une plage de dates à l'aide de deux paramètres

SQL

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN CAST(:date_range_min AS TIMESTAMP) AND CAST(:date_range_max AS TIMESTAMP)

Paramétrer la granularité de cumul

Utilisez DATE_TRUNC pour agréger les résultats à un niveau de granularité sélectionné par l'utilisateur. Passez DAY, MONTH ou YEAR comme valeur du paramètre.

SQL

SELECT
  DATE_TRUNC(:date_granularity, tpep_pickup_datetime) AS date_rollup,
  COUNT(*) AS total_trips
FROM samples.nyctaxi.trips
GROUP BY date_rollup

Transmettre plusieurs valeurs sous forme de chaîne

Utilisez ARRAY_CONTAINS, SPLIT et TRANSFORM pour filtrer une liste de valeurs séparées par des virgules, transmise comme un seul paramètre de chaîne. SPLIT analyse syntaxiquement la chaîne de caractères séparée par des virgules en un tableau. TRANSFORM supprime les espaces blancs de chaque élément. ARRAY_CONTAINS vérifie si la valeur de la table apparaît dans le tableau de résultats.

SQL

SELECT * FROM samples.nyctaxi.trips WHERE
  array_contains(
    TRANSFORM(SPLIT(:list_parameter, ','), s -> TRIM(s)),
    CAST(dropoff_zip AS STRING)
  )

remarque

Cet exemple fonctionne pour les valeurs de chaîne. Pour utiliser d'autres types de données, enveloppez l'opération TRANSFORM avec un CAST pour convertir les éléments au type souhaité.

Référence de migration de syntaxe

Utilisez cette table lors de la conversion des query de la syntaxe mustache en marqueurs de parameter nommés. Consultez la syntaxe des parameter mustache pour plus d'information concernant la syntaxe héritée.

Cas d'usage	Syntaxe Mustache	Syntaxe de paramètre nommée
Filtrer par date	WHERE date_field < '{{date_param}}'	WHERE date_field < :date_param
Filtrer par nombre	WHERE price < {{max_price}}	WHERE price < :max_price
Comparer les chaînes	WHERE region = '{{region_param}}'	WHERE region = :region_param
Spécifiez une table	SELECT * FROM {{table_name}}	SELECT * FROM IDENTIFIER(:table) — utilisez l'espace de noms complet à trois niveaux
Spécifiez le catalogue, le schéma et la table.	SELECT * FROM {{catalog}}.{{schema}}.{{table}}	SELECT * FROM IDENTIFIER(:catalog || '.' || :schema || '.' || :table)
Formater une chaîne à partir de plusieurs paramètres	"({{area_code}}) {{phone_number}}"	format_string("(%d) %d", :area_code, :phone_number)
Créer un intervalle	SELECT INTERVAL {{p}} MINUTE	SELECT CAST(format_string("INTERVAL '%s' MINUTE", :param) AS INTERVAL MINUTE)

Cas d'usage	Syntaxe Mustache	Syntaxe de paramètre nommée
Filtrer par date	WHERE date_field < '{{date_param}}'	WHERE date_field < :date_param
Filtrer par nombre	WHERE price < {{max_price}}	WHERE price < :max_price
Comparer les chaînes	WHERE region = '{{region_param}}'	WHERE region = :region_param
Spécifiez une table	SELECT * FROM {{table_name}}	SELECT * FROM IDENTIFIER(:table) — utilisez l'espace de noms complet à trois niveaux
Spécifiez le catalogue, le schéma et la table.	SELECT * FROM {{catalog}}.{{schema}}.{{table}}	SELECT * FROM IDENTIFIER(:catalog || '.' || :schema || '.' || :table)
Formater une chaîne à partir de plusieurs paramètres	"({{area_code}}) {{phone_number}}"	format_string("(%d) %d", :area_code, :phone_number)
Créer un intervalle	SELECT INTERVAL {{p}} MINUTE	SELECT CAST(format_string("INTERVAL '%s' MINUTE", :param) AS INTERVAL MINUTE)