fileDatastore

具有自定义文件读取器的数据存储

说明

对于不一定能放入内存的大型自定义格式文件集合或者不能放入内存的大型自定义格式文件，可以使用 FileDatastore 对象来管理。您可以使用 fileDatastore 函数创建 FileDatastore 对象，指定其属性，然后使用对象函数导入和处理数据。

创建对象

语法

fds = fileDatastore(location,"ReadFcn",@fcn)

fds = fileDatastore(location,"ReadFcn",@fcn,Name,Value)

描述

fds = fileDatastore(location,"ReadFcn",@fcn) 会根据由 location 指定的文件集合创建一个数据存储，并使用函数 fcn 从文件中读取数据。

fds = fileDatastore(location,"ReadFcn",@fcn,Name,Value) 使用一个或多个名称-值对组参量为 fds 指定其他参数和属性。例如，您可以使用 fileDatastore(location,"ReadFcn",@customreader,"FileExtensions",[".exts",".extx"]) 指定要根据文件扩展名将哪些文件包括在数据存储中。

示例

输入参量

全部展开

`location` — 要包括在数据存储中的文件或文件夹
`FileSet` | `DsFileSet` 对象 | 字符串数组 | 字符向量 | 字符向量元胞数组

要包含在数据存储中的文件或文件夹，指定为以下值之一：

FileSet 对象 - 与指定路径或 DsFileSet 对象相比，将位置指定为 FileSet 对象会加快数据存储的构造时间。有关详细信息，请参阅 matlab.io.datastore.FileSet。
DsFileSet 对象 - 有关详细信息，请参阅 matlab.io.datastore.DsFileSet。
文件路径 - 您可以将单个文件路径指定为字符串标量或字符向量。您可以将多个文件路径指定为字符串数组或字符向量元胞数组。

文件或文件夹可以是本地或远程的：

本地文件或文件夹 - 如果文件不在当前文件夹中，则指定完整路径或相对路径。指定文件夹的子文件夹中的文件不会自动包括在数据存储中。在指定本地路径时可以使用通配符 (*)。此字符指定数据存储包含所有匹配的文件或匹配文件夹中的所有文件。
远程文件或文件夹 - 将远程文件或文件夹的完整路径指定为 hdfs:///path_to_file 形式的统一资源定位器 (URL)。Internet URL 必须包含协议类型 "http://" 或 "https://"。在 URL 的任何位置使用通配符指定多个远程文件 (自 R2025a 起)。有关详细信息，请参阅处理远程数据。

当您指定文件夹时，数据存储仅包括具有支持的文件格式的文件，而忽略任何其他格式的文件。要指定要包含在数据存储中的自定义文件扩展名列表，请参阅 FileExtensions 名称-值参量。

示例: "file1.ext"

示例: "../dir/data/file1.ext"

示例: ["C:\dir\data\file1.exts","C:\dir\data\file2.extx"]

示例: "C:\dir\data\*.ext"

`@fcn` — 读取文件数据的函数
函数句柄

读取文件数据的函数，指定为函数句柄。

由函数句柄 @fcn 表示的函数签名取决于指定的 ReadMode 的值。读取文件数据的函数必须符合下列签名之一。

`ReadMode`	`ReadFcn` 签名
`"file"`（默认值）	函数必须具有以下签名： function data = MyReadFcn(filename) ... end `filename` - 要读取的文件的名称。 `data` - 对应的文件数据。
`"partialfile"`	函数必须具有以下签名： function [data,userdata,done] = MyReadFcn(filename,userdata) ... end `userdata` - 设置并读取 `userdata` 的字段，以便在多个 `FileDatastore` 读取调用之间保持数据。 `done` - 将此 `logical` 参量设置为 `true` 或 `false`。 `false` - 继续读取当前文件。 `true` - 终止当前文件读取并读取下一个文件。 `data` - 文件数据的一部分。
`"byte"`	函数必须具有以下签名： function data = MyReadFcn(filename,offset,size) ... end `offset` - 指定相对于文件中第一个字节的字节偏移量。 `size` - 指定当前读取操作期间要读取的字节数。 `data` - 具有 `BlockSize` 中指定的大小的文件数据部分。 `FileDatastore` 根据在 `BlockSize` 中指定的值同时递增 `offset` 和 `size` 输入。

ReadMode

ReadFcn 签名

