loadText

loadText(filename, [delimiter], [schema], [skipRows=0], [arrayDelimiter], [containHeader], [arrayMarker])

filename 字符串，表示数据文件的路径。仅支持 CSV 格式的文件。若传入其他格式文件，则无法保证数据准确性。

delimiter 字符串标量，表示数据文件中各列的分隔符。分隔符可以是一个或多个字符，默认是逗号（","）。

schema 表对象，用于指定各字段的数据类型。它可以包含以下四列（其中，name 和 type 这两列是必需的）

skipRows 0 到 1024 之间的整数，表示从文件头开始忽略的行数。它是一个可选参数。默认值为 0。

arrayDelimiter 数据文件中数组向量列的分隔符。默认是逗号。由于不支持自动识别数组向量，必须同步修改 schema 的 type 列修为数组向量类型。

containHeader 布尔值，表示数据文件是否包含标题行，默认为空。若不设置，则系统将会分析第一行数据并确定其是否为标题行。不同设置下，列名解析规则见详情描述。

arrayMarker 包含两个字符的字符串或或 CHAR 类型数据对，两个字符分别表示数组向量左右边界的标识符。默认标识符为双引号（"）。

• 不能包含空格、Tab(\t) 和换行符(\t和\n)。

• 不能包含数字或字母。

• 如果其中一个为双引号(")，另一个也必须为双引号。

• 如果标识符为 '，" 或\ ，需视情况添加转义符。例如 arrayMarker="\"\""。

• 如果 delimiter 是单个字符，则 arrayMarker 不能包含与其相同的字符。

• 如果 delimiter 是多个字符，则 arrayMarker 左边界不能与 delimiter 的首个字符相同。

将数据文件加载到 DolphinDB 的内存表中。loadText 使用单个线程加载数据，如果需要使用多个线程并行加载数据，请使用 ploadText 函数。

• 解析列名：

  • 不指定 containHeader 时，导入文本文件时将以字符串格式读取第一行数据，并根据该数据解析列名。但需要注意，系统内部对第一行数据设置了读取上限，即不能超过 256 KB。解析时，如果文件中第一行的内容不包含以数字开头的数据，那么加载文件时系统会将第一行作为列名。如果文件第一行记录中某列记录以数字开头，那么加载文件时系统可能会使用col0, col1, ...等作为列名。

  • 指定 containHeader = true 时，则系统将第一行数据视为标题行，并解析出列名。

  • 指定 containHeader = false 时，则系统将添加列名 col0, col1, ... 。

• 解析类型：

  • 当 DolphinDB 加载数据文件时，会进行随机抽样，并基于样本决定每列的数据类型。这个方法不一定每次都能准确决定各列的数据类型。因此我们建议，在加载数据前，使用 extractTextSchema 函数查看 DolphinDB 识别每列的数据类型。

  • 当加载的数据文件中包含了表达时间、日期的数据时，满足分隔符要求的这部分数据（日期数据分隔符包含"-"、"/"和"."，时间数据分隔符为":"）会解析为相应的类型。例如，"12:34:56"解析为SECOND类型；"23.04.10"解析为DATE类型。对于不包含分隔符的数据，形如"yyMMdd"的数据同时满足0<=yy<=99，0<=MM<=12，1<=dd<=31，会被优先解析成DATE；形如"yyyyMMdd"的数据同时满足1900<=yyyy<=2100，0<=MM<=12，1<=dd<=31会被优先解析成DATE。

  • 如果 DolphinDB 识别的数据类型不符合预期，可以在 schema 的 type 列中指定数据类型。对于日期列或时间列，如果 DolphinDB 识别的数据类型不符合预期，不仅需要在 schema 的 type 列指定时间类型，还需要在 format 列中指定数据文件中日期或时间的格式（用字符串表示），如 "MM/dd/yyyy"。如何表示日期和时间格式请参考 ParsingandFormatofTemporalVariables。

如果只需加载数据文件中的部分列，需要在 schema 的 col 列中指定要加载的列的下标。

由于 DolphinDB 的字符串采用 UTF-8 编码，加载的文件必须是 UTF-8 编码。

由于 DolphinDB 中列名仅可使用中文或英文字母、数字或下划线 (_)，且必须以中文或英文字母开头，若数据文件中的列名不符合要求，系统会依据以下规则自动调整列名：

• 若数据中列名存在中文或英文字母、数字或下划线之外的字符，将其转换为下划线。

• 若数据中列名第一个字符不是中文或英文字母，添加 "c" 作为该列名首字符。

以下是数据文件中不合规列名以及自动转换的列名的例子：

首先，使用以下脚本生成模拟的数据文件：

n=10
sym=rand(`AAPL`ORCL`MS`SUN,n)
permno=take(10001,n)
date=rand(2019.06.01..2019.06.10,n)
open=rand(100.0,n)
high=rand(200.0,n)
close=rand(200.0,n)
pre_close=rand(200.0,n)
change=rand(100.0,n)
vol=rand(10000,n)
amount=rand(100000.0,n)
t=table(sym,permno,date,open,high,close,pre_close,change,vol,amount)
saveText(t,"/home/DolphinDB/Data/stock.csv");

tt=loadText("/home/DolphinDB/Data/stock.csv");
# output
tt;

schema(tt).colDefs;

例如，我们想要把 permno 列的数据类型转换成 SYMBOL，可以用 extractTextSchema 函数获取输入文件的结构，在导入数据前修改该列的数据类型，并指定 loadText 函数的 schema 参数。

schema=extractTextSchema("/home/DolphinDB/Data/stock.csv");
update schema set type=`SYMBOL where name=`permno;
tt=loadText("/home/DolphinDB/Data/stock.csv",,schema);
schema(tt).colDefs;

用户也可以指定所有数据类型：

schematable=table(`sym`permno`date`open`high`close`pre_close`change`vol`amount as name,`SYMBOL`SYMBOL`DATE`DOUBLE`DOUBLE`DOUBLE`DOUBLE`DOUBLE`INT`DOUBLE as type)
tt=loadText("/home/DolphinDB/Data/stock.csv",,schematable)
schema(tt).colDefs;

例如，只需加载 sym, date, open, high, close, vol, amount 这 7 列。注意，加载数据时，不能改变各列的先后顺序。如果需要调整列的顺序，可以将数据文件加载后，再使用reorderColumns!函数。

schema=extractTextSchema("/home/DolphinDB/Data/stock.csv");
schema=select * from schema where name in `sym`date`open`high`close`vol`amount
schema[`col]=[0,2,3,4,5,8,9]

