Main Content

本页采用了机器翻译。点击此处可查看英文原文。

write

将分布式数据写入输出位置

全页折叠

语法

write(location,D)
write(filepattern,D)
write(___,Name,Value)

说明

示例

write(location,D) 将分布式数组 D 中的值写入文件夹 location 中的文件中。数据以高效的二进制格式存储，适合使用 datastore(location) 读回。如果不是沿第一个维度分布，则 MATLAB® 会在写入之前重新分配数据，以便可以使用 datastore 重新读取生成的文件。

示例

write(filepattern,D) 使用 filepattern 的文件扩展名来确定输出格式。filepattern 必须包含一个要写入文件的文件夹，后跟包含通配符 * 的文件名。通配符代表生成唯一文件名的增量数字，例如 write('folder/myfile_*.csv',D)。

示例

write(___,Name,Value) 使用任意先前的语法来指定具有一个或多个名称-值对参量的附加选项。例如，您可以使用 'FileType' 和有效的文件类型 ('mat'、'seq'、'parquet'、'text' 或 'spreadsheet') 指定文件类型，或者您可以使用 'WriteFcn' 和函数句柄指定自定义写入函数来进程数据。

示例

全部折叠

此示例显示如何将分布式数组写入文件系统，然后使用数据存储将其读回。

创建一个分布式数组并将其写入输出文件夹。

d = distributed.rand(5000,1);
location = 'hdfs://myHadoopCluster/some/output/folder';
write(location, d);

根据写入的文件重新创建分布式数组。

ds = datastore(location);
d1 = distributed(ds);

此示例展示如何使用文件模式将分布式数组写入不同的格式。

创建一个分布式表并将其写入许多应用程序可以读取的简单文本格式。

dt = distributed(array2table(rand(5000,3)));
location = "/tmp/CSVData/dt_*.csv";
write(location, dt);

从写入的文件重新创建分布式表。

ds = datastore(location);
dt1 = distributed(ds);

您可以写入分布式数据并将其读回为 tall 数据，反之亦然。

创建分布式时间表并将其写入磁盘。

dt = distributed(array2table(rand(5000,3)));
location = "/tmp/CSVData/dt_*.csv";
write(location, dt);

根据书面文件构建一张 tall 表。

 ds = datastore(location);
 tt = tall(ds);

或者，您可以将从 tall 数据写入分布式数据。创建一个 tall 时间表并将其写入磁盘。

tt = tall(array2table(rand(5000,3)));
location = "/tmp/CSVData/dt_*.csv";
write(location, tt);

回顾分布式时间表。 

 ds = datastore(location);
 dt = distributed(ds);

此示例说明如何使用自定义写入函数将分布式数组写入文件系统。

创建一个简单的写入函数，用于写出电子表格文件。

function dataWriter(info, data)
       filename = info.SuggestedFilename;
       writetable(data, filename, "FileType", "spreadsheet");
end

创建分布式表并使用自定义写入函数将其写入磁盘。

dt = distributed(array2table(rand(5000,3)));
location = "/tmp/MyData/tt_*.xlsx";
write(location, dt, "WriteFcn", @dataWriter);

输入参数

全部折叠

写入数据的文件夹位置，指定为字符向量或字符串。location 可以指定完整路径或相对路径。指定的文件夹可以是以下任一选项：

  • 现有的空文件夹不包含其他文件

  • write 创建的新文件夹

您可以将数据写入计算机上的本地文件夹、共享网络上的文件夹或远程位置，例如 Amazon S3™、Windows Azure® 存储 Blob 或 Hadoop® 分布式文件系统 (HDFS™)。有关读取和写入远程位置数据的更多信息，请参阅 处理远程数据。

示例: location = '../../dir/data' 指定相对文件路径。

示例: location = 'C:\Users\MyName\Desktop\data' 指定 Windows® 桌面文件夹的绝对路径。

示例: location = 'file:///path/to/data' 指定文件夹的绝对 URI 路径。

示例: location = 'hdfs://myHadoopCluster/some/output/folder' 指定 HDFS URL。

