JSON API

简介

DolphinDB Web API是访问DolphinDB server资源的程序接口。向url(http://IP:Port) post JSON数据包，即可使DolphinDB server运行指定脚本代码，并将结果以JSON的格式返回。

任何编程语言，只要支持通过http协议向指定url提交数据，且能够解析JSON格式数据包，那么就可以使用DolphinDB Web API访问DolphinDB server。

示例

返回值对象示例

在DolphinDB server中做一个1+2=3的运算。组织一个类似下面的格式的JSON数据包，然后把数据包post到datanode url，比如 http://localhost:8848。

javascript调用示例

var paramJson = {...}
var option = {
        url: "http://localhost:8848",
        async: true,
        data: JSON.stringify(paramJson),
        type: "POST",
        dataType: "json",
        success: function (data) {
             var resultJson = data; //data={...}
        }
    }
    $.ajax(option);

入参格式

注意在浏览器环境下，JSON里包含+号等特殊符号在提交前先做encodeURIComponent

var code = "1+2";
code = encodeURIComponent(code);
paramJson = {
	"sessionID": "942605602",
	"functionName": "executeCode",
	"params": [{
		"name": "script",
		"form": "scalar",
		"type": "string",
		"value": code
	}]
}

返回结果格式

resultJson = {
	"sessionID": "942605602",
	"resultCode": "0",
	"msg": "",
	"object": [{
		"name": "",
		"form": "scalar",
		"type": "int",
		"value": "3"
	}]
}

返回Table对象示例

这个示例通过DolphinDB script ：select * from table(1..3 as id,'tom' 'bob' 'tony' as name)，在server端生成一个table,并以json格式返回给客户端，返回的json是以多个Array组成。

入参格式

var code = "select * from table(1..3 as id,'tom' 'bob' 'tony' as name)";
code = encodeURIComponent(code);
var paramJson = {
    "sessionID": "0",
    "functionName": "executeCode",
    "params": [{
        "name": "script",
        "form": "scalar",
        "type": "string",
        "value": code
    }]
};

返回结果格式

{
	"sessionID": "1130397736",
	"resultCode": "0",
	"msg": "",
	"object": [{
		"name": "",
		"form": "table",
		"size": "3",
		"value": [{
			"name": "id",
			"form": "vector",
			"type": "int",
			"size": "3",
			"value": [1, 2, 3]
		}, {
			"name": "name",
			"form": "vector",
			"type": "string",
			"size": "3",
			"value": ["tom", "bob", "tony"]
		}]
	}]
}

参数为Table对象示例

这个示例中，我们以server端的equal join function(ej)为例，通过对两个table进行ej，返回的join结果也是table。

为了方便理解，下面以简化方式列出入参和返回结果。

leftTable: table(1 2 3 as id,'a' 'b' 'c' as name)

rightTable: table(2 3 4 as id,'e' 'f' 'g' as name)

resultTable: table(2 3 as id,'b' 'c' as name,'e' 'f' as rightTable_name)

入参格式

var paramJson = {
        "sessionID": "0",
        "functionName": "ej",
        "params": [{
            "name": "leftTable",
            "form": "table",
            "size": "3",
            "value": [{
                    "name": "id",
                    "form": "vector",
                    "type": "int",
                    "size": "3",
                    "value": [1, 2, 3]
                }, {
                    "name": "name",
                    "form": "vector",
                    "type": "string",
                    "size": "3",
                    "value": ["a", "b", "c"]
                }]
        },{
            "name": "rightTable",
            "form": "table",
            "size": "3",
            "value": [{
                    "name": "id",
                    "form": "vector",
                    "type": "int",
                    "size": "3",
                    "value": [2, 3, 4]
                }, {
                    "name": "name",
                    "form": "vector",
                    "type": "string",
                    "size": "3",
                    "value": ["e", "f", "g"]
                }]
        },{
            "name": "joincolumn",
            "form": "scalar",
            "type": "string",
            "value": "id"
        }]
    };

返回结果格式

{
	"sessionID": "1358033411",
	"resultCode": "0",
	"msg": "",
	"object": [{
		"name": "",
		"form": "table",
		"size": "2",
		"value": [{
			"name": "id",
			"form": "vector",
			"type": "int",
			"size": "2",
			"value": [2, 3]
		}, {
			"name": "name",
			"form": "vector",
			"type": "string",
			"size": "2",
			"value": ["b", "c"]
		}, {
			"name": "righttable_name",
			"form": "vector",
			"type": "string",
			"size": "2",
			"value": ["e", "f"]
		}]
	}]
}

JSON包格式详解

提交格式

SessionID：指定调用的会话ID，初次调用会话ID为0，在一个用户登录会话期间，同一个Server会将SessionID跟登录用户关联。
functionName：指定调用的函数名称。
params: functionName指定参数所需要的入参，params是一个json array。
length：数组的最大长度或查询table返回的最大行数，默认为1024，最大值为100000。

返回格式

sessionID：本次脚本执行所在的会话ID。
resultCode : 0-执行正常 1-执行异常。
msg：当resultCode为1时，此处会告知异常提示信息。
object：脚本执行返回的对象信息。

Javascript 开发包

DolphinDB为javascript的开发者提供了的开发包。要使用javascript 开发包，需要引入 DolphinDBConnection.js，DolphinDBEntity.js，以及 jquery 开发包。

DolphinDBConnection.js提供了run,runFunction,login,logout 方法。

run(script, [callback]) : 运行DolphinDB脚本

var server = new DolphinDBConnection("http://localhost:8848");
server.run("1+2",function(re){
    console.log(var DolphinDBEntity(re).toScalar());
});

runFunction(functionName, params, [callback]) : 运行DolphinDB函数，并以json方式传递参数。

var server = new DolphinDBConnection("http://localhost:8848");
var param = [{
        "name": "userId",
        "form": "scalar",
        "type": "string",
        "value": "user1"
    }, {
        "name": "password",
        "form": "scalar",
        "type": "string",
        "value": "passwordstring"
    }];
server.runFunction("login", param , function(re){
    if (re.resultCode === "1") {
        alert(re.msg);
    }
});

var server = new DolphinDBConnection("http://localhost:8848");
server.login("user1","pass");

logout() : 注销当前登录用户。

var server = new DolphinDBConnection("http://localhost:8848");
server.logout();

注意事项

javascript开发包依赖JQuery，只能在浏览器环境下使用。
默认情况下，Web数据接口单表一次返回1024条记录。通过length参数可设置返回更多（上限为10万）条记录。指定length的示例如下：

var code = "select * from table(1..200000 as id)";
code = encodeURIComponent(code);
var paramJson = {
    "sessionID": "0",
    "functionName": "executeCode",
    "length" : 100000,  //最大为100000，若设置超过100000，实际生效值仍为100000
    "params": [{
        "name": "script",
        "form": "scalar",
        "type": "string",
        "value": code
    }]
};
var option = {
        url: "http://localhost:8848",
        async: true,
        data: JSON.stringify(paramJson),
        type: "POST",
        dataType: "json",
        success: function (data) {
            var resultJson = data; //data={...}
            console.log(resultJson);
        }
    }
$.ajax(option);