---
source_url: https://docs.dolphindb.cn/zh/pydoc/AdvancedOperations/DataTypeCasting/TypeCasting.html
fetched_at: 2026-05-19T09:52:38Z
category: pydoc
title: 类型转换
sha1: 69ce97a560b81d1104dcbc67af642c7d5275d260
---

# 类型转换

DolphinDB 与 Python API 的交互过程始终遵循 [API交互协议](https://docs.dolphindb.cn/zh/api/connapi_intro.html)。该协议规定了通信双方在交互过程中使用的报文信息格式。在 API 与 DolphinDB 的交互过程中，通过指定 *protocol* 参数，即可选择交互过程中使用的传输数据格式协议。

Python 中包含多套常用类型系统，其与 DolphinDB 的类型系统并非一一对应。为更好地兼容各类型系统与 DolphinDB 之间的数据交互，DolphinDB Python API 自1.30.21.1版本起，session（session）和 DBConnectionPool 新增 *protocol* 参数。
目前已支持的协议包括 PROTOCOL\_DDB、PROTOCOL\_PICKLE（3.0.2.0 之前版本的默认值） 和 PROTOCOL\_ARROW。自 3.0.2.0 版本起，Python API 默认使用 PROTOCOL\_DDB 协议。
此外，对于 UUID、IPADDR、SECOND 等无法直接上传的类型， Python API 支持强制类型转换。

下例展示了 session 如何指定使用的传输协议。

```dolphindb
import dolphindb as ddb
import dolphindb.settings as keys
# 使用协议 PROTOCOL_DDB
s = ddb.session(protocol=keys.PROTOCOL_DDB)
# 使用协议 PROTOCOL_PICKLE
s = ddb.session(protocol=keys.PROTOCOL_PICKLE)
# 使用协议 PROTOCOL_ARROW
s = ddb.session(protocol=keys.PROTOCOL_ARROW)
```

PROTOCOL\_DDB、PROTOCOL\_PICKLE 和 PROTOCOL\_ARROW 协议支持不同的类型系统，提供各自特色的序列化方式以适应不同应用场景，最终实现更高效的数据传输。以下内容为用户选择传输协议提供些许参考建议：

- PROTOCOL\_DDB 协议是 DolphinDB 自定义的一套数据序列化、反序列化方案，被广泛使用于 Python API、C++ API、Java API 等 API 中。其支持的数据形式和数据类型最为全面。
- PROTOCOL\_PICKLE 协议基于 Python 原生的 [Pickle 协议](https://python.readthedocs.io/en/latest/library/pickle.html)，同时进行了部分适配 DolphinDB 的修改。
- PROTOCOL\_ARROW 协议是基于 [Apache Arrow](https://arrow.apache.org/) 通用序列化方案、用于对大型数据集进行序列化和反序列化的协议，可以跨平台、跨语言地进行高效数据传输。

从使用场景的角度来看：

- PROTOCOL\_ARROW 协议适用于从上游数据库到下游消费、且全部使用 Apache Arrow 格式作为中间格式的场景，可以方便地在各个组件之间传递数据。而用户只需要付出从数据库取出数据这一次序列化开销，后续不再需要进行序列化和反序列化。此外，使用该协议可以较高效地利用网络带宽，目前有较多的行情服务商使用 Apache Arrow 协议。
- PROTOCOL\_PICKLE 协议针对数据传输类的场景，PROTOCOL\_DDB 协议支持的数据形式和数据类型最为全面。如果场景中使用 pandas 的 DataFrame 较多，则更推荐使用 PROTOCOL\_PICKLE 协议和 PROTOCOL\_DDB 协议。

**注：** 自 Python API 3.0.3.0 起，针对 Python 3.13 及以上版本安装包将不再支持 PICKLE 协议。

## 交互流程

API 与 DolphinDB 的交互流程可以简化为 session 建立阶段和单次 run 请求阶段。

### session 建立阶段

API 先向 DolphinDB 发起连接请求，发送的报文中包含一组 flag。该 flag 中包含协议参数对应的标志位，表示建立 session 时 API 选用的序列化、反序列化协议。目前版本 Python API 支持的可选协议有 PROTOCOL\_DDB、PROTOCOL\_PICKLE、PROTOCOL\_ARROW。

协议参数的生效周期和 session 保持一致。在 session 连接期间，如果上传、查询涉及到的数据形式属于该协议支持的数据形式，则会使用该协议对应的序列化、反序列化方案进行类型转换。如果不属于该协议支持的数据形式，则默认使用 PROTOCOL\_DDB 的方式进行处理。举例来说，Python API 中的协议 PROTOCOL\_PICKLE 仅支持 Matrix 和 Table 数据形式的反序列化。在下载一个 Vector 数据时，即便指定了使用 PROTOCOL\_PICKLE 协议，但由于 PROTOCOL\_PICKLE 不支持 Vector 数据形式，因此仍会使用默认的 PROTOCOL\_DDB 协议的反序列化流程。

### 单次 run 请求阶段

与建立 session 类似，单次执行 run 时发送的请求同样附带一组 flag。该 flag 中包含协议参数和附加参数，例如协议参数 *PROTOCOL\_PICKLE* 和 *PROTOCOL\_DDB* 都具有附加参数 *pickleTableToList*。如果在执行 run 方法时指定 `pickleTableToList=True`，则将改变当次请求的序列化、反序列化流程。

但与建立 session 不同的是，单次 run 请求的 flag 参数生效周期和一次查询一致。
