# 从数据库获取数据

## DBAPIDumpTask

`DBAPIDumpTask` 用于从支持 [DBAPI](https://www.python.org/dev/peps/pep-0249/) 规范的数据库中提取数据。

DBAPI (Python Database API Specification) 是 Python 中访问数据库的标准接口规范。它定义了一套通用的 API，允许 Python 程序以统一的方式与不同的数据库进行交互，例如 MySQL、PostgreSQL、SQLite 等。DBAPI 可以类比为 JDBC.

## 操作步骤

使用 Transfer Operator 从数据库或数仓获取数据，操作步骤如下：

1. 创建一个高级管道（Advanced pipeline）
2. 点击“添加节点”，选择“Transfer Operator” 
3. 在右侧表单中，Dump 部分 “Task Type” 选择 `DBAPIDumpTask`

<figure><img src="https://3914025029-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMNJfiu2Or0lnmkm2x228%2Fuploads%2FyeV5wwm8gxiqDiNKQBaP%2Fimage.png?alt=media&#x26;token=cf0e5bb9-7850-4e26-a756-36e91752881c" alt=""><figcaption></figcaption></figure>

## 配置项 <a href="#configurations" id="configurations"></a>

### 定义要导入的数据源及数据范围

#### 数据源

* 具体来源数据库，从当前项目已添加的连接源中选择。前置步骤详见 [xiang-mu-lian-jie-guan-li](https://docs.reorc.com/cn-reorc-help-center/lian-jie/xiang-mu-lian-jie-guan-li "mention")

#### 源表

* 输入表的名字，会同步所有字段；
* 可以使用 `database_name.table_name` 格式\
  \*Postgres 和 Redshift 是 `schema_name.table_name`格式

#### 自定义 SQL

* 查询语句，支持使用[变量](https://docs.reorc.com/cn-reorc-help-center/advanced_usage/bian-liang)。&#x20;
* 如果同时填了源表名和自定义 SQL，则会以 自定义 SQL 为准 （两者必须至少填一个，自定义 SQL 的优先级更高）。

### 分片与并发

DBAPIDumpTask 提供了分片和并发功能，允许用户将数据同步任务拆分成多个子任务并行执行，从而充分利用系统资源，缩短同步时间。

#### 分片字段

* 用于将数据划分为多个分片的字段。该字段应具有良好的数据分布性，例如主键、时间戳等。
* 分片字段需要可排序，通常是整型、时间戳类型，不允许有 NULL 值，而且需要建索引以提升性能。
* 对于用字符串表达的时间戳，目前只支持 `YYYY-MM-DD` 和 `YYYY-MM-DD hh:mm:ss` 格式。
* 填写分片字段后会提示配置分片数和并发数。

#### 分片数

* 将数据划分成的分片数量。分片数越多，每个分片的数据量越小。

#### 并发数

* 同时执行的分片任务数量。通常并发数越高，同步速度越快，但也会消耗更多的系统资源，例如 CPU、内存和数据库连接。

{% hint style="info" %}
**如何选择合适的分片数和并发数？**

需要综合考虑数据库的性能、网络带宽、数据库超时、单行数据大小、数据倾斜情况等，所以很难给出一个标准计算公式。以下是一些经验值供参考：

1. 分片数设置
   1. 单个分片的数据量建议控制在 **50 万行以内**，以确保稳定性。
   2. 如果遇到超时等问题，可减少分片数据量（如 30 万行）。
   3. 在数据库性能、网络条件较好的情况下，单个分片的数据量可适当增加，但通常不建议超过 2**00 万行**。
   4. **分片数计算**：分片数 = 总数据量 / 单个分片的数据量。
2. 并发数设置
   1. 建议从 **5 个并发**开始测试，根据实际情况调整。通常建议不要超过 **10 个**，以避免对数据库造成过大压力。
   2. 如果数据库性能、网络条件较差，可将并发数设置为 1.
   3. **注意事项**：并发数应远小于分片数（如分片数为 50，并发数为 5）。
      {% endhint %}

### 启用基于时间的增量同步

可选是否按时间进行增量同步，一般用在周期性任务中。启用增量同步之后，系统会根据作业的调度周期，自动计算出时间范围，并添加到 `WHERE` 条件。勾选之后可以进一步配置：

#### 时间列名称

* 填写时间类型的字段名称，按这一列的时间进行增量同步
* 建议使用已建立索引的字段

#### 时区

* 默认是 UTC，北京时间是 Asia/Shanghai。

#### 时间戳格式

* 时间列的类型，仅日期（date, `YYYY-MM-DD`）或 日期+时间（datetime, `YYYY-MM-DD hh:mm:ss`）

**Auto Round Time Range**

* 自动将时间范围四舍五入到适当的间隔。例如：&#x20;
  * 日度任务将同步前一天 00:00 到当天 00:00 的数据
  * 周度任务将四舍五入到每周周一 00:00&#x20;
  * 月度任务将四舍五入到每月 1 号 00:00
* 如果禁用，则将使用精确的执行时间。例如调度周期为日度 `01:23`，则同步的时间范围是 01:23 到 01:23.