datastore

为大型数据集合创建数据存储

全页折叠

语法

ds = datastore(location)

ds = datastore(location,Name,Value)

说明

ds = datastore(location) 根据 location 指定的数据集合创建一个数据存储。数据存储是一个存储库，用于收集由于体积太大而无法载入内存的数据。创建 ds 后，您可以读取并处理数据。

示例

ds = datastore(location,Name,Value) 使用一个或多个名称-值对组参量为 ds 指定其他参数。例如，您可以通过指定 'Type','image' 为图像文件创建数据存储。

示例

全部折叠

为文本数据创建数据存储

创建一个与示例文件 airlinesmall.csv 关联的数据存储。此文件包含从 1987 至 2008 年的航空公司数据。

要控制如何在数值列中导入缺失的数据，请使用 "TreatAsMissing" 和 "MissingValue" 名称-值参量。通过将 "TreatAsMissing" 的值指定为 "NA" 并将 "MissingValue" 的值指定为 0，在导入的数据中用 0 替换每个 "NA" 实例。

ds = datastore("airlinesmall.csv","TreatAsMissing","NA",...
               "MissingValue",0)

ds = 
  TabularTextDatastore with properties:

                      Files: {
                             'B:\matlab\toolbox\matlab\demos\airlinesmall.csv'
                             }
                    Folders: {
                             'B:\matlab\toolbox\matlab\demos'
                             }
               FileEncoding: 'UTF-8'
   AlternateFileSystemRoots: {}
         VariableNamingRule: 'modify'
          ReadVariableNames: true
              VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
             DatetimeLocale: en_US

  Text Format Properties:
             NumHeaderLines: 0
                  Delimiter: ','
               RowDelimiter: '\r\n'
             TreatAsMissing: 'NA'
               MissingValue: 0

  Advanced Text Format Properties:
            TextscanFormats: {'%f', '%f', '%f' ... and 26 more}
                   TextType: 'char'
         ExponentCharacters: 'eEdD'
               CommentStyle: ''
                 Whitespace: ' \b\t'
    MultipleDelimitersAsOne: false

  Properties that control the table returned by preview, read, readall:
      SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
            SelectedFormats: {'%f', '%f', '%f' ... and 26 more}
                   ReadSize: 20000 rows
                 OutputType: 'table'
                   RowTimes: []

  Write-specific Properties:
     SupportedOutputFormats: ["txt"    "csv"    "xlsx"    "xls"    "parquet"    "parq"]
        DefaultOutputFormat: "txt"

datastore 创建一个 TabularTextDatastore。

为图像数据创建数据存储

创建一个包含 MATLAB® 路径及其子文件夹中的所有 .tif 文件的数据存储。

ds = datastore(fullfile(matlabroot,"toolbox","matlab"),...
"IncludeSubfolders",true,"FileExtensions",".tif","Type","image")

ds = ImageDatastore with properties:
                       Files: {
                              'H:\matlab\toolbox\matlab\demos\example.tif';
                              'H:\matlab\toolbox\matlab\imagesci\corn.tif'
                              }
                     Folders: {
                              'H:\matlab\toolbox\matlab'
                              }
    AlternateFileSystemRoots: {}
                    ReadSize: 1
                      Labels: {}
      SupportedOutputFormats: ["png"    "jpg"    "jpeg"    "tif"    "tiff"]
         DefaultOutputFormat: "png"
                     ReadFcn: @readDatastoreImage

输入参数

全部折叠

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

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

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

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

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

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

对于 KeyValueDatastore，参量 location 必须为由 mapreduce 函数生成的 MAT 文件或序列文件。MAT 文件必须在本地文件系统中或在网络文件系统中。序列文件可以在本地、网络上或 HDFS™ 文件系统中。对于 DatabaseDatastore 类型的数据存储，location 参量不必是文件。有关详细信息，请参阅 DatabaseDatastore (Database Toolbox)。

示例: "file1.csv"

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

示例: ["C:\dir\data\file1.xls","C:\dir\data\file2.xlsx"]

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

示例: "hdfs:///data/file1.txt"

名称-值参数

全部折叠

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

示例: datastore("myfolder","FileExtensions"=[".jpg",".tif"]) 包括所有扩展名，一个 .jpg 或 .tif 扩展名表示一个 ImageDatastore 对象。

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

示例: datastore("myfolder","FileExtensions",[".jpg",".tif"]) 包括所有扩展名，一个 .jpg 或 .tif 扩展名表示一个 ImageDatastore 对象。

`Type` — 数据存储类型
`'tabulartext'` | `'image'` | `'spreadsheet'` | `'keyvalue'` | `'file'` | `'tall'` | ...

数据存储类型，指定为以逗号分隔的对组，其中包含 'Type' 和下列项之一：

