本文へスキップ

SQLAlchemy 2.0のMappedとmapped_columnによるモデルの型付け

sqlalchemy-mapped-column-typing

Mappedとmapped_columnとは

SQLAlchemy 2.0のMappedとは、ORMのモデルの属性の型を型チェッカーに通知するためのジェネリッククラスである。
Mapped[str]の注釈は、インスタンスの属性の型がstrであることを意味する。
mapped_column()は、その属性に対応するテーブルの列を定義する関数で、列の型とNOT NULLの有無をMapped[...]の注釈から決定する。

  • mypyプラグインなしの環境では、1.x形式のname = Column(String)の属性の型はColumn[str]と判定され、strの値の代入が型エラーになる
    • 1.xではSQLAlchemyのmypyプラグインがこの型を補正していた
    • プラグインは2.0で非推奨になり、pyrightには対応していない
  • name: Mapped[str] = mapped_column()の形式では、属性の型と異なる値の代入を実行前の型チェックで検出できる
    • user.nameの型はstrで、intの代入は型エラーになる
    • select(User.id, User.name)の結果の行の型もRow[tuple[int, str]]と推論される
    • Mapped[str]の属性へのNoneの代入も、実行前の型チェックで検出できる
    • クラスから参照するUser.nameは、検索条件の構築用の列の式になる
  • 列のNULLとNOT NULLは、注釈のstr | Noneの有無とnullableの指定に依存する
    • 主キー以外でnullableの指定がない列の例では、str | Noneの列はNULLを許容し、strの列はNOT NULLになる
    • nullableを指定した列のNULLの可否は、注釈ではなくその指定に従う
    • nullableが無指定の1.x形式のColumn(String)をMapped[str]へ移行すると、モデルの列の定義はNULL許容からNOT NULLになる
  • 型チェッカーで検出されない誤りもある
    • Mapped[...]とmapped_column()の列の型の不一致は検出されない
    • 標準のコンストラクタでは引数名の誤りは検出されない

前提となるSQLAlchemyのモデルの用語

宣言的マッピング

宣言的マッピングはDeclarativeBaseを継承したクラスの属性の定義から、テーブルの定義と、クラスとテーブルの対応を生成する方式である。
以降のコード例のBaseはこの方式の基底クラスで、UserとAddressは説明のために定義したモデルである。

記述子

記述子(descriptor)は、__get__や__set__を定義したクラスのインスタンスで、クラスの属性に設定すると、属性の参照と代入の処理を置換する。
SQLAlchemyのモデルの属性は記述子で、クラスからの参照の結果は列の式(User.name == "Ada"のような条件の構築用のオブジェクト)、インスタンスからの参照の結果は列の値である。
Mappedは、この2種類の型を型チェッカーに通知するための型である。

Columnで定義した属性の型はColumnになる

以降のコード例は1つのファイルの抜粋で、2つ目以降のコード例では最初の例のimportとBaseの定義を再利用する。
DBへの保存を伴う例はcreate_engine("sqlite://")とBase.metadata.create_all(engine)でテーブルを作成してから実行する。

型情報がSQLAlchemyの同梱分に限られる環境で1.x形式のColumnでモデルを定義すると、型チェッカーはインスタンスの属性の型をColumn[str]と判定する。

from typing import reveal_type

from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)


user = User(name="Ada")
reveal_type(user.name)
# mypy: Revealed type is "sqlalchemy.sql.schema.Column[str]"
# pyright: Type of "user.name" is "Column[str]"
user.name = "Grace"
# mypy
# error: Incompatible types in assignment (expression has type "str", variable has type "Column[str]")  [assignment]

実行時のuser.nameの値は文字列の"Ada"であり、代入も問題なく動作する。
型チェッカーの判定と実行時の値が一致しないのは、Column(String)の戻り値の型がColumn[str]で、型チェッカーはクラスの属性への代入をそのままインスタンスの属性の型と判定するからである。
1.4まではこの型の補正はSQLAlchemyの mypyプラグイン の役割だった。
プラグインは2.0で非推奨になり、2.1で削除される予定で、mypy 1.11以降では正常に動作しない可能性がある。
pyrightはmypyのプラグインに非対応なので、1.x形式のnameに対するpyrightの判定はColumn[str]のままである。

