Расширение Azure

Расширение azure — это загружаемое расширение, которое добавляет абстракцию файловой системы для хранилища Azure Blob в DuckDB.

Установка и загрузка

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

INSTALL azure;
LOAD azure;

Использование

После настройки аутентификации вы можете запросить хранилище Azure следующим образом:

Хранилище Azure Blob

Допустимые схемы URI: az или azure

SELECT count(*)
FROM 'az://⟨my_container⟩/⟨path⟩/⟨my_file⟩.⟨parquet_or_csv⟩';

Также поддерживаются шаблоны:

SELECT *
FROM 'az://⟨my_container⟩/⟨path⟩/*.csv';

SELECT *
FROM 'az://⟨my_container⟩/⟨path⟩/**';

Или с синтаксисом полного пути:

SELECT count(*)
FROM 'az://⟨my_storage_account⟩.blob.core.windows.net/⟨my_container⟩/⟨path⟩/⟨my_file⟩.⟨parquet_or_csv⟩';

SELECT *
FROM 'az://⟨my_storage_account⟩.blob.core.windows.net/⟨my_container⟩/⟨path⟩/*.csv';

Хранилище Azure Data Lake (ADLS)

Допустимые схемы URI: abfss

SELECT count(*)
FROM 'abfss://⟨my_filesystem⟩/⟨path⟩/⟨my_file⟩.⟨parquet_or_csv⟩';

Также поддерживаются шаблоны:

SELECT *
FROM 'abfss://⟨my_filesystem⟩/⟨path⟩/*.csv';

SELECT *
FROM 'abfss://⟨my_filesystem⟩/⟨path⟩/**';

Или с синтаксисом полного пути:

SELECT count(*)
FROM 'abfss://⟨my_storage_account⟩.dfs.core.windows.net/⟨my_filesystem⟩/⟨path⟩/⟨my_file⟩.⟨parquet_or_csv⟩';

SELECT *
FROM 'abfss://⟨my_storage_account⟩.dfs.core.windows.net/⟨my_filesystem⟩/⟨path⟩/*.csv';

Настройка

Используйте следующие опции конфигурации, чтобы настроить чтение удаленных файлов расширением:

Явное задание azure_transport_option_type в значение curl имеет следующие последствия:

