Menggunakan fungsi `remote_query` untuk mengkueri database eksternal

Penting

Fungsi remote_query bernilai tabel (TVF) memungkinkan Anda menjalankan kueri SQL langsung terhadap database eksternal dan gudang data dari dalam Azure Databricks, menggunakan sintaks SQL asli dari sistem jarak jauh. Fungsi ini menyediakan alternatif yang fleksibel untuk federasi kueri, memungkinkan Anda menjalankan kueri yang ditulis dalam dialek database jarak jauh tanpa perlu menerjemahkannya ke Databricks SQL.

`remote_query` dibandingkan dengan federasi kueri

Tabel berikut ini meringkas perbedaan utama antara remote_query fungsi dan federasi kueri:

Attribute	fungsi `remote_query`	Federasi kueri
Sintaks kueri	Tulis kueri menggunakan dialek SQL asli database jarak jauh (misalnya, Oracle PL/SQL, BigQuery SQL).	Tulis kueri menggunakan sintaks Databricks SQL. Databricks menerjemahkan dan mengalirkan operasi yang kompatibel ke basis data jarak jauh.
Skenario penggunaan	Anda memiliki kueri SQL yang sudah ada yang ditulis dalam dialek database jarak jauh yang ingin Anda jalankan tanpa modifikasi. Anda perlu menggunakan fungsi atau sintaks khusus database yang mungkin tidak tersedia di Databricks SQL. Anda ingin akses ad hoc ke data jarak jauh tanpa membuat katalog asing.	Anda ingin mengkueri data eksternal menggunakan sintaks Databricks SQL. Anda memerlukan pola akses data jangka panjang dengan akses yang diatur melalui katalog asing Unity Catalog. Anda ingin menggabungkan data dari beberapa sumber dalam satu kueri menggunakan sintaks yang konsisten. Anda ingin menggunakan asisten Genie untuk menulis kueri.
Kontrol akses	Pengguna memerlukan `USE CONNECTION` hak istimewa pada koneksi. Izin dapat didelegasikan melalui tampilan.	Pengguna memerlukan hak istimewa tingkat tabel pada objek katalog asing. Kontrol terperinci.

Sebelum Anda mulai

Persyaratan ruang kerja:

Workspace telah diaktifkan untuk Unity Catalog.

Persyaratan komputasi:

Konektivitas jaringan dari kluster Databricks Runtime atau gudang SQL Anda ke sistem database target. Lihat Rekomendasi jaringan untuk Lakehouse Federation.
Kluster Azure Databricks harus menggunakan Databricks Runtime 17.3 atau lebih tinggi.
Gudang SQL harus Pro atau Tanpa Server dan menggunakan versi 2025.35 atau lebih tinggi.

Izin diperlukan:

Untuk membuat koneksi, Anda harus memiliki CREATE CONNECTION hak istimewa pada metastore Katalog Unity.
Untuk menggunakan remote_query fungsi, Anda harus memiliki USE CONNECTION hak istimewa pada koneksi atau SELECT hak istimewa pada tampilan yang membungkus fungsi. Kluster pengguna tunggal juga memerlukan MANAGE izin untuk koneksi.

Buat koneksi

Untuk menggunakan fungsi remote_query ini, pertama-tama Anda perlu membuat koneksi Katalog Unity ke database eksternal Anda. Jika Anda sudah memiliki koneksi yang dibuat untuk federasi kueri, Anda bisa menggunakannya kembali.

Fungsi ini remote_query mendukung koneksi ke jenis koneksi berikut:

Untuk informasi tentang mengelola koneksi yang ada, lihat Pengelolaan Koneksi untuk Lakehouse Federation.

Memberikan akses koneksi

Untuk menggunakan fungsi remote_query, Anda harus memiliki hak istimewa USE CONNECTION di koneksi (atau hak istimewa MANAGE di kluster pengguna tunggal).

GRANT USE CONNECTION ON CONNECTION <connection-name> TO <user-or-group>;

Menggunakan fungsi `remote_query`

Fungsi menjalankan remote_query kueri pada database jarak jauh dan mengembalikan hasil sebagai tabel yang bisa Anda gunakan dalam kueri Databricks SQL.

Syntax