`'Type'` 的值	描述
`'tabulartext'`	包含表格数据的文本文件。数据编码必须是 ASCII 或 UTF-8。
`'image'`	某种格式的图像文件（例如 JPEG 或 PNG）。可接受的文件包括 `imformats` 格式。
`'spreadsheet'`	包含一个或多个工作表的电子表格文件。
`'keyvalue'`	MAT 文件或序列文件中包含的键-值对组数据，这些文件的数据由 `mapreduce` 生成。有关详细信息，请参阅 `KeyValueDatastore`
`'file'`	自定义格式文件，需要指定的读取函数才能读取数据。有关详细信息，请参阅 `FileDatastore`。
`'tall'`	由 `tall` 数据类型的 `write` 函数生成的 MAT 文件或序列文件。有关详细信息，请参阅 `TallDatastore`。
`'parquet'`	包含列向数据的 Parquet 文件。有关详细信息，请参阅 `ParquetDatastore`。
`'database'`	数据库中存储的数据。需要 Database Toolbox™。在使用 `type` 参数时，需要指定额外的输入参量。有关详细信息，请参阅 `DatabaseDatastore` (Database Toolbox)。

如果有多种类型支持文件格式，则使用 'Type' 参量指定一种数据存储类型。
如果不指定 'Type' 的值，则 datastore 基于文件的扩展名自动确定要创建的数据存储的相应类型。

数据类型: char | string

`IncludeSubfolders` — 包括文件夹内的子文件夹
`true` 或 `false` | 0 或 1

包括文件夹内的子文件夹，指定为由 'IncludeSubfolders' 和 true (1) 或 false (0) 组成的逗号分隔的对组。指定 true 可包含每个文件夹中的所有文件和子文件夹，指定 false 则仅包含每个文件夹中的文件。

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

'IncludeSubfolders' 名称-值对组仅当创建以下对象时才有效：

TabularTextDatastore
ImageDatastore
SpreadsheetDatastore
FileDatastore
KeyValueDatastore
ParquetDatastore

示例: 'IncludeSubfolders',true

数据类型: logical | double

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

文件的扩展名，指定为以逗号分隔的对组，其中包含 'FileExtensions' 和一个字符向量、字符向量元胞数组、字符串标量或字符串数组。指定 'FileExtensions' 时，还需指定 'Type'。可以使用空引号 '' 表示不带扩展名的文件。

如果未指定 'FileExtensions'，则 datastore 会根据数据存储类型自动包含所有受支持的文件扩展名。如果要包含不受支持的扩展名，则需要逐个指定要包含的每个扩展名。

对于 TabularTextDatastore 对象，支持的扩展名包括 .txt、.csv、.dat、.dlm、.asc 和 .text，也支持没有扩展名的情况。
对于 ImageDatastore 对象，支持的扩展名包括所有 imformats 扩展名。
对于 SpreadsheetDatastore 对象，支持的扩展名包括 .xls、.xlsx、.xlsm、.xltx 和 .xltm。
对于 TallDatastore 对象，支持的扩展名包括 .mat 和 .seq。
对于 ParquetDatastore 对象，支持的扩展名包括 .parquet 和 .parq。

'FileExtensions' 名称-值对组仅当创建以下对象时才有效：

TabularTextDatastore
ImageDatastore
SpreadsheetDatastore
FileDatastore
KeyValueDatastore
ParquetDatastore

示例: 'FileExtensions','.jpg'

示例: 'FileExtensions',{'.txt','.text'}

数据类型: char | cell | string

