> ## 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. > 使用给定的 `format` 和 `结构` 从 `URL` 创建表 # url export const CloudNotSupportedBadge = () => { return

ClickHouse Cloud 不支持此功能

; }; export const ExperimentalBadge = () => { return

Experimental 功能。了解详情。

; }; `url` 函数使用给定的 `format` 和 `结构` 从 `URL` 创建表。 `url` 函数可用于对 [URL](/docs/zh/reference/engines/table-engines/special/url) 表中的数据执行 `SELECT` 和 `INSERT` 查询。

## 语法

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

## 参数

| Parameter | 描述 | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `URL` | 用单引号括起的 URL，其 URL 协议用于选择后端。`http`/`https` (或无法识别的) URL 是可接受 `GET` 或 `POST` 请求的服务器地址 (分别对应 `SELECT` 或 `INSERT` 查询) ；可识别的非 HTTP URL 协议 (`file://`、`s3://`、`az://`、`hdfs://`、…) 会委派给相应的表函数——参见[按 URL 协议分派](#scheme-dispatch)。类型：[String](/docs/zh/reference/data-types/string)。 | | `format` | 数据的[格式](/docs/zh/reference/formats/index)。类型：[String](/docs/zh/reference/data-types/string)。 | | `structure` | 采用 `'UserID UInt64, Name String'` 格式的结构，用于确定列名和类型。类型：[String](/docs/zh/reference/data-types/string)。 | | `headers` | 采用 `'headers('key1'='value1', 'key2'='value2')'` 格式的请求头。你可以为 HTTP 调用设置请求头。 |

## 返回值

一个采用指定格式和结构、包含已定义 `URL` 中数据的表。

## 示例

从以 [CSV](/docs/zh/reference/formats/CSV/CSV) 格式响应的 HTTP 服务器获取一个表的前 3 行，该表包含 `String` 和 [UInt32](/docs/zh/reference/data-types/int-uint) 类型的列。 ```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; ```

## 按 URL 协议分派

`url` 函数充当其他文件和对象存储表函数之上的统一包装层：它会根据 URL 协议分派到正确的后端。这样一来，你就可以用一套统一的语法，从任何受支持的位置读取数据。 | Scheme | Dispatches to | | --------------------------------------------- | --------------------------------------------------------------------------------- | | `http`, `https` (and any unrecognized scheme) | `URL` 引擎本身 (HTTP `GET`/`POST`) | | `file` | [`file`](/docs/zh/reference/functions/table-functions/file) 函数 | | `s3`, `gs`, `gcs`, `oss` | [`s3`](/docs/zh/reference/functions/table-functions/s3) 函数 | | `az`, `azure`, `abfss`, `abfs` | [`azureBlobStorage`](/docs/zh/reference/functions/table-functions/azureBlobStorage) 函数 | | `hdfs` | [`hdfs`](/docs/zh/reference/functions/table-functions/hdfs) 函数 | 只有那些无需额外配置、即可由 S3 URI mapper 解析为具体端点的 S3 协议 (`s3`，以及 `gs`/`gcs`/`oss`) 才会被分派。其他兼容 S3 的厂商协议 (`cos`、`obs`、`eos`、…) 具有区域特定性，且没有默认端点映射，因此像 `cos://…` 这样的 URL 会被视为无法识别的协议并报错；对于这些后端，请直接使用 [`s3`](/docs/zh/reference/functions/table-functions/s3) 函数 (并配置 `url_scheme_mappers`) 。对于 `file://`，相对路径 (`file://data.csv`) 会在 [user\_files](/docs/zh/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/zh/reference/functions/table-functions/urlCluster)：传递给 `urlCluster` 的非 `http(s)` scheme 目前会报错并被拒绝。对于这些后端，请改用对应的集群函数 (`s3Cluster`、`azureBlobStorageCluster`、`hdfsCluster` 等) 。

## URL 中的通配符

`{ }` 中的模式用于生成一组分片，或指定故障转移地址。支持的模式类型及示例，请参见 [remote](/docs/zh/reference/functions/table-functions/remote#globs-in-addresses) 函数说明。模式中的 `|` 字符用于指定故障转移地址。系统会按模式中列出的顺序依次遍历这些地址。生成的地址数量受 [glob\_expansion\_max\_elements](/docs/zh/reference/settings/session-settings#glob_expansion_max_elements) 设置限制。有关 URL 路径中的通配符语法 (例如 `*`、`{a,b}`、`{N..M}` 和 `**`) ，请参见 [路径中的通配符](/docs/zh/reference/functions/table-functions/file#globs-in-path)。请注意，`?` 在 URL 中用于标识查询字符串的开始，因此不能在路径部分用作通配符。

## 结合 HTTP 索引页使用通配符

对于 `url` 和 `URL` 表引擎，ClickHouse 可以通过拉取 HTTP 索引页 (HTML 或纯文本) ，并从响应正文中提取 URL 来展开通配符。当服务器提供目录列表时，这使得 `/**/` 之类的模式成为可能。注意： * 相对 URL 会基于索引页的 URL 进行解析。 * 在拉取索引页之前，会先展开 `URL` 模板，包括逗号分隔和数值范围的分片展开，以及路径组件之外的 `|` 故障转移选项。 * 不支持在 HTTP 索引页展开中使用路径组件内的 `|` 故障转移模式。 * 通配符匹配应用于 URL 的路径组件。 * 如果列出的 URL 已包含查询字符串或片段，则以其为准，而不是使用源 URL 中的对应部分。否则，将使用源 URL 中的查询字符串和片段。 * 允许列表为空；索引页返回 HTTP 错误 (例如 404) 时会引发异常。 * 索引页的最大大小受 [max\_http\_index\_page\_size](/docs/zh/reference/settings/server-settings/settings#max_http_index_page_size) 限制。 * 递归展开期间可读取的最大目录数受 [url\_wildcard\_max\_directories\_to\_read](/docs/zh/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; ```

## 虚拟列

* `_path` — `URL` 的路径。类型：`LowCardinality(String)`。 * `_file` — `URL` 的资源名。类型：`LowCardinality(String)`。 * `_size` — 资源大小 (以字节为单位) 。类型：`Nullable(UInt64)`。如果大小未知，则值为 `NULL`。 * `_time` — 文件的最后修改时间。类型：`Nullable(DateTime)`。如果时间未知，则值为 `NULL`。 * `_headers` - HTTP 响应头。类型：`Map(LowCardinality(String), LowCardinality(String))`。

## use\_hive\_partitioning 设置

当 `use_hive_partitioning` 设置为 1 时，ClickHouse 会检测路径中 Hive 风格的分区 (`/name=value/`) ，并允许在查询中将分区列作为虚拟列使用。这些虚拟列的名称将与分区路径中的名称相同。 **示例** 使用通过 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; ```

## 解析相对 URL

[url\_base](/docs/zh/reference/settings/session-settings#url_base) 设置允许向 `url` 函数传入相对 URL。设置了 `url_base` 后，如果函数参数是相对引用，则会按照 [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) 基于 base URL 对其进行解析。解析规则如下： * **相对路径** (例如 `data.csv`) ：与 base URL 的路径合并——base 路径中最后一个 `/` 之后的所有内容都会被替换。末尾斜杠很关键：`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`) ：使用 base URL 的 scheme 和主机进行解析。 * **相对 scheme** (例如 `//other.com/test/data.csv`) ：使用 base URL 的 scheme 进行解析。 * **仅查询字符串** (例如 `?x=1`) ：附加到完整的 base 路径，并替换现有的查询字符串或片段。 * **仅片段** (例如 `#frag`) ：附加到 base URL，保留查询字符串，并替换现有片段。 * **空值**：返回不带片段的 base 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; ```

## 存储设置

* [engine\_url\_skip\_empty\_files](/docs/zh/reference/settings/session-settings#engine_url_skip_empty_files) - 允许在读取时跳过空文件。默认情况下禁用。 * [enable\_url\_encoding](/docs/zh/reference/settings/session-settings#enable_url_encoding) - 允许启用/禁用 URI 中路径的解码/编码。默认情况下启用。 * [url\_base](/docs/zh/reference/settings/session-settings#url_base) - 用于解析传递给 `url` 函数的相对 URL 的基础 URL。

## 权限

`url` 函数需要具备 `CREATE TEMPORARY TABLE` 权限。因此，对于设置了 [readonly](/docs/zh/concepts/features/configuration/settings/permissions-for-queries#readonly) = 1 的用户，该函数无法使用。至少需要 readonly = 2。 * [虚拟列](/docs/zh/reference/engines/table-engines/index#table_engines-virtual_columns)