Antarmuka SQL Terbuka

Lapisan pemodelan semantik LookML Looker memungkinkan analis data menentukan dimensi, agregat, kalkulasi, dan hubungan data dalam database SQL. Model LookML menyediakan penggunaan kembali kode dan integrasi Git. Model LookML yang terstruktur dengan baik mendorong pengguna untuk melakukan eksplorasi dan pelaporan data secara mandiri.

Model LookML adalah dasar untuk setiap data yang diminta dari Looker, baik permintaan tersebut berasal dari antarmuka Jelajah Looker di UI Looker, visualisasi tersemat di portal perusahaan Anda atau aplikasi pihak ketiga lainnya, maupun aplikasi kustom yang dikembangkan dengan Looker API. Antarmuka Open SQL menyediakan akses ke model LookML ke aplikasi pihak ketiga yang mendukung Java Database Connectivity (JDBC). Aplikasi dapat terhubung ke model LookML seolah-olah itu adalah database, yang memungkinkan pengguna memanfaatkan semua pekerjaan yang dilakukan oleh analis data mereka dalam model LookML, sambil menggunakan alat apa pun yang paling nyaman bagi mereka.

Bagaimana Open SQL Interface memunculkan elemen project LookML

Untuk memahami cara Open SQL Interface menampilkan elemen project LookML, Anda harus memahami struktur project LookML.

Project LookML adalah kumpulan file yang mendeskripsikan objek, koneksi database, dan elemen antarmuka pengguna yang digunakan untuk menjalankan kueri SQL di Looker (lihat istilah dan konsep LookML untuk informasi selengkapnya). Konsep project LookML berikut terkait dengan Antarmuka Open SQL:

  • model LookML menentukan koneksi database dan satu atau beberapa Jelajah. Antarmuka Open SQL menampilkan model sebagai skema database.
  • Penjelajahan adalah pengelompokan logis dari satu atau beberapa tampilan dan hubungan gabungan di antara tampilan tersebut. Antarmuka Open SQL menampilkan Jelajah sebagai tabel database.
  • Tampilan menentukan kumpulan kolom (dimensi dan ukuran). Tampilan umumnya didasarkan pada tabel dalam database Anda atau tabel turunan. Tampilan dapat berisi kolom dari tabel database pokok serta ukuran atau dimensi kustom apa pun yang mungkin diperlukan oleh pengguna akhir Anda. Open SQL Interface menampilkan kombinasi nama tampilan dan nama kolom sebagai nama kolom database. Misalnya, dimensi id dalam tampilan order_items ditampilkan oleh Open SQL Interface sebagai kolom database yang disebut order_items.id.

Jelajah Looker dapat menentukan hubungan gabungan antara beberapa tampilan. Karena satu tampilan dapat memiliki kolom dengan nama yang sama dengan kolom dalam tampilan yang berbeda, Open SQL Interface akan menyertakan nama tampilan dan nama kolom saat mereferensikan kolom. Oleh karena itu, gunakan format ini untuk mereferensikan nama kolom saat mengirim kueri ke Antarmuka Open SQL:

`<view_name>.<field_name>`

Misalnya, jika ada Jelajah bernama order_items yang menggabungkan tampilan bernama customer dengan tampilan yang disebut product dan kedua tampilan ini memiliki dimensi id, Anda akan merujuk ke dua kolom id sebagai `customer.id` dan `product.id`. Untuk menggunakan nama yang sepenuhnya memenuhi syarat dengan nama Jelajah, Anda harus merujuk ke dua kolom sebagai `order_items`.`customer.id` dan `order_items`.`product.id`. (Lihat Menggunakan tanda kutip terbalik untuk ID database untuk mengetahui informasi tentang tempat meletakkan tanda kutip terbalik saat merujuk ke ID database.)

Menyiapkan Antarmuka SQL Terbuka

Untuk menggunakan Antarmuka Open SQL, lakukan langkah-langkah berikut:

  1. Verifikasi bahwa persyaratan terpenuhi.
  2. Aktifkan Open SQL Interface di instance Looker Anda.
  3. Download file driver JDBC Open SQL Interface.

