PyMongo Async への移行

Overview

PyMongo Async API は、 PyMongoと Motorライブラリの統合です。このガイドでは、アプリケーションをPyMongoまたはMotorからPyMongo Async APIに移行するために行う必要がある変更を識別できます。

意向

PyMongo Async API は、 Motorライブラリの置き換えとして設計されています。Motor はTornado をサポートするために作成され、asyncio のサポートはその後追加されました。このため、 Motor はasyncio と Tornado の完全なサポートを提供しますが、ネットワーク操作を実行するにはスレッドプールに依存します。場合によっては、 Motorライブラリを使用するとパフォーマンスの低下につながる恐れがあります。この問題に対処するために、 PyMongo Async API はasyncio サポートをPyMongoに直接実装します。ほとんどの場合、 PyMongo Async API はMotorよりもパフォーマンスが向上します。パフォーマンスベンチマークを確認するには、パフォーマンスベンチマークセクションを参照してください。

同期と非同期

PyMongo Async APIに移行するか、同期PyMongoを引き続き使用するかを決定するには、このセクションの情報を検討してください。

次の基準がアプリケーションまたはユースケースに適用される場合は、同期PyMongoが推奨されます。

アプリケーションの実行が単純であるか、コード内で非同期呼び出しを使用しないようにしたい場合
アプリケーションがシリアル化されたワークロードまたは非常に高速な応答時間を持つワークロードに依存している
アプリケーションをデバッグするときに、同期ロジックの簡素化を好みます

次の基準がアプリケーションまたはユースケースに適用される場合は、 PyMongo Async APIへの移行を検討してください。

アプリケーションが大規模で高度に同時実行されたワークロード（数千の同時操作数）を実装している
アプリケーションが、応答を待つやデータを書き込むワークロードに依存している
アプリケーションが、FastAPI などの他の非同期ライブラリやフレームワークに依存している

パフォーマンスベンチマーク

次の表は、 PyMongo Async APIとMotorライブラリを使用して実行されたさまざまなタスクのパフォーマンスベンチマークを示しています。各タスクは、それぞれ 1000 ドキュメントの 10 反復を使用して実行されました。ほとんどの場合、 PyMongo Async API はMotorよりもパフォーマンスが向上します。

操作	Motorパフォーマンス	PyMongo Async パフォーマンス
`TestFindManyAndEmptyCursor`	74.074 MB/s	112.490 MB/s
`TestFindManyAndEmptyCursor80Tasks`	37.181 MB/s	89.521 MB/s
`TestFindManyAndEmptyCursor8Tasks`	63.145 MB/s	97.165 MB/s
`TestFindOneByID`	3.121 MB/s	2.922 MB/s
`TestFindOneByID80Tasks`	3.789 MB/s	4.071 MB/s
`TestFindOneByID8Tasks`	3.697 MB/s	3.445 MB/s
`TestFindOneByIDUnlimitedTasks`	3.866 MB/s	4.171 MB/s
`TestGridFsDownload`	573.770 MB/s	603.578 MB/s
`TestGridFsUpload`	430.870 MB/s	444.445 MB/s
`TestLargeDocBulkInsert`	82.631 MB/s	102.105 MB/s
`TestLargeDocClientBulkInsert`	75.057 MB/s	90.345 MB/s
`TestLargeDocCollectionBulkInsert`	85.810 MB/s	101.838 MB/s
`TestLargeDocInsertOne`	84.832 MB/s	101.934 MB/s
`TestLargeDocInsertOneUnlimitedTasks`	120.389 MB/s	163.553 MB/s
`TestRunCommand`	0.036 MB/s	0.034 MB/s
`TestRunCommand80Tasks`	0.042 MB/s	0.043 MB/s
`TestRunCommand8Tasks`	0.039 MB/s	0.041 MB/s
`TestRunCommandUnlimitedTasks`	0.043 MB/s	0.042 MB/s
`TestSmallDocBulkInsert`	35.071 MB/s	38.213 MB/s
`TestSmallDocBulkMixedOps`	0.729 MB/s	0.446 MB/s
`TestSmallDocClientBulkInsert`	25.032 MB/s	25.727 MB/s
`TestSmallDocClientBulkMixedOps`	1.746 MB/s	1.723 MB/s
`TestSmallDocCollectionBulkInsert`	34.144 MB/s	37.666 MB/s
`TestSmallDocInsertOne`	0.539 MB/s	0.572 MB/s
`TestSmallDocInsertOneUnlimitedTasks`	0.740 MB/s	0.786 MB/s