Mappedの注釈でインスタンスとクラスの型を区別する

以降の例の前提は型情報がSQLAlchemy 2.0の同梱分に限られる環境である。
2.0の型付けが機能するには、sqlalchemy-stubsやsqlalchemy2-stubsなどのスタブのパッケージの 削除が必要である。
型チェッカーの解決順 では、スタブのパッケージがパッケージ同梱の型情報より優先される。
1.x向けのスタブがインストールされたままなら、2.0のMappedの定義は型チェッカーの参照の対象外になる。
pip show sqlalchemy-stubs sqlalchemy2-stubsで有無を確認し、mypyの設定のpluginsからsqlalchemy.ext.mypy.pluginも削除する。

2.0の形式では属性の注釈にMapped[...]を指定し、値にmapped_column()を設定する。

from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(30))


user = User(name="Ada")
reveal_type(user.name)
# mypy: Revealed type is "str"
reveal_type(User.name)
# mypy: Revealed type is "sqlalchemy.orm.attributes.InstrumentedAttribute[str]"
user.name = 1
# mypy
# error: Incompatible types in assignment (expression has type "int", variable has type "SQLCoreOperations[str] | str")  [assignment]

インスタンスからの参照はstr、クラスからの参照はInstrumentedAttribute[str]になり、pyrightの表示も一致する。
intの代入は、mypyとpyrightの両方がエラーにする。
1.x形式でエラーになった文字列の代入はエラーにならず、型と異なる値の代入だけが型チェッカーに検出される。
この区別はMappedの型スタブの__get__のオーバーロードで実現されている。

# sqlalchemy/orm/base.py の型スタブからの抜粋
class Mapped(...):
    @overload
    def __get__(self, instance: None, owner: Any) -> InstrumentedAttribute[_T_co]: ...
    @overload
    def __get__(self, instance: object, owner: Any) -> _T_co: ...
    def __set__(self, instance: Any, value: SQLCoreOperations[_T_co] | _T_co) -> None: ...

インスタンスがNoneの呼び出し、つまりクラスからの参照にはInstrumentedAttribute、インスタンスからの参照には型引数の_T_coが対応する。
SQLAlchemyのコードを解釈する専用の処理は不要で、判定は通常の記述子の型の規則に従うので、mypyとpyrightの結果が一致する。
mapped_column()の戻り値の型はMappedColumn[Any]で、注釈のMapped[str]への代入で型エラーにならない。

移行の途中でMappedの注釈にColumnを設定した場合

Mapped[int]の注釈の値にmapped_column()ではなくColumnを設定すると、型チェッカーはエラーにする。

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = Column(Integer, primary_key=True)
# mypy
# error: Incompatible types in assignment (expression has type "Column[int]", variable has type "Mapped[int]")  [assignment]

Mappedの注釈にColumnを設定しても、実行時には正常に動作する。
この型エラーは1.x形式からの移行時に注釈を先行して追加すると発生する。
値をmapped_column()に置換すると、Columnの引数をそのまま指定できる。

select()の結果も型が推論される

クラスの属性の型が列の型引数を保持するので、select()に指定した列から結果の行の型が推論される。

from sqlalchemy import create_engine, select
from sqlalchemy.orm import Session

engine = create_engine("sqlite://")
Base.metadata.create_all(engine)
with Session(engine) as session:
    session.add(User(id=1, name="Ada"))
    session.commit()
    statement = select(User.id, User.name)
    # mypy: Revealed type is "sqlalchemy.sql.selectable.Select[tuple[int, str]]"
    rows = session.execute(statement).all()
    # mypy: Revealed type is "typing.Sequence[sqlalchemy.engine.row.Row[tuple[int, str]]]"
    users = session.scalars(select(User)).all()
    # mypy: Revealed type is "typing.Sequence[User]"
    print(rows[0].name.upper())  # ADA

注釈のOptionalと列のNULLの対応

mapped_column()は、注釈のMapped[...]から列の型とNULLの可否を決定する。

