JavaScript API

import { DDB } from 'dolphindb'
// 已有的使用 CommonJS 模块的项目的导入方法为 const { DDB } = await import('dolphindb')
// 在浏览器中使用: import { DDB } from 'dolphindb/browser.js'

// 使用 WebSocket URL 初始化连接到 DolphinDB 的实例（不建立实际的网络连接）
let ddb = new DDB('ws://127.0.0.1:8848')

// 使用 HTTPS 加密
// let ddb = new DDB('wss://dolphindb.com')

// 建立到 DolphinDB 的连接（要求 DolphinDB 数据库版本不低于 1.30.16 或 2.00.4）
await ddb.connect()

<script type="module">
    import { DDB } from 'https://cdn.dolphindb.cn/assets/api.js'
    
    let ddb = new DDB('ws://127.0.0.1:8848')
    
    await ddb.connect()
</script>

代码补全、函数提示数据:

• https://cdn.dolphindb.cn/assets/docs.zh.json
• https://cdn.dolphindb.cn/assets/docs.en.json

let ddb = new DDB('ws://127.0.0.1:8848', {
    // 是否在建立连接后自动登录，默认 `true`
    autologin: true,
    
    // DolphinDB 登录用户名，默认 `'admin'`
    username: 'admin',
    
    // DolphinDB 登录密码，默认 `'123456'`
    password: '123456',
    
    // 设置 python session flag，默认 `false`
    python: false,
    
    // 设置当前会话执行的 sql 标准, 请使用 SqlStandard 枚举进行传参，默认 `DolphinDB`
    // sql: SqlStandard.MySQL,
    // sql: SqlStandard.Oracle,
    
    // 设置该选项后，该数据库连接只用于流数据，详细用法见后文 `5. 流数据`
    streaming: undefined
})

import { DdbInt } from 'dolphindb'

const result = await ddb.call('add', [new DdbInt(1), new DdbInt(1)])
// TypeScript: const result = await ddb.call<DdbInt>('add', [new DdbInt(1), new DdbInt(1)])

console.log(result.value === 2)  // true

scalar 形式的 NULL 对象，其对应 DdbObj 的 value 为 JavaScript 中的 null：

;(await ddb.eval('double()')).value === null

// 创建 NULL 对象
new DdbInt(null)
new DdbDouble(null)

async call <T extends DdbObj> (
    /** 函数名 */
    func: string,
    
    /** 调用参数 (传入的原生 string 和 boolean 会被自动转换为 DdbObj<string> 和 DdbObj<boolean>) */
    args?: (DdbObj | string | boolean)[] = [ ],
    
    /** 调用选项 */
    options?: {
        /** 紧急 flag。使用 urgent worker 执行，防止被其它作业阻塞 */
        urgent?: boolean
        
        /** 设置结点 alias 时发送到集群中对应的结点执行 (使用 DolphinDB 中的 rpc 方法) */
        node?: string
        
        /** 设置多个结点 alias 时发送到集群中对应的多个结点执行 (使用 DolphinDB 中的 pnodeRun 方法) */
        nodes?: string[]
        
        /** 设置 node 参数时必传，需指定函数类型，其它情况下不传 */
        func_type?: DdbFunctionType
        
        /** 设置 nodes 参数时选传，其它情况不传 */
        add_node_alias?: boolean
    } = { }
): Promise<T>

const result = await ddb.eval(
    'def foo (a, b) {\n' +
    '    return a + b\n' +
    '}\n' +
    'foo(1l, 1l)\n'
)

// TypeScript:
// import type { DdbLong } from 'dolphindb'
// const result = await ddb.eval<DdbLong>(...)

console.log(result.value === 2n)  // true

上面例子中，通过字符串上传了一段脚本到 DolphinDB 数据库执行，并接收最后一条语句 foo(1l, 1l) 执行结果 result

<DdbLong> 用于 TypeScript 推断返回值的类型

• result 是一个 DdbLong，也是 DdbObj<bigint>
• result.form 是 DdbForm.scalar
• result.type 是 DdbType.long
• result.value 是 JavaScript 中原生的 bigint (long 的精度不能用 JavaScript 的 number 准确表示，但可以用 bigint 表示)

只要 WebSocket 连接不断开，在后续的会话中 foo 这个自定义函数会一直存在，可复用，比如后续通过 await ddb.call<DdbInt>('foo', [new DdbInt(1), new DdbInt(1)]) 调用这个自定义函数

async eval <T extends DdbObj> (
    /** 执行的脚本 */
    script: string,
    
    /** 执行选项 */
    options: {
        /** 紧急 flag，确保提交的脚本使用 urgent worker 处理，防止被其它作业阻塞 */
        urgent?: boolean
    } = { }
): Promise<T>

import { DdbVectorDouble } from 'dolphindb'

let a = new Array(10000)
a.fill(1.0)

ddb.upload(['bar1', 'bar2'], [new DdbVectorDouble(a), new DdbVectorDouble(a)])

上面的例子中，上传了 bar1, bar2 两个变量，变量值是长度为 10000 的 double 向量

只要 WebSocket 连接不断开，在后续的会话中 bar1, bar2 这些变量会一直存在，可复用

async upload (
    /** 上传的变量名 */
    vars: string[],
    
    /** 上传的变量值 */
    args: (DdbObj | string | boolean)[]
): Promise<void>