• В Linux это может решить проблемы с сертификатами (Error: Invalid Error: Fail to get a new connection for: https://⟨storage account name⟩.blob.core.windows.net/. Problem with the SSL CA cert (path? access rights?)) потому что при указании расширения оно будет пытаться найти сертификат в различных путях (это не делается по умолчанию curl и может быть неверным из-за статической компоновки).
• В Windows это заменяет адаптер по умолчанию (WinHTTP), позволяя использовать все возможности curl (например, использование прокси-серверов socks).
• Во всех операционных системах будут учитываться следующие переменные окружения:
  • CURL_CA_INFO: Путь к файлу в формате PEM, содержащему авторитетные сертификаты, отправленные в libcurl. Обратите внимание, что эта опция известна тем, что работает только в Linux и может выбросить исключение при установке на других платформах.
  • CURL_CA_PATH: Путь к каталогу, содержащему файлы в формате PEM, содержащие авторитетные сертификаты, отправленные в libcurl.

Пример:

SET azure_http_stats = false;
SET azure_read_transfer_concurrency = 5;
SET azure_read_transfer_chunk_size = 1_048_576;
SET azure_read_buffer_size = 1_048_576;

Аутентификация

Расширение Azure имеет два способа настройки аутентификации. Предпочтительный способ — использовать секреты.

Аутентификация с секретом

Для расширения Azure доступно несколько поставщиков секретов:

• Если вам нужно определить разные секреты для разных учетных записей хранения, используйте конфигурацию SCOPE. Обратите внимание, что для SCOPE требуется конечный слэш (SCOPE 'azure://some_container/').
• Если вы используете полный путь, то атрибут ACCOUNT_NAME является необязательным.

CONFIG поставщик

Поставщик по умолчанию, CONFIG (т.е., настроенный пользователем), предоставляет доступ к учетной записи хранения с использованием строки подключения или анонимно. Например:

CREATE SECRET secret1 (
    TYPE AZURE,
    CONNECTION_STRING '⟨value⟩'
);

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

CREATE SECRET secret2 (
    TYPE AZURE,
    PROVIDER CONFIG,
    ACCOUNT_NAME '⟨storage account name⟩'
);

Значение по умолчанию для PROVIDER — CONFIG.

CREDENTIAL_CHAIN поставщик

Поставщик CREDENTIAL_CHAIN позволяет подключиться, используя учетные данные, автоматически полученные Azure SDK через цепочку учетных данных Azure. По умолчанию используется цепочка DefaultAzureCredential, которая пытается получить учетные данные в соответствии с порядком, указанным в документации Azure. Например:

CREATE SECRET secret3 (
    TYPE AZURE,
    PROVIDER CREDENTIAL_CHAIN,
    ACCOUNT_NAME '⟨storage account name⟩'
);

DuckDB также позволяет указать определенную цепочку с помощью ключевого слова CHAIN. Это принимает список поставщиков, разделенных точкой с запятой (a;b;c), которые будут проверены в порядке. Например:

CREATE SECRET secret4 (
    TYPE AZURE,
    PROVIDER CREDENTIAL_CHAIN,
    CHAIN 'cli;env',
    ACCOUNT_NAME '⟨storage account name⟩'
);

Возможные значения: cli; managed_identity; env; default;

Если явный CHAIN не указан, будет использоваться значение по умолчанию default

SERVICE_PRINCIPAL поставщик

Поставщик SERVICE_PRINCIPAL позволяет подключиться, используя Azure Service Principal (SPN).

Либо с секретом:

CREATE SECRET azure_spn (
    TYPE AZURE,
    PROVIDER SERVICE_PRINCIPAL,
    TENANT_ID '⟨tenant id⟩',
    CLIENT_ID '⟨client id⟩',
    CLIENT_SECRET '⟨client secret⟩',
    ACCOUNT_NAME '⟨storage account name⟩'
);

Либо с сертификатом:

CREATE SECRET azure_spn_cert (
    TYPE AZURE,
    PROVIDER SERVICE_PRINCIPAL,
    TENANT_ID '⟨tenant id⟩',
    CLIENT_ID '⟨client id⟩',
    CLIENT_CERTIFICATE_PATH '⟨client cert path⟩',
    ACCOUNT_NAME '⟨storage account name⟩'
);

Настройка прокси

Для настройки прокси-информации при использовании секретов вы можете добавить HTTP_PROXY, PROXY_USER_NAME, и PROXY_PASSWORD в определение секрета. Например:

CREATE SECRET secret5 (
    TYPE AZURE,
    CONNECTION_STRING '⟨value⟩',
    HTTP_PROXY 'http://localhost:3128',
    PROXY_USER_NAME 'john',
    PROXY_PASSWORD 'doe'
);

• При использовании секретов переменная среды HTTP_PROXY все равно будет учитываться, за исключением случаев, когда вы явно указываете ее значение.
• При использовании секретов переменная SET сессии «Аутентификация с переменными» будет проигнорирована.
• Для поставщика Azure CREDENTIAL_CHAIN фактический токен извлекается во время запроса, а не во время создания секрета.

Аутентификация с переменными (устарело)

SET variable_name = variable_value;

Где variable_name может быть одним из следующих:

Дополнительная информация

Ведение журнала

Расширение Azure использует Azure SDK для подключения к хранилищу Azure Blob и поддерживает вывод журналов SDK в консоль. Для управления уровнем журнала установите переменную среды AZURE_LOG_LEVEL.

Например, подробные журналы можно включить следующим образом в Python:

import os
import duckdb

os.environ["AZURE_LOG_LEVEL"] = "verbose"

duckdb.sql("CREATE SECRET myaccount (TYPE AZURE, PROVIDER CREDENTIAL_CHAIN, SCOPE 'az://myaccount.blob.core.windows.net/')")
duckdb.sql("SELECT count(*) FROM 'az://myaccount.blob.core.windows.net/path/to/blob.parquet'")

Различия между ADLS и хранилищем Blob

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

Чтобы продемонстрировать это, рассмотрим пример того, как выполняется поиск по шаблону в соответственно конечных точках Glob и ADLS.

Используя следующую файловую систему:

root
├── l_receipmonth=1997-10
│   ├── l_shipmode=AIR
│   │   └── data_0.csv
│   ├── l_shipmode=SHIP
│   │   └── data_0.csv
│   └── l_shipmode=TRUCK
│       └── data_0.csv
├── l_receipmonth=1997-11
│   ├── l_shipmode=AIR
│   │   └── data_0.csv
│   ├── l_shipmode=SHIP
│   │   └── data_0.csv
│   └── l_shipmode=TRUCK
│       └── data_0.csv
└── l_receipmonth=1997-12
    ├── l_shipmode=AIR
    │   └── data_0.csv
    ├── l_shipmode=SHIP
    │   └── data_0.csv
    └── l_shipmode=TRUCK
        └── data_0.csv

Следующий запрос, выполненный через конечную точку хранилища Blob,

SELECT count(*)
FROM 'az://root/l_receipmonth=1997-*/l_shipmode=SHIP/*.csv';

выполнит следующие действия:

• Список всех файлов с префиксом root/l_receipmonth=1997-
  • root/l_receipmonth=1997-10/l_shipmode=SHIP/data_0.csv
  • root/l_receipmonth=1997-10/l_shipmode=AIR/data_0.csv
  • root/l_receipmonth=1997-10/l_shipmode=TRUCK/data_0.csv
  • root/l_receipmonth=1997-11/l_shipmode=SHIP/data_0.csv
  • root/l_receipmonth=1997-11/l_shipmode=AIR/data_0.csv
  • root/l_receipmonth=1997-11/l_shipmode=TRUCK/data_0.csv
  • root/l_receipmonth=1997-12/l_shipmode=SHIP/data_0.csv
  • root/l_receipmonth=1997-12/l_shipmode=AIR/data_0.csv
  • root/l_receipmonth=1997-12/l_shipmode=TRUCK/data_0.csv
• Фильтр результатов с запрошенным шаблоном root/l_receipmonth=1997-*/l_shipmode=SHIP/*.csv
  • root/l_receipmonth=1997-10/l_shipmode=SHIP/data_0.csv
  • root/l_receipmonth=1997-11/l_shipmode=SHIP/data_0.csv
  • root/l_receipmonth=1997-12/l_shipmode=SHIP/data_0.csv

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

SELECT count(*)
FROM 'abfss://root/l_receipmonth=1997-*/l_shipmode=SHIP/*.csv';

выполнит следующие действия:

• Список всех каталогов в root/
  • root/l_receipmonth=1997-10
  • root/l_receipmonth=1997-11
  • root/l_receipmonth=1997-12
• Фильтр и список подкаталогов: root/l_receipmonth=1997-10, root/l_receipmonth=1997-11, root/l_receipmonth=1997-12
  • root/l_receipmonth=1997-10/l_shipmode=SHIP
  • root/l_receipmonth=1997-10/l_shipmode=AIR
  • root/l_receipmonth=1997-10/l_shipmode=TRUCK
  • root/l_receipmonth=1997-11/l_shipmode=SHIP
  • root/l_receipmonth=1997-11/l_shipmode=AIR
  • root/l_receipmonth=1997-11/l_shipmode=TRUCK
  • root/l_receipmonth=1997-12/l_shipmode=SHIP
  • root/l_receipmonth=1997-12/l_shipmode=AIR
  • root/l_receipmonth=1997-12/l_shipmode=TRUCK
• Фильтр и список подкаталогов: root/l_receipmonth=1997-10/l_shipmode=SHIP, root/l_receipmonth=1997-11/l_shipmode=SHIP, root/l_receipmonth=1997-12/l_shipmode=SHIP
  • root/l_receipmonth=1997-10/l_shipmode=SHIP/data_0.csv
  • root/l_receipmonth=1997-11/l_shipmode=SHIP/data_0.csv
  • root/l_receipmonth=1997-12/l_shipmode=SHIP/data_0.csv

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