> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8a08bda2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> URL 相关函数文档

# URL 相关函数

<div id="overview">
  ## 概述
</div>

<Note>
  本节提到的函数经过优化，可实现最高性能，但大多数情况下并不遵循 RFC-3986 标准。
  实现 RFC-3986 的函数会在函数名后附加 `RFC`，并且通常速度较慢。
</Note>

处理既不包含用户信息字符串也不包含 `@` 符号的公开注册域名时，通常可以使用非 `RFC` 函数变体。
下表详细列出了 URL 中哪些符号可以 (`✔`) 或不可以 (`✗`) 被相应的 `RFC` 和非 `RFC` 变体解析：

| Symbol | non-`RFC` | `RFC` |   |
| ------ | --------- | ----- | - |
| ' '    | ✗         | ✗     |   |
| \t     | ✗         | ✗     |   |
| \<     | ✗         | ✗     |   |
| >      | ✗         | ✗     |   |
| %      | ✗         | ✔\*   |   |
| \{     | ✗         | ✗     |   |
| }      | ✗         | ✗     |   |
|        |           | ✗     | ✗ |
| \\     | ✗         | ✗     |   |
| ^      | ✗         | ✗     |   |
| \~     | ✗         | ✔\*   |   |
| \[     | ✗         | ✗     |   |
| ]      | ✗         | ✔     |   |
| ;      | ✗         | ✔\*   |   |
| =      | ✗         | ✔\*   |   |
| &      | ✗         | ✔\*   |   |

标有 `*` 的符号是 RFC 3986 中的子分隔符，允许用于 `@` 符号后的用户信息。

URL 函数分为两类：

* 提取 URL 各部分的函数。如果 URL 中不存在相应部分，则返回空字符串。
* 移除 URL 某一部分的函数。如果 URL 中没有对应内容，则 URL 保持不变。

<Note>
  下方的函数由 `system.functions` 系统表生成。
</Note>

{/*AUTOGENERATED_START*/}

<div id="URLHierarchy">
  ## URLHierarchy
</div>

Introduced in: v1.1.0

返回一个数组，其中包含按层级截断的 URL：在 `path` 和查询字符串中，以 `/`、`?` 和 `#` 为分隔符从末尾逐级截断。连续的分隔符字符按一个计算。结果的第一个元素包含协议和主机，后续元素则通过逐步延长路径形成层级结构。

**语法**

```sql theme={null}
URLHierarchy(url)
```

**参数**

* `url` — 要处理的 URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回一个由长度逐步增加的 URL 组成的层级数组。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT URLHierarchy('https://example.com/a/b?c=1')
```

```response title=Response theme={null}
['https://example.com/','https://example.com/a/','https://example.com/a/b','https://example.com/a/b?c=1']
```

<div id="URLPathHierarchy">
  ## URLPathHierarchy
</div>

引入版本：v1.1.0

返回一个数组，其中包含 URL 的路径部分，并在末尾以 `/`、`?` 和 `#` 为截断符。与 `URLHierarchy` 不同，结果不包含协议和主机，而是从路径开始。连续的分隔符会视为一个。

**语法**

```sql theme={null}
URLPathHierarchy(url)
```

**参数**

