parquetread

从 Parquet 文件中读取列数据

全页折叠

语法

T = parquetread(filename)

T = parquetread(filename,Name,Value)

说明

示例

T = parquetread(filename) 将 filename 中指定的 Parquet 文件读入表或时间表 T 中。

示例

T = parquetread(filename,Name,Value) 使用由一个或多个名称-值对组参量指定的附加选项将 Parquet 文件读入表或时间表中。

示例

全部折叠

将 Parquet 文件读入表中

打开实时脚本

获取 Parquet 文件的相关信息，将文件中的数据读入表中，然后将变量的子集读入表中。

为文件 outages.parquet 创建一个 ParquetInfo 对象。

info = parquetinfo('outages.parquet')

info = 
  ParquetInfo with properties:

               Filename: "/mathworks/devel/bat/filer/batfs1904-0/Bdoc24a.2528353/build/matlab/toolbox/matlab/demos/outages.parquet"
               FileSize: 44202
           NumRowGroups: 1
        RowGroupHeights: 1468
          VariableNames: ["Region"    "OutageTime"    "Loss"    "Customers"    "RestorationTime"    "Cause"]
          VariableTypes: ["string"    "datetime"    "double"    "double"    "datetime"    "string"]
    VariableCompression: ["snappy"    "snappy"    "snappy"    "snappy"    "snappy"    "snappy"]
       VariableEncoding: ["plain"    "plain"    "plain"    "plain"    "plain"    "plain"]
                Version: "2.0"

将文件中的数据读入表中，并显示前 10 行。

T = parquetread('outages.parquet');
T(1:10,:)

ans=10×6 table
      Region            OutageTime          Loss     Customers       RestorationTime             Cause      
    ___________    ____________________    ______    __________    ____________________    _________________

    "SouthWest"    01-Feb-2002 12:18:00    458.98    1.8202e+06    07-Feb-2002 16:50:00    "winter storm"   
    "SouthEast"    23-Jan-2003 00:49:00    530.14    2.1204e+05                     NaT    "winter storm"   
    "SouthEast"    07-Feb-2003 21:15:00     289.4    1.4294e+05    17-Feb-2003 08:14:00    "winter storm"   
    "West"         06-Apr-2004 05:44:00    434.81    3.4037e+05    06-Apr-2004 06:10:00    "equipment fault"
    "MidWest"      16-Mar-2002 06:18:00    186.44    2.1275e+05    18-Mar-2002 23:23:00    "severe storm"   
    "West"         18-Jun-2003 02:49:00         0             0    18-Jun-2003 10:54:00    "attack"         
    "West"         20-Jun-2004 14:39:00    231.29           NaN    20-Jun-2004 19:16:00    "equipment fault"
    "West"         06-Jun-2002 19:28:00    311.86           NaN    07-Jun-2002 00:51:00    "equipment fault"
    "NorthEast"    16-Jul-2003 16:23:00    239.93         49434    17-Jul-2003 01:12:00    "fire"           
    "MidWest"      27-Sep-2004 11:09:00    286.72         66104    27-Sep-2004 16:37:00    "equipment fault"

选择变量 Region、OutageTime、Cause 并将其导入表中，然后显示前 10 行。

SelVarNames = {'Region','OutageTime','Cause'};
T_subset = parquetread('outages.parquet','SelectedVariableNames',SelVarNames);
T_subset(1:10,:)

ans=10×3 table
      Region            OutageTime               Cause      
    ___________    ____________________    _________________

    "SouthWest"    01-Feb-2002 12:18:00    "winter storm"   
    "SouthEast"    23-Jan-2003 00:49:00    "winter storm"   
    "SouthEast"    07-Feb-2003 21:15:00    "winter storm"   
    "West"         06-Apr-2004 05:44:00    "equipment fault"
    "MidWest"      16-Mar-2002 06:18:00    "severe storm"   
    "West"         18-Jun-2003 02:49:00    "attack"         
    "West"         20-Jun-2004 14:39:00    "equipment fault"
    "West"         06-Jun-2002 19:28:00    "equipment fault"
    "NorthEast"    16-Jul-2003 16:23:00    "fire"           
    "MidWest"      27-Sep-2004 11:09:00    "equipment fault"

将 Parquet 文件读入时间表中

打开实时脚本

将文件中的数据读入 timetable 中，然后使用时间表函数来确定时间表是否规则且已排序。

