IPv4CIDRToRange
引入版本：v20.1.0
接收一个带有无类别域间路由 (CIDR) 前缀长度的 IPv4 地址，并返回该子网的地址范围，作为包含两个 IPv4 值的元组：该子网内的第一个地址和最后一个地址。
IPv6 版本请参见 IPv6CIDRToRange。
语法
IPv4CIDRToRange(ipv4, cidr)
参数
返回值
返回一个包含两个 IPv4 地址的元组，表示子网范围。Tuple(IPv4, IPv4)
示例
用法示例
SELECT IPv4CIDRToRange(toIPv4('192.168.5.2'), 16);
┌─IPv4CIDRToRange(toIPv4('192.168.5.2'), 16)─┐
│ ('192.168.0.0','192.168.255.255') │
└────────────────────────────────────────────┘
IPv4NumToString
引入于：v1.1.0
将 32 位整数转换为其 IPv4 地址的点分十进制字符串表示形式 (A.B.C.D 格式) 。
采用大端字节序解释输入值。
语法
别名：INET_NTOA
参数
num — 以 UInt32 无符号 32 位整数形式表示的 IPv4 地址。UInt32
返回值
返回表示 IPv4 地址的字符串，如果格式无效则返回 0。String
示例
用法示例
IPv4NumToString(3232235521)
IPv4NumToStringClassC
自 v1.1.0 引入
将 32 位整数转换为 IPv4 地址的点分十进制字符串表示 (A.B.C.D 格式) ，
类似于 IPv4NumToString，但会使用 xxx 来替代最后一个八位组。
语法
IPv4NumToStringClassC(num)
参数
num — 以 UInt32 数值表示的 IPv4 地址。UInt32
返回值
返回 IPv4 地址字符串，并将最后一个八位组替换为 xxx。String
示例
包含聚合的基本示例
SELECT
IPv4NumToStringClassC(ClientIP) AS k,
count() AS c
FROM test.hits
GROUP BY k
ORDER BY c DESC
LIMIT 10
┌─k──────────────┬─────c─┐
│ 83.149.9.xxx │ 26238 │
│ 217.118.81.xxx │ 26074 │
│ 213.87.129.xxx │ 25481 │
│ 83.149.8.xxx │ 24984 │
│ 217.118.83.xxx │ 22797 │
│ 78.25.120.xxx │ 22354 │
│ 213.87.131.xxx │ 21285 │
│ 78.25.121.xxx │ 20887 │
│ 188.162.65.xxx │ 19694 │
│ 83.149.48.xxx │ 17406 │
└────────────────┴───────┘
IPv4StringToNum
引入版本：v1.1.0
将点分十进制表示法的 IPv4 地址字符串 (A.B.C.D 格式) 转换为对应的 32 位整数形式。 (是 IPv4NumToString 的反向操作) 。
如果 IPv4 地址格式无效，则会抛出异常。
语法
别名: INET_ATON
参数
返回值
返回 IPv4 地址的数值表示形式。UInt32
示例
使用示例
IPv4StringToNum('192.168.0.1')
IPv4StringToNumOrDefault
引入于：v22.3.0
将点分十进制表示法 (A.B.C.D 格式) 的 IPv4 地址字符串转换为对应的 32 位整数表示形式。如果 IPv4 地址格式无效，则返回 0。
语法
IPv4StringToNumOrDefault(string)
参数
返回值
返回 IPv4 地址，如果无效则返回 0。UInt32
示例
无效地址示例
SELECT
IPv4StringToNumOrDefault('127.0.0.1') AS valid,
IPv4StringToNumOrDefault('invalid') AS invalid;
┌──────valid─┬─invalid─┐
│ 2130706433 │ 0 │
└────────────┴─────────┘
IPv4StringToNumOrNull
自 v22.3.0 引入
将 32 位整数转换为其 IPv4 地址的点分十进制字符串表示 (A.B.C.D 格式) ，如果 IPv4 地址格式无效，则返回 NULL。
语法
IPv4StringToNumOrNull(string)
参数
返回值
返回 IPv4 地址，如果地址无效则返回 NULL。Nullable(UInt32)
示例
无效地址示例
SELECT
IPv4StringToNumOrNull('127.0.0.1') AS valid,
IPv4StringToNumOrNull('invalid') AS invalid;
┌──────valid─┬─invalid─┐
│ 2130706433 │ ᴺᵁᴸᴸ │
└────────────┴─────────┘
IPv4ToIPv6
引入于：v1.1.0
将一个大端序的 32 位整数值解释为 IPv4 地址，然后将该地址进一步解释为对应的 IPv6 地址，并以 FixedString(16) 格式表示。
语法
参数
返回值
返回以二进制格式表示的 IPv6 地址。FixedString(16)
示例
使用示例
SELECT IPv6NumToString(IPv4ToIPv6(IPv4StringToNum('192.168.0.1'))) AS addr;
┌─addr───────────────┐
│ ::ffff:192.168.0.1 │
└────────────────────┘
IPv6CIDRToRange
自 v20.1.0 起可用
接收带有无类别域间路由 (CIDR) 前缀长度的 IPv6 地址，并返回该子网的地址范围，作为包含两个 IPv6 值的元组：该子网中的最小地址和最大地址。
IPv4 版本请参见 IPv4CIDRToRange。
语法
IPv6CIDRToRange(ipv6, cidr)
参数
返回值
返回一个包含两个 IPv6 地址的元组，用于表示子网范围。Tuple(IPv6, IPv6)
示例
使用示例
SELECT IPv6CIDRToRange(toIPv6('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32);
┌─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
将 IPv6 地址从二进制形式 (FixedString(16)) 转换为其标准文本表示形式。
IPv4 映射的 IPv6 地址显示为 ::ffff:111.222.33.44 格式。
语法
别名: INET6_NTOA
参数
返回值
返回以文本格式表示的 IPv6 地址字符串。String
示例
使用示例
SELECT IPv6NumToString(toFixedString(unhex('2A0206B8000000000000000000000011'), 16)) AS addr;
┌─addr─────────┐
│ 2a02:6b8::11 │
└──────────────┘
结合 hits 表的 IPv6 分析
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
LIMIT 10
┌─IPv6NumToString(ClientIP6)──────────────┬─────c─┐
│ 2a02:2168:aaa:bbbb::2 │ 24695 │
│ 2a02:2698:abcd:abcd:abcd:abcd:8888:5555 │ 22408 │
│ 2a02:6b8:0:fff::ff │ 16389 │
│ 2a01:4f8:111:6666::2 │ 16016 │
│ 2a02:2168:888:222::1 │ 15896 │
│ 2a01:7e00::ffff:ffff:ffff:222 │ 14774 │
│ 2a02:8109:eee:ee:eeee:eeee:eeee:eeee │ 14443 │
│ 2a02:810b:8888:888:8888:8888:8888:8888 │ 14345 │
│ 2a02:6b8:0:444:4444:4444:4444:4444 │ 14279 │
│ 2a01:7e00::ffff:ffff:ffff:ffff │ 13880 │
└─────────────────────────────────────────┴───────┘
IPv6 映射 IPv4 地址
SELECT
IPv6NumToString(ClientIP6 AS k),
count() AS c
FROM hits_all
WHERE EventDate = today()
GROUP BY k
ORDER BY c DESC
LIMIT 10
┌─IPv6NumToString(ClientIP6)─┬──────c─┐
│ ::ffff:94.26.111.111 │ 747440 │
│ ::ffff:37.143.222.4 │ 529483 │
│ ::ffff:5.166.111.99 │ 317707 │
│ ::ffff:46.38.11.77 │ 263086 │
│ ::ffff:79.105.111.111 │ 186611 │
│ ::ffff:93.92.111.88 │ 176773 │
│ ::ffff:84.53.111.33 │ 158709 │
│ ::ffff:217.118.11.22 │ 154004 │
│ ::ffff:217.118.11.33 │ 148449 │
│ ::ffff:217.118.11.44 │ 148243 │
└────────────────────────────┴────────┘
IPv6StringToNum
引入版本：v1.1.0
将 IPv6 地址从其标准文本表示转换为二进制格式 (FixedString(16)) 。
接受格式为 ::ffff:111.222.33.44. 的 IPv4 映射的 IPv6 地址。
如果 IPv6 地址格式无效，将抛出异常。
如果输入字符串包含有效的 IPv4 地址，则返回其对应的 IPv6 表示。
HEX 字母可以是大写或小写。
语法
别名: INET6_ATON
参数
返回值
返回 IPv6 地址的二进制格式。FixedString(16)
示例
基本示例
SELECT addr, cutIPv6(IPv6StringToNum(addr), 0, 0) FROM (SELECT ['notaddress', '127.0.0.1', '1111::ffff'] AS addr) ARRAY JOIN addr;
┌─addr───────┬─cutIPv6(IPv6StringToNum(addr), 0, 0)─┐
│ notaddress │ :: │
│ 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)
参数
返回值
二进制格式的 IPv6 地址；如果无效，则返回零填充的 FixedString(16)。FixedString(16)
示例
包含无效地址的简单示例
SELECT
IPv6NumToString(IPv6StringToNumOrDefault('2001:db8::1')) AS valid,
IPv6NumToString(IPv6StringToNumOrDefault('invalid')) AS invalid;
┌─valid───────┬─invalid─┐
│ 2001:db8::1 │ :: │
└─────────────┴─────────┘
IPv6StringToNumOrNull
引入版本：v22.3.0
将 IPv6 地址从其标准文本表示形式转换为二进制格式 (FixedString(16)) 。
接受格式为 ::ffff:111.222.33.44. 的 IPv4 映射到 IPv6 的地址。
如果 IPv6 地址格式无效，则返回 NULL。
语法
IPv6StringToNumOrNull(string)
参数
返回值
以二进制格式返回 IPv6 地址；如果地址无效，则返回 NULL。Nullable(FixedString(16))
示例
包含无效地址的基本示例
SELECT
IPv6NumToString(IPv6StringToNumOrNull('2001:db8::1')) AS valid,
IPv6StringToNumOrNull('invalid') AS invalid;
┌─valid───────┬─invalid─┐
│ 2001:db8::1 │ ᴺᵁᴸᴸ │
└─────────────┴─────────┘
cutIPv6
引入版本：v1.1.0
接受一个包含 IPv6 地址二进制表示的 FixedString(16) 值。
返回一个字符串，内容为在文本格式下移除指定字节数后的该地址。
语法
cutIPv6(x, bytesToCutForIPv6, bytesToCutForIPv4)
参数
返回值
返回一个字符串，包含在移除指定字节后得到的文本格式 IPv6 地址。String
示例
使用示例
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)
┌─cutIPv6(ipv6, 2, 0)─────────────────┬─cutIPv6(ipv4, 0, 2)─┐
│ 2001:db8:ac10:fe01:feed:babe:cafe:0 │ ::ffff:192.168.0.0 │
└─────────────────────────────────────┴─────────────────────┘
isIPAddressInRange
引入版本：v21.4.0
判断某个 IP 地址是否落在以 无类别域间路由 (Classless Inter-Domain Routing，CIDR) 表示的网络范围内。
该函数接受以字符串形式表示的 IPv4 和 IPv6 地址及网络。如果 IP 地址和 CIDR 的 IP 版本不一致，则返回 0。
语法
isIPAddressInRange(address, prefix)
参数
address — IPv4 或 IPv6 地址。Stringprefix — 使用 CIDR 表示法的 IPv4 或 IPv6 网络前缀。String
返回值
如果地址的 IP 版本与 CIDR 匹配，则返回 1，否则返回 0。UInt8
示例
位于范围内的 IPv4 地址
SELECT isIPAddressInRange('127.0.0.1', '127.0.0.0/8')
IPv4 地址不在有效范围内
SELECT isIPAddressInRange('127.0.0.1', 'ffff::/16')
IPv6 地址不在有效范围内
SELECT isIPAddressInRange('::ffff:192.168.0.1', '::ffff:192.168.0.4/128')
isIPv4String
自 v21.1.0 起引入
判断输入字符串是否为 IPv4 地址。
IPv6 版本请参阅 isIPv6String。
语法
参数
返回值
如果 string 是 IPv4 地址，则返回 1，否则返回 0。UInt8
示例
用法示例
SELECT addr, isIPv4String(addr)
FROM(
SELECT ['0.0.0.0', '127.0.0.1', '::ffff:127.0.0.1'] AS addr
)
ARRAY JOIN addr;
┌─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。
语法
参数
返回值
如果 string 是 IPv6 地址，则返回 1，否则返回 0。UInt8
示例
使用示例
SELECT addr, isIPv6String(addr)
FROM(SELECT ['::', '1111::ffff', '::ffff:127.0.0.1', '127.0.0.1'] AS addr)
ARRAY JOIN addr;
┌─addr─────────────┬─isIPv6String(addr)─┐
│ :: │ 1 │
│ 1111::ffff │ 1 │
│ ::ffff:127.0.0.1 │ 1 │
│ 127.0.0.1 │ 0 │
└──────────────────┴────────────────────┘
toIPv4
在 v20.1.0 中引入
将字符串或 UInt32 形式的 IPv4 地址转换为 IPv4 类型。
它类似于 IPv4StringToNum 和 IPv4NumToString 函数，但同时支持字符串和无符号整数数据类型作为输入参数。
语法
参数
返回值
返回一个 IPv4 地址。IPv4
示例
使用示例
SELECT toIPv4('171.225.130.45');
┌─toIPv4('171.225.130.45')─┐
│ 171.225.130.45 │
└──────────────────────────┘
与 IPv4StringToNum 和 IPv4NumToString 函数比较。
WITH
'171.225.130.45' AS IPv4_string
SELECT
hex(IPv4StringToNum(IPv4_string)),
hex(toIPv4(IPv4_string))
┌─hex(IPv4StringToNum(IPv4_string))─┬─hex(toIPv4(IPv4_string))─┐
│ ABE1822D │ ABE1822D │
└───────────────────────────────────┴──────────────────────────┘
从整数进行转换
SELECT toIPv4(2130706433);
┌─toIPv4(2130706433)─┐
│ 127.0.0.1 │
└────────────────────┘
toIPv4OrDefault
引入版本：v22.3.0
将字符串或 UInt32 形式的 IPv4 地址转换为 IPv4 类型。
如果 IPv4 地址格式无效，则返回 0.0.0.0 (值为 0 的 IPv4 地址) ，或返回指定的 IPv4 默认值。
语法
toIPv4OrDefault(string[, default])
参数
string — 要转换的 IP 地址字符串。Stringdefault — 可选。当 string 不是有效 IPv4 地址时要返回的值。IPv4
返回值
返回由字符串转换得到的 IPv4 地址；如果转换失败，则返回默认值。IPv4
示例
有效和无效的 IPv4 字符串
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;
┌─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 地址。
- 超出取值范围的值。
- 格式错误的地址。
语法
参数
返回值
成功时返回 IPv4 地址，否则返回 NULL。IPv4 或 NULL
示例
使用示例
SELECT
toIPv4OrNull('192.168.1.1') AS valid_ip,
toIPv4OrNull('invalid.ip') AS invalid_ip
┌─valid_ip────┬─invalid_ip─┐
│ 192.168.1.1 │ ᴺᵁᴸᴸ │
└─────────────┴────────────┘
toIPv4OrZero
首次引入于：v23.1.0
将输入值转换为 IPv4 类型的值，但在出错时返回全零 IPv4 地址。
类似于 toIPv4，但在转换出错时返回全零 IPv4 地址 (0.0.0.0) ，而不是抛出异常。
支持的参数：
- 点分十进制表示法的 IPv4 地址字符串表示。
- IPv4 地址的整数表示形式。
不支持的参数 (返回全零 IPv4 地址) ：
- 无效的 IP 地址格式。
- IPv6 地址。
- 超出范围的值。
语法
参数
返回值
成功时返回一个 IPv4 地址，否则返回 IPv4 零地址 (0.0.0.0) 。IPv4
示例
用法示例
SELECT
toIPv4OrZero('192.168.1.1') AS valid_ip,
toIPv4OrZero('invalid.ip') AS invalid_ip
┌─valid_ip────┬─invalid_ip─┐
│ 192.168.1.1 │ 0.0.0.0 │
└─────────────┴────────────┘
toIPv6
引入版本：v20.1.0
将 IPv6 地址的字符串或 UInt128 形式转换为 IPv6 类型。
对于字符串，如果 IPv6 地址格式无效，则返回空值。
类似于 IPv6StringToNum 和 IPv6NumToString 函数，这些函数用于在 IPv6 地址与二进制格式 (即 FixedString(16)) 之间进行转换。
如果输入字符串包含一个有效的 IPv4 地址，则返回该 IPv4 地址对应的等价 IPv6 地址。
语法
参数
返回值
返回一个 IPv6 地址。IPv6
示例
使用示例
WITH '2001:438:ffff::407d:1bc1' AS IPv6_string
SELECT
hex(IPv6StringToNum(IPv6_string)),
hex(toIPv6(IPv6_string));
┌─hex(IPv6StringToNum(IPv6_string))─┬─hex(toIPv6(IPv6_string))─────────┐
│ 20010438FFFF000000000000407D1BC1 │ 20010438FFFF000000000000407D1BC1 │
└───────────────────────────────────┴──────────────────────────────────┘
IPv4 到 IPv6 的映射
SELECT toIPv6('127.0.0.1');
┌─toIPv6('127.0.0.1')─┐
│ ::ffff:127.0.0.1 │
└─────────────────────┘
toIPv6OrDefault
引入于：v22.3.0
将 IPv6 地址的字符串形式或 UInt128 形式转换为 IPv6 类型。
如果 IPv6 地址格式无效，则返回 :: (全零 IPv6 地址) 或指定的 IPv6 默认值。
语法
toIPv6OrDefault(string[, default])
参数
string — 要转换的 IP 地址字符串。default — 可选。若 string 格式无效时要返回的值。
返回值
返回 IPv6 地址；如果参数 string 格式无效，则返回 :: 或提供的可选默认值。IPv6
示例
有效和无效的 IPv6 字符串
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;
┌─valid──────────────────────────────────┬─default_value─┬─provided_default─┐
│ 2001:db8:85a3::8a2e:370:7334 │ :: │ ::1 │
└────────────────────────────────────────┴───────────────┴──────────────────┘
toIPv6OrNull
引入版本：v22.3.0
将输入值转换为 IPv6 类型的值，但在出错时返回 NULL。
类似于 toIPv6，但在转换出错时返回 NULL，而不是抛出异常。
支持的参数：
- 标准表示法的 IPv6 地址字符串。
- IPv4 地址的字符串表示 (会被转换为 IPv4-mapped IPv6) 。
- IPv6 地址的二进制表示。
不支持的参数 (返回 NULL) ：
- 无效的 IP 地址格式。
- 格式错误的 IPv6 地址。
- 超出范围的值。
- 无效的表示法。
语法
参数
x — IPv6 或 IPv4 地址的字符串形式。String
返回值
转换成功时返回 IPv6 地址，否则返回 NULL。IPv6 或 NULL
示例
使用示例
SELECT
toIPv6OrNull('2001:0db8:85a3:0000:0000:8a2e:0370:7334') AS valid_ipv6,
toIPv6OrNull('invalid::ip') AS invalid_ipv6
┌─valid_ipv6──────────────────────────┬─invalid_ipv6─┐
│ 2001:db8:85a3::8a2e:370:7334 │ ᴺᵁᴸᴸ │
└─────────────────────────────────────┴──────────────┘
toIPv6OrZero
引入于：v23.1.0
将输入值转换为 IPv6 类型的值，但在出错时返回全零 IPv6 地址。
类似于 toIPv6，但在转换出错时返回全零 IPv6 地址 (::) ，而不是抛出异常。
支持的参数：
- 使用标准记法表示的 IPv6 地址字符串。
- IPv4 地址的字符串表示 (会转换为 IPv4-mapped IPv6) 。
- IPv6 地址的二进制表示。
不支持的参数 (返回全零 IPv6 地址) ：
- 非法的 IP 地址格式。
- 格式错误的 IPv6 地址。
- 超出范围的数值。
语法
参数
x — IPv6 或 IPv4 地址的字符串形式。String
返回值
如果成功，返回一个 IPv6 地址，否则返回全零 IPv6 地址 (::)。IPv6
示例
用法示例
SELECT
toIPv6OrZero('2001:0db8:85a3:0000:0000:8a2e:0370:7334') AS valid_ipv6,
toIPv6OrZero('invalid::ip') AS invalid_ipv6
┌─valid_ipv6──────────────────────────┬─invalid_ipv6─┐
│ 2001:db8:85a3::8a2e:370:7334 │ :: │
└─────────────────────────────────────┴──────────────┘
