Bekerja dengan parameter dasbor

Artikel ini menjelaskan cara menggunakan parameter pada dasbor AI/BI. Jika Anda ingin mempelajari tentang filter bidang sebagai gantinya, lihat Filter pada bidang.

Parameter dasbor AI/BI memungkinkan Anda mengganti nilai yang berbeda dalam kueri himpunan data saat waktu eksekusi. Ini memungkinkan Anda memfilter data menurut kriteria seperti tanggal dan kategori produk sebelum data dikumpulkan dalam kueri SQL, yang mengarah ke kueri yang lebih efisien dan analisis yang tepat. Parameter dapat digunakan dengan widget filter untuk membuat dasbor interaktif atau dengan widget visualisasi untuk membuat himpunan data lebih mudah digunakan kembali.

Penulis atau editor dasbor menambahkan parameter ke himpunan data dan menghubungkannya ke satu atau beberapa widget di kanvas dasbor. Untuk parameter statis yang diatur dalam widget visualisasi, nilai diatur oleh penulis atau editor. Untuk parameter yang digunakan dalam widget filter, penampil dasbor dapat berinteraksi dengan data dengan memilih nilai di widget filter saat runtime. Interaksi ini menjalankan ulang kueri terkait dan menampilkan visualisasi berdasarkan data yang difilter.

Parameter dapat secara langsung memodifikasi kueri, yang bisa sangat berpengaruh. Filter bidang himpunan data juga dapat menawarkan interaktivitas dasbor, lebih banyak fitur, dan performa yang lebih baik dengan himpunan data besar daripada parameter. Lihat Menggunakan filter.

Menambahkan parameter ke kueri

Anda harus memiliki setidaknya izin DAPAT MENGEDIT di dasbor draf untuk menambahkan parameter ke himpunan data dasbor. Anda dapat menambahkan parameter langsung ke kueri himpunan data di tab Data .

Untuk menambahkan parameter ke kueri:

1. Letakkan kursor di tempat Anda ingin menempatkan parameter dalam kueri Anda.

2. Klik Tambahkan parameter untuk menyisipkan parameter baru.

   Ini membuat parameter baru dengan nama parameterdefault . Untuk mengubah nama default, ganti di editor kueri. Anda juga dapat menambahkan parameter dengan mengetik sintaks ini di editor kueri.

Mengedit parameter kueri

Untuk mengedit parameter:

1. Klik di samping nama parameter. Dialog Detail parameter muncul dan menyertakan opsi konfigurasi berikut:

   • Kata kunci: Kata kunci yang mewakili parameter dalam kueri. Ini hanya dapat diubah dengan langsung memperbarui teks dalam kueri.

   • Nama tampilan: Nama di editor filter. Secara default, judulnya sama dengan kata kunci.

   • Jenis: Jenis yang didukung termasuk String, Tanggal, Tanggal dan Waktu, Numerik.

     • Jenis defaultnya adalah String.
     • Jenis data Numerik memungkinkan Anda menentukan antara Desimal dan Bilangan Bulat. Jenis numerik default adalah Desimal.

   • Izinkan beberapa pilihan: Pilih kotak centang untuk memungkinkan pengguna memilih beberapa parameter saat runtime.

     Catatan

     Pilihan ini mungkin memerlukan perubahan tambahan pada kueri Anda. Lihat Perbolehkan beberapa pilihan.

2. Klik bagian lain dari UI untuk menutup dialog.

Tetapkan nilai parameter default

Agar kueri Anda berjalan, pilih nilai default untuk parameter Anda dengan mengetikkannya ke bidang teks di bawah nama parameter. Jalankan kueri untuk mempratinjau hasil kueri dengan nilai parameter yang diterapkan. Menjalankan kueri juga menyimpan nilai default. Saat Anda mengatur parameter ini menggunakan widget filter di kanvas, nilai default digunakan kecuali nilai default baru ditentukan dalam widget filter. Lihat Menggunakan filter.

Perbolehkan beberapa pilihan

Kueri yang memperbolehkan beberapa pilihan harus menyertakan ARRAY_CONTAINS fungsi dalam kueri.

