pyarrow.parquet.ParquetDataset#

class pyarrow.parquet.ParquetDataset(path_or_paths, filesystem=None, schema=None, *, filters=None, read_dictionary=None, memory_map=False, buffer_size=None, partitioning='hive', ignore_prefixes=None, pre_buffer=True, coerce_int96_timestamp_unit=None, decryption_properties=None, thrift_string_size_limit=None, thrift_container_size_limit=None, page_checksum_verification=False, use_legacy_dataset=None)[source]#

Bases: object

Encapsulates details of reading a complete Parquet dataset possibly consisting of multiple files and partitions in subdirectories.

Parameters:

path_or_pathsstr or List[str]

A directory name, single file name, or list of file names.

filesystemFileSystem, default None

If nothing passed, will be inferred based on path. Path will try to be found in the local on-disk filesystem otherwise it will be parsed as an URI to determine the filesystem.

schemapyarrow.parquet.Schema

Optionally provide the Schema for the Dataset, in which case it will not be inferred from the source.

filterspyarrow.compute.Expression or List[Tuple] or List[List[Tuple]], default None

Rows which do not match the filter predicate will be removed from scanned data. Partition keys embedded in a nested directory structure will be exploited to avoid loading files at all if they contain no matching rows. Within-file level filtering and different partitioning schemes are supported.

Predicates are expressed using an Expression or using the disjunctive normal form (DNF), like [[('x', '=', 0), ...], ...]. DNF allows arbitrary boolean logical combinations of single column predicates. The innermost tuples each describe a single column predicate. The list of inner predicates is interpreted as a conjunction (AND), forming a more selective and multiple column predicate. Finally, the most outer list combines these filters as a disjunction (OR).

Predicates may also be passed as List[Tuple]. This form is interpreted as a single conjunction. To express OR in predicates, one must use the (preferred) List[List[Tuple]] notation.

Each tuple has format: (key, op, value) and compares the key with the value. The supported op are: = or ==, !=, <, >, <=, >=, in and not in. If the op is in or not in, the value must be a collection such as a list, a set or a tuple.

Examples:

Using the Expression API:

import pyarrow.compute as pc
pc.field('x') = 0
pc.field('y').isin(['a', 'b', 'c'])
~pc.field('y').isin({'a', 'b'})

Using the DNF format:

('x', '=', 0)
('y', 'in', ['a', 'b', 'c'])
('z', 'not in', {'a','b'})

read_dictionarylist, default None

List of names or column paths (for nested types) to read directly as DictionaryArray. Only supported for BYTE_ARRAY storage. To read a flat column as dictionary-encoded pass the column name. For nested types, you must pass the full column “path”, which could be something like level1.level2.list.item. Refer to the Parquet file’s schema to obtain the paths.

memory_mapbool, default False

If the source is a file path, use a memory map to read file, which can improve performance in some environments.

buffer_sizeint, default 0

If positive, perform read buffering when deserializing individual column chunks. Otherwise IO calls are unbuffered.

partitioningpyarrow.dataset.Partitioning or str or list of str, default “hive”

The partitioning scheme for a partitioned dataset. The default of “hive” assumes directory names with key=value pairs like “/year=2009/month=11”. In addition, a scheme like “/2009/11” is also supported, in which case you need to specify the field names or a full schema. See the pyarrow.dataset.partitioning() function for more details.

ignore_prefixeslist, optional

Files matching any of these prefixes will be ignored by the discovery process. This is matched to the basename of a path. By default this is [‘.’, ‘_’]. Note that discovery happens only if a directory is passed as source.

pre_bufferbool, default True

Coalesce and issue file reads in parallel to improve performance on high-latency filesystems (e.g. S3, GCS). If True, Arrow will use a background I/O thread pool. If using a filesystem layer that itself performs readahead (e.g. fsspec’s S3FS), disable readahead for best results. Set to False if you want to prioritize minimal memory usage over maximum speed.

coerce_int96_timestamp_unitstr, default None

Cast timestamps that are stored in INT96 format to a particular resolution (e.g. ‘ms’). Setting to None is equivalent to ‘ns’ and therefore INT96 timestamps will be inferred as timestamps in nanoseconds.

decryption_propertiesFileDecryptionProperties or None

File-level decryption properties. The decryption properties can be created using CryptoFactory.file_decryption_properties().

thrift_string_size_limitint, default None

If not None, override the maximum total string size allocated when decoding Thrift structures. The default limit should be sufficient for most Parquet files.

thrift_container_size_limitint, default None

If not None, override the maximum total size of containers allocated when decoding Thrift structures. The default limit should be sufficient for most Parquet files.

page_checksum_verificationbool, default False

If True, verify the page checksum for each page read from the file.

use_legacy_datasetbool, optional

Deprecated and has no effect from PyArrow version 15.0.0.

Examples

Generate an example PyArrow Table and write it to a partitioned dataset:

