日付と時刻

用語

Python は日付と時刻を表すために専用のデータ型datetime.datetimeを使用します。 MongoDB は、英国ロード フィールドを対象としたグローバル タイム標準（UTC）にdatetime値を保存します。

datetime(2002, 10, 27, 14, 0, 0)

datetime(2002, 10, 27, 6, 0,
         tzinfo=<DstTzInfo 'US/Pacific' PST-1 day, 16:00:00 STD>)

from datetime import datetime
from pytz import timezone
utc_datetime = datetime(2002, 10, 27, 6, 0, 0)
pacific = timezone("US/Pacific")
local_datetime = pacific.localize(utc_datetime)
print(f"UTC datetime: {utc_datetime}")
print(f"Local datetime: {local_datetime}")

UTC datetime: 2002-10-27 06:00:00
Local datetime: 2002-10-27 06:00:00-08:00

ネイティブ UTC 日時

デフォルトでは 、 PyMongo は追加情報のない UTC datetime 値を検索します。次のコード例では、サンプルドキュメントを取得し、datetime 値を出力します。出力される値は、サンプルドキュメントの と同じです。対応するコードを表示するには、Synchronous タブまたは Asynchronousタブを選択します。

from datetime import datetime
collection = database["sample_collection"]
find_result = collection.find_one()["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 14:00:00
datetime.tzinfo: None

from datetime import datetime
collection = database["sample_collection"]
find_result = (await collection.find_one())["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 14:00:00
datetime.tzinfo: None

認識済み UTC 日時

PyMongo に認識済みのdatetime値を取得するよう指示するには、 CodecOptionsオブジェクトを作成し、 tz_aware = Trueをコンストラクターに渡します。 次に、 CodecOptionsオブジェクトをget_collection()メソッドに渡します。

次のコード例では、サンプルドキュメントから datetime の値を認識済みの datetime として取得します。対応するコードを表示するには、Synchronous タブまたは Asynchronousタブを選択します。

from pymongo import MongoClient
from datetime import datetime
from bson.codec_options import CodecOptions
options = CodecOptions(tz_aware = True)
collection = database.get_collection("sample_collection", options)
find_result = collection.find_one()["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 14:00:00+00:00
datetime.tzinfo: <bson.tz_util.FixedOffset object at 0x104db2b80>

from pymongo import MongoClient
from datetime import datetime
from bson.codec_options import CodecOptions
options = CodecOptions(tz_aware = True)
collection = database.get_collection("sample_collection", options)
find_result = (await collection.find_one())["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 14:00:00+00:00
datetime.tzinfo: <bson.tz_util.FixedOffset object at 0x104db2b80>

ローカライズされた日時

ユーザーにdatetime値を表示する予定の場合は、MongoDB から読み取られたすべての時間を特定のタイムゾーンに自動的に変換するように PyMongo に指示できます。 そのためには、「用語」セクションで説明されているように、ターゲット タイムゾーン用のtimezoneオブジェクトを作成します。 Then, create a CodecOptions object and pass the following arguments to the constructor:

• tz_aware: Trueに設定します。

• tzinfo: timezoneオブジェクト。

次のコード例では、サンプルドキュメントを取得していますが、tz_aware と tzinfo 引数を使用して datetime の値を "US/Pacific" タイムゾーンに自動的にローカライズします。対応するコードを表示するには、Synchronous タブまたは Asynchronousタブを選択します。

from pymongo import MongoClient
from datetime import datetime
from bson.codec_options import CodecOptions
import pytz
from pytz import timezone
pacific = timezone("US/Pacific")
options = CodecOptions(tz_aware = True, tzinfo = pacific)
collection = database.get_collection("sample_collection", options)
find_result = collection.find_one()["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 06:00:00-08:00
datetime.tzinfo: US/Pacific

from pymongo import MongoClient
from datetime import datetime
from bson.codec_options import CodecOptions
import pytz
from pytz import timezone
pacific = timezone("US/Pacific")
options = CodecOptions(tz_aware = True, tzinfo = pacific)
collection = database.get_collection("sample_collection", options)
find_result = (await collection.find_one())["date"]
print(f"datetime: {find_result}")
print(f"datetime.tzinfo: {find_result.tzinfo}")

datetime: 2002-10-27 06:00:00-08:00
datetime.tzinfo: US/Pacific

DatetimeConversion.DATETIME

DatetimeConversion.DATETIME は、デフォルト値です。 この値により、次の例に示すように、PyMongo は範囲外の日付をデコードしようとするとエラーを発生させます。

from datetime import datetime
from bson import encode, decode
from bson.datetime_ms import DatetimeMS
out_of_range = DatetimeMS(-(2**62))
val = encode({"date": out_of_range})
decoded = decode(val)
print(decoded)

...
bson.errors.InvalidBSON: year -146136543 is out of range (Consider Using
CodecOptions(datetime_conversion=DATETIME_AUTO) or
MongoClient(datetime_conversion='DATETIME_AUTO')).
...

DatetimeConversion.DATETIME_MS

この値は、日付がdatetimeの範囲内であっても、 DatetimeMSオブジェクトのみを返すように PyMongo に指示します。

from datetime import datetime
from bson import encode, decode
from bson.datetime_ms import DatetimeMS
from bson.codec_options import CodecOptions, DatetimeConversion
val = encode({"date": datetime(1970, 1, 2)})
codec_ms = CodecOptions(datetime_conversion=DatetimeConversion.DATETIME_MS)
decoded = decode(val, codec_options=codec_ms)
print(decoded)

{"date": DatetimeMS(86400000)}

DatetimeConversion.DATETIME_Auto

この値は、値がdatetimeの範囲内にある場合はdatetimeオブジェクトを返し、それ以外の場合はDatetimeMSオブジェクトを返すように PyMongo に指示します。 次のコード例では、 datetime範囲内の 1 つの日時と範囲外の日時をエンコードおよびデコードします。

from datetime import datetime
from bson import encode, decode
from bson.datetime_ms import DatetimeMS
from bson.codec_options import CodecOptions, DatetimeConversion
in_range = encode({"date": datetime(1970, 1, 1)})
out_of_range = encode({"date": DatetimeMS(-(2**62))})
codec_auto = CodecOptions(datetime_conversion=DatetimeConversion.DATETIME_AUTO)
in_decoded = decode(in_range, codec_options=codec_auto)
out_decoded = decode(out_of_range, codec_options=codec_auto)
print(f"in-range date: {in_decoded}")
print(f"out-of-range date: {out_decoded}")

in-range date: {"date": datetime.datetime(1970, 1, 1, 0, 0)}
out-of-range date: {'x': DatetimeMS(-4611686018427387904)}

DatetimeConversion.DATETIME_CLAMP

この値は結果のdatetimeオブジェクトを「ロック」し、それらをdatetimeの範囲（ 999 、 000マイクロ秒に削除）内に収まるようにします。

次のコード例では、 datetime範囲より前の 1 つの日時とdatetime範囲より後の 1 つの日時をエンコードおよびデコードします。 結果の値は、許可された範囲の先頭と末尾にあります。

from datetime import datetime
from bson import encode, decode
from bson.datetime_ms import DatetimeMS
from bson.codec_options import CodecOptions, DatetimeConversion
before = encode({"date": DatetimeMS(-(2**62))})
after = encode({"date": DatetimeMS(2**62)})
codec_clamp = CodecOptions(datetime_conversion=DatetimeConversion.DATETIME_CLAMP)
before_decoded = decode(before, codec_options=codec_clamp)
after_decoded = decode(after, codec_options=codec_clamp)
print(f"datetime before the range: {before_decoded}")
print(f"datetime after the range: {after_decoded}")

datetime before the range: {"date": datetime.datetime(1, 1, 1, 0, 0)}
datetime after the range: {"date": datetime.datetime(9999, 12, 31, 23, 59, 59, 999000)}

別の言語のドライバーによって保存された日付をデコードするときにオーバーフローエラーが発生する

PyMongo は BSON datetime値を Python のdatetime.datetimeクラスのインスタンスにデコードします。 datetime.datetimeのインスタンスは、 datetime.MINYEAR （ 1 ）からdatetime.MAXYEAR （ 9999 ）までの年に制限されています。 一部の MongoDB ドライバーは、 datetime.datetimeでサポートされている値より大幅に外側の年値を持つ BSON 日時を保存できます。

この問題を回避する方法がいくつかあります。 PyMongo 4.3以降、 bson.decodeは 4 つの方法のいずれかで BSON datetime値を復号化できます。 変換方法は、 ~bson.codec_options.CodecOptionsのdatetime_conversionパラメータを使用して指定できます。

デフォルトの変換オプションは ~bson.codec_options.DatetimeConversion.DATETIME です。これにより、値が datetime.datetime としてデコードされ、範囲外の日付で ~builtin.OverflowError が発生できるようになります。~bson.codec_options.DatetimeConversion.DATETIME_AUTO はこの動作を変更して、表現が範囲外の場合には代わりに ~bson.datetime_ms.DatetimeMS を返し、以前のように ~datetime.datetime オブジェクトを返します。対応するコードを表示するには、Synchronous タブまたは Asynchronousタブを選択します。

from datetime import datetime
from bson.datetime_ms import DatetimeMS
from bson.codec_options import DatetimeConversion
from pymongo import MongoClient
client = MongoClient(datetime_conversion=DatetimeConversion.DATETIME_AUTO)
client.db.collection.insert_one({"x": datetime(1970, 1, 1)})
client.db.collection.insert_one({"x": DatetimeMS(2**62)})
for x in client.db.collection.find():
   print(x)

{'_id': ObjectId('...'), 'x': datetime.datetime(1970, 1, 1, 0, 0)}
{'_id': ObjectId('...'), 'x': DatetimeMS(4611686018427387904)}

from datetime import datetime
from bson.datetime_ms import DatetimeMS
from bson.codec_options import DatetimeConversion
from pymongo import MongoClient
client = AsyncMongoClient(datetime_conversion=DatetimeConversion.DATETIME_AUTO)
await client.db.collection.insert_one({"x": datetime(1970, 1, 1)})
await client.db.collection.insert_one({"x": DatetimeMS(2**62)})
async for x in client.db.collection.find():
   print(x)

{'_id': ObjectId('...'), 'x': datetime.datetime(1970, 1, 1, 0, 0)}
{'_id': ObjectId('...'), 'x': DatetimeMS(4611686018427387904)}

その他のオプションについては、DatetimeConversionクラスのAPIドキュメントを参照してください。

datetime_conversion の設定に関係のないもう 1 つのオプションは、~datetime.datetime でサポートされている範囲外のドキュメント値をフィルタリングで除外することです。対応するコードを表示するには、Synchronous タブまたは Asynchronousタブを選択します。

from datetime import datetime
coll = client.test.dates
cur = coll.find({'dt': {'$gte': datetime.min, '$lte': datetime.max}})

from datetime import datetime
coll = client.test.dates
cur = coll.find({'dt': {'$gte': datetime.min, '$lte': datetime.max}})

datetime の値が必要ない場合は、そのフィールドのみをフィルタリングで除外できます。対応するコードを表示するには、Synchronous タブまたは Asynchronousタブを選択します。

cur = coll.find({}, projection={'dt': False})

cur = coll.find({}, projection={'dt': False})