将 outages.parquet 中的数据读入时间表中，并显示前 10 行。使用数据中的第二个变量 OutageTime 作为时间表的时间向量。

TT = parquetread('outages.parquet','RowTimes','OutageTime');
TT(1:10,:)

ans=10×5 timetable
         OutageTime           Region        Loss     Customers       RestorationTime             Cause      
    ____________________    ___________    ______    __________    ____________________    _________________

    01-Feb-2002 12:18:00    "SouthWest"    458.98    1.8202e+06    07-Feb-2002 16:50:00    "winter storm"   
    23-Jan-2003 00:49:00    "SouthEast"    530.14    2.1204e+05                     NaT    "winter storm"   
    07-Feb-2003 21:15:00    "SouthEast"     289.4    1.4294e+05    17-Feb-2003 08:14:00    "winter storm"   
    06-Apr-2004 05:44:00    "West"         434.81    3.4037e+05    06-Apr-2004 06:10:00    "equipment fault"
    16-Mar-2002 06:18:00    "MidWest"      186.44    2.1275e+05    18-Mar-2002 23:23:00    "severe storm"   
    18-Jun-2003 02:49:00    "West"              0             0    18-Jun-2003 10:54:00    "attack"         
    20-Jun-2004 14:39:00    "West"         231.29           NaN    20-Jun-2004 19:16:00    "equipment fault"
    06-Jun-2002 19:28:00    "West"         311.86           NaN    07-Jun-2002 00:51:00    "equipment fault"
    16-Jul-2003 16:23:00    "NorthEast"    239.93         49434    17-Jul-2003 01:12:00    "fire"           
    27-Sep-2004 11:09:00    "MidWest"      286.72         66104    27-Sep-2004 16:37:00    "equipment fault"

确定该时间表是否规则且已排序。规则时间表的连续行时间之间具有相同的时间间隔，已排序时间表具有按升序排列的行时间向量。

isregular(TT)

ans = logical
   0

issorted(TT)

ans = logical
   0

使用 sortrows 函数根据行时间对时间表进行排序，并显示排序后数据的前 10 行。

TT = sortrows(TT);
TT(1:10,:)

ans=10×5 timetable
         OutageTime           Region        Loss     Customers       RestorationTime             Cause       
    ____________________    ___________    ______    __________    ____________________    __________________

    01-Feb-2002 12:18:00    "SouthWest"    458.98    1.8202e+06    07-Feb-2002 16:50:00    "winter storm"    
    05-Mar-2002 17:53:00    "MidWest"      96.563    2.8666e+05    10-Mar-2002 14:41:00    "wind"            
    16-Mar-2002 06:18:00    "MidWest"      186.44    2.1275e+05    18-Mar-2002 23:23:00    "severe storm"    
    26-Mar-2002 01:59:00    "MidWest"      388.04    5.6422e+05    28-Mar-2002 19:55:00    "winter storm"    
    20-Apr-2002 16:46:00    "MidWest"       23141           NaN                     NaT    "unknown"         
    08-May-2002 20:34:00    "SouthWest"    50.732         34481    08-May-2002 22:21:00    "thunder storm"   
    18-May-2002 11:04:00    "MidWest"      1389.1    1.3447e+05    21-May-2002 01:22:00    "unknown"         
    20-May-2002 10:57:00    "NorthEast"    9116.6    2.4983e+06    21-May-2002 15:22:00    "unknown"         
    27-May-2002 09:44:00    "SouthEast"    237.28    1.7101e+05    27-May-2002 16:19:00    "wind"            
    02-Jun-2002 16:11:00    "SouthEast"         0             0    05-Jun-2002 05:55:00    "energy emergency"

使用行过滤器有条件地导入数据子集

打开实时脚本

通过使用行过滤器指定要导入的变量和行来导入一个数据子集。

要导入 outages.parquet 文件的一个子集，请创建一个过滤器，只导入 OutageTime、Region 和 Cause 变量。然后，细化该过滤器，确保只导入值满足特定条件的行。

rf = rowfilter(["OutageTime" "Region" "Cause"]);
rf2 = (rf.OutageTime > datetime("2013-02-01")) & (rf.Region == "NorthEast") & (rf.Cause == "winter storm");
d = parquetread("outages.parquet",RowFilter=rf2,SelectedVariableNames=["OutageTime" "Region" "Cause"])