>>> import pyarrow as pa
>>> table = pa.table({'year': [2020, 2022, 2021, 2022, 2019, 2021],
...                   'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_to_dataset(table, root_path='dataset_v2',
...                     partition_cols=['year'])

create a ParquetDataset object from the dataset source:

>>> dataset = pq.ParquetDataset('dataset_v2/')

and read the data:

>>> dataset.read().to_pandas()
   n_legs         animal  year
     5  Brittle stars  2019
     2       Flamingo  2020
     4            Dog  2021
   100      Centipede  2021
     2         Parrot  2022
     4          Horse  2022

create a ParquetDataset object with filter:

>>> dataset = pq.ParquetDataset('dataset_v2/',
...                             filters=[('n_legs','=',4)])
>>> dataset.read().to_pandas()
   n_legs animal  year
0       4    Dog  2021
1       4  Horse  2022

__init__(path_or_paths, filesystem=None, schema=None, *, filters=None, read_dictionary=None, memory_map=False, buffer_size=None, partitioning='hive', ignore_prefixes=None, pre_buffer=True, coerce_int96_timestamp_unit=None, decryption_properties=None, thrift_string_size_limit=None, thrift_container_size_limit=None, page_checksum_verification=False, use_legacy_dataset=None)[source]#

Methods

`__init__`(path_or_paths[, filesystem, ...])
`equals`(other)
`read`([columns, use_threads, use_pandas_metadata])	Read (multiple) Parquet files as a single pyarrow.Table.
`read_pandas`(**kwargs)	Read dataset including pandas metadata, if any.

Attributes

`files`	A list of absolute Parquet file paths in the Dataset source.
`filesystem`	The filesystem type of the Dataset source.
`fragments`	A list of the Dataset source fragments or pieces with absolute file paths.
`partitioning`	The partitioning of the Dataset source, if discovered.
`schema`	Schema of the Dataset.

equals(other)[source]#

property files#

A list of absolute Parquet file paths in the Dataset source.

Examples

Generate an example dataset:

>>> import pyarrow as pa
>>> table = pa.table({'year': [2020, 2022, 2021, 2022, 2019, 2021],
...                   'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_to_dataset(table, root_path='dataset_v2_files',
...                     partition_cols=['year'])
>>> dataset = pq.ParquetDataset('dataset_v2_files/')

List the files:

>>> dataset.files
['dataset_v2_files/year=2019/...-0.parquet', ...

property filesystem#: The filesystem type of the Dataset source.

property fragments#

A list of the Dataset source fragments or pieces with absolute file paths.

Examples

Generate an example dataset:

>>> import pyarrow as pa
>>> table = pa.table({'year': [2020, 2022, 2021, 2022, 2019, 2021],
...                   'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_to_dataset(table, root_path='dataset_v2_fragments',
...                     partition_cols=['year'])
>>> dataset = pq.ParquetDataset('dataset_v2_fragments/')

List the fragments:

>>> dataset.fragments
[<pyarrow.dataset.ParquetFileFragment path=dataset_v2_fragments/...

property partitioning#: The partitioning of the Dataset source, if discovered.

read(columns=None, use_threads=True, use_pandas_metadata=False)[source]#

Read (multiple) Parquet files as a single pyarrow.Table.

Parameters:

columnsList[str]: Names of columns to read from the dataset. The partition fields are not automatically included.
use_threadsbool, default True: Perform multi-threaded column reads.
use_pandas_metadatabool, default False: If True and file has custom pandas schema metadata, ensure that index columns are also loaded.

Returns:

pyarrow.Table: Content of the file as a table (of columns).

Examples

Generate an example dataset:

>>> import pyarrow as pa
>>> table = pa.table({'year': [2020, 2022, 2021, 2022, 2019, 2021],
...                   'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_to_dataset(table, root_path='dataset_v2_read',
...                     partition_cols=['year'])
>>> dataset = pq.ParquetDataset('dataset_v2_read/')

Read the dataset:

>>> dataset.read(columns=["n_legs"])
pyarrow.Table
n_legs: int64
----
n_legs: [[5],[2],[4,100],[2,4]]

read_pandas(**kwargs)[source]#

Read dataset including pandas metadata, if any. Other arguments passed through to read(), see docstring for further details.

Parameters:

**kwargsoptional: Additional options for read()

Examples

Generate an example parquet file:

>>> import pyarrow as pa
>>> import pandas as pd
>>> df = pd.DataFrame({'year': [2020, 2022, 2021, 2022, 2019, 2021],
...                    'n_legs': [2, 2, 4, 4, 5, 100],
...                    'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                    "Brittle stars", "Centipede"]})
>>> table = pa.Table.from_pandas(df)
>>> import pyarrow.parquet as pq
>>> pq.write_table(table, 'table_V2.parquet')
>>> dataset = pq.ParquetDataset('table_V2.parquet')

Read the dataset with pandas metadata:

>>> dataset.read_pandas(columns=["n_legs"])
pyarrow.Table
n_legs: int64
----
n_legs: [[2,2,4,4,5,100]]

>>> dataset.read_pandas(columns=["n_legs"]).schema.pandas_metadata
{'index_columns': [{'kind': 'range', 'name': None, 'start': 0, ...}

property schema#

Schema of the Dataset.

Examples

Generate an example dataset:

>>> import pyarrow as pa
>>> table = pa.table({'year': [2020, 2022, 2021, 2022, 2019, 2021],
...                   'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_to_dataset(table, root_path='dataset_v2_schema',
...                     partition_cols=['year'])
>>> dataset = pq.ParquetDataset('dataset_v2_schema/')

Read the schema:

>>> dataset.schema
n_legs: int64
animal: string
year: dictionary<values=int32, indices=int32, ordered=0>