Verwenden von benannten Parametermarkern

Mit benannten Parametermarkern können Sie variablen Werte zur Laufzeit in SQL-Abfragen einfügen. Anstelle von hartcodierten spezifischen Werten definieren Sie eingegebene Platzhalter, die Benutzer beim Ausführen der Abfrage ausfüllen. Dies verbessert die Wiederverwendung von Abfragen, verhindert die SQL-Einfügung und erleichtert das Erstellen flexibler, interaktiver Abfragen.

Benannte Parametermarkierungen funktionieren in den folgenden Databricks-Oberflächen:

• SQL-Editor (neu und legacy)
• Notebooks
• AI/BI Dashboard Datensatz-Editor
• Genie-Räume

Hinzufügen einer benannten Parametermarkierung

Fügen Sie einen Parameter ein, indem Sie einen Doppelpunkt gefolgt von einem Parameternamen eingeben, zum Beispiel :parameter_name. Wenn Sie einer Abfrage eine benannte Parametermarkierung hinzufügen, wird ein Widget angezeigt, in dem Sie den Parametertyp und den Wert festlegen können. Siehe "Arbeiten mit Parameter-Widgets".

In diesem Beispiel wird eine hartcodierte Abfrage in einen benannten Parameter konvertiert.

Abfrage wird gestartet:

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

1. Löschen Sie 5 aus der WHERE Klausel.
2. Geben Sie :fare_parameter an dessen Stelle ein. Die letzte Zeile sollte fare_amount < :fare_parameter gelesen werden.
3. Klicken Sie auf das Zahnradsymbol in der Nähe des Parameter-Widgets.
4. Legen Sie den Typ auf Dezimalzahl fest.
5. Geben Sie einen Wert in das Parameter-Widget ein, und klicken Sie auf "Änderungen übernehmen".
6. Klicken Sie auf Speichern.

Parametertypen

Legen Sie den Parametertyp im Bereich "Parametereinstellungen" fest. Der Typ bestimmt, wie Databricks den Wert zur Laufzeit interpretiert und verarbeitet.

Beispiele für benannte Parametersyntax

Die folgenden Beispiele zeigen allgemeine Muster für benannte Parametermarkierungen.

Einfügen eines Datums

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

Einfügen einer Zahl

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

Einfügen eines Feldnamens

Verwenden Sie die IDENTIFIER Funktion, um einen Spaltennamen als Parameter zu übergeben. Der Parameterwert sollte ein Spaltenname aus der Tabelle sein, die in der Abfrage verwendet wird.

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

Einfügen von Datenbankobjekten

Verwenden Sie die IDENTIFIER Funktion mit mehreren Parametern, um einen Katalog, ein Schema und eine Tabelle zur Laufzeit anzugeben.

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

Siehe IDENTIFIER Klausel.

Verketten mehrerer Parameter

Verwenden Sie format_string, um Parameter in einer einzelnen formatierten Zeichenfolge zu kombinieren. Siehe format_string Funktion.

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

Arbeiten mit JSON-Zeichenfolgen

Verwenden Sie die from_json Funktion , um einen Wert aus einer JSON-Zeichenfolge mithilfe eines Parameters als Schlüssel zu extrahieren. Indem man a als Wert für :param einsetzt, ergibt es 1.

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

Ein Intervall erstellen

Wird CAST verwendet, um einen Parameterwert in einen INTERVAL Typ für zeitbasierte Berechnungen zu konvertieren. Siehe Intervalltyp.

SELECT CAST(:param AS INTERVAL MINUTE)

Hinzufügen eines Datumsbereichs mit .min und .max

Datums- und Zeitstempelparameter unterstützen ein Bereichs-Widget. Verwenden Sie .min und .max, um auf den Anfang und das Ende des Bereichs zuzugreifen.

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

Legen Sie den Parametertyp auf Date oder Timestamp und den Widgettyp auf Range fest.

Hinzufügen eines Datumsbereichs mit zwei Parametern

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

Parametrisierung der Rollup-Granularität

Verwenden Sie DATE_TRUNC, um Ergebnisse auf der vom Benutzer ausgewählten Granularitätsebene zu aggregieren. Übergeben DAY, , MONTHoder YEAR als Parameterwert.

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

Übergeben mehrerer Werte als Zeichenfolge

Verwenden Sie ARRAY_CONTAINS, SPLIT und TRANSFORM, um nach einer durch Kommas getrennten Liste von Werten zu filtern, die als einzelner Zeichenfolgenparameter übergeben werden. SPLIT analysiert die kommagetrennte Zeichenfolge in ein Array. TRANSFORM entfernt Leerzeichen von jedem einzelnen Element. ARRAY_CONTAINS überprüft, ob der Tabellenwert im resultierenden Array angezeigt wird.

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

Syntaxmigrationsreferenz

Verwenden Sie diese Tabelle beim Konvertieren von Abfragen aus der Mustache-Syntax in benannte Parametermarkierungen. Weitere Informationen zur Legacy-Syntax finden Sie unter Mustache-Parametersyntax.