Skip to main content

Improved table_from_file feature in ehrQL

09 January 2026

We have improved the table_from_file feature in ehrQL.

table_from_file allows you to define a table from a tabular (csv, csv.gz or arrow) file containing patient data, and use that table in your dataset definition as if it was a standard ehrQL table. This allows you to include data extracted by other actions in your queries, just as if they were part of an ordinary table in the database. This feature is often used in case-control studies.

For example, if a previous action extracted some matched control patients in a file outputs/matched.arrow, you can include this with the following code:

from ehrql import table_from_file

matched_controls = table_from_file(
    "outputs/matched.arrow",
    columns={
        "age": int,
        "sex": str,
    }
)

You can then use the table as you would any other ehrQL table, e.g. the following code would allow us to extract further event data for the matched controls only:

...
dataset = create_dataset()
dataset.define_population(matched_controls.exists_for_patient())

dataset.event_code = clinical_events.where(...).snomedct_code
...

Note that the table_from_file feature has been available for some time. If your study is using the old @table_from_file decorator syntax, it will continue to work. However, we would recommended updating your code to use the new, simpler syntax.