# S3 и httpfs

> Выполняйте запросы к Amazon S3 и S3-совместимым хранилищам из DuckLocal с помощью httpfs из DuckDB: настройте учётные данные, просматривайте бакеты и запускайте SQL по удалённым файлам.

Source: https://ducklocal.app/docs/ru/s3

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

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

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

| Поле | По умолчанию | Примечания |
| --- | --- | --- |
| Endpoint | `s3.amazonaws.com` | `http://` учитывается; иначе используется HTTPS |
| Region | `us-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 — фильтры и выбор
столбцов передаются в чтение файла. Запрос заменяет всё, что было в активной
вкладке.

Щёлкать можно только по ключам, распознанным как файлы данных. Распознаваемые
расширения те же, что и для локальных файлов; см. [Источники
данных](data-sources.md#supported-file-formats).

## Ограничения {#limitations}

- **Просмотр доступен только для чтения.** В браузере нет загрузки, скачивания в
  файл, удаления, копирования или создания бакета. Запросы по-прежнему скачивают
  удалённые данные.
- **Нет токенов сеанса.** Заголовок `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`; в
поставляемом скрипте упаковки оно уже есть.