Bagian berikut menjelaskan langkah-langkah ini.

Persyaratan

Komponen berikut diperlukan untuk menggunakan Antarmuka Open SQL:

Mengaktifkan Antarmuka Open SQL di instance Looker

Aktifkan Antarmuka Open SQL di instance Anda dengan melakukan langkah-langkah berikut:

Mendownload driver JDBC Open SQL Interface

Driver JDBC Antarmuka Open SQL Looker disebut avatica-<release_number>-looker.jar. Download versi terbaru dari GitHub di https://github.com/looker-open-source/calcite-avatica/releases.

Driver JDBC mengharapkan format URL berikut:

jdbc:looker:url=https://your Looker instance URL

Contoh:

jdbc:looker:url=https://myInstance.cloud.looker.com

Class driver JDBC adalah:

org.apache.calcite.avatica.remote.looker.LookerDriver

Mengautentikasi ke Open SQL Interface

Antarmuka Open SQL mendukung tiga metode untuk otentikasi:

OAuth

Klien JDBC yang mendukung OAuth dapat dikonfigurasi untuk menggunakan server OAuth instance Looker. Ikuti langkah-langkah untuk mengonfigurasi autentikasi OAuth:

  1. Gunakan ekstensi API Explorer untuk mendaftarkan klien OAuth JDBC dengan instance Looker Anda sehingga instance Looker dapat mengenali permintaan OAuth. Lihat Mendaftarkan aplikasi klien OAuth untuk mengetahui petunjuknya.
  2. Login ke Looker dengan OAuth untuk meminta token akses. Lihat Melakukan login pengguna menggunakan OAuth untuk mengetahui contohnya.
  3. Gunakan objek Properties untuk meneruskan kredensial OAuth saat membuka koneksi JDBC ke Open SQL Interface.

Berikut adalah contoh yang menggunakan DriverManager#getConnection(<String>, <Properties>`):

String access_token = getAccessToken() //uses the Looker OAuth flow to get a token
String URL = "jdbc:looker:url=https://myInstance.cloud.looker.com"
Properties info = new Properties( );
info.put("token", access_token);
Connection conn = DriverManager.getConnection(URL, info);

Membuat token akses menggunakan kunci API

Daripada menggunakan alur OAuth standar untuk membuat token akses, Anda dapat mengikuti langkah-langkah berikut untuk menggunakan Looker API guna membuat token akses yang dapat diteruskan ke driver JDBC Open SQL Interface:

  1. Buat Kunci API untuk pengguna Looker Anda seperti yang dijelaskan di halaman Setelan admin - Pengguna.

  2. Gunakan endpoint login API untuk instance Looker Anda. Responsnya akan menyertakan token akses dalam format: Authorization: token <access_token>. Berikut adalah contoh perintah curl untuk membuat permintaan ini:

      curl -k -d "client_id=<client_id>&client_secret=<client_secret>" https://<looker_host>/login\

  3. Teruskan nilai <access_token> respons sebagai token di Properties object untuk meneruskan kredensial OAuth saat membuka koneksi JDBC ke Open SQL Interface.

Kunci API

Anda juga bisa menggunakan kunci API untuk mengautentikasi sebagai pengganti nama pengguna dan sandi. Kunci API dianggap kurang aman dibandingkan OAuth dan mungkin hanya tersedia selama pratinjau Antarmuka Open SQL. Lihat Kunci API untuk mendapatkan informasi tentang cara membuat kunci API untuk instance Looker Anda.

Gunakan bagian Client ID dari kunci Looker API sebagai nama pengguna. Gunakan bagian Rahasia Klien untuk sandi.

Menjalankan kueri dengan Antarmuka Open SQL

Perhatikan panduan berikut saat menjalankan kueri dengan Antarmuka Open SQL:

Batasan LookML

Perhatikan batasan LookML berikut saat mengirim kueri ke Antarmuka Open SQL:

Batasan SQL

Perhatikan batasan SQL berikut saat mengirim kueri ke Antarmuka Open SQL:

Menggunakan {i>backtick<i} pada ID database

