0
# Elasticsearch Matrix Stats Aggregation Plugin
1

2
The Matrix Stats aggregation plugin extends Elasticsearch with advanced statistical analysis capabilities across multiple numeric fields. It computes comprehensive statistical measures including basic statistics (count, mean, variance) and advanced metrics (skewness, kurtosis) for individual fields, along with cross-field relationships through covariance and correlation matrices.
3

4
## Package Information
5

6
- **Package Name**: aggs-matrix-stats-client
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: This is an Elasticsearch module included with Elasticsearch distributions
10
- **Plugin Class**: `org.elasticsearch.search.aggregations.matrix.MatrixAggregationPlugin`
11

12
## Core Imports
13

14
```java
15
import org.elasticsearch.search.aggregations.matrix.MatrixStatsAggregationBuilders;
16
import org.elasticsearch.search.aggregations.matrix.stats.MatrixStats;
17
import org.elasticsearch.search.aggregations.matrix.stats.MatrixStatsAggregationBuilder;
18
```
19

20
## Basic Usage
21

22
```java
23
import org.elasticsearch.search.aggregations.matrix.MatrixStatsAggregationBuilders;
24
import org.elasticsearch.search.aggregations.matrix.stats.MatrixStats;
25
import org.elasticsearch.action.search.SearchResponse;
26
import org.elasticsearch.search.aggregations.Aggregations;
27

28
// Create a matrix stats aggregation
29
MatrixStatsAggregationBuilder aggregationBuilder = 
30
    MatrixStatsAggregationBuilders.matrixStats("price_stats")
31
        .fields(Arrays.asList("price", "quantity", "discount"));
32

33
// Add to search request (this would be part of a larger search request)
34
SearchResponse response = client.search(searchRequest);
35

36
// Extract results
37
Aggregations aggregations = response.getAggregations();
38
MatrixStats matrixStats = aggregations.get("price_stats");
39

40
// Access statistical results
41
long docCount = matrixStats.getDocCount();
42
double priceCount = matrixStats.getFieldCount("price");
43
double priceMean = matrixStats.getMean("price");
44
double priceVariance = matrixStats.getVariance("price");
45
double correlation = matrixStats.getCorrelation("price", "quantity");
46
```
47

48
## Architecture
49

50
The Matrix Stats aggregation plugin is built around several key components:
51

52
- **Plugin Registration**: `MatrixAggregationPlugin` registers the aggregation with Elasticsearch
53
- **Builder Pattern**: `MatrixStatsAggregationBuilder` provides fluent API for configuration
54
- **Aggregation Interface**: `MatrixStats` defines the contract for accessing statistical results
55
- **Internal Implementation**: `InternalMatrixStats` handles distributed computation across shards
56
- **Running Statistics**: Efficient single-pass algorithm for computing statistics across large datasets
57
- **Result Computation**: Final statistical measures computed on coordinating node from shard-level statistics
58

59
## Capabilities
60

61
### Aggregation Builder
62

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

65
```java { .api }
66
public class MatrixStatsAggregationBuilders {
67
    public static MatrixStatsAggregationBuilder matrixStats(String name);
68
}
69

70
public class MatrixStatsAggregationBuilder extends ArrayValuesSourceAggregationBuilder.LeafOnly<MatrixStatsAggregationBuilder> {
71
    public static final String NAME = "matrix_stats";
72
    
73
    public MatrixStatsAggregationBuilder(String name);
74
    public MatrixStatsAggregationBuilder multiValueMode(MultiValueMode multiValueMode);
75
    public MultiValueMode multiValueMode();
76
    public String getType();
77
}
78
```
79

80
[Aggregation Builder](./aggregation-builder.md)
81

82
### Statistical Results Interface
83

84
Core interface for accessing computed statistical measures from matrix stats aggregation results.
85

86
```java { .api }
87
public interface MatrixStats extends Aggregation {
88
    long getDocCount();
89
    long getFieldCount(String field);
90
    double getMean(String field);
91
    double getVariance(String field);
92
    double getSkewness(String field);
93
    double getKurtosis(String field);
94
    double getCovariance(String fieldX, String fieldY);
95
    double getCorrelation(String fieldX, String fieldY);
96
}
97
```
98

99
[Statistical Results](./statistical-results.md)
100

101
### Plugin Registration
102

103
Plugin main class that registers the matrix_stats aggregation type with Elasticsearch's aggregation framework.
104

105
```java { .api }
106
public class MatrixAggregationPlugin extends Plugin implements SearchPlugin {
107
    public List<AggregationSpec> getAggregations();
108
}
109
```
110

111
[Plugin Registration](./plugin-registration.md)
112

113
## Types
114

115
```java { .api }
116
// From Elasticsearch core - used for handling multi-value fields
117
enum MultiValueMode {
118
    SUM, AVG, MEDIAN, MIN, MAX
119
}
120

121
// From Elasticsearch core - indicates aggregation bucket cardinality
122
enum BucketCardinality {
123
    NONE, ONE, MANY
124
}
125

126
// Base class for array-based aggregation builders
127
public abstract class ArrayValuesSourceAggregationBuilder<AB extends ArrayValuesSourceAggregationBuilder<AB>> 
128
    extends AbstractAggregationBuilder<AB> {
129
    
130
    public AB fields(List<String> fields);
131
    public List<String> fields();
132
    public AB format(String format);
133
    public String format();
134
    public AB missingMap(Map<String, Object> missingMap);
135
    public Map<String, Object> missingMap();
136
}
137

138
// Specialization for leaf aggregations (no sub-aggregations)
139
public abstract static class LeafOnly<AB extends ArrayValuesSourceAggregationBuilder<AB>> 
140
    extends ArrayValuesSourceAggregationBuilder<AB> {
141
    
142
    protected LeafOnly(String name);
143
    public final BucketCardinality bucketCardinality();
144
}
145

146
// Base parser for array values source aggregations
147
public abstract class ArrayValuesSourceParser<VS extends ValuesSource> implements Aggregator.Parser {
148
    public final ArrayValuesSourceAggregationBuilder<?> parse(String aggregationName, XContentParser parser) throws IOException;
149
    protected abstract ArrayValuesSourceAggregationBuilder<?> createFactory(
150
        String aggregationName,
151
        ValuesSourceType valuesSourceType,
152
        ValueType targetValueType,
153
        Map<ParseField, Object> otherOptions
154
    );
155
}
156

157
// Running statistics computation for single-pass algorithm
158
public class RunningStats implements Writeable, Cloneable {
159
    public RunningStats(StreamInput in) throws IOException;
160
    public void writeTo(StreamOutput out) throws IOException;
161
    public void add(String[] fieldNames, double[] fieldVals);
162
    public void merge(RunningStats other);
163
    public RunningStats clone();
164
}
165

166
// Internal aggregator implementation
167
public class MatrixStatsAggregator extends Aggregator {
168
    // Internal implementation for computing matrix statistics during aggregation
169
}
170

171
// Internal factory for creating aggregator instances
172
public class MatrixStatsAggregatorFactory extends AggregatorFactory {
173
    // Internal factory for creating MatrixStatsAggregator instances
174
}
175
```