Lineage queries

A lineage field stores values that form a hierarchy. For example, if B.1.1 is a sub-lineage of B.1, then a query for B.1* can include records assigned to B.1, B.1.1, B.1.1.7, and other descendants.

Exact Matches

Without a wildcard, lineage filters match only the exact lineage value:

GET /sample/aggregated?lineageField=B.1.1

This returns records whose lineage field value is exactly B.1.1.

Including Descendants

To include sub-lineages, add * at the end of the lineage:

GET /sample/aggregated?lineageField=B.1.1*

B.1.1* and B.1.1.* are equivalent. Both match B.1.1 itself and descendants such as B.1.1.7.

Counting Every Lineage Including Its Sublineages

On the /sample/aggregated endpoint you can add a lineage field suffixed with * to the fields parameter (for example lineageField*). This returns, for every lineage, the count of sequences in that lineage together with all of its sublineages — in a single query.

GET /sample/aggregated?fields=lineageField*

The response column is named lineageField*, and its values carry a trailing * to indicate that they are sublineage-inclusive, for example B.1.1*:

{
    "data": [
        {
            "lineageField*": "B*",
            "count": 97
        },
        {
            "lineageField*": "B.1*",
            "count": 97
        },
        {
            "lineageField*": "B.1.1*",
            "count": 61
        }
    ]
}

You can combine it with other fields and with filters as usual.

Advanced Queries

Lineage-indexed fields can also be used in advanced queries:

GET /sample/aggregated?advancedQuery=lineageField=B.1.1*

In POST requests, use the same expression as the advancedQuery value:

{
    "advancedQuery": "lineageField=B.1.1*"
}