All articles

OpenSearch terms aggregation order: make doc count ranking explicit

If anything downstream ranks results by the order of an OpenSearch terms aggregation's buckets, set that order explicitly: _count descending, then _key ascending as a tie-break. The default happens to sort by document count, but a default is not a contract, and the first refactor that touches the query (or swaps it for a composite aggregation) will quietly change the ranking. Write the order into the request, document it on the interface, and pin it in a test.

How a list of ids became a ranking

A .NET service on a job board platform answers a simple question: which companies have at least one open job whose title matches a phrase? It runs a search with size: 0, puts a terms aggregation on the company id field with a generous bucket size, and returns the bucket keys as a list of ids.

Nobody asked for an order when it was written. The callers used the list as a set: "is this company in it?" Later a directory page that filters companies by job title started using the list differently. It sorts by a business priority first, then by the position of each company in that list, then by id. In other words, a company with more matching jobs ranks higher.

That worked, because the terms aggregation's default order is document count descending. It also meant the page's ranking now depended on a property of the query that nobody had chosen, written down or tested.

Why relying on the default order is fragile

The terms aggregation documentation says buckets are ordered by doc_count descending unless you say otherwise. What it promises less loudly is what happens on ties, and ties are common here: plenty of companies have exactly one matching job. If the tie order is not deterministic, the directory reshuffles between two identical requests, which looks like a bug to anyone paging through it.

The bigger risk is that the order lives nowhere in the code. A few changes that look harmless from inside the search service would each break the ranking without breaking a single existing test:

  • Ordering by _key to make some other caller's output stable.
  • Switching to a composite aggregation to page through every bucket. Composite buckets come back in key order, not count order.
  • Moving the aggregation behind a shared query builder that sets its own order.

None of these is wrong for the search service on its own. They are only wrong because a caller two hops away relies on something the service never said it did.

How to set the order explicitly

The fix is small. In the raw query DSL, order accepts an array, applied in sequence:

{
  "size": 0,
  "query": { "match": { "title": "data engineer" } },
  "aggs": {
    "by_company": {
      "terms": {
        "field": "company_id",
        "size": 5000,
        "order": [ { "_count": "desc" }, { "_key": "asc" } ]
      }
    }
  }
}

With the OpenSearch .NET high-level client (OpenSearch.Client), the same thing reads:

var response = await client.SearchAsync<JobDocument>(s => s
    .Size(0)
    .Query(q => q.Match(m => m.Field(f => f.Title).Query(title)))
    .Aggregations(a => a
        .Terms("by_company", t => t
            .Field(f => f.CompanyId)
            .Size(5000)
            .Order(o => o.CountDescending().KeyAscending()))));

var terms = response.Aggregations.Terms("by_company");
var companyIds = terms.Buckets.Select(b => long.Parse(b.Key)).ToList();

The second sort key matters as much as the first. With _key ascending as the tie-break, two companies with the same number of matching jobs always come back in the same relative order, so the downstream sort is deterministic without any extra work.

Then say it where callers will read it. The XML doc comment on the service method and on the client interface now states that ids are returned in descending order of matching documents, ties by ascending id. That sentence is the contract; the query is how the service keeps it.

What the size cap does to the ranking

A terms aggregation returns at most size buckets. When it is ordered by count, the buckets that fall off the end are the ones with the fewest matches, which is usually what you want for a ranking. It is still worth knowing that it happened. The response carries sum_other_doc_count: the number of matching documents whose terms did not make it into the returned buckets. If that is above zero, some companies with matching jobs are missing from the list.

if (terms.SumOtherDocCount > 0)
{
    logger.LogWarning(
        "Company aggregation hit its bucket cap; {Omitted} matching documents were not bucketed",
        terms.SumOtherDocCount);
}

On an index with several shards there is a second subtlety. Each shard returns its own top shard_size terms and the coordinating node merges them, so counts near the cut-off can be slightly under-reported. doc_count_error_upper_bound tells you the worst case. For a "rank by roughly how many jobs match" use this is fine; for anything that has to be exact, raise shard_size or rethink the approach.

When a composite aggregation is the better tool

If the number of distinct companies could plausibly exceed any cap you are comfortable setting, the usual answer is a composite aggregation, which pages through every bucket with an after key. The trade-off is exactly the one that makes the explicit order worth having: composite buckets are sorted by key, and there is no way to ask for them by count. You would collect every page and sort by doc_count in the service yourself.

That is a perfectly good design, and with the order written into the contract it becomes a safe change: whoever makes it can see that count order is required, and the tests will tell them if they forget to sort.

How to pin the order in tests

Two tests cover it. The first checks the request the service builds, so a change to the query fails fast without a cluster. Serialise the request with the client's own serializer and assert on the order:

[Fact]
public void CompanyAggregation_OrdersByCountThenKey()
{
    var request = CompanySearchQueries.CompaniesWithMatchingJobs("data engineer");

    var json = JsonDocument.Parse(client.RequestResponseSerializer.SerializeToString(request));
    var order = json.RootElement
        .GetProperty("aggs").GetProperty("by_company")
        .GetProperty("terms").GetProperty("order");

    Assert.Equal("desc", order[0].GetProperty("_count").GetString());
    Assert.Equal("asc", order[1].GetProperty("_key").GetString());
}

The second checks the service's output against a canned aggregation response with deliberate ties, and asserts the ids come back in the documented order. That one protects the mapping code: it is easy to put the buckets through a HashSet or a dictionary on the way out and lose the order the query worked to produce.

Key takeaways

  • If a caller uses the order of terms aggregation buckets, set order explicitly instead of inheriting the default.
  • Add _key ascending after _count descending so ties come back in the same order on every request.
  • Check sum_other_doc_count to know when the bucket size cap has dropped results from a ranking.
  • A composite aggregation removes the cap but returns buckets in key order, so the caller or service must sort by count itself.
  • Document the order on the service interface and pin both the serialised request and the returned order in tests.