# 从数据库获取数据

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.reorc.com/cn-reorc-help-center/data-ingestion/lian-jie-yuan-lei-xing/cong-shu-ju-ku-huo-qu-shu-ju.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.