create-dwy 0.12.2 → 0.13.1

package/templates/claude-global/skills//346/225/260/346/215/256/345/272/223/dwy-dolphindb/references/official/pydoc/AdvancedOperations/DataTypeCasting/PROTOCOL_DDB.md

@@ -0,0 +1,714 @@
+---
+source_url: https://docs.dolphindb.cn/zh/pydoc/AdvancedOperations/DataTypeCasting/PROTOCOL_DDB.html
+fetched_at: 2026-05-19T09:52:38Z
+category: pydoc
+title: PROTOCOL_DDB
+sha1: 546a18924602ec389c02aede42842d81f8b95d75
+---
+
+# PROTOCOL\_DDB
+
+PROTOCOL\_DDB 作为 DolphinDB 自定义的一套数据序列化、反序列化方案，广泛使用于 Python API、C++ API、Java API 等 API 中，且其支持的**数据形式**和**数据类型**最为全面。
+
+- **注1**： 数据形式指 DolphinDB 类型系统中的 DATAFORM，表示数据结构的形式，通常包含 Scalar、Vector、Table 等。
+- **注2**： 数据类型指 DolphinDB 类型系统中的 DATATYPE，表示数据的具体类型，通常包含 INT、DOUBLE、DATETIME 等。
+- **注3**： 以下简称 Python 库 NumPy 为 **np**，pandas 为 **pd**。
+
+## 启用 PROTOCOL\_DDB
+
+在以下示例中，session 和 DBConnectionPool 通过设置参数 *protocol* 指定启用 PROTOCOL\_DDB 协议。
+
+```dolphindb
+import dolphindb as ddb
+import dolphindb.settings as keys
+
+s = ddb.session(protocol=keys.PROTOCOL_DDB)
+s.connect("localhost", 8848, "admin", "123456")
+
+pool = ddb.DBConnectionPool("localhost", 8848, "admin", "123456", 10, protocol=keys.PROTOCOL_DDB)
+```
+
+## PROTOCOL\_DDB 数据形式支持表
+
+PROTOCOL\_DDB 支持的数据形式如下表展示：
+
+| 附加参数 | 数据形式 | 序列化 | 反序列化 |
+| --- | --- | --- | --- |
+| pickleTableToList=False | Scalar | 支持 | 支持 |
+| pickleTableToList=False | Vector | 支持 | 支持 |
+| pickleTableToList=False | Pair | 不支持 | 支持 |
+| pickleTableToList=False | Matrix | 支持 | 支持 |
+| pickleTableToList=False | Set | 支持 | 支持 |
+| pickleTableToList=False | Dict | 支持 | 支持 |
+| pickleTableToList=False | Table | 支持 | 支持 |
+| pickleTableToList=True | Table | 不支持 | 支持 |
+
+## 序列化 Python->DolphinDB
+
+本节以 upload 函数为例，介绍在使用协议 PROTOCOL\_DDB 上传 Scalar、Vector，Pair 等类型数据时分别对应的 DolphinDB 数据类型。若 Python 中不存在与 DolphinDB 对应的数据类型，则该行显示为“---”。
+
+### Scalar
+
+下表展示上传 Scalar 型数据时，DolphinDB 与 Python 对应的数据类型与示例数据。
+
+| Python 类型 | Python 示例数据 | DolphinDB 类型 | DolphinDB 示例数据 |
+| --- | --- | --- | --- |
+| NoneType | None | VOID | NULL |
+| bool | True | BOOL | 1b, true |
+| np.int8 | np.int8(12) | CHAR | char(12), 12c |
+| np.int16 | np.int16(12) | SHORT | short(12), 12h |
+| np.int32 | np.int32(12) | INT | int(12), 12 |
+| np.int64 | np.int64(12) | LONG | long(12), 12l |
+| int | 12 | LONG | long(12), 12l |
+| np.datetime64[D] | np.datetime64("2012-01-02", "D") | DATE | 2012.01.02 |
+| np.datetime64[M] | np.datetime64("2012-01", "M") | MONTH | 2012.01M |
+| --- | --- | TIME | --- |
+| --- | --- | MINUTE | --- |
+| --- | --- | SECOND | --- |
+| np.datetime64[s] | np.datetime64("2012-01-02T01:02:03", "s") | DATETIME | datetime(2012.01.02T01:02:03) |
+| np.datetime64[ms] | np.datetime64("2012-01-02T01:02:03.123", "ms") | TIMESTAMP | timestamp(2012.01.02T01:02:03.123) |
+| --- | --- | NANOTIME | --- |
+| np.datetime64[ns] | np.datetime64("2012-01-02T01:02:03.123456789", "ns") | NANOTIMESTAMP | nanotimestamp(2012.01.02T01:02:03.123456789) |
+| np.datetime64 | np.datetime64("") | NANOTIMESTAMP | nanotimestamp(NULL) |
+| pd.Timestamp | pd.Timestamp("2012-01-02T01:02:03.123456789") | NANOTIMESTAMP | nanotimestamp(2012.01.02T01:02:03.123456789) |
+| pd.NaTType | pd.NaT | NANOTIMESTAMP | nanotimestamp(NULL) |
+| np.float32 | np.float32(1.1) | FLOAT | float(1.1), 1.1f |
+| np.float64 | np.float64(1.2) | DOUBLE | double(1.2) |
+| float | 1.2 | DOUBLE | double(1.2) |
+| float | np.nan | DOUBLE | double(NULL) |
+| str | "abc" | STRING | "abc" |
+| str | "" | STRING | "" |
+| --- | --- | SYMBOL | --- |
+| --- | --- | UUID | --- |
+| np.datetime64[h] | np.datetime64("2012-01-02T01", "h") | DATEHOUR | 2012.01.02T01 |
+| --- | --- | IPADDR | --- |
+| bytes | bytes("abc", encoding="UTF-8") | BLOB | "abc" |
+| --- | --- | DECIMAL32 | --- |
+| Decimal | decimal.Decimal("-10.21") | DECIMAL64 | decimal64(-10.21, 2) |
+| Decimal | decimal.Decimal("NaN") | DECIMAL64 | decimal64(NULL, 2) |
+| Decimal | decimal.Decimal(“-10.00000000000000000021“) | DECIMAL128 | decimal128(“-10.00000000000000000021“, 20) |
+
+**注意**：
+
+- Python API 自 1.30.22.6 版本起支持数据类型 Decimal128。上传 Decimal 标量（Scalar）对象时，如果保留的小数位数（scale）小于或等于 17，则作为 Decimal64 上传；如果保留的小数位数（scale）大于 17，则作为 Decimal128 上传。
+- 自 2.0.11.0 版本起，不再限制上传的 BLOB 类型数据的长度；对于上传的 SYMBOL/STRING 类型数据，其长度必须小于 256 KB。
+
+### Vector
+
+和 Scalar 类似，由于 DolphinDB 与 Python 的类型系统并不是一一对应的关系，因此 API 无法直接向 DolphinDB 上传 TIME、UUID 等类型的 Vector。
+
+类型转换的处理逻辑如下：
+
+1. 判断当前对象是否为 Vector 型数据，如 tuple、list、np.ndarray、pd.Series等。
+2. 如果当前对象为 np.ndarray 等类型确定的对象时，且 np.ndarray 的 dtype 不为 object，则直接进行类型转换。该种情况下的数据转换效率较高。
+3. 如果当前对象为 list 等类型不确定的对象，或者是 dtype 为 object 的 np.ndarray 对象，则需要遍历一遍上传的数据后再进行判断。在此过程中，
+
+   - 若数据中包含空值（None, np.nan, pd.NaT），则将根据第一个非空值类型确认该 Vector 型数据的类型。
+   - 若遍历过程中发现有 **两种及两种以上（注1）** 的数据类型数据，或者包含 Vector 型数据，则将会判断为 Any Vector。该种情况下需要逐个对数据进行类型转换，且需要额外遍历，转换效率较差。
+4. 在判断 Vector 型数据的元素类型时，基本遵循和 Scalar 一致的判断规则，因此，Python API 也不支持直接上传 MINUTE、UUID 等类型的 Vector 型数据。
+5. 如果一个 np.ndarray 对象中的元素都为长度相等的 Vector 型数据，则会优先判断为 Matrix 类型。
+6. 如果上传的对象不是 np.ndarray，但是却包含长度一致的 Vector 型数据，则会作为 Any Vector 数据上传。
+7. 如果上传的 Vector 中全为空值，且包含不同类型的空值，则将按照空值处理规则进行转换，如下表展示：
+
+   | 空值组合情况 | DolphinDB 列字段类型 |
+   | --- | --- |
+   | 全部为 None | STRING |
+   | np.nan 与 None 组合 | DOUBLE |
+   | pd.NaT 与 None 组合 | NANOTIMESTAMP |
+   | np.nan 与 pd.NaT 组合 | NANOTIMESTAMP |
+   | None, np.nan 与 pd.NaT 组合 | NANOTIMESTAMP |
+   | None, pd.NaT 或 np.nan 与非空值组合 | 非空值类型 |
+
+- **注1**： 此处“两种及两种以上”特指 DolphinDB 类型系统中的类型，例如数据为 np.array([np.float64(12), 1.3]) ，则将被视为仅包含一种数据类型。
+- **注2**： 目前版本的 DolphinDB Python API 并不支持 pd.array 的 Vector 型数据。
+- **注3**： 在 list 或是 dtype 为 object 的 np.ndarray 对象中的空值类型，将全部被视为同一种空值，例如 None/np.nan/pd.NaT 等，但不包含 decimal.Decimal('NaN')。
+- **注4**： 目前不支持直接上传 Array Vector 型数据，形如 np.array([[1], [2, 3]]) 的数据会作为 Any Vector 数据上传。
+- **注5**： 上传 Decimal 类型的数据时
+  - 若版本低于 3.0.1.0，则必须须确保 DECIMAL 类型列的所有数据具有相同的小数位数；可使用下述方式对齐小数位数：
+
+```dolphindb
+>>> b = decimal.Decimal("1.23")
+>>> b
+Decimal('1.23')
+>>> b = b.quantize(decimal.Decimal("0.000"))
+>>> b
+Decimal('1.230')
+```
+
+- 若版本大于等于 3.0.1.0，则无需确保 DECIMAL 类型列的所有数据具有相同的小数位数，系统会自动根据第一个非空 Decimal 数据来调整位数。
+- **注6**：目前版本不支持 上传 bytes 类型 Vector 作为 BLOB 数据。
+
+以下为 3 个常见的上传 Vector 型数据的例子：
+
+**示例 1** 上传不包含空值的 BOOL Vector、INT Vector、DOUBLE Vector、STRING Vector、DATE Vector
+
+相关代码示例：
+
+```dolphindb
+>>> s.upload({'bool_v': np.array([True, False, False], dtype="bool")})
+>>> s.upload({'int_v': np.array([1, 2, 4], dtype="int32")})
+>>> s.upload({'double_v': [1.2, 2.456]})
+>>> s.upload({'string_v': np.array(["abc", "123"], dtype="object")})
+>>> s.upload({'date_v': np.array(["2012-01-02"], dtype="datetime64[D]")})
+```
+
+可使用 typestr 方法查看已上传变量的数据类型：
+
+```dolphindb
+>>> s.run("typestr(bool_v)")
+FAST BOOL VECTOR
+>>> s.run("typestr(int_v)")
+FAST INT VECTOR
+>>> s.run("typestr(double_v)")
+FAST DOUBLE VECTOR
+>>> s.run("typestr(string_v)")
+STRING VECTOR
+>>> s.run("typestr(date_v)")
+FAST DATE VECTOR
+```
+
+**示例 2** 上传包含空值的 BOOL Vector、INT Vector、DOUBLE Vector、STRING Vector、DATE Vector
+
+相关代码示例：
+
+```dolphindb
+>>> s.upload({'bool_v': [True, None, False]})
+>>> s.upload({'int_v': np.array([None, np.int32(2), np.int32(12)], dtype="object")})
+>>> s.upload({'double_v': np.array([1.1, np.nan, 3.456])})
+>>> s.upload({'string_v': ["", "abc", "123"]})
+>>> s.upload({'date_v': [pd.NaT, None, np.nan, np.datetime64("2012-01-03", "D")]})
+```
+
+可使用 typestr 方法查看上传变量的数据类型：
+
+```dolphindb
+>>> s.run("typestr(bool_v)")
+FAST BOOL VECTOR
+>>> s.run("typestr(int_v)")
+FAST INT VECTOR
+>>> s.run("typestr(double_v)")
+FAST DOUBLE VECTOR
+>>> s.run("typestr(string_v)")
+STRING VECTOR
+>>> s.run("typestr(date_v)")
+FAST DATE VECTOR
+```
+
+**示例 3** 上传 Any Vector
+
+上传 Any Vector 有两种方式。一种是在构造 np.ndarray 时指定 `dtype=object`；另一种则是上传一个 list/tuple 对象。须注意，这两种方式都需要包含 **两种及两种以上** 类型的数据或者包含 Vector 型的数据。
+
+相关代码示例：
+
+```dolphindb
+>>> s.upload({'list_v': [1.2, "abc"])})
+>>> s.upload({'array_v': np.array([1, 1.2], dtype="object"})
+>>> s.upload({'list_av': [[1, 2], [3]]})
+>>> s.upload({'array_av': np.array([[1], [2, 3]], dtype="object")})
+```
+
+使用 typestr 方法查看上传变量的数据类型：
+
+```dolphindb
+>>> s.run("typestr(list_v)")
+ANY VECTOR
+>>> s.run("typestr(array_v)")
+ANY VECTOR
+>>> s.run("typestr(list_av)")
+ANY VECTOR
+>>> s.run("typestr(array_av)")
+ANY VECTOR
+```
+
+### Pair
+
+在使用 PROTOCOL\_DDB 协议时，DolphinDB Python API 暂不支持直接上传 Pair 形式的数据。
+
+### Matrix
+
+如果上传的 np.ndarray 对象中包含长度一致的 Vector 型数据，则将会作为 Matrix 形式的数据上传。但是，如果上传的对象不是 np.ndarray，却包含长度一致的 Vector 型数据，则将会作为 Any Vector 数据上传。
+
+上传 Matrix 型数据的相关代码示例：
+
+```dolphindb
+>>> s.upload({'int_m': np.array([[1, 2], [2, 3], [3, 4]])})
+>>> s.run("typestr(int_m)")
+FAST LONG MATRIX
+>>> s.upload({'any_vec': [[1, 2], [2, 3], [3, 4]]})
+>>> s.run("typestr(any_vec)")
+ANY VECTOR
+```
+
+**注意**：上传二维 ndarray 时，如果数据只有一行，则会被识别为 Vector 型数据而非 Matrix。
+
+### Set
+
+上传 Set 类型的 Python 对象，数据将会转换为 DolphinDB 中的 Set 形式。在转换时 API 将会遍历 Set 中的所有元素，将各元素作为 Scalar 数据进行逐个转换，最后数据整体作为一个 Set 上传至 DolphinDB，转换后的数据类型以对应的 DolphinDB 数据类型为准。
+
+上传 Set 型数据的相关代码示例：
+
+```dolphindb
+>>> s.upload({'long_set': {1, 2}})
+>>> s.run("typestr(long_set)")
+LONG SET
+>>> s.upload({'double_set': {1.2, np.double(5.5), pd.NaT}})
+>>> s.run("typestr(double_set)")
+DOUBLE SET
+```
+
+- **注1**： DolphinDB 的 Set 数据形式目前不支持元素有多种数据类型，也不支持 Vector 作为组成元素。
+- **注2**：在转换时，若 Set 中包含空值，则空值将不被视为任何一种数据类型。此外，DolphinDB 也不支持构造全为空值的 Set。
+
+### Dict
+
+和 Set 类似，在转换 Dict 型数据时 API 会遍历所有元素，按照对应的数据形式逐个进行类型转换，最后数据整体作为一个 Dictionary 上传至 DolphinDB。
+
+上传 Dict 型数据的相关代码示例：
+
+```dolphindb
+>>> s.upload({'long_dict': {'a': None, 'b': 1}})
+>>> s.run("typestr(long_dict)")
+STRING->LONG DICTIONARY
+>>> s.upload({'any_dict1': {'a': 1, 'b': [1.1, 2.4], 'c': np.array([1, "a"], dtype="object")}})
+>>> s.run("typestr(any_dict1)")
+STRING->ANY DICTIONARY
+>>> s.upload({'any_dict2': {1: [[1], [2, 3]], 2: [[1.1, np.nan], [3.3]]}})
+>>> s.run("typestr(any_dict2)")
+STRING->ANY DICTIONARY
+```
+
+- **注1**： DolphinDB 不支持多种数据类型作为键，支持多种数据类型作为值。
+- **注2**： 在 Dict 中转换时，Vector 型数据中如果包含 Vector 型元素，将作为 Any Vector 进行转换，而非 Array Vector。
+- **注3**： Dict 中的空值在转换时不视为任何一种数据类型。DolphinDB 也不支持构造全为空值的 Dict。
+
+### Table
+
+Table 型数据在 Python 中对应的数据类型为 pd.DataFrame，在转换时，按列进行处理，每列作为 Vector 型数据进行转换。特别的，当 pd.DataFrame 的元素中出现 Vector 型数据时，将作为 Array Vector 进行处理，且不支持 Any Vector 作为列类型，这点与 Vector 型数据的转换逻辑有较大不同。
+
+当 Table 型数据中包含空值时，处理逻辑与 Vector 型数据保持一致。同样的，也不支持直接上传 BLOB、INT128 等类型，如需上传，需指定 \_\_DolphinDB\_Type\_\_ 进行强制类型转换才能上传，具体操作参考：[强制类型转换](ForceTypeCasting.html)。
+
+**注意**：pd.DataFrame 中仅有一种时间类型 datetime64[ns]，对应 np.datetime64[ns]，因此，如果直接上传时间类型数据，在 DolphinDB 服务器端仅能得到 NANOTIMESTAMP 类型的数据。
+
+**示例 1**
+
+```dolphindb
+>>> df1 = pd.DataFrame({
+...     'int_v': [1, 2, 3],
+...     'long_v': np.array([None, 3, np.int64(3)], dtype="object"),
+...     'float_v': np.array([np.nan, 1.2, 3.3], dtype="float32")
+... })
+>>> s.upload({'df1': df1})
+>>> s.run("schema(df1)")['colDefs']
+      name typeString  typeInt  extra comment
+0    int_v       LONG        5    NaN        
+1   long_v       LONG        5    NaN        
+2  float_v      FLOAT       15    NaN
+```
+
+当上传的数据 `dtype=object` 时，会逐个判断数据类型，空值（None、pd.NaT、np.nan）不视为任何一种数据类型，并根据第一个非空值的数据类型作为该列的数据类型。
+
+本例中，int\_v 列没有空值，但是在 Python pandas 中，Python 的 int 会被转换为 int64，对应 DolphinDB 的 LONG；long\_v 列 `dtype=object`，且第一个非空值为 Python int 3，对应 DolphinDB LONG，因此该列作为 LONG 进行类型转换； float\_v 列 dtype=float，因此无论是否包含空值，都会作为 FLOAT 处理。
+
+**注意：** numpy 和 pandas 中，dtype=bool/int8/int16/int32/int64 时，不能包含空值，因此，如果需要上传包含空值的列，则需要在构造 pd.DataFrame 时，指定该列类型为 object。
+
+**示例 2**
+
+```dolphindb
+>>> df2 = pd.DataFrame({
+...     'day_v': np.array(["2012-01-02", "2022-02-05"], dtype="datetime64[D]"),
+...     'month_v': np.array([np.datetime64("2012-01", "M"), None], dtype="datetime64[M]"),
+... })
+>>> s.upload({'df2': df2})
+>>> s.run("schema(df2)")['colDefs']
+      name     typeString  typeInt  extra comment
+0    day_v  NANOTIMESTAMP       14    NaN        
+1  month_v  NANOTIMESTAMP       14    NaN
+```
+
+对于时间类型，pandas 中仅有一种时间类型 datetime64[ns]，因此无法直接上传 DATE、MONTH等类型，需要指定 \_\_DolphinDB\_Type\_\_ 进行强制类型转换才能上传，具体操作参考：[强制类型转换](ForceTypeCasting.html)。
+
+```dolphindb
+>>> import dolphindb.settings as keys
+>>> df2.__DolphinDB_Type__ = {
+...     "day_v": keys.DT_DATE,
+...     "month_v": keys.DT_MONTH,
+... }
+...
+>>> s.upload({'df2': df2})
+>>> s.run("schema(df2)")['colDefs']
+      name typeString  typeInt  extra comment
+0    day_v       DATE        6    NaN        
+1  month_v      MONTH        7    NaN
+```
+
+**示例 3**
+
+```dolphindb
+>>> df3 = pd.DataFrame({
+...     'long_av': [[1, None], [3]],
+...     'double_av': np.array([[1.1], [np.nan, 3.3]], dtype="object")
+... })
+>>> s.upload({'df3': df3})
+>>> s.run("schema(df3)")['colDefs']
+        name typeString  typeInt  extra comment
+0    long_av     LONG[]       69    NaN        
+1  double_av   DOUBLE[]       80    NaN
+```
+
+如上例所示，当上传的 pd.DataFrame 中某一列包含 Vector 型数据时，该列将作为 Array Vector 进行类型转换，而非 Any Vector。
+
+**示例 4：**
+
+Python API 自 3.0.0.0 版本起，支持上传 pandas 扩展类型：Boolean/Int8/Int16/Int32/Int64/Float32/Float64/String。以下为使用示例：
+
+```dolphindb
+>>> import pandas as pd
+>>> df4 = pd.DataFrame({
+...     'bool': pd.Series([True, False, None], dtype=pd.BooleanDtype()),
+...     'int64': pd.Series([1, -100, None], dtype=pd.Int64Dtype()),
+...     'float64': pd.Series([1.1, -0.23, None], dtype=pd.Float64Dtype()),
+...     'string': pd.Series(["abc", "def", None], dtype=pd.StringDtype()),
+... })
+...
+>>> df4.dtypes
+bool              boolean
+int64               Int64
+float64           Float64
+string     string[python]
+dtype: object
+>>> s.upload({'df4': df4})
+>>> s.run("schema(df4)")['colDefs']
+      name typeString  typeInt  extra comment
+0     bool       BOOL        1    NaN        
+1    int64       LONG        5    NaN        
+2  float64     DOUBLE       16    NaN        
+3   string     STRING       18    NaN
+
+// output
+
+      name typeString  typeInt  extra comment
+0     bool       BOOL        1    NaN        
+1    int64       LONG        5    NaN        
+2  float64     DOUBLE       16    NaN        
+3   string     STRING       18    NaN
+```
+
+以下为 pandas ExtensionDtype 和 DolphinDB 的数据类型对照表。其中关于强制类型转换的更多说明可参阅[强制类型转换](ForceTypeCasting.html)。
+
+| **pandas ExtensionDtype** | **DolphinDB 类型** | **说明** |
+| --- | --- | --- |
+| BooleanDtype | BOOL |  |
+| Int8Dtype | CHAR |  |
+| Int16Dtype | SHORT |  |
+| Int32Dtype | INT |  |
+| Int64Dtype | LONG |  |
+| Float32Dtype | FLOAT |  |
+| Float64Dtype | DOUBLE |  |
+| StringDtype | SYMBOL | 需强制类型转换 |
+| StringDtype | STRING |  |
+| StringDtype | UUID | 需强制类型转换 |
+| StringDtype | IPADDR | 需强制类型转换 |
+| StringDtype | INT128 | 需强制类型转换 |
+| StringDtype | BLOB | 需强制类型转换 |
+
+**示例 5：**
+
+Python API 自 1.30.22.4 版本起，支持上传 Pandas2.0 PyArrow 作为数据后端的 DataFrame。以下为使用示例：
+
+```dolphindb
+>>> import pandas as pd # pandas version >= 2.0.0
+>>> df5 = pd.DataFrame({
+...     'int64': pd.Series([1, 2, None, 4], dtype="int64[pyarrow]"),
+...     'float64': pd.Series([1.1, 2.2, None, 4.4], dtype="float64[pyarrow]"),
+...     'string': pd.Series(["aa", "bb", None, "cc"], dtype="string[pyarrow]"),
+... })
+... 
+>>> df5.dtypes
+int64       int64[pyarrow]
+float64    double[pyarrow]
+string     string[pyarrow]
+dtype: object
+>>> s.upload({'df5': df5})
+>>> s.run("schema(df5)")['colDefs']
+      name typeString  typeInt  extra comment
+0    int64       LONG        5    NaN        
+1  float64     DOUBLE       16    NaN        
+2   string     STRING       18    NaN
+```
+
+以下为 DataFrame/Series、PyArrow 和 DolphinDB 的数据类型对照表。其中关于强制类型转换的更多说明可参阅[强制类型转换](ForceTypeCasting.html)。
+
+| **DataFrame/Series 类型** | **PyArrow 类型** | **DolphinDB 类型** | **说明** |
+| --- | --- | --- | --- |
+| bool[pyarrow] | pa.bool\_() | BOOL |  |
+| int8[pyarrow] | pa.int8() | CHAR |  |
+| int16[pyarrow] | pa.int16() | SHORT |  |
+| int32[pyarrow] | pa.int32() | INT |  |
+| int64[pyarrow] | pa.int64() | LONG |  |
+| date32[day][pyarrow] | pa.date32() | DATE |  |
+| date32[day][pyarrow] | pa.date32() | MONTH | 需要强制类型转换 |
+| time32[ms][pyarrow] | pa.time32(“ms“) | TIME |  |
+| time32[s][pyarrow] | pa.time32(“s“) | MINUTE | 需要强制类型转换 |
+| time32[s][pyarrow] | pa.time32(“s“) | SECOND |  |
+| timestamp[s][pyarrow] | pa.timestamp(“s“) | DATETIME |  |
+| timestamp[ms][pyarrow] | pa.timestamp(“ms“) | TIMESTAMP |  |
+| time64[ns][pyarrow] | pa.time64(“ns“) | NANOTIME |  |
+| timestamp[ns][pyarrow] | pa.timestamp(“ns“) | NANOTIMESTAMP |  |
+| float[pyarrow] | pa.float32() | FLOAT |  |
+| double[pyarrow] | pa.float64() | DOUBLE |  |
+| dictionary<values=string, indices=int32, ordered=0>[pyarrow] | pa.dictionary(pa.int32(), pa.utf8()) | SYMBOL |  |
+| string[pyarrow] | pa.utf8() | STRING |  |
+| fixed\_size\_binary[16][pyarrow] | pa.binary(16) | UUID | 需要强制类型转换 |
+| timestamp[s][pyarrow] | pa.timestamp(“s“) | DATEHOUR | 需要强制类型转换 |
+| string[pyarrow] | pa.utf8() | IPADDR | 需要强制类型转换 |
+| fixed\_size\_binary[16][pyarrow] | pa.binary(16) | INT128 |  |
+| large\_binary[pyarrow] | pa.large\_binary() | BLOB |  |
+| decimal128(38, S)[pyarrow] | pa.decimal128(38, S) | DECIMAL32(S) | 需要强制类型转换 |
+| decimal128(38, S)[pyarrow] | pa.decimal128(38, S) | DECIMAL64(S) | 需要强制类型转换 |
+| decimal128(38, S)[pyarrow] | pa.decimal128(38, S) | DECIMAL128(S) |  |
+| list<item: T>[pyarrow]例：list<item: int32>[pyarrow] | pa.list\_(T)例：pa.list\_(pa.int32()) | ARRAYVECTOR例：INT ARRAYVECTOR | list\_ 嵌套对应 arrayvector |
+
+注：Python API 自 1.30.22.6 版本起支持数据类型 Decimal128。1.30.22.5 及之前的版本上传 pyarrow.decimal128 默认作为 DECIMAL64 上传，1.30.22.6 版本起将默认作为 DECIMAL128 上传，可以通过指定类型的方式上传为 DECIMAL32/64。
+
+如上例所示，当上传的 pd.DataFrame 中某一列包含 Vector 型数据时，该列将作为 Array Vector 进行类型转换，而非 Any Vector。
+
+## 反序列化 DolphinDB -> Python(设置 pickleTableToList=False)
+
+以下示例以 run 函数为例，介绍不同 DolphinDB 数据类型和数值通过该方式下载时对应的 Python 对象。
+
+**注意**： 由于 numpy 和 pandas 具有 dtype，故下文中，Python 类型中的 np.datetime64[D]，表示该对象的类型为 numpy.datetime64，且 dtype=datetime64[D]。
+
+### Scalar
+
+| DolphinDB 类型 | DolphinDB 数据 | Python 类型 | Python 数据 |
+| --- | --- | --- | --- |
+| VOID | NULL | NoneType | None |
+| INT | int(NULL) | NoneType | None |
+| STRING | string(NULL) | NoneType | None |
+| BOOL | true | bool | True |
+| CHAR | 'a' | int | 97 |
+| SHORT | 224h | int | 224 |
+| INT | 16 | int | 16 |
+| LONG | 3000l | int | 3000 |
+| DATE | 2013.06.13 | np.datetime64[D] | 2013-06-13 |
+| MONTH | 2012.06M | np.datetime64[M] | 2012-06 |
+| TIME | 13:30:10.008 | np.datetime64[ms] | 1970-01-01T13:30:10.008 |
+| MINUTE | 13:30m | np.datetime64[m] | 1970-01-01T13:30 |
+| SECOND | 13:30:10 | np.datetime64[s] | 1970-01-01T13:30:10 |
+| DATETIME | 2012.06.13T13:30:10 | np.datetime64[s] | 2012-06-13T13:30:10 |
+| TIMESTAMP | 2012.06.13T13:30:10.008 | np.datetime64[ms] | 2012-06-13T13:30:10.008 |
+| NANOTIME | 13:30:10.008007006 | np.datetime64[ns] | 1970-01-01T13:30:10.008007006 |
+| NANOTIMESTAMP | 2012.06.13T13:30:10.008007006 | np.datetime64[ns] | 2012-06-13T13:30:10.008007006 |
+| FLOAT | 2.1f | float | 2.0999999046325684 |
+| DOUBLE | 2.1 | float | 2.1 |
+| SYMBOL | --- | --- | --- |
+| STRING | "Hello" | str | "Hello" |
+| UUID | uuid("5d212a78-cc48-e3b1-4235-b4d91473ee87") | str | "5d212a78-cc48-e3b1-4235-b4d91473ee87" |
+| DATEHOUR | datehour(2012.06.13T13:30:10) | np.datetime64[h] | 2012-06-13T13 |
+| IPADDR | ipaddr("192.168.1.13") | str | "192.168.1.13" |
+| INT128 | int128("e1671797c52e15f763380b45e841ec32") | str | "e1671797c52e15f763380b45e841ec32" |
+| BLOB | blob("xxxyyyzzz") | bytes | b'xxxyyyzzz' |
+| DECIMAL32 | decimal32(1.111, 4) | decimal.Decimal | 1.1110 |
+| DECIMAL64 | decimal64(1.123456789, 5) | decimal.Decimal | 1.12345 |
+
+- **注1：** DolphinDB 中的空值不仅有 VOID 类型，还有 INT、STRING 等类型的空值，这些空值 Scalar 都对应 Python API 的空值 None。
+- **注2：** DolphinDB 中不存在 Scalar 形式的 SYMBOL 数据。
+- **注3：** 自 Python API 3.0.2.1 版本起，DolphinDB 中 BLOB 类型在 Python 中的对应类型由 str 修改为 bytes。
+
+### Vector
+
+DolphinDB 中的 Vector 数据一般对应 Python 中的 numpy.ndarray。特别的，Any Vector 对应 Python 中的 list （1.30.17.1及之前版本的 API 对应 numpy.ndarray）。
+
+下表给出各类型 Vector 所对应 numpy.ndarray 的 dtype：
+
+| DolphinDB类型 | np.dtype |
+| --- | --- |
+| BOOL（不含空值） | bool |
+| CHAR（不含空值） | int8 |
+| SHORT（不含空值） | int16 |
+| INT（不含空值） | int32 |
+| LONG（不含空值） | int64 |
+| DATE | datetime64[D] |
+| MONTH | datetime64[M] |
+| TIME、TIMESTAMP | datetime64[ms] |
+| MINUTE | datetime64[m] |
+| SECOND、DATETIME | datetime64[s] |
+| NANOTIME、NANOTIMESTAMP | datetime64[ns] |
+| FLOAT | float32 |
+| DOUBLE、CHAR（含空值）、SHORT（含空值）、INT（含空值）、LONG（含空值） | float64 |
+| DATEHOUR | datetime64[h] |
+| BOOL（含空值）、SYMBOL、STRING、UUID、IPADDR、INT128、BLOB、DECIMAL32、DECIMAL64、Array Vector | object |
+
+- **注1** ：numpy.ndarray 中没有整型的空值，因此如果 DolphinDB 整型的 Vector 中包含空值，则会强制转换为 float64，空值变为 np.nan。
+- **注2** ：BOOL Vector 中如果包含空值，则会转换为 `dtype=object` 的 np.ndarray，而非 `dtype=bool`。
+- **注3** ： DolphinDB Array Vector 下载到 Python 所对应的 dtype 为 object，其中每一项元素都是原始 ArrayVector 的一个元素转换而成的 np.ndarray。
+- **注4** ： 若使用 1.30.17.2 及之后版本的 Python API，则 DolphinDB Any Vector 下载到 Python 对应的数据类型为 list；若使用 1.30.17.2 及之前版本的 Python API，则 DolphinDB Any Vector 下载到 Python 对应的数据类型为 np.ndarray。
+- **注5** ： 自 1.30.22.3 版本起，API 支持下载类型为 Decimal32 Array Vector 和 Decimal64 Array Vector 的数据。
+
+下载 Vector 型数据的相关代码示例：
+
+```dolphindb
+>>> re = s.run("[true, false]")
+>>> re
+[ True False]
+>>> type(re)
+<class 'numpy.ndarray'>
+>>> re.dtype
+bool
+
+>>> re = s.run("[true, None]")
+>>> re
+[True None]
+>>> re.dtype
+object
+```
+
+上例中，首先下载一个不含空值的 BOOL Vector，可以看到对应的 Python 对象为 np.ndarray，且 `dtype=bool`；如果下载的 BOOL Vector 中包含空值，则对应的 dtype 变为 object。和 BOOL 不同，如果下载的整型向量中包含空值，则 `dtype=float64`。
+
+```dolphindb
+>>> re = s.run("[1, 2, 3, NULL]")
+>>> re
+[ 1.  2.  3. nan]
+>>> re.dtype
+float64
+```
+
+如果下载的 Vector 为 Array Vector，则 API 会遍历每个元素，将所有元素逐个按照 Vector 的转换规则进行转换。示例中下载的 INT Array Vector 某一元素中包含空值，因此，其他不含空值的元素对应 dtype=int32，包含空值的元素则对应 dtype=float64。
+
+```dolphindb
+>>> s.run("arrayVector(2 3 4, [1, 2, 3, NULL])")
+[array([1, 2], dtype=int32) array([3], dtype=int32) array([nan])]
+
+>>> re = s.run('''(1, 2, [12, "aaa"])''')
+>>> re
+[1, 2, [12, 'aaa']]
+>>> type(re)
+<class 'list'>
+>>> type(re[2])
+<class 'list'>
+```
+
+如果下载的 Vector 为 Any Vector，则 API 会遍历每个元素，按照每个元素的转换规则进行转换。示例中的 Any Vector 嵌套了另一个 Any Vector，两者都被转换为 list 类型。如果 Python API 版本等于或低于 1.30.17.1，则 Any Vector 数据将会被转换为 np.ndarray，且 dtype=object。
+
+### Pair
+
+DolphinDB 中的 Pair 类型对应 Python 中的 list，其中每一个元素都将按照 Scalar 的规则进行转换。
+
+上传 Pair 型数据的相关代码示例：
+
+```dolphindb
+>>> s.run("100:0")
+[100, 0]
+```
+
+### Matrix
+
+DolphinDB 中的 Matrix 类型对应 Python 中的 np.ndarray。不同数据类型与 np.dtype 对应关系如下表所示：
+
+| DolphinDB类型 | np.dtype |
+| --- | --- |
+| BOOL（不含空值） | bool |
+| CHAR（不含空值） | int8 |
+| SHORT（不含空值） | int16 |
+| INT（不含空值） | int32 |
+| LONG（不含空值） | int64 |
+| DATE | datetime64[D] |
+| MONTH | datetime64[M] |
+| TIME、TIMESTAMP | datetime64[ms] |
+| MINUTE | datetime64[m] |
+| SECOND、DATETIME | datetime64[s] |
+| NANOTIME、NANOTIMESTAMP | datetime64[ns] |
+| FLOAT | float32 |
+| DOUBLE、CHAR（含空值）、SHORT（含空值）、INT（含空值）、LONG（含空值） | float64 |
+| DATEHOUR | datetime64[h] |
+| BOOL（含空值） | object |
+
+下载 Matrix 型数据的相关代码示例：
+
+```dolphindb
+>>> s.run("""
+...     mtx = 1..12$4:3;
+...     mtx.rename!(1 2 3 4, `c1`c2`c3);
+...     mtx
+... """)
+[array([[ 1,  5,  9],
+       [ 2,  6, 10],
+       [ 3,  7, 11],
+       [ 4,  8, 12]], dtype=int32), array([1, 2, 3, 4], dtype=int32), array(['c1', 'c2', 'c3'], dtype=object)]
+```
+
+与上传数据时不同，虽然 Matrix 直接对应二维 np.ndarray，但是 API 在下载 Matrix 型数据时会包含其行名和列名的信息。如果 Matrix 数据中不包含行名（或列名），则使用 None 代替。
+
+- **注1：** 时间类型的 Matrix 在 PROTOCOL\_DDB 协议中的对应规则与 Vector 类似，但在 PROTOCOL\_PICKLE 协议中则全部对应 datetime64[ns]，请参考 [Pickle](PROTOCOL_PICKLE.html)。
+
+### Set
+
+DolphinDB 中的 Set 数据形式对应 Python set 类型，在转换时，API 会将 Set 中的每个元素作为 Scalar 进行转换。有关具体每种数据类型对应的 Python 类型，请参考本节 Scalar 部分的转换规则。
+
+**注意：** 目前仅支持 CHAR、SHORT、INT、LONG、FLOAT、DOUBLE、STRING、SYMBOL Set 转换为 Python 对象。
+
+下载 Set 型数据的相关代码示例：
+
+```dolphindb
+>>> re = s.run("set(1..5)")
+>>> re
+{1, 2, 3, 4, 5}
+>>> type(re)
+<class 'set'>
+```
+
+### Dict
+
+DolphinDB 中的 Dict 数据形式对应 Python 中的 dict 类型。在转换时，API 会遍历 Dict 中的所有键值对，并将键作为 Scalar 进行转换；同时根据值本身的数据形式、数据类型进行转换，转换规则请参考本文中对应数据形式的规则。
+
+下载 Dict 型数据的相关代码示例：
+
+```dolphindb
+>>> re = s.run('''{"a": 123, "b": [1.1, 2.2]}''')
+>>> re
+{'b': array([1.1, 2.2]), 'a': 123}
+>>> type(re)
+<class 'dict'>
+```
+
+### Table
+
+DolphinDB 中的 Table 数据形式对应 Python 中的 pandas.DataFrame 类型。在转换时，API 会将 Table 型数据的每一列作为 Vector 类型进行处理。
+
+特别的，不同于 Vector 的处理，当 Table 型数据为时间类型时，Python pandas 仅支持一种时间类型 datetime64[ns]，因此下载的时间类型都会转换为 datetime64[ns]。
+
+**注意：** 目前 API 仅支持 Array Vector 列的下载，不支持 Any Vector 列的下载。
+
+## 反序列化 DolphinDB -> Python(设置 pickleTableToList=True)
+
+开启附加参数 pickleTableToList 后，如果执行脚本的返回值数据形式为 Table，则对应的 Python 对象为 list 而非 pd.DataFrame。其中，list 中的每一元素（np.ndarray）都表示 Table 中的一列。
+
+PROTOCOL\_DDB 协议的附加参数仅在 API 端做处理，不会作为 flag 的一部分发送至 DolphinDB。API 收到数据后，不会再将数据拼接为 pd.DataFrame，而是将每一列放入 list 中。
+
+### Table
+
+和 Vector 型数据的转换流程不同，每一列在转换时仍旧视为是 Table 中的一列，而非单独的 Vector，因此时间类型会被转换为 datetime64[ns]。
+
+- **注1**： 如果下载 Table 型数据的数据列为 Array Vector 列，须确保每个元素的长度一致，其对应数据类型为二维 np.ndarray。
+
+下载 Table 型数据的相关代码示例：
+
+```dolphindb
+>>> re = s.run("table([1, NULL] as a, [2012.01.02, NULL] as b)", pickleTableToList=True)
+>>> re
+[array([ 1., nan]), array(['2012-01-02T00:00:00.000000000',                           'NaT'],
+      dtype='datetime64[ns]')]
+>>> type(re)
+<class 'list'>
+>>> re[0].dtype
+float64
+>>> re[1].dtype
+datetime64[ns]
+
+>>> s.run("table(arrayVector(1 2 3, [1, 2, 3]) as a)", pickleTableToList=True)
+[array([[1],
+       [2],
+       [3]], dtype=int32)]
+```
+
+上例中，指定附加参数 pickleTableToList 后下载的 Table 数据，转换为每个元素都是 np.ndarray 的 list。如果下载的 Table 中整型数据列中包含空值，则对应 dtype=float64；如果下载时间类型列，则全部对应 datetime64[ns]；如果下载 Array Vector 数据列，则需要其中的每个元素都长度相等。