处理 IPv4 和 IPv6 地址的函数

IPv4CIDRToRange

引入版本：v20.1.0 接受一个 IPv4 地址及其无类别域间路由 (CIDR) 前缀长度，并以包含两个 IPv4 值的元组形式返回该子网的地址范围：即该子网中的第一个和最后一个地址。 IPv6 版本请参见 IPv6CIDRToRange。语法

IPv4CIDRToRange(ipv4, cidr)

参数

ipv4 — IPv4 地址。IPv4 或 String
cidr — CIDR 值。UInt8

返回值 返回一个 Tuple，其中包含两个表示子网范围的 IPv4 地址。Tuple(IPv4, IPv4) 示例 用法示例

Query

SELECT IPv4CIDRToRange(toIPv4('192.168.5.2'), 16);

Response

┌─IPv4CIDRToRange(toIPv4('192.168.5.2'), 16)─┐
│ ('192.168.0.0','192.168.255.255')          │
└────────────────────────────────────────────┘

IPv4NumToString

引入版本：v1.1.0 将 32 位整数转换为采用点分十进制表示法 (A.B.C.D 格式) 的 IPv4 地址字符串表示形式。使用大端字节序来解释输入。语法

IPv4NumToString(num)

别名: INET_NTOA 参数

num — 以 UInt32 表示的 IPv4 地址。UInt32

返回值 返回表示 MAC 地址的数值；如果格式无效，则返回 0。String 示例 使用示例

Query

SELECT IPv4NumToString(3232235521)

Response

192.168.0.1

IPv4NumToStringClassC

引入版本：v1.1.0 将 32 位整数转换为采用点分十进制表示法 (A.B.C.D 格式) 的 IPv4 地址字符串表示形式，类似于 IPv4NumToString，但将最后一个八位字节替换为 xxx。语法

IPv4NumToStringClassC(num)

参数

num — 以 UInt32 数值表示的 IPv4 地址。UInt32

返回值 返回 IPv4 地址字符串，其中最后一个八位字节被替换为 xxx。String 示例 带聚合的基础示例

Query

SELECT
    IPv4NumToStringClassC(ClientIP) AS k,
    count() AS c
FROM VALUES('ClientIP UInt32',
    (toUInt32(toIPv4('83.149.9.10'))), (toUInt32(toIPv4('83.149.9.11'))), (toUInt32(toIPv4('83.149.9.12'))),
    (toUInt32(toIPv4('217.118.81.5'))), (toUInt32(toIPv4('217.118.81.6'))),
    (toUInt32(toIPv4('213.87.129.1'))))
GROUP BY k
ORDER BY c DESC, k

Response

┌─k──────────────┬─c─┐
│ 83.149.9.xxx   │ 3 │
│ 217.118.81.xxx │ 2 │
│ 213.87.129.xxx │ 1 │
└────────────────┴───┘

IPv4StringToNum

引入版本：v1.1.0 将点分十进制表示法 (A.B.C.D 格式) 的 IPv4 地址字符串转换为对应的 32 位整数表示。 (与 IPv4NumToString 相反。) 如果 IPv4 地址格式无效，则会抛出异常。语法

IPv4StringToNum(string)

别名: INET_ATON 参数

string — IPv4 地址字符串。String

返回值 返回 IPv4 地址。UInt32 示例 使用示例

Query

SELECT IPv4StringToNum('192.168.0.1')

Response

3232235521

IPv4StringToNumOrDefault

首次引入版本：v22.3.0 将点分十进制表示法 (A.B.C.D 格式) 的 IPv4 地址字符串转换为对应的 32 位整数表示；如果 IPv4 地址格式无效，则返回 0。语法

IPv4StringToNumOrDefault(string)

参数

string — IPv4 地址的字符串。String

返回值 返回 IPv4 地址；如果地址无效，则返回 0。UInt32 示例 无效地址示例

Query

SELECT
    IPv4StringToNumOrDefault('127.0.0.1') AS valid,
    IPv4StringToNumOrDefault('invalid') AS invalid;

Response