注釈からのNULLの可否の推論

nullableとprimary_keyの指定がない列のNULLの可否は、注釈のOptional[...]の有無に依存する。
str | NoneはOptional[str]と同等である。
str | Noneの記法はPython 3.10以降で、それより前のバージョンの記法はOptional[str]である。
mapped_column()の値の設定自体も省略でき、値のないname: Mapped[str]の注釈も列になる。

from sqlalchemy.schema import CreateTable


class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    nickname: Mapped[str | None]


print(CreateTable(Base.metadata.tables["users"]).compile(engine))
CREATE TABLE users (
	id INTEGER NOT NULL, 
	name VARCHAR NOT NULL, 
	nickname VARCHAR, 
	PRIMARY KEY (id)
)

Mapped[str]のnameはNOT NULLの列である。
Mapped[str | None]のnicknameはNULLを許容する。

1.x形式からの移行時のNULLの変化

1.x形式のname = Column(String)はNULLを許容するので、Mapped[str]への書き換えはモデルの列の定義の変更になる。
既存のテーブルの列はNULLを許容したままで、create_all()も既存のテーブルを変更しない。
NULLを許容する既存の列の注釈はMapped[str | None]にし、NOT NULLへの変更はマイグレーションとして別に行う。
nameへのNoneの代入はmypyとpyrightが型エラーにし、型チェックを無視して実行すると、commit()の時点でIntegrityError: NOT NULL constraint failed: users.nameになる。

nullableの明示による上書き

mapped_column(nullable=...)の明示は、注釈より優先される。

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(nullable=True)  # VARCHAR(NULLを許容)
    nickname: Mapped[str | None] = mapped_column(nullable=False)  # VARCHAR NOT NULL

注釈と異なる指定の 用途の例 は、オブジェクトの作成中に限りPython上でNoneを許容し、データベースの列はNOT NULLにする場合である。
逆にMapped[str]の列をnullable=Trueにすると、データベースの値がNULLの行でも、型チェッカーの判定はstrのままである。

注釈の型と列の型の対応

列の型をmapped_column()に指定しない場合、列の型は注釈の型から推論される。
標準の対応は次のとおりである。

注釈の型 列の型
int Integer
str String
float Float
bool Boolean
datetime.datetime DateTime
decimal.Decimal Numeric
uuid.UUID Uuid
enum.Enumのサブクラス Enum

list[int]のように標準の対応にない注釈は、対応から列の型を決定できないので、対応を追加していなければクラスの定義の時点で例外になる。
次のRecordは説明用のモデルである。

class Record(Base):
    __tablename__ = "records"
    id: Mapped[int] = mapped_column(primary_key=True)
    values: Mapped[list[int]]
# mypy: Success: no issues found in 1 source file
# pyright: 0 errors, 0 warnings, 0 informations
# 実行時
# sqlalchemy.orm.exc.MappedAnnotationError: Could not locate SQLAlchemy Core type when resolving for Python type indicated by 'list[int]' inside the Mapped[] annotation for the 'values' attribute; the type object is not resolvable by the registry

型チェッカーはこの誤りを検出せず、モジュールのimportの時点で初めて例外になる。

String(30)のように長さや精度を指定する列は、mapped_column(String(30))で型を明示する。
1つの型の指定を複数の列で再利用する方法は、公式ドキュメント のtype_annotation_mapとAnnotatedの節にある。

型チェッカーが検出しない誤り

注釈とmapped_column()の列の型の不一致

Mapped[...]の型とmapped_column()に指定した列の型が矛盾していても、型チェッカーはエラーにしない。

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[int] = mapped_column(String(30))


with Session(engine) as session:
    session.add(User(id=1, name="Ada"))
    session.commit()
    value = session.scalars(select(User.name)).one()
    reveal_type(value)
    # mypy: Revealed type is "int"
    print(value, type(value).__name__)  # Ada str

型チェッカーはname列の値valueをintと判定するが、実行時の値は文字列の"Ada"である。
この不一致を検出できないのは、mapped_column()の戻り値が列の型の情報のないMappedColumn[Any]だからである。
列の型を明示する列では注釈の型と列の型の対応を目視かテストで確認する。

