Typechecking Column Comparisons with select

[travis-cook-sfdc]

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

"""Minimal repro for ty invalid-argument-type with SQLModel column comparisons."""

from sqlmodel import Field, Integer, SQLModel, func


class Issue(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    status: int


# ty reports: Expected `SQLCoreOperations[Any] | ...`, found `bool`
expr = func.cast(Issue.status == 1, Integer)

Description

When using a type checker (tested with ty), column comparisons on SQLModel table models are inferred as bool instead of ColumnElement. This causes false positive type errors when passing comparisons to SQLAlchemy functions like func.cast().

Expected Behavior

Issue.status == 1 should be typed as ColumnElement[bool], not bool.

Root Cause

SQLModel uses plain Python annotations (status: int) and replaces them with Column objects at runtime via the metaclass:

# main.py lines 550-556
if config_table is True:
    for k, v in get_model_fields(new_cls).items():
        col = get_column_from_field(v)
        setattr(new_cls, k, col)

Type checkers see the annotation int and correctly infer int.eq() returns bool. They can't see the runtime transformation.

Comparison with SQLAlchemy 2.0

SQLAlchemy 2.0 solves this with Mapped[T] annotations:

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

class Issue(Base):
  status: Mapped[int] = mapped_column()

# Type checkers understand Issue.status is InstrumentedAttribute[int]
# which has __eq__ -> ColumnElement[bool]

This passes type checking because SQLAlchemy's stubs properly type Mapped descriptors.

Workaround

For now, I can workaround with a type: ignore, but it would be cool if sqlmodel could type this correctly

Operating System

macOS

Operating System Details

No response

SQLModel Version

0.0.31

Python Version

3.13.7

Additional Context

No response

[travis-cook-sfdc]

Ugh - I was searching in ways that was specific to __eq__ and didn't see this: #1419 (comment)

Looks like this can be resolved by wrapping the column with col.

Would be helpful if this was documented

[YuriiMotov]

Looks like this can be resolved by wrapping the column with col.

Would be helpful if this was documented

This is actually already documented here: https://sqlmodel.tiangolo.com/tutorial/where/#type-annotations-and-errors

Giving that not all people read tutorial step by step we should probably think about moving this to a separate section