SELECT * FROM remote_query(
  '<connection-name>',
  <option-key> => '<option-value>'
  [, <option-key> => '<option-value>' ...]
)

Parameter yang diperlukan

connection-name: Nama koneksi Katalog Unity yang akan digunakan.

Semua parameter lain yang diperlukan bervariasi menurut jenis koneksi. Lihat Opsi khusus konektor untuk detailnya.

Opsi khusus konektor

Opsi yang tersedia bervariasi menurut jenis koneksi. Tabel berikut ini menjelaskan opsi untuk setiap konektor.

MySQL, PostgreSQL, SQL Server, Redshift, dan Teradata

Pengaturan	Diperlukan	Description
`database`	Yes	Nama database pada sistem jarak jauh.
`query`	Ya (atau `dbtable`)	String kueri SQL untuk dieksekusi pada basis data jarak jauh. Tidak dapat digunakan dengan `dbtable`.
`dbtable`	Ya (atau `query`)	Nama tabel yang akan dikueri. Tidak dapat digunakan dengan `query`.
`fetchsize`	Tidak.	Jumlah baris yang diambil per perjalanan pulang pergi. Nilai yang lebih besar dapat meningkatkan performa tetapi menggunakan lebih banyak memori. Default: 0 (gunakan Default Driver).
`partitionColumn`	Tidak.	Kolom dengan nilai yang didistribusikan secara seragam untuk digunakan untuk pengambilan data paralel. Harus digunakan dengan `lowerBound`, `upperBound`, dan `numPartitions`. Tidak dapat digunakan dengan `query` opsi .
`lowerBound`	Tidak.	Nilai minimum kolom partisi. Harus digunakan dengan `partitionColumn`, `upperBound`, dan `numPartitions`.
`upperBound`	Tidak.	Nilai maksimum kolom partisi. Harus digunakan dengan `partitionColumn`, `lowerBound`, dan `numPartitions`.
`numPartitions`	Tidak.	Jumlah koneksi paralel yang digunakan untuk mengambil data. Jangan tentukan ini terlalu tinggi (ratusan). Harus digunakan dengan `partitionColumn`, `lowerBound`, dan `upperBound`.

Nota

Ketika Anda menggunakan parameter partisi, keempat parameter (partitionColumn, , lowerBound, upperBoundnumPartitions) harus ditentukan bersama-sama, dan Anda harus menggunakan dbtable opsi alih-alih query.

Oracle

Pengaturan	Diperlukan	Description
`service_name`	Yes	Nama layanan Oracle (digunakan alih-alih `database`).
`query`	Ya (atau `dbtable`)	String kueri SQL untuk dieksekusi pada basis data jarak jauh. Tidak dapat digunakan dengan `dbtable`.
`dbtable`	Ya (atau `query`)	Nama tabel yang akan dikueri. Tidak dapat digunakan dengan `query`.
`fetchsize`	Tidak.	Jumlah baris yang diambil per perjalanan pulang pergi. Nilai yang lebih besar dapat meningkatkan performa tetapi menggunakan lebih banyak memori. Default: 0 (gunakan Default Driver).
`partitionColumn`	Tidak.	Kolom dengan nilai yang didistribusikan secara seragam untuk digunakan untuk pengambilan data paralel. Harus digunakan dengan `lowerBound`, `upperBound`, dan `numPartitions`. Tidak dapat digunakan dengan `query` opsi .
`lowerBound`	Tidak.	Nilai minimum kolom partisi. Harus digunakan dengan `partitionColumn`, `upperBound`, dan `numPartitions`.
`upperBound`	Tidak.	Nilai maksimum kolom partisi. Harus digunakan dengan `partitionColumn`, `lowerBound`, dan `numPartitions`.
`numPartitions`	Tidak.	Jumlah koneksi paralel yang digunakan untuk mengambil data. Jangan tentukan ini terlalu tinggi (ratusan). Harus digunakan dengan `partitionColumn`, `lowerBound`, dan `upperBound`.

Nota

Snowflake