┌──────valid─┬─invalid─┐
│ 2130706433 │       0 │
└────────────┴─────────┘

IPv4StringToNumOrNull

引入版本：v22.3.0 将 32 位整数转换为采用点分十进制表示法 (A.B.C.D 格式) 的 IPv4 地址字符串表示形式；但如果 IPv4 地址格式无效，则返回 NULL。语法

IPv4StringToNumOrNull(string)

参数

string — IPv4 地址字符串。String

返回值 返回 IPv4 地址；如果地址无效，则返回 NULL。Nullable(UInt32) 示例 地址无效示例

Query

SELECT
IPv4StringToNumOrNull('127.0.0.1') AS valid,
IPv4StringToNumOrNull('invalid') AS invalid;

Response

┌──────valid─┬─invalid─┐
│ 2130706433 │    ᴺᵁᴸᴸ │
└────────────┴─────────┘

IPv4ToIPv6

Introduced in: v1.1.0 将一个 (大端序) 32 位数解释为 IPv4 地址，再将其转换为对应的 FixedString(16) 格式 IPv6 地址。语法

IPv4ToIPv6(x)

参数

x — IPv4 地址。UInt32

返回值 返回以二进制格式表示的 IPv6 地址。FixedString(16) 示例 使用示例

Query

SELECT IPv6NumToString(IPv4ToIPv6(IPv4StringToNum('192.168.0.1'))) AS addr;

Response

┌─addr───────────────┐
│ ::ffff:192.168.0.1 │
└────────────────────┘

IPv6CIDRToRange

引入版本：v20.1.0 接受一个 IPv6 地址及其无类别域间路由 (CIDR) 前缀长度，并以包含两个 IPv6 值的元组形式返回该子网的地址范围：该子网中的最低地址和最高地址。 IPv4 版本请参见 IPv4CIDRToRange。语法

IPv6CIDRToRange(ipv6, cidr)

参数

ipv6 — IPv6 地址。IPv6 或 String
cidr — CIDR 值。UInt8

返回值 返回一个包含两个 IPv6 地址的 Tuple，用于表示子网范围。Tuple(IPv6, IPv6) 示例 使用示例

Query

