File - XLSX Read

Type identifier: file:xlsx:read Category: File Operations

Description

The File - XLSX Read node reads spreadsheet files (XLSX, CSV, TSV) with configurable parsing options and extracts data as an array of records. Each row becomes an object matching the configured Schema, with columns mapped to properties.

Input Handles

Handle	Type	Description
`file`	`file` (xlsx, csv, tsv)	The spreadsheet file to read.
`skipEmptyLines`	`boolean`	(Dynamic) Whether to skip empty lines.
`sheetName`	`string`	(Dynamic, XLSX only) Name of the sheet to read.
`range`	`string`	(Dynamic, XLSX only) Cell range to read (for example, "A1:D10").
`skipHidden`	`boolean`	(Dynamic, XLSX only) Whether to skip hidden rows.
`header`	`boolean`	(Dynamic, CSV/TSV only) Whether first row is header.
`delimiter`	`string`	(Dynamic, CSV only) Field delimiter character.

Note: Dynamic input handles only appear when the corresponding option is set to dynamic mode.

Output Handles

Handle	Type	Description
`data`	`array`	Array of records matching the configured Schema.
`sheetName`	`string`	(XLSX only) Name of the sheet that was read.

Configuration Options

Common Options

Option	Type	Default	Description
File Format	`"xlsx"` \| `"csv"` \| `"tsv"`	`"xlsx"`	Format of the input file.
Skip Empty Lines	`boolean` or dynamic	`true`	Skip rows where all cells are empty.
Date Format	`string`	-	Format string for parsing date values.
Schema	Schema config	-	Schema defining the structure of each row.

XLSX-Specific Options

Option	Type	Default	Description
Sheet Name	`string` or dynamic	-	Name of the sheet to read (first sheet if omitted).
Range	`string` or dynamic	-	Cell range to read (for example, "A1:D10", entire sheet if omitted).
Skip Hidden	`boolean` or dynamic	`false`	Skip rows hidden in the spreadsheet.

CSV/TSV-Specific Options

Option	Type	Default	Description
Header	`boolean` or dynamic	`true`	Treat first row as column headers.
Delimiter	`string` or dynamic	`","`	(CSV only) Field delimiter character.

Behaviour

Receives a spreadsheet file from the input handle
Validates file belongs to the current Space
Detects format (XLSX, CSV, or TSV) and applies format-specific parsing:
- XLSX: Supports sheets and ranges
- CSV/TSV: Delimiter-separated values
Maps columns to Schema properties based on headers
Validates and converts each row against the Schema
Returns array of validated records

Dynamic Options

Options can be configured as:

Literal: Fixed value set in the node configuration
Dynamic: Value provided via input handle at runtime

Date Handling

Date values in spreadsheets are parsed according to the configured date format or Excel's internal date system for XLSX files.

Examples

Read Customer Data from XLSX

Configuration:

Format: XLSX
Sheet Name: "Customers"

Schema:

{
  type: "object",
  properties: {
    name: { type: "string" },
    email: { type: "string" },
    created: { type: "date" }
  }
}

Output (data):

[
  { "name": "Alice", "email": "alice@example.com", "created": "2024-01-15" },
  { "name": "Bob", "email": "bob@example.com", "created": "2024-01-16" }
]