/ /

データ型

PyMongoArrow は、大多数のBSON typesをサポートしています。 Arrow と Alerts はリストと構造体のファーストクラスのサポートを提供するため、これには埋め込み配列とドキュメントが含まれます。

その他のタイプのサポートは、後続のリリースで追加されます。

Tip

BSON types の詳細については、 BSON仕様を参照してください。

BSON 型	タイプ識別子
文字列	`py.str` のインスタンス `pyarrow.string`
embeddedDocument	`py.dict` のインスタンス `pyarrow.struct`
埋め込み配列	のインスタンス `pyarrow.list_`
ObjectId	`py.bytes` `bson.ObjectId` のインスタンス `pymongoarrow.types.ObjectIdType` のインスタンス `pymongoarrow.pandas_types.PandasObjectId`
Decimal128	`bson.Decimal128` のインスタンス `pymongoarrow.types.Decimal128Type` のインスタンス `pymongoarrow.pandas_types.PandasDecimal128` のインスタンス `pyarrow.Decimal128`
ブール値	`~py.bool` のインスタンス `~pyarrow.bool_`
64 ビットのバイナリ浮動小数点	`py.float` のインスタンス `pyarrow.float64`
32 ビット整数	のインスタンス `pyarrow.int32`
64 ビット整数	`~py.int` `bson.int64.Int64` のインスタンス `pyarrow.int64`
UTC 日時	`py.datetime.datetime` `ms` の解決を持つ `~pyarrow.timestamp` のインスタンス
バイナリデータ	`bson.Binary` のインスタンス `pymongoarrow.types.BinaryType` のインスタンス `pymongoarrow.pandas_types.PandasBinary`
JavaScript コード	`bson.Code` のインスタンス `pymongoarrow.types.CodeType` のインスタンス `pymongoarrow.pandas_types.PandasCode`
null	のインスタンス `pyarrow.null`

注意

PyMongoArrow は、リトルエンディアンシステムのみでDecimal128をサポートしています。ビッグエンディアンシステムでは、代わりにnullが使用されます。

型識別子を使用して、 pymongoarrow.api.Schema宣言中にフィールドが特定の型であることを指定します。たとえば、データに 32 ビット整数と UTC 日時のタイプを持つf1とf2と、 ObjectIdである_idがある場合は、次のようにスキーマを定義できます。

schema = Schema({
  '_id': ObjectId,
  'f1': pyarrow.int32(),
  'f2': pyarrow.timestamp('ms')
})

スキーマでサポートされていないデータ型では、 ValueErrorがフィールドとそのデータ型を識別します。

埋め込み配列に関する考慮事項

埋め込み配列に使用されるスキーマでは、配列要素の型を指定するためにpyarrow.list_()型を使用する必要があります。たとえば、

from pyarrow import list_, float64
schema = Schema({'_id': ObjectId,
  'location': {'coordinates': list_(float64())}
})

拡張タイプ

PyMongoArrow は、 ObjectId 、 Decimal128 、 Binary data 、 JavaScript code型を PyArrow および Pandoras の拡張型として実装します。矢印テーブルの場合、これらの型の値には適切なpymongoarrow拡張タイプ（ pymongoarrow.types.ObjectIdTypeなど）があります。適切なbson Python オブジェクトを取得するには、 .as_py()メソッドを使用するか、テーブルで.to_pylist()を呼び出します。

>>> from pymongo import MongoClient
>>> from bson import ObjectId
>>> from pymongoarrow.api import find_arrow_all
>>> client = MongoClient()
>>> coll = client.test.test
>>> coll.insert_many([{"_id": ObjectId(), "foo": 100}, {"_id": ObjectId(), "foo": 200}])
<pymongo.results.InsertManyResult at 0x1080a72b0>
>>> table = find_arrow_all(coll, {})
>>> table
pyarrow.Table
_id: extension<arrow.py_extension_type<ObjectIdType>>
foo: int32
----
_id: [[64408B0D5AC9E208AF220142,64408B0D5AC9E208AF220143]]
foo: [[100,200]]
>>> table["_id"][0]
<pyarrow.ObjectIdScalar: ObjectId('64408b0d5ac9e208af220142')>
>>> table["_id"][0].as_py()
ObjectId('64408b0d5ac9e208af220142')
>>> table.to_pylist()
[{'_id': ObjectId('64408b0d5ac9e208af220142'), 'foo': 100},
 {'_id': ObjectId('64408b0d5ac9e208af220143'), 'foo': 200}]

Pandoraに変換する場合、拡張タイプ列には適切なpymongoarrow拡張タイプ（ pymongoarrow.pandas_types.PandasDecimal128など）があります。データフレーム内の要素の値は適切なbsonタイプです。

>>> from pymongo import MongoClient
>>> from bson import Decimal128
>>> from pymongoarrow.api import find_pandas_all
>>> client = MongoClient()
>>> coll = client.test.test
>>> coll.insert_many([{"foo": Decimal128("0.1")}, {"foo": Decimal128("0.1")}])
<pymongo.results.InsertManyResult at 0x1080a72b0>
>>> df = find_pandas_all(coll, {})
>>> df
                       _id  foo
0  64408bf65ac9e208af220144  0.1
1  64408bf65ac9e208af220145  0.1
>>> df["foo"].dtype
<pymongoarrow.pandas_types.PandasDecimal128 at 0x11fe0ae90>
>>> df["foo"][0]
Decimal128('0.1')
>>> df["_id"][0]
ObjectId('64408bf65ac9e208af220144')

Tarlas は拡張タイプをサポートしていません。

NULL 値と Pandora Data Frames への変換

Arrow と Aggregation では、すべての配列が null 可能です。Pandora には、Int64 などの実験的な null 可能なデータ型があります。次のApacheドキュメントコードで、nullable dtypes を使用してpandas Data Frame を作成するよう Arrow に指示できます。

>>> dtype_mapping = {
...     pa.int8(): pd.Int8Dtype(),
...     pa.int16(): pd.Int16Dtype(),
...     pa.int32(): pd.Int32Dtype(),
...     pa.int64(): pd.Int64Dtype(),
...     pa.uint8(): pd.UInt8Dtype(),
...     pa.uint16(): pd.UInt16Dtype(),
...     pa.uint32(): pd.UInt32Dtype(),
...     pa.uint64(): pd.UInt64Dtype(),
...     pa.bool_(): pd.BooleanDtype(),
...     pa.float32(): pd.Float32Dtype(),
...     pa.float64(): pd.Float64Dtype(),
...     pa.string(): pd.StringDtype(),
... }
... df = arrow_table.to_pandas(
...     types_mapper=dtype_mapping.get, split_blocks=True, self_destruct=True
... )
... del arrow_table

pa.string()の変換を定義すると、オブジェクトではなく、Arrow string が NumPy string に変換されます。

ネストされた拡張タイプ

Pending ARROW-179、ネストされたドキュメントに表示される ObjectId などの拡張タイプは、対応する PyMongoArrow 拡張タイプに変換されず、代わりに未加工の Arrow タイプ FixedSizeBinaryType(fixed_size_binary[12]) になります。

これらの値はそのまま使用することも、 _id = out['nested'][0]['_id'].cast(ObjectIdType())などの目的の拡張タイプに個別に変換することもできます。

戻る

PyMongoとの比較

スキーマの例