跳转到主要内容
url 函数使用给定的 format 和 结构 从 URL 创建表。 url 函数可用于对 URL 表中的数据执行 SELECT 和 INSERT 查询。

​
语法

url(URL [,format] [,structure] [,headers])

​
参数

Parameter描述
URL用单引号括起的 HTTP 或 HTTPS 服务器地址，可接受 GET 或 POST 请求 (分别对应 SELECT 或 INSERT 查询) 。类型：String。
format数据的格式。类型：String。
structure采用 'UserID UInt64, Name String' 格式的结构，用于确定列名和类型。类型：String。
headers采用 'headers('key1'='value1', 'key2'='value2')' 格式的请求头。你可以为 HTTP 调用设置请求头。

​
返回值

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

​
示例

从以 CSV 格式响应的 HTTP 服务器获取一个表的前 3 行，该表包含 String 和 UInt32 类型的列。 
SELECT * FROM url('http://127.0.0.1:12345/', CSV, 'column1 String, column2 UInt32', headers('Accept'='text/csv; charset=utf-8')) LIMIT 3;
将 URL 中的数据插入到表中： 
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 中的通配符

{ } 中的模式用于生成一组分片，或指定故障转移地址。支持的模式类型及示例，请参见 remote 函数说明。 模式中的 | 字符用于指定故障转移地址。系统会按模式中列出的顺序依次遍历这些地址。生成的地址数量受 glob_expansion_max_elements 设置限制。

​
虚拟列

  • _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 风格分区生成的虚拟列 
SELECT * FROM url('http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

​
解析相对 URL

url_base 设置允许向 url 函数传入相对 URL。设置了 url_base 后，如果函数参数是相对引用，则会按照 RFC 3986 基于 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 会被忽略。
示例 
SET url_base = 'https://raw.githubusercontent.com/ClickHouse/ClickHouse/master/';
SELECT * FROM url('tests/queries/0_stateless/data_csv/data.csv', CSV) LIMIT 3;

​
存储设置

​
权限

url 函数需要具备 CREATE TEMPORARY TABLE 权限。因此，对于设置了 readonly = 1 的用户，该函数无法使用。至少需要 readonly = 2。
最后修改于 2026年6月10日