PROTOCOL_DDB

下表展示上传 Scalar 型数据时，DolphinDB 与 Python 对应的数据类型与示例数据。

注意：

• Python API 自 1.30.22.6 版本起支持数据类型 Decimal128。上传 Decimal 标量（Scalar）对象时，如果保留的小数位数（scale）小于或等于 17，则作为 Decimal64 上传；如果保留的小数位数（scale）大于 17，则作为 Decimal128 上传。
• 自 2.0.11.0 版本起，不再限制上传的 BLOB 类型数据的长度；对于上传的 SYMBOL/STRING 类型数据，其长度必须小于 256 KB。

和 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 类型列的所有数据具有相同的小数位数；可使用下述方式对齐小数位数：

>>> 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

相关代码示例：

>>> 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 方法查看已上传变量的数据类型：

>>> 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

相关代码示例：

>>> 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 方法查看上传变量的数据类型：

>>> 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 型的数据。

相关代码示例：

>>> 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 方法查看上传变量的数据类型：

>>> 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

在使用 PROTOCOL_DDB 协议时，DolphinDB Python API 暂不支持直接上传 Pair 形式的数据。

如果上传的 np.ndarray 对象中包含长度一致的 Vector 型数据，则将会作为 Matrix 形式的数据上传。但是，如果上传的对象不是 np.ndarray，却包含长度一致的 Vector 型数据，则将会作为 Any Vector 数据上传。

上传 Matrix 型数据的相关代码示例：

>>> 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 类型的 Python 对象，数据将会转换为 DolphinDB 中的 Set 形式。在转换时 API 将会遍历 Set 中的所有元素，将各元素作为 Scalar 数据进行逐个转换，最后数据整体作为一个 Set 上传至 DolphinDB，转换后的数据类型以对应的 DolphinDB 数据类型为准。

上传 Set 型数据的相关代码示例：

>>> 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。

和 Set 类似，在转换 Dict 型数据时 API 会遍历所有元素，按照对应的数据形式逐个进行类型转换，最后数据整体作为一个 Dictionary 上传至 DolphinDB。

上传 Dict 型数据的相关代码示例：

>>> 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 型数据在 Python 中对应的数据类型为 pd.DataFrame，在转换时，按列进行处理，每列作为 Vector 型数据进行转换。特别的，当 pd.DataFrame 的元素中出现 Vector 型数据时，将作为 Array Vector 进行处理，且不支持 Any Vector 作为列类型，这点与 Vector 型数据的转换逻辑有较大不同。

当 Table 型数据中包含空值时，处理逻辑与 Vector 型数据保持一致。同样的，也不支持直接上传 BLOB、INT128 等类型，如需上传，需指定 __DolphinDB_Type__ 进行强制类型转换才能上传，具体操作参考：强制类型转换。

注意：pd.DataFrame 中仅有一种时间类型 datetime64[ns]，对应 np.datetime64[ns]，因此，如果直接上传时间类型数据，在 DolphinDB 服务器端仅能得到 NANOTIMESTAMP 类型的数据。

示例 1

>>> 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

>>> 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__ 进行强制类型转换才能上传，具体操作参考：强制类型转换。

>>> 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

>>> 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。以下为使用示例：

>>> 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 的数据类型对照表。其中关于强制类型转换的更多说明可参阅强制类型转换。

示例 5：

Python API 自 1.30.22.4 版本起，支持上传 Pandas2.0 PyArrow 作为数据后端的 DataFrame。以下为使用示例：

>>> 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 的数据类型对照表。其中关于强制类型转换的更多说明可参阅强制类型转换。

注：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。

• 注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。

DolphinDB 中的 Vector 数据一般对应 Python 中的 numpy.ndarray。特别的，Any Vector 对应 Python 中的 list （1.30.17.1及之前版本的 API 对应 numpy.ndarray）。

下表给出各类型 Vector 所对应 numpy.ndarray 的 dtype：

• 注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 型数据的相关代码示例：

>>> 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。

>>> 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。

>>> 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。

DolphinDB 中的 Pair 类型对应 Python 中的 list，其中每一个元素都将按照 Scalar 的规则进行转换。

上传 Pair 型数据的相关代码示例：

>>> s.run("100:0")
[100, 0]

DolphinDB 中的 Matrix 类型对应 Python 中的 np.ndarray。不同数据类型与 np.dtype 对应关系如下表所示：

下载 Matrix 型数据的相关代码示例：

>>> 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。

DolphinDB 中的 Set 数据形式对应 Python set 类型，在转换时，API 会将 Set 中的每个元素作为 Scalar 进行转换。有关具体每种数据类型对应的 Python 类型，请参考本节 Scalar 部分的转换规则。

注意： 目前仅支持 CHAR、SHORT、INT、LONG、FLOAT、DOUBLE、STRING、SYMBOL Set 转换为 Python 对象。

下载 Set 型数据的相关代码示例：

>>> re = s.run("set(1..5)")
>>> re
{1, 2, 3, 4, 5}
>>> type(re)
<class 'set'>

DolphinDB 中的 Dict 数据形式对应 Python 中的 dict 类型。在转换时，API 会遍历 Dict 中的所有键值对，并将键作为 Scalar 进行转换；同时根据值本身的数据形式、数据类型进行转换，转换规则请参考本文中对应数据形式的规则。

下载 Dict 型数据的相关代码示例：

>>> re = s.run('''{"a": 123, "b": [1.1, 2.2]}''')
>>> re
{'b': array([1.1, 2.2]), 'a': 123}
>>> type(re)
<class 'dict'>

DolphinDB 中的 Table 数据形式对应 Python 中的 pandas.DataFrame 类型。在转换时，API 会将 Table 型数据的每一列作为 Vector 类型进行处理。

特别的，不同于 Vector 的处理，当 Table 型数据为时间类型时，Python pandas 仅支持一种时间类型 datetime64[ns]，因此下载的时间类型都会转换为 datetime64[ns]。

注意： 目前 API 仅支持 Array Vector 列的下载，不支持 Any Vector 列的下载。

和 Vector 型数据的转换流程不同，每一列在转换时仍旧视为是 Table 中的一列，而非单独的 Vector，因此时间类型会被转换为 datetime64[ns]。

• 注1： 如果下载 Table 型数据的数据列为 Array Vector 列，须确保每个元素的长度一致，其对应数据类型为二维 np.ndarray。

下载 Table 型数据的相关代码示例：

>>> 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 数据列，则需要其中的每个元素都长度相等。