Перейти к содержимому

S3 и httpfs ​

DuckLocal может читать объекты из S3 и S3-совместимых хранилищ через расширение httpfs DuckDB. Настройте его кнопкой S3 в строке заголовка.

Настройка учётных данных ​

В диалоге четыре поля:

ПолеПо умолчаниюПримечания
Endpoints3.amazonaws.comhttp:// учитывается; иначе используется HTTPS
Regionus-east-1Передаётся как введено
Access Key ID—Обязательно
Secret Access Key—Обязательно, скрыто, с переключателем показа

Подтверждение выполняет эквивалент:

sql
INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE SECRET ducklocal_s3 (
  TYPE s3, PROVIDER config,
  KEY_ID '…', SECRET '…',
  REGION '…', ENDPOINT '…'
);

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

Просмотр ​

После настройки в боковой панели появляется корень S3. Его содержимое загружается только при развёртывании: корень перечисляет бакеты, а каждый бакет или префикс — свои объекты. Бакеты и префиксы сортируются, а объекты показывают размер в удобочитаемом виде. Кнопка обновления перезагружает уровень или повторяет попытку после ошибки.

Список ограничен 1 000 записей на уровень, даже если ответ сообщает, что доступно больше. Более глубокого постраничного просмотра, поля фильтра по префиксу и поиска нет: бакет с более чем тысячей объектов на одном уровне будет выглядеть полным, хотя это не так.

Запросы к объектам ​

Щелчок по объекту, ключ которого имеет расширение файла данных, заполняет активный редактор:

sql
SELECT *
FROM 's3://bucket/key'
LIMIT 100;

Это обычный запрос: чтение идёт через httpfs, поэтому действует поведение read_parquet / read_csv_auto DuckDB, включая pushdown — фильтры и выбор столбцов передаются в чтение файла. Запрос заменяет всё, что было в активной вкладке.

Щёлкать можно только по ключам, распознанным как файлы данных. Распознаваемые расширения те же, что и для локальных файлов; см. Источники данных.

Ограничения ​

  • Просмотр доступен только для чтения. В браузере нет загрузки, скачивания в файл, удаления, копирования или создания бакета. Запросы по-прежнему скачивают удалённые данные.
  • Нет токенов сеанса. Заголовок X-Amz-Security-Token никогда не отправляется, поэтому временные учётные данные STS не работают: используйте долгоживущие ключи или endpoint, который принимает только ключ и секрет.
  • Стиль endpoint определяется в основном автоматически. URL-адреса S3 могут адресовать бакет двумя способами: виртуальным хостингом (virtual-hosted) или путём (path style). Виртуальный хостинг используется, когда хост содержит amazonaws.com, иначе стиль пути. Для самостоятельно размещённых шлюзов это обычно то, что нужно; для шлюза, которому нужен другой стиль, переопределения нет.
  • Неверный регион повторяется один раз с регионом, который сообщает DuckDB. Если и это не удаётся, ошибка показывается как есть.
  • Требуется сеть: INSTALL httpfs загружает расширение при первом использовании. Просмотр отправляет HTTP- или HTTPS-запросы на настроенный endpoint (с http:// выбирается HTTP, иначе используется HTTPS). Эти запросы передают метаданные, такие как имена бакетов и префиксы ключей, а также сведения аутентификации в подписанных заголовках; при просмотре локальные файлы баз данных или результаты запросов не выгружаются. Запросы к удалённым объектам скачивают данные на ваш компьютер через httpfs.

Решение проблем ​

СимптомВероятная причина
Просмотр не работает сразу после настройкиНеверный регион или endpoint; проверьте сообщение в боковой панели
Ошибки на самостоятельно размещённом endpointНеверный стиль адресации или endpoint, требующий токен сеанса
Ошибка установки httpfsНет сети или прокси блокирует загрузку расширения
Учётные данные как будто забытыБыла открыта или изменена база данных, что по замыслу очищает их

Когда DuckLocal упакован как подписанное приложение, для загрузки расширения httpfs требуется право com.apple.security.cs.disable-library-validation; в поставляемом скрипте упаковки оно уже есть.

Опубликовано под лицензией Apache-2.0.