0
# Aggregation Builder
1

2
Factory methods and builder pattern for creating matrix stats aggregations with field configuration and multi-value handling options.
3

4
## Capabilities
5

6
### MatrixStatsAggregationBuilders Factory
7

8
Static factory class providing convenient methods for creating matrix stats aggregation builders.
9

10
```java { .api }
11
/**
12
 * Factory class for creating matrix stats aggregation builders
13
 */
14
public class MatrixStatsAggregationBuilders {
15
    /**
16
     * Create a new MatrixStats aggregation with the given name
17
     * @param name The name for the aggregation
18
     * @return A new MatrixStatsAggregationBuilder instance
19
     */
20
    public static MatrixStatsAggregationBuilder matrixStats(String name);
21
}
22
```
23

24
**Usage Example:**
25

26
```java
27
import org.elasticsearch.search.aggregations.matrix.MatrixStatsAggregationBuilders;
28

29
// Create a matrix stats aggregation builder
30
MatrixStatsAggregationBuilder builder = MatrixStatsAggregationBuilders.matrixStats("sales_analysis");
31
```
32

33
### MatrixStatsAggregationBuilder
34

35
Builder class for configuring matrix stats aggregations with field selection and multi-value handling.
36

37
```java { .api }
38
/**
39
 * Builder for matrix stats aggregations
40
 */
41
public class MatrixStatsAggregationBuilder extends ArrayValuesSourceAggregationBuilder.LeafOnly<MatrixStatsAggregationBuilder> {
42
    /** The aggregation type name used in Elasticsearch queries */
43
    public static final String NAME = "matrix_stats";
44
    
45
    /**
46
     * Constructor for creating a new matrix stats aggregation builder
47
     * @param name The name for this aggregation instance
48
     */
49
    public MatrixStatsAggregationBuilder(String name);
50
    
51
    /**
52
     * Sets the multi-value mode for handling fields with multiple values
53
     * @param multiValueMode The mode to use (AVG, SUM, MIN, MAX, MEDIAN)
54
     * @return This builder instance for method chaining
55
     */
56
    public MatrixStatsAggregationBuilder multiValueMode(MultiValueMode multiValueMode);
57
    
58
    /**
59
     * Gets the current multi-value mode
60
     * @return The configured MultiValueMode
61
     */
62
    public MultiValueMode multiValueMode();
63
    
64
    /**
65
     * Returns the aggregation type name
66
     * @return "matrix_stats"
67
     */
68
    public String getType();
69
}
70
```
71

72
**Usage Examples:**
73

74
```java
75
import org.elasticsearch.search.aggregations.matrix.MatrixStatsAggregationBuilders;
76
import org.elasticsearch.search.MultiValueMode;
77
import java.util.Arrays;
78

79
// Basic usage with default settings
80
MatrixStatsAggregationBuilder basicBuilder = MatrixStatsAggregationBuilders
81
    .matrixStats("product_stats")
82
    .fields(Arrays.asList("price", "weight", "rating"));
83

84
// Advanced usage with multi-value mode configuration
85
MatrixStatsAggregationBuilder advancedBuilder = MatrixStatsAggregationBuilders
86
    .matrixStats("detailed_analysis")
87
    .fields(Arrays.asList("sales", "profit", "customers"))
88
    .multiValueMode(MultiValueMode.AVG)
89
    .format("0.00");
90

91
// With missing value handling
92
Map<String, Object> missingValues = new HashMap<>();
93
missingValues.put("sales", 0.0);
94
missingValues.put("profit", 0.0);
95

96
MatrixStatsAggregationBuilder builderWithMissing = MatrixStatsAggregationBuilders
97
    .matrixStats("complete_analysis")
98
    .fields(Arrays.asList("sales", "profit", "customers"))
99
    .missingMap(missingValues);
100
```
101

102
### ArrayValuesSourceAggregationBuilder Base Class
103

104
Base class providing common functionality for aggregations that work with multiple fields.
105

106
```java { .api }
107
/**
108
 * Base class for aggregations working with arrays of values sources
109
 */
110
public abstract class ArrayValuesSourceAggregationBuilder<AB extends ArrayValuesSourceAggregationBuilder<AB>> 
111
    extends AbstractAggregationBuilder<AB> {
112
    
113
    /**
114
     * Sets the fields to use for this aggregation
115
     * @param fields List of field names to analyze
116
     * @return This builder instance for method chaining
117
     */
118
    public AB fields(List<String> fields);
119
    
120
    /**
121
     * Gets the currently configured fields
122
     * @return List of field names
123
     */
124
    public List<String> fields();
125
    
126
    /**
127
     * Sets the format to use for the output of the aggregation
128
     * @param format Format string for numeric output
129
     * @return This builder instance for method chaining
130
     */
131
    public AB format(String format);
132
    
133
    /**
134
     * Gets the format to use for the output of the aggregation
135
     * @return Current format string
136
     */
137
    public String format();
138
    
139
    /**
140
     * Sets the value to use when the aggregation finds a missing value in a document
141
     * @param missingMap Map of field names to default values
142
     * @return This builder instance for method chaining
143
     */
144
    public AB missingMap(Map<String, Object> missingMap);
145
    
146
    /**
147
     * Gets the value to use when the aggregation finds a missing value in a document
148
     * @return Map of field names to default values
149
     */
150
    public Map<String, Object> missingMap();
151
}
152
```
153

154
### LeafOnly Specialization
155

156
Specialization for aggregations that cannot accept sub-aggregations.
157

158
```java { .api }
159
/**
160
 * Base class for leaf-only aggregations (cannot accept sub-aggregations)
161
 */
162
public abstract static class LeafOnly<AB extends ArrayValuesSourceAggregationBuilder<AB>> 
163
    extends ArrayValuesSourceAggregationBuilder<AB> {
164
    
165
    /**
166
     * Constructor for leaf-only aggregation builders
167
     * @param name The aggregation name  
168
     */
169
    protected LeafOnly(String name);
170
    
171
    /**
172
     * Returns the bucket cardinality for this aggregation type
173
     * @return BucketCardinality.NONE (leaf aggregations don't create buckets)
174
     */
175
    public final BucketCardinality bucketCardinality();
176
}
177
```
178

179
## Multi-Value Mode Options
180

181
When fields contain multiple values per document, the aggregation uses the specified MultiValueMode:
182

183
- **AVG** (default): Uses the average of all values
184
- **SUM**: Uses the sum of all values  
185
- **MIN**: Uses the minimum value
186
- **MAX**: Uses the maximum value
187
- **MEDIAN**: Uses the median value
188

189
## Error Handling
190

191
The builder validates field names and configuration options. Common validation errors include:
192

193
- **IllegalArgumentException**: Thrown when field list is null or empty
194
- **AggregationInitializationException**: Thrown when attempting to add sub-aggregations to a leaf aggregation