[Doc][Improve] support chinese (apache#6373)

chaorongzhi · Aug 21, 2024 · 1a718ab · 1a718ab
1 parent f79f8f4
commit 1a718ab
Show file tree

Hide file tree

Showing 8 changed files with 707 additions and 1 deletion.
diff --git a/docs/en/other-engine/flink.md b/docs/en/other-engine/flink.md
@@ -1,6 +1,6 @@
 # Seatunnel runs on Flink
 
-Flink is a powerful high-performance distributed stream processing engine,More information about it you can,You can search for `Apacke Flink`
+Flink is a powerful high-performance distributed stream processing engine,More information about it you can,You can search for `Apache Flink`
 
 ### Set Flink configuration information in the job
 

diff --git a/docs/zh/concept/JobEnvConfig.md b/docs/zh/concept/JobEnvConfig.md
@@ -0,0 +1,52 @@
+# JobEnvConfig
+
+本文档描述了env的配置信息，公共参数可以在所有引擎中使用。为了更好的区分引擎参数，其他引擎的附加参数需要携带前缀。
+在flink引擎中，我们使用`flink.`作为前缀。在spark引擎中，我们不使用任何前缀来修改参数，因为官方的spark参数本身就是以`spark.`开头。
+
+## 公共参数
+
+以下配置参数对所有引擎通用：
+
+### job.name
+
+该参数配置任务名称。
+
+### jars
+
+第三方包可以通过`jars`加载，例如：`jars="file://local/jar1.jar;file://local/jar2.jar"`
+
+### job.mode
+
+通过`job.mode`你可以配置任务是在批处理模式还是流处理模式。例如：`job.mode = "BATCH"` 或者 `job.mode = "STREAMING"`
+
+### checkpoint.interval
+
+获取定时调度检查点的时间间隔。
+
+在`STREAMING`模式下，检查点是必须的，如果不设置，将从应用程序配置文件`seatunnel.yaml`中获取。 在`BATCH`模式下，您可以通过不设置此参数来禁用检查点。
+
+### parallelism
+
+该参数配置source和sink的并行度。
+
+### shade.identifier
+
+指定加密方式，如果您没有加密或解密配置文件的需求，此选项可以忽略。
+
+更多详细信息，您可以参考文档 [config-encryption-decryption](../../en/connector-v2/Config-Encryption-Decryption.md)
+
+## Flink 引擎参数
+
+这里列出了一些与 Flink 中名称相对应的 SeaTunnel 参数名称，并非全部，更多内容请参考官方 [flink documentation](https://flink.apache.org/) for more.
+
+|           Flink 配置名称            |            SeaTunnel 配置名称             |
+|---------------------------------|---------------------------------------|
+| pipeline.max-parallelism        | flink.pipeline.max-parallelism        |
+| execution.checkpointing.mode    | flink.execution.checkpointing.mode    |
+| execution.checkpointing.timeout | flink.execution.checkpointing.timeout |
+| ...                             | ...                                   |
+
+## Spark 引擎参数
+
+由于spark配置项并无调整，这里就不列出来了，请参考官方 [spark documentation](https://spark.apache.org/).
+
diff --git a/docs/zh/concept/config.md b/docs/zh/concept/config.md
@@ -0,0 +1,191 @@
+---
+
+sidebar_position: 2
+-------------------
+
+# 配置文件简介
+
+In SeaTunnel, the most important thing is the Config file, through which users can customize their own data
+synchronization requirements to maximize the potential of SeaTunnel. So next, I will introduce you how to
+configure the Config file.
+
+在SeaTunnel中，最重要的事情就是配置文件，尽管用户可以自定义他们自己的数据同步需求以发挥SeaTunnel最大的潜力。那么接下来，
+我将会向你介绍如何设置配置文件。
+
+The main format of the Config file is `hocon`, for more details of this format type you can refer to [HOCON-GUIDE](https://github.com/lightbend/config/blob/main/HOCON.md),
+BTW, we also support the `json` format, but you should know that the name of the config file should end with `.json`
+
+配置文件的主要格式是 `hocon`, 有关该格式类型的更多信息你可以参考[HOCON-GUIDE](https://github.com/lightbend/config/blob/main/HOCON.md),
+顺便提一下，我们也支持 `json`格式，但你应该知道配置文件的名称应该是以 `.json`结尾。
+
+## 例子
+
+在你阅读之前，你可以在发布包中的config目录[这里](https://github.com/apache/seatunnel/tree/dev/config)找到配置文件的例子。
+
+## 配置文件结构
+
+配置文件类似下面。
+
+### hocon
+
+```hocon
+env {
+  job.mode = "BATCH"
+}
+
+source {
+  FakeSource {
+    result_table_name = "fake"
+    row.num = 100
+    schema = {
+      fields {
+        name = "string"
+        age = "int"
+        card = "int"
+      }
+    }
+  }
+}
+
+transform {
+  Filter {
+    source_table_name = "fake"
+    result_table_name = "fake1"
+    fields = [name, card]
+  }
+}
+
+sink {
+  Clickhouse {
+    host = "clickhouse:8123"
+    database = "default"
+    table = "seatunnel_console"
+    fields = ["name", "card"]
+    username = "default"
+    password = ""
+    source_table_name = "fake1"
+  }
+}
+```
+
+### json
+
+```json
+
+{
+  "env": {
+    "job.mode": "batch"
+  },
+  "source": [
+    {
+      "plugin_name": "FakeSource",
+      "result_table_name": "fake",
+      "row.num": 100,
+      "schema": {
+        "fields": {
+          "name": "string",
+          "age": "int",
+          "card": "int"
+        }
+      }
+    }
+  ],
+  "transform": [
+    {
+      "plugin_name": "Filter",
+      "source_table_name": "fake",
+      "result_table_name": "fake1",
+      "fields": ["name", "card"]
+    }
+  ],
+  "sink": [
+    {
+      "plugin_name": "Clickhouse",
+      "host": "clickhouse:8123",
+      "database": "default",
+      "table": "seatunnel_console",
+      "fields": ["name", "card"],
+      "username": "default",
+      "password": "",
+      "source_table_name": "fake1"
+    }
+  ]
+}
+
+```
+
+正如你看到的，配置文件包括几个部分：env, source, transform, sink。不同的模块有不同的功能。
+当你了解了这些模块后，你就会懂得SeaTunnel如何工作。
+
+### env
+
+用于添加引擎可选的参数，不管是什么引擎（Spark 或者 Flink），对应的可选参数应该在这里填写。
+
+注意，我们按照引擎分离了参数，对于公共参数，我们可以像以前一样配置。对于Flink和Spark引擎，其参数的具体配置规则可以参考[JobEnvConfig](./JobEnvConfig.md)。
+
+<!-- TODO add supported env parameters -->
+
+### source
+
+source用于定义SeaTunnel在哪儿检索数据，并将检索的数据用于下一步。
+可以同时定义多个source。目前支持的source请看[Source of SeaTunnel](../../en/connector-v2/source)。每种source都有自己特定的参数用来
+定义如何检索数据，SeaTunnel也抽象了每种source所使用的参数，例如 `result_table_name` 参数，用于指定当前source生成的数据的名称，
+方便后续其他模块使用。
+
+### transform
+
+当我们有了数据源之后，我们可能需要对数据进行进一步的处理，所以我们就有了transform模块。当然，这里使用了“可能”这个词，
+这意味着我们也可以直接将transform视为不存在，直接从source到sink。像下面这样。
+
+```hocon
+env {
+  job.mode = "BATCH"
+}
+
+source {
+  FakeSource {
+    result_table_name = "fake"
+    row.num = 100
+    schema = {
+      fields {
+        name = "string"
+        age = "int"
+        card = "int"
+      }
+    }
+  }
+}
+
+sink {
+  Clickhouse {
+    host = "clickhouse:8123"
+    database = "default"
+    table = "seatunnel_console"
+    fields = ["name", "age", "card"]
+    username = "default"
+    password = ""
+    source_table_name = "fake1"
+  }
+}
+```
+
+与source类似, transform也有属于每个模块的特定参数。目前支持的source请看。目前支持的transform请看 [Transform V2 of SeaTunnel](../../en/transform-v2)
+
+<!-- TODO missing source links --->
+
+### sink
+
+我们使用SeaTunnel的作用是将数据从一个地方同步到其它地方，所以定义数据如何写入，写入到哪里是至关重要的。通过SeaTunnel提供的
+sink模块，你可以快速高效地完成这个操作。Sink和source非常相似，区别在于读取和写入。所以去看看我们[支持的sink](../../en/connector-v2/sink)吧。
+
+### 其它
+
+你会疑惑当定义了多个source和多个sink时，每个sink读取哪些数据，每个transform读取哪些数据？我们使用`result_table_name` 和
+`source_table_name` 两个键配置。每个source模块都会配置一个`result_table_name`来指示数据源生成的数据源名称，其它transform和sink
+模块可以使用`source_table_name` 引用相应的数据源名称，表示要读取数据进行处理。然后transform，作为一个中间的处理模块，可以同时使用
+`result_table_name` 和 `source_table_name` 配置。但你会发现在上面的配置例子中，不是每个模块都配置了这些参数，因为在SeaTunnel中，
+有一个默认的约定，如果这两个参数没有配置，则使用上一个节点的最后一个模块生成的数据。当只有一个source时这是非常方便的。
+
+## 此外
+
+如果你想了解更多关于格式配置的详细信息，请查看 [HOCON](https://github.com/lightbend/config/blob/main/HOCON.md)。
diff --git a/docs/zh/concept/connector-v2-features.md b/docs/zh/concept/connector-v2-features.md
@@ -0,0 +1,70 @@
+# Connector V2 功能简介
+
+## Connector V2 和 Connector V1 之间的不同
+
+从 https://github.com/apache/seatunnel/issues/1608 我们添加了 Connector V2 特性。
+Connector V2 是基于SeaTunnel Connector API接口定义的连接器。不像Connector V1，Connector V2 支持如下特性：
+
+* **多引擎支持** SeaTunnel Connector API 是引擎独立的API。基于这个API开发的连接器可以在多个引擎上运行。目前支持Flink和Spark引擎，后续我们会支持其它的引擎。
+* **多引擎版本支持** 通过翻译层将连接器与引擎解耦，解决了大多数连接器需要修改代码才能支持新版本底层引擎的问题。
+* **流批一体** Connector V2 可以支持批处理和流处理。我们不需要为批和流分别开发连接器。
+* **多路复用JDBC/Log连接。** Connector V2支持JDBC资源复用和共享数据库日志解析。
+
+## Source Connector 特性
+
+Source connector有一些公共的核心特性，每个source connector在不同程度上支持它们。
+
+### 精确一次（exactly-once）
+
+如果数据源中的每条数据仅由源向下游发送一次，我们认为该source connector支持精确一次（exactly-once）。
+
+在SeaTunnel中, 我们可以保存读取的 **Split** 和 它的 **offset**(当时读取的数据被分割时的位置，例如行号, 字节大小, 偏移量等) 作为检查点时的 **StateSnapshot** 。 如果任务重新启动, 我们会得到最后的 **StateSnapshot**
+然后定位到上次读取的 **Split** 和 **offset**，继续向下游发送数据。
+
+例如 `File`, `Kafka`。
+
+### 列投影（column projection）
+
+如果连接器支持仅从数据源读取指定列（请注意，如果先读取所有列，然后通过元数据（schema）过滤不需要的列，则此方法不是真正的列投影）
+
+例如 `JDBCSource` 可以使用sql定义读取列。
+
+`KafkaSource` 从主题中读取所有内容然后使用`schema`过滤不必要的列, 这不是真正的`列投影`。
+
+### 批（batch）
+
+批处理作业模式，读取的数据是有界的，当所有数据读取完成后作业将停止。
+
+### 流（stream）
+
+流式作业模式，数据读取无界，作业永不停止。
+
+### 并行性（parallelism）
+
+并行执行的Source Connector支持配置 `parallelism`，每个并发会创建一个任务来读取数据。
+在**Parallelism Source Connector**中，source会被分割成多个split，然后枚举器会将 split 分配给 SourceReader 进行处理。
+
+### 支持用户自定义split
+
+用户可以配置分割规则。
+
+### 支持多表读取
+
+支持在一个 SeaTunnel 作业中读取多个表
+
+## Sink Connector 的特性
+
+Sink connector有一些公共的核心特性，每个sink connector在不同程度上支持它们。
+
+### 精确一次（exactly-once）
+
+当任意一条数据流入分布式系统时，如果系统在整个处理过程中仅准确处理任意一条数据一次，且处理结果正确，则认为系统满足精确一次一致性。
+
+对于sink connector，如果任何数据只写入目标一次，则sink connector支持精确一次。 通常有两种方法可以实现这一目标：
+
+* 目标数据库支持key去重。例如 `MySQL`, `Kudu`。
+* 目标支持 **XA 事务**(事务可以跨会话使用。即使创建事务的程序已经结束，新启动的程序也只需要知道最后一个事务的ID就可以重新提交或回滚事务）。 然后我们可以使用 **两阶段提交** 来确保 * 精确一次**。 例如：`File`, `MySQL`.
+
+### cdc(更改数据捕获，change data capture)
+
+如果sink connector支持基于主键写入行类型（INSERT/UPDATE_BEFORE/UPDATE_AFTER/DELETE），我们认为它支持cdc（更改数据捕获，change data capture）。