执行命令与管理连接

使用 exec() 执行一段 DolphinDB 脚本，并返回脚本执行结果。

def exec(
    self,
    script,
    *,
    clear_memory=False,
    table_to_list=False,
    priority=4,
    parallelism=64,
    fetch_size=None,
    disable_decimal=False,
) -> object: ...

• script：必填参数，用于指定待执行的 DolphinDB 脚本，可以是表达式、查询语句，也可以包含多条以分号分隔的语句。

conn.exec("x = 1..10")
print(conn.exec("sum(x)"))
# 输出：55

• clear_memory：可选参数，用于指定请求完成后是否释放本次请求在会话中创建的变量，默认值为 False。

设为 True 时，适合执行不需要在后续请求中复用中间变量的脚本。

conn.exec("temporary = 1..100", clear_memory=True)

• table_to_list：可选参数，用于指定是否将表结果按列转换为 list，仅对 DDB 和 PICKLE 协议有效，默认值为 False。

注意：在 DDB 协议下，若表中包含数组向量（array vector，即元素为向量的列），开启该选项后会将其转换为二维数组。这要求该列各行的向量长度必须完全一致，否则会导致转换失败。

columns = conn.exec(
    "table(1..3 as id, `A`B`C as sym)",
    table_to_list=True,
)
print(columns[0])
# 输出：[1 2 3]

• priority：可选参数，用于指定作业优先级，取值范围为 0 到 9，取值越高表示任务执行的优先级越高。默认值为 4。

• parallelism：可选参数，用于指定单个数据节点上执行该作业子任务的最大线程数，必须大于 0，默认值为 64。

priority 的实际值不超过服务端 setMaxJobPriority 设置的上限；parallelism 的实际值不超过服务端 setMaxJobParallelism 设置的上限。

result = conn.exec(
    "sum(1..1000000)",
    priority=7,
    parallelism=16,
)

• fetch_size：可选参数，用于指定分段读取时每段返回的记录数，应为不小于 8192 的整数，默认值为 None。

指定后，exec() 返回 BlockReader，而不是一次性返回完整结果。该参数仅用于返回表的脚本。

分段读取的每一段表数据返回 pandas.DataFrame，不按构造时的 Arrow 或 PICKLE 协议转换结果；当前也不会应用 table_to_list 和 disable_decimal 参数。需要这些转换选项时，应使用普通查询。

conn.exec("testblock = table(1..20000 as id)")
block = conn.exec("select * from testblock", fetch_size=8192)

total = 0
try:
    for data in block:
        total += len(data)
finally:
    block.skip_all()

print(total)
# 输出：20000

全部数据读取完毕前，同一连接不能执行其他命令。若不再需要剩余数据，必须调用 skip_all()：

block = conn.exec("select * from testblock", fetch_size=8192)
first_block = block.read()
block.skip_all()

print(conn.exec("1 + 1"))
# 输出：2

注意：

• 使用 fetch_size 分段读取时，fetch_size 必须大于或等于 8192，且执行的脚本结果必须为表。异步模式下请勿指定 fetch_size。

• 若在获取 BlockReader 之前发生异常（例如参数非法或结果类型不匹配），该连接将无法继续执行其他操作。此时建议调用 close() 关闭当前连接并重新创建，避免复用该连接。

• disable_decimal：可选参数，控制是否将结果表中的 DECIMAL 列转换为 DOUBLE。默认值为 False，即保留 DECIMAL 类型。

当设置为 True 时，结果表中的 DECIMAL 列会转换为 DOUBLE。该参数需配合 DolphinDB 2.00.12.3、3.00.1 或更高版本使用；客户端不会预先校验服务端版本。详见官方常用方法说明。

result = conn.exec(
    "table(decimal32([1.23, 2.345], 3) as value)",
    disable_decimal=True,
)
print(result.dtypes)
# value    float64

• 未指定 fetch_size 时，exec() 返回脚本执行结果；具体 Python 类型取决于 DolphinDB 数据形式和当前协议。

• 同步模式下指定 fetch_size 时，返回 BlockReader，用于分段读取表结果。

• 启用异步模式（enable_async=True）时，请求发送后不等待服务端响应，返回 None。

• priority 不在 0 到 9 范围内、parallelism 不是正整数、fetch_size 小于 8192，或服务端脚本执行失败时，通常抛出 RuntimeError。

• 上一个 BlockReader 尚未读取完毕且未调用 skip_all() 放弃剩余数据时，在同一连接上继续执行 exec()、call()、run()、upload() 或读取 is_alive，通常会抛出 RuntimeError。

使用 call() 调用 DolphinDB 内置函数或服务端已定义的用户自定义函数。

def call(
    self,
    func,
    *args,
    clear_memory=False,
    table_to_list=False,
    priority=4,
    parallelism=64,
    disable_decimal=False,
) -> object: ...

• func：必填参数，用于指定要调用的 DolphinDB 内置函数或用户自定义函数名称。

• args：可选参数，用于按顺序传入服务端函数的位置参数。

其余参数与 exec() 中的同名参数含义相同；call() 不支持 fetch_size，不能用于分段读取结果。

print(conn.call("sum", [1, 2, 3]))
print(conn.call("add", 1, 2))
# 输出：6
# 输出：3

conn.exec("def answer(){ return 42; }")
print(conn.call("answer"))
# 输出：42

函数不存在、服务端参数校验失败、权限不足或函数执行失败时，通常抛出 RuntimeError；Python 调用签名不匹配时，抛出 TypeError。

run() 是兼容入口，根据是否传入函数参数，将请求分派给 exec() 或 call()。

• script：必填参数，用于指定待执行的脚本，或在传入函数参数时指定要调用的服务端函数名。

• args：可选参数，用于决定 run() 的调用模式，并作为位置参数传给服务端函数。

• kwargs：可选参数，用于传入 exec() 或 call() 支持的同名关键字参数。

def run(self, script, *args, **kwargs) -> object: ...

• 未传入 args 时，等价于 exec(script, **kwargs)。

• 传入一个或多个 args 时，等价于 call(script, *args, **kwargs)。

print(conn.run("1 + 1"))
print(conn.run("add", 1, 2))
# 输出：2
# 输出：3

fetch_size 仅适用于未传入 args 的脚本执行模式；如果在函数调用模式下传入 fetch_size，将抛出 TypeError。

调用无参数函数时，请使用 call("functionName") 或 exec("functionName()")。run("functionName") 会将函数名按脚本内容执行，并不会自动调用该函数。

def login(self, userid, password, enable_encryption=True) -> None: ...

• userid：必填参数，用于指定登录 DolphinDB 的用户名。

• password：必填参数，用于指定对应用户的登录密码。

• enable_encryption：可选参数，指定在传输用户登录凭据时是否启用加密，默认值为 True。

conn = ddb.DBConnection()
conn.connect("localhost", 8848)
conn.login("admin", "your_password")

def close(self) -> None: ...

close() 可以重复调用。对象析构时也会尝试关闭连接，但不应依赖 Python 垃圾回收及时释放资源；推荐使用 try...finally 确保连接最终被关闭。

conn = ddb.DBConnection()
try:
    if not conn.connect("localhost", 8848):
        raise RuntimeError("Failed to connect to DolphinDB")
    print(conn.exec("1 + 1"))
finally:
    conn.close()