Saat mengirim kueri ke Open SQL Interface, gunakan {i>backtick<i} di sekitar ID skema, tabel, dan kolom. Berikut cara menentukan elemen database menggunakan tanda kutip terbalik dengan istilah Looker:

  • skema: `<model_name>`
  • tabel: `<explore_name>`

  • kolom: `<view_name>.<field_name>`

Berikut adalah contoh format pernyataan SELECT yang menggunakan elemen ini:

SELECT `view.field`
  FROM `model`.`explore`
  LIMIT 10;

Menentukan tindakan LookML dengan AGGREGATE()

Tabel database biasanya hanya berisi dimensi, yaitu data yang menjelaskan satu atribut tentang baris dalam tabel. Namun, project LookML dapat menentukan dimensi dan ukuran. Pengukuran adalah agregasi data di beberapa baris, seperti SUM, AVG, MIN, atau MAX. (Jenis tindakan lain juga didukung, lihat halaman Jenis pengukuran untuk daftar lengkap jenis pengukuran LookML yang didukung.)

Dengan Open SQL Interface, Anda harus menentukan tindakan LookML yang disertakan dalam kueri dengan menggabungkan ukuran (termasuk tanda aksen rendah) dalam fungsi khusus AGGREGATE(). Misalnya, gunakan atribut ini untuk menentukan ukuran count dari tampilan pesanan:

AGGREGATE(`orders.count`)

Anda harus menggabungkan ukuran LookML dalam fungsi AGGREGATE(), baik pengukuran tersebut berada dalam klausa SELECT, klausa HAVING, atau klausa ORDER BY.

Jika tidak yakin apakah kolom merupakan ukuran LookML, Anda dapat menggunakan metode DatabaseMetaData.getColumns untuk mengakses metadata project LookML. Kolom IS_GENERATEDCOLUMN akan menunjukkan YES untuk ukuran LookML, dan NO untuk dimensi LookML. Lihat bagian Mengakses metadata database untuk informasi selengkapnya.

Contoh

Berikut adalah contoh kueri yang menggunakan dimensi dan ukuran. Kueri ini mengambil dimensi state dan state dari tampilan state dan ukuran state dari tampilan state. Kedua tampilan ini digabungkan ke dalam Jelajah pesanan dalam model e-commerce. Untuk kota yang memiliki lebih dari 10 pesanan, respons kueri ini menampilkan 5 kota teratas berdasarkan jumlah pesanan:

SELECT `customers.state`, `customers.city`,
  AGGREGATE(`orders.total_amount`)
FROM `ecommerce`.`orders`
GROUP BY `customers.state`, `customers.city`
HAVING AGGREGATE(`orders.count`) > 10
ORDER BY 3 DESC LIMIT 5;

Mengakses {i>metadata<i} dari {i>database<i}

Antarmuka Open SQL mendukung subset antarmuka DatabaseMetaData JDBC standar, yang digunakan untuk memperoleh informasi tentang database yang mendasarinya. Anda dapat menggunakan metode antarmuka DatabaseMetaData berikut untuk mendapatkan informasi tentang model LookML Anda:

DatabaseMetadata.getSchemas

Tabel berikut menjelaskan bagaimana model LookML berkaitan dengan struktur database standar sebagai respons metode antarmuka DatabaseMetadata.getSchemas.

getSchemas kolom jawaban Deskripsi
TABLE_SCHEM Nama model LookML
TABLE_CATALOG (null)

DatabaseMetadata.getTables

Tabel berikut menjelaskan bagaimana model LookML berkaitan dengan struktur database sebagai respons metode antarmuka DatabaseMetaData.getTables. Responsnya mencakup metadata JDBC standar serta metadata khusus Looker:

getTables kolom jawaban Deskripsi
Metadata standar JDBC
TABLE_CAT (null)
TABLE_SCHEM Nama model LookML
TABLE_NAME nama Jelajah LookML
TABLE_TYPE Selalu menampilkan nilai TABLE_TYPE
Metadata khusus Looker
DESCRIPTION Jelajahi deskripsi
LABEL Jelajahi label
TAGS Pelajari tag