"file"（默认值）

函数必须具有以下签名：

function data = MyReadFcn(filename)
...
end

filename - 要读取的文件的名称。

data - 对应的文件数据。

"partialfile"

函数必须具有以下签名：

function [data,userdata,done] = MyReadFcn(filename,userdata)
...
end

userdata - 设置并读取 userdata 的字段，以便在多个 FileDatastore 读取调用之间保持数据。

done - 将此 logical 参量设置为 true 或 false。

false - 继续读取当前文件。
true - 终止当前文件读取并读取下一个文件。

data - 文件数据的一部分。

"byte"

函数必须具有以下签名：

function data = MyReadFcn(filename,offset,size)
...
end

offset - 指定相对于文件中第一个字节的字节偏移量。

size - 指定当前读取操作期间要读取的字节数。

data - 具有 BlockSize 中指定的大小的文件数据部分。

FileDatastore 根据在 BlockSize 中指定的值同时递增 offset 和 size 输入。

@fcn 中指定的值将设置 ReadFcn 属性的值。

示例: @customreader

数据类型: function_handle

名称-值参数

全部展开

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

示例: fds = fileDatastore("C:\dir\data",FileExtensions=[".exts",".extx"])

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

示例: fds = fileDatastore("C:\dir\data","FileExtensions",[".exts",".extx"])

`IncludeSubfolders` — 子文件夹包含标记
`true` 或 `false` | 0 或 1

子文件夹包含标记，指定为以逗号分隔的对组，其中包含 "IncludeSubfolders" 以及 true、false、0 或 1。指定 true 可包含每个文件夹中的所有文件和子文件夹，指定 false 则仅包含每个文件夹中的文件。

如果不指定 "IncludeSubfolders"，则默认值为 false。

示例: "IncludeSubfolders",true

数据类型: logical | double

`FileExtensions` — 自定义格式的文件扩展名
字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

自定义格式的文件扩展名，指定为以逗号分隔的对组，其中包含 "FileExtensions" 和一个字符向量、字符向量元胞数组、字符串标量或字符串数组。

如果您指定了文件扩展名，fileDatastore 函数将只为具有指定扩展名的文件创建数据存储对象。您还可以通过将 "FileExtensions" 指定为空字符向量 ''，为没有任何扩展名的文件创建数据存储。如果不指定 "FileExtensions"，fileDatastore 会自动将所有文件包含在一个文件夹中。

示例: "FileExtensions",''

示例: "FileExtensions",".ext"

示例: "FileExtensions",[".exts",".extx"]

数据类型: char | cell | string

`PreviewFcn` — 用于预览输入数据的函数
`@ReadFcn` (默认) | 函数句柄

用于预览输入数据的函数，指定为函数句柄。

如果未指定预览函数，FileDatastore 将使用 @ReadFcn 中指定的值作为默认预览函数。您也可以为数据指定自己的自定义预览函数。

@ReadFcn（默认值）- 使用 ReadFcn 对 FileDatastore 数据进行采样。此选项会导致 tall 构造的性能下降。
Function handle - 对 FileDatastore 和 tall 构造使用自定义预览函数来对输入数据进行采样。使用 PreviewFcn 提供一个函数，该函数只读取预览和 tall 构造所需的最少的输入数据部分。

PreviewFcn 指定的函数必须返回与 ReadFcn 返回的数据类型相同的值。

数据类型: function_handle

`ReadMode` — 要读取的文件部分
`"file"` (默认) | `"partialfile"` | `"bytes"`

要读取的文件部分，指定为 "file"、"partialfile" 或 "bytes"。

"file"（默认值）

如果您在 ReadFcn 中指定的自定义函数在一次读取操作中读取完整文件，请使用 "file" 读取模式。

根据您的自定义读取函数，文件数据存储会在每次调用 read 时读取完整的文件。并行处理单元是一个完整文件。

"partialfile"

如果您在 ReadFcn 中指定的自定义文件读取函数在每次读取操作中仅读取文件的一部分，请使用 "partialfile" 读取模式。

根据您的自定义读取函数，每次调用 read 函数时，文件数据存储仅读取文件的一部分。

在 "partialfile" 读取模式下，并行处理单元是一个完整文件。读取一个完整文件需要连续进行多个 read 操作。

"bytes"

