快速上手#
本章专为初学者设计，旨在帮助用户入门 Python Swordfish，并熟悉如何安装该库及使用其核心功能。如果您已经是高级用户或对 Swordfish 有所了解，可以选择跳过本章，直接阅读后续章节。
安装#
版本说明#
在安装 Python Swordfish 前，请确定已部署 Python 执行环境。若无，推荐使用 Anaconda Distribution 下载 Python 及常用库（future, NumPy 和 pandas）。 目前 Python Swordfish 仅支持 Linux(x86_64)。
版本要求如下：
操作系统：Linux x86-64 和 Windows amd64
Python 环境：推荐 Anaconda Distribution ，其中包括 Python 和 future、NumPy 和 pandas 等常用库。
版本要求： - Python: 3.8 to 3.12
Numpy：1.18 或更高
pandas：1.0.0 或更高版本（不包括1.3.0）
future
packaging
toml
使用 pip 安装#
从 PyPI 安装最新版本的 Python Swordfish：
pip install pyswordfish
初始化 Swordfish#
在导入 Swordfish 前，需要先联系技术支持获取 Swordfish 定制版许可证文件 dolphindb.lic，并将其放置到指定路径。
dolphindb.lic 路径查找顺序如下（优先级从高到低）：
1.环境变量`SWORDFISH_PYTHON_LICENSE_PATH`指定的路径。
- 2.配置文件 swordfish.toml 的license字段中指定的路径（该文件必须手动创建）。
点击查看 配置。
3.<home>/dolphindb.lic（默认路径）。 <home> 目录按以下顺序确定：
a.环境变量
SWORDFISH_PYTHON_HOME_PATHb.*swordfish.toml* 中的 home 配置
c.当前工作目录
Swordfish 在导入时会自动初始化，请确保导入前已正确配置许可证路径。
>>> import swordfish as sf
表#
创建表#
此示例演示如何从字典创建 Swordfish 表：
>>> import swordfish as sf
>>> sym = ["a", "b", "a", "b", "a"]
>>> timestamp = sf.vector([
... "2024.08.22 14:31:15",
... "2024.08.22 14:31:20",
... "2024.08.22 14:31:30",
... "2024.08.22 14:31:30",
... "2024.08.22 14:31:50",
... ], type="TIMESTAMP")
>>> vol = [1, 2, 3, 6, 8]
>>> price = [11.5, 12.8, 13.5, 11.6, 13.8]
>>> t = sf.table({
... 'sym': sym,
... 'timestamp': timestamp,
... 'vol': vol,
... 'price': price,
... })
>>> t
sym timestamp vol price
--- ----------------------- --- ------------------
a 2024.08.22T14:31:15.000 1 11.5
b 2024.08.22T14:31:20.000 2 12.8
a 2024.08.22T14:31:30.000 3 13.5
b 2024.08.22T14:31:30.000 6 11.6
a 2024.08.22T14:31:50.000 8 13.8
可以通过指定列名和数据类型来创建表。
>>> sym = ["a", "b", "a", "b", "a"]
>>> timestamp = sf.vector([
... "2024.08.22 14:31:15",
... "2024.08.22 14:31:20",
... "2024.08.22 14:31:30",
... "2024.08.22 14:31:30",
... "2024.08.22 14:31:50",
... ], type="TIMESTAMP")
>>> vol = [1, 2, 3, 6, 8]
>>> price = [11.5, 12.8, 13.5, 11.6, 13.8]
>>> t = sf.table(
... {
... 'sym': sym,
... 'timestamp': timestamp,
... 'vol': vol,
... 'price': price,
... },
... names=['sym', 'timestamp', 'vol', 'price'],
... types=['STRING', 'TIMESTAMP', 'INT', 'DOUBLE'],
... )
可以从 DataFrame 创建表。
>>> import pandas as pd
>>> df = pd.DataFrame({
... "name": ["a", "b", "c", "b", "c"],
... "id": [12, 13, 15, 14, 16],
... })
>>> t = sf.table(df)
>>> t
name id
---- -----
a 12
b 13
c 15
b 14
c 16
查看数据#
通过 head() 和 tail() 分别查看表格的前几行和最后几行。
>>> t.head(2)
sym timestamp vol price
--- ----------------------- --- -----
a 2024.08.22T14:31:15.000 1 11.5
b 2024.08.22T14:31:20.000 2 12.8
上面的代码从表 “t” 中查看前两行。如下代码从表 “t” 中查看最后两行。
>>> t.tail(2)
sym timestamp vol price
--- ----------------------- --- -----
b 2024.08.22T14:31:30.000 6 11.6
a 2024.08.22T14:31:50.000 8 13.8
通过 count() 和 summary() 分别查看表格行数和描述性信息。
查看表 “t” 中的总行数。
>>> t.count()
Int(5)
查看表 't' 的汇总统计信息，例如计数、平均值、每列的最小值、最大值和其他聚合信息。
>>> t.summary()
name min max nonNullCount count avg std percentile
----- ---- ---- ------------ ----- ----- ----------------- ----------------------------------------------------------
vol 1 8 5 5 4 2.91547594742265 [1.999999523305699,3.000002384471506,5.999997616528495]
price 11.5 13.8 5 5 12.64 1.059716943339125 [11.600000524564352,12.800000238983796,13.500000620757871]
通过 sortBy_() 可以基于表的列进行排序。
>>> t.sortBy_("sym")
sym timestamp vol price
--- ----------------------- --- ------------------
a 2024.08.22T14:31:15.000 1 11.5
a 2024.08.22T14:31:30.000 3 13.5
a 2024.08.22T14:31:50.000 8 13.8
b 2024.08.22T14:31:20.000 2 12.8
b 2024.08.22T14:31:30.000 6 11.6
选择数据#
使用 Table[colLabel] 或 Table.colLabel 访问表中的列，并生成一个向量。
>>> t["sym"]
Vector(["a","a","a","b","b"], type=STRING)
>>> t.sym
Vector(["a","a","a","b","b"], type=STRING)
使用 Table[rowIndex] 访问表中的行。当 rowIndex 为整数时，返回字典。当 rowIndex 是切片或列表时，返回一个 Table。
>>> t[0]
Dictionary(
sym->a
timestamp->2024.08.22T14:31:15.000
vol->1
price->11.5
, key_type=STRING, val_type=ANY)
>>> t[1:3]
sym timestamp vol price
--- ----------------------- --- -----
b 2024.08.22T14:31:20.000 2 12.8
a 2024.08.22T14:31:30.000 3 13.5
合并表#
调用 swordfish.function 模块中的 join 函数合并两个表。首先创建两个表 t1 和 t2。
>>> t1 = sf.table({
... 'sym': ["a", "b", "a", "b", "a"],
... 'price': [11.5, 12.8, 13.5, 11.6, 13.8],
... })
>>> t2 = sf.table({
... 'name': ["a", "b", "c", "b", "c"],
... 'val': [12, 13, 15, 14, 16],
... })
>>> t1
sym price
--- ------------------
a 11.5
b 12.8
a 13.5
b 11.599999999999999
a 13.8
>>> t2
name val
---- -----
a 12
b 13
c 15
b 14
c 16
调用 join 函数来合并 t1 和 t2。
>>> import swordfish.function as F
>>> F.join(t1, t2)
sym price name val
--- ------------------ ---- -----
a 11.5 a 12
b 12.8 b 13
a 13.5 c 15
b 11.599999999999999 b 14
a 13.8 c 16
SQL 操作#
在 Swordfish 中，SQL 语句是使用 sql 函数执行的。本节演示使用 sql 函数对表进行基本操作。
从 t2 中选择 val 列：
>>> sf.sql("SELECT val FROM t", vars={"t": t2})
val
-----
12
13
15
14
16
通过 WHERE 子句过滤数据：
>>> sf.sql("SELECT valt FROM t WHERE val>14", vars={"t": t2})
val
-----
15
16
通过 UPDATE 语句更新表数据：
>>> sf.sql("UPDATE t SET val=10 WHERE val=14", vars={"t": t2})
name val
---- -----
a 12
b 13
c 15
b 10
c 16
通过 DELETE 语句从表中删除行：
>>> sf.sql("DELETE from t WHERE val=16", vars={"t": t2})
name val
---- -----
a 12
b 13
c 15
b 14
通过 GROUP BY 语句查询表中各个 sym 分组分别包含几条数据：
>>> sf.sql("SELECT count(sym) as counts FROM t GROUP BY sym", vars={"t": t1})
sym counts
--- ------
a 3
b 2
通过 LEFT JOIN 语句连接两个表：
>>> sf.sql("SELECT * FROM ta LEFT JOIN tb on ta.sym = tb.name",
... vars={"ta": t1, "tb": t2})
sym price val
--- ------------------ -----
a 11.5 12
b 12.8 13
b 12.8 14
a 13.5 12
b 11.599999999999999 13
b 11.599999999999999 14
a 13.8 12
矩阵#
创建矩阵#
通过一个嵌套列表构造一个 Matrix 对象。
>>> m = sf.matrix([[1, 2, 3], [0, 1, 4], [5, 6, 0]])
>>> m
Matrix(
#0 #1 #2
-- -- --
1 0 5
2 1 6
3 4 0
, type=LONG)
矩阵计算#
首先导入函数库模块，然后调用其中的函数对矩阵进行计算。
>>> import swordfish.function as F
计算矩阵每一列的最大值与最小值。
>>> F.max(m)
Vector([3,4,6], type=LONG)
>>> F.min(m)
Vector([1,0,0], type=LONG)
矩阵转置
>>> F.transpose(m)
Matrix(
#0 #1 #2
-- -- --
1 2 3
0 1 4
5 6 0
, type=LONG)
矩阵求逆
>>> F.inverse(m)
Matrix(
#0 #1 #2
------------------- ------------------- ------------------
-24.000000000000088 20.000000000000074 -5.000000000000021
18.000000000000067 -15.000000000000055 4.000000000000014
5.000000000000018 -4.000000000000015 1.000000000000003
, type=DOUBLE)
导入导出#
将表另存为 CSV 文件：
>>> t = sf.table({
... 'sym': ["a", "b", "a", "b", "a"],
... 'vol': [1, 2, 3, 6, 8],
... 'price': [11.5, 12.8, 13.5, 11.6, 13.8],
... })
>>> import swordfish.function as F
>>> F.saveText(t, "./data.csv")
从 CSV 文件加载表：
>>> F.loadText(t, "./data.csv")
sym vol price
--- --- ------------------
a 1 11.5
b 2 12.8
a 3 13.5
b 6 11.599999999999999
a 8 13.8