* `url` — 要处理的 URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回一个数组，其中包含按层级逐步变长的 URL 路径部分。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT URLPathHierarchy('https://example.com/a/b?c=1')
```

```response title=Response theme={null}
['/a/','/a/b','/a/b?c=1']
```

<div id="cutFragment">
  ## cutFragment
</div>

引入版本：v1.1.0

从 URL 中移除片段标识符，包括井号 (#) 。

**语法**

```sql theme={null}
cutFragment(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回去除了片段标识符的 URL。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT cutFragment('http://example.com/path?query=value#fragment123');
```

```response title=Response theme={null}
┌─cutFragment('http://example.com/path?query=value#fragment123')─┐
│ http://example.com/path?query=value                            │
└────────────────────────────────────────────────────────────────┘
```

<div id="cutQueryString">
  ## cutQueryString
</div>

引入版本：v1.1.0

从 URL 中去掉查询字符串 (包括问号) 。

**语法**

```sql theme={null}
cutQueryString(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回移除查询字符串后的 URL。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT cutQueryString('http://example.com/path?query=value&param=123#fragment');
```

```response title=Response theme={null}
┌─cutQueryString('http://example.com/path?query=value&param=123#fragment')─┐
│ http://example.com/path#fragment                                         │
└──────────────────────────────────────────────────────────────────────────┘
```

<div id="cutQueryStringAndFragment">
  ## cutQueryStringAndFragment
</div>

在 v1.1.0 中引入

从 URL 中移除查询字符串和片段标识符，包括问号和井号。

**语法**

```sql theme={null}
cutQueryStringAndFragment(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回去除了查询字符串和片段标识符的 URL。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT cutQueryStringAndFragment('http://example.com/path?query=value&param=123#fragment');
```

```response title=Response theme={null}
┌─cutQueryStringAndFragment('http://example.com/path?query=value&param=123#fragment')─┐
│ http://example.com/path                                                             │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="cutToFirstSignificantSubdomain">
  ## cutToFirstSignificantSubdomain
</div>

引入版本：v1.1.0

返回域名中从顶级子域开始，直到[第一个有效子域](/zh/reference/functions/regular-functions/url-functions#firstSignificantSubdomain) (含) 的部分。

**语法**

```sql theme={null}
cutToFirstSignificantSubdomain(url)
```

**参数**

* `url` — 要处理的 URL 或域名字符串。[`String`](/zh/reference/data-types/string)

**返回值**

如果可能，返回域名中从顶级子域到第一个有效子域的部分；否则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT
    cutToFirstSignificantSubdomain('https://news.clickhouse.com.tr/'),
    cutToFirstSignificantSubdomain('www.tr'),
    cutToFirstSignificantSubdomain('tr');
```

```response title=Response theme={null}
┌─cutToFirstSignificantSubdomain('https://news.clickhouse.com.tr/')─┬─cutToFirstSignificantSubdomain('www.tr')─┬─cutToFirstSignificantSubdomain('tr')─┐
│ clickhouse.com.tr                                                 │ tr                                       │                                      │
└───────────────────────────────────────────────────────────────────┴──────────────────────────────────────────┴──────────────────────────────────────┘
```

<div id="cutToFirstSignificantSubdomainCustom">
  ## cutToFirstSignificantSubdomainCustom
</div>

引入版本：v21.1.0

返回域名中从顶级子域开始直到第一个有效子域的部分。接受自定义的 [TLD 列表](https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains) 名称。如果你需要最新的 TLD 列表，或者有自定义列表，此函数会很有用。

**配置示例**

```yaml theme={null}
<!-- <top_level_domains_path>/var/lib/clickhouse/top_level_domains/</top_level_domains_path> -->
<top_level_domains_lists>
    <!-- https://publicsuffix.org/list/public_suffix_list.dat -->
    <public_suffix_list>public_suffix_list.dat</public_suffix_list>
    <!-- 注意：path 位于 top_level_domains_path 下 -->
</top_level_domains_lists>
```

**语法**

```sql theme={null}
cutToFirstSignificantSubdomainCustom(url, tld_list_name)
```

**参数**

* `url` — 要处理的 URL 或域名字符串。[`String`](/zh/reference/data-types/string)
* `tld_list_name` — 在 ClickHouse 中配置的自定义 TLD 列表的名称。[`const String`](/zh/reference/data-types/string)

**返回值**

返回域名中从顶级子域开始、直到第一个有效子域为止的部分。[`String`](/zh/reference/data-types/string)

**示例**

**对非标准域名使用自定义 TLD 列表**

```sql title=Query theme={null}
SELECT cutToFirstSignificantSubdomainCustom('bar.foo.there-is-no-such-domain', 'public_suffix_list')
```

```response title=Response theme={null}
foo.there-is-no-such-domain
```

<div id="cutToFirstSignificantSubdomainCustomRFC">
  ## cutToFirstSignificantSubdomainCustomRFC
</div>

引入版本：v22.10.0

返回域名中从顶级子域到第一个有效子域的部分。
接受自定义的 [TLD 列表](https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains) 名称。
如果你需要最新的 TLD 列表，或者使用自定义列表，此函数会很有用。
与 [cutToFirstSignificantSubdomainCustom](#cutToFirstSignificantSubdomainCustom) 类似，但符合 RFC 3986。

**配置示例**

```xml theme={null}
<!-- <top_level_domains_path>/var/lib/clickhouse/top_level_domains/</top_level_domains_path> -->
<top_level_domains_lists>
    <!-- https://publicsuffix.org/list/public_suffix_list.dat -->
    <public_suffix_list>public_suffix_list.dat</public_suffix_list>
    <!-- 注意：路径位于 top_level_domains_path 下 -->
</top_level_domains_lists>
```

**语法**

```sql theme={null}
cutToFirstSignificantSubdomainCustomRFC(url, tld_list_name)
```

**参数**

* `url` — 按照 RFC 3986 处理的 URL 或域名字符串。 - `tld_list_name` — 在 ClickHouse 中配置的自定义 TLD 列表名称。

**返回值**

返回域名中从顶级子域到第一个有效子域这一部分。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT cutToFirstSignificantSubdomainCustomRFC('www.foo', 'public_suffix_list');
```

```response title=Response theme={null}
┌─cutToFirstSignificantSubdomainCustomRFC('www.foo', 'public_suffix_list')─────┐
│ www.foo                                                                      │
└──────────────────────────────────────────────────────────────────────────────┘
```

<div id="cutToFirstSignificantSubdomainCustomWithWWW">
  ## cutToFirstSignificantSubdomainCustomWithWWW
</div>

引入版本：v21.1.0

返回域名中从顶级子域到第一个有效子域的部分，且不会去除 'www'。接受自定义 TLD 列表名称。如果你需要最新的 TLD 列表，或者使用自定义列表，此函数会很有用。

**配置示例**

````yaml theme={null}
<!-- <top_level_domains_path>/var/lib/clickhouse/top_level_domains/</top_level_domains_path> -->
<top_level_domains_lists>
    <!-- https://publicsuffix.org/list/public_suffix_list.dat -->
    <public_suffix_list>public_suffix_list.dat</public_suffix_list>
    <!-- 注意：path 位于 top_level_domains_path 下 -->
</top_level_domains_lists>
    

**Syntax**

```sql
cutToFirstSignificantSubdomainCustomWithWWW(url, tld_list_name)
````

**参数**

* `url` — 要处理的 URL 或域名字符串。 - `tld_list_name` — 在 ClickHouse 中配置的自定义 TLD 列表名称。

**返回值**

域名中从顶级子域到第一个有效子域的部分，且不会移除 'www'。 [`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT cutToFirstSignificantSubdomainCustomWithWWW('www.foo', 'public_suffix_list');
```

```response title=Response theme={null}
┌─cutToFirstSignificantSubdomainCustomWithWWW('www.foo', 'public_suffix_list')─┐
│ www.foo                                                                      │
└──────────────────────────────────────────────────────────────────────────────┘
```

<div id="cutToFirstSignificantSubdomainRFC">
  ## cutToFirstSignificantSubdomainCustomWithWWWRFC
</div>

引入版本：v22.10.0

返回域名中从顶级子域到第一个有效子域的部分，且不会去除 `www`。
接受自定义 TLD 列表名称。
如果你需要较新的 TLD 列表，或者使用自定义列表，此函数会很有用。
与 [cutToFirstSignificantSubdomainCustomWithWWW](#cutToFirstSignificantSubdomainCustomWithWWW) 类似，但遵循 [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)。

**配置示例**

````xml theme={null}
{/* <top_level_domains_path>/var/lib/clickhouse/top_level_domains/</top_level_domains_path> */}
<top_level_domains_lists>
    {/* https://publicsuffix.org/list/public_suffix_list.dat */}
    <public_suffix_list>public_suffix_list.dat</public_suffix_list>
    {/* 注意：path 位于 top_level_domains_path 下 */}
</top_level_domains_lists>
    

**Syntax**

```sql
cutToFirstSignificantSubdomainCustomWithWWWRFC(url, tld_list_name)
````

**参数**

* `url` — 要按照 RFC 3986 处理的 URL 或域名字串。 - `tld_list_name` — 在 ClickHouse 中配置的自定义 TLD 列表名称。

**返回值**

返回域名中从顶级子域到第一个有效子域的部分，且不会去除 `www`。[`String`](/zh/reference/data-types/string)

**示例**

**使用自定义 TLD 列表按 RFC 3986 解析并保留 www**

```sql title=Query theme={null}
SELECT cutToFirstSignificantSubdomainCustomWithWWWRFC('https://www.subdomain.example.custom', 'public_suffix_list')
```

```response title=Response theme={null}
www.example.custom
```

<div id="cutToFirstSignificantSubdomainWithWWW">
  ## cutToFirstSignificantSubdomainRFC
</div>

Introduced in：v22.10.0

返回域名中从顶级子域开始直到[“第一个有效子域”](/zh/reference/functions/regular-functions/url-functions#firstSignificantSubdomain)的部分。与 [`cutToFirstSignificantSubdomain`](#cutToFirstSignificantSubdomain) 类似，但遵循 [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)。

**Syntax**

```sql theme={null}
cutToFirstSignificantSubdomainRFC(url)
```

**参数**

* `url` — 要按 RFC 3986 处理的 URL 或域名字符串。[`String`](/zh/reference/data-types/string)

**返回值**

如果可能，返回域名中从顶级子域开始直到第一个有效子域 (含) 的部分；否则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT
    cutToFirstSignificantSubdomain('http://user:password@example.com:8080'),
    cutToFirstSignificantSubdomainRFC('http://user:password@example.com:8080');
```

```response title=Response theme={null}
┌─cutToFirstSignificantSubdomain('http://user:password@example.com:8080')─┬─cutToFirstSignificantSubdomainRFC('http://user:password@example.com:8080')─┐
│                                                                         │ example.com                                                                │
└─────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────────────┘
```

<div id="cutToFirstSignificantSubdomainWithWWWRFC">
  ## cutToFirstSignificantSubdomainWithWWW
</div>

引入版本：v20.12.0

返回域名中从顶级子域到“第一个有效子域”的部分，且不会去除 `www.`。

与 [`cutToFirstSignificantSubdomain`](#cutToFirstSignificantSubdomain) 类似，但如果存在 `www.` 前缀，则会保留它。

**语法**

```sql theme={null}
cutToFirstSignificantSubdomainWithWWW(url)
```

**参数**

* `url` — 要处理的 URL 或域名字符串。[`String`](/zh/reference/data-types/string)

**返回值**

返回域名中从顶级子域开始、直到第一个有效子域为止的部分 (如可能则包含 www) ；否则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT
    cutToFirstSignificantSubdomainWithWWW('https://news.clickhouse.com.tr/'),
    cutToFirstSignificantSubdomainWithWWW('www.tr'),
    cutToFirstSignificantSubdomainWithWWW('tr');
```

```response title=Response theme={null}
┌─cutToFirstSignificantSubdomainWithWWW('https://news.clickhouse.com.tr/')─┬─cutToFirstSignificantSubdomainWithWWW('www.tr')─┬─cutToFirstSignificantSubdomainWithWWW('tr')─┐
│ clickhouse.com.tr                                                        │ www.tr                                          │                                             │
└──────────────────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────┴─────────────────────────────────────────────┘
```

<div id="cutURLParameter">
  ## cutToFirstSignificantSubdomainWithWWWRFC
</div>

引入版本：v22.10.0

返回域名中从顶级子域到“第一个有效子域”为止的部分，且不会去除 'www'。与 [`cutToFirstSignificantSubdomainWithWWW`](#cutToFirstSignificantSubdomainWithWWW) 类似，但符合 [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)。

**语法**

```sql theme={null}
cutToFirstSignificantSubdomainWithWWWRFC(url)
```

**参数**

* `url` — 按照 RFC 3986 处理的 URL 或域名字符串。

**返回值**

如果可能，返回域名中从顶级子域开始直到第一个有效子域 (包括 'www') 的部分；否则返回空字符串 [`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT
    cutToFirstSignificantSubdomainWithWWW('http:%2F%2Fwwwww.nova@mail.ru/economicheskiy'),
    cutToFirstSignificantSubdomainWithWWWRFC('http:%2F%2Fwwwww.nova@mail.ru/economicheskiy');
```

```response title=Response theme={null}
┌─cutToFirstSignificantSubdomainWithWWW('http:%2F%2Fwwwww.nova@mail.ru/economicheskiy')─┬─cutToFirstSignificantSubdomainWithWWWRFC('http:%2F%2Fwwwww.nova@mail.ru/economicheskiy')─┐
│                                                                                       │ mail.ru                                                                                  │
└───────────────────────────────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="cutWWW">
  ## cutURLParameter
</div>

引入版本：v1.1.0

如果存在，则从 URL 中移除 `name` 参数。
此函数不会对参数名称中的字符进行编码或解码，例如，`Client ID` 和 `Client%20ID` 会被视为不同的参数名称。

**语法**

```sql theme={null}
cutURLParameter(url, name)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)
* `name` — URL 参数名。[`String`](/zh/reference/data-types/string) 或 [`Array(String)`](/zh/reference/data-types/array)

**返回值**

移除 `name` URL 参数后的 URL。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT
    cutURLParameter('http://bigmir.net/?a=b&c=d&e=f#g', 'a') AS url_without_a,
    cutURLParameter('http://bigmir.net/?a=b&c=d&e=f#g', ['c', 'e']) AS url_without_c_and_e;
```

```response title=Response theme={null}
┌─url_without_a────────────────┬─url_without_c_and_e──────┐
│ http://bigmir.net/?c=d&e=f#g │ http://bigmir.net/?a=b#g │
└──────────────────────────────┴──────────────────────────┘
```

<div id="decodeURLComponent">
  ## cutWWW
</div>

引入版本：v1.1.0

如果 URL 的域名以 `www.` 开头，则将其移除。

**语法**

```sql theme={null}
cutWWW(url)
```

**参数**

* `url` — URL。 [`String`](/zh/reference/data-types/string)

**返回值**

返回去除域名前导 `www.` 后的 URL。 [`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT cutWWW('http://www.example.com/path?query=value#fragment');
```

```response title=Response theme={null}
┌─cutWWW('http://www.example.com/path?query=value#fragment')─┐
│ http://example.com/path?query=value#fragment               │
└────────────────────────────────────────────────────────────┘
```

<div id="decodeURLFormComponent">
  ## decodeURLComponent
</div>

引入版本：v1.1.0

接受一个经过 URL 编码的字符串作为输入，并将其解码为原始的可读形式。

**语法**

```sql theme={null}
decodeURLComponent(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回解码后的 URL。 [`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT decodeURLComponent('http://127.0.0.1:8123/?query=SELECT%201%3B') AS DecodedURL;
```

```response title=Response theme={null}
┌─DecodedURL─────────────────────────────┐
│ http://127.0.0.1:8123/?query=SELECT 1; │
└────────────────────────────────────────┘
```

<div id="domain">
  ## decodeURLFormComponent
</div>

引入于：v1.1.0

使用表单编码规则 ([RFC-1866](https://www.rfc-editor.org/rfc/rfc1866.html)) 对 URL 编码字符串进行解码，其中 `+` 号会转换为空格，百分号编码的字符也会被解码。

**语法**

```sql theme={null}
decodeURLFormComponent(url)
```

**参数**

* `url` — URL。 [`String`](/zh/reference/data-types/string)

**返回值**

返回解码后的 URL。 [`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT decodeURLFormComponent('http://127.0.0.1:8123/?query=SELECT%201+2%2B3') AS DecodedURL;
```

```response title=Response theme={null}
┌─DecodedURL────────────────────────────────┐
│ http://127.0.0.1:8123/?query=SELECT 1 2+3 │
└───────────────────────────────────────────┘
```

<div id="domainRFC">
  ## domain
</div>

引入版本：v1.1.0

从 URL 中提取主机名。

URL 可以带协议，也可以不带协议。

**语法**

```sql theme={null}
domain(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

如果输入字符串可解析为 URL，则返回主机名；否则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT domain('svn+ssh://some.svn-hosting.com:80/repo/trunk');
```

```response title=Response theme={null}
┌─domain('svn+ssh://some.svn-hosting.com:80/repo/trunk')─┐
│ some.svn-hosting.com                                   │
└────────────────────────────────────────────────────────┘
```

<div id="domainWithoutWWW">
  ## domainRFC
</div>

引入版本：v22.10.0

从 URL 中提取主机名。
与 [`domain`](#domain) 类似，但遵循 [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) 规范。

**语法**

```sql theme={null}
domainRFC(url)
```

**参数**

* `url` — URL。 [`String`](/zh/reference/data-types/string)

**返回值**

如果输入字符串可解析为 URL，则返回主机名；否则返回空字符串。 [`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT
    domain('http://user:password@example.com:8080/path?query=value#fragment'),
    domainRFC('http://user:password@example.com:8080/path?query=value#fragment');
```

```response title=Response theme={null}
┌─domain('http://user:password@example.com:8080/path?query=value#fragment')─┬─domainRFC('http://user:password@example.com:8080/path?query=value#fragment')─┐
│                                                                           │ example.com                                                                  │
└───────────────────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────┘
```

<div id="domainWithoutWWWRFC">
  ## domainWithoutWWW
</div>

引入版本：v1.1.0

返回 URL 的域名；如果存在前缀 `www.`，则将其去除。

**语法**

```sql theme={null}
domainWithoutWWW(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

若输入字符串可解析为 URL (不含前导 `www.`) ，则返回域名；否则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT domainWithoutWWW('http://paul@www.example.com:80/');
```

```response title=Response theme={null}
┌─domainWithoutWWW('http://paul@www.example.com:80/')─┐
│ example.com                                         │
└─────────────────────────────────────────────────────┘
```

<div id="encodeURLComponent">
  ## domainWithoutWWWRFC
</div>

引入版本：v1.1.0

如果存在前导 `www.`，则返回去掉此前导部分的域名。与 [`domainWithoutWWW`](#domainWithoutWWW) 类似，但符合 [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)。

**语法**

```sql theme={null}
domainWithoutWWWRFC(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

如果输入字符串可解析为 URL，则返回域名 (不带前导 `www.`) ；否则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT
    domainWithoutWWW('http://user:password@www.example.com:8080/path?query=value#fragment'),
    domainWithoutWWWRFC('http://user:password@www.example.com:8080/path?query=value#fragment');
```

```response title=Response theme={null}
┌─domainWithoutWWW('http://user:password@www.example.com:8080/path?query=value#fragment')─┬─domainWithoutWWWRFC('http://user:password@www.example.com:8080/path?query=value#fragment')─┐
│                                                                                         │ example.com                                                                                │
└─────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="encodeURLFormComponent">
  ## encodeURLComponent
</div>

引入版本：v22.3.0

接受一个普通字符串，并将其转换为 URL 编码 (百分号编码) 格式，其中特殊字符会替换为对应的百分号编码表示。

**语法**

```sql theme={null}
encodeURLComponent(url)
```

**参数**

* `url` — URL。 [`String`](/zh/reference/data-types/string)

**返回值**

返回编码后的 URL。 [`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT encodeURLComponent('http://127.0.0.1:8123/?query=SELECT 1;') AS EncodedURL;
```

```response title=Response theme={null}
┌─EncodedURL───────────────────────────────────────────────┐
│ http%3A%2F%2F127.0.0.1%3A8123%2F%3Fquery%3DSELECT%201%3B │
└──────────────────────────────────────────────────────────┘
```

<div id="extractURLParameter">
  ## encodeURLFormComponent
</div>

引入版本：v22.3.0

按照表单编码规则 ([RFC-1866](https://www.rfc-editor.org/rfc/rfc1866.html)) 对字符串进行编码，其中空格会转换为 + 号，特殊字符会进行百分比编码。

**语法**

```sql theme={null}
encodeURLFormComponent(url)
```

**参数**

* `url` — URL。 [`String`](/zh/reference/data-types/string)

**返回值**

返回经过编码的 URL。 [`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT encodeURLFormComponent('http://127.0.0.1:8123/?query=SELECT 1 2+3') AS EncodedURL;
```

```response title=Response theme={null}
┌─EncodedURL────────────────────────────────────────────────┐
│ http%3A%2F%2F127.0.0.1%3A8123%2F%3Fquery%3DSELECT+1+2%2B3 │
└───────────────────────────────────────────────────────────┘
```

<div id="extractURLParameterNames">
  ## extractURLParameter
</div>

引入版本：v1.1.0

返回 URL 中 `name` 参数的值；如果不存在，则返回空字符串。
如果存在多个同名参数，则返回第一次出现的值。
该函数假定 `url` 参数中的该参数与 `name` 参数采用相同的编码方式。

**语法**

```sql theme={null}
extractURLParameter(url, name)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)
* `name` — 参数名。[`String`](/zh/reference/data-types/string)

**返回值**

返回名称为指定值的 URL 参数值。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT extractURLParameter('http://example.com/?param1=value1&param2=value2', 'param1');
```

```response title=Response theme={null}
┌─extractURLPa⋯, 'param1')─┐
│ value1                   │
└──────────────────────────┘
```

<div id="extractURLParameters">
  ## extractURLParameterNames
</div>

引入版本：v1.1.0

返回由 URL 参数名称对应的字符串组成的数组。
这些值不会被解码。

**语法**

```sql theme={null}
extractURLParameterNames(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回一个字符串数组，其中包含与 URL 参数名称对应的名称字符串。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT extractURLParameterNames('http://example.com/?param1=value1&param2=value2');
```

```response title=Response theme={null}
┌─extractURLPa⋯m2=value2')─┐
│ ['param1','param2']      │
└──────────────────────────┘
```

<div id="firstSignificantSubdomain">
  ## extractURLParameters
</div>

引入版本：v1.1.0

返回一个数组，其中包含与 URL 参数对应的 `name=value` 字符串。
这些值不会被解码。

**语法**

```sql theme={null}
extractURLParameters(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回一个数组，其中包含与 URL 参数对应的 `name=value` 字符串。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT extractURLParameters('http://example.com/?param1=value1&param2=value2');
```

```response title=Response theme={null}
┌─extractURLParame⋯&param2=value2')─┐
│ ['param1=value1','param2=value2'] │
└───────────────────────────────────┘
```

<div id="firstSignificantSubdomainCustom">
  ## firstSignificantSubdomain
</div>

引入版本：v1.1.0

返回“第一个有效子域名”。

如果二级域名是“com”“net”“org”或“co”，则第一个有效子域名为二级域名。
否则为三级域名。

例如，firstSignificantSubdomain('[https://news.clickhouse.com/\&#39](https://news.clickhouse.com/\&#39);) = 'clickhouse'，firstSignificantSubdomain ('[https://news.clickhouse.com.tr/\&#39](https://news.clickhouse.com.tr/\&#39);) = 'clickhouse'。

“无效”二级域名的列表以及其他实现细节在未来可能会发生变化。

**语法**

```sql theme={null}
firstSignificantSubdomain(url)
```

**参数**

* 无。

**返回值**

**示例**

**firstSignificantSubdomain**

```sql title=Query theme={null}
SELECT firstSignificantSubdomain('https://news.clickhouse.com/')
```

```response title=Response theme={null}
```

<div id="firstSignificantSubdomainCustomRFC">
  ## firstSignificantSubdomainCustom
</div>

引入版本：v21.1.0

使用自定义 TLD (顶级域名) 列表返回 URL 的第一个有效子域名。自定义 TLD 列表名称指向一个配置，用于定义哪些域名后缀应被视为顶级域。这对于非标准的 TLD 层级结构非常有用。该函数使用简化的 URL 解析算法，并假定协议及其后的所有内容都已被去掉。

**语法**

```sql theme={null}
firstSignificantSubdomainCustom(url, tld_list_name)
```

**参数**

* `url` — 要从中提取子域名的 URL。[`String`](/zh/reference/data-types/string)
* `tld_list_name` — 配置中自定义 TLD 列表的名称。[`String`](/zh/reference/data-types/string)

**返回值**

返回第一个有效的子域名。[`String`](/zh/reference/data-types/string)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT firstSignificantSubdomainCustom('https://news.example.com', 'public_suffix_list')
```

```response title=Response theme={null}
example
```

<div id="firstSignificantSubdomainRFC">
  ## firstSignificantSubdomainCustomRFC
</div>

引入版本：v22.10.0

与 `firstSignificantSubdomainCustom` 类似，但它使用符合 RFC 3986 的 URL 解析方式，而不是简化算法。

**语法**

```sql theme={null}
firstSignificantSubdomainCustomRFC(url, tld_list_name)
```

**参数**

* `url` — 要从中提取子域名的 URL。[`String`](/zh/reference/data-types/string)
* `tld_list_name` — 配置中自定义 TLD 列表的名称。[`String`](/zh/reference/data-types/string)

**返回值**

返回第一个有效的子域名。[`String`](/zh/reference/data-types/string)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT firstSignificantSubdomainCustomRFC('https://news.example.com', 'public_suffix_list')
```

```response title=Response theme={null}
example
```

<div id="fragment">
  ## firstSignificantSubdomainRFC
</div>

首次引入于：v22.10.0

根据 RFC 1034，返回“第一个有效子域名”。

**语法**

```sql theme={null}
firstSignificantSubdomainRFC(url)
```

**参数**

* 无。

**返回值**

**示例**

<div id="netloc">
  ## fragment
</div>

引入版本：v1.1.0

返回不包含开头哈希符号的片段标识符。

**语法**

```sql theme={null}
fragment(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回去掉开头哈希符号后的片段标识符。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT fragment('https://clickhouse.com/docs/getting-started/quick-start/cloud#1-create-a-clickhouse-service');
```

```response title=Response theme={null}
┌─fragment('http⋯ouse-service')─┐
│ 1-create-a-clickhouse-service │
└───────────────────────────────┘
```

<div id="path">
  ## netloc
</div>

引入版本：v20.5.0

从 URL 中提取网络位置部分 (`username:password@host:port`) 。

**语法**

```sql theme={null}
netloc(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回给定 URL 中的 `username:password@host:port`。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT netloc('http://paul@www.example.com:80/');
```

```response title=Response theme={null}
┌─netloc('http⋯e.com:80/')─┐
│ paul@www.example.com:80  │
└──────────────────────────┘
```

<div id="pathFull">
  ## path
</div>

自 v1.1.0 起引入

返回 URL 中不含查询字符串的路径。

**语法**

```sql theme={null}
path(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回 URL 中不含查询字符串的路径部分。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT path('https://clickhouse.com/docs/sql-reference/functions/url-functions/?query=value');
```

```response title=Response theme={null}
┌─path('https://clickhouse.com/en/sql-reference/functions/url-functions/?query=value')─┐
│ /docs/sql-reference/functions/url-functions/                                         │
└──────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="port">
  ## pathFull
</div>

在 v1.1.0 中引入

与 [`path`](#path) 相同，但还包含 URL 的查询字符串和片段。

**语法**

```sql theme={null}
pathFull(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回 URL 的路径，包含查询字符串和片段。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT pathFull('https://clickhouse.com/docs/sql-reference/functions/url-functions/?query=value#section');
```

```response title=Response theme={null}
┌─pathFull('https://clickhouse.com⋯unctions/?query=value#section')─┐
│ /docs/sql-reference/functions/url-functions/?query=value#section │
└──────────────────────────────────────────────────────────────────┘
```

<div id="portRFC">
  ## port
</div>

首次引入版本：v20.5.0

返回 URL 的端口；如果 URL 中不包含端口，或无法解析该 URL，则返回 `default_port`。

**语法**

```sql theme={null}
port(url[, default_port])
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)
* `default_port` — 可选。返回的默认端口号。默认为 `0`。[`UInt16`](/zh/reference/data-types/int-uint)

**返回值**

返回 URL 的端口；如果 URL 中不包含端口，或验证出错，则返回默认端口。[`UInt16`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT port('https://clickhouse.com:8443/docs'), port('https://clickhouse.com/docs', 443);
```

```response title=Response theme={null}
┌─port('https://clickhouse.com:8443/docs')─┬─port('https://clickhouse.com/docs', 443)─┐
│                                     8443 │                                      443 │
└──────────────────────────────────────────┴──────────────────────────────────────────┘
```

<div id="protocol">
  ## portRFC
</div>

引入版本：v22.10.0

返回端口；如果 URL 不包含端口或无法解析，则返回 `default_port`。
与 [`port`](#port) 类似，但符合 [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) 规范。

**语法**

```sql theme={null}
portRFC(url[, default_port])
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)
* `default_port` — 可选。要返回的默认端口号。默认为 `0`。[`UInt16`](/zh/reference/data-types/int-uint)

**返回值**

返回端口号；如果 URL 中不包含端口，或验证出错，则返回默认端口。[`UInt16`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT port('http://user:password@example.com:8080/'), portRFC('http://user:password@example.com:8080/');
```

```response title=Response theme={null}
┌─port('http:/⋯com:8080/')─┬─portRFC('htt⋯com:8080/')─┐
│                        0 │                     8080 │
└──────────────────────────┴──────────────────────────┘
```

<div id="queryString">
  ## protocol
</div>

引入版本：v1.1.0

从 URL 中提取协议。

典型返回值包括：http、https、ftp、mailto、tel、magnet。

**语法**

```sql theme={null}
protocol(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回 URL 的协议；如果无法确定，则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT protocol('https://clickhouse.com/');
```

```response title=Response theme={null}
┌─protocol('https://clickhouse.com/')─┐
│ https                               │
└─────────────────────────────────────┘
```

<div id="queryStringAndFragment">
  ## queryString
</div>

自 v1.1.0 起引入

返回 URL 的查询字符串，不包含开头的问号、`#` 以及 `#` 之后的所有内容。

**语法**

```sql theme={null}
queryString(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回 URL 的查询字符串，不包含开头的问号和片段标识符。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT queryString('https://clickhouse.com/docs?query=value&param=123#section');
```

```response title=Response theme={null}
┌─queryString(⋯3#section')─┐
│ query=value&param=123    │
└──────────────────────────┘
```

<div id="topLevelDomain">
  ## queryStringAndFragment
</div>

引入版本：v1.1.0

返回 URL 的查询字符串和片段标识符。

**语法**

```sql theme={null}
queryStringAndFragment(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

返回 URL 的查询字符串和片段标识符。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT queryStringAndFragment('https://clickhouse.com/docs?query=value&param=123#section');
```

```response title=Response theme={null}
┌─queryStringAnd⋯=123#section')─┐
│ query=value&param=123#section │
└───────────────────────────────┘
```

<div id="topLevelDomainRFC">
  ## topLevelDomain
</div>

版本引入：v1.1.0

从 URL 中提取顶级域名。

<Note>
  URL 可以包含协议，也可以不包含协议。
  例如：

  ```text theme={null}
  svn+ssh://some.svn-hosting.com:80/repo/trunk
  some.svn-hosting.com:80/repo/trunk
  https://clickhouse.com/time/
  ```
</Note>

**语法**

```sql theme={null}
topLevelDomain(url)
```

**参数**

* `url` — URL。[`String`](/zh/reference/data-types/string)

**返回值**

如果输入字符串可以解析为 URL，则返回域名；否则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT topLevelDomain('svn+ssh://www.some.svn-hosting.com:80/repo/trunk');
```

```response title=Response theme={null}
┌─topLevelDomain('svn+ssh://www.some.svn-hosting.com:80/repo/trunk')─┐
│ com                                                                │
└────────────────────────────────────────────────────────────────────┘
```

## topLevelDomainRFC

引入版本：v22.10.0

从 URL 中提取顶级域名。
与 [`topLevelDomain`](#topLevelDomain) 类似，但遵循 [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)。

**语法**

```sql theme={null}
topLevelDomainRFC(url)
```

**参数**

* `url` — URL。 [`String`](/zh/reference/data-types/string)

**返回值**

如果输入字符串可解析为 URL，则返回域名；否则返回空字符串。 [`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT topLevelDomain('http://foo:foo%41bar@foo.com'), topLevelDomainRFC('http://foo:foo%41bar@foo.com');
```

```response title=Response theme={null}
┌─topLevelDomain('http://foo:foo%41bar@foo.com')─┬─topLevelDomainRFC('http://foo:foo%41bar@foo.com')─┐
│                                                │ com                                               │
└────────────────────────────────────────────────┴───────────────────────────────────────────────────┘
```