Function reference

Functions produce scalar values or predicates. Boolean functions are used in filter expressions; value-producing functions can be assigned in map operations.

General functions

`at(column, position)`

Return the character at a 1-based position. A position beyond the value returns an empty string; null remains null.

default.map({symbol := S.at(501)})

`isoWeek(column)`

Return the ISO 8601 week date of a date column as a string of the form <ISO-year>-W<ISO-week>, such as 2026-W12. The zero-padded week keeps the values sortable within a year. The ISO week-numbering year can differ from the calendar year around the turn of the year: 2021-01-01 falls into 2020-W53.

default.map({week := date.isoWeek()})

`between(column, from, to)`

Test an inclusive date or numeric range. Use null for an open bound.

date.between('2024-01-01'::date, '2024-12-31'::date)
age.between(18, null)

`in(column, {values})`

Test whether a string column equals one of the values in a set.

country.in({'Germany', 'France', 'Italy'})

`isNull(column) / isNotNull(column)`

Test whether a column value is null or non-null. These are the only way to filter on missing values, because comparing a column against the null literal is an error.

isNotNull(date)

`like(column, pattern)`

Match a string with an RE2 regular expression.

division.like('Basel.*')

Lineage and phylogenetic functions

`lineage(column, value [, includeSublineages := bool] [, recombinantFollowingMode := string])`

Match a value in a configured lineage index. Optionally include its descendants.

pangoLineage.lineage('B.1.1.7', includeSublineages := true)

`phyloDescendantOf(column, node)`

Test whether a value descends from a node in a configured phylogenetic tree.

usherTree.phyloDescendantOf('NODE_0000072')

Sequence functions

●

Note

Every sequence predicate requires a sequence name. Positions are 1-based. Nucleotide and amino-acid functions have parallel forms where shown.

`nucleotideEquals(position := n, symbol := s, sequenceName := name)`

Test the symbol at a nucleotide reference position. Use . to represent the reference symbol. aminoAcidEquals is the amino-acid form.

nucleotideEquals(position := 23403, symbol := 'G', sequenceName := 'main')
aminoAcidEquals(position := 501, symbol := 'Y', sequenceName := 'S')

`hasMutation(position := n, sequenceName := name) / hasAAMutation(...)`

Test whether a position differs from the reference and is not an unknown symbol.

hasMutation(position := 23403, sequenceName := 'main')

`insertionContains(position := n, value := regex, sequenceName := name)`

Test whether an insertion after a reference position matches an RE2 expression. aminoAcidInsertionContains is the amino-acid form.

insertionContains(position := 22204, value := 'A.*G', sequenceName := 'main')

`maybe(child) / exact(child)`

Relax a child sequence expression to admit ambiguity, or require an exact match.

maybe(nucleotideEquals(position := 122, symbol := 'A', sequenceName := 'main'))

`nOf(count, {children} [, matchExactly := bool])`

Test whether at least count child predicates match, or exactly count when matchExactly is true.

nOf(2, {
nucleotideEquals(position := 241, symbol := 'T', sequenceName := 'main'),
nucleotideEquals(position := 3037, symbol := 'T', sequenceName := 'main'),
nucleotideEquals(position := 23403, symbol := 'G', sequenceName := 'main')
})

`nucleotideMutationProfile(distance := n, ..., sequenceName := name)`

Test whether a sequence is within a conservative-difference distance of a profile. Define the profile with exactly one of querySequence, sequenceId, or mutations. aminoAcidMutationProfile is the amino-acid form.

nucleotideMutationProfile(
distance := 3,
sequenceName := 'main',
mutations := {
  {position := 241, symbol := 'T'},
  {position := 23403, symbol := 'G'}
}
)