`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

`TextType` — 文本变量的输出数据类型
`'char'` (默认) | `'string'`

文本变量的输出数据类型，指定为以逗号分隔的对组，其中包含 'TextType' 和 'char' 或 'string' 之一。如果 read、readall 或 preview 函数的输出表包含文本变量，则 'TextType' 仅为 TabularTextDatastore 和 SpreadsheetDatastore 对象指定这些变量的数据类型。如果 'TextType' 为 'char'，则输出为字符向量元胞数组。如果 'TextType' 为 'string'，则输出的类型为 string。

数据类型: char | string

`DatetimeType` — 导入日期和时间数据的类型
`'datetime'` (默认) | `'text'`

导入日期和时间数据的类型，指定为以逗号分隔的对组，其中包含 'DatetimeType' 和下列值之一：'datetime' 或 'text'。'DatetimeType' 参量仅在创建 TabularTextDatastore 对象时才适用。

值导入日期和时间数据的类型

值	导入日期和时间数据的类型
`'datetime'`	MATLAB `datetime` 数据类型有关详细信息，请参阅 `datetime`。
`'text'`	如果将 `'DatetimeType'` 指定为 `'text'`，则导入日期和时间数据的类型取决于 `'TextType'` 参数中指定的值：如果 `'TextType'` 为 `'char'`，则 `datastore` 将以字符向量元胞数组形式返回日期。如果 `'TextType'` 为 `'string'`，则 `datastore` 将以字符串数组形式返回日期。

'datetime'

MATLAB datetime 数据类型

有关详细信息，请参阅 datetime。

'text'

如果将 'DatetimeType' 指定为 'text'，则导入日期和时间数据的类型取决于 'TextType' 参数中指定的值：

如果 'TextType' 为 'char'，则 datastore 将以字符向量元胞数组形式返回日期。
如果 'TextType' 为 'string'，则 datastore 将以字符串数组形式返回日期。

示例: 'DatetimeType','datetime'

数据类型: char | string

`DurationType` — 持续时间数据的输出数据类型
`'duration'` (默认) | `'text'`

来自文本文件的持续时间数据的输出数据类型，指定为以逗号分隔的对组，其中包含 'DurationType' 和 'duration' 或 'text'。

值导入的持续时间数据的类型

值	导入的持续时间数据的类型
`'duration'`	MATLAB `duration` 数据类型有关详细信息，请参阅 `duration`。
`'text'`	如果将 `'DurationType'` 指定为 `'text'`，则导入的持续时间数据的类型取决于 `'TextType'` 参数中指定的值：如果 `'TextType'` 是 `'char'`，则导入函数会以字符向量元胞数组的形式返回持续时间数据。如果 `'TextType'` 是 `'string'`，则导入函数会以字符串数组的形式返回持续时间数据。

'duration'

MATLAB duration 数据类型

有关详细信息，请参阅 duration。

'text'

如果将 'DurationType' 指定为 'text'，则导入的持续时间数据的类型取决于 'TextType' 参数中指定的值：

如果 'TextType' 是 'char'，则导入函数会以字符向量元胞数组的形式返回持续时间数据。
如果 'TextType' 是 'string'，则导入函数会以字符串数组的形式返回持续时间数据。

数据类型: char | string | datetime

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

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

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

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

数据类型: char | string

除了这些名称-值对组外，您还可以将以下对象的任何属性（但 Files 属性除外）指定为名称-值对组：

输出参量

全部折叠

`ds` — 数据集合的数据存储
`TabularTextDatastore` | `ImageDatastore` | `SpreadsheetDatastore` | `KeyValueDatastore` | `FileDatastore` | `TallDatastore` | ...

数据集合的数据存储，作为以下对象之一返回：TabularTextDatastore、ImageDatastore、SpreadsheetDatastore、KeyValueDatastore、FileDatastore、TallDatastore、ParquetDatastore 或 DatabaseDatastore。数据存储的类型取决于文件类型或 location 参量。有关详细信息，请点击下表中的数据存储名称：

类型	输出
文本文件	`TabularTextDatastore`
图像文件	`ImageDatastore`
电子表格文件	`SpreadsheetDatastore`
`mapreduce` 生成的 MAT 文件或序列文件	`KeyValueDatastore`
自定义格式文件	`FileDatastore`
由 `tall` 数据类型的 `write` 函数生成的 MAT 文件或序列文件。	`TallDatastore`
Parquet 文件	`ParquetDatastore`
数据库	`DatabaseDatastore` (Database Toolbox)

对于这些数据存储类型，Files 属性是一个字符向量元胞数组。每个字符向量都是一个文件的绝对路径，由 location 参量解析。

限制

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

版本历史记录

在 R2014b 中推出

全部展开

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

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

另请参阅

datastore

语法

说明

示例

为文本数据创建数据存储

为图像数据创建数据存储

输入参数

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

名称-值参数

Type — 数据存储类型 'tabulartext' | 'image' | 'spreadsheet' | 'keyvalue' | 'file' | 'tall' | ...

IncludeSubfolders — 包括文件夹内的子文件夹 true 或 false | 0 或 1

FileExtensions — 文件的扩展名 字符向量 | 字符向量元胞数组 | 字符串标量 | 字符串数组

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

TextType — 文本变量的输出数据类型 'char' (默认) | 'string'

DatetimeType — 导入日期和时间数据的类型 'datetime' (默认) | 'text'

DurationType — 持续时间数据的输出数据类型 'duration' (默认) | 'text'

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

输出参量

ds — 数据集合的数据存储 TabularTextDatastore | ImageDatastore | SpreadsheetDatastore | KeyValueDatastore | FileDatastore | TallDatastore | ...

限制

版本历史记录

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

另请参阅

主题

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

`Type` — 数据存储类型
`'tabulartext'` | `'image'` | `'spreadsheet'` | `'keyvalue'` | `'file'` | `'tall'` | ...

`IncludeSubfolders` — 包括文件夹内的子文件夹
`true` 或 `false` | 0 或 1

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

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

`TextType` — 文本变量的输出数据类型
`'char'` (默认) | `'string'`

`DatetimeType` — 导入日期和时间数据的类型
`'datetime'` (默认) | `'text'`

`DurationType` — 持续时间数据的输出数据类型
`'duration'` (默认) | `'text'`

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

`ds` — 数据集合的数据存储
`TabularTextDatastore` | `ImageDatastore` | `SpreadsheetDatastore` | `KeyValueDatastore` | `FileDatastore` | `TallDatastore` | ...