Запрос внешних баз данных с помощью remote_query функции

Функция remote_query с табличным значением (TVF) позволяет выполнять SQL-запросы непосредственно в внешних базах данных и хранилищах данных из Azure Databricks с помощью собственного синтаксиса SQL удаленной системы. Эта функция предоставляет гибкую альтернативу федерации запросов, позволяя выполнять запросы, написанные на диалекте удаленной базы данных без необходимости переводить их в Databricks SQL.

remote_query по сравнению с федерацией запросов

В следующей таблице приведены основные различия между функцией remote_query и федерацией запросов.

Перед тем как начать

Требования к рабочей области:

• Рабочая область активирована для Unity Catalog.

Требования к вычислениям:

• Сетевое подключение из кластера среды выполнения Databricks или хранилища SQL к целевым системам баз данных. Смотрите Рекомендации по сетевым настройкам для федерации Lakehouse.
• Кластеры Azure Databricks должны использовать Databricks Runtime 17.3 или более поздней версии.
• Хранилища SQL должны быть Pro или Serverless и использовать версию 2025.35 или выше.

Необходимые разрешения:

• Чтобы создать подключение, необходимо иметь привилегии CREATE CONNECTION в хранилище метаданных каталога Unity.
• Чтобы использовать функцию remote_query, необходимо иметь привилегию USE CONNECTION на подключение или привилегию SELECT на представление, которое оборачивает функцию. Для кластеров с одним пользователем также требуется MANAGE разрешение на подключение.

Создание подключения

Чтобы использовать функцию remote_query , сначала необходимо создать подключение каталога Unity к внешней базе данных. Если у вас уже есть подключение, созданное для федерации запросов, его можно использовать повторно.

Функция remote_query поддерживает подключения к следующим типам подключений:

• MySQL
• PostgreSQL
• Teradata
• Oracle
• Amazon Redshift
• Snowflake
• Microsoft SQL Server
• Google BigQuery

Для получения сведений об управлении существующими подключениями см. статью Управление подключениями для федерации Lakehouse.

Предоставление доступа к подключению

Чтобы использовать remote_query функциональность, необходимо иметь USE CONNECTION привилегии на подключение (или MANAGE привилегии на однопользовательские кластеры).

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

Использование функции remote_query

Функция remote_query выполняет запрос к удаленной базе данных и возвращает результаты в виде таблицы, которую можно использовать в запросах Databricks SQL.

Синтаксис

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

Обязательные параметры

• connection-name: имя подключения каталога Unity, которое будет использоваться.

Все остальные необходимые параметры зависят от типа подключения. См. специфические параметры соединителя для получения подробной информации.

Параметры для конкретного соединителя

Доступные параметры зависят от типа подключения. В следующих таблицах описаны параметры каждого соединителя.

MySQL, PostgreSQL, SQL Server, Redshift и Teradata

Oracle;

Snowflake

BigQuery

Дополнительные параметры управления сжатием (pushdown)

Вы можете объединить функцию с операциями remote_query SQL Databricks, и большинство этих операций также можно отправить вниз. Вы также можете управлять тем, какие операции Databricks SQL можно отправить вниз. Эти параметры применяются ко всем типам подключений и не учитывают регистр.

По умолчанию все pushdown включены. При необходимости вы можете отключить определенные pushdown'ы для диагностики неисправностей или обхода проблем совместимости с конкретными удаленными базами данных.

Делегирование доступа через представления

Вы можете делегировать доступ к удаленным данным без предоставления пользователям прямых USE CONNECTION привилегий, завернув функцию remote_query в представление. Этот подход имеет следующие преимущества:

• Упрощенное управление доступом: предоставление SELECT привилегий для представления вместо управления USE CONNECTION привилегиями.
• Безопасность данных: управление доступом к столбцам и строкам, определяя запрос представления.
• Отслеживание происхождения: отслеживание доступа к данным с помощью представления происхождения, а не прямого использования подключений.

Делегирование доступа через представление:

1. Создайте представление, которое вызывает функцию remote_query :

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

2. Предоставьте SELECT привилегии на представление пользователям или группам:

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

3. Теперь пользователи могут запрашивать представление, не нуждаясь в привилегиях USE CONNECTION :

   SELECT * FROM sales_data_view WHERE region = 'US';
   

Примеры

Базовое выполнение запроса

Выполните запрос в базе данных PostgreSQL:

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

Запрос определенной таблицы

Запрос таблицы MySQL напрямую:

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

Oracle с именем службы

Запрос базы данных Oracle:

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

Запрос BigQuery

Запрос 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)'
);

Запрос Snowflake

Запрос Snowflake:

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

Настройка производительности с помощью секционирования

Параллельное получение данных из таблицы SQL Server:

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

Объединение с операциями Databricks SQL

Применение дополнительных фильтров и преобразований:

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;

Создание представления для делегированного доступа

Создайте представление, которое упаковывает функцию remote_query . Пользователи с SELECT привилегиями в представлении могут запрашивать данные, не требуя USE CONNECTION прав доступа к базовому подключению:

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>;

Управление поведением pushdown

При использовании remote_query функции Databricks может отправлять дополнительные операции в удаленную базу данных за пределами указанного запроса. Эта функция полезна при запросе представления, использующего функцию remote_query .

Следующие операции могут быть оптимизированы:

• Фильтры: WHERE предложения, примененные к результату удаленного запроса
• Проекции: выбор столбцов (SELECT определенные столбцы)
• Ограничение: LIMIT предложения, ограничивающие количество возвращаемых строк
• Смещение: OFFSET предложения для пропуска строк
• Агрегаты: функции агрегирования, такие как COUNT, SUM, AVG, MAXMIN
• Top-N: сочетание ORDER BY и LIMIT для запросов с верхними/нижними N элементами.

Поддержка pushdown зависит от источника данных. Дополнительные сведения см. в документации по конкретному типу подключения.

Отключите определенные pushdowns для устранения неполадок или настройки совместимости.

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

Ограничения

• Операции только для чтения: функция поддерживает только remote_query запросы. Операции изменения данных (, INSERTDELETE, MERGE), операции DDL (UPDATECREATE, DROP, ALTER) и хранимые процедуры не поддерживаются.

• Проверка запроса: предоставленный запрос выполняется непосредственно в удаленной базе данных. Databricks проверяет, что запрос доступен только для чтения, выполняя проверку схемы, но синтаксис и семантическая проверка выполняются удаленной базой данных.

Устранение неполадок

Ошибки разрешений

Если вы получили сообщение об ошибке разрешения, убедитесь, что:

1. У вас есть привилегия USE CONNECTION на подключение или привилегия SELECT на представление, оборачивающее функцию.
2. Учетные данные в соединении имеют соответствующие разрешения для удаленной базы данных.

Пример ошибки:

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

Резолюция:

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

Неподдерживаемые параметры

Если вы получаете сообщение об ошибке о неподдерживаемых параметрах, убедитесь, что вы используете правильные параметры для типа подключения. В сообщении об ошибке перечислены допустимые параметры.

Пример ошибки:

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'.

Разрешение. Удалите неподдерживаемый параметр и используйте правильные параметры для типа подключения.

Операции DML не поддерживаются

Функция remote_query поддерживает только запросы на чтение SELECT.

Пример ошибки:

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

разрешение: удалите из запроса любые инструкции, DELETE, DDL или INSERT, UPDATE. Используйте SELECT только инструкции.

Дополнительные ресурсы

• Что такое федерация запросов?
• Управление подключениями Federation для Lakehouse
• Рекомендации по производительности Федерации Lakehouse
• Управление привилегиями в каталоге Unity