Additional Collectors¶

The SearchRequest can define a mapping of additional collectors to compute aggregations over the recalled document set.

//Definition of additional document collector.
message Collector {
    oneof Collectors {
        //Collector for aggregating based on term values.
        TermsCollector terms = 1;
        PluginCollector pluginCollector = 2;
        //Collector for getting top hits based on score or sorting.
        TopHitsCollector topHitsCollector = 4;
        //Collector that filters documents to nested collectors
        FilterCollector filter = 5;
        //Collector for finding a max double value from collected documents.
        MaxCollector max = 6;
        //Collector for finding a min double value from collected documents.
        MinCollector min = 7;
    }
    //Nested collectors that define sub-aggregations per bucket, supported by bucket based collectors.
    map<string, Collector> nestedCollectors = 3;
}

Terms Collector¶

Aggregate term counts into buckets based on term values.

//Definition of term aggregating collector.
message TermsCollector {
    oneof TermsSource {
        //Use field values for terms.
        string field = 1;
        //Use FacetScript definition to produce terms.
        Script script = 2;
    }
    //Maximum number of top terms to return.
    int32 size = 3;
    //How results Buckets should be ordered, defaults to descending Bucket _count.
    BucketOrder order = 4;
}

Terms can either come from the doc values of an indexed field, or be produced by a script. If nestedCollectors are defined, they will compute sub-aggregations per bucket.

Bucket Order¶

The ordering to use when sorting aggregated buckets can optionally be defined. The order defaults to the bucket count value in descending order.

//Defines how Buckets should be ordered in BucketResult.
message BucketOrder {
    //Sorting order type
    enum OrderType {
        DESC = 0;
        ASC = 1;
    }
    //What to use for sorting. This can be _count for Bucket count, or the name of a nested collector that supports ordering.
    string key = 1;
    //Sorting order
    OrderType order = 2;
}

When specifying a nested collector name, the collector type must support ordering. Currently, only the max and min collector type supports this.

Plugin Collector¶

Aggregate using a collector defined by a plugin.

// Defines an entry point for using a collector from a plugin
message PluginCollector {
    string name = 1;
    google.protobuf.Struct params = 2; // arguments passed to the plugin
}

The name must have been registered by a plugin defining the CollectorPlugin interface.

Top Hits Collector¶

Collect the top hits for aggregated documents based on relevance score or sorting.

//Definition of top hits based collector.
message TopHitsCollector {
    //Offset for retrieval of top hits.
    int32 startHit = 1;
    //Total hits to collect, note that the number of hits returned is (topHits - startHit).
    int32 topHits = 2;
    //When specified, collector does sort based collection. Otherwise, relevance score is used.
    QuerySortField querySort = 3;
    //Which fields to retrieve.
    repeated string retrieveFields = 4;
    // If Lucene explanation should be included in the collector response
    bool explain = 5;
}

Filter Collector¶

Forwards documents through to nested collectors that pass the given criteria.

//Definition of filtering collector, there must be at least one nested collector specified in the Collector message.
message FilterCollector {
    oneof Filter {
        // Only propagate documents that match the given query.
        Query query = 1;
        // Specialized implementation for set queries, checks if field doc values are in the provided set. This can be useful for large set sizes with lower recall, where building the scorer would be expensive.
        TermInSetQuery setQuery = 2;
    }
}

Max Collector¶

Collect a maximum double value across all aggregated documents. This value is produced by execution of a score script per document.

//Definition of collector to find a max double value over documents. Currently only allows for script based value production.
message MaxCollector {
    oneof ValueSource {
        //Script to produce a double value
        Script script = 1;
    }
}

This aggregation is usable for sorting buckets as a nested collector.

Min Collector¶

Collect a minimum double value across all aggregated documents. This value is produced by execution of a score script per document.

//Definition of collector to find a min double value over documents. Currently only allows for script based value production.
message MinCollector {
    oneof ValueSource {
        //Script to produce a double value
        Script script = 1;
    }
}