Contoh berikut menunjukkan kueri SQL yang memungkinkan Anda memilih beberapa nilai untuk disisipkan ke dalam kueri saat runtime. Klausa WHEREARRAY_CONTAINS menggunakan fungsi . Fungsi tersebut mengambil kata kunci parameter dan nama kolom sebagai argumen. Parameter harus diatur untuk menampung beberapa nilai sehingga dapat dimasukkan ke dalam kueri sebagai array. Saat kueri berjalan, setiap baris dievaluasi, dan semua baris di mana l_quantity sesuai setidaknya dengan satu nilai dalam :parameter akan disertakan dalam set hasil.

SELECT
  *
FROM
  samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity)

Untuk mengatur nilai default:

1. Tulis kueri himpunan data yang menggunakan fungsi ARRAY_CONTAINS untuk memfilter baris berdasarkan daftar nilai.

2. Klik di samping nama parameter. Pilih Izinkan beberapa pilihan.

   Catatan

   Langkah ini memungkinkan parameter dimasukkan ke dalam kueri sebagai array. Jika fungsi ARRAY_CONTAINS digunakan tanpa mengaktifkan beberapa pilihan, kesalahan terjadi.

3. Ketik nilai ke dalam bidang teks di bawah nama tampilan. Anda dapat memasukkan lebih dari satu nilai. Pilih nilai saat ini sebelum memasukkan nilai berikutnya.

Terapkan parameter rentang tanggal

Anda dapat menggunakan parameter untuk menentukan rentang dan hanya mengembalikan hasil dalam rentang tersebut. Saat Anda memilih salah satu jenis parameter berikut, Anda membuat dua parameter yang ditunjuk oleh akhiran .min dan .max:

• Rentang Tanggal
• Rentang Tanggal dan Waktu

Contoh berikut menunjukkan kueri SQL yang membuat parameter rentang tanggal bernama date_param.

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max

Untuk membuat parameter rentang tanggal:

1. Klik Tambahkan parameter.

2. Klik di samping nama parameter. Masukkan Kata Kunci dan Nama tampilan. Jangan sertakan .min atau .max akhiran.

3. Pilih Rentang Tanggal atau Rentang Tanggal dan Waktu sebagai Jenis.

4. Sisipkan klausa WHERE yang menentukan rentang ke dalam kueri Anda. Untuk menentukan rentang, gunakan klausa BETWEEN dengan nilai .min dan .max. Contohnya:

    WHERE date_col BETWEEN :date_param.min AND :date_param.max
   

5. Masukkan nilai tanggal default dan jalankan kueri untuk mengujinya. Gunakan ikon kalender untuk memilih opsi prasetel seperti minggu lalu atau bulan lalu.

Parameter berbasis kueri

Parameter berbasis kueri memungkinkan penulis menentukan daftar nilai dinamis atau statis yang dapat dipilih penonton saat mengatur parameter saat mereka menjelajahi data di dasbor. Mereka didefinisikan dengan menggabungkan filter bidang dan filter parameter dalam satu widget filter.

Untuk membuat parameter berbasis kueri, pembuat dasbor melakukan langkah-langkah berikut:

1. Buat himpunan data yang tataan hasilnya terbatas pada daftar kemungkinan nilai parameter.
2. Buat kueri himpunan data yang menggunakan parameter.
3. Konfigurasikan widget filter pada kanvas yang memfilter pada bidang dan menggunakan parameter.
   • Bidang Konfigurasi harus diatur untuk menggunakan bidang dengan daftar nilai parameter yang memenuhi syarat yang diinginkan.
   • Konfigurasi Parameter harus diatur untuk memilih nilai parameter.

Lihat Menggunakan parameter berbasis kueri untuk tutorial langkah demi langkah yang menunjukkan cara menambahkan parameter dan visualisasi berbasis kueri.

Membuat daftar parameter dinamis

Untuk membuat himpunan data dinamis yang mengisi drop-down yang digunakan pemirsa untuk memilih nilai parameter, tulis kueri SQL yang mengembalikan satu bidang dan menyertakan semua nilai di bidang tersebut. Nilai baru apa pun di bidang tersebut secara otomatis ditambahkan sebagai pilihan parameter. Contoh kueri SQL adalah sebagai berikut:

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Membuat daftar parameter statis

