write
将分布式数据写入输出位置
说明
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 数据和分布式数据
您可以写入分布式数据并将其读回为 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
— 写入数据的文件夹位置
字符向量 | 字符串
写入数据的文件夹位置,指定为字符向量或字符串。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
D
— 输入数组
分布式数组
输入数组,指定为分布式数组。
filepattern
— 文件命名模式
字符串 | 字符向量
文件命名模式,指定为字符串或字符向量。文件命名模式必须包含一个要写入文件的文件夹,后跟包含通配符 *
的文件名。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'
和以下允许的文件类型之一组成:'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
— 自定义书写函数
函数句柄
自定义写入函数,指定为由 '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
— 将变量名称写为列标题的指示器
true
或 1
(默认) | false
或 0
将变量名称写为列标题的指示符,指定为由 'WriteVariableNames'
和数值或逻辑 1
(true
) 或 0
(false
) 组成的逗号分隔的对。
指示符 | 行为 |
---|---|
| 变量名称作为输出的列标题包含在内。这是默认行为。 |
| 变量名称不包含在输出中。 |
DateLocale
— 编写日期的区域设置
字符向量 | 字符串标量
用于编写日期的语言环境,指定为由 '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'
| ...
字段分隔符,指定为由 'Delimiter'
和以下设定符之一组成的逗号分隔对:
设定符 | 字段分隔符 |
---|---|
| 逗号。这是默认行为。 |
| 空格 |
| 制表符 |
| 分号 |
| 竖线 |
您只能对分隔文本文件使用 'Delimiter'
名称-值对参量。
示例: 'Delimiter','space'
或 'Delimiter',"space"
QuoteStrings
— 引用文本书写指示
false
(默认) | true
用于写入引用文本的指示符,指定为由 'QuoteStrings'
和 false
或 true
组成的逗号分隔的对。如果 'QuoteStrings'
是 true
,则 write
将文本括在双引号中,并用两个双引号字符替换作为该文本一部分出现的任何双引号字符。有关示例,请参阅 将引用文本写入 CSV 文件。
您只能在带分隔符的文本文件中使用 'QuoteStrings'
名称-值对参量。
Encoding
— 字符编码方案
'UTF-8'
| 'ISO-8859-1'
| 'windows-1251'
| 'windows-1252'
| ...
与文件关联的字符编码方案,指定为由 'Encoding'
和 'system'
组成的逗号分隔的对或标准字符编码方案名称,类似于此表中的一个值。当您没有指定任何编码或者指定编码为 'system'
时,write
函数将使用系统默认编码来写入文件。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
|
示例: 'Encoding','system'
或 'Encoding',"system"
使用系统默认编码。
Sheet
— 目标工作表
字符向量 | 字符串标量 | 正整数
目标工作表,指定为以逗号分隔的对,由 '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
VariableCompression
— Parquet 压缩算法
'snappy'
(默认) | 'brotli'
| 'gzip'
| 'uncompressed'
| 字符向量元胞数组 | 字符串向量
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'})
VariableEncoding
— 编码方案名称
'auto'
(默认) | 'dictionary'
| 'plain'
| 字符向量元胞数组 | 字符串向量
编码方案名称,指定为以下值之一:
'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'})
Version
— 要使用的 Parquet 版本
'2.0'
(默认) | '1.0'
要使用的 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 中推出
MATLAB 命令
您点击的链接对应于以下 MATLAB 命令:
请在 MATLAB 命令行窗口中直接输入以执行命令。Web 浏览器不支持 MATLAB 命令。
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- 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)