d=6×3 table
         OutageTime           Region           Cause     
    ____________________    ___________    ______________

    09-Feb-2013 00:55:00    "NorthEast"    "winter storm"
    13-Feb-2013 01:44:00    "NorthEast"    "winter storm"
    25-Dec-2013 11:24:00    "NorthEast"    "winter storm"
    30-Dec-2013 11:40:00    "NorthEast"    "winter storm"
    22-Feb-2013 02:17:00    "NorthEast"    "winter storm"
    23-Feb-2013 01:53:00    "NorthEast"    "winter storm"

得到的经过过滤的数据的子集仅包含满足过滤条件的 6 个行和 3 个指定变量。

输入参数

全部折叠

`filename` — Parquet 文件的名称
字符向量 | 字符串标量

Parquet 文件的名称，指定为字符向量或字符串标量。parquetread 兼容 Parquet 1.0 或 Parquet 2.0 文件。

根据文件的位置，filename 可以采用下列形式之一。

位置

形式

当前文件夹或 MATLAB^® 路径上的文件夹

指定 filename 中文件的名称。

示例：'data.parquet'

文件夹中的文件

如果该文件不在当前文件夹或 MATLAB 路径下的文件夹中，则指定完整或相对路径名。

示例：'C:\myFolder\data.parquet'

示例：'myDir\myFile.ext'

Internet URL

如果文件指定为 Internet 统一资源定位器 (URL)，则 filename 必须包含协议类型 'http://' 或 'https://'，并以 '?raw=true' 结尾。

示例：'http://hostname/path_to_file/my_data.parquet?raw=true'

远程位置

如果文件存储在远程位置，则 filename 必须包含用以下格式指定的文件的完整路径：

scheme_name://path_to_file/my_file.ext

根据远程位置，scheme_name 可以是下表中的值之一。

远程位置	`scheme_name`
Amazon S3™	`s3`
Azure^® Blob 存储	`wasb`, `wasbs`
HDFS™	`hdfs`

有关详细信息，请参阅处理远程数据。

示例：'s3://bucketname/path_to_file/data.parquet'

parquetread 函数可以从 Parquet 文件中导入结构化数据。有关支持读取的 Parquet 数据类型的详细信息，请参阅 Apache Parquet Data Type Mappings。

数据类型: char | string

名称-值参数

将可选的参量对组指定为 Name1=Value1,...,NameN=ValueN，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但参量对组的顺序无关紧要。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: 'OutputType','table' 将 Parquet 文件中的数据作为表导入。

`OutputType` — 输出数据类型
`'auto'` (默认) | `'table'` | `'timetable'`

输出数据类型，指定为以逗号分隔的对组，其中包含 'OutputType' 以及 'auto'、'table' 或 'timetable'。

'auto' - 返回表或时间表。parquetread 根据您指定的其他名称-值对组检测输出应是表还是时间表。例如，当您设置与时间表相关的名称-值对组时，parquetread 推断输出是时间表。设置以下名称-值对组指示输出是时间表：RowTimes、StartTime、SampleRate 或 TimeStep。
'table' - 返回一个表。有关表数据类型的详细信息，请参阅 table。
'timetable' - 返回时间表。有关时间表数据类型的详细信息，请参阅 timetable。

示例: 'OutputType','timetable'

数据类型: char | string

`SelectedVariableNames` — 要导入的变量子集
字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

要导入的变量子集，指定为逗号分隔的对组，其中包含 'SelectedVariableNames' 和一个字符向量、字符串标量、字符向量元胞数组或字符串数组。

SelectedVariableNames 必须为 Parquet 文件中包含的变量名称的子集。要获取文件中所有变量的名称，请使用 ParquetInfo 对象的 VariableNames 属性。
如果您没有指定 SelectedVariableNames 名称-值对组，parquetread 将从文件中读取所有变量。

数据类型: char | string | cell

`RowTimes` — 行时间变量
变量名称 | 时间向量

行时间变量，指定为由 'RowTimes' 和变量名称或时间向量组成的以逗号分隔的对组。

变量名称必须为字符向量或字符串标量，其中包含输入表中任何具有 datetime 或 duration 值的变量的名称。变量名称指定的变量为行提供行时间标签。输入表的其余变量成为时间表的变量。
时间向量必须为 datetime 向量或 duration 向量。时间向量的元素数必须等于输入表的行数。时间向量中的时间值不必是唯一、已排序或规则的。输入表中的所有变量都成为时间表中的变量。

数据类型: char | string | datetime | duration