如果您在 ReadFcn 中指定的自定义函数在每次读取操作中读取 BlockSize 大小的文件部分，请使用 "bytes" 读取模式。

FileDatastore 将并行处理单元设置为包含 BlockSize 指定的字节数的文件块。

根据您的自定义读取函数，每次调用读取函数时，文件数据存储都会读取 BlockSize 大小的文件部分。读取一个完整文件需要并行进行多个 read 操作。

要对 FileDatastore 对象使用 subset 和 shuffle 函数，必须将 "ReadMode" 设置为 "file"。

数据类型: char | string

`BlockSize` — 要读取的字节数
`positive integer`

每次 read 操作要读取的字节数，指定为正整数。

为了确保您可以在多个并行的 MATLAB^® 工作单元之间分发文件的多个块，请将 BlockSize 指定为大于 131072 字节 (128 KB) 的正整数。

要指定或更改 BlockSize 的值，您必须首先将 ReadMode 设置为 "bytes"。FileDatastore 根据在 ReadMode 中指定的值设置 BlockSize 的默认值。

如果 ReadMode 是 "file" 或 "partialfile"，则 FileDatastore 将 BlockSize 的默认值设置为 inf。
如果 ReadMode 是 "bytes"，则 FileDatastore 将 BlockSize 的默认值设置为 128 MB。

`AlternateFileSystemRoots` — 备用文件系统根路径
字符串向量 | 元胞数组

备用文件系统根路径，以名称-值参量形式指定，其中包含 "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

属性

全部展开

FileDatastore 属性用于描述与 FileDatastore 对象关联的文件。除了 Files 属性，您还可以使用名称-值对组参量指定 FileDatastore 属性的值。要在创建对象后查看或修改属性，请使用圆点表示法。

`Files` — 包含在数据存储中的文件
字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

包含在数据存储中的文件，解析为字符向量、字符向量元胞数组、字符串标量或字符串数组，其中每个字符向量或字符串表示文件的一个完整路径。创建数据存储时，fileDatastore 和 datastore 函数中的 location 参量用来定义 Files。

示例: {"C:\dir\data\file1.ext";"C:\dir\data\file2.ext"}

示例: "hdfs:///data/*.mat"

数据类型: char | cell | string

`Folders` — 用于构造数据存储的文件夹
只读: 字符向量元胞数组

此属性为只读。

用于构造数据存储的文件夹，以字符向量元胞数组形式返回。该元胞数组定向为一个列向量。每个字符向量均为指向一个包含数据文件的文件夹的路径。创建数据存储时，fileDatastore 和 datastore 函数中的 location 参量用来定义 Folders。

当您修改 FileDatastore 对象的 Files 属性时，将重置 Folders 属性。

数据类型: cell

`ReadFcn` — 读取文件数据的函数
函数句柄

读取文件数据的函数，指定为函数句柄。

@fcn 指定的值设置 ReadFcn 属性的值。

示例: @MyCustomFileReader

数据类型: function_handle

`UniformRead` — 可垂直串联标志
只读: `false` (默认) | `true`

此属性为只读。

可垂直串联标志，指定为逻辑值 true 或 false。此属性的值在您首次创建 FileDatastore 对象时指定。

true

多次读取 FileDatastore 对象返回可垂直串联的统一数据。

当 UniformRead 属性值为 true 时：

ReadFcn 函数必须返回可垂直串联的数据；否则，readall 方法将返回错误。
tall 函数输出的基础数据类型与 ReadFcn 输出的数据类型相同。

false（默认值）

多次读取 FileDatastore 对象不返回可垂直串联的统一数据。

当 UniformRead 属性值为 false 时：

readall 返回元胞数组。
tall 返回 tall 元胞数组。

示例: fds = fileDatastore(location,"ReadFcn",@load,"UniformRead",true)

数据类型: logical | double

`SupportedOutputFormats` — 支持写入的格式
只读: 字符串行向量

此属性为只读。

支持写入的格式，以字符串组成的行向量形式返回。此属性指定使用 writeall 从数据存储写入输出文件时可能的输出格式。

对象函数

