标准 SQL 中的网络函数

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