示例: location = 's3://bucketname/some/output/folder' 指定 Amazon S3 位置。

数据类型: char | string

输入数组，指定为分布式数组。

文件命名模式，指定为字符串或字符向量。文件命名模式必须包含一个要写入文件的文件夹，后跟包含通配符 * 的文件名。write 用序列数字替换通配符，以确保文件名唯一。

示例: write('folder/data_*.txt',D) 将分布式数组 D 写入 folder 中的一系列 .txt 文件，文件名分别为 data_1.txt、data_2.txt 等。

数据类型: char | string

名称-值参数

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

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

示例: write('C:\myData', D, 'FileType', 'text', 'WriteVariableNames', false) 将分布式数组 D 至 C:\myData 写入为不使用变量名作为列标题的文本文件集合。

常规选项

全部折叠

文件类型，指定为以逗号分隔的对，由 'FileType' 和以下允许的文件类型之一组成：'auto'、'mat'、'parquet'、'seq'、'text' 或 'spreadsheet'。

使用 'FileType' 名称-值对和 location 参量来指定要写入的文件类型。默认情况下，write 会尝试自动检测正确的文件类型。如果 write 可以根据 location 或 filepattern 参量中的扩展名确定文件类型，则无需指定 'FileType' 名称-值对参量。write 可以根据以下扩展名确定文件类型：

  • .mat（用于 MATLAB 数据文件）

  • 对于 Parquet 文件，为 .parquet 或 .parq

  • .seq 表示序列文件

  • .txt、.dat 或 .csv（用于分隔文本文件）

  • 对于电子表格文件，为 .xls、.xlsx、.xlsb、.xlsm、.xltx 或 .xltm

示例: write('C:\myData', D, 'FileType', 'text')

自定义写入函数，指定为由 'WriteFcn' 和函数句柄组成的逗号分隔的对。指定的函数从 D 接收数据块并负责创建输出文件。您可以使用 'WriteFcn' 名称-值对参量以多种格式写入数据，即使 write 不直接支持输出格式。

函数签名

自定义写作函数必须接受两个输入参量，info 和 data：

function myWriter(info, data)

  • data 包含来自 D 的数据块。

  • info 是一个具有字段的结构，其中包含有关数据块的信息。您可以使用这些字段来构建在最终位置内全局唯一的新文件名。结构字段包括：

    字段描述
    RequiredLocation临时输出文件夹的完整限定路径。所有输出文件都必须写入此文件夹。
    RequiredFilePattern输出文件名所需的文件模式。如果仅指定了文件夹名称，则此字段为空。
    SuggestedFilename满足位置和命名要求的完全限定的、全局唯一的文件名。
    PartitionIndex正在写入的分布式数组分区的索引。
    NumPartitions分布式数组中的分区总数。
    BlockIndexInPartition分区内当前数据块的位置。
    IsFinalBlock如果当前块是分区的最后一个块，则为 true。

文件命名

用于输出文件的文件名决定了稍后由 datastore 读回文件的顺序。如果文件的顺序很重要，那么最佳做法是使用 SuggestedFilename 字段来命名文件，因为建议的名称可以保证文件顺序。如果您不使用建议的文件名，则自定义写入函数必须创建全局唯一的、正确排序的文件名。文件名应遵循 RequiredFilePattern 中概述的命名模式。尽管每个工作进程都会写入自己的本地文件夹，但工作进程之间的文件名必须是唯一的且顺序正确。

具有多个分区的数组

将分布式数组分成多个分区，以便与 Parallel Computing Toolbox™ 并行在数组上运行计算。当写入分布式数组时，每个分区被分成更小的块。

info 包含几个与分区相关的字段：PartitionIndex、NumPartitions、BlockIndexInPartition 和 IsFinalBlock。当您写出单个文件并附加到其中时，这些字段很有用，这对于已被分成多个块的大型分区的数组来说是一项常见任务。自定义写入函数每个块调用一次，并且一个分区中的块总是按顺序写入一个工作进程上。然而，不同的分区可以由不同的工作进程来写入。

示例函数

写出电子表格文件的一个简单写入函数是：

