Datasets documentation

テーブルクラス

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.2.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

テーブルクラス

各Datasetオブジェクトは、PyArrow Tableによって裏付けられています。 Tableは、ディスクから(メモリマップドで)読み込むことも、メモリ内に読み込むこともできます。 複数のTableタイプが利用可能であり、それらはすべてtable.Tableを継承しています。

テーブル

クラス datasets.table.Table

< >

( table: Table )

合成を用いて pyarrow の Table をラップします。 これは InMemoryTable、MemoryMappedTable および ConcatenationTable のベースクラスです。

pyarrowのTableクラスの基本的な属性/メソッドをすべて実装していますが、Tableの変換(slice, filter, flatten, combine_chunks, cast, add_column, append_column, remove_column, set_column, rename_columnsおよびdrop)は除きます。

これらのメソッドの実装は、サブクラスによって異なります。

validate

< >

( *args**kwargs )

パラメータ

  • full (bool、デフォルトはFalse) — Trueの場合、コストの高いチェックを実行し、それ以外の場合はコストの低いチェックのみを実行します。

例外

pa.lib.ArrowInvalid

  • pa.lib.ArrowInvalid — 検証が失敗した場合

検証チェックを実行します。検証に失敗した場合、例外が発生します。

デフォルトでは、低コストな検証チェックのみが実行されます。徹底的な検証チェック(O(n)になる可能性があります)を実行するには、full=Trueを渡してください。

equals

< >

( *args**kwargs ) → bool

パラメータ

  • other (Table) — 比較対象となるテーブル。
  • check_metadata bool、デフォルトはFalse) — スキーマのメタデータが等しいこともチェックするかどうか。

戻り値

bool

2つのテーブルの内容が等しいかどうかを確認します。

to_batches

< >

( *args**kwargs )

パラメータ

  • max_chunksize (int、デフォルトはNone) — RecordBatchチャンクの最大サイズ。個々のチャンクは、個々のカラムのチャンクレイアウトに応じて、より小さくなることがあります。

Tableを(連続した)RecordBatchオブジェクトのリストに変換します。

to_pydict

< >

( *args**kwargs ) → dict

戻り値

dict

TableをdictまたはOrderedDictに変換します。

to_pandas

< >

( *args**kwargs ) → pandas.Series or pandas.DataFrame

パラメータ

  • memory_pool (MemoryPool、デフォルトはNone) — 割り当てに使用する Arrow MemoryPool です。指定されない場合は、デフォルトのメモリプールが使用されます。
  • strings_to_categorical (bool、デフォルトはFalse) — 文字列 (UTF8) 型およびバイナリ型をpandas.Categoricalにエンコードします。
  • categories (list、デフォルトはempty) — pandas.Categoricalとして返されるべきフィールドのリストです。テーブル形式のデータ構造にのみ適用されます。
  • zero_copy_only (bool、デフォルトはFalse) — この関数呼び出しが基底データのコピーを必要とする場合、ArrowExceptionを発生させます。
  • integer_object_nulls (bool、デフォルトはFalse) — nullを含む整数をオブジェクトにキャストします。
  • date_as_object (bool、デフォルトはTrue) — 日付をオブジェクトにキャストします。Falseの場合、datetime64[ns]型に変換します。
  • timestamp_as_object (bool、デフォルトはFalse) — ナノ秒以外のタイムスタンプ(np.datetime64)をオブジェクトにキャストします。これは、ナノ秒タイムスタンプの通常の日付範囲(西暦1678年〜西暦2262年)に収まらないタイムスタンプがある場合に便利です。 Falseの場合、すべてのタイムスタンプはdatetime64[ns]型に変換されます。
  • use_threads (bool、デフォルトはTrue) — 複数のスレッドを使用して変換を並列化するかどうかを指定します。
  • deduplicate_objects (bool、デフォルトはFalse) — Pythonオブジェクトの作成時に複数のコピーを作成せず、メモリ使用量を節約します。変換は遅くなります。
  • ignore_metadata (bool、デフォルトはFalse) — Trueの場合、存在する‘pandas’メタデータを使用してDataFrameのインデックスを再構築しません。
  • safe (bool、デフォルトはTrue) — 特定のデータ型では、データを pandas の DataFrame または Series に格納するためにキャストが必要です(例: タイムスタンプは pandas では常にナノ秒で格納されます)。このオプションは、キャストが安全かどうかを制御します。
  • split_blocks (bool、デフォルトはFalse) — Trueの場合、RecordBatchまたはTableからpandas.DataFrameを作成する際、各カラムごとに1つの内部「ブロック」を生成します。これによりメモリ使用量が一時的に減少する可能性がありますが、pandasのさまざまな操作が「統合」をトリガーし、メモリ使用量が急増する可能性がある点にご注意ください。
  • self_destruct (bool、デフォルトはFalse) — EXPERIMENTAL: Trueの場合、Arrowオブジェクトをpandasに変換する際に、元のArrowメモリを解放しようとします。このオプションを指定してto_pandasを呼び出した後、オブジェクトを使用するとプログラムがクラッシュします。
  • types_mapper (function、デフォルトは None) — pyarrow の DataType を pandas の ExtensionDtype にマッピングする関数です。 組み込みの pyarrow 型のコンバージョンにおける pandas の既定の型を上書きするために、または Table スキーマに pandas_metadata が存在しない場合に使用できます。この関数は pyarrow の DataType を受け取り、その型に対して既定のコンバージョンを使用する場合は None、それ以外の場合は pandas の ExtensionDtype を返すことが期待されます。マッピング用の辞典を持っている場合は、dict.get を関数として渡すことができます。

戻り値

pandas.Series または pandas.DataFrame

オブジェクトの種類に応じて、pandas.Seriesまたはpandas.DataFrame

適切な場合、pandas 互換の NumPy 配列または DataFrame に変換します。

