# S3 と httpfs

> DuckDB の httpfs を使って、DuckLocal から Amazon S3 と S3 互換ストレージをクエリします。認証情報の設定、バケットの閲覧、リモートファイルへの SQL 実行を説明します。

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

DuckLocal は、DuckDB の `httpfs` 拡張機能を通じて S3 および S3 互換ストレージの
オブジェクトを読み取れます。タイトルバーの **S3** ボタンから設定します。

## 認証情報を設定する

ダイアログには 4 つのフィールドがあります:

| フィールド | 既定値 | 説明 |
| --- | --- | --- |
| 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 階層あたり **1,000 件** までです。応答がさらに多くの項目があると示していても
変わりません。それ以上のページングやプレフィックスの絞り込みボックス、検索はありません。
ある階層に 1,000 件を超えるオブジェクトがあるバケットは、実際にはそうでなくても
完了したように見えます。

## オブジェクトをクエリする

キーがデータファイルの拡張子を持つオブジェクトをクリックすると、アクティブなエディターに
次の内容が入ります:

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

これは通常のクエリです。読み取りは `httpfs` を通るため、DuckDB の
`read_parquet` / `read_csv_auto` の動作が適用され、プッシュダウンも含まれます。
フィルターや列の選択はファイルの読み取り側に押し込まれます。クエリはアクティブな
タブの内容を置き換えます。

クリックできるのはデータファイルとして認識されたキーだけです。認識される拡張子は
ローカルファイルの場合と同じです。[データソース](data-sources.md#supported-file-formats)を
参照してください。

## 制限事項 {#limitations}

- **閲覧は読み取り専用です。** ブラウザーにはアップロード、ファイルへのダウンロード、
  削除、コピー、バケット作成の操作はありません。ただしクエリはリモートのデータを
  ダウンロードします。
- **セッショントークンは使えません。** `X-Amz-Security-Token` ヘッダーは送信されないため、
  一時的な STS 認証情報は機能しません。長期間有効なキーを使うか、キーとシークレットだけで
  受け付けるエンドポイントを使ってください。
- **エンドポイント形式はほぼ自動です。** S3 の URL にはバケットを指定する方法が 2 つあります。
  仮想ホスト形式とパス形式です。ホストに `amazonaws.com` が含まれる場合は仮想ホスト形式、
  それ以外はパス形式が使われます。セルフホスト型のゲートウェイでは通常これで問題ありませんが、
  もう一方の形式が必要なゲートウェイには切り替える手段がありません。
- リージョンが間違っている場合は、DuckDB が返すリージョンを使って 1 回だけ再試行します。
  それも失敗すると、エラーがそのまま表示されます。
- ネットワークが必要です。`INSTALL httpfs` は初回使用時に拡張機能を取得します。
  閲覧時は設定したエンドポイントに HTTP または HTTPS リクエストを送ります（`http://`
  なら HTTP、それ以外は HTTPS）。これらのリクエストではバケット名やキーのプレフィックスと
  いったメタデータと、署名済みヘッダーの認証情報が送信されます。閲覧がローカルの
  データベースファイルやクエリ結果をアップロードすることはありません。リモート
  オブジェクトへのクエリは `httpfs` を通じてデータをマシンにダウンロードします。

## トラブルシューティング

| 症状 | 考えられる原因 |
| --- | --- |
| 設定した直後に閲覧が失敗する | リージョンまたはエンドポイントが間違っています。サイドバーに表示されるメッセージを確認してください |
| セルフホスト型エンドポイントでエラーになる | アドレス指定方式が違うか、セッショントークンを必要とするエンドポイントです |
| `httpfs` のインストールでエラーになる | ネットワークがないか、拡張機能のダウンロードを遮断するプロキシがあります |
| 認証情報が忘れられたように見える | データベースを開いたか切り替えたため、仕様どおり認証情報が消去されました |

署名済みアプリとしてパッケージ化された DuckLocal では、`httpfs` 拡張機能の読み込みに
`com.apple.security.cs.disable-library-validation` エンタイトルメントが必要です。
配布用のパッケージングスクリプトにはすでに含まれています。
