Categorize docs

Author: jan-elastic

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

@@ -9,6 +9,7 @@ The <<esql-stats-by>> command supports these grouping functions:
 
 // tag::group_list[]
 * <<esql-bucket>>
+* <<esql-categorize>>
 // end::group_list[]
 
 include::layout/bucket.asciidoc[]

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

@@ -676,3 +676,20 @@ Ahmedabad     | 9                 | 72
 Bangalore     | 9                 | 72
 // end::bitLength-result[]
 ;
+
+docsCategorize
+required_capability: categorize_v4
+// tag::docsCategorize[]
+FROM sample_data
+| STATS count=COUNT() BY category=CATEGORIZE(message)
+// end::docsCategorize[]
+| SORT category
+;
+
+// tag::docsCategorize[]
+count:long | category:keyword
+         3 | .*?Connected.+?to.*?
+         3 | .*?Connection.+?error.*?
+         1 | .*?Disconnected.*?
+// end::docsCategorize[]
+;

docs/reference/esql/functions/grouping-functions.asciidoc

@@ -16,6 +16,7 @@
 import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
 import org.elasticsearch.xpack.esql.core.tree.Source;
 import org.elasticsearch.xpack.esql.core.type.DataType;
+import org.elasticsearch.xpack.esql.expression.function.Example;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
 import org.elasticsearch.xpack.esql.expression.function.Param;
 import org.elasticsearch.xpack.esql.io.stream.PlanStreamInput;
@@ -44,10 +45,21 @@ public class Categorize extends GroupingFunction implements Validatable {
 
     private final Expression field;
 
-    @FunctionInfo(returnType = "keyword", description = "Categorizes text messages.")
+    @FunctionInfo(
+        returnType = "keyword",
+        description = "Groups text messages into categories of similarly formatted text values.",
+        examples = {
+            @Example(
+                file = "docs",
+                tag = "docsCategorize",
+                description = "This example categorizes server logs messages into categories and aggregates their counts. "
+            ) },
+        preview = true
+    )
     public Categorize(
         Source source,
         @Param(name = "field", type = { "text", "keyword" }, description = "Expression to categorize") Expression field
+
     ) {
         super(source, List.of(field));
         this.field = field;