function dataWriter(info, data)
  filename = info.SuggestedFilename;
  writetable(data, filename, 'FileType', 'spreadsheet')
end
要调用 dataWriter 作为某些数据 D 的写入函数，请使用以下命令：
D = distributed(array2table(rand(5000,3)));
location = '/tmp/MyData/D_*.xlsx';
write(location, D, 'WriteFcn', @dataWriter);
对于每个块，dataWriter 函数使用 info 结构中建议的文件名并调用 writetable 来写出电子表格文件。建议的文件名考虑了 location 参量中指定的文件命名模式。

数据类型: function_handle

文本或电子表格文件

全部折叠

将变量名称写为列标题的指示符，指定为由 'WriteVariableNames' 和数值或逻辑 1 (true) 或 0 (false) 组成的逗号分隔的对。

指示符

行为

true

变量名称作为输出的列标题包含在内。这是默认行为。

false

变量名称不包含在输出中。

用于编写日期的语言环境，指定为由 'DateLocale' 和字符向量或字符串标量组成的逗号分隔的对。将 datetime 值写入文件时，使用 DateLocale 指定 write 应写入月份和星期名称及缩写的区域设置。字符向量或字符串采用 xx_YY 的形式，其中 xx 是表示语言的小写 ISO 639-1 双字母代码，YY 是表示国家/地区的大写 ISO 3166-1 alpha-2 代码。有关语言环境的常用值的列表，请参阅 datetime 函数的 Locale 名称-值对参量。

对于 Excel® 文件，write 将包含 datetime 数组的变量写入为 Excel 日期，并忽略 'DateLocale' 参数值。如果 datetime 变量包含 1900 年或 1904 年之前的年份，则 write 会将变量写入文本。有关 Excel 日期的更多信息，请参阅 Excel 中 1900 和 1904 日期系统之间的差异。

示例: 'DateLocale','ja_JP' 或 'DateLocale',"ja_JP"

数据类型: char | string

仅限文本文件

全部折叠

字段分隔符，指定为由 'Delimiter' 和以下设定符之一组成的逗号分隔对：

设定符

字段分隔符

','

'comma'

逗号。这是默认行为。

' '

'space'

空格

'\t'

'tab'

制表符

';'

'semi'

分号

'|'

'bar'

竖线

您只能对分隔文本文件使用 'Delimiter' 名称-值对参量。

示例: 'Delimiter','space' 或 'Delimiter',"space"

用于写入引用文本的指示符，指定为由 'QuoteStrings' 和 false 或 true 组成的逗号分隔的对。如果 'QuoteStrings' 是 true，则 write 将文本括在双引号中，并用两个双引号字符替换作为该文本一部分出现的任何双引号字符。有关示例，请参阅 将引用文本写入 CSV 文件。

您只能在带分隔符的文本文件中使用 'QuoteStrings' 名称-值对参量。

与文件关联的字符编码方案，指定为由 'Encoding' 和 'system' 组成的逗号分隔的对或标准字符编码方案名称，类似于此表中的一个值。当您没有指定任何编码或者指定编码为 'system' 时，write 函数将使用系统默认编码来写入文件。

"Big5"

"ISO-8859-1"

"windows-874"

"Big5-HKSCS"

"ISO-8859-2"

"windows-949"

"CP949"

"ISO-8859-3"

"windows-1250"

"EUC-KR"

"ISO-8859-4"

"windows-1251"

"EUC-JP"

"ISO-8859-5"

"windows-1252"

"EUC-TW"

"ISO-8859-6"

"windows-1253"

"GB18030"

"ISO-8859-7"

"windows-1254"

"GB2312"

"ISO-8859-8"

"windows-1255"

"GBK"

"ISO-8859-9"

"windows-1256"

"IBM866"

"ISO-8859-11"

"windows-1257"

"KOI8-R"

"ISO-8859-13"

"windows-1258"

"KOI8-U"

"ISO-8859-15"

"US-ASCII"

 

"Macintosh"

"UTF-8"

 

"Shift_JIS"

 

示例: 'Encoding','system' 或 'Encoding',"system" 使用系统默认编码。

仅限电子表格文件

全部折叠

目标工作表，指定为以逗号分隔的对，由 'Sheet' 和一个字符向量或包含工作表名称或表示工作表索引的正整数的字符串标量组成。工作表名称不能包含冒号（:）。要确定电子表格文件中工作表的名称，请使用 [status,sheets] = xlsfinfo(filename)。

如果工作表不存在，则 write 会在工作表集合的末尾添加一个新工作表。如果工作表的索引大于工作表的数量，则 write 会附加空工作表，直到工作簿中的工作表数量等于工作表索引。无论哪种情况，write 都会生成一个警告，表明它已添加了新的工作表。

您只能在电子表格文件中使用 'Sheet' 名称-值对参量。

示例: 'Sheet',2

示例: 'Sheet', 'MySheetName'

数据类型: char | string | single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

仅限 Parquet 文件

全部折叠

Parquet 压缩算法，指定为这些值之一。

  • 'snappy'、'brotli'、'gzip' 或 'uncompressed'。如果您指定一种压缩算法，那么 write 会使用相同的算法压缩所有变量。

  • 或者，您可以指定一个字符向量单元格数组或一个字符串向量，其中包含要用于每个变量的压缩算法的名称。

总体来说，'snappy' 的读写性能更佳；'gzip' 的压缩率更高但需要更多的 CPU 处理时间；'brotli' 通常可以产生最小的文件大小但压缩速度较慢。

示例: write('C:\myData',D,'FileType','parquet','VariableCompression','brotli')

示例: write('C:\myData', D, 'FileType', 'parquet', 'VariableCompression', {'brotli' 'snappy' 'gzip'})

编码方案名称，指定为以下值之一：

  • 'auto' - write 对逻辑变量使用 'plain' 编码，对所有其他变量使用 'dictionary' 编码。

  • 'dictionary', 'plain' - 如果您指定一种编码方案，那么 write 会使用该方案对所有变量进行编码。

  • 或者，您可以指定一个字符向量单元格数组或一个字符串向量，其中包含每个变量要使用的编码方案的名称。

一般来说，'dictionary' 编码会产生较小的文件大小，但对于不包含许多重复值的变量，'plain' 编码的速度会更快。如果字典的大小或唯一值的数量变得太大，那么编码会自动恢复为普通编码。有关 Parquet 编码的更多信息，请参阅 Parquet 编码定义。

示例: write('myData.parquet', D, 'FileType', 'parquet', 'VariableEncoding', 'plain')

示例: write('myData.parquet', D, 'FileType', 'parquet', 'VariableEncoding', {'plain' 'dictionary' 'plain'})

要使用的 Parquet 版本，指定为 '1.0' 或 '2.0'。默认情况下，'2.0' 提供最有效的存储，但您可以选择 '1.0' 以实现与支持 Parquet 格式的外部应用程序的最广泛兼容性。

限制

在某些情况下，write(location, D, 'FileType', type) 创建的文件不能准确表示原始数组 D。如果使用 datastore(location) 读取检查点文件，则结果可能具有与原始分布式表不同的格式或内容。

对于 'text' 和 'spreadsheet' 文件类型，write 使用以下规则：

  • write 使用 longG 格式输出数值变量，并将分类、字符或字符串变量作为不带引号的文本输出。

  • 对于具有多列的非文本变量，write 在每一行输出多个以分隔符分隔的字段，并为文件的第一行构建合适的列标题。

  • write 将具有两个以上维度的变量输出为二维变量，并将尾随维度折叠起来。

  • 对于单元格值变量，当内容为数值、逻辑、字符或分类时，write 会将每个单元格的内容作为一行输出，分为多个以分隔符分隔的字段，否则输出单个空字段。

如果您需要写入分布式数组的精确检查点，请不要使用 'text' 或 'spreadsheet' 文件类型。

提示

  • 使用 write 函数在工作时创建数据的检查点或快照。这种做法允许您直接从磁盘上的文件重建分布式数组，而不是重新执行生成分布式数组的所有命令。

版本历史记录

在 R2017a 中推出

另请参阅

| |

主题