Skip to content
Zoan Docs

Read Excel Range

Read Excel Range

Section titled “Read Excel Range”

Type: excel-read-range  ·  Package: Excel Activities v1.0.6  ·  Output: DataTable

Reads a range of cells and returns it as a DataTable (tabular data is always a DataTable). Useful when you want to read a specific portion of the sheet: unlike Read Excel Sheet — which reads the whole used range — here you set the exact range.

By default the first row is treated as headers. If your range has none, set hasHeader = false and the columns are named automatically (Col1, Col2…).

How it works

Section titled “How it works”

It reads the cells of the given range and builds a DataTable of exactly that size: if the range includes empty rows or columns, they appear in the table (as DBNull). If hasHeader is true (the default), the first row provides the column names; if false, columns are named automatically. Accepts session or path — see the two modes.

Read-only: in fast mode it does not modify the file.

Required parameters

Section titled “Required parameters”
ParameterTypeDefaultDescription
rangestring—Range address, e.g. "A1:D20". Avoid whole columns ("A:D"): they span over a million rows.

Optional parameters

Section titled “Optional parameters”
ParameterTypeDefaultDescription
sessionZoanExcelSession—Excel Open session (instead of path).
pathstring—Path to the .xlsx (required if there is no session). The file must exist.
sheetstring | int—Sheet name or 1-based index. If omitted, the first sheet.
hasHeaderbooltrueTreat the first row of the range as headers. With false, columns are named Col1, Col2…

Output

Section titled “Output”

Returns a DataTable with the same shape as Read Excel Sheet:

  • Columns: the text of the range’s first row (an empty header is named Col<n> after its position), or Col1, Col2… with hasHeader = false.
  • Values: each cell keeps its type (since version 1.0.6): number, date, boolean or text; empty cells are DBNull. See how the data arrives.
  • A range with no data returns the range’s rows and columns, all DBNull.

Common errors

Section titled “Common errors”
MessageCause and fix
'range' is required.range is missing.
'session' or 'path' is required.Neither session nor path is set.
File not found.path does not exist. Validate first with File Exists.
'…' is not A1 address or named range.range is not a valid address. Use the form "A1:D20".
There isn't a worksheet named '…'.No sheet has that name.
There isn't a worksheet associated with that position.The sheet index does not exist (or the name is just a number and was taken as an index).
A column named '…' already belongs to this DataTable.Two headers in the range have the same name. Read with hasHeader = false or adjust the range.

Example

Section titled “Example”
Read Excel Range   path = asset("data.xlsx")   range = "A1:C50"   → output: table
Log   message = "Rows read: " + str(rowCount(table))


For Each   items = table   itemVariable = row
 └─ activities:
      Log   message = str(row["Customer"]) + " — " + str(row["Total"])

Read a block without headers (for example, the totals of a template):

Read Excel Range   path = asset("template.xlsx")   range = "F2:G6"   hasHeader = false   → output: totals


For Each   items = totals   itemVariable = row
 └─ activities:
      Log   message = str(row["Col1"]) + ": " + str(row["Col2"])
Section titled “Related activities”