docstr: Read (multiple) Parquet files as a single pyarrow.Table.
  
  Parameters
  ----------
  columns : List[str]
      Names of columns to read from the dataset. The partition fields
      are not automatically included.
  use_threads : bool, default True
      Perform multi-threaded column reads.
  use_pandas_metadata : bool, 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]]
docstr_tok: ["Read","(","multiple",")","Parquet","files","as","a","single","pyarrow.Table",".","Parameters","--","--","--","--","--","columns",":","List","[","str","]","Names","of","columns","to","read","from","the","dataset",".","The","partition","fields","are","not","automatically","included",".","use_threads",":","bool",",","default","True","Perform","multi-threaded","column","reads",".","use_pandas_metadata",":","bool",",","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","]","]"]
code: def read(
      self, columns=None, use_threads=True, use_pandas_metadata=False
  ):
      """
      Read (multiple) Parquet files as a single pyarrow.Table.
  
      Parameters
      ----------
      columns : List[str]
          Names of columns to read from the dataset. The partition fields
          are not automatically included.
      use_threads : bool, default True
          Perform multi-threaded column reads.
      use_pandas_metadata : bool, 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]]
      """
      # if use_pandas_metadata, we need to include index columns in the
      # column selection, to be able to restore those in the pandas DataFrame
      metadata = self.schema.metadata or {}
  
      if use_pandas_metadata:
          # if the dataset schema metadata itself doesn't have pandas
          # then try to get this from common file (for backwards compat)
          if b"pandas" not in metadata:
              common_metadata = self._get_common_pandas_metadata()
              if common_metadata:
                  metadata = common_metadata
  
      if columns is not None and use_pandas_metadata:
          if metadata and b"pandas" in metadata:
              # RangeIndex can be represented as dict instead of column name
              index_columns = [
                  col
                  for col in _get_pandas_index_columns(metadata)
                  if not isinstance(col, dict)
              ]
              columns = list(columns) + list(
                  set(index_columns) - set(columns)
              )
  
      table = self._dataset.to_table(
          columns=columns,
          filter=self._filter_expression,
          use_threads=use_threads,
      )
  
      # if use_pandas_metadata, restore the pandas metadata (which gets
      # lost if doing a specific `columns` selection in to_table)
      if use_pandas_metadata:
          if metadata and b"pandas" in metadata:
              new_metadata = table.schema.metadata or {}
              new_metadata.update({b"pandas": metadata[b"pandas"]})
              table = table.replace_schema_metadata(new_metadata)
  
      return table
  
imports: from collections import defaultdict
  from contextlib import nullcontext
  from functools import reduce
  import inspect
  import json
  import os
  import re
  import operator
  import warnings
  import pyarrow
  from pyarrow._parquet import ParquetReader, Statistics, FileMetaData, RowGroupMetaData, ColumnChunkMetaData, ParquetSchema, ColumnSchema, ParquetLogicalType, FileEncryptionProperties, FileDecryptionProperties, SortingColumn
  from pyarrow.fs import LocalFileSystem, FileSystem, FileType, _resolve_filesystem_and_path, _ensure_filesystem
  from pyarrow import filesystem
  from pyarrow.util import guid, _is_path_like, _stringify_path, _deprecate_api
label_desc: Use image node_id 5 for calling the ParquetDataset obj's underlying member method code with example usage: obj.read(columns, use_threads, use_pandas_metadata) and returns: table