ehrQL v1 was released on Friday 8th December 2023.

It contains a small number of breaking changes from v0.

Upgrading from v0

• In project.yaml, replace either ehrql:v0 or databuilder:v0 with ehrql:v1
• From the command line, run opensafely pull ehrql

Breaking changes

Removal of databuilder imports

Some projects have been using ehrQL from when the project was called "Databuilder".

Update lines in your dataset definition that use databuilder imports to ehrql.
For example, change:

from databuilder import create_dataset

to:

from ehrql import create_dataset

Movement of tables out of the "beta" namespace

Tables have been moved out of the "beta" namespace.

Update lines in your dataset definition that import tables from the beta namespace.
For example, change:

from ehrql.tables.beta.core import patients

to:

from ehrql.tables.core import patients

Change to default size of dummy dataset

By default, a dummy dataset will now contain data for 10 patients.
This means when you generate a dummy dataset from the console,
you get a tractable amount of output.

This can be changed per dataset with:

dataset.configure_dummy_data(population_size=1000)

Renaming of language features

For consistency, a few small language features have been renamed.

• if_null_then has been renamed to when_null_then.
• The default argument to case() has been renamed to otherwise.
• Dataset.configure_dummy_dataset has been renamed to Dataset.configure_dummy_data.

Deprecation of tpp.hospital_admissions table

The tpp.hospital_admissions table duplicated the tpp.apcs table.
Additionally, its .primary_diagnoses field should have been called .primary_diagnosis.

Update lines in your dataset definition that use tpp.hospital_admissions to use tpp.apcs
For example, change:

from ehrql.tables.beta.core import hospital_admissions

to:

from ehrql.tables.core import apcs

Change to behaviour when household information is missing

When querying tpp.household_memberships_2020,
None is now returned instead of zero if information for a household is missing.

Getting help

If you are stuck or unsure how to upgrade, ask your co-pilot or seek help in Slack.