【画像付き】SQLAlchemyのfirst, one, scalarの違い

2020年1月20日2020年3月21日

SQLAlchemyにはall()をはじめとしてたくさんのクエリーがあります。その中でもfirst, one, scalarは動作が似ており、きちんと区別して使えている人は少ないです。

そこでこの記事では各クエリーの違いを解説します。

記事を作成するにあたり以下のSQLAlchemyの公式サイトを参考にしました。
Query API — SQLAlchemy 1.3 Documentation

Table of Contents(目次)

1. first
- 1.1. 使い所
2. one
- 2.1. 使い所
3. scalar
- 3.1. 使い所
4. 全体まとめ
5. 参考サイト

first

クエリによって取得できる全ての行のうち先頭の行だけを取得します。もしクエリによって一つも行が取得できなかった場合にはエラーは発生せず、Noneが返されます。

クエリが2つ以上のテーブルを結合するものであれば、結合された状態の行が一つだけ返ってきます。

使い所

order_by句を使ってあるカラムの並びによって並び替えた後に先頭の行を取得したい時に使えます。例えば、レコードの作成順番(created_at)での並び替えと同時にfirstを使うことで、最も最近作成されたレコードのみを取得することができます。

one

一行だけ取得するクエリです。

もしクエリによって一つも行が取得できなかった場合には”sqlalchemy.orm.exc.NoResultFound”エラーが発生し、複数行返された時には”sqlalchemy.orm.exc.MultipleResultsFound”エラーが発生します。

使い所

必ず取得対象が一つしか存在しないよう、WHERE句(SQLAlchemyで言うfilter)で絞りこむことと同時に使うことが多いです。

また、一つも行を取得できなかったときや複数行取得した時にエラーを発生させる性質から単体テストの作成時にもよく使われます。

scalar

クエリによって最初に取得できた行(first()の結果)の最初の要素を返します。複数行の情報が取得できてしまったらoneと同じく”MultipleResultsFound”エラーが発生します。

少し分かりにくいので具体例を公式サイトから抜粋します。

>>> session.query(Item).scalar()
<Item>
>>> session.query(Item.id).scalar()
1
>>> session.query(Item.id).filter(Item.id < 0).scalar()
None
>>> session.query(Item.id, Item.name).scalar()
1

特に注目して欲しいのが最後の例です。ItemテーブルのidとItemテーブルのnameを指定していますが、最初に指定された要素はidのため、1というidの値のみが返されています。

これは行として情報を取得するone, firstとの大きな違いです。

ついでにoneと比較してみましょう。

# idカラムとnameカラムを持つUserテーブル作成してから以下の作業を行っています。

user_id = session.query(User.id).one()
print(user_id)  # 出力結果：(1,)
print(type(user_id))  # 出力結果：<class 'sqlalchemy.util._collections.result'>

user_id = session.query(User.id).scalar()
print(user_id)  # 出力結果：1
print(type(user_id))  # 出力結果：<class 'int'>


user = session.query(User.id, User.name).one()
print(user)  # 出力結果：(1, 'ed')
print(type(user))  # 出力結果：<class 'sqlalchemy.util._collections.result'>

user = session.query(User.id, User.name).scalar()
print(user)  # 出力結果：1
print(type(user))  # 出力結果：<class 'int'>