to_string

< >

( *args**kwargs )

フィールド

< >

( *args**kwargs )

パラメータ

  • i (Union[int, str]) — 取得するフィールドのインデックスまたは名前。

カラム名または数値インデックスを指定して、スキーマのフィールドを選択します。

カラム

< >

( *args**kwargs )

パラメータ

  • i (Union[int, str]) — 取得する列のインデックスまたは名前です。

カラム名または数値インデックスを指定してカラムを選択します。

itercolumns

< >

( *args**kwargs )

数値順で全カラムを反復するイテレータ。

スキーマ

< >

( )

テーブルとそのカラムのスキーマ。

カラム

< >

( )

数値順で並べられたすべてのカラムのリスト。

num_columns

< >

( )

このテーブルの列数。

num_rows

< >

( )

このテーブルの行数。

テーブルの定義により、すべての列は同じ行数を持ちます。

shape

< >

( ) → (int, int)

戻り値

(int, int)

行数と列数。

テーブルの次元: (#rows, #columns)。

nbytes

< >

( )

テーブルの要素が消費するバイト数の合計。

InMemoryTable

class datasets.table.InMemoryTable

< >

( table: Table )

テーブルがユーザーの RAM に読み込まれている場合、そのテーブルはインメモリであると言われます。

ピクルス化を行うと、メモリを使用してすべてのデータがコピーされます。 その実装はシンプルで、基盤となるpyarrowのTableメソッドを直接使用しています。

これはMemoryMappedテーブルとは異なり、ピクルス化してもメモリ内のすべてのデータをコピーしません。MemoryMappedの場合、アンピクルス化すると代わりにディスクからテーブルを再読み込みします。

InMemoryTableは、データがメモリに収まる場合に使用し、MemoryMappedは、データがメモリより大きい場合、またはアプリケーションのメモリ使用量を低く保ちたい場合に使用します。

validate

< >

( *args**kwargs )

パラメータ

  • full (bool、デフォルトはFalse) — Trueの場合、コストの高いチェックを実行し、それ以外の場合はコストの低いチェックのみを実行します。

例外

pa.lib.ArrowInvalid

  • pa.lib.ArrowInvalid — 検証が失敗した場合

検証チェックを実行します。検証に失敗した場合、例外が発生します。

デフォルトでは、低コストな検証チェックのみが実行されます。徹底的な検証チェック(O(n)になる可能性があります)を実行するには、full=Trueを渡してください。

equals

< >

( *args**kwargs ) → bool

パラメータ

  • other (Table) — 比較対象となるテーブル。
  • check_metadata bool、デフォルトはFalse) — スキーマのメタデータが等しいこともチェックするかどうか。

戻り値

bool

2つのテーブルの内容が等しいかどうかを確認します。

to_batches

< >

( *args**kwargs )

パラメータ

  • max_chunksize (int、デフォルトはNone) — RecordBatchチャンクの最大サイズ。個々のチャンクは、個々のカラムのチャンクレイアウトに応じて、より小さくなることがあります。

Tableを(連続した)RecordBatchオブジェクトのリストに変換します。

to_pydict

< >

( *args**kwargs ) → dict

戻り値

dict

TableをdictまたはOrderedDictに変換します。

to_pandas

< >

( *args**kwargs ) → pandas.Series or pandas.DataFrame

パラメータ

  • memory_pool (MemoryPool、デフォルトはNone) — 割り当てに使用する Arrow MemoryPool です。指定されない場合は、デフォルトのメモリプールが使用されます。
  • strings_to_categorical (bool、デフォルトはFalse) — 文字列 (UTF8) 型およびバイナリ型をpandas.Categoricalにエンコードします。
  • categories (list、デフォルトはempty) — pandas.Categoricalとして返されるべきフィールドのリストです。テーブル形式のデータ構造にのみ適用されます。
  • zero_copy_only (bool、デフォルトはFalse) — この関数呼び出しが基底データのコピーを必要とする場合、ArrowExceptionを発生させます。
  • integer_object_nulls (bool、デフォルトはFalse) — nullを含む整数をオブジェクトにキャストします。
  • date_as_object (bool、デフォルトはTrue) — 日付をオブジェクトにキャストします。Falseの場合、datetime64[ns]型に変換します。
  • timestamp_as_object (bool、デフォルトはFalse) — ナノ秒以外のタイムスタンプ(np.datetime64)をオブジェクトにキャストします。これは、ナノ秒タイムスタンプの通常の日付範囲(西暦1678年〜西暦2262年)に収まらないタイムスタンプがある場合に便利です。 Falseの場合、すべてのタイムスタンプはdatetime64[ns]型に変換されます。
  • use_threads (bool、デフォルトはTrue) — 複数のスレッドを使用して変換を並列化するかどうかを指定します。
  • deduplicate_objects (bool、デフォルトはFalse) — Pythonオブジェクトの作成時に複数のコピーを作成せず、メモリ使用量を節約します。変換は遅くなります。
  • ignore_metadata (bool、デフォルトはFalse) — Trueの場合、存在する‘pandas’メタデータを使用してDataFrameのインデックスを再構築しません。
  • safe (bool、デフォルトはTrue) — 特定のデータ型では、データを pandas の DataFrame または Series に格納するためにキャストが必要です(例: タイムスタンプは pandas では常にナノ秒で格納されます)。このオプションは、キャストが安全かどうかを制御します。
  • split_blocks (bool、デフォルトはFalse) — Trueの場合、RecordBatchまたはTableからpandas.DataFrameを作成する際、各カラムごとに1つの内部「ブロック」を生成します。これによりメモリ使用量が一時的に減少する可能性がありますが、pandasのさまざまな操作が「統合」をトリガーし、メモリ使用量が急増する可能性がある点にご注意ください。
  • self_destruct (bool、デフォルトはFalse) — EXPERIMENTAL: Trueの場合、Arrowオブジェクトをpandasに変換する際に、元のArrowメモリを解放しようとします。このオプションを指定してto_pandasを呼び出した後、オブジェクトを使用するとプログラムがクラッシュします。
  • types_mapper (function、デフォルトは None) — pyarrow の DataType を pandas の ExtensionDtype にマッピングする関数です。 組み込みの pyarrow 型のコンバージョンにおける pandas の既定の型を上書きするために、または Table スキーマに pandas_metadata が存在しない場合に使用できます。この関数は pyarrow の DataType を受け取り、その型に対して既定のコンバージョンを使用する場合は None、それ以外の場合は pandas の ExtensionDtype を返すことが期待されます。マッピング用の辞典を持っている場合は、dict.get を関数として渡すことができます。

