DolphinDB 数据访问接口开发教程

例1： 用户可以访问全表的数据

login("admin", "123456")
def query(startDate, endDate, cols="*", security=NULL) {
	whereConditions = [<date between startDate:endDate>]
	if (typestr(security) <> VOID) {
		whereConditions.append!(<SecurityID in security>)
	}
	return eval(sql(select=sqlCol(cols), from=loadTable("dfs://stock", "factor"), where=whereConditions))
}
addFunctionView(query)
grant("testGroup1", VIEW_EXEC, "query")

• 参数
  • startDate 开始日期
  • endDate 结束日期
  • cols 列名，默认所有列
  • security 证券代码，默认所有证券代码

例2： 限制用户仅能访问表中最近一年的数据

login("admin", "123456")
def queryRecentYear(startDate=NULL, endDate=NULL, cols="*", security=NULL) {
	start = temporalAdd(date(now()), -1, "y")
	end = date(now())
	if (startDate == NULL) { date0 = start }
	else if (startDate < start) { throw("Not granted to read data before " + start) }
	else { date0 = startDate }
	if (endDate == NULL) { date1 = end }
	else if (endDate > end) { throw("Not granted to read data after " + end) }
	else { date1 = endDate }
	whereConditions = [<date between date0:date1>]
	if (typestr(security) <> VOID) {
		whereConditions.append!(<SecurityID in security>)
	}
	return eval(sql(select=sqlCol(cols), from=loadTable("dfs://stock", "factor"), where=whereConditions))
}
addFunctionView(queryRecentYear)
grant("testGroup1", VIEW_EXEC, "queryRecentYear")

• 参数
  • startDate 开始日期，默认1年前
  • endDate 结束日期，默认今天
  • cols 列名，默认所有列
  • security 证券代码，默认所有证券代码

例3： 限制用户限制用户仅能访问表中前 10 列的数据

login("admin", "123456")
def queryFirst10Col(startDate, endDate, cols=NULL, security=NULL) {
	grantedCols = loadTable("dfs://stock", "factor").schema()['colDefs']['name'][:10]
	notGranted = not(cols in grantedCols)
	if (typestr(cols) == VOID) { col = grantedCols }
	else if (sum(notGranted) > 0) {	throw("Not granted to read columns " + toStdJson(distinct(cols[notGranted]))) }
	else { col = cols }
	whereConditions = [<date between startDate:endDate>]
	if (typestr(security) <> VOID) {
		whereConditions.append!(<SecurityID in security>)
	}
	return eval(sql(select=sqlCol(col), from=loadTable("dfs://stock", "factor"), where=whereConditions))
}
addFunctionView(queryFirst10Col)
grant("testGroup1", VIEW_EXEC, "queryFirst10Col")

• 参数
  • startDate 开始日期
  • endDate 结束日期
  • cols 列名，默认允许访问的所有列
  • security 证券代码，默认所有证券代码

例4： 限制用户仅能访问表中 2020 年以后的几列数据

login("admin", "123456")
def queryCond(startDate, endDate, cols=NULL, security=NULL) {
	grantedCols = `SecurityID`date`time`col46`col47`col48`col49`col50
	notGranted = not(cols in grantedCols)
	if (typestr(cols) == VOID) { col = grantedCols }
	else if (sum(notGranted) > 0) {	throw("Not granted to read columns " + toStdJson(distinct(cols[notGranted]))) }
	else { col = cols }
	if (startDate < 2020.01.01) {
		throw("Not granted to read data before 2020")
	}
	if (startDate < temporalAdd(endDate, -1, "y")) {
		throw("Time duration exceeds 1 year. Please change the dates.")
	}
	whereConditions = [<date between startDate:endDate>]
	if (typestr(security) <> VOID) {
		whereConditions.append!(<SecurityID in security>)
	}
	return eval(sql(select=sqlCol(col), from=loadTable("dfs://stock", "factor"), where=whereConditions))
}
addFunctionView(queryCond)
grant("testGroup1", VIEW_EXEC, "queryCond")

• 参数
  • startDate, endDate 开始日期，结束日期，间隔不得超过 1 年
  • cols 列名，默认允许访问的所有列
  • security 证券代码，默认所有证券代码

本小节将简要介绍 DolphinDB 开发 IDE 的安装和使用方法，更详细的使用教程可以在官方文档中心搜索学习。

• 在 DolphinDB server 中登录用户 testUser1 的账号

login("testUser1", "123456")

• 使用全表访问接口访问数据

// 访问全表数据
t = query(startDate=2015.01.01, endDate=2024.12.31)

// 访问2024年2月指定证券、指定列的数据
t = query(startDate=2024.02.01, endDate=2024.02.29, security="000001", cols=`SecurityID`date`time`col1`col2`col3`col4`col5`col6`col7`col8`col9`col10)

• 使用行级别访问接口访问数据

// 访问近1年所有数据
t = queryRecentYear()

// 访问指定日期开始、指定列的数据
t = queryRecentYear(startDate=2023.07.10, cols=`SecurityID`date`time`col2`col3)