`StartTime` — 行时间的开始时间
日期时间标量 | 持续时间标量

行时间的开始时间，指定为由 StartTime 和一个日期时间标量或持续时间标量组成的逗号分隔对组。

如果开始时间是日期时间，则 T 的行时间是日期时间值。
如果开始时间是持续时间，则 T 的行时间是持续时间值。
如果时间步是日历持续时间值，则开始时间必须是日期时间值。

StartTime 是与时间表相关的参数。parquetread 函数使用 StartTime 以及 SampleRate 或 TimeStep 来定义输出 T 的时间向量。

数据类型: datetime | duration

`SampleRate` — 采样率
正数值标量

采样率，以逗号分隔的对组形式指定，该对组由 'SampleRate' 和一个正数值标量组成。采样率是输出时间表 T 的时间向量的每秒采样数 (Hz)。

SampleRate 是与时间表相关的参数。parquetread 函数使用 SampleRate 和其他时间表参数来定义输出 T 的时间向量。

数据类型: double

`RowGroups` — 要导入的行组的索引
正数值标量 | 正整数向量

要导入的行组的索引，指定为正整数标量或正整数向量，引用要读取的行组的索引。

如果指定标量，则该函数读取单个行组。
如果指定向量，则该函数将读取所有指定的行组。
如果不指定行组，则 parquetread 会导入整个文件。

示例: RowGroups=701:720

`RowFilter` — 用于选择要导入的行的过滤器
`matlab.io.RowFilter` 对象

用于选择要导入的行的过滤器，指定为 matlab.io.RowFilter 对象。matlab.io.RowFilter 对象指定每行要包含在输出表或时间表中必须满足的条件。如果不指定 RowFilter，则 parquetread 将从输入 Parquet 文件中导入所有行。

`TimeStep` — 时间向量的时间步
持续时间 | calendarDuration

时间向量的时间步，指定为由 'TimeStep' 和持续时间标量组成的以逗号分隔的对组。

如果将时间步指定为日历持续时间（例如，日历月），则行时间向量必须是日期时间向量。
如果将时间步指定为持续时间（例如，秒），则行时间向量可以是日期时间或持续时间向量。

TimeStep 是与时间表相关的参数。parquetread 函数使用 TimeStep 和其他时间表参数来定义输出 T 的时间向量。

`VariableNamingRule` — 保留变量名称的标志
`"modify"` (默认) | `"preserve"`

保留变量名称的标志，指定为 "modify" 或 "preserve"。

"modify" - 将无效变量名称（由 isvarname 函数确定）转换为有效的 MATLAB 标识符。
"preserve" - 保留作为无效 MATLAB 标识符的变量名称，如包含空白和非 ASCII 字符的变量名称。

从 R2019b 开始，变量名称和行名称可以包含任何字符，包括空格和非 ASCII 字符。此外，它们可以由任何字符（而不仅仅是字母）开头。变量名称和行名称可以不是有效的 MATLAB 标识符（由 isvarname 函数决定）。要保留这些变量名称和行名称，请将 VariableNamingRule 的值设置为 "preserve"。当 VariableNamingRule 的值从 "modify" 更改为 "preserve" 时，变量名称不会刷新。

数据类型: char | string

输出参量

全部折叠

`T` — 输出数据
表 | 时间表

输出数据，以表或时间表形式返回。parquetread 函数的输出取决于 OutputType 名称-值对组的值。有关详细信息，请参阅 OutputType 的名称-值对组说明。

局限性

在某些情况下，parquetwrite 创建的文件并不能准确表示原始数组 T。如果使用 parquetread 或 datastore 来读取文件，则结果可能与原始表的格式或内容不完全相同。有关详细信息，请参阅Apache Parquet Data Type Mappings。

扩展功能

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

此函数完全支持基于线程的环境。有关详细信息，请参阅在基于线程的环境中运行 MATLAB 函数。

版本历史记录

在 R2019a 中推出

全部展开

R2022b: 读取包含结构化数据的 Parquet 文件

将 Parquet 文件中的结构化数据作为嵌套表读取。

R2022b: 在基于线程的环境中使用函数

此函数支持基于线程的环境。

R2022a: 使用 `rowfilter` 有条件地过滤行，以便更高效地读取 Parquet 文件数据

使用 parquetread 和 parquetDatastore 时，有条件地从 Parquet 文件中更快地过滤和读取数据（谓词下推）。您可以使用 rowfilter 函数、matlab.io.RowFilter 对象和 RowFilter 名称-值参量来创建过滤条件。

