NET.IP_FROM_STRING
NET.IP_FROM_STRING(addr_str)
说明
将 IPv4 或 IPv6 地址从文本 (STRING) 格式转换为网络字节顺序的二进制 (BYTES) 格式。
此函数支持以下 addr_str
格式:
- IPv4:点分四组格式。例如
10.1.2.3
。 - IPv6:冒号分隔格式。例如,
1234:5678:90ab:cdef:1234:5678:90ab:cdef
。如需查看更多示例,请参阅 IP 版本 6 寻址架构。
此函数不支持 CIDR 表示法,例如 10.1.2.3/32
。
如果此函数收到一个 NULL
输入,则会返回 NULL
。如果输入视为无效,则发生 OUT_OF_RANGE
错误。
返回数据类型
BYTES
示例
SELECT
addr_str, FORMAT("%T", NET.IP_FROM_STRING(addr_str)) AS ip_from_string
FROM UNNEST([
'48.49.50.51',
'::1',
'3031:3233:3435:3637:3839:4041:4243:4445',
'::ffff:192.0.2.128'
]) AS addr_str;
addr_str | ip_from_string |
---|---|
48.49.50.51 | b"0123" |
::1 | b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01" |
3031:3233:3435:3637:3839:4041:4243:4445 | b"0123456789@ABCDE" |
::ffff:192.0.2.128 | b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80" |
NET.SAFE_IP_FROM_STRING
NET.SAFE_IP_FROM_STRING(addr_str)
说明
类似于 NET.IP_FROM_STRING
,但在输入无效的情况下会返回 NULL
,而不是抛出错误。
返回数据类型
BYTES
示例
SELECT
addr_str,
FORMAT("%T", NET.SAFE_IP_FROM_STRING(addr_str)) AS safe_ip_from_string
FROM UNNEST([
'48.49.50.51',
'::1',
'3031:3233:3435:3637:3839:4041:4243:4445',
'::ffff:192.0.2.128',
'48.49.50.51/32',
'48.49.50',
'::wxyz'
]) AS addr_str;
addr_str | safe_ip_from_string |
---|---|
48.49.50.51 | b"0123" |
::1 | b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01" |
3031:3233:3435:3637:3839:4041:4243:4445 | b"0123456789@ABCDE" |
::ffff:192.0.2.128 | b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80" |
48.49.50.51/32 | NULL |
48.49.50 | NULL |
::wxyz | NULL |
NET.IP_TO_STRING
NET.IP_TO_STRING(addr_bin)
说明 将 IPv4 或 IPv6 地址从文本 (STRING) 格式转换为网络字节顺序的二进制 (BYTES) 格式。
如果输入为 4 个字节,则此函数返回 STRING 形式的 IPv4 地址。如果输入为 16 个字节,则返回 STRING 形式的 IPv6 地址。
如果此函数收到一个 NULL
输入,则会返回 NULL
。如果输入的长度并非 4 或 16,则发生 OUT_OF_RANGE
错误。
返回数据类型
STRING
示例
SELECT FORMAT("%T", x) AS addr_bin, NET.IP_TO_STRING(x) AS ip_to_string
FROM UNNEST([
b"0123",
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01",
b"0123456789@ABCDE",
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80"
]) AS x;
addr_bin | ip_to_string |
---|---|
b"0123" | 48.49.50.51 |
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01" | ::1 |
b"0123456789@ABCDE" | 3031:3233:3435:3637:3839:4041:4243:4445 |
b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff\xc0\x00\x02\x80" | ::ffff:192.0.2.128 |
NET.IP_NET_MASK
NET.IP_NET_MASK(num_output_bytes, prefix_length)
说明
返回一个网路掩码:长度等于 num_output_bytes
的一个字节序列,其中第一个 prefix_length
位设置为 1,其他位设置为 0。num_output_bytes
和 prefix_length
为 INT64 类型。如果 num_output_bytes
不是 4(对于 IPv4)或 16(对于 IPv6),则此函数会引发错误。如果 prefix_length
为负或者大于 8 * num_output_bytes
,此函数也会引发错误。
返回数据类型
BYTES
示例
SELECT x, y, FORMAT("%T", NET.IP_NET_MASK(x, y)) AS ip_net_mask
FROM UNNEST([
STRUCT(4 as x, 0 as y),
(4, 20),
(4, 32),
(16, 0),
(16, 1),
(16, 128)
]);
x | y | ip_net_mask |
---|---|---|
4 | 0 | b"\x00\x00\x00\x00" |
4 | 20 | b"\xff\xff\xf0\x00" |
4 | 32 | b"\xff\xff\xff\xff" |
16 | 0 | b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00" |
16 | 1 | b"\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00" |
16 | 128 | b"\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff" |
NET.IP_TRUNC
NET.IP_TRUNC(addr_bin, prefix_length)
说明
获取 addr_bin
(以网络字节顺序排列的二进制 (BYTES) 格式的 IPv4 或 IPv6 地址),并返回相同格式的子网地址。结果具有与 addr_bin
相同的长度,其中第一个 prefix_length
位等于 addr_bin
中的位,其余位是 0。
如果 LENGTH(addr_bin)
不是 4 或 16,或者 prefix_len
为负或者大于 LENGTH(addr_bin) * 8
,此函数会引发错误。
返回数据类型
BYTES
示例
SELECT
FORMAT("%T", x) as addr_bin, prefix_length,
FORMAT("%T", NET.IP_TRUNC(x, prefix_length)) AS ip_trunc
FROM UNNEST([
STRUCT(b"\xAA\xBB\xCC\xDD" as x, 0 as prefix_length),
(b"\xAA\xBB\xCC\xDD", 11), (b"\xAA\xBB\xCC\xDD", 12),
(b"\xAA\xBB\xCC\xDD", 24), (b"\xAA\xBB\xCC\xDD", 32),
(b'0123456789@ABCDE', 80)
]);
addr_bin | prefix_length | ip_trunc |
---|---|---|
b"\xaa\xbb\xcc\xdd" | 0 | b"\x00\x00\x00\x00" |
b"\xaa\xbb\xcc\xdd" | 11 | b"\xaa\xa0\x00\x00" |
b"\xaa\xbb\xcc\xdd" | 12 | b"\xaa\xb0\x00\x00" |
b"\xaa\xbb\xcc\xdd" | 24 | b"\xaa\xbb\xcc\x00" |
b"\xaa\xbb\xcc\xdd" | 32 | b"\xaa\xbb\xcc\xdd" |
b"0123456789@ABCDE" | 80 | b"0123456789\x00\x00\x00\x00\x00\x00" |
NET.IPV4_FROM_INT64
NET.IPV4_FROM_INT64(integer_value)
说明
将 IPv4 地址从整数格式转换为网络字节顺序的二进制 (BYTES) 格式。在整数输入中,无论主机或客户端采用何种架构,IP 地址的最低有效位都存储为整数最低有效位。例如,1
表示 0.0.0.1
,0x1FF
表示 0.0.1.255
。
此函数会检查是否所有最高有效 32 位均为 0,或者是否所有最高有效 33 位均为 1(从 32 位整数进行有符号扩展)。换句话说,输入应该在 [-0x80000000, 0xFFFFFFFF]
范围内;否则,此函数会引发错误。
此函数不支持 IPv6。
返回数据类型
BYTES
示例
SELECT x, x_hex, FORMAT("%T", NET.IPV4_FROM_INT64(x)) AS ipv4_from_int64
FROM (
SELECT CAST(x_hex AS INT64) x, x_hex
FROM UNNEST(["0x0", "0xABCDEF", "0xFFFFFFFF", "-0x1", "-0x2"]) AS x_hex
);
x | x_hex | ipv4_from_int64 |
---|---|---|
0 | 0x0 | b"\x00\x00\x00\x00" |
11259375 | 0xABCDEF | b"\x00\xab\xcd\xef" |
4294967295 | 0xFFFFFFFF | b"\xff\xff\xff\xff" |
-1 | -0x1 | b"\xff\xff\xff\xff" |
-2 | -0x2 | b"\xff\xff\xff\xfe" |
NET.IPV4_TO_INT64
NET.IPV4_TO_INT64(addr_bin)
说明
将 IPv4 地址从网络字节顺序的二进制 (BYTES) 格式转换为整数格式。在整数输出中,无论主机或客户端采用何种架构,IP 地址的最低有效位都存储为整数最低有效位。例如,1
表示 0.0.0.1
,0x1FF
表示 0.0.1.255
。输出范围为 [0, 0xFFFFFFFF]
。
如果输入长度不是 4,则此函数会引发错误。
此函数不支持 IPv6。
返回数据类型
INT64
示例
SELECT
FORMAT("%T", x) AS addr_bin,
FORMAT("0x%X", NET.IPV4_TO_INT64(x)) AS ipv4_to_int64
FROM
UNNEST([b"\x00\x00\x00\x00", b"\x00\xab\xcd\xef", b"\xff\xff\xff\xff"]) AS x;
addr_bin | ipv4_to_int64 |
---|---|
b"\x00\x00\x00\x00" | 0x0 |
b"\x00\xab\xcd\xef" | 0xABCDEF |
b"\xff\xff\xff\xff" | 0xFFFFFFFF |
NET.HOST
NET.HOST(url)
说明
获取一个 STRING 格式的网址,并返回 STRING 格式的主机。为获得最佳结果,网址值应符合 RFC 3986 定义的格式。如果网址值不符合 RFC 3986 格式,此函数会尽最大努力解析输入并返回相关结果。如果函数无法解析输入,则返回 NULL。
注意:此函数不执行任何标准化。
返回数据类型
STRING
示例
SELECT
FORMAT("%T", input) AS input,
description,
FORMAT("%T", NET.HOST(input)) AS host,
FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
SELECT "" AS input, "invalid input" AS description
UNION ALL SELECT "http://abc.xyz", "standard URL"
UNION ALL SELECT "//user:password@a.b:80/path?query",
"standard URL with relative scheme, port, path and query, but no public suffix"
UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
UNION ALL SELECT " www.Example.Co.UK ",
"non-standard URL with spaces, upper case letters, and without scheme"
UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
输入 | 说明 | 主机 | 后缀 | 域名 |
---|---|---|---|---|
"" | 输入无效 | NULL | NULL | NULL |
"http://abc.xyz" | 标准网址 | "abc.xyz" | "xyz" | "abc.xyz" |
"//user:password@a.b:80/path?query" | 具有相对架构、端口、路径和查询的标准网址,但没有公开后缀 | "a.b" | NULL | NULL |
"https://[::1]:80" | 采用 IPv6 主机的标准网址 | "[::1]" | NULL | NULL |
"http://例子.卷筒纸.中国" | 采用国际化域名的标准网址 | "例子.卷筒纸.中国" | "中国" | "卷筒纸.中国" |
" www.Example.Co.UK " | 带有空格、大写字母但没有架构的非标准网址 | "www.Example.Co.UK" | "Co.UK" | "Example.Co.UK" |
"mailto:?to=&subject=&body=" | URI 而非网址 - 不支持 | "mailto" | NULL | NULL |
NET.PUBLIC_SUFFIX
NET.PUBLIC_SUFFIX(url)
说明
获取一个 STRING 格式的网址,并返回 STRING 格式的公共后缀(例如 com
、org
或 net
)。公共后缀就是在 publicsuffix.org 注册的一个 ICANN 域名。为获得最佳结果,网址值应符合 RFC 3986 定义的格式。如果网址值不符合 RFC 3986 格式,此函数会尽最大努力解析输入并返回相关结果。
如果下述任一条件为 true,则此函数返回 NULL:
- 它无法通过输入解析主机;
- 解析得出的主机中间包含相邻点(而非前导或尾随位置);
- 解析得到的主机不包含任何公开后缀。
在查找公开后缀之前,此函数会临时标准化主机,方法是将大写英文字母转换为小写字母,并使用 Punycode 编码所有非 ASCII 字符。随后,此函数将公开后缀作为原始主机(而非标准化主机)的一部分返回。
注意:此函数不执行 Unicode 标准化。
注意:publicsuffix.org 的公共后缀数据还包含不公开域名。此函数会忽略不公开域名。
注意:公开后缀数据可能会随着时间的推移而变化。因此,现在生成 NULL 结果的输入可能会在将来生成非 NULL 值。
返回数据类型
STRING
示例
SELECT
FORMAT("%T", input) AS input,
description,
FORMAT("%T", NET.HOST(input)) AS host,
FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
SELECT "" AS input, "invalid input" AS description
UNION ALL SELECT "http://abc.xyz", "standard URL"
UNION ALL SELECT "//user:password@a.b:80/path?query",
"standard URL with relative scheme, port, path and query, but no public suffix"
UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
UNION ALL SELECT " www.Example.Co.UK ",
"non-standard URL with spaces, upper case letters, and without scheme"
UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
输入 | 说明 | 主机 | 后缀 | 域名 |
---|---|---|---|---|
"" | 输入无效 | NULL | NULL | NULL |
"http://abc.xyz" | 标准网址 | "abc.xyz" | "xyz" | "abc.xyz" |
"//user:password@a.b:80/path?query" | 具有相对架构、端口、路径和查询的标准网址,但没有公开后缀 | "a.b" | NULL | NULL |
"https://[::1]:80" | 采用 IPv6 主机的标准网址 | "[::1]" | NULL | NULL |
"http://例子.卷筒纸.中国" | 采用国际化域名的标准网址 | "例子.卷筒纸.中国" | "中国" | "卷筒纸.中国" |
" www.Example.Co.UK " | 带有空格、大写字母但没有架构的非标准网址 | "www.Example.Co.UK" | "Co.UK" | "Example.Co.UK |
"mailto:?to=&subject=&body=" | URI 而非网址 - 不支持 | "mailto" | NULL | NULL |
NET.REG_DOMAIN
NET.REG_DOMAIN(url)
说明
获取一个 STRING 格式的网址,并返回 STRING 格式的已注册或可注册域名(公共后缀加一个前置标签)。为获得最佳结果,网址值应符合 RFC 3986 定义的格式。如果网址值不符合 RFC 3986 格式,此函数会尽最大努力解析输入并返回相关结果。
如果下述任一条件为 true,则此函数返回 NULL:
- 它无法通过输入解析主机;
- 解析得出的主机中间包含相邻点(而非前导或尾随位置);
- 解析得到的主机不包含任何公开后缀;
- 解析得出的主机只包含公开后缀,而无任何前置标签。
在查找公开后缀之前,此函数会临时标准化主机,方法是将大写英文字母转换为小写字母,并使用 Punycode 编码所有非 ASCII 字符。随后,此函数将已注册或可注册域名作为原始主机(而非标准化主机)的一部分返回。
注意:此函数不执行 Unicode 标准化。
注意:publicsuffix.org 的公共后缀数据还包含不公开域名。此函数不会将不公开域名视为公开后缀。例如,如果“us.com”是公开后缀数据中的一个不公开域名,NET.REG_DOMAIN("foo.us.com") 会返回“us.com”(公开后缀“com”加上前置标签“us”)而非“foo.us.com”(不公开域名“us.com”加上前置标签“foo”)。
注意:公开后缀数据可能会随着时间的推移而变化。因此,现在生成 NULL 结果的输入可能会在将来生成非 NULL 值。
返回数据类型
STRING
示例
SELECT
FORMAT("%T", input) AS input,
description,
FORMAT("%T", NET.HOST(input)) AS host,
FORMAT("%T", NET.PUBLIC_SUFFIX(input)) AS suffix,
FORMAT("%T", NET.REG_DOMAIN(input)) AS domain
FROM (
SELECT "" AS input, "invalid input" AS description
UNION ALL SELECT "http://abc.xyz", "standard URL"
UNION ALL SELECT "//user:password@a.b:80/path?query",
"standard URL with relative scheme, port, path and query, but no public suffix"
UNION ALL SELECT "https://[::1]:80", "standard URL with IPv6 host"
UNION ALL SELECT "http://例子.卷筒纸.中国", "standard URL with internationalized domain name"
UNION ALL SELECT " www.Example.Co.UK ",
"non-standard URL with spaces, upper case letters, and without scheme"
UNION ALL SELECT "mailto:?to=&subject=&body=", "URI rather than URL--unsupported"
);
输入 | 说明 | 主机 | 后缀 | 域名 |
---|---|---|---|---|
"" | 输入无效 | NULL | NULL | NULL |
"http://abc.xyz" | 标准网址 | "abc.xyz" | "xyz" | "abc.xyz" |
"//user:password@a.b:80/path?query" | 具有相对架构、端口、路径和查询的标准网址,但没有公开后缀 | "a.b" | NULL | NULL |
"https://[::1]:80" | 采用 IPv6 主机的标准网址 | "[::1]" | NULL | NULL |
"http://例子.卷筒纸.中国" | 采用国际化域名的标准网址 | "例子.卷筒纸.中国" | "中国" | "卷筒纸.中国" |
" www.Example.Co.UK " | 带有空格、大写字母但没有架构的非标准网址 | "www.Example.Co.UK" | "Co.UK" | "Example.Co.UK" |
"mailto:?to=&subject=&body=" | URI 而非网址 - 不支持 | "mailto" | NULL | NULL |