Addax Documentation

English

中文

English

中文

主题

Excel Reader ​

Excel Reader plugin implements the ability to read data from Microsoft Excel files.

Configuration ​

Get Sample Files ​

Download the Excel compressed file for demonstration from here and extract it to the /tmp/in directory. The three folders have the same content, where:

  • demo.xlsx is the new Excel format
  • demo_old.xls is the old Excel format
  • demo_gbk.xlsx is created under Windows and stored with GBK encoding

File content is shown in the following table:

No.Integer TypeFloat TypeString TypeDate TypeFormula CalculationCell Formatting
1111102.234Addax 加上中文2021/9/105544.17¥1,102.23
2121103.234Addax 加上中文2021/9/115552.17¥1,103.23
3131104.234Addax 加上中文2021/9/125560.17¥1,104.23
4141105.234Addax 加上中文2021/9/135568.17¥1,105.23
5151106.234Addax 加上中文2021/9/145576.17¥1,106.23
6161107.234Addax 加上中文2021/9/155584.17¥1,107.23
7171108.234Addax 加上中文2021/9/165592.17¥1,108.23
8181109.234Addax 加上中文2021/9/175600.17¥1,109.23
9191110.234Addax 加上中文2021/9/185608.17¥1,110.23
10201111.234Addax 加上中文2021/9/195616.17¥1,111.23
11211112.234Addax 加上中文2021/9/205624.17¥1,112.23
12221113.234Addax 加上中文2021/9/215632.17¥1,113.23
13231114.234Addax 加上中文2021/9/225640.17¥1,114.23
14241115.234Addax 加上中文2021/9/235648.17¥1,115.23
15251116.234Addax 加上中文2021/9/245656.17¥1,116.23
16261117.234Addax 加上中文2021/9/255664.17¥1,117.23
17271118.234Addax 加上中文2021/9/265672.17¥1,118.23
18281119.234Addax 加上中文2021/9/275680.17¥1,119.23
19291120.234Addax 加上中文2021/9/285688.17¥1,120.23
20301121.234Addax 加上中文2021/9/295696.17¥1,121.23

The table headers roughly describe the characteristics of cell data.

Create Job File ​

Create the following JSON file:

json
{
  "job": {
    "setting": {
      "speed": {
        "channel": 2,
        "bytes": -1
      }
    },
    "content": {
      "reader": {
        "name": "excelreader",
        "parameter": {
          "path": [
            "/tmp/in"
          ],
          "header": true,
          "skipRows": 0
        }
      },
      "writer": {
        "parameter": {
          "print": true
        },
        "name": "streamwriter"
      }
    }
  }
}

Save the output content to the job/excel2stream.json file and execute the collection command:

bash
$ bin/addax.sh job/excel2stream.json

If there are no errors, you should get the following output:

Details
txt
2026-09-22 10:37:24.324 [        main] INFO  Engine               - 
  ___      _     _            
 / _ \    | |   | |           