R2022a: 确定和定义 Parquet 文件数据中的行组

Parquet 文件可以将一定范围的行存储为一个不同的行组，以提高粒度和进行有针对性的分析。parquetread 在读取 Parquet 文件数据时使用 RowGroups 名称-值参量来确定行组。parquetwrite 在写入 Parquet 文件数据时使用 RowGroupHeights 名称-值参量来定义行组。

R2022a: 导入嵌套的 Parquet 文件数据

现在，您可以通过以下方式导入嵌套 Parquet 文件数据：

LogicalType 作为 LIST。
LogicalType 作为 NONE，PhysicalType 作为 BYTE_ARRAY 或 FIXED_LEN_BYTE_ARRAY。

parquetread 函数转换这些数据架构并将其作为元胞数组导入。

R2021b: 使用原始时区读取和写入日期时间

Parquet 文件要求时区感知时间戳采用 UTC 时区。当写入日期时间时，parquetwrite 将它们转换为等效的 UTC 值，并将原始时区值存储在 Parquet 文件的元数据中。parquetread 使用存储的原始时区值来启用往复。

R2021a: 读取在线数据

通过将 filename 指定为包含协议类型 'http://' 或 'https://' 的字符串标量或字符向量，从 Internet URL 读取文件。

R2021a: 使用 Parquet 数据格式的分类数据

导入包含 categorical 数据类型的 Parquet 数据。

R2019b: 读取包含任意字符的表格数据

导入含有变量名称的表格数据（这些变量名称可以包含任何 Unicode 字符，包括空格和非 ASCII 字符）。要读取包含任意变量名称（如包含空格和非 ASCII 字符的变量名称）的表格数据，请将 PreserveVariableNames 参数设置为 true。

另请参阅

parquetread

语法

说明

示例

将 Parquet 文件读入表中

将 Parquet 文件读入时间表中

使用行过滤器有条件地导入数据子集

输入参数

filename — Parquet 文件的名称 字符向量 | 字符串标量

名称-值参数

OutputType — 输出数据类型 'auto' (默认) | 'table' | 'timetable'

SelectedVariableNames — 要导入的变量子集 字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

RowTimes — 行时间变量 变量名称 | 时间向量

StartTime — 行时间的开始时间 日期时间标量 | 持续时间标量

SampleRate — 采样率 正数值标量

RowGroups — 要导入的行组的索引 正数值标量 | 正整数向量

RowFilter — 用于选择要导入的行的过滤器 matlab.io.RowFilter 对象

TimeStep — 时间向量的时间步 持续时间 | calendarDuration

VariableNamingRule — 保留变量名称的标志 "modify" (默认) | "preserve"

输出参量

T — 输出数据 表 | 时间表

局限性

扩展功能

基于线程的环境 使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

版本历史记录

R2022b: 读取包含结构化数据的 Parquet 文件

R2022b: 在基于线程的环境中使用函数

R2022a: 使用 rowfilter 有条件地过滤行，以便更高效地读取 Parquet 文件数据

R2022a: 确定和定义 Parquet 文件数据中的行组

R2022a: 导入嵌套的 Parquet 文件数据

R2021b: 使用原始时区读取和写入日期时间

R2021a: 读取在线数据

R2021a: 使用 Parquet 数据格式的分类数据

R2019b: 读取包含任意字符的表格数据

另请参阅

WeChat

`filename` — Parquet 文件的名称
字符向量 | 字符串标量

`OutputType` — 输出数据类型
`'auto'` (默认) | `'table'` | `'timetable'`

`SelectedVariableNames` — 要导入的变量子集
字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组

`RowTimes` — 行时间变量
变量名称 | 时间向量

`StartTime` — 行时间的开始时间
日期时间标量 | 持续时间标量

`SampleRate` — 采样率
正数值标量

`RowGroups` — 要导入的行组的索引
正数值标量 | 正整数向量

`RowFilter` — 用于选择要导入的行的过滤器
`matlab.io.RowFilter` 对象

`TimeStep` — 时间向量的时间步
持续时间 | calendarDuration

`VariableNamingRule` — 保留变量名称的标志
`"modify"` (默认) | `"preserve"`

`T` — 输出数据
表 | 时间表

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

R2022a: 使用 `rowfilter` 有条件地过滤行，以便更高效地读取 Parquet 文件数据