戻り値

pandas.Series または pandas.DataFrame

オブジェクトの種類に応じて、pandas.Seriesまたはpandas.DataFrame

適切な場合、pandas 互換の NumPy 配列または DataFrame に変換します。

to_string

< >

( *args**kwargs )

フィールド

< >

( *args**kwargs )

パラメータ

  • i (Union[int, str]) — 取得するフィールドのインデックスまたは名前。

カラム名または数値インデックスを指定して、スキーマのフィールドを選択します。

カラム

< >

( *args**kwargs )

パラメータ

  • i (Union[int, str]) — 取得する列のインデックスまたは名前です。

カラム名または数値インデックスを指定してカラムを選択します。

itercolumns

< >

( *args**kwargs )

数値順で全カラムを反復するイテレータ。

スキーマ

< >

( )

テーブルとそのカラムのスキーマ。

カラム

< >

( )

数値順で並べられたすべてのカラムのリスト。

num_columns

< >

( )

このテーブルの列数。

num_rows

< >

( )

このテーブルの行数。

テーブルの定義により、すべての列は同じ行数を持ちます。

shape

< >

( ) → (int, int)

戻り値

(int, int)

行数と列数。

テーブルの次元: (#rows, #columns)。

nbytes

< >

( )

テーブルの要素が消費するバイト数の合計。

column_names

< >

( )

テーブルの列の名前。

スライス

< >

( offset = 0length = None )

パラメータ

  • offset (int, デフォルトは 0) — テーブルの先頭からのオフセット。スライスする位置を指定します。
  • length (int, デフォルトは None) — スライスの長さ(デフォルトでは、オフセットからテーブルの末尾まで)。

このTableのゼロコピースライスを計算します。

フィルタ

< >

( *args**kwargs )

Table からレコードを選択します。詳細な使用法については、pyarrow.compute.filterを参照してください。

flatten

< >

( *args**kwargs )

パラメータ

  • memory_pool (MemoryPool、デフォルトはNone) — メモリ割り当てに必要に応じて使用します。不要な場合はデフォルトのプールを使用します。

このTableをフラットにします。struct型の各カラムは、structのフィールドごとに1カラムずつにフラット化されます。その他のカラムは変更されません。

combine_chunks

< >

( *args**kwargs )

パラメータ

  • memory_pool (MemoryPool、デフォルトはNone) — メモリ割り当てに必要に応じて使用します。不要な場合はデフォルトのプールを使用します。

このテーブルが持つチャンクを結合して、新しいテーブルを作成します。

各カラムのChunkedArray内のすべての基となるチャンクは、0個または1個のチャンクに連結されます。

キャスト

< >

( *args**kwargs )

パラメータ

  • target_schema (Schema) — キャスト先のスキーマです。フィールドの名前と順序が一致する必要があります。
  • safe (bool、デフォルトはTrue) — オーバーフローやその他の安全でない変換を確認します。

テーブルの値を別のスキーマにキャストします。

replace_schema_metadata

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • metadata(dict、デフォルトはNone)—

戻り値

datasets.table.Table

shallow_copy

実験的機能: スキーマのキーと値のメタデータを指定された新しいメタデータ(Noneを指定すると、既存のメタデータが削除されます)に置き換えることで、テーブルの浅いコピーを作成します。

add_column

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • i (int) — 列を配置するインデックス。
  • field_ (Union[str, pyarrow.Field]) — 文字列が渡された場合、カラムのデータから型が推測されます。
  • column (Union[pyarrow.Array, List[pyarrow.Array]]) — カラムのデータ。

戻り値

datasets.table.Table

追加されたカラムを含む新しいテーブル。

Tableの指定した位置に列を追加します。

追加されたカラムを含む新しいテーブルが返され、元のテーブルオブジェクトは変更されません。

append_column

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • field_ (Union[str, pyarrow.Field]) — 文字列が渡された場合、カラムのデータから型が推測されます。
  • column (Union[pyarrow.Array, List[pyarrow.Array]]) — カラムのデータ。

戻り値

datasets.table.Table

追加されたカラムを含む新しいテーブル。

列の末尾に列を追加します。

remove_column

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • i (int) — 削除する列のインデックス。

戻り値

datasets.table.Table

その列を削除した新しいテーブル。

指定された列を削除した新しいTableを作成します。

set_column

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • i (int) — 列を配置するインデックス。
  • field_ (Union[str, pyarrow.Field]) — 文字列が渡された場合、カラムのデータから型が推測されます。
  • column (Union[pyarrow.Array, List[pyarrow.Array]]) — カラムのデータ。

戻り値

datasets.table.Table

渡されたカラムセットを持つ新しいテーブル。

Tableの指定された位置の列を置き換えます。

rename_columns

< >

( *args**kwargs )

指定された名前に変更された列を持つ新しいテーブルを作成します。

select

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • columns (Union[List[str], List[int]]) — 選択する列名または整数インデックス。

指定された列を持つ新しいテーブルで、メタデータは保持されます。

テーブルの列を選択します。

指定された列とメタデータを保持した新しいテーブルを返します。

drop

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • columns (List[str]) — 既存の列を参照するフィールド名のリスト。

戻り値

datasets.table.Table

列を削除した新しいテーブル。

例外

KeyError

  • KeyError — : 渡された列名が存在しない場合。

1つ以上の列を削除し、新しいテーブルを返します。

from_file

< >

( filename: str )

from_buffer

< >

( buffer: Buffer )

from_pandas

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • df (pandas.DataFrame) —
  • schema (pyarrow.Schema, 省略可) — Arrow Table の想定されるスキーマです。自動推論できない場合、列の型を指定するために使用できます。指定された場合、出力はこのスキーマと完全に一致します。スキーマに指定されているが、DataFrame の列やインデックスに見つからない列がある場合はエラーが発生します。スキーマに指定されていない DataFrame の追加の列やインデックスレベルは無視されます。
  • preserve_index (bool, 省略可能) — 結果のTableにインデックスを追加の列として保存するかどうか。デフォルトのNoneでは、インデックスを列として保存しますが、RangeIndexの場合はメタデータとしてのみ保存されます。インデックスを列として保存することを強制するには、preserve_index=Trueを使用してください。
  • nthreads (int、デフォルトは None(システム CPU のコア数までのスレッドを使用する可能性があります)) — 1 より大きい場合、指定されたスレッド数を使用して、カラムを並列で Arrow に変換します。
  • columns (List[str]、任意) — 変換対象の列のリストです。None の場合、すべての列を使用します。
  • safe (bool、デフォルトはTrue) — オーバーフローやその他の安全でない変換を確認します。

戻り値

datasets.table.Table

pandas.DataFrame を Arrow Table に変換します。

結果として得られる Arrow Table のカラム型は、DataFrame 内の pandas.Series の dtype から推論されます。object 以外の Series の場合、NumPy の dtype はその Arrow 相当の型に変換されます。object の場合、この Series 内の Python オブジェクトを確認してデータ型を推測する必要があります。

object dtype の Series は、常に意味のある Arrow 型を導出するのに十分な情報を保持しているとは限りません。DataFrame の長さが 0 である場合や、Series が None/nan オブジェクトのみを含む場合など、型を推論できない場合は、型は null に設定されます。この動作を回避するには、明示的なスキーマを構築し、この関数に渡すことができます。

例:

>>> import pandas as pd
>>> import pyarrow as pa
>>> df = pd.DataFrame({
    ...     'int': [1, 2],
    ...     'str': ['a', 'b']
    ... })
>>> pa.Table.from_pandas(df)
<pyarrow.lib.Table object at 0x7f05d1fb1b40>

from_arrays

< >

( *args**kwargs )

パラメータ

  • arrays (List[Union[pyarrow.Array, pyarrow.ChunkedArray]]) — テーブルを構成する、長さの等しい配列。
  • names (List[str]、省略可) — テーブルの列名です。指定しない場合は、schema を渡す必要があります。
  • schema (Schema、デフォルトはNone) — 作成されるテーブルのスキーマです。指定しない場合は、名前を渡す必要があります。
  • metadata (Union[dict, Mapping]、デフォルトはNone) — スキーマ(推定された場合)の任意のメタデータ。

Arrow配列からTableを構築します。

from_pydict

< >

( *args**kwargs )

パラメータ

  • mapping (Union[dict, Mapping]) — 文字列から配列または Python のリストへのマッピングです。
  • schema (Schema、デフォルトはNone) — 指定されない場合、Mapping の値から推論されます。
  • metadata (Union[dict, Mapping]、デフォルトはNone) — スキーマ(推定された場合)の任意のメタデータ。

Arrow配列またはカラムからTableを構築します。

from_batches

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • batches (Union[Sequence[pyarrow.RecordBatch], Iterator[pyarrow.RecordBatch]]) — 変換対象のRecordBatchのシーケンス。すべてのスキーマが等しくなければなりません。
  • schema (Schema、デフォルトはNone) — 指定されない場合、最初のRecordBatchから推論されます。

戻り値

datasets.table.Table

RecordBatches のシーケンスまたはイテレータから Table を構築します。

MemoryMappedTable

class datasets.table.MemoryMappedTable

< >

( table: Tablepath: strreplays: typing.Optional[list[tuple[str, tuple, dict]]] = None )

テーブルがユーザーのRAMを使用せず、代わりにディスクからデータをロードする場合、そのテーブルはメモリマップドであるとされます。

ピクルス化しても、データをメモリにコピーしません。 代わりに、メモリマップされたarrowファイルへのパスと、ディスクからテーブルを再読み込みする際に「リプレイ」する変換のリストのみがピクルス化されます。

その実装には、基盤となるpyarrowのTableに適用されたすべてのtransformの履歴を保存する必要があり、ディスクからTableを再読み込みする際にそれらを「リプレイ」できるようにします。

これはInMemoryTableテーブルとは異なり、後者ではピクルス化によってメモリ内のデータがすべてコピーされます。

InMemoryTableは、データがメモリに収まる場合に使用し、MemoryMappedは、データがメモリより大きい場合、またはアプリケーションのメモリ使用量を低く保ちたい場合に使用します。

validate

< >

( *args**kwargs )

パラメータ

  • full (bool、デフォルトはFalse) — Trueの場合、コストの高いチェックを実行し、それ以外の場合はコストの低いチェックのみを実行します。

例外

pa.lib.ArrowInvalid

  • pa.lib.ArrowInvalid — 検証が失敗した場合

検証チェックを実行します。検証に失敗した場合、例外が発生します。

デフォルトでは、低コストな検証チェックのみが実行されます。徹底的な検証チェック(O(n)になる可能性があります)を実行するには、full=Trueを渡してください。

equals

< >

( *args**kwargs ) → bool

パラメータ

  • other (Table) — 比較対象となるテーブル。
  • check_metadata bool、デフォルトはFalse) — スキーマのメタデータが等しいこともチェックするかどうか。