SELECT IPv6CIDRToRange(toIPv6('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32);

Response

┌─IPv6CIDRToRange(toIPv6('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32)─┐
│ ('2001:db8::','2001:db8:ffff:ffff:ffff:ffff:ffff:ffff')                │
└────────────────────────────────────────────────────────────────────────┘

IPv6NumToString

引入版本：v1.1.0 将二进制格式 (FixedString(16)) 的 IPv6 地址转换为其标准文本表示。 IPv4 映射的 IPv6 地址显示格式为 ::ffff:111.222.33.44。语法

IPv6NumToString(x)

别名: INET6_NTOA 参数

x — 二进制格式的 IPv6 地址。FixedString(16) 或 IPv6

返回值 返回文本格式的 IPv6 地址字符串。String 示例 使用示例

Query

SELECT IPv6NumToString(toFixedString(unhex('2A0206B8000000000000000000000011'), 16)) AS addr;

Response

┌─addr─────────┐
│ 2a02:6b8::11 │
└──────────────┘

基于 hits 的 IPv6 分析

Query

CREATE TABLE hits_all (EventDate Date, ClientIP6 FixedString(16)) ENGINE = Memory;

INSERT INTO hits_all SELECT today(), IPv6StringToNum(addr) FROM VALUES('addr String',
    ('2a02:2168:aaa:bbbb::2'), ('2a02:2168:aaa:bbbb::2'), ('2a02:2168:aaa:bbbb::2'),
    ('2a02:6b8:0:fff::ff'), ('2a02:6b8:0:fff::ff'),
    ('::ffff:94.26.111.111'), ('::ffff:94.26.111.111'), ('::ffff:94.26.111.111'), ('::ffff:94.26.111.111'),
    ('::ffff:37.143.222.4'));

-- The addresses that are not an IPv4 address mapped into the IPv6 space.
SELECT
    IPv6NumToString(ClientIP6 AS k),
    count() AS c
FROM hits_all
WHERE EventDate = today() AND substring(ClientIP6, 1, 12) != unhex('00000000000000000000FFFF')
GROUP BY k
ORDER BY c DESC, k
LIMIT 10

Response

┌─IPv6NumToString(k)────┬─c─┐
│ 2a02:2168:aaa:bbbb::2 │ 3 │
│ 2a02:6b8:0:fff::ff    │ 2 │
└───────────────────────┴───┘

映射为 IPv6 的 IPv4 地址

Query

-- Without the filter, the mapped IPv4 addresses show up as well.
SELECT
    IPv6NumToString(ClientIP6 AS k),
    count() AS c
FROM hits_all
WHERE EventDate = today()
GROUP BY k
ORDER BY c DESC, k
LIMIT 10

Response

┌─IPv6NumToString(k)────┬─c─┐
│ ::ffff:94.26.111.111  │ 4 │
│ 2a02:2168:aaa:bbbb::2 │ 3 │
│ 2a02:6b8:0:fff::ff    │ 2 │
│ ::ffff:37.143.222.4   │ 1 │
└───────────────────────┴───┘

IPv6StringToNum

引入版本：v1.1.0 将 IPv6 地址从标准文本表示转换为二进制格式 (FixedString(16)) 。接受格式为 ::ffff:111.222.33.44. 的 IPv4 映射的 IPv6 地址。如果 IPv6 地址格式无效，则会抛出异常。如果输入字符串包含有效的 IPv4 地址，则返回其对应的 IPv6 地址。 HEX 可以为大写或小写。语法

IPv6StringToNum(string)

别名: INET6_ATON 参数

string — IPv6 地址字符串。String

返回值 以二进制格式返回 IPv6 地址。FixedString(16) 示例 基本示例

Query

SELECT addr, cutIPv6(IPv6StringToNum(addr), 0, 0) FROM (SELECT ['127.0.0.1', '1111::ffff'] AS addr) ARRAY JOIN addr;

Response

┌─addr───────┬─cutIPv6(IPv6StringToNum(addr), 0, 0)─┐
│ 127.0.0.1  │ ::ffff:127.0.0.1                     │
│ 1111::ffff │ 1111::ffff                           │
└────────────┴──────────────────────────────────────┘

IPv6StringToNumOrDefault

引入版本：v22.3.0 将 IPv6 地址从标准文本表示转换为二进制格式 (FixedString(16)) 。接受格式为 ::ffff:111.222.33.44. 的 IPv4 映射的 IPv6 地址。如果 IPv6 地址格式无效，则返回默认值 ::。语法

IPv6StringToNumOrDefault(string)

参数

string — IPv6 地址字符串。String

返回值 二进制格式的 IPv6 地址；如果地址无效，则返回以零填充的 FixedString(16)。FixedString(16) 示例 无效地址的基础示例

Query

SELECT
    IPv6NumToString(IPv6StringToNumOrDefault('2001:db8::1')) AS valid,
    IPv6NumToString(IPv6StringToNumOrDefault('invalid')) AS invalid;

Response

┌─valid───────┬─invalid─┐
│ 2001:db8::1 │ ::      │
└─────────────┴─────────┘

IPv6StringToNumOrNull

引入版本：v22.3.0 将 IPv6 地址从标准文本表示转换为二进制格式 (FixedString(16)) 。接受格式为 ::ffff:111.222.33.44. 的 IPv4 映射的 IPv6 地址。如果 IPv6 地址格式无效，则返回 NULL。语法

IPv6StringToNumOrNull(string)

参数

string — IPv6 地址字符串。String

返回值 返回二进制格式的 IPv6 地址；如果地址无效，则返回 NULL。Nullable(FixedString(16)) 示例 无效地址的基础示例

Query

SELECT
    IPv6NumToString(IPv6StringToNumOrNull('2001:db8::1')) AS valid,
    IPv6StringToNumOrNull('invalid') AS invalid;

Response

┌─valid───────┬─invalid─┐
│ 2001:db8::1 │ ᴺᵁᴸᴸ    │
└─────────────┴─────────┘

cutIPv6

引入版本：v1.1.0 接受一个 FixedString(16) 值，其中包含二进制格式的 IPv6 地址。返回一个字符串，以文本格式表示移除指定字节数后的地址。语法

cutIPv6(x, bytesToCutForIPv6, bytesToCutForIPv4)

参数

x — 二进制格式的 IPv6 地址。FixedString(16) 或 IPv6
bytesToCutForIPv6 — 要从 IPv6 中截去的字节数。UInt8
bytesToCutForIPv4 — 要从 IPv4 中截去的字节数。UInt8

返回值 返回一个字符串，其中包含删除了指定字节后的文本格式 IPv6 地址。String 示例 使用示例

Query

WITH
    IPv6StringToNum('2001:0DB8:AC10:FE01:FEED:BABE:CAFE:F00D') AS ipv6,
    IPv4ToIPv6(IPv4StringToNum('192.168.0.1')) AS ipv4
SELECT
    cutIPv6(ipv6, 2, 0),
    cutIPv6(ipv4, 0, 2)

Response

┌─cutIPv6(ipv6, 2, 0)─────────────────┬─cutIPv6(ipv4, 0, 2)─┐
│ 2001:db8:ac10:fe01:feed:babe:cafe:0 │ ::ffff:192.168.0.0  │
└─────────────────────────────────────┴─────────────────────┘

ipcryptDecrypt

引入版本：v26.10.0

此函数为实验性函数，在未来的发行版中可能会以不可预测的方式发生向后不兼容的变更。设置 enable_ipcrypt = 1 即可启用该函数。

使用相同的密钥，解密先前通过 ipcryptEncrypt 加密的 IP 地址。输入为 IPv4/IPv6 时返回 IPv6，输入为 String 时返回 String (与参考实现一致，IPv4 映射地址的结果会以 IPv4 文本形式输出) 。语法

ipcryptDecrypt(encrypted_ip, key)

参数

encrypted_ip — 要解密的已加密 IP 地址。IPv4 或 IPv6 或 String
key — 16 字节加密密钥 (原始字节或 32 个十六进制字符) ，必须为常量。String 或 FixedString

返回值 解密后的 IP 地址。输入为 IPv4/IPv6 时返回 IPv6，输入为 String 时返回 String。IPv6 或 String 示例 Round-trip：先加密再解密

Query

SET enable_ipcrypt = 1;
SELECT ipcryptDecrypt(ipcryptEncrypt(toIPv4('192.168.1.1'), unhex('00112233445566778899aabbccddeeff')), unhex('00112233445566778899aabbccddeeff'))

Response

::ffff:192.168.1.1

ipcryptEncrypt

引入版本：v26.10.0

此函数为实验性功能，在未来的发行版中可能会发生不可预测的向后不兼容的变更。请设置 enable_ipcrypt = 1 以启用该函数。

使用 16 字节密钥，通过确定性的保格式加密 (format-preserving encryption) 对 IP 地址进行加密。输入为 IPv4/IPv6 时返回 IPv6，输入为 String 时返回 String (与参考实现一致，IPv4 映射的结果会以 IPv4 文本形式输出) 。语法

ipcryptEncrypt(ip, key)

参数

ip — 要加密的 IP 地址。IPv4、IPv6 或 String
key — 16 字节的加密密钥 (原始字节或 32 个十六进制字符) ，必须为常量。String 或 FixedString

返回值 加密后的 IP 地址。输入为 IPv4/IPv6 时返回 IPv6，输入为 String 时返回 String。IPv6 或 String 示例 加密 IPv4 地址

Query

SET enable_ipcrypt = 1;
SELECT ipcryptEncrypt(toIPv4('192.168.1.1'), unhex('00112233445566778899aabbccddeeff'))

Response

c629:37a3:24f9:e1c3:705e:a51b:a160:f609

ipcryptPrefixDecrypt

引入版本：v26.10.0

此函数为实验性功能，在未来的发行版中可能会以不可预测的、向后不兼容的方式发生变更。如需启用，请设置 enable_ipcrypt = 1。

使用相同的密钥，解密先前通过 ipcryptPrefixEncrypt 加密的 IP 地址。返回类型与输入的地址类别保持一致：IPv4 仍为 IPv4，IPv6 仍为 IPv6。语法

ipcryptPrefixDecrypt(encrypted_ip, key)

参数

encrypted_ip — 要解密的已加密 IP 地址。IPv4 或 IPv6 或 String
key — 32 字节的加密密钥 (原始字节或 64 个十六进制字符) 。必须为常量。String 或 FixedString

返回值 解密后的 IP 地址。输入为 IPv4 时返回 IPv4，输入为 IPv6 时返回 IPv6，输入为 String 时返回 String。IPv4 或 IPv6 或 String 示例 保留前缀的先加密后解密 (round-trip)

Query

SET enable_ipcrypt = 1;
SELECT ipcryptPrefixDecrypt(ipcryptPrefixEncrypt(toIPv4('192.168.1.1'), unhex('00112233445566778899aabbccddeeffffeeddccbbaa99887766554433221100')), unhex('00112233445566778899aabbccddeeffffeeddccbbaa99887766554433221100'))

Response

192.168.1.1

ipcryptPrefixEncrypt

引入版本：v26.10.0

此函数为实验性功能，在未来的发行版中可能会以不可预测的方式发生向后不兼容的变更。设置 enable_ipcrypt = 1 即可启用该函数。

使用 32 字节密钥，以保留前缀的加密方式对 IP 地址进行加密。具有相同网络前缀的地址，加密后的地址同样具有相同的前缀。返回类型与输入类型保持一致：IPv4 仍为 IPv4，IPv6 仍为 IPv6。语法

ipcryptPrefixEncrypt(ip, key)

参数

ip — 要加密的 IP 地址。IPv4、IPv6 或 String
key — 32 字节的加密密钥 (原始字节或 64 个十六进制字符) 。必须为常量。String 或 FixedString

返回值 加密后的 IP 地址。输入为 IPv4 时返回 IPv4，输入为 IPv6 时返回 IPv6，输入为 String 时返回 String。IPv4、IPv6 或 String 示例 对 IPv4 进行前缀保留加密

Query

SET enable_ipcrypt = 1;
SELECT ipcryptPrefixEncrypt(toIPv4('192.168.1.1'), unhex('00112233445566778899aabbccddeeffffeeddccbbaa99887766554433221100'))

Response

43.223.59.191

isIPAddressInRange

自 v21.4.0 引入判断某个 IP 地址是否位于以无类别域间路由 (CIDR) 表示的网络范围内。此函数接受以字符串形式表示的 IPv4 和 IPv6 地址 (以及网络) 。如果地址的 IP 版本与 CIDR 不匹配，则返回 0。语法

isIPAddressInRange(address, prefix)

参数

address — IPv4 或 IPv6 地址。String
prefix — CIDR 表示法中的 IPv4 或 IPv6 网络前缀。String

返回值 如果该地址的 IP 版本与 CIDR 一致，则返回 1；否则返回 0。UInt8 示例 范围内的 IPv4 地址

Query

SELECT isIPAddressInRange('127.0.0.1', '127.0.0.0/8')

Response

IPv4 地址超出范围

Query

SELECT isIPAddressInRange('127.0.0.1', 'ffff::/16')

Response

IPv6 地址不在范围内

Query

SELECT isIPAddressInRange('::ffff:192.168.0.1', '::ffff:192.168.0.4/128')

Response

isIPv4String

首次引入版本：v21.1.0 判断输入字符串是否为 IPv4 地址。 IPv6 版本请参见 isIPv6String。语法

isIPv4String(string)

参数

string — 要检查的 IP 地址字符串。String

返回值 如果 string 是 IPv4 地址，则返回 1；否则返回 0。UInt8 示例 使用示例

Query

SELECT addr, isIPv4String(addr)
FROM(
SELECT ['0.0.0.0', '127.0.0.1', '::ffff:127.0.0.1'] AS addr
)
ARRAY JOIN addr;

Response

┌─addr─────────────┬─isIPv4String(addr)─┐
│ 0.0.0.0          │                  1 │
│ 127.0.0.1        │                  1 │
│ ::ffff:127.0.0.1 │                  0 │
└──────────────────┴────────────────────┘

isIPv6String

首次引入版本：v21.1.0 判断输入字符串是否为 IPv6 地址。 IPv4 版本请参见 isIPv4String。语法

isIPv6String(string)

参数

string — 要检查的 IP 地址字符串。String

返回值 如果 string 是 IPv6 地址，则返回 1；否则返回 0。UInt8 示例 用法示例

Query

SELECT addr, isIPv6String(addr)
FROM(SELECT ['::', '1111::ffff', '::ffff:127.0.0.1', '127.0.0.1'] AS addr)
ARRAY JOIN addr;

Response

┌─addr─────────────┬─isIPv6String(addr)─┐
│ ::               │                  1 │
│ 1111::ffff       │                  1 │
│ ::ffff:127.0.0.1 │                  1 │
│ 127.0.0.1        │                  0 │
└──────────────────┴────────────────────┘

toIPv4

引入版本：v20.1.0 将 IPv4 地址的字符串或 UInt32 形式转换为 IPv4 类型。它与 IPv4StringToNum 和 IPv4NumToString 函数类似，但同时支持字符串和无符号整数数据类型作为输入参数。语法

toIPv4(x)

参数

x — IPv4 地址，类型为 String 或 UInt8/16/32

返回值 返回 IPv4 地址。IPv4 示例 使用示例

Query

SELECT toIPv4('171.225.130.45');

Response

┌─toIPv4('171.225.130.45')─┐
│ 171.225.130.45           │
└──────────────────────────┘

与 IPv4StringToNum 和 IPv4NumToString 函数的对比。

Query

WITH
    '171.225.130.45' AS IPv4_string
SELECT
    hex(IPv4StringToNum(IPv4_string)),
    hex(toIPv4(IPv4_string))

Response

┌─hex(IPv4StringToNum(IPv4_string))─┬─hex(toIPv4(IPv4_string))─┐
│ ABE1822D                          │ ABE1822D                 │
└───────────────────────────────────┴──────────────────────────┘

从整数值转换

Query

SELECT toIPv4(2130706433);

Response

┌─toIPv4(2130706433)─┐
│ 127.0.0.1          │
└────────────────────┘

toIPv4OrDefault

引入版本：v22.3.0 将 IPv4 地址的字符串形式或 UInt32 形式转换为 IPv4 类型。如果 IPv4 地址格式无效，则返回 0.0.0.0 (即 0 IPv4) ，或者返回提供的默认 IPv4 值。语法

toIPv4OrDefault(string[, default])

参数

string — 要转换的 IP 地址字符串。String
default — 可选。如果字符串不是有效的 IPv4 地址，则返回该值。IPv4

返回值 返回转换后的 IPv4 地址；如果转换失败，则返回默认值。IPv4 示例 有效和无效的 IPv4 字符串

Query

WITH
    '192.168.1.1' AS valid_IPv4_string,
    '999.999.999.999' AS invalid_IPv4_string,
    'not_an_ip' AS malformed_string
SELECT
    toIPv4OrDefault(valid_IPv4_string) AS valid,
    toIPv4OrDefault(invalid_IPv4_string) AS default_value,
    toIPv4OrDefault(malformed_string, toIPv4('8.8.8.8')) AS provided_default;

Response

┌─valid───────┬─default_value─┬─provided_default─┐
│ 192.168.1.1 │ 0.0.0.0       │ 8.8.8.8          │
└─────────────┴───────────────┴──────────────────┘

toIPv4OrNull

引入版本：v22.3.0 将输入值转换为 IPv4 类型的值，但如果出错则返回 NULL。与 toIPv4 类似，但在转换出错时会返回 NULL，而不是抛出异常。支持的参数：

点分十进制表示法的 IPv4 地址字符串表示形式。
IPv4 地址的整数表示形式。

不支持的参数 (返回 NULL) ：

无效的 IP 地址格式。
IPv6 地址。
超出范围的值。
格式不正确的地址。

语法

toIPv4OrNull(x)

参数

x — IPv4 地址的字符串或整数形式。String 或 Integer

返回值 成功时返回 IPv4 地址，否则返回 NULL。IPv4 或 NULL 示例 使用示例

Query

SELECT
    toIPv4OrNull('192.168.1.1') AS valid_ip,
    toIPv4OrNull('invalid.ip') AS invalid_ip

Response

┌─valid_ip────┬─invalid_ip─┐
│ 192.168.1.1 │ ᴺᵁᴸᴸ       │
└─────────────┴────────────┘

toIPv4OrZero

Introduced in: v23.1.0 将输入值转换为 IPv4 类型的值；如果发生错误，则返回零 IPv4 地址。与 toIPv4 类似，但在转换出错时会返回零 IPv4 地址 (0.0.0.0) ，而不是抛出异常。支持的参数：

采用点分十进制表示法的 IPv4 地址字符串表示形式。
IPv4 地址的整数表示形式。

不支持的参数 (返回零 IPv4) ：

无效的 IP 地址格式。
IPv6 地址。
超出范围的值。

Syntax

toIPv4OrZero(x)

参数

x — IPv4 地址的字符串或整数表示。String 或 Integer

返回值 成功时返回 IPv4 地址，否则返回零 IPv4 地址 (0.0.0.0) 。IPv4 示例 使用示例

Query

SELECT
    toIPv4OrZero('192.168.1.1') AS valid_ip,
    toIPv4OrZero('invalid.ip') AS invalid_ip

Response

┌─valid_ip────┬─invalid_ip─┐
│ 192.168.1.1 │ 0.0.0.0    │
└─────────────┴────────────┘

toIPv6

Introduced in: v20.1.0 将字符串或 IPv6 地址的 UInt128 形式转换为 IPv6 类型。对于字符串，如果 IPv6 地址格式无效，则返回空值。与 IPv6StringToNum 和 IPv6NumToString 函数类似，这两个函数用于在 IPv6 地址与二进制格式 (即 FixedString(16)) 之间相互转换。如果输入字符串包含有效的 IPv4 地址，则返回该 IPv4 地址对应的 IPv6 等效形式。 Syntax

toIPv6(x)

参数

x — IP 地址。String 或 UInt128

返回值 返回 IPv6 地址。IPv6 示例 用法示例

Query

WITH '2001:438:ffff::407d:1bc1' AS IPv6_string
SELECT
    hex(IPv6StringToNum(IPv6_string)),
    hex(toIPv6(IPv6_string));

Response

┌─hex(IPv6StringToNum(IPv6_string))─┬─hex(toIPv6(IPv6_string))─────────┐
│ 20010438FFFF000000000000407D1BC1  │ 20010438FFFF000000000000407D1BC1 │
└───────────────────────────────────┴──────────────────────────────────┘

IPv4 到 IPv6 映射

Query

SELECT toIPv6('127.0.0.1');

Response

┌─toIPv6('127.0.0.1')─┐
│ ::ffff:127.0.0.1    │
└─────────────────────┘

toIPv6OrDefault

引入版本：v22.3.0 将字符串或 IPv6 地址的 UInt128 形式转换为 IPv6 类型。如果 IPv6 地址的格式无效，则返回 :: (IPv6 的 0 值) 或提供的默认 IPv6 值。语法

toIPv6OrDefault(string[, default])

参数

string — 要转换的 IP 地址字符串。 - default — 可选。当字符串格式无效时返回的值。

返回值 返回 IPv6 地址；如果参数 string 的格式无效，则返回 :: 或所提供的可选默认值。IPv6 示例 有效与无效的 IPv6 字符串

Query

WITH
    '2001:0db8:85a3:0000:0000:8a2e:0370:7334' AS valid_IPv6_string,
    '2001:0db8:85a3::8a2e:370g:7334' AS invalid_IPv6_string,
    'not_an_ipv6' AS malformed_string
SELECT
    toIPv6OrDefault(valid_IPv6_string) AS valid,
    toIPv6OrDefault(invalid_IPv6_string) AS default_value,
    toIPv6OrDefault(malformed_string, toIPv6('::1')) AS provided_default;

Response

┌─valid────────────────────────┬─default_value─┬─provided_default─┐
│ 2001:db8:85a3::8a2e:370:7334 │ ::            │ ::1              │
└──────────────────────────────┴───────────────┴──────────────────┘

toIPv6OrNull

引入版本：v22.3.0 将输入值转换为 IPv6 类型的值；如果发生错误，则返回 NULL。与 toIPv6 类似，但在转换出错时会返回 NULL，而不是抛出异常。支持的参数：

标准表示法的 IPv6 地址字符串表示形式。
IPv4 地址的字符串表示形式 (会转换为 IPv4 映射的 IPv6 地址) 。
IPv6 地址的二进制表示形式。

不支持的参数 (返回 NULL) ：

无效的 IP 地址格式。
格式不正确的 IPv6 地址。
超出范围的值。
无效的表示法。

语法

toIPv6OrNull(x)

参数

x — IPv6 或 IPv4 地址的字符串表示形式。String

返回值 成功时返回 IPv6 地址，否则返回 NULL。IPv6 或 NULL 示例 用法示例

Query

SELECT
    toIPv6OrNull('2001:0db8:85a3:0000:0000:8a2e:0370:7334') AS valid_ipv6,
    toIPv6OrNull('invalid::ip') AS invalid_ipv6

Response

┌─valid_ipv6───────────────────┬─invalid_ipv6─┐
│ 2001:db8:85a3::8a2e:370:7334 │ ᴺᵁᴸᴸ         │
└──────────────────────────────┴──────────────┘

toIPv6OrZero

引入版本：v23.1.0 将输入值转换为 IPv6 类型的值；如果出错，则返回全零 IPv6 地址。类似于 toIPv6，但在转换出错时会返回全零 IPv6 地址 (::) ，而不是抛出异常。支持的参数：

标准表示法的 IPv6 地址字符串表示形式。
IPv4 地址的字符串表示形式 (将转换为 IPv4 映射的 IPv6 地址) 。
IPv6 地址的二进制表示形式。

不支持的参数 (将返回全零 IPv6) ：

无效的 IP 地址格式。
格式不正确的 IPv6 地址。
超出范围的值。

语法

toIPv6OrZero(x)

参数

x — IPv6 或 IPv4 地址的字符串表示形式。String

返回值 如果成功，返回 IPv6 地址；否则返回全零 IPv6 地址 (::) 。IPv6 示例 用法示例

Query

SELECT
    toIPv6OrZero('2001:0db8:85a3:0000:0000:8a2e:0370:7334') AS valid_ipv6,
    toIPv6OrZero('invalid::ip') AS invalid_ipv6

Response

┌─valid_ipv6───────────────────┬─invalid_ipv6─┐
│ 2001:db8:85a3::8a2e:370:7334 │ ::           │
└──────────────────────────────┴──────────────┘

SQL 参考文档

数据类型

引擎

函数

格式

设置

系统表

数据湖

IPv4CIDRToRange

IPv4NumToString

IPv4NumToStringClassC

IPv4StringToNum

IPv4StringToNumOrDefault

IPv4StringToNumOrNull

IPv4ToIPv6

IPv6CIDRToRange

IPv6NumToString

IPv6StringToNum

IPv6StringToNumOrDefault

IPv6StringToNumOrNull

cutIPv6

ipcryptDecrypt

ipcryptEncrypt

ipcryptPrefixDecrypt

ipcryptPrefixEncrypt

isIPAddressInRange

isIPv4String

isIPv6String

toIPv4

toIPv4OrDefault

toIPv4OrNull

toIPv4OrZero

toIPv6

toIPv6OrDefault

toIPv6OrNull

toIPv6OrZero