feat(lapis): add sequence position fields syntax to aggregated endpoint

[fhennig]

Summary

• Adds Name[N] syntax (e.g. S[501]) to the fields parameter of /aggregated, allowing users to request specific sequence positions as group-by columns
• Shorthand [N] is supported for single-segmented genomes and resolves to the single nucleotide sequence
• Sequence names are validated case-insensitively against both genes and nucleotide segments from the reference genome
• Generates a .map({"S[501]":="S".at(501)}) SaneQL step before .groupBy(...) when position fields are present — the user-facing name is used directly as the SaneQL alias, so no post-processing is needed
• Response column keys mirror the input exactly: S[501] in → S[501] out, [501] in → [501] out

Example

POST /sample/aggregated
{"fields": ["country", "S[501]"]}

Generates:

default.filter(true).map({"S[501]":="S".at(501)}).groupBy({"count":=count()}, {"country", "S[501]"})

Test plan

• Unit tests for Name[N] parsing in SequenceFiltersRequestWithFieldsTest
• Error cases: unknown sequence name, position ≤ 0, shorthand on multi-segmented genome
• SaneQL generation tests in SiloQueryToSaneQlTest for position-only and mixed fields
• Full test suite passes

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lapis	Ready	Preview, Comment	Jul 15, 2026 12:24pm

[Copilot]

Pull request overview

Adds support for requesting specific sequence positions (e.g. S[501], and [501] for single-segment genomes) as group-by columns in the /aggregated endpoint by parsing them from the fields request parameter and generating the appropriate SaneQL .map(...).groupBy(...) pipeline.

Changes:

• Introduces RequestField with a new SequencePositionField type and updates request parsing to recognize Name[N] / [N] syntax.
• Extends aggregated SaneQL generation to add a .map(...) step that computes requested positions and includes them in .groupBy(...).
• Updates SaneQL AST rendering/tests to quote assignment keys (e.g. {"count":=count()}) and adds unit coverage for new parsing/generation.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
lapis/src/main/kotlin/org/genspectrum/lapis/request/Field.kt	Adds RequestField + SequencePositionField, and extends field conversion to parse/validate position syntax against the reference genome schema.
lapis/src/main/kotlin/org/genspectrum/lapis/request/SequenceFiltersRequestWithFields.kt	Updates request model to store fields as List<RequestField> and keeps deserialization via the field converter.
lapis/src/main/kotlin/org/genspectrum/lapis/silo/SiloQuery.kt	Adds sequencePositionFields to aggregated actions and emits .map(...) before .groupBy(...) when present.
lapis/src/main/kotlin/org/genspectrum/lapis/silo/SaneQlAst.kt	Changes assignment rendering to quote/escape keys (e.g. "name":=value) to align with SaneQL expectations and harden output.
lapis/src/main/kotlin/org/genspectrum/lapis/model/SiloQueryModel.kt	Splits RequestField values into metadata fields vs. sequence-position fields for aggregated query construction.
lapis/src/main/kotlin/org/genspectrum/lapis/controller/LapisController.kt	Ensures response headers/field lists use outputColumnName (aggregated) and filters non-metadata fields out of details fields handling.
lapis/src/main/kotlin/org/genspectrum/lapis/controller/ControllerDescriptions.kt	Updates aggregated endpoint parameter description to document the new position-field syntax.
lapis/src/main/kotlin/org/genspectrum/lapis/request/PhyloTreeSequenceFiltersRequest.kt	Adjusts phylo-tree parsing to work with the generalized FieldConverter<RequestField> while enforcing a Field result.
lapis/src/test/kotlin/org/genspectrum/lapis/request/SequenceFiltersRequestWithFieldsTest.kt	Adds unit tests for parsing valid/invalid Name[N] / [N] field forms.
lapis/src/test/kotlin/org/genspectrum/lapis/silo/SiloQueryToSaneQlTest.kt	Updates expected SaneQL strings and adds coverage for aggregated SaneQL with sequence position fields.
lapis/src/test/kotlin/org/genspectrum/lapis/silo/SaneQlAstTest.kt	Updates AST rendering assertions to match quoted assignment output.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fhennig]

Ok, something weird with the test? But still reviewable I think. I'll look into it.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.