戻り値

bool

2つのテーブルの内容が等しいかどうかを確認します。

to_batches

< >

( *args**kwargs )

パラメータ

  • max_chunksize (int、デフォルトはNone) — RecordBatchチャンクの最大サイズ。個々のチャンクは、個々のカラムのチャンクレイアウトに応じて、より小さくなることがあります。

Tableを(連続した)RecordBatchオブジェクトのリストに変換します。

to_pydict

< >

( *args**kwargs ) → dict

戻り値

dict

TableをdictまたはOrderedDictに変換します。

to_pandas

< >

( *args**kwargs ) → pandas.Series or pandas.DataFrame

パラメータ

  • memory_pool (MemoryPool、デフォルトはNone) — 割り当てに使用する Arrow MemoryPool です。指定されない場合は、デフォルトのメモリプールが使用されます。
  • strings_to_categorical (bool、デフォルトはFalse) — 文字列 (UTF8) 型およびバイナリ型をpandas.Categoricalにエンコードします。
  • categories (list、デフォルトはempty) — pandas.Categoricalとして返されるべきフィールドのリストです。テーブル形式のデータ構造にのみ適用されます。
  • zero_copy_only (bool、デフォルトはFalse) — この関数呼び出しが基底データのコピーを必要とする場合、ArrowExceptionを発生させます。
  • integer_object_nulls (bool、デフォルトはFalse) — nullを含む整数をオブジェクトにキャストします。
  • date_as_object (bool、デフォルトはTrue) — 日付をオブジェクトにキャストします。Falseの場合、datetime64[ns]型に変換します。
  • timestamp_as_object (bool、デフォルトはFalse) — ナノ秒以外のタイムスタンプ(np.datetime64)をオブジェクトにキャストします。これは、ナノ秒タイムスタンプの通常の日付範囲(西暦1678年〜西暦2262年)に収まらないタイムスタンプがある場合に便利です。 Falseの場合、すべてのタイムスタンプはdatetime64[ns]型に変換されます。
  • use_threads (bool、デフォルトはTrue) — 複数のスレッドを使用して変換を並列化するかどうかを指定します。
  • deduplicate_objects (bool、デフォルトはFalse) — Pythonオブジェクトの作成時に複数のコピーを作成せず、メモリ使用量を節約します。変換は遅くなります。
  • ignore_metadata (bool、デフォルトはFalse) — Trueの場合、存在する‘pandas’メタデータを使用してDataFrameのインデックスを再構築しません。
  • safe (bool、デフォルトはTrue) — 特定のデータ型では、データを pandas の DataFrame または Series に格納するためにキャストが必要です(例: タイムスタンプは pandas では常にナノ秒で格納されます)。このオプションは、キャストが安全かどうかを制御します。
  • split_blocks (bool、デフォルトはFalse) — Trueの場合、RecordBatchまたはTableからpandas.DataFrameを作成する際、各カラムごとに1つの内部「ブロック」を生成します。これによりメモリ使用量が一時的に減少する可能性がありますが、pandasのさまざまな操作が「統合」をトリガーし、メモリ使用量が急増する可能性がある点にご注意ください。
  • self_destruct (bool、デフォルトはFalse) — EXPERIMENTAL: Trueの場合、Arrowオブジェクトをpandasに変換する際に、元のArrowメモリを解放しようとします。このオプションを指定してto_pandasを呼び出した後、オブジェクトを使用するとプログラムがクラッシュします。
  • types_mapper (function、デフォルトは None) — pyarrow の DataType を pandas の ExtensionDtype にマッピングする関数です。 組み込みの pyarrow 型のコンバージョンにおける pandas の既定の型を上書きするために、または Table スキーマに pandas_metadata が存在しない場合に使用できます。この関数は pyarrow の DataType を受け取り、その型に対して既定のコンバージョンを使用する場合は None、それ以外の場合は pandas の ExtensionDtype を返すことが期待されます。マッピング用の辞典を持っている場合は、dict.get を関数として渡すことができます。

