企业官网建设流程全解析

StarRocks inet_aton 函数详解：IPv4 字符串转 BIGINT 大端数值

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks

inet_aton是 StarRocks 提供的字符串类函数，用于将A.B.C.D格式的 IPv4 地址字符串转换为对应的大端序（big endian）BIGINT 数值，是日志分析、网络审计、IP 归属地关联等场景中把 IP 文本转为可排序、可比较数值的常用工具。本文以 inet_aton.md 为骨架，结合 be/src/exprs/inet_aton.cpp、be/src/common/format_ip.h 等源码实现，完整讲解其语法、返回语义、边界行为与底层解析原理，并给出可直接运行的 SQL 示例。

函数概述

inet_aton（INET Address to Number）接收一个包含 IPv4 地址的字符串，格式为A.B.C.D，返回该地址对应的大端序整数（类型为BIGINT）。

大端序的含义是：四个字节段从高位到低位排列，即数值等于A * 2^24 + B * 2^16 + C * 2^8 + D。因此：

• 0.0.0.0对应最小值0；
• 255.255.255.255对应最大值4294967295（即2^32 - 1）。

这一语义与 MySQL 的INET_ATON()保持一致，便于用户在熟悉 SQL 方言的基础上平滑迁移。

语法说明

BIGINT inet_aton(VARCHAR ipv4)

参数说明：

从函数元数据注册信息（gensrc/script/functions.py）可以看到，该函数在 StarRocks 中以向量化形式注册，入参为VARCHAR，返回BIGINT，底层实现绑定到StringFunctions::inet_aton：

[30132, 'inet_aton', True, False, 'BIGINT', ['VARCHAR'], 'StringFunctions::inet_aton'],

使用示例

以下示例均可在 StarRocks 客户端（如mysql命令行）中直接执行。

单个地址转换

mysql> select inet_aton('192.168.1.1'); +--------------------------------------+ | inet_aton('192.168.1.1') | +--------------------------------------+ | 3232235777 | +--------------------------------------+

验证一下换算关系：192 * 2^24 + 168 * 2^16 + 1 * 2^8 + 1 = 3221225472 + 11010048 + 256 + 1 = 3232235777，与结果完全一致。

批量转换与非法值处理

mysql> select stringIp, inet_aton(stringIp) from ipv4; +-----------------+----------------------------+ | stringIp | inet_aton(stringIp) | +-----------------+----------------------------+ | 0.0.0.0 | 0 | | 255.255.255.255 | 4294967295 | | invalid | NULL | +-----------------+----------------------------+

可以看到，合法的地址被正确转为数值，而无法解析的字符串invalid返回 NULL，不会中断查询。

边界行为与解析规则

通过阅读底层解析函数 be/src/common/format_ip.h 中的parse_ipv4，可以确认以下严格校验规则，这些规则决定了哪些输入合法、哪些返回 NULL：

• 字符串长度必须在 7 ~ 15 个字符之间：最短的合法地址是0.0.0.0（7 字符），最长的是255.255.255.255（15 字符），长度越界直接判定非法；
• 每个字节段必须是纯数字（0-9），且位数不超过 3 位：非数字字符（如abc.def.ghi.jkl）无法通过is_numeric_ascii检查；
• 每个字节段的值不能超过 255：999.999.999.999这类输入会被拒绝；
• 段与段之间必须由点.分隔：在解析前三个字节段后，如果后续字符不是.，则判定非法；
• 必须是完整的四段地址：如192.168.1（仅三段）、192.168.1.1.1（五段）均不合法；
• 第一段之前不允许出现前导点或其他字符：解析器从字符串起始位置开始逐字符消费，任何残留字符都会导致失败。

对应地，在 be/src/exprs/inet_aton.cpp 的向量化实现中，输入为 NULL 的行直接追加 NULL；对非 NULL 行调用try_parse_ipv4，解析成功则追加转换后的数值，失败则追加 NULL：

StatusOr<ColumnPtr> StringFunctions::inet_aton(FunctionContext* context, const Columns& columns) { RETURN_IF_COLUMNS_ONLY_NULL(columns); auto str_viewer = ColumnViewer<TYPE_VARCHAR>(columns[0]); auto size = columns[0]->size(); ColumnBuilder<TYPE_BIGINT> result(size); for (int row = 0; row < size; row++) { if (str_viewer.is_null(row)) { result.append_null(); continue; } auto str_value = str_viewer.value(row); int64_t parsed_result; if (try_parse_ipv4(str_value.get_data(), str_value.get_size(), parsed_result)) { result.append(parsed_result); } else { result.append_null(); } } return result.build(ColumnHelper::is_all_const(columns)); }

从实现细节可以看出两点设计：

1. 逐行解析 + 向量化执行：函数按列处理（ColumnViewer/ColumnBuilder），并支持常量列折叠优化（ColumnHelper::is_all_const），在海量日志行上执行时仍能保持向量化引擎的高吞吐；
2. 位运算组装数值：parse_ipv4内部使用result |= value << offset按 8 位一组移位组装，即把四个字节段直接拼接成 32 位整数，天然符合大端序语义，无需浮点或除法运算。

源码测试验证

StarRocks 在 be/test/exprs/string_fn_test.cpp 中为该函数提供了两组并行测试用例，与本文所述规则一一对应：

• inetAtonValidIPv4Test：验证合法输入。192.168.1.1→3232235777，0.0.0.0→0，255.255.255.255→4294967295；
• inetAtonInvalidIPv4Test：验证非法输入全部返回 NULL，覆盖了999.999.999.999（段值越界）、abc.def.ghi.jkl（非数字）、192.168.1.1.1（五段）、192.168.1（三段）、空字符串""五类典型错误输入。

这两组用例直接印证了文档中“非法输入返回 NULL”的行为描述，也是做数据质量校验时的权威参考。

实践建议与应用场景

• IP 排序与范围比较：将 IPv4 转为整数后，A.B.C.D字典序与数值序不再一致（例如10.0.0.1字典序小于9.0.0.1），而数值化后可以直接用<、>、BETWEEN做正确的 IP 范围过滤，适合访问日志的网段统计；
• 配合inet_ntoa双向转换：数值化存储比字符串占用更小、索引更高效，需要展示时再转回字符串，降低存储成本；
• 注意 NULL 语义：由于非法 IP 返回 NULL，在WHERE inet_aton(ip) > x等过滤条件下，非法行会被自然排除，无需额外清洗；若需保留行，可用COALESCE或IFNULL提供默认值。

keyword

INET_ATON

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks