本页对应的英文页面已更新,但尚未翻译。 若要查看最新内容,请点击此处访问英文页面。

datastore

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

说明

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

示例

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

示例

全部折叠

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

要控制如何在数值列中导入缺失的数据,请使用 'TreatAsMissing' 名称-值对组参数。在此示例中,为 'TreatAsMissing' 指定值 'NA',在导入的数据中将 'NA' 的每个实例替换为 NaN。其中,NaN 是数据存储的 'MissingValue' 属性中指定的值。

ds = datastore('airlinesmall.csv', ...
                   'TreatAsMissing','NA')
ds = 
  TabularTextDatastore with properties:

                      Files: {
                             ' .../devel/bat/Bdoc19a/build/matlab/toolbox/matlab/demos/airlinesmall.csv'
                             }
               FileEncoding: 'UTF-8'
   AlternateFileSystemRoots: {}
          ReadVariableNames: true
              VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
             DatetimeLocale: en_US
            ReadFailureRule: 'error'
                MaxFailures: Inf

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

  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

datastore 创建一个 TabularTextDatastore

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

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

  ImageDatastore with properties:

       Files: {
              ' ...\matlab\toolbox\matlab\demos\example.tif';
              ' ...\matlab\toolbox\matlab\imagesci\corn.tif'
              }
    ReadSize: 1
      Labels: {}
     ReadFcn: @readDatastoreImage

输入参数

全部折叠

数据存储中包含的文件或文件夹,指定为路径或 DsFileSet 对象。

  • 路径 - 将路径指定为字符向量、字符向量元胞数组、字符串标量或字符串数组,其中包含本地或远程文件或文件夹的位置。

    • 本地文件或文件夹 - 将 location 指定为文件或文件夹的本地路径。如果文件不在当前文件夹中,则本地路径必须指定完整路径或相对路径。指定文件夹的子文件夹中的文件不会自动包括在数据存储中。在指定本地路径时可以使用通配符 (*)。此字符指定数据存储包含所有匹配的文件或匹配文件夹中的所有文件。

    • 远程文件或文件夹 - 以 hdfs:///path_to_file 格式的国际化资源标识符 (IRI) 将 location 指定为文件或文件夹的完整路径。有关详细信息,请参阅处理远程数据

  • DsFileSet 对象 - 您也可以将 location 指定为 DsFileSet 对象。有关详细信息,请参阅 matlab.io.datastore.DsFileSet

location 表示文件夹时,数据存储只包含支持的文件格式,并忽略任何其他格式。要指定要包含在数据存储中的自定义文件扩展名列表,请参阅 FileExtensions 属性。

对于 KeyValueDatastore,这些文件必须是 mapreduce 函数生成的 MAT 文件或序列文件。MAT 文件必须在本地文件系统中或在网络文件系统中。序列文件可以在本地、网络上或 HDFS™ 文件系统中。对于 DatabaseDatastore,位置参数不需要是文件。有关详细信息,请参阅 DatabaseDatastore

示例: 'file1.csv'

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

示例: {'C:\dir\data\file1.xls','C:\dir\data\file2.xlsx'}

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

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

名称-值对组参数

指定可选的、以逗号分隔的 Name,Value 对组参数。Name 为参数名称,Value 为对应的值。Name 必须放在引号中。您可采用任意顺序指定多个名称-值对组参数,如 Name1,Value1,...,NameN,ValueN 所示。

示例: 'FileExtensions',{'.jpg','.tif'} 包括所有扩展名,一个 .jpg.tif 扩展名表示一个 ImageDatastore 对象。

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

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

  • 如果不指定 'Type' 的值,则 datastore 基于文件的扩展名自动确定要创建的数据存储的相应类型。

数据类型: char | string

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

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

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

  • TabularTextDatastore

  • ImageDatastore

  • SpreadsheetDatastore

  • FileDatastore

  • KeyValueDatastore

示例: 'IncludeSubfolders',true

数据类型: logical | double

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

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

  • 对于 TabularTextDatastore 对象,支持的扩展名包括 .txt.csv.dat.dlm.asc.text,也支持没有扩展名的情况。

  • 对于 ImageDatastore 对象,支持的扩展名包括所有 imformats 扩展名。

  • 对于 SpreadsheetDatastore 对象,支持的扩展名包括 .xls.xlsx.xlsm.xltx.xltm

  • 对于 TallDatastore 对象,支持的扩展名包括 .mat.seq

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

  • TabularTextDatastore

  • ImageDatastore

  • SpreadsheetDatastore

  • FileDatastore

  • KeyValueDatastore

示例: 'FileExtensions','.jpg'

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

数据类型: char | cell | string

备用文件系统根路径,以逗号分隔的对组形式指定,该对组由 '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' 之一。如果 readreadallpreview 函数的输出表包含文本变量,则 'TextType' 仅为 TabularTextDatastoreSpreadsheetDatastore 对象指定这些变量的数据类型。如果 'TextType''char',则输出为字符向量元胞数组。如果 'TextType''string',则输出的类型为 string

数据类型: char | string

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

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

MATLAB datetime 数据类型

有关详细信息,请参阅 datetime

'text'

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

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

  • 如果 'TextType''string',则 datastore 将以字符串数组形式返回日期。

示例: 'DatetimeType','datetime'

数据类型: char | string

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

导入的持续时间数据的类型
'duration'

MATLAB duration 数据类型

有关详细信息,请参阅 duration

'text'

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

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

  • 如果 'TextType''string',则导入函数会以字符串数组的形式返回持续时间数据。

数据类型: char | string

除了这些名称-值对组外,您还可以将以下对象的任何属性(但 Files 属性除外)指定为名称-值对组:

输出参数

全部折叠

数据集合的数据存储,作为以下对象之一返回:TabularTextDatastoreImageDatastoreSpreadsheetDatastoreKeyValueDatastoreFileDatastoreTallDatastoreParquetDatastoreDatabaseDatastore。数据存储的类型取决于文件类型或 location 参数。有关详细信息,请点击下表中的数据存储名称:

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

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

在 R2014b 中推出