标准 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_bytesprefix_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.10x1FF 表示 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.10x1FF 表示 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.Google.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.Google.Co.UK    " 带有空格、大写字母但没有架构的非标准网址 "www.Google.Co.UK" "Co.UK" "Google.Co.UK"
"mailto:?to=&subject=&body=" URI 而非网址 - 不支持 "mailto" NULL NULL

NET.PUBLIC_SUFFIX

NET.PUBLIC_SUFFIX(url)

说明

获取一个 STRING 格式的网址,并返回 STRING 格式的公开后缀(例如 comorgnet)。公开后缀就是在 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.Google.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.Google.Co.UK    " 带有空格、大写字母但没有架构的非标准网址 "www.Google.Co.UK" "Co.UK" "Google.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.Google.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.Google.Co.UK    " 带有空格、大写字母但没有架构的非标准网址 "www.Google.Co.UK" "Co.UK" "Google.Co.UK"
"mailto:?to=&subject=&body=" URI 而非网址 - 不支持 "mailto" NULL NULL
此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面