Intro to config file

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.

The main format of the Config file is hocon, for more details of this format type you can refer to HOCON-GUIDE, BTW, we also support the json format, but you should know that the name of the config file should end with .json

Example

Before you read on, you can find config file examples here and in distribute package’s config directory.

Config file structure

The Config file will be similar to the one below.

hocon

  1. env {
  2.   job.mode = "BATCH"
  3. }
  5. source {
  6.   FakeSource {
  7.     result_table_name = "fake"
  8.     row.num = 100
  9.     schema = {
  10.       fields {
  11.         name = "string"
  12.         age = "int"
  13.         card = "int"
  14.       }
  15.     }
  16.   }
  17. }
  19. transform {
  20.   Filter {
  21.     source_table_name = "fake"
  22.     result_table_name = "fake1"
  23.     fields = [name, card]
  24.   }
  25. }
  27. sink {
  28.   Clickhouse {
  29.     host = "clickhouse:8123"
  30.     database = "default"
  31.     table = "seatunnel_console"
  32.     fields = ["name", "card"]
  33.     username = "default"
  34.     password = ""
  35.     source_table_name = "fake1"
  36.   }
  37. }

multi-line support

In hocon, multiline strings are supported, which allows you to include extended passages of text without worrying about newline characters or special formatting. This is achieved by enclosing the text within triple quotes """ . For example:

  1. var = """
  2. Apache SeaTunnel is a
  3. next-generation high-performance,
  4. distributed, massive data integration tool.
  5. """
  6. sql = """ select * from "table" """

json

  2. {
  3.   "env": {
  4.     "job.mode": "batch"
  5.   },
  6.   "source": [
  7.     {
  8.       "plugin_name": "FakeSource",
  9.       "result_table_name": "fake",
  10.       "row.num": 100,
  11.       "schema": {
  12.         "fields": {
  13.           "name": "string",
  14.           "age": "int",
  15.           "card": "int"
  16.         }
  17.       }
  18.     }
  19.   ],
  20.   "transform": [
  21.     {
  22.       "plugin_name": "Filter",
  23.       "source_table_name": "fake",
  24.       "result_table_name": "fake1",
  25.       "fields": ["name", "card"]
  26.     }
  27.   ],
  28.   "sink": [
  29.     {
  30.       "plugin_name": "Clickhouse",
  31.       "host": "clickhouse:8123",
  32.       "database": "default",
  33.       "table": "seatunnel_console",
  34.       "fields": ["name", "card"],
  35.       "username": "default",
  36.       "password": "",
  37.       "source_table_name": "fake1"
  38.     }
  39.   ]
  40. }

As you can see, the Config file contains several sections: env, source, transform, sink. Different modules have different functions. After you understand these modules, you will understand how SeaTunnel works.

env

Used to add some engine optional parameters, no matter which engine (Spark or Flink), the corresponding optional parameters should be filled in here.

Note that we have separated the parameters by engine, and for the common parameters, we can configure them as before. For flink and spark engine, the specific configuration rules of their parameters can be referred to JobEnvConfig.

source

source is used to define where SeaTunnel needs to fetch data, and use the fetched data for the next step. Multiple sources can be defined at the same time. The supported source at now check Source of SeaTunnel. Each source has its own specific parameters to define how to fetch data, and SeaTunnel also extracts the parameters that each source will use, such as the result_table_name parameter, which is used to specify the name of the data generated by the current source, which is convenient for follow-up used by other modules.

transform

When we have the data source, we may need to further process the data, so we have the transform module. Of course, this uses the word ‘may’, which means that we can also directly treat the transform as non-existent, directly from source to sink. Like below.

  1. env {
  2.   job.mode = "BATCH"
  3. }
  5. source {
  6.   FakeSource {
  7.     result_table_name = "fake"
  8.     row.num = 100
  9.     schema = {
  10.       fields {
  11.         name = "string"
  12.         age = "int"
  13.         card = "int"
  14.       }
  15.     }
  16.   }
  17. }
  19. sink {
  20.   Clickhouse {
  21.     host = "clickhouse:8123"
  22.     database = "default"
  23.     table = "seatunnel_console"
  24.     fields = ["name", "age", "card"]
  25.     username = "default"
  26.     password = ""
  27.     source_table_name = "fake1"
  28.   }
  29. }

Like source, transform has specific parameters that belong to each module. The supported source at now check. The supported transform at now check Transform V2 of SeaTunnel

sink

Our purpose with SeaTunnel is to synchronize data from one place to another, so it is critical to define how and where data is written. With the sink module provided by SeaTunnel, you can complete this operation quickly and efficiently. Sink and source are very similar, but the difference is reading and writing. So go check out our supported sinks.

Other

You will find that when multiple sources and multiple sinks are defined, which data is read by each sink, and which is the data read by each transform? We use result_table_name and source_table_name two key configurations. Each source module will be configured with a result_table_name to indicate the name of the data source generated by the data source, and other transform and sink modules can use source_table_name to refer to the corresponding data source name, indicating that I want to read the data for processing. Then transform, as an intermediate processing module, can use both result_table_name and source_table_name configurations at the same time. But you will find that in the above example Config, not every module is configured with these two parameters, because in SeaTunnel, there is a default convention, if these two parameters are not configured, then the generated data from the last module of the previous node will be used. This is much more convenient when there is only one source.

Config variable substitution

In config file we can define some variables and replace it in run time. This is only support hocon format file.

  1. env {
  2.   job.mode = "BATCH"
  3.   job.name = ${jobName}
  4.   parallelism = 2
  5. }
  7. source {
  8.   FakeSource {
  9.     result_table_name = ${resName}
  10.     row.num = ${rowNum}
  11.     string.template = ${strTemplate}
  12.     int.template = [20, 21]
  13.     schema = {
  14.       fields {
  15.         name = ${nameType}
  16.         age = "int"
  17.       }
  18.     }
  19.   }
  20. }
  22. transform {
  23.     sql {
  24.       source_table_name = "fake"
  25.       result_table_name = "sql"
  26.       query = "select * from "${resName}" where name = '"${nameVal}"' "
  27.     }
  29. }
  31. sink {
  32.   Console {
  33.      source_table_name = "sql"
  34.      username = ${username}
  35.      password = ${password}
  36.      blankSpace = ${blankSpace}
  37.   }
  38. }

In the above config, we define some variables, like ${rowNum}, ${resName}. We can replace those parameters with this shell command:

  1. ./bin/seatunnel.sh -c <this_config_file> 
  2. -i jobName='st var job' 
  3. -i resName=fake 
  4. -i rowNum=10 
  5. -i strTemplate=['abc','d~f','h i'] 
  6. -i nameType=string 
  7. -i nameVal=abc 
  8. -i username=seatunnel=2.3.1 
  9. -i password='$a^b%c.d~e0*9(' 
  10. -i blankSpace='2023-12-26 11:30:00' 
  11. -e local

Then the final submitted config is:

  1. env {
  2.   job.mode = "BATCH"
  3.   job.name = "st var job"
  4.   parallelism = 2
  5. }
  7. source {
  8.   FakeSource {
  9.     result_table_name = "fake"
  10.     row.num = 10
  11.     string.template = ["abc","d~f","h i"]
  12.     int.template = [20, 21]
  13.     schema = {
  14.       fields {
  15.         name = string
  16.         age = "int"
  17.       }
  18.     }
  19.   }
  20. }
  22. transform {
  23.     sql {
  24.       source_table_name = "fake"
  25.       result_table_name = "sql"
  26.       query = "select * from fake where name = 'abc' "
  27.     }
  29. }
  31. sink {
  32.   Console {
  33.      source_table_name = "sql"
  34.      username = "seatunnel=2.3.1"
  35.      password = "$a^b%c.d~e0*9("
  36.      blankSpace = "2023-12-26 11:30:00"
  37.   }
  38. }

Some Notes:

  • quota with ' if the value has space ` or special character (like(`)
  • if the replacement variables is in " or ', like resName and nameVal, you need add "

What’s More

If you want to know the details of this format configuration, Please see HOCON.