Structured File
On this page
Purpose
Structured File loads exactly one CSV, Excel, Parquet, JSON, or YAML file. It keeps tabular files as real columns and keeps JSON or YAML as nested structured data.
Use it for one dataset or configuration-style payload. Use Knowledge Base - Files when you need multi-file document ingestion and retrieval.
When to use it
- Filter, sort, or rename columns from a CSV, Excel, or Parquet file.
- Read nested JSON or YAML without flattening it into text.
- Send tabular rows to a Data consumer as
{"rows": [...]}.
Required setup
Supported file types are csv, xls, xlsx, parquet, json, yaml, and yml. Select one file only.
Structured File loads the full file into memory and does not redact values. Use approved, de-identified data when records are sensitive.
How to use it
- Select one supported file.
- Keep Tables for CSV, Excel, or Parquet, then connect it to DataFrame Operations.
- Keep Structured Data for JSON or YAML, then connect it to Data Operations.
- Run Test and inspect the rows or nested object before adding a model or a side effect.
For example, use Tables for a CSV that needs column filtering. Use Structured Data for a YAML configuration that must keep nested objects.
The selected extension chooses the active output for you. Both output ports remain available.
Configuration
| Setting | What it controls | Recommended starting point |
|---|---|---|
| File | The single file to load | Select one supported file |
| Server File Path | An existing server-side file that overrides File | Leave empty unless an upstream step saved the file |
| Delete Server File After Processing | Deletes a Server File Path during cleanup | Keep it on for disposable files |
| Active output | The representation sent downstream | Keep the extension-selected output unless the next component needs another type |
Tabular files use Tables by default. JSON and YAML use Structured Data by default. Wiring JSON or YAML to Tables raises a clear error telling you to use Structured Data.
Expected result
Tables returns a DataFrame with real file columns. Structured Data preserves a JSON or YAML object, wraps a top-level list or scalar under data, and wraps tabular records under rows.
The public outputs omit the source path. A Server File Path is deleted after processing by default. For deployments, use Builder-managed hosted files owned by the deployment owner.
Reference details
Use Server File Path only for one existing server file. It is list-capable upstream, but Structured File rejects multiple resolved files.
You can use Structured Data for a tabular file when a downstream component needs Data instead of a DataFrame.
DataFrame Operations works with Tables output. Data Operations works with Structured Data output.