Выполнение федеративных запросов в Snowflake (OAuth)

2025-07-02

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

Чтобы подключиться к базе данных Snowflake с помощью Федерации Lakehouse, необходимо создать следующее в метахранилище каталога Unity в Azure Databricks:

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

На этой странице рассматривается подключение к Snowflake с помощью встроенной интеграции OAuth Snowflake. Сведения о других методах проверки подлинности см. на следующих страницах:

Федеративные запросы можно выполнять в Snowflake с помощью федерации базы данных или федерации каталога. См. федерация каталогов.

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

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

Федерация базы данных

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

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

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

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

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

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

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

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

Создание интеграции безопасности

В консоли Snowflake выполните команду CREATE SECURITY INTEGRATION. Замените следующие значения:

<integration-name>: уникальное имя для интеграции OAuth.
<workspace-url>: URL-адрес рабочей области Azure Databricks. Необходимо установить OAUTH_REDIRECT_URI в https://<workspace-url>/login/oauth/snowflake.html, где <workspace-url> — это уникальный URL-адрес рабочей области Azure Databricks, в которой будет создано подключение к Snowflake.
<duration-in-seconds>: длительность действия токенов обновления.

Внимание

OAUTH_REFRESH_TOKEN_VALIDITY — это настраиваемое поле, которое по умолчанию имеет значение 90 дней. После истечения срока действия маркера обновления необходимо повторно пройти проверку подлинности подключения. Установите для поля разумную длительность времени.

Например:

CREATE SECURITY INTEGRATION <integration-name>
TYPE = oauth
ENABLED = true
OAUTH_CLIENT = custom
OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
OAUTH_REDIRECT_URI = 'https://<workspace-url>/login/oauth/snowflake.html'
OAUTH_ISSUE_REFRESH_TOKENS = TRUE
OAUTH_REFRESH_TOKEN_VALIDITY = <duration-in-seconds>
OAUTH_ENFORCE_PKCE = TRUE;

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

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

Примечание.

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

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

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

Кроме того, на странице быстрого доступа нажмите кнопку Внешние данные >, перейдите на вкладку Подключения и нажмите Создать подключение.
На странице основы подключения мастера настройки подключения введите понятное имя подключения.
Выберите тип подключенияSnowflake.
Для типа проверки подлинности выберите OAuth в раскрывающемся меню.
(Необязательно) Добавьте комментарий.
Нажмите кнопку Далее.
Введите следующие сведения о проверке подлинности и подключении для хранилища Snowflake.
- Узел: например, snowflake-demo.east-us-2.azure.snowflakecomputing.com
- Порт: например, 443
- Пользователь: например, snowflake-user
- Идентификатор клиента: в консоли Snowflake запустите SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<security-integration-name>') , чтобы получить идентификатор клиента для интеграции безопасности.
- Секрет клиента: в консоли Snowflake запустите SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<security-integration-name>') , чтобы получить секрет клиента для интеграции безопасности.
- Область OAuth: refresh_token session:role:<role-name>. Укажите роль Snowflake для использования <role-name>.
- Войдите с помощью Snowflake: щелкните и войдите в Snowflake с помощью учетных данных OAuth.
  
  После успешного входа вы будете перенаправлены обратно в мастер настройки подключения .
Щелкните Создать подключение.
На странице Основы каталога введите имя иностранного каталога. Внешний каталог зеркально отражает базу данных во внешней системе данных, чтобы можно было запрашивать и управлять доступом к данным в этой базе данных с помощью Azure Databricks и каталога Unity.
(Необязательно) Нажмите кнопку "Проверить подключение" , чтобы убедиться, что она работает.
Нажмите Создать каталог.
На странице Access выберите рабочие области, в которых пользователи могут получить доступ к созданному каталогу. Вы можете выбрать Все рабочие области имеют доступ, или нажать Назначить рабочие области, выбрать рабочие области, а затем нажать Назначить.
Измените владельца , чтобы он мог управлять доступом ко всем объектам в каталоге. Начните вводить основной элемент в текстовом поле, а затем щелкните его в результатах поиска.
Предоставьте привилегии в каталоге. Щелкните Предоставить доступ:
1. Укажите принципалов , у которых будет доступ к объектам в каталоге. Начните вводить основной элемент в текстовом поле, а затем щелкните его в результатах поиска.
2. Выберите предустановки привилегий , чтобы предоставить их каждому принципалу. Все пользователи учетной записи по умолчанию получают BROWSE.
  - В раскрывающемся меню выберите средство чтения данных , чтобы предоставить привилегии read объектам каталога.
  - Выберите редактор данных в выпадающем меню, чтобы предоставить привилегии read и modify для объектов в каталоге.
  - Вручную выберите привилегии для предоставления.
3. Нажмите Предоставить.
Нажмите кнопку Далее.
Укажите на странице метаданных пары "ключ-значение" тегов. Дополнительные сведения см. в статье Применение тегов к защищаемым объектам каталога Unity.
(Необязательно) Добавьте комментарий.
Нажмите Сохранить.

Идентификаторы базы данных с учетом регистра

Поле database внешнего каталога сопоставляется с идентификатором базы данных Snowflake. Если идентификатор базы данных Snowflake не чувствителен к регистру, форматирование, используемое в внешнем каталоге <database-name>, сохраняется. Однако если идентификатор базы данных Snowflake чувствителен к регистру, необходимо обернуть внешний каталог <database-name> в двойные кавычки, чтобы сохранить регистр.

Например:

database преобразуется в DATABASE
"database" преобразуется в database
"database""" преобразуется в database"

Чтобы избежать двойной кавычки, используйте еще одну двойную кавычку.
"database"" приводит к ошибке, так как двойные кавычки не экранируются правильно.