コンストラクタの引数名の誤り

DeclarativeBaseが生成するコンストラクタの型は、任意のキーワード引数を受理する。
型チェッカーは引数名の誤りを検出しない。
標準のコンストラクタの引数名がモデルの属性にない場合、実行時にTypeErrorになる。

User(nmae="x")
# mypy: Success: no issues found in 1 source file
# 実行時
# TypeError: 'nmae' is an invalid keyword argument for User

型チェッカーで引数名の誤りを検出する方法は2つある。
1つは引数に型の注釈がある__init__(def __init__(self, *, name: str) -> None)をモデルに定義する方法である。
もう1つはMappedAsDataclassの併用で、モデルはdataclassになり、生成されたコンストラクタの引数が型チェッカーに通知される。

from sqlalchemy.orm import MappedAsDataclass


class Base(MappedAsDataclass, DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(init=False, primary_key=True)
    name: Mapped[str]


User(nmae="x")
# mypy
# error: Unexpected keyword argument "nmae" for "User"  [call-arg]
# pyright
# error: Argument missing for parameter "name" (reportCallIssue)
# error: No parameter named "nmae" (reportCallIssue)

コンストラクタの引数にしない列にはinit=Falseを指定する。
自動採番のidがその例である。
引数を省略可能にするにはdefaultを指定する。
str | Noneの注釈だけでは引数は省略可能にならない。
注釈の役割は引数の値の型の指定で、生成される__init__の引数の省略の可否は、dataclassと同じく デフォルト値の有無に依存する。
dataclassになると、デフォルトの設定では__eq__と__repr__も生成され、インスタンスはハッシュ化できなくなる。
モデルを集合や辞書のキーにする既存のコードがあるなら、__init__の定義のほうが既存のコードへの影響が少ない。
型チェッカーがこのモデルを dataclassとして認識する のは、PEP 681 のdataclass_transformを解釈するからである。

relationshipの型

relationship()の属性もMapped[...]で注釈し、1対多の側はMapped[list["Address"]]、多対1の側はMapped["User"]にする。

from sqlalchemy import ForeignKey
from sqlalchemy.orm import relationship


class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    addresses: Mapped[list["Address"]] = relationship(back_populates="user")


class Address(Base):
    __tablename__ = "addresses"
    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
    user: Mapped["User"] = relationship(back_populates="addresses")

# reveal_type(user.addresses) -> list[Address]
# reveal_type(address.user) -> User

モデルを複数のファイルに分割したときの循環参照の回避は SQLAlchemyでMany to Manyのモデルを分割する で説明した。

この記事に出てくる用語

用語集の一覧へ

関連事例

  • データ分析支援

    事例:過去実績を提案に活用する分析の仕組み

    広告代理店との取り組みです。同社は過去実績の示唆を次の提案へ反映し、結果をどのように予測したか、その背景まで提案先のクライアントへ説明できるようになりました。KDOT は案ごとの見込みと判断材料を比較できる仕組みを業務アプリとして実装しました。さらに業務アプリの中核となる処理ロジックと機械学習モデルについて、特許手続きを担う弁理士が技術の新規性や工夫を検討するための資料を作成しました。その後この発明には特許が付与されました。

  • データ基盤構築 / 技術顧問(技術企業向け)

    事例:効果検証の分析処理基盤

    効果検証を提供する分析会社との取り組みです。同社は分析者の人数に比例してしか売上と利益を伸ばせない事業の形を、効果検証をプロダクトとして提供することで変革しようとしていました。手法とモデルは同社のまま、社内では開発できなかった、データと機械学習の重い推定を製品として動かす仕組みの開発を、開発支援会社の KDOT に任せました。推定を案件ごとの手作業ではなくシステムで実行できるようになったことで、同社は人数に比例しない形で売上と利益を伸ばすことを目指せるようになりました。

お問い合わせ・ご相談

システム開発、データ活用、プロダクトづくりのことならお気軽にご相談ください。要件が固まる前の整理や、お見積もりだけのご依頼も承ります。