ESQL: Add ip_prefix function (#109070)

Added ESQL function to get the prefix of an IP. It works now with both
IPv4 and IPv6. For users planning to use it with mixed IPs, we may need
to add a function like "is_ipv4()" first.

**About the skipped test:** There's currently a "bug" in the
evaluators//functions that return null. Evaluators can't handle them.
We'll work on support for that in another PR. It affects other
functions, like `substring()`. In this function, however, it only
affects in "wrong" cases (Like an invalid prefix), so it has no impact.

Fixes #99064

Author: ivancea

.gitattributes

@@ -8,3 +8,8 @@ x-pack/plugin/esql/src/main/antlr/*.tokens linguist-generated=true
 x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/parser/*.interp linguist-generated=true
 x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/parser/EsqlBaseLexer*.java linguist-generated=true
 x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/parser/EsqlBaseParser*.java linguist-generated=true
+x-pack/plugin/esql/src/main/generated/** linguist-generated=true
+
+# ESQL functions docs are autogenerated. More information at `docs/reference/esql/functions/README.md`
+docs/reference/esql/functions/*/** linguist-generated=true
+

docs/changelog/109070.yaml

@@ -0,0 +1,6 @@
+pr: 109070
+summary: "ESQL: Add `ip_prefix` function"
+area: ES|QL
+type: feature
+issues:
+ - 99064

docs/reference/esql/functions/description/ip_prefix.asciidoc

@@ -101,7 +101,7 @@ public static Tuple<Version, Version> skipVersionRange(String testName) {
         Map<String, String> pairs = extractInstructions(testName);
         String versionRange = pairs.get("skip");
         if (versionRange != null) {
-            String[] skipVersions = versionRange.split("-");
+            String[] skipVersions = versionRange.split("-", Integer.MAX_VALUE);
             if (skipVersions.length != 2) {
                 throw new IllegalArgumentException("malformed version range : " + versionRange);
             }

docs/reference/esql/functions/examples/ip_prefix.asciidoc

@@ -485,3 +485,108 @@ beta         | 127.0.0.1
 beta         | 127.0.0.1
 beta         | 127.0.0.1
 ;
+
+ipPrefix
+required_capability: fn_ip_prefix
+//tag::ipPrefix[]
+row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9")
+| eval ip4_prefix = ip_prefix(ip4, 24, 0), ip6_prefix = ip_prefix(ip6, 0, 112);
+//end::ipPrefix[]
+
+//tag::ipPrefix-result[]
+ip4:ip  | ip6:ip                    | ip4_prefix:ip | ip6_prefix:ip
+1.2.3.4 | fe80::cae2:65ff:fece:feb9 | 1.2.3.0       | fe80::cae2:65ff:fece:0000
+//end::ipPrefix-result[]
+;
+
+ipPrefixCompleteIp
+required_capability: fn_ip_prefix
+row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9")
+| eval ip4_prefix = ip_prefix(ip4, 32, 0), ip6_prefix = ip_prefix(ip6, 0, 128);
+
+ip4:ip  | ip6:ip                    | ip4_prefix:ip | ip6_prefix:ip
+1.2.3.4 | fe80::cae2:65ff:fece:feb9 | 1.2.3.4       | fe80::cae2:65ff:fece:feb9 
+;
+
+ipPrefixZeroBits
+required_capability: fn_ip_prefix
+row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9")
+| eval ip4_prefix = ip_prefix(ip4, 0, 128), ip6_prefix = ip_prefix(ip6, 32, 0);
+
+ip4:ip  | ip6:ip                    | ip4_prefix:ip | ip6_prefix:ip
+1.2.3.4 | fe80::cae2:65ff:fece:feb9 | 0.0.0.0       | ::0
+;
+
+ipPrefixWithBits
+required_capability: fn_ip_prefix
+row ip4 = to_ip("1.2.3.255"), ip6 = to_ip("fe80::cae2:65ff:fece:feff")
+| eval ip4_prefix = ip_prefix(ip4, 25, 0), ip6_prefix = ip_prefix(ip6, 0, 121);
+
+ip4:ip    | ip6:ip                    | ip4_prefix:ip | ip6_prefix:ip
+1.2.3.255 | fe80::cae2:65ff:fece:feff | 1.2.3.128     | fe80::cae2:65ff:fece:fe80
+;
+
+ipPrefixLengthFromColumn
+required_capability: fn_ip_prefix
+from hosts
+| where host == "alpha"
+| sort card
+| eval prefix = ip_prefix(ip0, 24, 128)
+| keep card, ip0, prefix;
+
+card:keyword | ip0:ip    | prefix:ip
+eth0         | 127.0.0.1 | 127.0.0.0
+eth1         | ::1       | ::0
+;
+
+ipPrefixLengthFromExpression
+required_capability: fn_ip_prefix
+row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9"), bits_per_byte = 8
+| eval ip4_length = 3 * bits_per_byte, ip4_prefix = ip_prefix(ip4, ip4_length, 0), ip6_prefix = ip_prefix(ip6, 0, 12 * 10);
+
+ip4:ip  | ip6:ip                    | bits_per_byte:integer | ip4_length:integer | ip4_prefix:ip | ip6_prefix:ip
+1.2.3.4 | fe80::cae2:65ff:fece:feb9 | 8                     | 24                 | 1.2.3.0       | fe80::cae2:65ff:fece:fe00
+;
+
+ipPrefixAsGroup
+required_capability: fn_ip_prefix
+from hosts
+| stats count(*) by ip_prefix(ip1, 24, 120)
+| sort `ip_prefix(ip1, 24, 120)`;
+warning:Line 2:21: evaluation of [ip_prefix(ip1, 24, 120)] failed, treating result as null. Only first 20 failures recorded.
+warning:Line 2:21: java.lang.IllegalArgumentException: single-value function encountered multi-value
+
+count(*):long | ip_prefix(ip1, 24, 120):ip
+2             | ::0
+3             | 127.0.0.0
+1             | 128.0.0.0
+1             | fe80::cae2:65ff:fece:fe00
+1             | fe81::cae2:65ff:fece:fe00
+2             | null
+;
+
+ipPrefixWithWrongLengths
+required_capability: fn_ip_prefix
+row ip4 = to_ip("1.2.3.4")
+| eval a = ip_prefix(ip4, -1, 128), b = ip_prefix(ip4, 32, -1), c = ip_prefix(ip4, 33, 0), d = ip_prefix(ip4, 32, 129);
+warning:Line 2:12: evaluation of [ip_prefix(ip4, -1, 128)] failed, treating result as null. Only first 20 failures recorded.
+warning:Line 2:12: java.lang.IllegalArgumentException: Prefix length v4 must be in range [0, 32], found -1
+warning:Line 2:41: evaluation of [ip_prefix(ip4, 32, -1)] failed, treating result as null. Only first 20 failures recorded.
+warning:Line 2:41: java.lang.IllegalArgumentException: Prefix length v6 must be in range [0, 128], found -1
+warning:Line 2:69: evaluation of [ip_prefix(ip4, 33, 0)] failed, treating result as null. Only first 20 failures recorded.
+warning:Line 2:69: java.lang.IllegalArgumentException: Prefix length v4 must be in range [0, 32], found 33
+warning:Line 2:96: evaluation of [ip_prefix(ip4, 32, 129)] failed, treating result as null. Only first 20 failures recorded.
+warning:Line 2:96: java.lang.IllegalArgumentException: Prefix length v6 must be in range [0, 128], found 129
+
+ip4:ip  | a:ip | b:ip | c:ip | d:ip
+1.2.3.4 | null | null | null | null
+;
+
+ipPrefixWithNullArguments
+required_capability: fn_ip_prefix
+row ip4 = to_ip("1.2.3.4")
+| eval a = ip_prefix(null, 32, 128), b = ip_prefix(ip4, null, 128), c = ip_prefix(ip4, 32, null);
+
+ip4:ip  | a:ip | b:ip | c:ip
+1.2.3.4 | null | null | null
+;

docs/reference/esql/functions/kibana/definition/ip_prefix.json

@@ -30,6 +30,7 @@ double e()
 "double|integer|long|unsigned_long floor(number:double|integer|long|unsigned_long)"
 "keyword from_base64(string:keyword|text)"
 "boolean|double|integer|ip|keyword|long|text|version greatest(first:boolean|double|integer|ip|keyword|long|text|version, ?rest...:boolean|double|integer|ip|keyword|long|text|version)"
+"ip ip_prefix(ip:ip, prefixLengthV4:integer, prefixLengthV6:integer)"
 "boolean|double|integer|ip|keyword|long|text|version least(first:boolean|double|integer|ip|keyword|long|text|version, ?rest...:boolean|double|integer|ip|keyword|long|text|version)"
 "keyword left(string:keyword|text, length:integer)"
 "integer length(string:keyword|text)"
@@ -144,6 +145,7 @@ ends_with     |[str, suffix]                       |["keyword|text", "keyword|te
 floor         |number                              |"double|integer|long|unsigned_long"                                                                                               |Numeric expression. If `null`, the function returns `null`.
 from_base64   |string                              |"keyword|text"                                                                                                                    |A base64 string.
 greatest      |first                               |"boolean|double|integer|ip|keyword|long|text|version"                                                                             |First of the columns to evaluate.
+ip_prefix     |[ip, prefixLengthV4, prefixLengthV6]|[ip, integer, integer]                                                                                                            |[IP address of type `ip` (both IPv4 and IPv6 are supported)., Prefix length for IPv4 addresses., Prefix length for IPv6 addresses.]
 least         |first                               |"boolean|double|integer|ip|keyword|long|text|version"                                                                             |First of the columns to evaluate.
 left          |[string, length]                    |["keyword|text", integer]                                                                                                         |[The string from which to return a substring., The number of characters to return.]
 length        |string                              |"keyword|text"                                                                                                                    |String expression. If `null`, the function returns `null`.
@@ -259,6 +261,7 @@ ends_with     |Returns a boolean that indicates whether a keyword string ends wi
 floor         |Round a number down to the nearest integer.
 from_base64   |Decode a base64 string.
 greatest      |Returns the maximum value from multiple columns. This is similar to <<esql-mv_max>> except it is intended to run on multiple columns at once.
+ip_prefix     |Truncates an IP to a given prefix length.
 least         |Returns the minimum value from multiple columns. This is similar to <<esql-mv_min>> except it is intended to run on multiple columns at once.
 left          |Returns the substring that extracts 'length' chars from 'string' starting from the left.
 length        |Returns the character length of a string.
@@ -375,6 +378,7 @@ ends_with     |boolean
 floor         |"double|integer|long|unsigned_long"                                                                                         |false                       |false           |false
 from_base64   |keyword                                                                                                                     |false                       |false           |false
 greatest      |"boolean|double|integer|ip|keyword|long|text|version"                                                                       |false                       |true            |false
+ip_prefix     |ip                                                                                                                          |[false, false, false]       |false           |false
 least         |"boolean|double|integer|ip|keyword|long|text|version"                                                                       |false                       |true            |false
 left          |keyword                                                                                                                     |[false, false]              |false           |false
 length        |integer                                                                                                                     |false                       |false           |false
@@ -471,5 +475,5 @@ countFunctions#[skip:-8.14.99, reason:BIN added]
 meta functions |  stats  a = count(*), b = count(*), c = count(*) |  mv_expand c;
 
 a:long | b:long | c:long
-106    | 106    | 106
+107    | 107    | 107
 ;