Дополнительные сведения см. в разделе "Требования к идентификатору" в документации по Snowflake.

Поддерживаемые pushdowns

Поддерживаются следующие методы снижения:

Фильтры
Проекции.
Лимит
Объединения
Агрегаты (Average, Corr, CovPopulation, CovSample, Count, Max, Min, StddevPop, StdevSamp, Sum, VariancePop, VarianceSamp)
Функции (строковые функции, математические функции, функции data, time и timestamp и другие прочие функции, такие как псевдоним, приведение, сортировка)
Функции Windows (DenseRank, Rank, RowNumber)
Сортировка

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

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

Тип снежинка	Тип Spark
десятичная, число, числовой	ДесятичныйТип
bigint (большое целое число), byteint (байтовое целое число), int (целое число), integer (целое число), smallint (малое целое число), tinyint (крошечное целое число)	ИнтеджерТайп
float, float4, float8	Тип с плавающей запятой
двойной, двойная точность, вещественное число	ДвойнойТип
char, символ, строка, текст, время, varchar	Тип строки
бинарный	БинарныйТип
булевый	Тип Boolean
Дата	ТипДата
datetime, timestamp, timestamp_ltz, timestamp_ntz, timestamp_tz	ТипВременнойМетки

Ограничения федерации базы данных

Конечная точка OAuth Snowflake должна быть доступна из IP-адресов уровня управления Azure Databricks. См. исходящий трафик из плоскости управления Azure Databricks. Snowflake поддерживает настройку сетевых политик на уровне интеграции безопасности, что позволяет отдельной политике обеспечивать прямое подключение от контрольной панели Azure Databricks к конечной точке OAuth для авторизации.
Использование прокси, Прокси-узел, Прокси-порт и параметры конфигурации роли Snowflake не поддерживаются. Укажите роль Snowflake в рамках области OAuth.

Федерация каталога

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

Для выполнения федеративных запросов в Snowflake с помощью федерации каталогов необходимо выполнить следующие требования:

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

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

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

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

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

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

Используйте Databricks Runtime 16.4 LTS или более поздней версии или Databricks SQL.

Настройка федерации каталога

Действия по настройке федерации каталога аналогичны настройке федерации базы данных. Однако необходимо также создать учетные данные для хранения и внешнее местоположение для путей к таблицам Apache Iceberg, зарегистрированным в Snowflake.

Создайте внешнее местоположение для таблиц Айсберга.

Необходимо настроить внешнее расположение в каталоге Unity, чтобы управлять доступом к расположениям облачного хранилища, в которые хранятся таблицы Iceberg, зарегистрированные в базе данных Snowflake. Внешние расположения — это защищаемые объекты каталога Unity, которые связывают учетные данные хранения с путями контейнера облачного хранилища. См. идентификационные данные хранилища и внешние расположения.

Вы можете создать внешнее расположение с помощью следующих интерфейсов:
- SQL
- обозреватель каталогов
Внешнее расположение будет указано в качестве авторизованного пути во время настройки конфигурации иностранного каталога.
Создайте подключение к каталогу Snowflake Horizon и создайте внешний каталог. Необходимо указать расположение в облачном хранилище, где метаданные будут храниться для таблиц Iceberg в этом каталоге.

Настройка расположения хранилища в каталоге позволяет читать таблицы Iceberg в внешнем каталоге через хранилище объектов. Чтение или запись в таблицы Айсберга с помощью протокола JDBC больше не будет доступно (таблицы, отличные от Айсберга, не будут затронуты).

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

Ограничения федерации каталогов

Выполнение федеративных запросов в Snowflake с помощью федерации каталога имеет следующие ограничения:

Некоторые таблицы типа "айсберг" можно считывать только с помощью федерации баз данных.
- Таблицы с несовместимыми URI-расположениями (которые содержат специальные символы).
- Таблицы с расположением метаданных за пределами расположения таблицы.
- Таблицы с расположениями, которые имеют неподдерживаемые схемы (только s3, s3a, s3n, abfs, abfss, gs, r2, wasb, и wasbs поддерживаются).
Таблицы с идентичными именами, игнорирующие регистр, конфликт. Первая таблица для загрузки — это та, которая отображается.
Для Azure таблицы Snowflake Iceberg не могут находиться в корневом расположении контейнера.

См. ограничения таблицы Айсберга для связанных с Айсбергом ограничений.

Определение того, использует ли иностранная таблица Snowflake каталог или федерацию баз данных

Внешние таблицы Snowflake, прочитанные с помощью федерации каталога, будут отображать исходный формат Iceberg в обозревателе каталогов. Таблицы Iceberg, прочитанные с помощью федерации базы данных, будут отображать исходный формат Snowflake в обозревателе каталогов.

Федеративные каталоги Snowflake могут содержать как встроенные в систему таблицы Snowflake, так и таблицы Iceberg. Запросы, выполняемые против таблиц с обоими форматами хранилища, будут запущены с использованием федерации базы данных, которая использует вычислительные ресурсы Snowflake.

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

См. следующие статьи в документации по Snowflake:

Настройка OAuth Snowflake для пользовательских клиентов
справочник по SQL : CREATE SECURITY INTEGRATION (Snowflake OAuth)

Поделиться через

Выполнение федеративных запросов в Snowflake (OAuth)

Федерация базы данных

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

Создание интеграции безопасности

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

Идентификаторы базы данных с учетом регистра

Поддерживаемые pushdowns

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

Ограничения федерации базы данных

Федерация каталога

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

Настройка федерации каталога

Ограничения федерации каталогов

Определение того, использует ли иностранная таблица Snowflake каталог или федерацию баз данных

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

Обратная связь

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