> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> 指定された `フォーマット` と `structure` を使用して `URL` からテーブルを作成します

# url

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            ClickHouse Cloud では利用できません
        </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            実験的な機能です。 <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">詳細を見る。</a></u>
        </div>;
};

`url` 関数は、指定された `フォーマット` と `structure` を使用して `URL` からテーブルを作成します。

`url` 関数は、[URL](/docs/ja/reference/engines/table-engines/special/url) テーブルのデータに対する `SELECT` クエリおよび `INSERT` クエリで使用できます。

<div id="syntax">
  ## 構文
</div>

```sql theme={null}
url(URL [,format] [,structure] [,headers])
```

<div id="parameters">
  ## パラメーター
</div>

| Parameter   | Description                                                                                                                                                                                                                                                                                                                      |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `URL`       | スキームによってバックエンドが選択される、単一引用符で囲んだ URL です。`http`/`https` (または未認識の) URL は `GET` または `POST` リクエストを受け付けるサーバーアドレスです (それぞれ `SELECT` クエリ、`INSERT` クエリに対応) 。認識される非 HTTP スキーム (`file://`、`s3://`、`az://`、`hdfs://`、…) は、対応する テーブル関数 に委譲されます。詳しくは [URL スキームによる振り分け](#scheme-dispatch) を参照してください。型: [String](/docs/ja/reference/data-types/string)。 |
| `format`    | データの[フォーマット](/docs/ja/reference/formats/index)です。型: [String](/docs/ja/reference/data-types/string)。                                                                                                                                                                                                                                        |
| `structure` | `'UserID UInt64, Name String'` フォーマットで指定するテーブル構造です。カラム名と型を決定します。型: [String](/docs/ja/reference/data-types/string)。                                                                                                                                                                                                                    |
| `headers`   | `'headers('key1'='value1', 'key2'='value2')'` フォーマットのヘッダーです。HTTP 呼び出し用のヘッダーを設定できます。                                                                                                                                                                                                                                              |

<div id="returned_value">
  ## 戻り値
</div>

指定されたフォーマットと構造を持ち、指定した`URL`のデータを含むテーブル。

<div id="examples">
  ## 例
</div>

[CSV](/docs/ja/reference/formats/CSV/CSV) フォーマットで応答する HTTP サーバーから、`String` 型と [UInt32](/docs/ja/reference/data-types/int-uint) 型のカラムを含むテーブルの先頭 3 行を取得します。

```sql theme={null}
SELECT * FROM url('http://127.0.0.1:12345/', CSV, 'column1 String, column2 UInt32', headers('Accept'='text/csv; charset=utf-8')) LIMIT 3;
```

`URL` からテーブルへデータを挿入するには:

```sql theme={null}
CREATE TABLE test_table (column1 String, column2 UInt32) ENGINE=Memory;
INSERT INTO FUNCTION url('http://127.0.0.1:8123/?query=INSERT+INTO+test_table+FORMAT+CSV', 'CSV', 'column1 String, column2 UInt32') VALUES ('http interface', 42);
SELECT * FROM test_table;
```

<div id="scheme-dispatch">
  ## URL スキームによる振り分け
</div>

`url` 関数は、他のファイルストレージおよびオブジェクトストレージのテーブル関数を統一的に扱うラッパーとして機能します。URL スキームに基づいて適切なバックエンドに振り分けられるため、サポートされている任意の場所から単一の統一された構文で読み取ることができます。

| Scheme                             | 振り分け先                                                                             |
| ---------------------------------- | --------------------------------------------------------------------------------- |
| `http`, `https` (および認識されない任意のスキーム) | `URL` エンジン自体 (HTTP `GET`/`POST`)                                                  |
| `file`                             | [`file`](/docs/ja/reference/functions/table-functions/file) 関数                         |
| `s3`, `gs`, `gcs`, `oss`           | [`s3`](/docs/ja/reference/functions/table-functions/s3) 関数                             |
| `az`, `azure`, `abfss`, `abfs`     | [`azureBlobStorage`](/docs/ja/reference/functions/table-functions/azureBlobStorage) 関数 |
| `hdfs`                             | [`hdfs`](/docs/ja/reference/functions/table-functions/hdfs) 関数                         |

追加設定なしで S3 URI mapper が具体的なエンドポイントに解決できる S3 スキーム (`s3` と `gs`/`gcs`/`oss`) のみが振り分けの対象です。その他の S3-compatible ベンダーのスキーム (`cos`、`obs`、`eos`、…) はリージョン固有で、デフォルトのエンドポイントマッピングがありません。そのため、`cos://…` URL は認識されないスキームとして扱われ、エラーとして報告されます。これらのバックエンドでは、[`s3`](/docs/ja/reference/functions/table-functions/s3) 関数を直接使用してください (`url_scheme_mappers` を設定したうえで) 。

`file://` の場合、相対パス (`file://data.csv`) は [user\_files](/docs/ja/reference/settings/server-settings/settings#user_files_path) ディレクトリ内で解決され、絶対パス (`file:///home/user/data.csv`) は通常どおりその配下を指している必要があります。

`format`、`structure`、`compression_method` の引数と [url\_base](#resolving-relative-urls) 設定は、振り分け先にかかわらず同じように機能します。

```sql theme={null}
SELECT * FROM url('file://data.csv', CSV, 'a UInt32, b String');
SELECT * FROM url('s3://clickhouse-public-datasets/hits_compatible/hits.csv');
```

スキームの振り分けは、[`urlCluster`](/docs/ja/reference/functions/table-functions/urlCluster) ではまだサポートされていません。`urlCluster` に `http(s)` 以外のスキームを渡すと、エラーになって拒否されます。そうしたバックエンドでは、代わりに対応するクラスター関数 (`s3Cluster`、`azureBlobStorageCluster`、`hdfsCluster`、…) を使用してください。

<div id="globs-in-url">
  ## URL 内の globs
</div>

`{ }` 内のパターンは、分片のセットを生成したり、フェイルオーバー先のアドレスを指定したりするために使用されます。サポートされているパターンの種類と例については、[remote](/docs/ja/reference/functions/table-functions/remote#globs-in-addresses) 関数の説明を参照してください。
パターン内の文字 `|` は、フェイルオーバー先のアドレスを指定するために使用されます。これらは、パターンに記載された順序どおりに順番に試行されます。生成されるアドレス数は、[glob\_expansion\_max\_elements](/docs/ja/reference/settings/session-settings#glob_expansion_max_elements) 設定によって制限されます。
URL パスでの glob 構文 (`*`、`{a,b}`、`{N..M}`、`**` など) については、[パス内の globs](/docs/ja/reference/functions/table-functions/file#globs-in-path) を参照してください。なお、`?` は URL ではクエリ文字列の開始を表すため、パス部分ではワイルドカードとして使用できません。

<div id="wildcards-with-http-index-pages">
  ## HTTPインデックスページでのワイルドカード
</div>

`url` および `URL` テーブルエンジンでは、ClickHouse は HTTP インデックスページ (HTML または平文) を取得し、レスポンスボディから URL を抽出することでワイルドカードを展開できます。これにより、サーバーがディレクトリ一覧を公開している場合は、`/**/` のようなパターンを使用できます。

注意:

* 相対 URL は、インデックスページの URL を基準に解決されます。
* `URL` テンプレートは、インデックスページを取得する前に展開されます。これには、カンマ区切りおよび数値範囲の分片展開と、パス部分の外側にある `|` フェイルオーバーオプションが含まれます。
* パス部分の内側にある `|` フェイルオーバーパターンは、HTTP インデックスページ展開ではサポートされていません。
* ワイルドカードの照合は、URL のパス部分に適用されます。
* 一覧に含まれる URL にすでにクエリ文字列またはフラグメントが含まれている場合は、ソース URL のものよりそちらが優先されます。含まれていない場合は、ソース URL のクエリ文字列とフラグメントが使用されます。
* 空の一覧も許可されます。インデックスページに対する HTTP エラー (例: 404) は例外を発生させます。
* インデックスページの最大サイズは、[max\_http\_index\_page\_size](/docs/ja/reference/settings/server-settings/settings#max_http_index_page_size) によって制限されます。
* 再帰的な展開中に読み取るディレクトリの最大数は、[url\_wildcard\_max\_directories\_to\_read](/docs/ja/reference/settings/session-settings#url_wildcard_max_directories_to_read) によって制限されます。

例:

```sql theme={null}
SELECT count()
FROM url('https://ftp.gnu.org/gnu/wget/wget-1.21*.tar.gz', 'RawBLOB')
SETTINGS max_threads = 1, allow_experimental_url_wildcard_from_index_pages = 1;
```

<div id="virtual-columns">
  ## 仮想カラム
</div>

* `_path` — `URL` のパス。型: `LowCardinality(String)`。
* `_file` — `URL` のリソース名。型: `LowCardinality(String)`。
* `_size` — リソースのサイズ (バイト単位) 。型: `Nullable(UInt64)`。サイズが不明な場合、値は `NULL` です。
* `_time` — ファイルの最終更新時刻。型: `Nullable(DateTime)`。時刻が不明な場合、値は `NULL` です。
* `_headers` - HTTP レスポンスヘッダー。型: `Map(LowCardinality(String), LowCardinality(String))`。

<div id="hive-style-partitioning">
  ## `use_hive_partitioning` 設定
</div>

`use_hive_partitioning` 設定を 1 にすると、ClickHouse はパス (`/name=value/`) 内の Hive スタイルのパーティション化を検出し、クエリ内でパーティションカラムを仮想カラムとして使用できるようになります。これらの仮想カラムには、パーティション化されたパス内と同じ名前が付きます。

**例**

Hive スタイルのパーティション化で作成された仮想カラムを使用する

```sql theme={null}
SELECT * FROM url('http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;
```

<div id="resolving-relative-urls">
  ## 相対 URL の解決
</div>

[url\_base](/docs/ja/reference/settings/session-settings#url_base) 設定を使用すると、`url` 関数に相対 URL を渡せます。`url_base` が設定されていて、関数の引数が相対参照である場合、その参照は [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) に従ってベース URL を基準に解決されます。

解決規則は次のとおりです。

* **パス相対** (例: `data.csv`) : ベース URL のパスにマージされ、ベースパスの最後の `/` 以降はすべて置き換えられます。末尾のスラッシュの有無は重要です。`https://example.com/dir/` + `data.csv` は `https://example.com/dir/data.csv` になりますが、`https://example.com/dir` + `data.csv` は `https://example.com/data.csv` になります。ドットセグメント (`./` と `../`) は正規化されます。
* **ホスト相対** (例: `/test/data.csv`) : ベース URL のスキームとホストを使用して解決されます。
* **スキーム相対** (例: `//other.com/test/data.csv`) : ベース URL のスキームを使用して解決されます。
* **クエリのみ** (例: `?x=1`) : 完全なベースパスに付加され、既存のクエリやフラグメントは置き換えられます。
* **フラグメントのみ** (例: `#frag`) : ベース URL に付加され、クエリは保持されたまま、既存のフラグメントは置き換えられます。
* **空**: フラグメントを除いたベース URL を返します。
* **絶対 URL**: 変更せずそのまま渡されます。`url_base` は無視されます。

**例**

```sql theme={null}
SET url_base = 'https://raw.githubusercontent.com/ClickHouse/ClickHouse/master/';
SELECT * FROM url('tests/queries/0_stateless/data_csv/data.csv', CSV) LIMIT 3;
```

<div id="storage-settings">
  ## ストレージ設定
</div>

* [engine\_url\_skip\_empty\_files](/docs/ja/reference/settings/session-settings#engine_url_skip_empty_files) - 読み取り時に空のファイルをスキップできます。デフォルトでは無効です。
* [enable\_url\_encoding](/docs/ja/reference/settings/session-settings#enable_url_encoding) - URI 内のパスのデコード/エンコードを有効または無効にできます。デフォルトでは有効です。
* [url\_base](/docs/ja/reference/settings/session-settings#url_base) - `url` 関数に渡された相対 URL を解決するためのベース URL です。

<div id="permissions">
  ## 権限
</div>

`url` 関数を使用するには、`CREATE TEMPORARY TABLE` 権限が必要です。そのため、[readonly](/docs/ja/concepts/features/configuration/settings/permissions-for-queries#readonly) = 1 に設定されているユーザーは利用できません。少なくとも readonly = 2 が必要です。

<div id="related">
  ## 関連
</div>

* [仮想カラム](/docs/ja/reference/engines/table-engines/index#table_engines-virtual_columns)