Utiliser des marqueurs de paramètres nommés

Les marqueurs de paramètres nommés vous permettent d’insérer des valeurs de variable dans des requêtes SQL au moment 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 lors de l’exécution de la requête. Cela améliore la réutilisation des requêtes, empêche l’injection SQL et facilite la création de requêtes flexibles et interactives.

Les marqueurs de paramètres nommés fonctionnent dans les surfaces Databricks suivantes :

• Éditeur SQL (nouveau et hérité)
• Notebooks
• Éditeur de jeu de données du tableau de bord AI/BI
• Genie Spaces

Ajouter un marqueur de paramètre nommé

Insérez un paramètre en tapant un signe deux-points suivi d’un nom de paramètre, tel que :parameter_name. Lorsque vous ajoutez un marqueur de paramètre nommé à une requête, un widget apparaît où vous pouvez définir le type de paramètre et la valeur. Consultez Utiliser les widgets de paramètres.

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

Requête de départ :

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

1. Supprimez 5 de la WHERE clause.
2. Tapez :fare_parameter à sa place. La dernière ligne doit lire fare_amount < :fare_parameter.
3. Cliquez sur l’icône d’engrenage près du widget de paramètre.
4. Définissez le typesur Décimal.
5. Entrez une valeur dans le widget de paramètre, puis 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 au moment de l’exécution.

Type	Description
Chaîne	Texte de forme libre. Les antislashs, les guillemets simples et doubles sont automatiquement échappés. Databricks ajoute des guillemets autour de la valeur.
Integer	Valeur de nombre entier.
Décimal	Valeur numérique qui prend en charge les valeurs fractionnaires.
Date	Valeur de date Utilise un sélecteur de calendrier et utilise par défaut la date actuelle.
Timestamp	Valeur de date et d’heure. Utilise un sélecteur de calendrier et est défini par défaut sur la date et l’heure actuelles.

Exemples de syntaxe de paramètre nommé

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

Insérer une date

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

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 IDENTIFIER fonction pour passer un nom de colonne en tant que paramètre. La valeur du paramètre doit être un nom de colonne de la table utilisée dans la requête.

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

Insérer des objets de base de données

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

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

Consultez la IDENTIFIER clause.

Concaténer plusieurs paramètres

Permet format_string de combiner des paramètres dans une seule chaîne mise en forme. Voir fonction format_string.

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

Utiliser des chaînes JSON

Utilisez la from_json fonction pour extraire une valeur d’une chaîne JSON à l’aide d’un paramètre comme clé. Substituer a comme valeur de :param retourne 1.

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

Créer un intervalle

Permet CAST de convertir une valeur de paramètre en type INTERVAL pour les calculs basés sur le temps. Consultez le type d’intervalle.

SELECT CAST(:param AS INTERVAL MINUTE)

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

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

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

Définissez le type de paramètre sur Date ou Timestamp et le type de widget sur Range.

Ajouter une plage de dates à l’aide de deux paramètres

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é d'agrégation

Permet DATE_TRUNC d’agréger les résultats au niveau de granularité sélectionné par l’utilisateur. Passer DAY, MONTH, ou YEAR en tant que valeur de paramètre.

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

Passer plusieurs valeurs sous forme de chaîne

Utilisez ARRAY_CONTAINS, SPLITet TRANSFORM pour filtrer sur une liste séparée par des virgules des valeurs passées en tant que paramètre de chaîne unique. SPLIT analyse la chaîne séparée par des virgules dans 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 résultant.

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

Note

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 en le type souhaité.

Informations de référence sur la migration de syntaxe

Utilisez ce tableau lors de la conversion de requêtes de la syntaxe de moustache en marqueurs de paramètres nommés. Pour plus d’informations sur la syntaxe héritée, consultez la syntaxe des paramètres Mustache .

Cas d’utilisation	Syntaxe Mustache	Syntaxe de paramètre nommé
Filtrer par date	WHERE date_field < '{{date_param}}'	WHERE date_field < :date_param
Filtrer par numéro	WHERE price < {{max_price}}	WHERE price < :max_price
Comparer des chaînes	WHERE region = '{{region_param}}'	WHERE region = :region_param
Définir une table	SELECT * FROM {{table_name}}	SELECT * FROM IDENTIFIER(:table) — utiliser l’espace de noms complet à trois niveaux
Spécifier le catalogue, le schéma et la table	SELECT * FROM {{catalog}}.{{schema}}.{{table}}	SELECT * FROM IDENTIFIER(:catalog \|\| '.' \|\| :schema \|\| '.' \|\| :table)
Mettre en forme 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)