---
source_url: https://docs.dolphindb.cn/zh/pydoc/QuickStart/Demo.html
fetched_at: 2026-05-19T09:52:40Z
category: pydoc
title: 快速开始
sha1: b3f60d1fddce786c1a9093eae4454f514b9d3cb4
---

# 快速开始

本节将展示通过 dolphindb 连接、使用及操作单节点 DolphinDB 服务器的完整操作。

通过阅读，您将了解到如何使用 dolphindb 连接 DolphinDB 并与之交互、以及如何操作数据库表。

## 使用前准备

### Python 基础知识

在学习使用 dolphindb 前，建议您先了解 Python 的相关知识。您可以查阅 [Python 官方教程](https://docs.python.org/3/tutorial/)，了解有关 Python 的更多信息和教程。

### 搭建 DolphinDB 服务器

在 [DolphinDB 官网](https://dolphindb.cn/)下载 DolphinDB 服务器，并参考[单节点部署教程](https://docs.dolphindb.cn/zh/tutorials/standalone_server.html)启动 DolphinDB 服务。

有关快速部署 DolphinDB 服务器, 请参考[Linux 系统部署准备](https://docs.dolphindb.cn/zh/tutorials/prep_linux_for_deploy.html)。

如果您想尝试更多部署方式，请参阅 [部署](https://docs.dolphindb.cn/zh/deploy/deploy_intro.html)。

## 建立连接

session（会话控制）可以实现客户端与服务器之间的信息交互。DolphinDB Python API 通过 session 在 DolphinDB 服务器上执行脚本和函数，同时实现双向的数据传递。

**注意**： dolphindb 自 1.30.22.1 版本调整 session 类名为 Session，同时增加别名 session 以确保兼容性。

### session 连接及使用示例

在如下脚本中，先通过 `import` 语句导入 dolphindb ，在 Python 中创建一个 session，然后使用指定的域名（或 IP 地址）和端口号把该会话连接到 DolphinDB 服务器。最后展示一个简单的计算示例，执行 `1+1` 的脚本，得到返回值 `2`。

```dolphindb
>>> import dolphindb as ddb
>>> s = ddb.session()
>>> s.connect("localhost", 8848)
True
>>> s.run("1+1;")
2
>>> s.close()
```

**注意**：

- 建立连接前，须先启动 DolphinDB 服务器。
- 若当前 session 不再使用，建议立即调用 `close()` 关闭会话。否则可能出现因连接数过多，导致其它会话无法连接服务器的情况。

## 数据交互

dolphindb 目前支持多种数据交互的方法，本节仅介绍通过 run, upload 等方式上传和下载数据。更多交互方式请参考章节 [session 的常用方法](../BasicOperations/Session/OtherParams.html) 和 [DBConnectionPool 的常用方法](../BasicOperations/DBConnectionPool/AsyncMethodsAndOthers.html)。

下表为 [DolphinDB 的各种数据形式](https://docs.dolphindb.cn/zh/progr/data_forms.html)与 Python 对象的对应关系。

| DolphinDB DataForm | Python |
| --- | --- |
| Scalar | int/str/float/... |
| Vector | numpy.ndarray |
| Pair | list |
| Matrix | [numpy.ndarray, numpy.ndarray, numpy.ndarray] |
| Set | set |
| Dictionary | dict |
| Table | pandas.DataFrame |

**注意**：

- 由于 DolphinDB 中的 Matrix 对象可以设置行名和列名，故下载的 Matrix 形式的数据将转换成 list 类型的 Python 对象。该 list 对象中将包含一个表示数据的二维数组和两个分别表示行名、列名的一维数组。
- 若 API 使用不同的下载方式，同样的 DolphinDB 数据将会对应不同的 Python 对象。详情请参考章节[类型转换](https://docs.dolphindb.cn/zh/api/python/AdvancedOperations/DataTypeCasting/TypeCasting.html)。

在下载数据前，首先导入 dolphindb，然后创建一个 session 并连接到 DolphinDB 服务端。

```dolphindb
>>> import dolphindb as ddb
>>> s = ddb.session()
>>> s.connect("localhost", 8848)
True
```

### 下载数据

使用 `s.run` 的方式运行脚本，成功执行后将下载具体数据。

以下依次创建并下载数据形式分别为标量（Scalar）、向量（Vector）、数据对（Pair）、矩阵（Matrix）、集合（Set）、字典（Dictionary）和表（Table）的数据。

**标量（Scalar）**

```dolphindb
>>> s.run("1;")
1
```

**向量（Vector）**

```dolphindb
>>> s.run("1..10;")
array([ 1,  2,  3,  4,  5,  6,  7,  8,  9, 10], dtype=int32)
```

**数据对（Pair）**

```dolphindb
>>> s.run("1:5;")
[1, 5]
```

**矩阵（Matrix）**

```dolphindb
>>> s.run("1..6$2:3;")
[array([[1, 3, 5],
       [2, 4, 6]], dtype=int32), None, None]
```

**集合（Set）**

```dolphindb
>>> s.run("set([1,5,9]);")
{1, 5, 9}
```

**字典（Dictionary）**

```dolphindb
>>> s.run("dict(1 2 3, 4.5 7.8 4.3);")
{2: 7.8, 1: 4.5, 3: 4.3}
```

**表（Table）**

```dolphindb
>>> s.run("table(`XOM`GS`AAPL as id, 102.1 33.4 73.6 as x);")
     id      x
0   XOM  102.1
1    GS   33.4
2  AAPL   73.6
```

### 上传数据

导入库 numpy 和 pandas，示例如下：

```dolphindb
>>> import numpy as np
>>> import pandas as pd
```

通过 `s.upload` 的方式上传数据，输入参数 `变量名称：数据`，成功执行后将返回该变量在服务器端的地址。

以下将依次展示上传 Python 对象对应 DolphinDB 数据形式为标量（Scalar）、向量（Vector）、矩阵（Matrix）、集合（Set）、字典（Dictionary）和表（Table）的数据。

**注意**： Python API 暂不支持上传数据对（Pair）形式的数据。

以下脚本中将展示成功上传后，通过 `typestr` 函数查询数据的 DolphinDB 类型名称，以及使用 `s.run` 的方式重新下载数据。

**标量（Scalar）**

```dolphindb
>>> s.upload({'scalar_sample': 1})
62776640
>>> s.run("typestr(scalar_sample);")
'LONG'
>>> s.run("scalar_sample;")
1
```

**向量（Vector）**

```dolphindb
>>> s.upload({'vector_sample': np.array([1, 3])})
65583680
>>> s.run("typestr(vector_sample);")
'FAST LONG VECTOR'
>>> s.run("vector_sample;")
array([1, 3])
```

**矩阵（Matrix）**

```dolphindb
>>> s.upload({'matrix_sample': np.array([[1, 2, 3], [4, 5, 6]])})
65484832
>>> s.run("typestr(matrix_sample);")
'FAST LONG MATRIX'
>>> s.run("matrix_sample;")
[array([[1, 2, 3],
       [4, 5, 6]]), None, None]
```

**集合（Set）**

```dolphindb
>>> s.upload({'set_sample': {1, 4, 7}})
65578432
>>> s.run("typestr(set_sample);")
'LONG SET'
>>> s.run("set_sample;")
{1, 4, 7}
```

**字典（Dictionary）**

```dolphindb
>>> s.upload({'dict_sample': {'a': 1}})
58318576
>>> s.run("typestr(dict_sample);")
'STRING->LONG DICTIONARY'
>>> s.run("dict_sample;")
{'a': 1}
```

**表（Table）**

```dolphindb
>>> df = pd.DataFrame({'a': [1, 2, 3], 'b': ['a', 'b', 'c']})
>>> s.upload({'table_sample': df})
63409760
>>> s.run("typestr(table_sample);")
'IN-MEMORY TABLE'
>>> s.run("table_sample;")
   a  b
0  1  a
1  2  b
2  3  c
```

## 数据库操作

Python API 支持通过如下两种方式操作 DolphinDB：

- 方式一：通过 `session.run()` 执行 DolphinDB 脚本。
- 方式二：使用 Python API 封装的方法操作服务器。

以下展示两种方式的使用示例。

### 方式一：执行 DolphinDB 脚本

在以下脚本中，先导入 dolphindb，创建一个 session 并连接到 DolphinDB 服务端。由于后续脚本中涉及到执行数据库相关的操作，须在连接服务端的并且登录具有相应权限的账户。

在完成上述操作后，通过 `s.run()` 执行创建变量、数据库 db 和数据表 pt，并向表 pt 中写入数据等操作，最后执行 SQL 语句返回表 pt 的行数。

```dolphindb
import dolphindb as ddb
s = ddb.session()
s.connect("localhost", 8848, "admin", "123456")
s.run("""
    n=1000000
    ID=rand(10, n)
    x=rand(1.0, n)
    t=table(ID, x)
    db=database(directory="dfs://hashdb", partitionType=HASH, partitionScheme=[INT, 2])
    pt = db.createPartitionedTable(t, `pt, `ID)
    pt.append!(t);
""")
re = s.run("select count(x) from pt;")
print(re)

// output
   count_x
0  1000000
```

### 方式二：使用 API 接口

在以下脚本中，首先创建一个 session 并连接到 DolphinDB 服务端，同时登录具有相应权限的账户。然后创建 schema\_t 用于定义分布式表的表结构。使用 API 接口执行 `session.table`, `session.database` 和 `Database.createPartitionedTable` 以创建一个内存表、数据库 db 和 分区表 pt，再通过 `pt.append` 方法向表中追加数据。最后使用 `Table.toDF` 获取表 pt 的数据。

```dolphindb
import pandas as pd
import numpy as np
import dolphindb as ddb
import dolphindb.settings as keys

s = ddb.session("192.168.1.113", 8848, "admin", "123456")
n = 1000000
df = pd.DataFrame({
    'ID':   np.random.randint(0, 10, n),
    'x':    np.random.rand(n),
})
s.run("schema_t = table(100000:0, `ID`x,[INT, DOUBLE])")
schema_t = s.table(data="schema_t")
if s.existsDatabase("dfs://hashdb"):
    s.dropDatabase("dfs://hashdb")
db = s.database(dbPath="dfs://hashdb", partitionType=keys.HASH, partitions=[keys.DT_INT, 2])
pt: ddb.Table = db.createPartitionedTable(table=schema_t, tableName="pt", partitionColumns=["ID"])
data = s.table(data=df)
pt.append(data)
print(pt.toDF())

// output
        ID         x
0        4  0.320935
1        8  0.426056
2        8  0.505221
3        4  0.692984
4        4  0.709175
...     ..       ...
999995   5  0.479531
999996   3  0.805629
999997   5  0.873164
999998   7  0.158090
999999   5  0.530824

[1000000 rows x 2 columns]
```

## 相关内容

- [数据形式](https://docs.dolphindb.cn/zh/progr/data_forms.html)
- [数据库操作](https://docs.dolphindb.cn/zh/db_distr_comp/db_distr_comp.html)