`hasdata`	确定是否有数据可读取
`numpartitions`	数据存储分区数
`partition`	划分数据存储
`preview`	预览数据存储中的数据子集
`read`	读取数据存储中的数据
`readall`	读取数据存储中的所有数据
`writeall`	将数据存储写入文件
`reset`	将数据存储重置为初始状态
`transform`	变换数据存储
`combine`	合并来自多个数据存储的数据
`isPartitionable`	确定数据存储是否可分区
`isSubsettable`	Determine whether datastore is subsettable
`isShuffleable`	确定数据存储是否可乱序
`shuffle`	对数据存储中的所有数据进行乱序处理
`subset`	创建数据存储或 FileSet 的子集

示例

全部折叠

创建 FileDatastore 对象

使用 FileSet 对象或文件路径创建一个 fileDatastore 对象。

创建一个 FileSet 对象。创建一个 fileDatastore 对象。

fs = matlab.io.datastore.FileSet("fluidtemp.mat");
fds = fileDatastore(fs,"ReadFcn",@load)

fds = 

  FileDatastore with properties:

                       Files: {
                              ' ...\matlab\toolbox\matlab\demos\fluidtemp.mat'
                              }
                     Folders: {
                              '...\matlab\toolbox\matlab\demos'
                              }
                 UniformRead: 0
                    ReadMode: 'file'
                   BlockSize: Inf
                  PreviewFcn: @load
      SupportedOutputFormats: ["txt"    "csv"    "dat"    "asc"    "xlsx"    "xls"    "parquet"    "parq"    "png"    …    ] (1×20 string)
                     ReadFcn: @load
    AlternateFileSystemRoots: {}

您也可以使用文件路径来创建 fileDatastore 对象。

fds = fileDatastore("fluidtemp.mat","ReadFcn",@load);

读取 MAT 文件的数据存储

创建一个数据存储，其中包含 MATLAB® demos 文件夹中的所有 .mat 文件，并指定 load 函数读取文件数据。

fds = fileDatastore(fullfile(matlabroot,"toolbox","matlab","demos"),"ReadFcn",@load,"FileExtensions",".mat")

fds = 

  FileDatastore with properties:
    
                       Files: {
                              '...\matlab\toolbox\matlab\demos\accidents.mat';
                              '...\matlab\toolbox\matlab\demos\airfoil.mat';
                              ' ...\matlab\toolbox\matlab\demos\airlineResults.mat'
                               ... and 38 more
                              }
                     Folders: {
                              '...\matlab\toolbox\matlab\demos'
                              }
                 UniformRead: 0
                    ReadMode: 'file'
                   BlockSize: Inf
                  PreviewFcn: @load
      SupportedOutputFormats: ["txt"    "csv"    "xlsx"    "xls"    "parquet"    "parq"    "png"    "jpg"    "jpeg"    "tif"    "tiff"    "wav"    "flac"    "ogg"    "mp4"    "m4a"]
                     ReadFcn: @load
    AlternateFileSystemRoots: {}

读取数据存储中的第一个文件，然后读取第二个文件。

data1 = read(fds);                   
data2 = read(fds);

同时读取数据存储中的所有文件。

readall(fds);

初始化元胞数组，以保留数据和计数器 i。

dataarray = cell(numel(fds.Files), 1);
i = 1;

将数据存储重置为第一个文件，然后一次读取一个文件，直到没有剩余数据。为数组 dataarray 分配数据。

reset(fds);                          
while hasdata(fds)                   
    dataarray{i} = read(fds);
    i = i+1;
end

从大型 MAT 文件中一次读取一个数组

打开实时脚本

您可以创建数据存储来读取不一定能放入内存的大型 MAT 文件。假设大型 MAT 文件中的每个数组都能放入可用内存，请创建一个数据存储，分三步读取和处理数据：

编写自定义读取函数，一次从 MAT 文件中读取一个数组。
设置数据存储函数的参数以执行部分读取。
一次从 MAT 文件中读取一个数组。

编写自定义函数，一次从 MAT 文件中读取一个数组。该函数必须具有 FileDatastore 的 @ReadFcn 参量中所述的签名。将此文件保存在工作文件夹或 MATLAB 路径上的文件夹中。对于本示例，此处包含自定义函数 load_variable。

type load_variable.m

function [data,variables,done] = load_variable(filename,variables)
    
    % If variable list is empty, 
    % create list of variables from the file
    if isempty(variables) 
        variables = who('-file', filename);
    end
    
    % Load a variable from the list of variables
    data = load(filename, variables{1});
    
    % Remove the newly-read variable from the list
    variables(1) = []; 
    
    % Move on to the next file if this file is done reading.
    done = isempty(variables); 
    