戻り値

pandas.Series または pandas.DataFrame

オブジェクトの種類に応じて、pandas.Seriesまたはpandas.DataFrame

適切な場合、pandas 互換の NumPy 配列または DataFrame に変換します。

to_string

< >

( *args**kwargs )

フィールド

< >

( *args**kwargs )

パラメータ

  • i (Union[int, str]) — 取得するフィールドのインデックスまたは名前。

カラム名または数値インデックスを指定して、スキーマのフィールドを選択します。

カラム

< >

( *args**kwargs )

パラメータ

  • i (Union[int, str]) — 取得する列のインデックスまたは名前です。

カラム名または数値インデックスを指定してカラムを選択します。

itercolumns

< >

( *args**kwargs )

数値順で全カラムを反復するイテレータ。

スキーマ

< >

( )

テーブルとそのカラムのスキーマ。

カラム

< >

( )

数値順で並べられたすべてのカラムのリスト。

num_columns

< >

( )

このテーブルの列数。

num_rows

< >

( )

このテーブルの行数。

テーブルの定義により、すべての列は同じ行数を持ちます。

shape

< >

( ) → (int, int)

戻り値

(int, int)

行数と列数。

テーブルの次元: (#rows, #columns)。

nbytes

< >

( )

テーブルの要素が消費するバイト数の合計。

column_names

< >

( )

テーブルの列の名前。

スライス

< >

( offset = 0length = None )

パラメータ

  • offset (int, デフォルトは 0) — テーブルの先頭からのオフセット。スライスする位置を指定します。
  • length (int, デフォルトは None) — スライスの長さ(デフォルトでは、オフセットからテーブルの末尾まで)。

このTableのゼロコピースライスを計算します。

フィルタ

< >

( *args**kwargs )

Table からレコードを選択します。詳細な使用法については、pyarrow.compute.filterを参照してください。

flatten

< >

( *args**kwargs )

パラメータ

  • memory_pool (MemoryPool、デフォルトはNone) — メモリ割り当てに必要に応じて使用します。不要な場合はデフォルトのプールを使用します。

このTableをフラットにします。struct型の各カラムは、structのフィールドごとに1カラムずつにフラット化されます。その他のカラムは変更されません。

combine_chunks

< >

( *args**kwargs )

パラメータ

  • memory_pool (MemoryPool、デフォルトはNone) — メモリ割り当てに必要に応じて使用します。不要な場合はデフォルトのプールを使用します。

このテーブルが持つチャンクを結合して、新しいテーブルを作成します。

各カラムのChunkedArrayに含まれるすべての基盤となるチャンクは、ゼロ個または1個のチャンクに連結されます。

キャスト

< >

( *args**kwargs )

パラメータ

  • target_schema (Schema) — キャスト先のスキーマです。フィールドの名前と順序が一致する必要があります。
  • safe (bool、デフォルトはTrue) — オーバーフローやその他の安全でない変換を確認します。

テーブルの値を別のスキーマにキャストする

replace_schema_metadata

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • metadata(dict、デフォルトはNone)—

戻り値

datasets.table.Table

shallow_copy

実験的機能: スキーマのキーと値のメタデータを指定された新しいメタデータ(None を指定すると、既存のメタデータが削除されます)に置き換えることで、テーブルの浅いコピーを作成します。

add_column

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • i (int) — 列を配置するインデックス。
  • field_ (Union[str, pyarrow.Field]) — 文字列が渡された場合、カラムのデータから型が推測されます。
  • column (Union[pyarrow.Array, List[pyarrow.Array]]) — カラムのデータ。

戻り値

datasets.table.Table

追加されたカラムを含む新しいテーブル。

Tableの指定した位置に列を追加します。

追加されたカラムを含む新しいテーブルが返され、元のテーブルオブジェクトは変更されません。

append_column

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • field_ (Union[str, pyarrow.Field]) — 文字列が渡された場合、カラムのデータから型が推測されます。
  • column (Union[pyarrow.Array, List[pyarrow.Array]]) — カラムのデータ。

戻り値

datasets.table.Table

追加されたカラムを含む新しいテーブル。

列の末尾に列を追加します。

remove_column

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • i (int) — 削除する列のインデックス。

戻り値

datasets.table.Table

その列を削除した新しいテーブル。

指定された列を削除した新しいTableを作成します。

set_column

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • i (int) — 列を配置するインデックス。
  • field_ (Union[str, pyarrow.Field]) — 文字列が渡された場合、カラムのデータから型が推測されます。
  • column (Union[pyarrow.Array, List[pyarrow.Array]]) — カラムのデータ。

戻り値

datasets.table.Table

渡されたカラムセットを持つ新しいテーブル。

Tableの指定された位置の列を置き換えます。

rename_columns

< >

( *args**kwargs )

指定された名前に変更された列を持つ新しいテーブルを作成します。

select

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • columns (Union[List[str], List[int]]) — 選択する列名または整数インデックス。

指定された列を持つ新しいテーブルで、メタデータは保持されます。

テーブルの列を選択します。

指定された列とメタデータを保持した新しいテーブルを返します。

drop

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • columns (List[str]) — 既存の列を参照するフィールド名のリスト。

戻り値

datasets.table.Table

列を削除した新しいテーブル。

例外

KeyError

  • KeyError — : 渡された列名が存在しない場合。

1つ以上の列を削除し、新しいテーブルを返します。

from_file

< >

( filename: strreplays = None )

ConcatenationTable

クラス datasets.table.ConcatenationTable

< >

( table: Tableblocks: list )

このテーブルは、ブロックと呼ばれる複数のテーブルを連結して構成されています。 軸0(行の追加)と軸1(列の追加)の両方で連結を可能にします。

基盤となるテーブルは「ブロック」と呼ばれ、InMemoryTableまたはMemoryMappedTableオブジェクトのいずれかです。 これにより、メモリ由来のテーブルとメモリマップされたテーブルを組み合わせることができます。 ConcatenationTableがピクルス化されると、各ブロックがピクルス化されます:

  • InMemoryTable オブジェクトは、メモリ内のデータをすべてコピーすることによってピクルス化されます。
  • MemoryMappedTableオブジェクトは、データをメモリにコピーせずにピクルス化されます。 代わりに、メモリマップされたarrowファイルへのパスと、ディスクからテーブルを再読み込みする際に「リプレイ」する変換のリストのみがピクルス化されます。

その実装には、各ブロックを個別に保存する必要があります。 blocks 属性は、ブロックのリストのリストを保存します。 第1軸はテーブルを軸0に沿って連結します(行を追加します)。 一方、第2軸はテーブルを軸1に沿って連結します(列を追加します)。

axis 0 で結合する際に一部の列が欠落している場合、null 値で埋められます。 これは pyarrow.concat_tables(tables, promote=True) を使用して行われます。

ConcatenationTable.table 属性にアクセスすることで、完全に結合されたテーブルにアクセスでき、ConcatenationTable.blocks 属性にアクセスすることで、ブロックにアクセスできます。

validate

< >

( *args**kwargs )

パラメータ

  • full (bool、デフォルトはFalse) — Trueの場合、コストの高いチェックを実行し、それ以外の場合はコストの低いチェックのみを実行します。

例外

pa.lib.ArrowInvalid

  • pa.lib.ArrowInvalid — 検証が失敗した場合

検証チェックを実行します。検証に失敗した場合、例外が発生します。

デフォルトでは、低コストな検証チェックのみが実行されます。徹底的な検証チェック(O(n)になる可能性があります)を実行するには、full=Trueを渡してください。

equals

< >

( *args**kwargs ) → bool

パラメータ

  • other (Table) — 比較対象となるテーブル。
  • check_metadata bool、デフォルトはFalse) — スキーマのメタデータが等しいこともチェックするかどうか。