Motorから移行

警告

Motor の廃止

Motorは、年 5 月14 2026日（Motorが引き続きサポートされている間に、 MotorユーザーをPyMongo Async APIに移行することを強くお勧めします。

PyMongo Async API はMotorライブラリと同様に機能しますが、スレッドプールに作業を委任する代わりにPython asyncio を直接使用することで、レイテンシとスループットの向上が可能です。ほとんどの場合、MotorClient の代わりに AsyncMongoClient を使用し、アプリケーションのインポートステートメントを pymongo からインポートするように変更することで、既存のMotorアプリケーションをPyMongo Async に直接移行できます。

次の例は、 Motorでの読み取りおよび書込み (write) 操作にクライアントを使用するためのインポートにおけるPyMongo Async との違いを示しています。

# Motor client import
from motor.motor_asyncio import AsyncIOMotorClient
# PyMongo Async client import
from pymongo import AsyncMongoClient

PyMongo Async APIで使用できる非同期メソッドのリストを確認するには、「非同期メソッド」セクションを参照してください。PyMongoに対応するMotorのバージョンの詳細については、互換性ガイドの Motorの互換性セクションを参照してください。

次のセクションでは、 MotorからPyMongo Async APIに移行するときにアプリケーションに実装する必要があるメソッド署名の変更を示します。

メソッド署名の変更

次のMotorメソッド署名はPyMongo Async APIでは動作が異なります。

AsyncMongoClient.__init__() は io_loop パラメータを受け入れません。
AsyncCursor.each() はPyMongo Async APIに存在しません。
MotorGridOut.stream_to_handler() はPyMongo Async APIに存在しません。
AsyncCursor.to_list(0) はPyMongo Async APIでは有効ではありません。代わりに to_list(None) を使用してください。
MongoClient はスレッドセーフであり、多くのスレッドで使用できますが、AsyncMongoClient はスレッドセーフではないため、単一のイベントループでのみ使用する必要があります。

警告

MotorユーザーはPyMongo Async APIに切り替えるとパフォーマンスが低下する可能性があります。これは、 PyMongo Async API がスレッドベースの実行プログラムではなくネイティブの asyncio タスクを使用しているためです。スレッドベースの実行プログラムは、同期ドライバーと同様のパフォーマンス特性を持ちますが、動作は遅くなります。つまり、 PyMongo Async APIの前述の基準に満たないワークロードのパフォーマンスが向上します。

パフォーマンスの低下が発生している場合は、ユースケースにPyMongo Async API が必要かどうかを特定してください。同期PyMongoの方がユースケースが優れていると判断した場合は、非同期互換性のために asyncio.loop.run_in_executor() とともに同期ドライバーを使用することを検討してください。詳しくは、イベントループAPIドキュメントを参照してください。

PyMongoからの移行

PyMongo Async API はPyMongoと同様に動作しますが、ネットワーク操作を実行するすべてのメソッドはコルーチンであり、待機する必要があります。PyMongoからPyMongo Async に移行するには、次の方法でコードを更新する必要があります。

MongoClient のすべての使用を AsyncMongoClient に置き換えます。
すべての非同期メソッド呼び出しに await キーワードを追加します。
関数内で非同期メソッドを呼び出す場合は、その関数を async としてマークします。

同期PyMongoからPyMongo Async APIに移行するときは、次の点に注意してください。

AsyncCursor をリストに変換するには、非同期 cursor.to_list() メソッドを使用する必要があります。
PyMongo Async APIの AsyncCollection.find() メソッドは同期されていますが、AsyncCursor を返します。カーソルを反復処理するには、async for ループを使用する必要があります。
AsyncMongoClientオブジェクトはconnect キーワード引数をサポートしていません。
スレッドまたはイベントループ間で AsyncMongoClient オブジェクトを共有することはできません。
非同期呼び出しによって返された結果のプロパティまたはメソッドにアクセスするには、次の例に示すように、呼び出しを括弧で適切にラップする必要があります。
```
id = (await posts.insert_one(doc)).inserted_id
```

非同期メソッド

PyMongo Async APIで使用できる非同期メソッドの完全なリストについては、APIドキュメントを参照してください。

注意

上記のAPIドキュメントにリストされていないメソッドは同期されます。

詳細情報

非同期Pythonの詳細については、Python asyncio ドキュメントを参照してください。

戻る

アップグレードガイド

以前のバージョン