如果数据查询的时间范围超过最近1年，则会提示如下错误：

t = queryRecentYear(2023.07.01, , ["SecurityID","date","time","col2","col3"]) => queryRecentYear: throw "Not granted to read data before " + start => Not granted to read data before 2023.07.05

• 使用列级别访问接口访问数据

// 访问2023年指定证券、允许访问的所有列的数据
t = queryFirst10Col(startDate=2023.01.01, endDate=2023.12.31, security=`000008`000009`000010)

// 访问2022年12月指定列的数据
t = queryFirst10Col(startDate=2022.12.01, endDate=2022.12.31, cols=`SecurityID`date`time`col4`col5`col6)

• 使用行列级别访问接口访问数据

// 访问2021年1月允许访问的所有列的数据
t = queryCond(startDate=2021.01.01, endDate=2021.01.31)

// 访问2021年指定列的数据
t = queryCond(startDate=2021.01.01, endDate=2021.12.31, cols=`SecurityID`date`time`col47`col48`col49)

dolphindb 是 DolphinDB 的官方 Python API，用于连接 DolphinDB 服务端和 Python 客户端，从而实现数据的双向传输和脚本的调用执行。dolphindb 可以方便您在 Python 环境中调用 DolphinDB 进行数据的处理、分析和建模等操作，利用其优秀的计算性能和强大的存储能力来帮助您加速数据的处理和分析。

参考安装教程，安装 Python API。在 Jupyter Notebook 中新建一个* .ipynb *文件，可以在 Python API 中查看数据。

图5-1 在 Python API 中查看数据

dolphindb 提供了的 session() 和 run() 接口，可以快速实现 Python 和 DolphinDB server 的交互，方便用户调用教程第2章中通过函数视图封装的取数接口，下面的示例是基于原生 Python API 交互接口实现的。

• 在 Python API 中创建 session，登录用户 testUser2 的账号

  import pandas as pd
  import dolphindb as ddb
  
  # 建立会话并登陆账号
  s = ddb.session("192.198.1.38", 8200, 'testUser2', '123456')

• 使用全表访问接口访问数据

  # 访问全表数据
  startDate = np.datetime64("2015-01-01", "D")
  endDate = np.datetime64("2024-12-31", "D")
  cols = "*"
  df = s.run("query", startDate, endDate, cols)

• 使用行级别访问接口访问数据

  # 访问近1年所有数据
  startDate = np.datetime64("2024-07-01", "D")
  df = s.run("queryRecentYear", startDate)

• 使用列级别访问接口访问数据

  # 访问2023年指定证券、允许访问的所有列的数据
  startDate = np.datetime64("2023-01-01", "D")
  endDate = np.datetime64("2023-12-31", "D")
  cols = None
  security = np.array(['000008', '000009', '000010'])
  df = s.run("queryFirst10Col", startDate, endDate, cols, security)

• 使用行列级别访问接口访问数据

  # 访问2021年指定列的数据
  startDate = np.datetime64("2021-01-01", "D")
  endDate = np.datetime64("2021-12-31", "D")
  cols = np.array(['SecurityID', 'date', 'time', 'col47', 'col48', 'col49'])
  df = s.run("queryCond", startDate, endDate, cols)

为了提高取数接口的易用性，用户可以进一步在 Python 中对 dolphindb 提供的标准接口进行二次封装。本教程将提供一些简单的示例，旨在给读者提供一种二次封装的思路，提高读者的开发效率。

• query.py文件中是对 dolphindb 标准接口二次封装的简单示例，需要和查询代码* .py* 文件或* .ipynb* 文件放在同一目录下，以便调用

#!/usr/bin/env python
# coding: utf-8

def query(session, startDate, endDate, cols='"*"', security='NULL'):
    script = 'query({}, {}, {}, {})'.format(startDate, endDate, cols, security)
    return session.run(script)

def queryRecentYear(session, startDate='NULL', endDate='NULL', cols='"*"', security='NULL'):
    script = 'queryRecentYear({}, {}, {}, {})'.format(startDate, endDate, cols, security)
    return session.run(script)

def queryFirst10Col(session, startDate, endDate, cols='NULL', security='NULL'):
    script = 'queryFirst10Col({}, {}, {}, {})'.format(startDate, endDate, cols, security)
    return session.run(script)

def queryCond(session, startDate, endDate, cols='NULL', security='NULL'):
    script = 'queryCond({}, {}, {}, {})'.format(startDate, endDate, cols, security)
    return session.run(script)

接下来，给出一些结合 Python 客户端二次封装后的取数接口的示例。

• 在 Python API 中创建 session，登录用户 testUser2 的账号

  import pandas as pd
  import dolphindb as ddb
  import query
  
  # 建立会话并登陆账号
  s = ddb.session("192.198.1.38", 8200, 'testUser2', '123456')

• 使用全表访问接口访问数据

  # 访问全表数据
  df = query.query(session=s, startDate='2015.01.01', endDate='2024.12.31')
  
  # 访问2024年2月指定证券、指定列的数据
  df = query.query(session=s, startDate='2024.02.01', endDate='2024.02.29', security='`000001', cols='`SecurityID`date`time`col1`col2`col3`col4`col5`col6`col7`col8`col9`col10')

• 使用行级别访问接口访问数据

  # 访问近1年所有数据
  df = query.queryRecentYear(session=s)
  
  # 访问指定日期开始、指定列的数据
  df = query.queryRecentYear(session=s, startDate='2024.07.01', cols='`SecurityID`date`time`col2`col3')

• 使用列级别访问接口访问数据

  # 访问2023年指定证券、允许访问的所有列的数据
  df = query.queryFirst10Col(session=s, startDate='2023.01.01', endDate='2023.12.31', security='`000008`000009`000010')
  
  # 访问2022年12月指定列的数据
  df = query.queryFirst10Col(session=s, startDate='2022.12.01', endDate='2022.12.31', cols='`SecurityID`date`time`col4`col5`col6')

• 使用行列级别访问接口访问数据

  # 访问2021年1月允许访问的所有列的数据
  df = query.queryCond(session=s, startDate='2021.01.01', endDate='2021.01.31')
  
  # 访问2021年指定列的数据
  df = query.queryCond(session=s, startDate='2021.01.01', endDate='2021.12.31', cols='`SecurityID`date`time`col47`col48`col49')

为了方便读者快速扩展该取数接口的设计方法，本教程提供了以下几种常用 API 语言的示例代码，通过 run(funcName, args...) 的规范 rpc 接口来调用，大家可以根据标准接口进行二次封装，对外提供更加便捷的数据访问接口。

• C++ 示例

  # 建立会话并登陆账号
  DBConnection conn;
  conn.connect("192.198.1.38", 8200, "testUser2", "123456");
  
  # 访问全表数据
  ConstantSP startDate = Util::createDate(2015, 1, 1);
  ConstantSP endDate = Util::createDate(2024, 12, 31);
  ConstantSP cols = Util::createString("*");
  vector<ConstantSP> funcArgs = {startDate, endDate, cols};
  auto tb = conn.run("query", funcArgs);

• Java 示例

  // 建立会话并登陆账号
  DBConnection conn= new DBConnection();
  conn.connect("192.198.1.38", 8200, "testUser2", "123456");
  
  // 访问全表数据
  BasicDate startDate = new BasicDate(LocalDate.of(2015,1,1));
  BasicDate endDate = new BasicDate(LocalDate.of(2024,12,31));
  BasicString cols = new BasicString("*");
  List<Entity> funcArgs = Arrays.asList(startDate, endDate, cols);
  BasicTable tb = (BasicTable)conn.run("query", funcArgs);

• C# 示例

  // 建立会话并登陆账号
  DBConnection conn = new DBConnection();
  conn.connect("192.198.1.38", 8200, "testUser2", "123456");
  
  // 访问全表数据
  BasicDate startDate = new BasicDate(new DateTime(2015, 1, 1));
  BasicDate endDate = new BasicDate(new DateTime(2024, 12, 31));
  BasicString cols = new BasicString("*");
  List<IEntity> funcArgs = new List<IEntity> { startDate, endDate, cols };
  BasicTable tb = (BasicTable)conn.run("query", funcArgs);

• JavaScript 示例

  // 建立会话并登陆账号
  let ddb = new DDB('ws://192.198.1.38:8200', { username: 'testUser2', password: '123456' })
  await ddb.connect()
  
  // 访问全表数据      
  const start = '2015.01.01'
  const end = '2024.12.31'
  const tb = await ddb.execute(`query(${start}, ${end}, "*")`)

调用函数视图访问数据时报如下错误：

t = queryRecentYear(2023.06.01) => queryRecentYear: throw "Not granted to read data before " + start => Not granted to read data before 2023.06.28
t = queryFirst10Col(2023.01.01, 2023.12.31, ["SecurityID","date","time","col40","col50"]) => queryFirst10Col: throw "Not granted to read columns " + toStdJson(distinct(cols[notGranted])) => Not granted to read columns ["col50","col40"]

造成问题原因：

• 没有权限访问相关的行或列

解决方案：

• 修改相关参数，在权限内访问数据

t = queryRecentYear(startDate=2023.07.01)
t = queryFirst10Col(startDate=2023.01.01, endDate=2023.12.31, cols=`SecurityID`date`time`col5`col6`col7)