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

На этой странице описывается, как настроить Федерацию Lakehouse для выполнения федеративных запросов на данные PostgreSQL, которые не управляются Azure Databricks. Дополнительные сведения о Федерации Lakehouse см. в статье "Что такое Федерация Lakehouse?"

Чтобы подключиться к выполнению запросов в базе данных PostgreSQL с помощью Lakehouse Federation, необходимо создать следующее в хранилище метаданных Azure Databricks Unity Catalog (рабочие области, созданные после 9 ноября 2023 г., уже автоматически обеспечены хранилищем метаданных Unity Catalog).

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

Перед началом работы

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

• Рабочая область активирована для каталога Unity. Рабочие области, созданные после 9 ноября 2023 г., автоматически включены для каталога Unity, включая автоматическую подготовку хранилища метаданных. Вам не нужно создавать хранилище метаданных вручную, если ваша рабочая область была создана до автоматического включения и не была включена для Unity Catalog. См. автоматическое включение каталога Unity.

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

• Сетевое подключение от вычислительного ресурса к целевым системам баз данных. См. рекомендации по сетям для федерации Lakehouse.
• Вычислительные ресурсы Azure Databricks должны использовать Databricks Runtime 13.3 LTS или более поздней версии, а также стандартный или выделенный режим доступа.
• Хранилища SQL должны быть профессиональными или бессерверными и должны использовать 2023.40 или более поздней версии.

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

• Чтобы создать подключение, необходимо быть администратором хранилища метаданных или пользователем с правами CREATE CONNECTION в хранилище метаданных каталога Unity, подключенном к рабочей области. В рабочих областях, автоматически включённых в каталог Unity, администраторы рабочих областей по умолчанию имеют CREATE CONNECTION привилегии.
• Чтобы создать внешний каталог, необходимо обладать разрешением CREATE CATALOG в хранилище метаданных и быть владельцем подключения или иметь CREATE FOREIGN CATALOG привилегию подключения. В рабочих областях, автоматически включённых в каталог Unity, администраторы рабочих областей по умолчанию имеют CREATE CATALOG привилегии.

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

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

Подключение задает путь и учетные данные для доступа к внешней системе базы данных. Чтобы создать подключение, можно использовать обозреватель каталогов или команду CREATE CONNECTION SQL в записной книжке Azure Databricks или редакторе sql-запросов Databricks.

Note

Для создания подключения можно также использовать REST API Databricks или интерфейс командной строки Databricks. См. POST /api/2.1/unity-catalog/connections и команды каталога Unity .

Необходимые разрешения: администратор хранилища метаданных или пользователь с привилегиями CREATE CONNECTION .

Обозреватель каталогов

1. В рабочей области Azure Databricks щелкните Каталог.
2. В верхней части области каталога щелкните " и выберите "Создать подключение" в меню.
3. На странице Основы подключения мастера Настройка подключения введите удобное Имя подключения.
4. Выберите тип подключения для PostgreSQL.
5. (Необязательно) Добавьте комментарий.
6. Нажмите кнопку Далее.
7. На странице аутентификации введите следующие свойства подключения для экземпляра PostgreSQL.
   • Узел: например, postgres-demo.lb123.us-west-2.rds.amazonaws.com
   • Порт: например, 5432
   • Пользователь: например, postgres_user
   • Пароль: например, password123
8. Щелкните Создать подключение.
9. На странице Основы каталога введите имя иностранного каталога. Внешний каталог зеркально отражает базу данных во внешней системе данных, чтобы можно было запрашивать и управлять доступом к данным в этой базе данных с помощью Azure Databricks и каталога Unity.
10. (Необязательно) Нажмите кнопку "Проверить подключение" , чтобы убедиться, что она работает.
11. Кликните Создать каталог.
12. На странице Access выберите рабочие области, в которых пользователи могут получить доступ к созданному каталогу. Вы можете выбрать Все рабочие области имеют доступ, или щелкнуть Назначить рабочим областям, выбрать рабочие области, а затем нажать Назначить.
13. Измените владельца , чтобы он мог управлять доступом ко всем объектам в каталоге. Начните вводить название участника в текстовом поле, а затем щелкните на него в результатах поиска.
14. Предоставьте привилегий в каталоге. Нажмите кнопку "Предоставить":
    1. Укажите субъекты , у которых будет доступ к объектам в каталоге. Начните вводить название участника в текстовом поле, а затем щелкните на него в результатах поиска.
    2. Выберите пресеты привилегий , которые необходимо предоставить каждому субъекту. Все пользователи учетной записи получают BROWSE по умолчанию.
       • В раскрывающемся меню выберите средство чтения данных , чтобы предоставить привилегии read объектам каталога.
       • Выберите Редактор данных в выпадающем меню, чтобы назначить read и modify привилегии объектам в каталоге.
       • Вручную выберите привилегии для предоставления.
    3. Нажмите Grant.
15. Нажмите кнопку Далее.
16. На странице метаданных укажите пары ключ-значение для тегов. Дополнительные сведения см. в статье Применение тегов к защищаемым объектам каталога Unity.
17. (Необязательно) Добавьте комментарий.
18. Нажмите кнопку Сохранить.

SQL

