ormar/docs/queries/select-columns.md

Selecting subset of columns

• fields(columns: Union[List, str, set, dict]) -> QuerySet
• exclude_fields(columns: Union[List, str, set, dict]) -> QuerySet

fields

fields(columns: Union[List, str, set, dict]) -> QuerySet

With fields() you can select subset of model columns to limit the data load.

!!!note Note that fields() and exclude_fields() works both for main models (on normal queries like get, all etc.) as well as select_related and prefetch_related models (with nested notation).

Given a sample data like following:

--8 < -- "../docs_src/queries/docs006.py"

You can select specified fields by passing a str, List[str], Set[str] or dict with nested definition.

To include related models use notation {related_name}__{column}[__{optional_next} etc.].

all_cars = await Car.objects.select_related('manufacturer').fields(['id', 'name', 'manufacturer__name']).all()
for car in all_cars:
    # excluded columns will yield None
    assert all(getattr(car, x) is None for x in ['year', 'gearbox_type', 'gears', 'aircon_type'])
    # included column on related models will be available, pk column is always included
    # even if you do not include it in fields list
    assert car.manufacturer.name == 'Toyota'
    # also in the nested related models - you cannot exclude pk - it's always auto added
    assert car.manufacturer.founded is None

fields() can be called several times, building up the columns to select.

If you include related models into select_related() call but you won't specify columns for those models in fields

• implies a list of all fields for those nested models.

all_cars = await Car.objects.select_related('manufacturer').fields('id').fields(
    ['name']).all()
# all fiels from company model are selected
assert all_cars[0].manufacturer.name == 'Toyota'
assert all_cars[0].manufacturer.founded == 1937

!!!warning Mandatory fields cannot be excluded as it will raise ValidationError, to exclude a field it has to be nullable.

You cannot exclude mandatory model columns - manufacturer__name in this example.

await Car.objects.select_related('manufacturer').fields(
    ['id', 'name', 'manufacturer__founded']).all()
# will raise pydantic ValidationError as company.name is required

!!!tip Pk column cannot be excluded - it's always auto added even if not explicitly included.

You can also pass fields to include as dictionary or set.

To mark a field as included in a dictionary use it's name as key and ellipsis as value.

To traverse nested models use nested dictionaries.

To include fields at last level instead of nested dictionary a set can be used.

To include whole nested model specify model related field name and ellipsis.

Below you can see examples that are equivalent:

--8 < -- "../docs_src/queries/docs009.py"

!!!note All methods that do not return the rows explicitly returns a QueySet instance so you can chain them together

So operations like `filter()`, `select_related()`, `limit()` and `offset()` etc. can be chained.

Something like `Track.object.select_related("album").filter(album__name="Malibu").offset(1).limit(1).all()`

exclude_fields

exclude_fields(columns: Union[List, str, set, dict]) -> QuerySet

With exclude_fields() you can select subset of model columns that will be excluded to limit the data load.

It's the opposite of fields() method so check documentation above to see what options are available.

Especially check above how you can pass also nested dictionaries and sets as a mask to exclude fields from whole hierarchy.

!!!note Note that fields() and exclude_fields() works both for main models (on normal queries like get, all etc.) as well as select_related and prefetch_related models (with nested notation).

Below you can find few simple examples:

--8<-- "../docs_src/queries/docs008.py"

!!!warning Mandatory fields cannot be excluded as it will raise ValidationError, to exclude a field it has to be nullable.

!!!tip Pk column cannot be excluded - it's always auto added even if explicitly excluded.

!!!note All methods that do not return the rows explicitly returns a QueySet instance so you can chain them together

So operations like `filter()`, `select_related()`, `limit()` and `offset()` etc. can be chained.

Something like `Track.object.select_related("album").filter(album__name="Malibu").offset(1).limit(1).all()`