干货丨Orca 数据加载入门教程
本文介绍在Orca中加载数据的方法。
1 建立数据库连接
在Orca中通过connect函数连接到DolphinDB服务器：
>>> import dolphindb.orca as orca
>>> orca.connect(MY_HOST, MY_PORT, MY_USERNAME, MY_PASSWORD)
复制代码2 导入数据
下面的教程使用了一个数据文件：quotes.csv。
2.1 read_csv函数
Orca提供read_csv函数，用于导入数据集。需要说明的是，Orca的read_csv函数的engine参数的取值可以是{‘c’, ‘python’, ‘dolphindb’}，且该参数默认取值为‘dolphindb’。当取值为‘dolphindb’时，read_csv函数会在DolphinDB服务器目录下寻找要导入的数据文件。当取值为‘python’或‘c’时，read_csv函数会在python客户端的目录下寻找要导入的数据文件。
请注意，当engine参数设置为‘python’或者‘c’时，Orca的
read_csv函数相当于调用了pandas的read_csv函数进行导入。本节是基于engine参数取值为‘dolphindb’的前提下对Orca的read_csv函数进行讲解。
当engine参数设置为‘dolphindb’时，Orca的read_csv函数目前支持的参数如下：
- path：文件路径
- sep：分隔符
- delimiter：分隔符
- names：指定列名
- index_col：指定作为index的列
- engine：进行导入的引擎
- usecols：指定要导入的列
- squeeze：当数据文件只有一行或者一列时，是否将DataFrame压缩成Series
- prefix：给每列加上的前缀字符串
- dtype：指定数据类型导入
- partitioned：是否允许以分区的方式导入数据
- db_handle：要导入的数据库路径
- table_name：要导入的表名
- partition_columns：进行分区的列名
下面详细介绍Orca与pandas实现有所不同的几个参数。
- dtype参数
Orca在导入csv的时候会自动识别要导入文件的数据类型，支持各种通用时间格式。用户也可以通过dtype参数来强制指定数据类型。
需要说明的是，Orca的read_csv函数不仅支持指定各种numpy的数据类型（np.bool, np.int8, np.float32, etc.），还支持支持以字符串的方式指定DolphinDB的提供的所有数据类型，包括所有时间类型和字符串类型。
例如：
dfcsv = orca.read_csv("DATA_DIR/quotes.csv", dtype={"TIME": "NANOTIMESTAMP", "Exchange": "SYMBOL", "SYMBOL": "SYMBOL", "Bid_Price": np.float64, "Bid_Size": np.int32， "Offer_Price": np.float64, "Offer_Size": np.int32})
复制代码- partitioned参数
bool类型，默认为True。该参数为True时，在数据规模达到一定程度时，会将数据导入为分区内存表，如果设置为False，会直接将csv导入为未经分区的DolphinDB普通内存表。
请注意：Orca的分区表与Orca的内存表相比，在操作时也存在许多差异，具体见Orca分区表的特殊差异。若您的数据量不是很大，且在使用Orca时对Orca与pandas的一致性要求更高，请尽量不要将数据以分区的方式导入。若您数据量极大，对性能要求极高，则建议您采用分区方式导入数据。
- db_handle，table_name以及partition_columns参数
Orca的read_csv还支持db_handle，table_name和partition_columns这3个参数，这些参数用于在导入数据的时通过指定DolphinDB的数据库和表等相关信息，将数据导入到DolphinDB的分区表。
DolphinDB支持通过多种方式将数据导入DolphinDB数据库，Orca在调用read_csv函数时指定db_handle， table_name以及partition_columns参数，本质上是调用DolphinDB的loadTextEx函数，通过这种方式，我们可以直接将数据直接导入DolphinDB的分区表。
2.1.1 导入到内存表
- 导入为内存分区表
直接调用read_csv函数，数据会并行导入。由于采用并行导入，导入速度快，但是对内存占用是普通表的两倍。下面的例子中'DATA_DIR'为数据文件存放的路径。
>>> DATA_DIR = "dolphindb/database" # e.g. data_dir
>>> df = orca.read_csv(DATA_DIR + "/quotes.csv")
>>> df.head()
# output
time Exchange Symbol Bid_Price Bid_Size \
0 2017-01-01 04:40:11.686699 T AAPL 0.00 0
1 2017-01-01 06:42:50.247631 P AAPL 26.70 10
2 2017-01-01 07:00:12.194786 P AAPL 26.75 5
3 2017-01-01 07:15:03.578071 P AAPL 26.70 10
4 2017-01-01 07:59:39.606882 K AAPL 26.90 1
Offer_Price Offer_Size
0 27.42 1
1 27.47 1
2 27.47 1
3 27.47 1
4 0.00 0
复制代码- 导入为普通内存表
partitioned参数取值为False，导入为普通内存表。导入对内存要求低，但是计算速度略低于上面的导入方式：
df = orca.read_csv(DATA_DIR + "/quotes.csv"， partitioned=False)
复制代码2.1.2 导入到磁盘表
DolphinDB的分区表可以保存在本地磁盘，也可以保存在dfs上，磁盘分区表与分布式表的区别就在于分布式表的数据库路径以"dfs://"开头，而磁盘分区表的数据库路径是本地路径。
示例
我们在DolphinDB服务端创建一个磁盘分区表，下面的脚本中，'YOUR_DIR'为保存磁盘数据库的路径：
dbPath=YOUR_DIR + "/demoOnDiskPartitionedDB"
login('admin', '123456')
if(existsDatabase(dbPath))
dropDatabase(dbPath)
db=database(dbPath, RANGE, datehour(2017.01.01 00:00:00+(0..24)*3600))
复制代码请注意：以上两段脚本需要在DolphinDB服务端执行，在Python客户端中则可以通过DolphinDB Python API执行脚本。
在Python客户端中调用Orca的read_csv函数，指定数据库db_handle为磁盘分区数据库YOUR_DIR + "/demoOnDiskPartitionedDB"，指定表名table_name为"quotes"和进行分区的列partition_columns为"time"，将数据导入到DolphinDB的磁盘分区表，并返回一个表示DolphinDB数据表的对象给df，用于后续计算。
>>> df = orca.read_csv(path=DATA_DIR+"/quotes.csv", dtype={"Exchange": "SYMBOL", "SYMBOL": "SYMBOL"}, db_handle=YOUR_DIR + "/demoOnDiskPartitionedDB", table_name="quotes", partition_columns="time")
>>> df
# output
<'dolphindb.orca.core.frame.DataFrame' object representing a column in a DolphinDB segmented table>
>>> df.head()
# output
time Exchange Symbol Bid_Price Bid_Size \
0 2017-01-01 04:40:11.686699 T AAPL 0.00 0
1 2017-01-01 06:42:50.247631 P AAPL 26.70 10
2 2017-01-01 07:00:12.194786 P AAPL 26.75 5
3 2017-01-01 07:15:03.578071 P AAPL 26.70 10
4 2017-01-01 07:59:39.606882 K AAPL 26.90 1
Offer_Price Offer_Size
0 27.42 1
1 27.47 1
2 27.47 1
3 27.47 1
4 0.00 0
复制代码将上述过程整合成的Python中可执行的脚本如下：
>>> s = orca.default_session()
>>> DATA_DIR = "/dolphindb/database" # e.g. data_dir
>>> YOUR_DIR = "/dolphindb/database" # e.g. database_dir
>>> create_onDiskPartitioned_database = """
dbPath="{YOUR_DIR}" + "/demoOnDiskPartitionedDB"
login('admin', '123456')
if(existsDatabase(dbPath))
dropDatabase(dbPath)
db=database(dbPath, RANGE, datehour(2017.01.01 00:00:00+(0..24)*3600))
""".format(YOUR_DIR=YOUR_DIR)
>>> s.run(create_onDiskPartitioned_database)
>>> df = orca.read_csv(path=DATA_DIR+"/quotes.csv", dtype={"Exchange": "SYMBOL", "SYMBOL": "SYMBOL"}, db_handle=YOUR_DIR + "/demoOnDiskPartitionedDB", table_name="quotes", partition_columns="time")
复制代码上述脚本中，我们使用的defalut_session实际上就是通过orca.connect函数创建的会话，在Python端，我们可以通过这个会话与DolphinDB服务端进行交互。关于更多功能，请参见DolphinDB Python API。
请注意：在通过
read_csv函数指定数据库导入数据之前，需要确保在DolphinDB服务器上已经创建了对应的数据库。read_csv函数根据指定的数据库，表名和分区字段导入数据到DolphinDB数据库中，若表存在则追加数据，若表不存在则创建表并且导入数据。
2.1.3 导入到分布式表
read_csv函数若指定db_handle参数为dfs数据库路径，则数据将直接导入到DolphinDB的dfs数据库中。
示例
请注意只有启用enableDFS=1的集群环境或者DolphinDB单例模式才能使用分布式表。
与磁盘分区表类似，首先需要在DolphinDB服务器上创建分布式表，只需要将数据库路径改为"dfs://"开头的字符串即可。
dbPath="dfs://demoDB"
login('admin', '123456')
if(existsDatabase(dbPath))
dropDatabase(dbPath)
db=database(dbPath, RANGE, datehour(2017.01.01 00:00:00+(0..24)*3600))
复制代码在Python客户端中调用Orca的read_csv函数，指定数据库db_handle为分布式数据库"dfs://demoDB"，指定表名table_name为"quotes"和进行分区的列partition_columns为"time"，将数据导入到DolphinDB的分布式表。
>>> df = orca.read_csv(path=DATA_DIR+"/quotes.csv", dtype={"Exchange": "SYMBOL", "SYMBOL": "SYMBOL"}, db_handle="dfs://demoDB", table_name="quotes", partition_columns="time")
>>> df
# output
<'dolphindb.orca.core.frame.DataFrame' object representing a column in a DolphinDB segmented table>
>>> df.head()
# output
time Exchange Symbol Bid_Price Bid_Size \
0 2017-01-01 04:40:11.686699 T AAPL 0.00 0
1 2017-01-01 06:42:50.247631 P AAPL 26.70 10
2 2017-01-01 07:00:12.194786 P AAPL 26.75 5
3 2017-01-01 07:15:03.578071 P AAPL 26.70 10
4 2017-01-01 07:59:39.606882 K AAPL 26.90 1
Offer_Price Offer_Size
0 27.42 1
1 27.47 1
2 27.47 1
3 27.47 1
4 0.00 0
复制代码将上述过程整合成的Python中可执行的脚本如下：
>>> s = orca.default_session()
>>> DATA_DIR = "/dolphindb/database" # e.g. data_dir
>>> create_dfs_database = """
dbPath="dfs://demoDB"
login('admin', '123456')
if(existsDatabase(dbPath))
dropDatabase(dbPath)
db=database(dbPath, RANGE, datehour(2017.01.01 00:00:00+(0..24)*3600))
"""
>>> s.run(create_dfs_database)
>>> df = orca.read_csv(path=DATA_DIR+"/quotes.csv", dtype={"Exchange": "SYMBOL", "SYMBOL": "SYMBOL"}, db_handle="dfs://demoDB", table_name="quotes", partition_columns="time")
复制代码2.2 read_table函数
Orca提供read_table函数，通过该函数指定DolphinDB数据库和表名来加载DolphinDB数据表的数据，可以用于加载DolphinDB的磁盘表、磁盘分区表和分布式表。若您已在DolphinDB中创建了数据库和表，则可以直接在Orca中调用该函数加载存放在DolphinDB服务端中的数据，read_table函数支持的参数如下:
- database：数据库名称
- table：表名
- partition：需要导入的分区,可选参数
加载DolphinDB的磁盘表
read_table函数可以用于加载DolphinDB的磁盘表，首先在DolphinDB服务端创建一个本地磁盘表：
>>> s = orca.default_session()
>>> YOUR_DIR = "/dolphindb/database" # e.g. database_dir
>>> create_onDisk_database="""
saveTable("{YOUR_DIR}"+"/demoOnDiskDB", table(2017.01.01..2017.01.10 as date, rand(10.0,10) as prices), "quotes")
""".format(YOUR_DIR=YOUR_DIR)
>>> s.run(create_onDisk_database)
复制代码通过read_table函数加载磁盘表：
>>> df = orca.read_table(YOUR_DIR + "/demoOnDiskDB", "quotes")
>>> df.head()
# output
date prices
0 2017-01-01 8.065677
1 2017-01-02 2.969041
2 2017-01-03 3.688191
3 2017-01-04 4.773723
4 2017-01-05 5.567130
复制代码请注意: read_table函数要求所要导入的数据库和表在DolphinDB服务器上已经存在，若只存在数据库和没有创建表，则不能将数据成功导入到Python中。
加载DolphinDB的磁盘分区表
对于已经在DolphinDB上创建的数据表，可以通过read_table函数直接加载。例如，加载2.1.2小节中创建的磁盘分区表：
>>> df = orca.read_table(YOUR_DIR + "/demoOnDiskPartitionedDB", "quotes")
复制代码加载DolphinDB的分布式表
分布式表同样可以通过read_table函数加载。例如，加载2.1.3小节中创建的分布式表：
>>> df = orca.read_table("dfs://demoDB", "quotes")
复制代码2.3 from_pandas函数
Orca提供from_pandas函数，该函数接受一个pandas的DataFrame作为参数，返回一个Orca的DataFrame，通过这个方式，Orca可以直接加载原先存放在pandas的DataFrame中的数据。
>>> import pandas as pd
>>> import numpy as np
>>> pdf = pd.DataFrame(np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]), columns=['a', 'b', 'c'])
>>> odf = orca.from_pandas(pdf)
复制代码3 对其它格式文件的支持
对于其它数据格式的导入，Orca也提供了与pandas类似的接口。这些方法包括：read_pickle, read_fwf, read_msgpack, read_clipboard, read_excel, read_json, json_normalize,build_table_schema, read_html, read_hdf, read_feather, read_parquet, read_sas, read_sql_table, read_sql_query, read_sql, read_gbq, read_stata。
相关文章