/ /_\ \ __| | __| | __ ___  __
|  _  |/ _` |/ _` |/ _` \ \/ /
| | | | (_| | (_| | (_| |>  < 
\_| |_/\__,_|\__,_|\__,_/_/\_\
:: Addax version ::    (v6.1.1-SNAPSHOT)
2026-09-22 10:37:24.451 [        main] INFO  Engine               - 
{
	"setting":{
		"speed":{
			"channel":2,
			"bytes":-1
		}
	},
	"content":{
		"reader":{
			"name":"excelreader",
			"parameter":{
				"path":[
					"/tmp/in"
				],
				"header":true,
				"skipRows":0
			}
		},
		"writer":{
			"parameter":{
				"print":true
			},
			"name":"streamwriter"
		}
	}
}

2026-09-22 10:37:24.466 [        main] INFO  JobContainer         - The jobContainer begins to process the job.
2026-09-22 10:37:24.472 [       job-0] INFO  FileHelper           - Total source files to process: 3
2026-09-22 10:37:24.472 [       job-0] INFO  ExcelReader$Job      - The number of files to read is: [3]
2026-09-22 10:37:24.473 [       job-0] INFO  JobContainer         - The Reader.Job [excelreader] perform prepare work .
2026-09-22 10:37:24.473 [       job-0] INFO  JobContainer         - The Writer.Job [streamwriter] perform prepare work .
2026-09-22 10:37:24.474 [       job-0] INFO  JobContainer         - Job set Channel-Number to 2 channel(s).
2026-09-22 10:37:24.474 [       job-0] INFO  JobContainer         - The Reader.Job [excelreader] is divided into [2] task(s).
2026-09-22 10:37:24.474 [       job-0] INFO  JobContainer         - The Writer.Job [streamwriter] is divided into [2] task(s).
2026-09-22 10:37:24.492 [       job-0] INFO  JobContainer         - The Scheduler launches [1] taskGroup(s).
2026-09-22 10:37:24.494 [ taskGroup-0] INFO  TaskGroupContainer   - The taskGroupId=[0] started [2] channels for [2] tasks.
2026-09-22 10:37:24.495 [ taskGroup-0] INFO  Channel              - The Channel set byte_speed_limit to -1, No bps activated.
2026-09-22 10:37:24.496 [ taskGroup-0] INFO  Channel              - The Channel set record_speed_limit to -1, No tps activated.
2026-09-22 10:37:24.498 [  reader-0-0] INFO  ExcelReader$Task     - The first row is skipped as a table header
2026-09-22 10:37:24.499 [  reader-0-1] INFO  ExcelReader$Task     - The first row is skipped as a table header
2026-09-22 10:37:24.499 [  reader-0-0] INFO  ExcelReader$Task     - Begin to read file /tmp/in/demo_gbk.xlsx
2026-09-22 10:37:24.499 [  reader-0-1] INFO  ExcelReader$Task     - Begin to read file /tmp/in/demo_old.xls
2026-09-22T02:37:24.526709Z reader-0-0 ERROR Log4j API could not find a logging provider.
2026-09-22 10:37:24.623 [  reader-0-1] INFO  XlsDomHelper         - Read sheet [Sheet1] of /tmp/in/demo_old.xls
2026-09-22 10:37:24.676 [  reader-0-0] INFO  XlsxStreamHelper     - Read sheet [Sheet1] of /tmp/in/demo_gbk.xlsx
2026-09-22 10:37:24.689 [  reader-0-0] INFO  ExcelReader$Task     - Begin to read file /tmp/in/demo.xlsx
2026-09-22 10:37:24.701 [  reader-0-0] INFO  XlsxStreamHelper     - Read sheet [Sheet1] of /tmp/in/demo.xlsx
1	11	1102.234	Addax加上中文	2021-09-10 00:00:00	5544.17	1102.234
1	11	1102.234	Addax加上中文	2021-09-10 00:00:00	5544.17	1102.234
1	12	1103.234	Addax加上中文	2021-09-11 00:00:00	5552.17	1103.234
2	12	1103.234	Addax加上中文	2021-09-11 00:00:00	5552.17	1103.234
1	13	1104.234	Addax加上中文	2021-09-12 00:00:00	5560.17	1104.234
3	13	1104.234	Addax加上中文	2021-09-12 00:00:00	5560.17	1104.234
1	14	1105.234	Addax加上中文	2021-09-13 00:00:00	5568.17	1105.234
4	14	1105.234	Addax加上中文	2021-09-13 00:00:00	5568.17	1105.234
1	15	1106.234	Addax加上中文	2021-09-14 00:00:00	5576.17	1106.234
5	15	1106.234	Addax加上中文	2021-09-14 00:00:00	5576.17	1106.234
1	16	1107.234	Addax加上中文	2021-09-15 00:00:00	5584.17	1107.234
6	16	1107.234	Addax加上中文	2021-09-15 00:00:00	5584.17	1107.234
1	17	1108.234	Addax加上中文	2021-09-16 00:00:00	5592.17	1108.234
7	17	1108.234	Addax加上中文	2021-09-16 00:00:00	5592.17	1108.234
1	18	1109.234	Addax加上中文	2021-09-17 00:00:00	5600.17	1109.234
8	18	1109.234	Addax加上中文	2021-09-17 00:00:00	5600.17	1109.234
1	19	1110.234	Addax加上中文	2021-09-18 00:00:00	5608.17	1110.234
9	19	1110.234	Addax加上中文	2021-09-18 00:00:00	5608.17	1110.234
1	20	1111.234	Addax加上中文	2021-09-19 00:00:00	5616.17	1111.234
10	20	1111.234	Addax加上中文	2021-09-19 00:00:00	5616.17	1111.234
1	21	1112.234	Addax加上中文	2021-09-20 00:00:00	5624.17	1112.234
11	21	1112.234	Addax加上中文	2021-09-20 00:00:00	5624.17	1112.234
1	22	1113.234	Addax加上中文	2021-09-21 00:00:00	5632.17	1113.234
12	22	1113.234	Addax加上中文	2021-09-21 00:00:00	5632.17	1113.234
1	23	1114.234	Addax加上中文	2021-09-22 00:00:00	5640.17	1114.234
13	23	1114.234	Addax加上中文	2021-09-22 00:00:00	5640.17	1114.234
1	24	1115.234	Addax加上中文	2021-09-23 00:00:00	5648.17	1115.234
14	24	1115.234	Addax加上中文	2021-09-23 00:00:00	5648.17	1115.234
1	25	1116.234	Addax加上中文	2021-09-24 00:00:00	5656.17	1116.234
15	25	1116.234	Addax加上中文	2021-09-24 00:00:00	5656.17	1116.234
1	26	1117.234	Addax加上中文	2021-09-25 00:00:00	5664.17	1117.234
16	26	1117.234	Addax加上中文	2021-09-25 00:00:00	5664.17	1117.234
1	27	1118.234	Addax加上中文	2021-09-26 00:00:00	5672.17	1118.234
17	27	1118.234	Addax加上中文	2021-09-26 00:00:00	5672.17	1118.234
1	28	1119.234	Addax加上中文	2021-09-27 00:00:00	5680.17	1119.234
18	28	1119.234	Addax加上中文	2021-09-27 00:00:00	5680.17	1119.234
1	29	1120.234	Addax加上中文	2021-09-28 00:00:00	5688.17	1120.234
19	29	1120.234	Addax加上中文	2021-09-28 00:00:00	5688.17	1120.234
1	30	1121.234	Addax加上中文	2021-09-29 00:00:00	5696.17	1121.234
20	30	1121.234	Addax加上中文	2021-09-29 00:00:00	5696.17	1121.234
1	11	1102.234	Addax加上中文	2021-09-10 00:00:00	5544.17	1102.234
2	12	1103.234	Addax加上中文	2021-09-11 00:00:00	5552.17	1103.234
3	13	1104.234	Addax加上中文	2021-09-12 00:00:00	5560.17	1104.234
4	14	1105.234	Addax加上中文	2021-09-13 00:00:00	5568.17	1105.234
5	15	1106.234	Addax加上中文	2021-09-14 00:00:00	5576.17	1106.234
6	16	1107.234	Addax加上中文	2021-09-15 00:00:00	5584.17	1107.234
7	17	1108.234	Addax加上中文	2021-09-16 00:00:00	5592.17	1108.234
8	18	1109.234	Addax加上中文	2021-09-17 00:00:00	5600.17	1109.234
9	19	1110.234	Addax加上中文	2021-09-18 00:00:00	5608.17	1110.234
10	20	1111.234	Addax加上中文	2021-09-19 00:00:00	5616.17	1111.234
11	21	1112.234	Addax加上中文	2021-09-20 00:00:00	5624.17	1112.234
12	22	1113.234	Addax加上中文	2021-09-21 00:00:00	5632.17	1113.234
13	23	1114.234	Addax加上中文	2021-09-22 00:00:00	5640.17	1114.234
14	24	1115.234	Addax加上中文	2021-09-23 00:00:00	5648.17	1115.234
15	25	1116.234	Addax加上中文	2021-09-24 00:00:00	5656.17	1116.234
16	26	1117.234	Addax加上中文	2021-09-25 00:00:00	5664.17	1117.234
17	27	1118.234	Addax加上中文	2021-09-26 00:00:00	5672.17	1118.234
18	28	1119.234	Addax加上中文	2021-09-27 00:00:00	5680.17	1119.234
19	29	1120.234	Addax加上中文	2021-09-28 00:00:00	5688.17	1120.234
20	30	1121.234	Addax加上中文	2021-09-29 00:00:00	5696.17	1121.234
2026-09-22 10:37:27.497 [       job-0] INFO  AbstractScheduler    - The scheduler has completed all tasks.
2026-09-22 10:37:27.499 [       job-0] INFO  JobContainer         - The Writer.Job [streamwriter] perform post work.
2026-09-22 10:37:27.499 [       job-0] INFO  JobContainer         - The Reader.Job [excelreader] perform post work.
2026-09-22 10:37:27.511 [       job-0] INFO  StandAloneJobContainerCommunicator - Total 60 records, 3360 bytes | Speed 1.09KB/s, 20 records/s | Error 0 records, 0 bytes |  All Task WaitWriterTime 0.000s |  All Task WaitReaderTime 0.346s | Percentage 100.00%
2026-09-22 10:37:27.514 [       job-0] INFO  JobContainer         - 
Job start  at             : 2026-09-22 10:37:24
Job end    at             : 2026-09-22 10:37:27
Job took secs             :                  3s
Total   bytes             :                3360
Average   bps             :            1.09KB/s
Average   rps             :             20rec/s
Number of rec             :                  60
Failed record             :                   0

Parameters ​

ConfigurationRequiredTypeDefault ValueDescription
pathYesstring/listNoneSpecify the folder to read, multiple can be specified
headerNobooleanfalseWhether the file contains headers
skipRowsNoint0How many rows to skip at the beginning
sheetIndexNoint0Index of the sheet to read, counted from 0
sheetNameNostringNoneName of the sheet to read, not together with sheetIndex
trimNobooleantrueWhether to trim whitespace around text cells

Whether the Excel file contains headers, if so, skip them.

skipRows ​

Specify the number of rows to skip, default is 0, meaning no skipping. Note that if header is set to true and skipRows is set to 2, it means the first three rows are all skipped. If header is false, it means skipping the first two rows.

sheetIndex / sheetName ​

Only the first sheet is read by default. sheetIndex counts from 0 and sheetName selects by name; do not set both. When a workbook holds several sheets and the job names none of them, the plugin logs a warning saying which sheet it read.

trim ​

Whether to remove the whitespace around the text of a cell, true by default. Text in Excel often carries spaces that cannot be seen; set it to false to keep the text as it is stored.

The trimming follows Unicode whitespace; a non breaking space (U+00A0) is a character rather than whitespace and survives either setting.

Empty cells and formulas ​

  • A cell without a value — blank, an empty string, an error (#DIV/0! and friends) or one that was skipped — is read as NULL, never as an empty string
  • Every record is padded to the widest row with NULL, so a cell never lands in the wrong column
  • A formula cell is read as the result Excel stored in the file. A file written by a library (openpyxl, POI) that stores no result reads the formula column as NULL and logs a warning; opening and saving the file in Excel fills it in
  • The column count comes from the header row (with header: true) or the first data row; a later row that is wider is written with its own column count and reported once

Supported Data Types ​

The Excel reading functionality implementation depends on the Apache POI project, which has a very broad definition of cell data types. It only defines three types: Boolean, Double (numeric), and String. Among them, numeric type includes all integers, decimals, and dates. Currently, simple distinction is made for numeric types:

  1. Use library utility classes to detect if it's a date type, if so, determine it as date type
  2. Convert the numeric value to long integer and compare with the original value, if equal, determine as Long type
  3. Otherwise determine as Double type

Memory ​

An xlsx file is read as a stream that holds one row at a time, so the memory it needs does not grow with the file. An xls file is loaded at once, which is affordable because the format itself stops at 65536 rows.

Limitations ​

  1. Does not support specifying column reading
  2. Does not support skipping trailing rows (for example, summary tail rows may not meet requirements)
  3. Encrypted (password protected) workbooks are not supported and fail with an error
  4. Files in the directory are recognized by their content (the ZIP and OLE2 magics); a file that is not a workbook is skipped with a warning, and a workbook whose extension is wrong is still read