S3 и httpfs
DuckLocal может читать объекты из S3 и S3-совместимых хранилищ через расширение httpfs DuckDB. Настройте его кнопкой S3 в строке заголовка.
Настройка учётных данных
В диалоге четыре поля:
| Поле | По умолчанию | Примечания |
|---|---|---|
| Endpoint | s3.amazonaws.com | http:// учитывается; иначе используется HTTPS |
| Region | us-east-1 | Передаётся как введено |
| Access Key ID | — | Обязательно |
| Secret Access Key | — | Обязательно, скрыто, с переключателем показа |
Подтверждение выполняет эквивалент:
INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE SECRET ducklocal_s3 (
TYPE s3, PROVIDER config,
KEY_ID '…', SECRET '…',
REGION '…', ENDPOINT '…'
);Учётные данные действуют только в течение сеанса. Они не записываются на диск и очищаются при открытии или смене базы данных, поэтому после этого их нужно настроить заново. Отдельного способа очистить учётные данные, кроме повторной настройки, нет.
Просмотр
После настройки в боковой панели появляется корень S3. Его содержимое загружается только при развёртывании: корень перечисляет бакеты, а каждый бакет или префикс — свои объекты. Бакеты и префиксы сортируются, а объекты показывают размер в удобочитаемом виде. Кнопка обновления перезагружает уровень или повторяет попытку после ошибки.
Список ограничен 1 000 записей на уровень, даже если ответ сообщает, что доступно больше. Более глубокого постраничного просмотра, поля фильтра по префиксу и поиска нет: бакет с более чем тысячей объектов на одном уровне будет выглядеть полным, хотя это не так.
Запросы к объектам
Щелчок по объекту, ключ которого имеет расширение файла данных, заполняет активный редактор:
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; в поставляемом скрипте упаковки оно уже есть.
