IPv4CIDRToRange
引入版本：v20.1
接收一个带有无类别域间路由（Classless Inter-Domain Routing，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 版本引入
将一个 32 位整数转换为其点分十进制表示形式的 IPv4 地址字符串（A.B.C.D 格式）。
采用大端字节序来解析输入值。
语法
别名：INET_NTOA
参数
num — 以 UInt32 数字表示的 IPv4 地址。UInt32
返回值
返回一个表示 IPv4 地址的字符串；如果格式无效则返回 0。String
示例
使用示例
IPv4NumToString(3232235521)
IPv4NumToStringClassC
自 v1.1 起提供
将一个 32 位整数转换为以点分十进制表示法（A.B.C.D 格式）的 IPv4 地址字符串，
类似于 IPv4NumToString，但使用 xxx 替代最后一个八位组。
语法
IPv4NumToStringClassC(num)
参数
num — 以 UInt32 无符号整数表示的 IPv4 地址。UInt32
返回值
返回将最后一个八位组替换为 xxx 的 IPv4 地址字符串。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
将点分十进制表示（A.B.C.D 格式）的 IPv4 地址字符串转换为对应的 32 位整数表示。（是 IPv4NumToString 的逆操作）。
如果 IPv4 地址格式无效，将抛出异常。
语法
别名：INET_ATON
参数
返回值
返回 IPv4 地址的数值表示。UInt32
示例
使用示例
IPv4StringToNum('192.168.0.1')
IPv4StringToNumOrDefault
引入于：v22.3
将点分十进制表示法（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
将 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;
┌──────有效─┬─无效────┐
│ 2130706433 │ ᴺᵁᴸᴸ │
└────────────┴─────────┘
IPv4ToIPv6
自 v1.1 引入
将（大端序）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 版本引入。
接受一个 IPv6 地址及其无类别域间路由（Classless Inter-Domain Routing，CIDR）前缀长度，并返回该子网的地址范围，形式为包含两个 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 引入
将 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 │
└──────────────┘
基于 IPv6 的 hits 分析
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
将 IPv6 地址从其标准文本表示形式转换为二进制格式（FixedString(16)）。
接受格式为 ::ffff:111.222.33.44. 的 IPv4 映射 IPv6 地址。
如果 IPv6 地址格式无效，则会抛出异常。
如果输入字符串包含有效的 IPv4 地址，则返回其对应的 IPv6 表示。
十六进制字符可以是大写或小写。
语法
别名: 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 引入
将 IPv6 地址从其标准文本表示转换为二进制格式（FixedString(16)）。
接受 IPv4 映射的 IPv6 地址，格式为 ::ffff:111.222.33.44.。
如果 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
将 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
接受一个以二进制格式存储 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
判断某个 IP 地址是否属于使用 无类别域间路由（CIDR） 表示法表示的网络。
此函数接受以字符串形式表示的 IPv4 和 IPv6 地址及网络。如果地址与 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 起提供
判断输入字符串是否为 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
用于判断输入字符串是否为 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
将 IPv4 地址的字符串形式或 UInt32 形式转换为 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 引入
将 IPv4 地址的字符串或 UInt32 形式转换为 IPv4 类型。
如果 IPv4 地址格式无效，则返回 0.0.0.0（IPv4 0），或返回提供的 IPv4 默认值。
语法
toIPv4OrDefault(string[, default])
参数
string — 要转换的 IPv4 地址字符串。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 引入
将输入值转换为 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
将输入值转换为 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
将字符串或 UInt128 形式的 IPv6 地址转换为 IPv6 类型。
对于字符串，如果 IPv6 地址格式无效，则返回空结果。
类似于 IPv6StringToNum 和 IPv6NumToString 函数，它们在 IPv6 地址与二进制格式（即 FixedString(16)）之间进行转换。
如果输入字符串中包含有效的 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
将 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
将输入值转换为 IPv6 类型的值，但在发生错误时返回 NULL。
与 toIPv6 类似，但在转换出错时返回 NULL，而不是抛出异常。
支持的参数：
- 标准表示法的 IPv6 地址字符串。
- IPv4 地址的字符串表示（转换为 IPv4 映射的 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
将输入值转换为 IPv6 类型的值，但在出错时返回全零 IPv6 地址。
类似于 toIPv6，但在转换出错时返回全零 IPv6 地址（::），而不是抛出异常。
支持的参数：
- 标准表示法的 IPv6 地址字符串。
- IPv4 地址的字符串表示（会转换为 IPv4 映射的 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 │ :: │
└─────────────────────────────────────┴──────────────┘
