Поддержка API S3

Расширение httpfs поддерживает чтение/запись/обработку шаблонов файлов на серверах хранилища объектов с использованием API S3. S3 предлагает стандартный API для чтения и записи в удаленные файлы (в то время как обычные HTTP-серверы, предшествующие S3, не предлагают общего API записи). DuckDB соответствует API S3, который сейчас распространён среди поставщиков облачных хранилищ.

Платформы

Файловая система httpfs протестирована с AWS S3, Minio, Google Cloud и lakeFS. Другие сервисы, реализующие API S3 (такие как Cloudflare R2), также должны работать, но не все функции могут быть поддерживаемы.

В следующей таблице показано, какие части API S3 необходимы для каждой httpfs функции.

Настройка и аутентификация

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

Устаревшее До версии 0.10.0 в DuckDB не было менеджера секретов. Поэтому настройка и аутентификация с конечными точками S3 обрабатывались с помощью переменных. См. старый механизм аутентификации для API S3.

CONFIG Поставщик

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

CREATE SECRET secret1 (
    TYPE S3,
    KEY_ID 'AKIAIOSFODNN7EXAMPLE',
    SECRET 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    REGION 'us-east-1'
);

Подсказка Если возникает ошибка IO (Connection error for HTTP HEAD), настройте конечную точку явно через ENDPOINT 's3.⟨your-region⟩.amazonaws.com'.

Теперь для запроса с использованием указанного секрета просто запросите любой файл с префиксом s3://:

SELECT *
FROM 's3://my-bucket/file.parquet';

CREDENTIAL_CHAIN Поставщик

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

CREATE SECRET secret2 (
    TYPE S3,
    PROVIDER CREDENTIAL_CHAIN
);

И снова, для запроса файла с использованием указанного секрета, просто запросите любой файл с префиксом s3://.

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

CREATE SECRET secret3 (
    TYPE S3,
    PROVIDER CREDENTIAL_CHAIN,
    CHAIN 'env;config'
);

Возможные значения для CHAIN:

• config
• sts
• sso
• env
• instance
• process

Поставщик CREDENTIAL_CHAIN также позволяет переопределить автоматически извлеченные параметры конфигурации. Например, чтобы автоматически загрузить учетные данные, а затем переопределить регион, выполните:

CREATE SECRET secret4 (
    TYPE S3,
    PROVIDER CREDENTIAL_CHAIN,
    CHAIN 'config',
    REGION 'eu-west-1'
);

Обзор параметров секрета S3

Ниже приведен полный список поддерживаемых параметров, которые можно использовать для обоих поставщиков CONFIG и CREDENTIAL_CHAIN:

Платформенно-специфичные типы секретов

Секреты R2

Хотя Cloudflare R2 использует стандартный API S3, в DuckDB есть специальный тип секрета R2, чтобы упростить его настройку:

CREATE SECRET secret5 (
    TYPE R2,
    KEY_ID 'AKIAIOSFODNN7EXAMPLE',
    SECRET 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    ACCOUNT_ID 'my_account_id'
);

Обратите внимание на добавление ACCOUNT_ID, которое используется для генерации корректного URL конечной точки. Также обратите внимание, что для секретов R2 можно использовать как поставщики CONFIG, так и CREDENTIAL_CHAIN. Наконец, секреты R2 доступны только при использовании URL, начинающихся с r2://, например:

SELECT *
FROM read_parquet('r2://some/file/that/uses/r2/secret/file.parquet');

Секреты GCS

Хотя к Google Cloud Storage DuckDB обращается с помощью API S3, в DuckDB есть специальный тип секрета GCS, чтобы упростить его настройку:

CREATE SECRET secret6 (
    TYPE GCS,
    KEY_ID 'my_key',
    SECRET 'my_secret'
);

Обратите внимание, что указанный секрет автоматически настроит корректную конечную точку Google Cloud Storage. Также обратите внимание, что для секретов GCS можно использовать как поставщики CONFIG, так и CREDENTIAL_CHAIN. Наконец, секреты GCS доступны только при использовании URL, начинающихся с gcs:// или gs://, например:

SELECT *
FROM read_parquet('gcs://some/file/that/uses/gcs/secret/file.parquet');

Чтение

Чтение файлов из S3 теперь так же просто, как:

SELECT *
FROM 's3://bucket/file.extension';

Частичное чтение

Расширение httpfs поддерживает частичное чтение из ведер S3.

Чтение нескольких файлов

Возможность чтения нескольких файлов, например:

SELECT *
FROM read_parquet([
    's3://bucket/file1.parquet',
    's3://bucket/file2.parquet'
]);

Обработка шаблонов

Обработка шаблонов файлов реализована с помощью вызова API ListObjectV2 и позволяет использовать похожие на файловую систему шаблоны для сопоставления нескольких файлов, например:

SELECT *
FROM read_parquet('s3://bucket/*.parquet');

Этот запрос соответствует всем файлам в корне ведра с расширением Parquet.

Поддерживается несколько функций сопоставления, таких как * для совпадения с любым количеством любых символов, ? для любого одиночного символа или [0-9] для одиночного символа в диапазоне символов:

SELECT count(*) FROM read_parquet('s3://bucket/folder*/100?/t[0-9].parquet');

Полезной функцией при использовании шаблонов является опция filename, которая добавляет столбец с именем filename, кодирующий файл, из которого произошла конкретная строка:

SELECT *
FROM read_parquet('s3://bucket/*.parquet', filename = true);

что, например, может привести к следующему:

Разбиение по Hive

DuckDB также поддерживает схему разбиения по Hive, доступную при использовании HTTP(S) и S3 конечных точек. Подробнее о схеме разбиения по Hive.

Запись

Запись в S3 использует API многочастотной загрузки. Это позволяет DuckDB надежно загружать файлы с высокой скоростью. Запись в S3 работает как для CSV, так и для Parquet:

COPY table_name TO 's3://bucket/file.extension';

Разбитая копия в S3 также работает:

COPY table TO 's3://my-bucket/partitioned' (
    FORMAT PARQUET,
    PARTITION_BY (part_col_a, part_col_b)
);

Производится автоматическая проверка на наличие существующих файлов/каталогов, которая в настоящее время довольно консервативна (и в S3 добавит некоторую задержку). Чтобы отключить эту проверку и принудительно выполнить запись, добавлена опция OVERWRITE_OR_IGNORE.

COPY table TO 's3://my-bucket/partitioned' (
    FORMAT PARQUET,
    PARTITION_BY (part_col_a, part_col_b),
    OVERWRITE_OR_IGNORE true
);

Схема именования записываемых файлов выглядит следующим образом:

s3://my-bucket/partitioned/part_col_a=⟨val⟩/part_col_b=⟨val⟩/data_⟨thread_number⟩.parquet

Настройка

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