or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

aggregation-builder.mdindex.mdplugin-registration.mdstatistical-results.md
tile.json

tessl/maven-org-elasticsearch-plugin--aggs-matrix-stats-client

Elasticsearch plugin that adds matrix statistics aggregation functionality for computing statistical measures and relationships across multiple numeric fields

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.elasticsearch.plugin/aggs-matrix-stats-client@7.17.x

To install, run

npx @tessl/cli install tessl/maven-org-elasticsearch-plugin--aggs-matrix-stats-client@7.17.0

index.mddocs/

Elasticsearch Matrix Stats Aggregation Plugin

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.

Package Information

  • Package Name: aggs-matrix-stats-client
  • Package Type: maven
  • Language: Java
  • Installation: This is an Elasticsearch module included with Elasticsearch distributions
  • Plugin Class: org.elasticsearch.search.aggregations.matrix.MatrixAggregationPlugin

Core Imports

import org.elasticsearch.search.aggregations.matrix.MatrixStatsAggregationBuilders;
import org.elasticsearch.search.aggregations.matrix.stats.MatrixStats;
import org.elasticsearch.search.aggregations.matrix.stats.MatrixStatsAggregationBuilder;

Basic Usage

import org.elasticsearch.search.aggregations.matrix.MatrixStatsAggregationBuilders;
import org.elasticsearch.search.aggregations.matrix.stats.MatrixStats;
import org.elasticsearch.action.search.SearchResponse;
import org.elasticsearch.search.aggregations.Aggregations;

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

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

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

// Access statistical results
long docCount = matrixStats.getDocCount();
double priceCount = matrixStats.getFieldCount("price");
double priceMean = matrixStats.getMean("price");
double priceVariance = matrixStats.getVariance("price");
double correlation = matrixStats.getCorrelation("price", "quantity");

Architecture

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

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

Capabilities

Aggregation Builder

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

public class MatrixStatsAggregationBuilders {
    public static MatrixStatsAggregationBuilder matrixStats(String name);
}

public class MatrixStatsAggregationBuilder extends ArrayValuesSourceAggregationBuilder.LeafOnly<MatrixStatsAggregationBuilder> {
    public static final String NAME = "matrix_stats";
    
    public MatrixStatsAggregationBuilder(String name);
    public MatrixStatsAggregationBuilder multiValueMode(MultiValueMode multiValueMode);
    public MultiValueMode multiValueMode();
    public String getType();
}

Aggregation Builder

Statistical Results Interface

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

public interface MatrixStats extends Aggregation {
    long getDocCount();
    long getFieldCount(String field);
    double getMean(String field);
    double getVariance(String field);
    double getSkewness(String field);
    double getKurtosis(String field);
    double getCovariance(String fieldX, String fieldY);
    double getCorrelation(String fieldX, String fieldY);
}

Statistical Results

Plugin Registration

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

public class MatrixAggregationPlugin extends Plugin implements SearchPlugin {
    public List<AggregationSpec> getAggregations();
}

Plugin Registration

Types

// From Elasticsearch core - used for handling multi-value fields
enum MultiValueMode {
    SUM, AVG, MEDIAN, MIN, MAX
}

// From Elasticsearch core - indicates aggregation bucket cardinality
enum BucketCardinality {
    NONE, ONE, MANY
}

// Base class for array-based aggregation builders
public abstract class ArrayValuesSourceAggregationBuilder<AB extends ArrayValuesSourceAggregationBuilder<AB>> 
    extends AbstractAggregationBuilder<AB> {
    
    public AB fields(List<String> fields);
    public List<String> fields();
    public AB format(String format);
    public String format();
    public AB missingMap(Map<String, Object> missingMap);
    public Map<String, Object> missingMap();
}

// Specialization for leaf aggregations (no sub-aggregations)
public abstract static class LeafOnly<AB extends ArrayValuesSourceAggregationBuilder<AB>> 
    extends ArrayValuesSourceAggregationBuilder<AB> {
    
    protected LeafOnly(String name);
    public final BucketCardinality bucketCardinality();
}

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

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

// Internal aggregator implementation
public class MatrixStatsAggregator extends Aggregator {
    // Internal implementation for computing matrix statistics during aggregation
}

// Internal factory for creating aggregator instances
public class MatrixStatsAggregatorFactory extends AggregatorFactory {
    // Internal factory for creating MatrixStatsAggregator instances
}