Pengaturan	Diperlukan	Description
`database`	Yes	Nama database di Snowflake.
`query`	Ya (atau `dbtable`)	String kueri SQL untuk dieksekusi pada basis data jarak jauh. Tidak dapat digunakan dengan `dbtable`.
`dbtable`	Ya (atau `query`)	Nama tabel untuk dikueri (nama bagian tunggal atau nama multi-bagian). Tidak dapat digunakan dengan `query`.
`schema`	Tidak.	Nama skema di Snowflake. Standar: `public`.
`query_timeout`	Tidak.	Batas waktu tunggu kueri dalam detik. Default: 0 (tidak ada batas waktu).
`partition_size_in_mb`	Tidak.	Ukuran partisi yang diharapkan dalam megabyte untuk pengambilan data paralel. Default: 100 MB.

BigQuery

Pengaturan	Diperlukan	Description
`query`	Ya (atau `dbtable`)	String kueri SQL untuk dieksekusi pada basis data jarak jauh. Tidak dapat digunakan dengan `dbtable`.
`dbtable`	Ya (atau `query`)	Nama tabel yang akan dikueri. Tidak dapat digunakan dengan `query`.
`materializationDataset`	Ya jika materialisasi hasil diperlukan. Materialisasi diperlukan jika `query` ditentukan dan jika `dbtable` menunjuk ke tampilan.	Nama himpunan data BigQuery tempat tabel sementara diwujudkan. Time-to-live (TTL) tabel sementara secara default adalah 24 jam.
`materializationProject`	Tidak.	ID proyek BigQuery untuk proses materialisasi. Default ke proyek yang ditentukan dalam koneksi.
`materializationEnabled`	Tidak.	Apakah akan mengaktifkan materialisasi untuk kueri. Setel `true` untuk memeriksa tampilan. Default: `false` jika `dbtable` ditentukan, `true` jika `query` ditentukan.
`parentProject`	Tidak.	ID proyek induk untuk tujuan penagihan.

Penting

Semua parameter BigQuery peka terhadap huruf besar/kecil.

Opsi kontrol pushdown tambahan

Anda dapat menggabungkan remote_query fungsi dengan operasi Databricks SQL, dan sebagian besar operasi tersebut juga dapat didorong ke bawah. Anda juga dapat mengontrol operasi Databricks SQL mana yang dapat didorong ke bawah. Opsi ini berlaku untuk semua jenis koneksi dan tidak sensitif terhadap huruf besar/kecil.

Pengaturan	Bawaan	Description
`pushdown.limit.enabled`	`true`	Aktifkan atau nonaktifkan pendorongan `LIMIT` klausa ke database jarak jauh.
`pushdown.offset.enabled`	`true`	Aktifkan atau nonaktifkan pendorongan `OFFSET` klausa ke database jarak jauh.
`pushdown.filters.enabled`	`true`	Aktifkan atau nonaktifkan pendorongan `WHERE` filter ke database jarak jauh.
`pushdown.aggregates.enabled`	`true`	Aktifkan atau nonaktifkan pendorongan fungsi agregat (`COUNT`, `SUM`, `AVG`, `MAX`, `MIN`) ke database jarak jauh.
`pushdown.sortLimit.enabled`	`true`	Aktifkan atau nonaktifkan penerusan kueri top-N (kombinasi `ORDER BY` dan `LIMIT`) ke database jarak jauh.

Secara default, semua pushdown diaktifkan. Anda dapat menonaktifkan pushdown tertentu jika diperlukan untuk pemecahan masalah atau mengatasi masalah kompatibilitas dengan database jarak jauh tertentu.

Mendelegasikan akses melalui antarmuka tampilan

Anda dapat mendelegasikan akses ke data jarak jauh tanpa memberikan hak istimewa langsung USE CONNECTION kepada pengguna dengan membungkus remote_query fungsi dalam tampilan. Pendekatan ini memiliki manfaat berikut:

Kontrol akses yang disederhanakan: Berikan SELECT hak istimewa pada tampilan alih-alih mengelola USE CONNECTION hak istimewa.
Keamanan data: Mengontrol kolom dan baris mana yang dapat diakses pengguna dengan menentukan kueri tampilan.
Lacak silsilah data: Lacak akses data melalui silsilah tampilan daripada penggunaan koneksi langsung.

Untuk mendelegasikan akses melalui tampilan:

Buat tampilan yang memanggil remote_query fungsi:

CREATE VIEW sales_data_view AS
SELECT * FROM remote_query(
  'my_connection',
  database => 'sales_db',
  query => 'SELECT region, product, revenue FROM sales'
);

