String stats aggregation #

A multi-value metrics aggregation computing length and character statistics over keyword/string values: count, min/max/avg length and Shannon entropy of the character distribution.

How it works #

Every document that has a string value for the field contributes one string. Over those strings the engine reports:

• count — how many values were seen (documents without the field are skipped, not counted);
• min_length, max_length, avg_length — length statistics in UTF-8 bytes, so a non-ASCII character counts as its encoded width;
• entropy — Shannon entropy of the pooled character frequencies, in bits: -Σ p(c) · log2 p(c) over the share p(c) of each character across all strings. Constant text gives 0; text where every character is equally likely gives log2(alphabet size).

The character frequencies are pooled across all contributing values before the entropy is taken, so repetition across documents counts: the teaching type field repeats the same few words 120 times and still scores ≈3.22 bits.

If no document has a string value, all five numbers come back as 0. No per-character distribution map is returned; show_distribution: true has no effect here.

Example #

Four product types (t-shirt 7 chars ×60, hat 3 ×30, mug 3 ×20, sticker 7 ×10): count 120, min_length 3, max_length 7, avg_length ≈5.33.

POST /sales/_search
{
  "aggs": {
    "type_stats": {
      "string_stats": {
        "field": "type"
      }
    }
  }
}

Response:

{
  ...
  "aggregations": {
    "type_stats": {
      "count": 120,
      "min_length": 3,
      "max_length": 7,
      "avg_length": 5.333333333333333,
      "entropy": 3.222680611208111
    }
  }
}

For contrast, logs.level (info ×100, error ×25, warn ×25) gives count 150, min_length 4, max_length 5, avg_length ≈4.17 and entropy ≈2.76 — a smaller character pool over shorter words than the product types, so less uncertainty per character.

Use cases #

• Field-length audits. max_length near a storage or UI limit flags values that will not fit; a max_length far above avg_length means a few pathological entries (typically concatenated or spilled fields).
• Entropy profiling. High-entropy fields look like IDs, tokens or hashes; near-zero entropy means an effectively constant field — both matter when deciding what to index, facet on, or anonymize.
• Vocabulary reconnaissance. Before choosing analyzer settings or term facets, entropy and length say how varied a keyword field really is (type: 4 distinct short words; a message field would score far higher).
• Data-quality gates. count below the document count reveals documents missing the field; length stats out of contract reveal machine-generated junk.

Parameters for string_stats #

• field
  (Required, string) Keyword field you wish to aggregate.

Related #

• cardinality — how many distinct strings, rather than how long and how varied.
• value_count — how many values in total.
• terms — the actual distinct strings with counts, for when the aggregate stats raise a question.