Выполните следующую команду в записной книжке или редакторе sql-запросов Databricks.

CREATE CONNECTION <connection-name> TYPE postgresql
OPTIONS (
  host '<hostname>',
  port '<port>',
  user '<user>',
  password '<password>'
);

Мы рекомендуем использовать секреты Azure Databricks вместо строк открытого текста для конфиденциальных значений, таких как учетные данные. Рассмотрим пример.

CREATE CONNECTION <connection-name> TYPE postgresql
OPTIONS (
  host '<hostname>',
  port '<port>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>')
)

Сведения о настройке секретов см. в разделе "Управление секретами".

Создание внешнего каталога

Note

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

Внешний каталог зеркально отражает базу данных во внешней системе данных, чтобы можно было запрашивать и управлять доступом к данным в этой базе данных с помощью Azure Databricks и каталога Unity. Чтобы создать внешний каталог, вы используете подключение к источнику данных, который уже определен.

Чтобы создать внешний каталог, можно использовать обозреватель каталогов или команду SQL CREATE FOREIGN CATALOG в записной книжке Azure Databricks или редакторе запросов SQL. Для создания каталога можно также использовать REST API Databricks или интерфейс командной строки Databricks. См. POST /api/2.1/unity-catalog/catalogs и команды Unity Catalog .

Необходимые разрешения:CREATE CATALOG разрешение на хранилище метаданных и право владения подключением или CREATE FOREIGN CATALOG привилегией подключения.

Обозреватель каталогов

1. В рабочей области Azure Databricks щелкните Каталог , чтобы открыть обозреватель каталогов.

2. В верхней части панели Каталог щелкните значок и выберитеДобавить каталог в меню.

   Кроме того, на странице быстрого доступа нажмите кнопку каталогов, а затем нажмите кнопку "Создать каталог".

3. Следуйте инструкциям по созданию внешних каталогов в Создание каталогов.

SQL

Выполните следующую команду SQL в Jupyter Notebook или в редакторе запросов SQL. Элементы в квадратных скобках являются необязательными. Замените значения заполнителей:

• <catalog-name>: имя каталога в Azure Databricks.
• <connection-name>: объект подключения , указывающий источник данных, путь и учетные данные доступа.
• <database-name>. Имя базы данных, которую вы хотите зеркально отражать в качестве каталога в Azure Databricks.

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (database '<database-name>');

Поддерживаемые продвижения

В следующей таблице перечислены операции pushdown, поддерживаемые для PostgreSQL, а также вычислительные ресурсы, необходимые для каждого.

Pushdown	Поддерживаемые вычислительные ресурсы
Функции даты, времени и метки времени (выражения фильтра, только частично)	Все вычислительные ресурсы
Filters	Все вычислительные ресурсы
Limit	Все вычислительные ресурсы
Математические функции (выражения фильтра, только частично)	Все вычислительные ресурсы
Прочие функции (например, Псевдоним, Приведение, SortOrder; частичное, только выражения фильтра)	Все вычислительные ресурсы
Projections	Все вычислительные ресурсы
Строковые функции (выражения фильтра, только частично)	Все вычислительные ресурсы
Агрегаты	Databricks Runtime 13.3 LTS и более поздние версии, а также SQL-хранилища
Арифметические операторы (например, +, -, *, %, /; не поддерживается, если ANSI отключен)	Databricks Runtime 13.3 LTS и более поздние версии, а также SQL-хранилища
Логические операторы (например, =, <, <, =>, >=, <=>)	Databricks Runtime 13.3 LTS и более поздние версии, а также SQL-хранилища
Другие операторы | и ~	Databricks Runtime 13.3 LTS и более поздние версии, а также SQL-хранилища
Сортировка при использовании с лимитом	Databricks Runtime 13.3 LTS и более поздние версии, а также SQL-хранилища
Joins	Databricks Runtime 17.2 и более поздние версии, а также SQL-склады 2025.30 и более поздние версии.
Функции Windows	Не поддерживается

Сопоставление типов данных

При чтении из PostgreSQL в Spark типы данных сопоставляются следующим образом:

Тип PostgreSQL	Тип Spark
numeric	DecimalType
int2	ShortType
int4 (если он не подписан)	IntegerType
int8, oid, xid, int4 (если подписан)	LongType
float4	FloatType
двойная точность, float8	DoubleType
char	CharType
name, varchar, tid	VarcharType
bpchar, переменный символ, json, money, point, super, text	StringType
bytea, geometry, varbyte	BinaryType
bit, bool	BooleanType
date	DateType
tabstime, time, время с часовым поясом, timetz, время без часового пояса, метка времени с часовым поясом, метка времени, временная метка с часовым поясом, метка времени без часового пояса*	TimestampType/TimestampNTZType
Тип массива Postgresql**	ArrayType

*При чтении из Postgresql Postgresql Timestamp сопоставляется с Spark TimestampType, если preferTimestampNTZ = false (по умолчанию). Postgresql Timestamp сопоставляется с TimestampNTZType, если preferTimestampNTZ = true.

**Поддерживаются ограниченные типы массивов.

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

• Спуск соединения в Lakehouse Federation
• Рекомендации по сетям для Федерации Лейкхаус
• Запрос внешних баз данных с помощью remote_query функции