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.

Aggregating Including Sublineages

The * suffix above includes descendants when filtering. The includeSublineagesFor parameter is the aggregation counterpart: it groups the /sample/aggregated results by a lineage field so that each lineage’s count includes the sequences assigned to that lineage or any of its sublineages.

Name the lineage field to expand with includeSublineagesFor, and list that same field in fields:

GET /sample/aggregated?fields=lineageField&includeSublineagesFor=lineageField

In a POST request:

{
    "fields": [
        "lineageField"
    ],
    "includeSublineagesFor": "lineageField"
}

The response contains one row per lineage defined for that field, including lineages that have a count of zero. This makes the result well-suited to building lineage facets, where you want every possible lineage listed even if no sequence currently matches.

Caution

includeSublineagesFor can only group by a single field. The field it names must be the only entry in fields. Combining sublineage-inclusive aggregation with any other group-by field (for example adding country to fields) is not supported and returns an error. If you need a breakdown by another field as well, run separate queries.

Caution

Unlike a plain group-by, these counts do not partition the data. A sequence is counted under its own lineage and under every ancestor lineage, so if B.1.1 is a sub-lineage of B.1, a B.1.1 sequence contributes to both the B.1.1 and the B.1 count. As a result the counts do not sum to the total number of sequences.

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*"
}