Anda dapat membuat himpunan data statis yang hanya menyertakan nilai yang Anda hardcode ke dalam himpunan data Anda. Contoh kueri adalah sebagai berikut:

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

Menghapus parameter kueri

Untuk menghapus parameter, hapus dari kueri Anda.

Widget statis parameter

Parameter widget statis dikonfigurasi langsung dalam widget visualisasi, memungkinkan penulis untuk secara individual membuat parameter widget visualisasi yang berbagi himpunan data yang sama. Ini memungkinkan himpunan data yang sama untuk menyajikan tampilan yang berbeda di kanvas.

Contoh di bagian ini didasarkan pada himpunan data yang meminta tabel samples.nyctaxi.trips. Kueri yang disediakan mengembalikan jarak setiap perjalanan dan mengategorikan hari penjemputan sebagai Weekday atau Weekend. Parameter kueri memfilter hasil berdasarkan apakah pengambilan terjadi pada hari kerja atau akhir pekan.

Teks kueri disediakan di blok kode berikut, tetapi instruksi di bagian ini terbatas pada penyiapan visualisasi terkait yang dikonfigurasi dengan parameter widget statis. Untuk petunjuk tentang menyiapkan himpunan data dengan parameter, lihat Menambahkan parameter ke kueri.

  WITH DayType AS (
    SELECT
      CASE
        WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
        ELSE 'Weekday'
      END AS day_type,
      trip_distance
    FROM samples.nyctaxi.trips
  )
  SELECT day_type, trip_distance
  FROM DayType
  WHERE day_type = :day_type_param

Untuk menambahkan parameter widget statis ke visualisasi:

1. Tambahkan widget visualisasi ke kanvas dasbor draf.

2. Dengan widget baru dipilih, pilih himpunan data parameter dari menu drop-down Himpunan Data di panel konfigurasi.

3. Klik Perlihatkan filter. Untuk himpunan data yang menyertakan parameter, bagian Parameter muncul di panel konfigurasi.

   

4. Klik tanda plus di sebelah kanan judul Parameter dan pilih parameter dari menu drop-down.

5. Secara default, nilai parameter mencerminkan apa yang diatur dalam kueri pada tab Data . Anda dapat menyimpannya atau memilih nilai baru untuk diganti ke dalam himpunan data. Navigasikan menjauh dari bidang teks untuk memperlihatkan visualisasi dengan parameter baru yang diterapkan.

6. Tinjau dasbor Anda.

   Gambar berikut menunjukkan dua widget visualisasi. Masing-masing dikonfigurasi sebagai histogram dengan parameter widget statis. Bagan di sebelah kiri menunjukkan distribusi jarak perjalanan untuk perjalanan yang dimulai pada hari kerja, sementara bagan di sebelah kanan menunjukkan data yang sama untuk akhir pekan. Kedua visualisasi didasarkan pada himpunan data yang sama.

   

Membandingkan data menggunakan kondisi filter

Anda dapat menambahkan kondisi filter yang memungkinkan Anda membandingkan agregasi pada bagian data ke agregasi yang diterapkan ke seluruh himpunan data.

Contoh berikut memperluas kueri sebelumnya untuk menyertakan kondisi filter di mana nilai parameter yang ditentukan All, yang tidak muncul dalam data. Bagian pertama dari kondisi filter berfungsi sama seperti dalam contoh sebelumnya, memfilter hasil di mana day_type adalah baik Weekday maupun Weekend. Bagian kedua dari kondisi filter memeriksa apakah parameter itu sendiri diatur ke nilai tertentu, dalam hal ini All, yang tidak muncul dalam data. Ketika Anda mengatur nilai default untuk parameter tersebut di editor himpunan data, Anda secara efektif melewati filter ketika baik Weekday maupun Weekend tidak diteruskan sebagai nilai.

WITH DayType AS (
  SELECT
    CASE
      WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
      ELSE 'Weekday'
    END AS day_type,
    trip_distance
  FROM
    samples.nyctaxi.trips
)
SELECT
  day_type,
  trip_distance
