Why sqlmodel_update method don't ignore the None fields automatically?

[lucasmsoares96]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the SQLModel documentation, with the integrated search.
• I already searched in Google "How to X in SQLModel" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to SQLModel but to Pydantic.
• I already checked if it is not related to SQLModel but to SQLAlchemy.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from fastapi import FastAPI, HTTPException, Query
from sqlmodel import Field, Session, SQLModel, create_engine, select


class HeroBase(SQLModel):
    name: str = Field(index=True)
    secret_name: str
    age: int | None = Field(default=None, index=True)


class Hero(HeroBase, table=True):
    id: int | None = Field(default=None, primary_key=True)


class HeroCreate(HeroBase):
    pass


class HeroPublic(HeroBase):
    id: int


class HeroUpdate(SQLModel):
    name: str | None = None
    secret_name: str | None = None
    age: int | None = None


sqlite_file_name = "database.db"
sqlite_url = f"sqlite:///{sqlite_file_name}"

connect_args = {"check_same_thread": False}
engine = create_engine(sqlite_url, echo=True, connect_args=connect_args)


def create_db_and_tables():
    SQLModel.metadata.create_all(engine)


app = FastAPI()


@app.on_event("startup")
def on_startup():
    create_db_and_tables()


@app.post("/heroes/", response_model=HeroPublic)
def create_hero(hero: HeroCreate):
    with Session(engine) as session:
        db_hero = Hero.model_validate(hero)
        session.add(db_hero)
        session.commit()
        session.refresh(db_hero)
        return db_hero


@app.get("/heroes/", response_model=list[HeroPublic])
def read_heroes(offset: int = 0, limit: int = Query(default=100, le=100)):
    with Session(engine) as session:
        heroes = session.exec(select(Hero).offset(offset).limit(limit)).all()
        return heroes


@app.get("/heroes/{hero_id}", response_model=HeroPublic)
def read_hero(hero_id: int):
    with Session(engine) as session:
        hero = session.get(Hero, hero_id)
        if not hero:
            raise HTTPException(status_code=404, detail="Hero not found")
        return hero


@app.patch("/heroes/{hero_id}", response_model=HeroPublic)
def update_hero(hero_id: int, hero: HeroUpdate):
    with Session(engine) as session:
        db_hero = session.get(Hero, hero_id)
        if not db_hero:
            raise HTTPException(status_code=404, detail="Hero not found")
        hero_data = hero.model_dump(exclude_unset=True)   # <<< the hero_data variable is not checked by type checker.
        db_hero.sqlmodel_update(hero_data)
        session.add(db_hero)
        session.commit()
        session.refresh(db_hero)
        return db_hero

Description

To use the db_hero.sqlmodel_update method when a field has a None value, it is currently necessary to convert the typed BaseModel object into an untyped dictionary before updating it:

hero_data = hero.model_dump(exclude_unset=True)

However, converting the model to a dictionary removes static analysis and autocompletion. The codebase would be more concise and safer if the sqlmodel_update method could automatically ignore None fields.

Operating System

Linux

Operating System Details

OS: Ubuntu 24.04.3 LTS x86_64
Host: 550XDA P23CFB
Kernel: 6.14.0-37-generic
Shell: zsh 5.9
Resolution: 1920x1080
DE: GNOME 46.0
CPU: 11th Gen Intel i7-1165G7 (8) @ 4.700GHz
GPU: Intel TigerLake-LP GT2 [Iris Xe Graphics]
Memory: 10625MiB / 15716MiB

SQLModel Version

0.0.27

Python Version

3.12.3

Additional Context

No response

[MentalOfCrow]

sqlmodel_update() should not ignore None automatically because, for a PATCH request, these inputs have different meanings:

{}

means “do not change age”, while:

{"age": null}

means “explicitly clear age in the database”.

exclude_unset=True preserves exactly that three-state behavior:

HeroUpdate()                       # -> {}
HeroUpdate(age=None)               # -> {"age": None}
HeroUpdate(age=42)                 # -> {"age": 42}

hero_data = hero.model_dump(exclude_unset=True)
db_hero.sqlmodel_update(hero_data)

This is intentional and is documented in SQLModel's Update Data with FastAPI section: an explicitly supplied None lets a client remove an existing nullable value.

If your API contract says that null must also mean “ignore this field”, opt into that behavior at the serialization boundary:

hero_data = hero.model_dump(
    exclude_unset=True,
    exclude_none=True,
)
db_hero.sqlmodel_update(hero_data)

It should not be the global default because that version makes it impossible for the client to clear age.

Passing the model directly is supported by the method's type signature:

db_hero.sqlmodel_update(hero)

but it is not equivalent for PATCH. The current implementation iterates every field of a model argument, including fields that were omitted and received their default None, so it would overwrite stored values. The dumped dictionary is what carries the runtime set of fields actually sent by the client.

Regarding static checking: a partial update is intrinsically dynamic — its keys are determined by the JSON request at runtime — so a type checker cannot prove the exact dictionary shape after exclude_unset. The original HeroUpdate is still fully validated and typed before the dump. If you need static checking for every assignment, use explicit field handling:

def apply_hero_patch(target: Hero, patch: HeroUpdate) -> None:
    if "name" in patch.model_fields_set and patch.name is not None:
        target.name = patch.name

    if "secret_name" in patch.model_fields_set and patch.secret_name is not None:
        target.secret_name = patch.secret_name

    if "age" in patch.model_fields_set:
        # None is intentionally allowed here to clear the database value.
        target.age = patch.age

That is more verbose, but it retains autocomplete and makes each field's None policy explicit. For most CRUD endpoints, the documented model_dump(exclude_unset=True) + sqlmodel_update() pattern is the better trade-off.

If this clarifies why None is preserved and which option matches your API contract, please mark it as the accepted answer so future readers do not accidentally break PATCH semantics.