Adjacency matrix aggregation #

A multi-bucket aggregation returning every named filter’s document set plus their pairwise INTERSECTIONS — the cross product view of several filters. Where filters answers each filter separately, this one also tells you how much they overlap, which is exactly what co-occurrence analysis needs.

How it works #

Each named filter is evaluated against every candidate document, so a document can carry several filter flags at once. The engine then emits one bucket per non-empty filter (keyed by its name) and one bucket per non-empty pair, keyed a&b with the two names in alphabetical order. Intersections beyond pairs — no a&b&c triples — are not computed, and empty buckets are skipped entirely, so the bucket count tops out at n·(n−1)/2 + n.

Buckets are returned sorted by key ascending: delivered, delivered&hats, hats. Sub-aggregations run per bucket over that bucket’s documents, so an intersection bucket can carry its own sums and averages — the profile of “documents matching both”.

Examples #

hats and delivered filters, and the documents matching both:

Buckets: hats (30), delivered (40) and delivered&hats (10); empty intersections are skipped. Keys sort alphabetically, so delivered leads:

{
  ...
  "aggregations": {
    "matrix": {
      "buckets": [
        { "key": "delivered", "doc_count": 40 },
        { "key": "delivered&hats", "doc_count": 10 },
        { "key": "hats", "doc_count": 30 }
      ]
    }
  }
}

Use cases #

• Tag co-occurrence. Declare one filter per important tag; the a&b buckets are the edge weights of the tag graph.
• Audience overlap. “Premium users” × “Active last 7 days” — the intersection bucket is the segment every growth report argues about.
• Label QA. Filters that should be mutually exclusive but show a non-empty a&b bucket expose a classification bug immediately.
• Facet cross-tabs. A two-filter matrix with a sum nested per bucket is a small pivot table built from one request.
• Graph edges from facets. Any set of boolean-ish facets becomes an adjacency list: the non-empty a&b buckets are the edges, their doc_count the weights.

Parameters for adjacency_matrix #

• filters
  (Required, object) Named filter queries; each name (and each a&b intersection) becomes a bucket.
• aggs
  (Optional, object) Sub-aggregations computed per bucket.

Related #

• filters — the same named filters without the intersections
• terms — single-field co-occurrence counts
• filter — one query, one bucket