Gunakan penanda parameter dengan nama tertentu

Penanda parameter bernama memungkinkan Anda menyisipkan nilai variabel ke dalam kueri SQL saat runtime. Alih-alih menghardcode nilai-nilai tertentu, Anda menentukan tempat penampung bertipe yang diisi pengguna saat kueri berjalan. Ini meningkatkan penggunaan kembali kueri, mencegah injeksi SQL, dan mempermudah pembuatan kueri interaktif yang fleksibel.

Penanda parameter bernama berfungsi di permukaan Databricks berikut:

• Editor SQL (baru dan warisan)
• Notebooks
• Editor himpunan data dasbor AI/BI
• Ruang Genie

Menambahkan penanda parameter bernama

Sisipkan parameter dengan mengetik titik dua diikuti dengan nama parameter, seperti :parameter_name. Saat Anda menambahkan penanda parameter bernama ke kueri, widget muncul di mana Anda dapat mengatur jenis dan nilai parameter. Lihat Bekerja dengan widget parameter.

Contoh ini mengonversi kueri yang dikodekan secara permanen untuk menggunakan parameter bernama.

Memulai kueri:

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

1. Hapus 5 dari WHERE klausa.
2. Ketik :fare_parameter di tempatnya. Baris terakhir harus membaca fare_amount < :fare_parameter.
3. Klik ikon roda gigi yang berada di dekat widget parameter.
4. Atur Jenis ke Desimal.
5. Masukkan nilai di widget parameter dan klik Terapkan perubahan.
6. Klik Simpan.

Jenis parameter

Atur jenis parameter di panel pengaturan parameter. Jenis menentukan bagaimana Databricks menginterpretasikan dan menangani nilai saat runtime.

Jenis	Deskripsi
String	Teks bebas. Garis miring terbalik, tanda kutip tunggal, dan tanda kutip ganda di-escape secara otomatis. Databricks menambahkan tanda kutip di sekitar nilai.
Bilangan Bulat	Seluruh nilai angka.
Decimal	Nilai numerik yang mendukung nilai pecahan.
Tanggal	Nilai tanggal. Menggunakan pemilih tanggal dengan tanggal saat ini sebagai default.
Stempel waktu	Nilai tanggal dan waktu. Menggunakan pemilih kalender dan default ke tanggal dan waktu saat ini.

Contoh sintaksis parameter bernama

Contoh berikut menunjukkan pola umum untuk penanda parameter melalui nama.

Sisipkan tanggal

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

Sisipkan angka

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

Sisipkan nama bidang

IDENTIFIER Gunakan fungsi untuk meneruskan nama kolom sebagai parameter. Nilai parameter harus berupa nama kolom dari tabel yang digunakan dalam kueri.

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

Sisipkan objek database

IDENTIFIER Gunakan fungsi dengan beberapa parameter untuk menentukan katalog, skema, dan tabel saat runtime.

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

Lihat klausa IDENTIFIER.

Menggabungkan beberapa parameter

Gunakan format_string untuk menggabungkan parameter ke dalam satu string berformat. Lihat fungsi format_string.

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

Bekerja dengan string JSON

from_json Gunakan fungsi untuk mengekstrak nilai dari string JSON menggunakan parameter sebagai kunci. Menggantikan a sebagai nilai untuk :param menghasilkan 1.

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

Membuat interval

Gunakan CAST untuk mengonversi nilai parameter menjadi INTERVAL jenis untuk perhitungan berbasis waktu. Lihat Jenis interval.

SELECT CAST(:param AS INTERVAL MINUTE)

Menambahkan rentang tanggal menggunakan .min dan .max

Parameter Tanggal dan Tanda Waktu mendukung widget rentang. Gunakan .min dan .max untuk mengakses awal dan akhir rentang.

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

Atur jenis parameter ke Date atau Timestamp dan jenis widget ke Rentang.

Menambahkan rentang tanggal menggunakan dua parameter

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

Parameterisasi tingkat kekasaran rollup

Gunakan DATE_TRUNC untuk mengagregasi hasil pada tingkat granularitas yang dipilih pengguna. Teruskan DAY, MONTH, atau YEAR sebagai nilai parameter.

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

Mengkonversikan beberapa nilai menjadi string

Gunakan ARRAY_CONTAINS, SPLIT, dan TRANSFORM untuk memfilter daftar nilai yang dipisahkan koma yang diteruskan sebagai parameter string tunggal. SPLIT mengurai string yang dipisahkan koma menjadi array. TRANSFORM memangkas spasi kosong dari setiap elemen. ARRAY_CONTAINS memeriksa apakah nilai tabel muncul dalam array yang dihasilkan.

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

Catatan

Contoh ini berfungsi untuk nilai string. Untuk menggunakan jenis data lain, bungkus TRANSFORM operasi dengan CAST untuk mengonversi elemen ke jenis yang diinginkan.

Referensi migrasi sintaksis

Gunakan tabel ini saat mengonversi kueri dari sintaks kumis ke penanda parameter bernama. Lihat Sintaks parameter Mustache untuk informasi selengkapnya tentang sintaksis warisan.

Skenario penggunaan	Sintaks Mustache	Sintaks parameter bernama
Filter menurut tanggal	WHERE date_field < '{{date_param}}'	WHERE date_field < :date_param
Filter menurut angka	WHERE price < {{max_price}}	WHERE price < :max_price
Membandingkan string	WHERE region = '{{region_param}}'	WHERE region = :region_param
Spesifikasikan tabel	SELECT * FROM {{table_name}}	SELECT * FROM IDENTIFIER(:table) — gunakan namespace tiga tingkat lengkap
Tentukan katalog, skema, dan tabel	SELECT * FROM {{catalog}}.{{schema}}.{{table}}	SELECT * FROM IDENTIFIER(:catalog \|\| '.' \|\| :schema \|\| '.' \|\| :table)
Memformat string dari beberapa parameter	"({{area_code}}) {{phone_number}}"	format_string("(%d) %d", :area_code, :phone_number)
Membuat interval	SELECT INTERVAL {{p}} MINUTE	SELECT CAST(format_string("INTERVAL '%s' MINUTE", :param) AS INTERVAL MINUTE)