FROM
  DayType
WHERE
  day_type = :day_type_param
  OR :day_type_param = 'All'

Anda dapat menggunakan himpunan data ini untuk mengonfigurasi tiga widget visualisasi, dengan day_type_param diatur ke masing-masing All, Weekday dan Weekend. Kemudian, penampil dasbor dapat membandingkan setiap himpunan data yang difilter menurut jenis hari dengan seluruh himpunan data.

GIF berikut ini memperlihatkan bagaimana Anda bisa dengan cepat membuat tiga bagan dari himpunan data yang dibuat dengan kueri ini.

1. Bagan pertama dikonfigurasi untuk memperlihatkan himpunan data Jarak Perjalanan menurut Jenis Hari dengan nilai parameter yang diatur ke Hari Kerja .
2. Kloning bagan untuk mempertahankan semua konfigurasi yang diterapkan.
3. Untuk menampilkan data untuk perjalanan yang diambil pada akhir pekan, sesuaikan parameter statis dengan Akhir Pekan.
4. Kloning bagan baru untuk mempertahankan semua konfigurasi yang diterapkan sebelumnya.
5. Atur parameter di bagan baru ke Semua untuk menampilkan jumlah total perjalanan berdasarkan jarak untuk perjalanan akhir pekan dan hari kerja.

Menampilkan parameter di dasbor

Menambahkan filter ke kanvas dasbor Anda memungkinkan penonton untuk memilih dan memodifikasi nilai parameter untuk menjelajahi dan menganalisis data secara interaktif. Jika Anda tidak mengekspos parameter di dasbor, penampil hanya melihat hasil kueri yang menggunakan nilai parameter default yang Anda tetapkan dalam kueri.

Untuk menambahkan parameter ke dasbor Anda:

1. Klik Tambahkan filter (bidang/parameter).
2. Klik tambahkan ikon bidang di samping Parameter di panel konfigurasi.
3. Klik nama parameter yang Anda inginkan untuk digunakan penampil dengan widget ini.

Bekerja dengan widget filter dan parameter statis

Parameter-parameter adalah nilai tetap yang dimasukkan ke dalam kueri pada waktu runtime. Jika dua atau beberapa referensi ke parameter yang sama diatur dengan nilai yang berbeda saat dasbor Anda diperbarui, widget visualisasi menampilkan kesalahan yang menunjukkan parameter mana yang memiliki nilai yang bertentangan. Ini dapat terjadi ketika beberapa widget filter menggunakan parameter yang sama atau ketika parameter statis bertentangan dengan widget filter yang memungkinkan pemilihan penampil.

Anda dapat menggunakan pola seperti dalam contoh berikut untuk mengatur nilai fallback untuk parameter yang berbeda dalam kueri yang sama.

CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

Dalam contoh ini, :static_param mengacu pada parameter statis, yang harus diatur ke 'Semua' di widget visualisasi dan editor himpunan data. Parameter :dash_param adalah nilai dinamis yang dikontrol oleh widget filter di kanvas dasbor. Pernyataan ini memeriksa nilai yang disediakan sebagai parameter statis. Jika tidak ada yang diatur, parameter tersebut akan default ke nilai parameter dasbor yang dipilih oleh pemirsa.

Sertakan parameter dalam URL

Pengaturan parameter disimpan di URL, memungkinkan pengguna untuk menandainya untuk mempertahankan status dasbor mereka, termasuk filter dan parameter yang telah ditetapkan sebelumnya, atau membagikannya dengan orang lain untuk menerapkan filter dan parameter yang sama secara konsisten.

Parameter papan kendali vs. Parameter kueri Mustache

Parameter Dashboard menggunakan sintaks yang sama dengan penanda parameter bernama. Lihat Penanda parameter bernama. Dasbor tidak mendukung parameter gaya Mustache.

Contoh sintaks

Penggunaan umum untuk parameter termasuk menyisipkan tanggal, angka, teks, objek database, dan nilai dari string JSON. Untuk contoh yang menunjukkan cara menggunakan parameter dalam kasus ini, lihat contoh sintaks parameter bernama.