Berikan SELECT hak istimewa pada tampilan kepada pengguna atau grup:
```
GRANT SELECT ON VIEW sales_data_view TO <user-or-group>;
```
Pengguna sekarang dapat mengkueri tampilan tanpa memerlukan USE CONNECTION hak istimewa:
```
SELECT * FROM sales_data_view WHERE region = 'US';
```

Penting

Pemilik tampilan harus memiliki USE CONNECTION hak istimewa pada koneksi. Saat pengguna mengkueri tampilan, pemeriksaan akses koneksi dilakukan menggunakan hak istimewa pemilik tampilan, bukan hak istimewa pengguna yang mengkueri.

Examples

Eksekusi kueri dasar

Jalankan kueri pada database PostgreSQL:

SELECT * FROM remote_query(
  'my_postgres_connection',
  database => 'sales_db',
  query => 'SELECT * FROM orders WHERE order_date > CURRENT_DATE - INTERVAL \'30 days\''
);

Mengkueri tabel tertentu

Mengkueri tabel MySQL secara langsung:

SELECT * FROM remote_query(
  'my_mysql_connection',
  database => 'inventory',
  dbtable => 'my_schema.products'
);

Oracle dengan nama layanan

Menjalankan kueri pada database Oracle:

SELECT * FROM remote_query(
  'my_oracle_connection',
  service_name => 'ORCL',
  query => 'SELECT * FROM customers WHERE ROWNUM <= 1000'
);

Kueri BigQuery

Kueri Google BigQuery:

SELECT * FROM remote_query(
  'my_bigquery_connection',
  materializationDataset => 'analytics',
  query => 'SELECT * FROM `project.dataset.table` WHERE created_date > DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)'
);

Kueri Snowflake

Kueri Snowflake:

SELECT * FROM remote_query(
  'my_snowflake_connection',
  database => 'ANALYTICS_DB',
  query => 'SELECT * FROM SALES WHERE SALE_DATE >= DATEADD(day, -30, CURRENT_DATE())'
);

Penyetelan performa dengan pemartisian

Ambil data secara paralel dari tabel SQL Server:

SELECT * FROM remote_query(
  'my_sqlserver_connection',
  database => 'sales',
  dbtable => 'transactions',
  partitionColumn => 'transaction_id',
  lowerBound => '0',
  upperBound => '1000000',
  numPartitions => '10',
  fetchsize => '1000'
);

Gabungkan dengan operasi Databricks SQL

Terapkan filter dan transformasi tambahan:

SELECT customer_id, SUM(amount) as total_amount
FROM remote_query(
  'my_postgres_connection',
  database => 'orders_db',
  query => 'SELECT customer_id, amount, order_date FROM orders'
)
WHERE order_date >= '2025-01-01'
GROUP BY customer_id
HAVING total_amount > 1000
ORDER BY total_amount DESC
LIMIT 100;

Membuat tampilan untuk akses yang didelegasikan

Buat tampilan yang membungkus fungsi remote_query. Pengguna dengan SELECT hak istimewa pada tampilan dapat mengkueri data tanpa memerlukan USE CONNECTION hak istimewa pada koneksi yang mendasar:

CREATE VIEW sales_summary AS
SELECT * FROM remote_query(
  'my_mysql_connection',
  database => 'sales',
  query => 'SELECT region, product, SUM(revenue) as total_revenue FROM sales_data GROUP BY region, product'
);

GRANT SELECT ON VIEW sales_summary TO <user-or-group>;

Mengontrol perilaku pushdown

Saat Anda menggunakan fungsi remote_query, Databricks dapat meneruskan operasi tambahan ke database jarak jauh di luar kueri yang Anda tentukan. Fitur ini berguna saat Anda mengkueri tampilan yang menggunakan remote_query fungsi .

Operasi berikut dapat didorong ke bawah:

Filter: WHERE klausa yang diterapkan ke hasil kueri jarak jauh
Proyeksi: Pemilihan kolom (SELECT kolom tertentu)
Batas: LIMIT klausa untuk membatasi jumlah baris yang dikembalikan
Offset: OFFSET klausa untuk melewati baris
Agregat: Fungsi agregasi seperti COUNT, , SUMAVG, MAX,MIN
Top-N: Kombinasi ORDER BY dan LIMIT untuk kueri N atas/bawah