end

创建并设置一个包含 accidents.mat 的 FileDatastore。指定数据存储参数，以使用 "partialfile" 作为读取模式，load_variable 作为自定义读取函数。

fds = fileDatastore("accidents.mat","ReadMode","partialfile","ReadFcn",@load_variable);

使用数据存储从文件中读取前三个变量。文件 accidents.mat 包含九个变量，对 read 的每次调用都返回一个变量。因此，要获取前三个变量，请调用 read 函数三次。

data = read(fds)

data = struct with fields:
    datasources: {3×1 cell}

data = read(fds)

data = struct with fields:
    hwycols: 17

data = read(fds)

data = struct with fields:
    hwydata: [51×17 double]

请注意，示例文件 accidents.mat 很小，可放入内存，但对于无法放入内存的大型 MAT 文件，您可以获得类似的结果。

局限性

MATLAB 不支持要求身份验证的 Internet URL。
MATLAB Online™ 支持与 Microsoft^® OneDrive™ 文件和文件夹相关联的 Internet URL，而 MATLAB 的安装版本仅支持本地 OneDrive 文件。

提示

要对 FileDatastore 对象使用 subset 和 shuffle 函数，必须将 "ReadMode" 设置为 "file"。

版本历史记录

在 R2016a 中推出

全部展开

R2025a: 使用通配符指定多个远程文件

您可以从多个远程文件创建一个数据存储。在 URL 的任何位置使用通配符指定多个远程文件。

R2024b: 使用数据存储函数通过 HTTP 和 HTTPS 读取数据

您可以通过在 Internet URL 上执行数据存储操作，从主要在线数据源读取数据。

另请参阅

mapreduce | tall

fileDatastore

说明

创建对象

语法

描述

输入参量

location — 要包括在数据存储中的文件或文件夹 FileSet | DsFileSet 对象 | 字符串数组 | 字符向量 | 字符向量元胞数组

@fcn — 读取文件数据的函数 函数句柄

名称-值参数

IncludeSubfolders — 子文件夹包含标记 true 或 false | 0 或 1

FileExtensions — 自定义格式的文件扩展名 字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

PreviewFcn — 用于预览输入数据的函数 @ReadFcn (默认) | 函数句柄

ReadMode — 要读取的文件部分 "file" (默认) | "partialfile" | "bytes"

BlockSize — 要读取的字节数 positive integer

AlternateFileSystemRoots — 备用文件系统根路径 字符串向量 | 元胞数组

属性

Files — 包含在数据存储中的文件 字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

Folders — 用于构造数据存储的文件夹 只读: 字符向量元胞数组

ReadFcn — 读取文件数据的函数 函数句柄

UniformRead — 可垂直串联标志 只读: false (默认) | true

SupportedOutputFormats — 支持写入的格式 只读: 字符串行向量

对象函数

示例

创建 FileDatastore 对象

读取 MAT 文件的数据存储

从大型 MAT 文件中一次读取一个数组

局限性

提示

版本历史记录

R2025a: 使用通配符指定多个远程文件

R2024b: 使用数据存储函数通过 HTTP 和 HTTPS 读取数据

另请参阅

主题

`location` — 要包括在数据存储中的文件或文件夹
`FileSet` | `DsFileSet` 对象 | 字符串数组 | 字符向量 | 字符向量元胞数组

`@fcn` — 读取文件数据的函数
函数句柄

`IncludeSubfolders` — 子文件夹包含标记
`true` 或 `false` | 0 或 1

`FileExtensions` — 自定义格式的文件扩展名
字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

`PreviewFcn` — 用于预览输入数据的函数
`@ReadFcn` (默认) | 函数句柄

`ReadMode` — 要读取的文件部分
`"file"` (默认) | `"partialfile"` | `"bytes"`

`BlockSize` — 要读取的字节数
`positive integer`

`AlternateFileSystemRoots` — 备用文件系统根路径
字符串向量 | 元胞数组

`Files` — 包含在数据存储中的文件
字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

`Folders` — 用于构造数据存储的文件夹
只读: 字符向量元胞数组

`ReadFcn` — 读取文件数据的函数
函数句柄

`UniformRead` — 可垂直串联标志
只读: `false` (默认) | `true`

`SupportedOutputFormats` — 支持写入的格式
只读: 字符串行向量