Benoemde parametermarkeringen gebruiken

Met benoemde parametermarkeringen kunt u tijdens runtime variabele waarden invoegen in SQL-query's. In plaats van vaste waarden te coderen, definieert u getypte tijdelijke aanduidingen die gebruikers invullen wanneer de query wordt uitgevoerd. Dit verbetert het hergebruik van query's, voorkomt SQL-injectie en maakt het eenvoudiger om flexibele, interactieve query's te bouwen.

Benoemde parametermarkeringen werken in de volgende Databricks-oppervlakken:

• SQL-editor (nieuw en verouderd)
• Notitieboekjes
• Bewerkingsprogramma voor gegevenssets van AI/BI-dashboards
• Genie-ruimten

Een benoemde parametermarkering toevoegen

Voeg een parameter in door een dubbele punt te typen, gevolgd door een parameternaam, zoals :parameter_name. Wanneer u een benoemde parametermarkering aan een query toevoegt, wordt er een widget weergegeven waarin u het parametertype en de waarde kunt instellen. Zie Werken met parameterwidgets.

In dit voorbeeld wordt een in code vastgelegde query geconverteerd om een benoemde parameter te gebruiken.

Query starten:

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

1. Verwijder 5 uit de WHERE clausule.
2. Typ :fare_parameter op de juiste plaats. De laatste regel moet worden gelezen fare_amount < :fare_parameter.
3. Klik op het tandwielpictogram in de buurt van de parameterwidget.
4. Stel het type in op Decimaal.
5. Voer een waarde in de parameterwidget in en klik op Wijzigingen toepassen.
6. Klik op Opslaan.

Parametertypen

Stel het parametertype in het deelvenster parameterinstellingen in. Het type bepaalt hoe Databricks de waarde tijdens runtime interpreteert en verwerkt.

Voorbeelden van benoemde parametersyntaxis

In de volgende voorbeelden ziet u veelvoorkomende patronen voor benoemde parametermarkeringen.

Een datum invoegen

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

Een getal invoegen

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

Een veldnaam invoegen

Gebruik de IDENTIFIER functie om een kolomnaam door te geven als parameter. De parameterwaarde moet een kolomnaam zijn uit de tabel die in de query wordt gebruikt.

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

Databaseobjecten invoegen

Gebruik de IDENTIFIER functie met meerdere parameters om tijdens runtime een catalogus, schema en tabel op te geven.

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

Zie IDENTIFIER clausule.

Meerdere parameters samenvoegen

Gebruik format_string om parameters te combineren in één opgemaakte tekenreeks. Zie format_string functie.

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

Werken met JSON-tekenreeksen

Gebruik de from_json functie om een waarde uit een JSON-tekenreeks te extraheren met behulp van een parameter als sleutel. Het vervangen van a door de waarde voor :param geeft 1 terug.

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

Een interval maken

Hiermee CAST converteert u een parameterwaarde naar een INTERVAL type voor berekeningen op basis van tijd. Zie intervaltype.

SELECT CAST(:param AS INTERVAL MINUTE)

Een datumbereik toevoegen met behulp van .min en .max

Datum- en tijdstempelparameters ondersteunen een bereikwidget. Gebruik .min en .max voor toegang tot het begin en einde van het bereik.

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

Stel het parametertype in op Date of Timestamp en het widgettype op Bereik.

Een datumbereik toevoegen met twee parameters

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

De granulariteit van de rollup parameteriseren

Gebruik DATE_TRUNC dit om resultaten te aggregeren op een door de gebruiker geselecteerd niveau van granulariteit. Geef DAY, MONTH, of YEAR door als de parameterwaarde.

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

Meerdere waarden doorgeven als een tekenreeks

Gebruik ARRAY_CONTAINS, SPLITen TRANSFORM filter op een door komma's gescheiden lijst met waarden die als één tekenreeksparameter zijn doorgegeven. SPLIT parseert de door komma's gescheiden tekenreeks in een matrix. TRANSFORM trimt witruimte van elk element. ARRAY_CONTAINS controleert of de tabelwaarde wordt weergegeven in de resulterende matrix.

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

Syntax-migratie referentie

Gebruik deze tabel bij het converteren van query's van mustache-syntaxis naar benoemde parametermarkeringen. Zie de syntaxis van de mustache-parameter voor meer informatie over de verouderde syntaxis.