0
# Plugin Registration
1

2
Plugin main class and supporting infrastructure that registers the matrix_stats aggregation type with Elasticsearch's aggregation framework.
3

4
## Capabilities
5

6
### MatrixAggregationPlugin
7

8
Main plugin class that integrates the matrix stats aggregation with Elasticsearch's plugin system.
9

10
```java { .api }
11
/**
12
 * Main plugin class for the Matrix Stats aggregation
13
 * Registers the matrix_stats aggregation type with Elasticsearch
14
 */
15
public class MatrixAggregationPlugin extends Plugin implements SearchPlugin {
16
    /**
17
     * Returns the list of aggregation specifications provided by this plugin
18
     * @return List containing the matrix_stats aggregation specification
19
     */
20
    public List<AggregationSpec> getAggregations();
21
}
22
```
23

24
**Implementation Details:**
25

26
The plugin registers a single aggregation type with the following components:
27

28
- **Aggregation Name**: `"matrix_stats"`
29
- **Builder Factory**: `MatrixStatsAggregationBuilder::new`
30
- **Parser**: `MatrixStatsParser` instance for parsing query DSL
31
- **Result Reader**: `InternalMatrixStats::new` for deserializing shard results
32

33
**Usage Context:**
34

35
This plugin class is automatically loaded by Elasticsearch when the aggs-matrix-stats module is available. Users don't directly instantiate this class - it's managed by Elasticsearch's plugin framework.
36

37
```java
38
// Plugin registration happens automatically in Elasticsearch
39
// The following aggregation becomes available in search requests:
40

41
{
42
  "aggs": {
43
    "my_matrix_stats": {
44
      "matrix_stats": {
45
        "fields": ["price", "quantity", "discount"]
46
      }
47
    }
48
  }
49
}
50
```
51

52
### MatrixStatsParser
53

54
Parser class for processing matrix_stats aggregation definitions from Elasticsearch query DSL.
55

56
```java { .api }
57
/**
58
 * Parser for matrix stats aggregation query DSL
59
 * Extends NumericValuesSourceParser to handle numeric field aggregations
60
 */
61
public class MatrixStatsParser extends NumericValuesSourceParser {
62
    /**
63
     * Default constructor enabling formatting support
64
     */
65
    public MatrixStatsParser();
66
    
67
    /**
68
     * Creates a MatrixStatsAggregationBuilder from parsed aggregation definition
69
     * @param aggregationName Name of the aggregation instance
70
     * @param valuesSourceType Type of values source (numeric)
71
     * @param targetValueType Target value type for the aggregation
72
     * @param otherOptions Additional parsed options (like multiValueMode)
73
     * @return Configured MatrixStatsAggregationBuilder
74
     */
75
    protected MatrixStatsAggregationBuilder createFactory(
76
        String aggregationName,
77
        ValuesSourceType valuesSourceType,
78
        ValueType targetValueType,
79
        Map<ParseField, Object> otherOptions
80
    );
81
}
82
```
83

84
**Supported Query DSL Options:**
85

86
```json
87
{
88
  "matrix_stats": {
89
    "fields": ["field1", "field2", "field3"],
90
    "missing": {
91
      "field1": 0,
92
      "field2": 10.5
93
    },
94
    "mode": "avg"
95
  }
96
}
97
```
98

99
### MatrixStatsNamedXContentProvider
100

101
Service Provider Interface (SPI) class for registering XContent parsers with Elasticsearch's content parsing framework.
102

103
```java { .api }
104
/**
105
 * SPI provider for registering matrix stats XContent parsers
106
 * Enables parsing of matrix stats aggregation results from JSON responses
107
 */
108
public class MatrixStatsNamedXContentProvider implements NamedXContentProvider {
109
    /**
110
     * Returns the list of named XContent parser entries for this plugin
111
     * @return List containing parser entry for ParsedMatrixStats
112
     */
113
    public List<NamedXContentRegistry.Entry> getNamedXContentParsers();
114
}
115
```
116

117
**Registration Details:**
118

119
This SPI provider registers a parser for the `"matrix_stats"` aggregation type that:
120

121
- **Parse Field**: `"matrix_stats"`
122
- **Target Class**: `Aggregation.class`
123
- **Parser Function**: `ParsedMatrixStats.fromXContent`
124

125
This enables Elasticsearch clients to automatically parse matrix stats aggregation results from JSON responses into `ParsedMatrixStats` objects.
126

127
### MatrixAggregationInspectionHelper
128

129
Helper class providing inspection and testing utilities for matrix aggregations.
130

131
```java { .api }
132
/**
133
 * Helper class for aggregation inspection and testing
134
 * Provides utilities for examining matrix aggregation internals
135
 */
136
public class MatrixAggregationInspectionHelper {
137
    // Implementation details are internal to Elasticsearch testing framework
138
    // This class is primarily used for unit testing and debugging
139
}
140
```
141

142
## Plugin Integration Architecture
143

144
The matrix stats plugin integrates with Elasticsearch through several extension points:
145

146
### Search Plugin Interface
147

148
```java { .api }
149
/**
150
 * Elasticsearch's SearchPlugin interface allows plugins to extend search functionality
151
 */
152
public interface SearchPlugin {
153
    /**
154
     * Returns aggregation specifications provided by this plugin
155
     * @return List of AggregationSpec instances
156
     */
157
    default List<AggregationSpec> getAggregations() {
158
        return Collections.emptyList();
159
    }
160
}
161

162
/**
163
 * Specification for registering an aggregation type
164
 */
165
public static class AggregationSpec {
166
    /**
167
     * Create aggregation specification
168
     * @param name Aggregation type name used in queries
169
     * @param builderReader Function to create builder from stream input
170
     * @param parser Parser for query DSL
171
     */
172
    public AggregationSpec(
173
        String name,
174
        Writeable.Reader<? extends AggregationBuilder> builderReader,
175
        Aggregator.Parser parser
176
    );
177
    
178
    /**
179
     * Add result reader for deserializing aggregation results
180
     * @param resultReader Function to create result from stream input
181
     * @return This specification for chaining
182
     */
183
    public AggregationSpec addResultReader(
184
        Writeable.Reader<? extends InternalAggregation> resultReader
185
    );
186
}
187
```
188

189
### Plugin Lifecycle
190

191
1. **Loading**: Elasticsearch discovers the plugin via classpath scanning
192
2. **Registration**: `getAggregations()` is called to register aggregation types
193
3. **Query Processing**: When `matrix_stats` appears in queries, the registered parser handles it
194
4. **Execution**: Elasticsearch creates aggregators using the registered builder factory
195
5. **Result Processing**: Results are serialized/deserialized using registered result readers
196

197
## Error Handling
198

199
The plugin registration system handles various error conditions:
200

201
- **Plugin Loading Errors**: If the plugin fails to load, Elasticsearch logs errors and continues without the plugin
202
- **Registration Conflicts**: If multiple plugins try to register the same aggregation name, Elasticsearch reports conflicts
203
- **Parser Errors**: Invalid query DSL is handled by the parser with appropriate error messages
204
- **Version Compatibility**: Plugin version compatibility is enforced by Elasticsearch's plugin system
205

206
## Dependencies
207

208
The plugin depends on core Elasticsearch classes:
209

210
- `org.elasticsearch.plugins.Plugin` - Base plugin interface
211
- `org.elasticsearch.plugins.SearchPlugin` - Search extension interface  
212
- `org.elasticsearch.search.aggregations.*` - Aggregation framework classes
213
- `org.elasticsearch.plugins.spi.NamedXContentProvider` - Content parsing SPI