DatabaseMetadata.getColumns

Tabel berikut menjelaskan bagaimana model LookML berkaitan dengan struktur database sebagai respons metode antarmuka DatabaseMetaData.getColumns. Responsnya mencakup metadata JDBC standar serta metadata khusus Looker:

getColumns kolom jawaban Deskripsi
Metadata standar JDBC
TABLE_CAT (null)
TABLE_SCHEM Nama model LookML
TABLE_NAME Nama Jelajah LookML
COLUMN_NAME Nama kolom LookML dalam format `<view_name>.<field_name>`. Contoh, `orders.amount`.
DATA_TYPE Kode java.sql.Types kolom. Misalnya, Kolom yesno Looker adalah kode jenis SQL 16 (BOOLEAN).
ORDINAL_POSITION Ordinal berbasis 1 untuk kolom dalam Explore (menggabungkan dimensi dan mengukur secara alfabetis berdasarkan nama tampilan, lalu nama kolom)
IS_NULLABLE Selalu menampilkan nilai YES
IS_GENERATEDCOLUMN YES untuk ukuran, NO untuk dimensi
Metadata khusus Looker
DIMENSION_GROUP Nama grup dimensi jika kolom adalah bagian dari grup dimensi. Jika kolom bukan bagian dari grup dimensi, kolom ini akan menjadi null.
DRILL_FIELDS Daftar kolom bor yang ditetapkan untuk dimensi atau ukuran, jika ada
FIELD_ALIAS Alias untuk kolom tersebut, jika ada
FIELD_CATEGORY Apakah kolom berupa dimension atau measure
FIELD_DESCRIPTION Deskripsi kolom
FIELD_GROUP_VARIANT Jika kolom ditampilkan dalam label grup kolom, FIELD_GROUP_VARIANT akan menentukan nama kolom yang lebih pendek yang ditampilkan di bawah label grup.
FIELD_LABEL Label kolom
FIELD_NAME Nama dimensi atau ukuran
HIDDEN Apakah kolom disembunyikan dari pemilih kolom di Jelajah (TRUE), atau apakah kolom tersebut terlihat di alat pilih kolom di Jelajah (FALSE).
LOOKER_TYPE Jenis kolom LookML untuk dimensi atau measure
REQUIRES_REFRESH_ON_SORT Apakah kueri SQL harus dimuat ulang untuk mengurutkan ulang nilai kolom (TRUE), atau jika nilai kolom dapat diurutkan ulang tanpa memerlukan pemuatan ulang kueri SQL (FALSE).
SORTABLE Apakah kolom dapat diurutkan (TRUE) atau tidak dapat diurutkan (FALSE)
TAGS Tag kolom
USE_STRICT_VALUE_FORMAT Apakah kolom menggunakan format nilai ketat (TRUE) atau tidak (FALSE)
VALUE_FORMAT String format nilai untuk kolom
VIEW_LABEL Lihat label untuk kolom
VIEW_NAME Nama tampilan tempat kolom ditentukan dalam project LookML

Mengidentifikasi kueri Antarmuka Open SQL di UI Looker

Admin Looker dapat menggunakan UI Looker untuk mengidentifikasi kueri yang berasal dari Antarmuka Open SQL:

  • Di halaman admin Queries, kueri dari Open SQL Interface memiliki nilai Source untuk "Sql Interface". Nilai Pengguna akan menampilkan nama pengguna Looker yang menjalankan kueri.

  • Di bagian System Activity History Explore, kueri dari Antarmuka Open SQL memiliki nilai Source "sql_interface". Nilai Email Pengguna akan menampilkan alamat email pengguna Looker yang menjalankan kueri. Anda dapat langsung membuka History Explore yang difilter pada "sql_interface" dengan memasukkan alamat instance Looker Anda ke awal URL ini:

    https://your Looker instance URL/explore/system__activity/history?fields=history.source,history.completed_date&f[history.source]=sql_interface

Masukan untuk Antarmuka Open SQL

Hubungi looker-sql-interface@google.com jika Anda memiliki pertanyaan atau permintaan fitur untuk Open SQL Interface.