戻り値

bool

2つのテーブルの内容が等しいかどうかを確認します。

to_batches

< >

( *args**kwargs )

パラメータ

  • max_chunksize (int、デフォルトはNone) — RecordBatchチャンクの最大サイズ。個々のチャンクは、個々のカラムのチャンクレイアウトに応じて、より小さくなることがあります。

Tableを(連続した)RecordBatchオブジェクトのリストに変換します。

to_pydict

< >

( *args**kwargs ) → dict

戻り値

dict

TableをdictまたはOrderedDictに変換します。

to_pandas

< >

( *args**kwargs ) → pandas.Series or pandas.DataFrame

パラメータ

  • memory_pool (MemoryPool、デフォルトはNone) — 割り当てに使用する Arrow MemoryPool です。指定されない場合は、デフォルトのメモリプールが使用されます。
  • strings_to_categorical (bool、デフォルトはFalse) — 文字列 (UTF8) 型およびバイナリ型をpandas.Categoricalにエンコードします。
  • categories (list、デフォルトはempty) — pandas.Categoricalとして返されるべきフィールドのリストです。テーブル形式のデータ構造にのみ適用されます。
  • zero_copy_only (bool、デフォルトはFalse) — この関数呼び出しが基底データのコピーを必要とする場合、ArrowExceptionを発生させます。
  • integer_object_nulls (bool、デフォルトはFalse) — nullを含む整数をオブジェクトにキャストします。
  • date_as_object (bool、デフォルトはTrue) — 日付をオブジェクトにキャストします。Falseの場合、datetime64[ns]型に変換します。
  • timestamp_as_object (bool、デフォルトはFalse) — ナノ秒以外のタイムスタンプ(np.datetime64)をオブジェクトにキャストします。これは、ナノ秒タイムスタンプの通常の日付範囲(西暦1678年〜西暦2262年)に収まらないタイムスタンプがある場合に便利です。 Falseの場合、すべてのタイムスタンプはdatetime64[ns]型に変換されます。
  • use_threads (bool、デフォルトはTrue) — 複数のスレッドを使用して変換を並列化するかどうかを指定します。
  • deduplicate_objects (bool、デフォルトはFalse) — Pythonオブジェクトの作成時に複数のコピーを作成せず、メモリ使用量を節約します。変換は遅くなります。
  • ignore_metadata (bool、デフォルトはFalse) — Trueの場合、存在する‘pandas’メタデータを使用してDataFrameのインデックスを再構築しません。
  • safe (bool、デフォルトはTrue) — 特定のデータ型では、データを pandas の DataFrame または Series に格納するためにキャストが必要です(例: タイムスタンプは pandas では常にナノ秒で格納されます)。このオプションは、キャストが安全かどうかを制御します。
  • split_blocks (bool、デフォルトはFalse) — Trueの場合、RecordBatchまたはTableからpandas.DataFrameを作成する際、各カラムごとに1つの内部「ブロック」を生成します。これによりメモリ使用量が一時的に減少する可能性がありますが、pandasのさまざまな操作が「統合」をトリガーし、メモリ使用量が急増する可能性がある点にご注意ください。
  • self_destruct (bool、デフォルトはFalse) — EXPERIMENTAL: Trueの場合、Arrowオブジェクトをpandasに変換する際に、元のArrowメモリを解放しようとします。このオプションを指定してto_pandasを呼び出した後、オブジェクトを使用するとプログラムがクラッシュします。
  • types_mapper (function、デフォルトは None) — pyarrow の DataType を pandas の ExtensionDtype にマッピングする関数です。 組み込みの pyarrow 型のコンバージョンにおける pandas の既定の型を上書きするために、または Table スキーマに pandas_metadata が存在しない場合に使用できます。この関数は pyarrow の DataType を受け取り、その型に対して既定のコンバージョンを使用する場合は None、それ以外の場合は pandas の ExtensionDtype を返すことが期待されます。マッピング用の辞典を持っている場合は、dict.get を関数として渡すことができます。