tt=loadText("/home/DolphinDB/Data/stock.csv",,schema);
tt;

示例文件的第一行为列名，因此忽略前 2 行后，总的数据条数为 9。

re=loadText(filename="/home/DolphinDB/Data/stock.csv",skipRows=2)
select count(*) from re;

生成本例所需的数据文件：

time=["20190623145457","20190623155423","20190623163025"]
sym=`AAPL`MS`IBM
qty=2200 5400 8670
price=54.78 59.64 65.23
t=table(time,sym,qty,price)
saveText(t,"/home/DolphinDB/Data/t2.csv");

加载数据前，使用 extractTextSchema 函数获取该数据文件的结构：

extractTextSchema("/home/DolphinDB/Data/t2.csv");

由于 time 列的时间格式与 DolphinDB 中的时间格式不同，如果直接加载该文件，time 列的数据将会被识别为长整型。为了能够正确加载该文件 time 列的数据，需要指定 time 列的数据类型为 DATETIME，并且指定该列的格式为 "yyyyMMddHHmmss"。

schema=extractTextSchema("/home/DolphinDB/Data/t2.csv")
update schema set type = "DATETIME" where name = "time"
schema[`format]=["yyyyMMddHHmmss",,,];

loadText("/home/DolphinDB/Data/t2.csv",,schema);

使用以下脚本模拟生成一个 csv 文本文件：

bid = array(DOUBLE[], 0, 20).append!([1.4799 1.479 1.4787, 1.4796 1.479 1.4784, 1.4791 1.479 1.4784])
ask = array(DOUBLE[], 0, 20).append!([1.4821 1.4825 1.4828, 1.4818 1.482 1.4821, 1.4814 1.4818 1.482])
TradeDate = 2022.01.01 + 1..3
SecurityID = rand(`APPL`AMZN`IBM, 3)
t = table(SecurityID as `sid, TradeDate as `date, bid as `bid, ask as `ask)
t;
saveText(t,filename="/home/DolphinDB/Data/t.csv",delimiter=',',append=true)

sid,date,bid,ask
APPL,2022.01.02,"1.4799,1.479,1.4787","1.4821,1.4825,1.4828"
IBM,2022.01.03,"1.4796,1.479,1.4784","1.4818,1.482,1.4821"
APPL,2022.01.04,"1.4791,1.479,1.4784","1.4814,1.4818,1.482"

然后调用 loadText 导入该文件：

path = "/home/DolphinDB/Data/t.csv"
schema=extractTextSchema(path);
update schema set type = "DOUBLE[]" where name="bid" or name ="ask"
t = loadText(path, schema=schema, arrayDelimiter=",")
t;

通过 saveText 导出 csv 文件时，数组向量的边界标识默认为双引号（”），本例中 t.csv 的内容如下

当数组向量的边界标识不为双引号时，可以通过设置参数 arrayMarker 导入，例如当 t.csv 的内容如下时

sid,date,bid,ask
APPL,2022.01.02,[1.4799,1.479,1.4787],[1.4821,1.4825,1.4828]
IBM,2022.01.03,[1.4796,1.479,1.4784],[1.4818,1.482,1.4821]
APPL,2022.01.04,[1.4791,1.479,1.4784],[1.4814,1.4818,1.482]

通过以下脚本导入

path = "/home/DolphinDB/Data/t.csv"
schema=extractTextSchema(path);
update schema set type = "DOUBLE[]" where name="bid" or name ="ask"
t = loadText(path, schema=schema, arrayDelimiter=",",arrayMarker="[]")
t;