spreadsheetDatastore
用于电子表格文件的数据存储
说明
对于不一定能放入内存的大型电子表格文件集合,可以使用 spreadsheetDatastore
对象来进行管理。您可以使用 spreadsheetDatastore
函数创建 spreadsheetDatastore
对象,指定其属性,然后使用对象函数导入数据。
创建对象
描述
使用一个或多个名称-值参量为 ssds
= spreadsheetDatastore(location
,Name,Value
)ssds
指定其他参数和属性。例如,spreadsheetDatastore(location,"FileExtensions",[".xlsx",".xls"])
指定根据文件扩展名要在数据存储中包含哪些文件。
输入参量
要包含在数据存储中的文件或文件夹,指定为以下值之一:
FileSet
对象 - 与指定路径或DsFileSet
对象相比,将位置指定为FileSet
对象会加快数据存储的构造时间。有关详细信息,请参阅matlab.io.datastore.FileSet
。DsFileSet
对象 - 有关详细信息,请参阅matlab.io.datastore.DsFileSet
。文件路径 - 您可以将单个文件路径指定为字符串标量或字符向量。您可以将多个文件路径指定为字符串数组或字符向量元胞数组。
文件或文件夹可以是本地或远程的:
本地文件或文件夹 - 如果文件不在当前文件夹中,则指定完整路径或相对路径。指定文件夹的子文件夹中的文件不会自动包括在数据存储中。在指定本地路径时可以使用通配符 (*)。此字符指定数据存储包含所有匹配的文件或匹配文件夹中的所有文件。
远程文件或文件夹 - 将远程文件或文件夹的完整路径指定为
hdfs:///
形式的统一资源定位器 (URL)。Internet URL 必须包含协议类型path_to_file
"http://"
或"https://"
。在 URL 的任何位置使用通配符指定多个远程文件 (自 R2025a 起)。有关详细信息,请参阅处理远程数据。
当您指定文件夹时,数据存储仅包括具有支持的文件格式的文件,而忽略任何其他格式的文件。要指定要包含在数据存储中的自定义文件扩展名列表,请参阅 FileExtensions
名称-值参量。
spreadsheetDatastore
函数支持扩展名为 .xls
、.xlsx
、.xlsm
、.xltx
和 .xltm
的文件。
示例: "file1.xlsx"
示例: "../dir/data/file1.xlsx"
示例: ["C:\dir\data\file1.xlsx","C:\dir\data\file2.xlsx"]
示例: "s3://bucketname/path_to_files/*.xls"
名称-值参数
以 Name1=Value1,...,NameN=ValueN
的形式指定可选参量对组,其中 Name
是参量名称,Value
是对应的值。名称-值参量必须出现在其他参量之后,但参量对组的顺序无关紧要。
示例: ssds = spreadsheetDatastore("C:\dir\spreadsheetdata",FileExtensions=[".xls",".xlsm"])
在 R2021a 之前,使用逗号分隔每个名称和值,并用引号将 Name
引起来。
示例: ssds = spreadsheetDatastore("C:\dir\spreadsheetdata","FileExtensions",[".xls",".xlsm"])
电子表格文件扩展名,指定为名称-值参量,其中包含 "FileExtensions"
和一个字符向量、字符向量元胞数组、字符串标量或字符串数组。
如果不指定
"FileExtensions"
,则spreadsheetDatastore
会自动包含指定路径中具有.xls
、.xlsx
、.xlsm
、.xltx
和.xltm
扩展名的所有文件。如果要在
SpreadsheetDatastore
中包含具有非标准文件扩展名的电子表格,请显式指定这些扩展名。如果要为没有任何扩展名的文件创建
SpreadsheetDatastore
,请将"FileExtensions"
指定为空字符向量''
。
示例: "FileExtensions",''
示例: "FileExtensions",".xls"
示例: "FileExtensions",[".xlsx",".xlsm"]
数据类型: char
| cell
| string
子文件夹包含标记,指定为名称-值参量,其中包含 "IncludeSubfolders"
以及 true
、false
、0 或 1。指定 true
可包含每个文件夹中的所有文件和子文件夹,指定 false
则仅包含每个文件夹中的文件。
如果不指定 "IncludeSubfolders"
,则默认值为 false
。
示例: "IncludeSubfolders",true
数据类型: logical
| double
备用文件系统根路径,以名称-值参量形式指定,其中包含 "AlternateFileSystemRoots"
和一个字符串向量或元胞数组。当您在本地计算机上创建数据存储,但需要访问和处理另一台计算机(可能是不同操作系统)上的数据时,请使用 "AlternateFileSystemRoots"
。此外,如果您使用 Parallel Computing Toolbox™ 和 MATLAB® Parallel Server™ 处理数据,而数据存储在本地计算机上并且在不同平台云或集群计算机上存储数据副本,则必须使用 "AlternateFileSystemRoots"
关联根路径。
要关联一组等效的根路径,请将
"AlternateFileSystemRoots"
指定为字符串向量。例如,["Z:\datasets","/mynetwork/datasets"]
要将在数据存储方面等效的多组根路径关联起来,请将
"AlternateFileSystemRoots"
指定为包含多个行的元胞数组,其中每一行代表一组等效的根路径。将元胞数组中的每一行指定为一个字符串向量或字符向量元胞数组。例如:将
"AlternateFileSystemRoots"
指定为字符串向量元胞数组。{["Z:\datasets", "/mynetwork/datasets"];... ["Y:\datasets", "/mynetwork2/datasets","S:\datasets"]}
也可以将
"AlternateFileSystemRoots"
指定为字符向量元胞数组。{{'Z:\datasets','/mynetwork/datasets'};... {'Y:\datasets', '/mynetwork2/datasets','S:\datasets'}}
"AlternateFileSystemRoots"
的值必须满足以下条件:
包含一行或多行,每一行指定一组等效的根路径。
每一行指定多个根路径,每个根路径必须至少包含两个字符。
根路径是唯一的,并且不是彼此的子文件夹。
包含至少一个指向文件位置的根路径条目。
有关详细信息,请参阅Set Up Datastore for Processing on Different Machines or Clusters。
示例: ["Z:\datasets","/mynetwork/datasets"]
数据类型: string
| cell
文本变量的输出数据类型,指定为名称-值参量,其中包含 "TextType"
和 "char"
或 "string"
之一。
如果
read
、readall
或preview
函数的输出表包含文本变量,则"TextType"
指定这些变量的数据类型。如果
"TextType"
为"char"
,则输出为字符向量元胞数组。如果
"TextType"
为"string"
,则输出的类型为string
。
数据类型: char
| string
除了这些名称-值对组外,还可以指定本页上除 Files
属性之外的任何属性作为名称-值对组。
属性
SpreadsheetDatastore
属性描述数据存储对象中文件的格式,并控制如何从数据存储中读取数据。除了 Files
属性之外,您可以在创建数据存储对象时使用名称-值对组参量指定 SpreadsheetDatastore
属性的值。要在创建对象后查看或修改属性,请使用圆点表示法:
ds = spreadsheetDatastore("airlinesmall_subset.xlsx"); ds.Sheets = [1 2]; ds.Range = "A1:C6";
文件属性
包含在数据存储中的文件,解析为字符向量元胞数组或字符串数组,其中每个字符向量或字符串表示文件的一个完整路径。spreadsheetDatastore
和 datastore
函数中的 location
参量定义这些文件。
在元胞数组中指定的第一个文件确定数据存储中的所有文件的变量名称和格式信息。
示例: ["C:\dir\data\file1.xls";"C:\dir\data\file2.xls"]
数据类型: cell
| string
在读取时在每个工作表开头跳过的行数,指定为正整数。如果您还指定了 Range
属性,则 NumHeaderLines
是在指定的数据区域开头跳过的行数。
数据类型: double
文件中的工作表,指定为包含工作表名称的字符向量、字符向量元胞数组、字符串标量或字符串数组,或者指定为工作表索引的数值向量。空字符向量 ''
表示包含文件中的所有工作表。
示例: ["sheet1","sheet7"]
示例: [3 5 7]
数据类型: char
| cell
| string
| double
行和列的边界,指定为字符向量或字符串标量,用于在工作表中定义一个矩形数据区域。空字符向量 ''
表示边界就是文件的开头和数据的末尾。
示例: "B1:T7"
示例: "A:C"
数据类型: char
| string
将数据存储中的第一个文件的第一行读作变量名称的指示符,指定为 true
(1
) 或 false
(0
)。
如果为
true
,则第一个文件的第一个非标头行确定了数据的变量名称。如果为
false
,则第一个文件的第一个非标头行包含第一行数据。默认的变量名称指定为Var1
、Var2
等。
数据类型: logical
| double
保留变量名称的标志,指定为 "modify"
或 "preserve"
。
"modify"
- 将无效变量名称(由isvarname
函数确定)转换为有效的 MATLAB 标识符。"preserve"
- 保留作为无效 MATLAB 标识符的变量名称,如包含空白和非 ASCII 字符的变量名称。
从 R2019b 开始,变量名称和行名称可以包含任何字符,包括空格和非 ASCII 字符。此外,它们可以由任何字符(而不仅仅是字母)开头。变量名称和行名称可以不是有效的 MATLAB 标识符(由 isvarname
函数决定)。要保留这些变量名称和行名称,请将 VariableNamingRule
的值设置为 "preserve"
。当 VariableNamingRule
的值从 "modify"
更改为 "preserve"
时,变量名称不会刷新。
数据类型: char
| string
数据存储中变量的名称,指定为字符向量、字符向量元胞数组、字符串标量或字符串数组。按变量显示在文件中的顺序指定变量名称。如果不指定变量名称,数据存储会从第一个文件的第一个非标头行中检测它们。您可以用字符向量或字符串标量指定 VariableNames
,但是,数据存储会转换属性值并将其存储为字符向量元胞数组。修改 VariableNames
属性时,新变量名称的数量必须与原始变量名称的数量匹配。
要支持无效的 MATLAB 标识符作为变量名称,例如包含空白和非 ASCII 字符的变量名称,请将 VariableNamingRule
参数的值设置为 "preserve"
。
如果 ReadVariableNames
为 false
,则 VariableNames
默认为 ["Var1","Var2", ...]
。
示例: ["Time","Date","Quantity"]
数据类型: char
| cell
| string
变量类型,指定为 "double"
、"char"
、"string"
、"categorical"
或 "datetime"
,表示读取数据时每个变量的类型。
以下变量类型列表对应于 VariableNames
中的变量。类型 double
、char
和 datetime
可以自动从数据中检测。您可以将 VariableTypes
指定为字符向量或字符串标量,但 spreadsheetDatastore
会自动将它转换为字符向量元胞数组或字符串数组。
示例: ["char","categorical"]
数据类型: char
| cell
| string
preview
、read
、readall
表的属性
要从文件中读取的变量,指定为字符向量、字符向量元胞数组、字符串标量或字符串数组。每个字符向量或字符串包含一个变量的名称。可按任何顺序指定变量名称。您可以使用字符向量或字符串标量指定 SelectedVariableNames
,但 spreadsheetDatastore
会自动将它转换为字符向量元胞数组或字符串数组。
要支持无效的 MATLAB 标识符作为变量名称,例如包含空白和非 ASCII 字符的变量名称,请将 VariableNamingRule
参数的值设置为 "preserve"
。
示例: ["Var3","Var7","Var4"]
数据类型: char
| cell
| string
选定变量的类型,指定为 "double"
、"char"
、"string"
、"categorical"
或 "datetime"
,表示读取数据时每个选定变量的类型。以下变量类型列表对应于 SelectedVariableNames
中的变量。类型 double
、char
和 datetime
可以自动从数据中检测。您可以将 SelectedVariableTypes
指定为字符向量或字符串标量,但它会自动转换为字符向量元胞数组或字符串数组。
示例: ["double","datetime"]
数据类型: char
| cell
| string
要读取到 read
函数调用中的数据量,指定为 "file"
或 "sheet"
,或指定为正整数标量。
如果
ReadSize
为"file"
,则每次调用read
都会按照一次读取一个文件的方式读取所有数据。如果
ReadSize
为"sheet"
,则每次调用read
都会按照一次读取一个工作表的方式读取所有数据。如果
ReadSize
是正整数,则每次调用read
都会读取ReadSize
指定的行数(如果已到数据末尾,则可能小于此值)。
如果您将 ReadSize
从整数标量更改为 "file"
或 "sheet"
,或者进行相反的更改,数据存储将使用 reset
函数重置。
数据类型: char
| string
| double
行时间变量的名称,以名称-值参量形式指定,其中包含 "RowTimes"
和变量名称(如 "Date"
)或变量索引(如 3
)。
RowTimes
是与时间表相关的参数。时间表的每行都与一个时间相关联,该时间是在时间表的时间向量中捕获的。RowTimes
中指定的变量必须包含 datetime
或 duration
向量。
如果 "OutputType"
的值是 "timetable"
,但您没有指定 "RowTimes"
,则 spreadsheetDatastore
使用第一个 datetime
或 duration
变量作为时间表的行时间。
writeall
使用的属性
此 属性 为只读。
用于构造数据存储的文件夹,以字符向量元胞数组形式返回。该元胞数组定向为一个列向量。每个字符向量均为指向一个包含数据文件的文件夹的路径。创建数据存储时,spreadsheetDatastore
和 datastore
函数中的 location
参量用来定义 Folders
。
当您修改 SpreadsheetDatastore
对象的 Files
属性时,将重置 Folders
属性。
数据类型: cell
此 属性 为只读。
支持写入的格式,以字符串组成的行向量形式返回。此属性指定使用 writeall
从数据存储写入输出文件时可能的输出格式。
对象函数
hasdata | 确定是否有数据可读取 |
numpartitions | 数据存储分区数 |
partition | 划分数据存储 |
preview | 预览数据存储中的数据子集 |
read | 读取数据存储中的数据 |
readall | 读取数据存储中的所有数据 |
writeall | 将数据存储写入文件 |
reset | 将数据存储重置为初始状态 |
sheetnames | 从数据存储中查询工作表名称 |
transform | 变换数据存储 |
combine | 合并来自多个数据存储的数据 |
isPartitionable | 确定数据存储是否可分区 |
isSubsettable | Determine whether datastore is subsettable |
isShuffleable | 确定数据存储是否可乱序 |
示例
使用 FileSet 对象或文件路径创建一个 spreadsheetDatastore 对象。
创建一个 FileSet 对象。创建一个 spreadsheetDatastore 对象。
fs = matlab.io.datastore.FileSet("airlinesmall_subset.xlsx");
ssds = spreadsheetDatastore(fs)
ssds = SpreadsheetDatastore with properties: Files: { ' ...\Documents\MATLAB\Examples\airlinesmall_subset.xlsx' } Folders: { ' ...\Documents\MATLAB\Examples' } AlternateFileSystemRoots: {} Sheets: '' Range: '' Sheet Format Properties: NumHeaderLines: 0 VariableNamingRule: 'modify' ReadVariableNames: true VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more} VariableTypes: {'double', 'double', 'double' ... and 26 more} Properties that control the table returned by preview, read, readall: SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more} SelectedVariableTypes: {'double', 'double', 'double' ... and 26 more} ReadSize: 'file' OutputType: 'table' RowTimes: [] Write-specific Properties: SupportedOutputFormats: ["txt" "csv" "xlsx" "xls" "parquet" "parq"] DefaultOutputFormat: "xlsx"
您也可以使用文件路径指定数据。
ssds = spreadsheetDatastore("airlinesmall_subset.xlsx");
创建包含文件 airlinesmall_subset.xlsx
的 SpreadsheetDatastore
对象。
ssds = spreadsheetDatastore("airlinesmall_subset.xlsx")
ssds = SpreadsheetDatastore with properties: Files: { ' ...\Documents\MATLAB\Examples\airlinesmall_subset.xlsx' } Folders: { ' ...\Documents\MATLAB\Examples' } AlternateFileSystemRoots: {} Sheets: '' Range: '' Sheet Format Properties: NumHeaderLines: 0 VariableNamingRule: 'modify' ReadVariableNames: true VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more} VariableTypes: {'double', 'double', 'double' ... and 26 more} Properties that control the table returned by preview, read, readall: SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more} SelectedVariableTypes: {'double', 'double', 'double' ... and 26 more} ReadSize: 'file' OutputType: 'table' RowTimes: [] Write-specific Properties: SupportedOutputFormats: ["txt" "csv" "xlsx" "xls" "parquet" "parq"] DefaultOutputFormat: "xlsx"
显示文件的工作表名称。文件中针对每一年包含一个工作表。
sheetnames(ssds,1)
ans = 13x1 string
"1996"
"1997"
"1998"
"1999"
"2000"
"2001"
"2002"
"2003"
"2004"
"2005"
"2006"
"2007"
"2008"
在第二个工作表中指定变量 FlightNum
作为感兴趣的数据,并预览前八行。
ssds.Sheets = 2;
ssds.SelectedVariableNames = "FlightNum";
preview(ssds)
ans=8×1 table
FlightNum
_________
1014
1201
702
1184
1310
1759
1242
1558
只读取第一个工作表中变量 DepTime
和 ArrTime
的前三行。
ssds.ReadSize = 3; ssds.Sheets = 1; ssds.SelectedVariableNames = ["DepTime","ArrTime"]; read(ssds)
ans=3×2 table
DepTime ArrTime
_______ _______
2117 2305
1252 1511
1441 1708
读取所有工作表,包括四、五、六。
ssds.Sheets = 4:6; readall(ssds);
使用 OutputType
和 RowTimes
名称-值对组来使 SpreadsheetDatastore
返回时间表,而不是表。
为 tsunamis_dated.xlsx
创建一个数据存储。指定 "OutputType"
为 "timetable"
,以使 SpreadsheetDatastore
返回时间表而不是表。
ssds = spreadsheetDatastore("tsunamis_dated.xlsx","OutputType","timetable"); preview(ssds)
ans=8×15 timetable
Date Latitude Longitude ValidityCode Validity CauseCode Cause EarthquakeMagnitude Country Location MaxHeight IidaMagnitude Intensity NumDeaths DescDeaths Time
___________ ________ _________ ____________ ____________________ _________ ____________________________ ___________________ _____________ ____________________________ _________ _____________ _________ _________ __________ ________________________
04-Mar-1952 42.15 143.85 4 {'definite tsunami'} 1 {'Earthquake' } 8.1 {'JAPAN' } {'SE. HOKKAIDO ISLAND' } 6.5 2.7 2 33 1 04-Mar-1952 01:22:41.000
10-Jul-1958 58.34 -136.52 4 {'definite tsunami'} 3 {'Earthquake and Landslide'} 8.3 {'USA' } {'SE. ALASKA, AK' } 524.26 4.6 5 5 1 10-Jul-1958 06:15:53.600
22-May-1960 -39.5 -74.5 4 {'definite tsunami'} 1 {'Earthquake' } 9.5 {'CHILE' } {'CENTRAL CHILE' } 25 4.6 4 1260 3 22-May-1960 19:11:17.000
20-Nov-1960 -6.8 -80.7 4 {'definite tsunami'} 1 {'Earthquake' } 6.8 {'PERU' } {'PERU' } 9 3.2 2.5 66 2 20-Nov-1960 22:01:56.400
28-Mar-1964 61.1 -147.5 4 {'definite tsunami'} 3 {'Earthquake and Landslide'} 9.2 {'USA' } {'PRINCE WILLIAM SOUND, AK'} 67 6.1 5 221 3 28-Mar-1964 03:36:14.000
16-Jun-1964 38.65 139.2 4 {'definite tsunami'} 1 {'Earthquake' } 7.5 {'JAPAN' } {'NW. HONSHU ISLAND' } 5.8 2.7 2 26 1 16-Jun-1964 04:01:44.300
14-Aug-1968 0.2 119.8 4 {'definite tsunami'} 1 {'Earthquake' } 7.8 {'INDONESIA'} {'BANDA SEA' } 10 3.3 3 200 3 14-Aug-1968 22:14:19.400
23-Feb-1969 -3.1 118.9 4 {'definite tsunami'} 1 {'Earthquake' } 6.9 {'INDONESIA'} {'MAKASSAR STRAIT' } 4 2 2 600 3 23-Feb-1969 00:36:56.600
如果您没有指定 "RowTimes"
,spreadsheetDatastore
将使用第一个日期时间或持续时间变量作为行时间。在本例中,将 Date
变量用于行时间。此数据有两个日期时间变量:Date
和 Time
。Date
变量不包括小时、分钟或秒的信息,而 Time
变量有每个事件的具体时间。
指定 "RowTimes"
选项以使用事件时间(Time
变量)作为行时间。
ssds = spreadsheetDatastore("tsunamis_dated.xlsx","OutputType","timetable","RowTimes","Time"); preview(ssds)
ans=8×15 timetable
Time Latitude Longitude ValidityCode Validity CauseCode Cause EarthquakeMagnitude Country Location MaxHeight IidaMagnitude Intensity NumDeaths DescDeaths Date
________________________ ________ _________ ____________ ____________________ _________ ____________________________ ___________________ _____________ ____________________________ _________ _____________ _________ _________ __________ ___________
04-Mar-1952 01:22:41.000 42.15 143.85 4 {'definite tsunami'} 1 {'Earthquake' } 8.1 {'JAPAN' } {'SE. HOKKAIDO ISLAND' } 6.5 2.7 2 33 1 04-Mar-1952
10-Jul-1958 06:15:53.600 58.34 -136.52 4 {'definite tsunami'} 3 {'Earthquake and Landslide'} 8.3 {'USA' } {'SE. ALASKA, AK' } 524.26 4.6 5 5 1 10-Jul-1958
22-May-1960 19:11:17.000 -39.5 -74.5 4 {'definite tsunami'} 1 {'Earthquake' } 9.5 {'CHILE' } {'CENTRAL CHILE' } 25 4.6 4 1260 3 22-May-1960
20-Nov-1960 22:01:56.400 -6.8 -80.7 4 {'definite tsunami'} 1 {'Earthquake' } 6.8 {'PERU' } {'PERU' } 9 3.2 2.5 66 2 20-Nov-1960
28-Mar-1964 03:36:14.000 61.1 -147.5 4 {'definite tsunami'} 3 {'Earthquake and Landslide'} 9.2 {'USA' } {'PRINCE WILLIAM SOUND, AK'} 67 6.1 5 221 3 28-Mar-1964
16-Jun-1964 04:01:44.300 38.65 139.2 4 {'definite tsunami'} 1 {'Earthquake' } 7.5 {'JAPAN' } {'NW. HONSHU ISLAND' } 5.8 2.7 2 26 1 16-Jun-1964
14-Aug-1968 22:14:19.400 0.2 119.8 4 {'definite tsunami'} 1 {'Earthquake' } 7.8 {'INDONESIA'} {'BANDA SEA' } 10 3.3 3 200 3 14-Aug-1968
23-Feb-1969 00:36:56.600 -3.1 118.9 4 {'definite tsunami'} 1 {'Earthquake' } 6.9 {'INDONESIA'} {'MAKASSAR STRAIT' } 4 2 2 600 3 23-Feb-1969
局限性
MATLAB 不支持要求身份验证的 Internet URL。
MATLAB Online™ 支持与 Microsoft® OneDrive™ 文件和文件夹相关联的 Internet URL,而 MATLAB 的安装版本仅支持本地 OneDrive 文件。
版本历史记录
在 R2016a 中推出MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
选择网站
选择网站以获取翻译的可用内容,以及查看当地活动和优惠。根据您的位置,我们建议您选择:。
您也可以从以下列表中选择网站:
如何获得最佳网站性能
选择中国网站(中文或英文)以获得最佳网站性能。其他 MathWorks 国家/地区网站并未针对您所在位置的访问进行优化。
美洲
- América Latina (Español)
- Canada (English)
- United States (English)
欧洲
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)