戻り値

pandas.Series または pandas.DataFrame

オブジェクトの種類に応じて、pandas.Seriesまたはpandas.DataFrame

適切な場合、pandas 互換の NumPy 配列または DataFrame に変換します。

to_string

< >

( *args**kwargs )

フィールド

< >

( *args**kwargs )

パラメータ

  • i (Union[int, str]) — 取得するフィールドのインデックスまたは名前。

カラム名または数値インデックスを指定して、スキーマのフィールドを選択します。

カラム

< >

( *args**kwargs )

パラメータ

  • i (Union[int, str]) — 取得する列のインデックスまたは名前です。

カラム名または数値インデックスを指定してカラムを選択します。

itercolumns

< >

( *args**kwargs )

数値順で全カラムを反復するイテレータ。

スキーマ

< >

( )

テーブルとそのカラムのスキーマ。

カラム

< >

( )

数値順で並べられたすべてのカラムのリスト。

num_columns

< >

( )

このテーブルの列数。

num_rows

< >

( )

このテーブルの行数。

テーブルの定義により、すべての列は同じ行数を持ちます。

shape

< >

( ) → (int, int)

戻り値

(int, int)

行数と列数。

テーブルの次元: (#rows, #columns)。

nbytes

< >

( )

テーブルの要素が消費するバイト数の合計。

column_names

< >

( )

テーブルの列の名前。

スライス

< >

( offset = 0length = None )

パラメータ

  • offset (int, デフォルトは 0) — テーブルの先頭からのオフセット。スライスする位置を指定します。
  • length (int, デフォルトは None) — スライスの長さ(デフォルトでは、オフセットからテーブルの末尾まで)。

このTableのゼロコピースライスを計算します。

フィルタ

< >

( mask*args**kwargs )

Table からレコードを選択します。詳細な使用法については、pyarrow.compute.filterを参照してください。

flatten

< >

( *args**kwargs )

パラメータ

  • memory_pool (MemoryPool、デフォルトはNone) — メモリ割り当てに必要に応じて使用します。不要な場合はデフォルトのプールを使用します。

このTableをフラットにします。struct型の各カラムは、structのフィールドごとに1カラムずつにフラット化されます。その他のカラムは変更されません。

combine_chunks

< >

( *args**kwargs )

パラメータ

  • memory_pool (MemoryPool、デフォルトはNone) — メモリ割り当てに必要に応じて使用します。不要な場合はデフォルトのプールを使用します。

このテーブルが持つチャンクを結合して、新しいテーブルを作成します。

各カラムのChunkedArray内のすべての基となるチャンクは、0個または1個のチャンクに連結されます。

キャスト

< >

( target_schema*args**kwargs )

パラメータ

  • target_schema (Schema) — キャスト先のスキーマです。フィールドの名前と順序が一致する必要があります。
  • safe (bool、デフォルトはTrue) — オーバーフローやその他の安全でない変換を確認します。

テーブルの値を別のスキーマにキャストします。

replace_schema_metadata

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • metadata(dict、デフォルトはNone)—

戻り値

datasets.table.Table

shallow_copy

実験的機能: スキーマのキーと値のメタデータを指定された新しいメタデータ(Noneを指定すると、既存のメタデータが削除されます)に置き換えることで、テーブルの浅いコピーを作成します。

add_column

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • i (int) — 列を配置するインデックス。
  • field_ (Union[str, pyarrow.Field]) — 文字列が渡された場合、カラムのデータから型が推測されます。
  • column (Union[pyarrow.Array, List[pyarrow.Array]]) — カラムのデータ。

戻り値

datasets.table.Table

追加されたカラムを含む新しいテーブル。

Tableの指定した位置に列を追加します。

追加されたカラムを含む新しいテーブルが返され、元のテーブルオブジェクトは変更されません。

append_column

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • field_ (Union[str, pyarrow.Field]) — 文字列が渡された場合、カラムのデータから型が推測されます。
  • column (Union[pyarrow.Array, List[pyarrow.Array]]) — カラムのデータ。

戻り値

datasets.table.Table

追加されたカラムを含む新しいテーブル。

列の末尾に列を追加します。

remove_column

< >

( i*args**kwargs ) → datasets.table.Table

パラメータ

  • i (int) — 削除する列のインデックス。

戻り値

datasets.table.Table

その列を削除した新しいテーブル。

指定された列を削除した新しいTableを作成します。

set_column

< >

( *args**kwargs ) → datasets.table.Table

パラメータ

  • i (int) — 列を配置するインデックス。
  • field_ (Union[str, pyarrow.Field]) — 文字列が渡された場合、カラムのデータから型が推測されます。
  • column (Union[pyarrow.Array, List[pyarrow.Array]]) — カラムのデータ。

戻り値

datasets.table.Table

渡されたカラムセットを持つ新しいテーブル。

Tableの指定された位置の列を置き換えます。

rename_columns

< >

( names*args**kwargs )

指定された名前に変更された列を持つ新しいテーブルを作成します。

select

< >

( columns*args**kwargs ) → datasets.table.Table

パラメータ

  • columns (Union[List[str], List[int]]) — 選択する列名または整数インデックス。

指定された列を持つ新しいテーブルで、メタデータは保持されます。

テーブルの列を選択します。

指定された列とメタデータを保持した新しいテーブルを返します。

drop

< >

( columns*args**kwargs ) → datasets.table.Table

パラメータ

  • columns (List[str]) — 既存の列を参照するフィールド名のリスト。

戻り値

datasets.table.Table

列を削除した新しいテーブル。

例外

KeyError

  • KeyError — : 渡された列名が存在しない場合。

1つ以上の列を削除し、新しいテーブルを返します。

from_blocks

< >

( blocks: ~TableBlockContainer )

from_tables

< >

( tables: listaxis: int = 0 )

パラメータ

  • tables (Table のリストまたは pyarrow.Table のリスト) — テーブルのリスト。
  • axis ({0, 1}, デフォルトは 0, 行方向を意味します) — 連結する軸。 0 は行方向(縦方向)の連結を、 1 は列方向(横方向)の連結を意味します。

    1.6.0で追加

テーブルのリストからConcatenationTableを作成します。

ユーティリティ

datasets.table.concat_tables

< >

( tables: listaxis: int = 0 ) → datasets.table.Table

パラメータ

  • tables (Table のリスト) — 連結するテーブルのリスト。
  • axis ({0, 1}, デフォルトは 0, 行方向を意味します) — 連結する軸。 0 は行方向(縦方向)の連結を、 1 は列方向(横方向)の連結を意味します。

    1.6.0で追加

戻り値

datasets.table.Table

入力テーブルの数が 1 より大きい場合、返されるテーブルは datasets.table.ConcatenationTable になります。 一方、テーブルが 1 つしかない場合は、そのまま返されます。

テーブルを連結します。

datasets.table.list_table_cache_files

< >

( table: Table ) → List[str]

戻り値

List[str]

テーブルによって読み込まれるキャッシュファイルへのパスのリスト。

テーブルによって読み込まれるキャッシュファイルを取得します。 テーブルの一部がメモリマッピングを介してディスクから読み込まれる場合に、キャッシュファイルが使用されます。

Update on GitHub