Is there a way to get a list of column headers available for use with --columns? #34

Activity

1. thanhleviet

   closed this as completedin #42on Aug 5, 2026
2. thanhleviet commented on Aug 5, 2026

   

   thanhleviet

   on Aug 5, 2026

   Collaborator

   More actions

   Yes - as of v0.20.0 there is now atb columns:

   $ atb columns
   Columns accepted by atb query --columns.
   
   assembly
       sample_accession    BioSample accession identifying the sample
       run_accession       ENA run accession the assembly was built from
       ...
   
   sylph
     * Adjusted_ANI         Nucleotide identity to the species reference, coverage-adjusted
     * Taxonomic_abundance  Percentage of the sample's cells estimated to be the species
     * Sequence_abundance   Percentage of the sample's reads assigned to the species
     * Median_cov           Median k-mer coverage of the species reference
   
   mlst
       mlst_scheme   MLST scheme applied, - when the species has none
       mlst_st       Sequence type assigned by the scheme
       ...
   
   40 columns. * marks one the SQLite index cannot answer: asking for it
   sends the query to the parquet files, which is slower.
   

   It groups the 40 columns by the table each comes from and marks with * the ones the SQLite index cannot answer - asking for one of those sends the query to the parquet files, which is slower and needs that file downloaded. The command reads no data, so it works before you have fetched anything.

   For scripting:

   atb columns --format tsv | cut -f1 | tail -n +2   # names only
   atb columns --format json                          # name, source, in_index, description

   The same list is on the docs site: https://allthebacteria.github.io/atb-cli/reference/columns/. It is generated from the registry the CLI validates against, so it cannot fall behind.

   Two related changes came out of putting this together.

   A typo is now an error rather than a blank column. Previously an unrecognised name produced an empty column and exit status 0, which is the failure mode this issue makes hard to notice:

   $ atb query --species "Escherichia coli" --columns sample_accession,N5O
   Error: unknown column "N5O" - did you mean "N50" or "N90"? Run 'atb columns' to list all
   $ echo $?
   1
   

   This is checked before the index is opened, and names in a TOML filter file are checked too. It is a breaking change if you have a script passing a name that is not a column - it will now fail where it used to quietly return nothing.

   Nine columns that were listed as available never returned data. The four sylph columns and the five mlst_* columns were read from their parquet files but never joined onto the result, so any query that could not be answered from the SQLite index returned them empty. Fixed:

   $ atb query --species "Escherichia coli" --limit 3 --columns sample_accession,mlst_st,mean_length
   sample_accession  mlst_st  mean_length
   SAMN40589622      14141    18645.92
   SAMN41155940      152      8233.3
   SAMN41388190      152      8258.6
   

   Released in v0.20.0 (PR #42). Thanks for raising it - the question turned up more than it looked like it would.