Dukungan pushdown bervariasi tergantung pada sumber data. Lihat dokumentasi untuk jenis koneksi spesifik Anda untuk detailnya.

Nonaktifkan pushdown tertentu untuk pemecahan masalah atau kompatibilitas:

SELECT * FROM remote_query(
  'my_postgres_connection',
  database => 'analytics',
  query => 'SELECT * FROM complex_view',
  `pushdown.aggregates.enabled` => 'false',
  `pushdown.filters.enabled` => 'false'
);

Keterbatasan

Operasi baca-saja: Fungsi remote_query hanya mendukung SELECT kueri. Operasi modifikasi data (INSERT, , UPDATEDELETE, MERGE), operasi DDL (CREATE, DROP, ALTER) dan prosedur tersimpan tidak didukung.
Validasi kueri: Kueri yang Anda berikan dijalankan langsung pada database jarak jauh. Databricks memvalidasi bahwa kueri bersifat baca-saja dengan melakukan inspeksi skema, tetapi validasi sintaksis dan semantik dilakukan oleh database jarak jauh.

Troubleshooting

Kesalahan izin

Jika Anda menerima kesalahan izin, verifikasi bahwa:

Anda memiliki USE CONNECTION hak istimewa pada koneksi atau SELECT hak istimewa pada tampilan yang membungkus fungsi.
Kredensial dalam koneksi memiliki izin yang sesuai pada database jarak jauh.

Contoh kesalahan:

PERMISSION_DENIED: User does not have USE CONNECTION on Connection 'my_connection'

Resolusi:

GRANT USE CONNECTION ON CONNECTION my_connection TO <user-or-group>;

Parameter yang tidak didukung

Jika Anda menerima kesalahan tentang parameter yang tidak didukung, periksa apakah Anda menggunakan parameter yang benar untuk jenis koneksi Anda. Pesan kesalahan mencantumkan parameter yang diizinkan.

Contoh kesalahan:

REMOTE_QUERY_FUNCTION_UNSUPPORTED_CONNECTOR_PARAMETERS: The following parameters are not supported for connection type 'postgresql': 'materializationDataset'. Allowed parameters for this connection type are: 'database', 'query', 'dbtable', 'fetchsize', 'partitionColumn', 'lowerBound', 'upperBound', 'numPartitions'.

Resolusi: Hapus parameter yang tidak didukung dan gunakan parameter yang benar untuk jenis koneksi Anda.

Operasi DML tidak didukung

Fungsi ini remote_query hanya mendukung kueri baca-saja SELECT .

Contoh kesalahan:

DML_OPERATIONS_NOT_SUPPORTED_FOR_REMOTE_QUERY_FUNCTION: Data modification operations are not supported in remote_query function.

Resolusi: Hapus setiap pernyataan INSERT, UPDATE, DELETE, atau DDL dari kueri Anda. Hanya gunakan SELECT instruksi.

Sumber daya tambahan

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-01-30

Menggunakan fungsi remote_query untuk mengkueri database eksternal

remote_query dibandingkan dengan federasi kueri

Sebelum Anda mulai

Buat koneksi

Memberikan akses koneksi

Menggunakan fungsi remote_query

Syntax

Parameter yang diperlukan

Opsi khusus konektor

MySQL, PostgreSQL, SQL Server, Redshift, dan Teradata

Oracle

Snowflake

BigQuery

Opsi kontrol pushdown tambahan

Mendelegasikan akses melalui antarmuka tampilan

Examples

Eksekusi kueri dasar

Mengkueri tabel tertentu

Oracle dengan nama layanan

Kueri BigQuery

Kueri Snowflake

Penyetelan performa dengan pemartisian

Gabungkan dengan operasi Databricks SQL

Membuat tampilan untuk akses yang didelegasikan

Mengontrol perilaku pushdown

Keterbatasan

Troubleshooting

Kesalahan izin

Parameter yang tidak didukung

Operasi DML tidak didukung

Sumber daya tambahan

Saran dan Komentar

Sumber Daya Tambahan:

Menggunakan fungsi `remote_query` untuk mengkueri database eksternal

`remote_query` dibandingkan dengan federasi kueri

Menggunakan fungsi `remote_query`