---

name: matlab-choose-big-data-solution description: > Guide users or agents to the correct MATLAB tool for processing large tabular data in file-based formats (CSV, Parquet, delimited text, spreadsheets, MDF) that may not fit in memory. Use when a user or agent mentions large files, big data, out-of-memory errors, OOM, scaling up, tall arrays, datastores, or needs to process multiple tabular files. Covers the decision between datastore + tall, datastore + transform, and parallel execution. Also use when a user or agent has working in-memory code (readtable, parquetread) that runs out of memory and needs a migration path. Also covers building custom datastore classes for proprietary or non-standard formats — use when the task requires subclassing matlab.io.Datastore, implementing a custom reader, building an extensible datastore, or integrating a new file format with tall arrays or parallel computing. Do NOT use for MAT files (use matfile instead). license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "2.0"

Choose Big Data Solution

Help users and agents select the right MATLAB tool for large tabular data in file-based formats (CSV, Parquet, delimited text, spreadsheets, MDF). The skill encodes a decision flowchart — recommend one clear path, not a menu of options.

When to Use

• User or agent has large tabular data in file-based formats (CSV, Parquet, delimited text, spreadsheets, MDF)
• User or agent says data is "large", "big", or "huge" (even without a specific size)
• User or agent hits an out-of-memory error with readtable, parquetread, or similar
• User or agent has multiple tabular files to process as a single dataset
• User or agent has multiple tabular files to process independently (per-file)
• User or agent asks how to scale up an existing workflow on tabular file data
• User or agent asks about datastores, tall arrays, or mapreduce
• User or agent needs to build a custom datastore class for a proprietary or non-standard format
• User or agent has large XML, JSON, HTML, or Word document files — readtable supports these formats but the built-in datastores do not. Scaling these requires a custom datastore (see "Formats Without a Built-in Datastore" and "Custom Datastores" sections below)

When NOT to Use

• Single file that fits in memory (file-size-to-RAM ratio < 0.5) — see Pre-Flight Check and matlab-import-export-data skill
• User or agent is working with MAT files — matfile provides partial I/O for large .mat files, different workflow
• User or agent is working with databases (SQL, ODBC) — use Database Toolbox. See the matlab-use-database and matlab-use-duckdb skills in the reporting-and-database-access category
• User or agent needs GPU acceleration — different domain
• Deep learning training workflows — datastore is correct for data loading, but use minibatchqueue for batching (not tall or transform)

Pre-Flight Check

ALWAYS run this check BEFORE recommending datastore or tall array patterns. Estimate the file-size-to-available-RAM ratio (accounting for in-memory expansion of the file format).

| Condition | Route | Rationale | |-----------|-------|-----------| | Single file, ratio < 0.5 | Native MATLAB I/O (readtable, parquetread) | Fits in memory; datastore/tall adds unnecessary complexity | | Single file, ratio ≥ 0.5, OR user/agent reports OOM | Continue to Decision Flowchart below | Data may not fit in memory | | Multiple files | Continue to Decision Flowchart below | Datastore patterns provide unified multi-file access | | Size unknown and user/agent describes data as "large", "big", or "huge" | Continue to Decision Flowchart below | Assume large until proven otherwise |

If the data fits in memory (single file, ratio < 0.5): recommend native I/O and stop. Mention that datastore and tall array patterns exist if the data grows beyond memory in the future, but do not implement them now.

Decision Flowchart

Follow this flowchart strictly. Present ONE recommended path, not multiple alternatives. Only mention alternatives if the situation is ambiguous.

Is the data described as "large" or causing OOM?
│
├── YES
│   │
│   ├── Is the goal to process all data as ONE continuous dataset?
│   │   │
│   │   └── YES → Datastore + Tall Arrays
│   │             Choose datastore by format:
│   │               CSV/delimited text → tabularTextDatastore
│   │               Parquet            → parquetDatastore
│   │               Excel (.xlsx/.xls) → spreadsheetDatastore
│   │               MDF (.mf4/.mdf)    → mdfDatastore (requires Vehicle Network Toolbox)
│   │               Other formats      → Custom Datastore
│   │
│   └── Is the goal to process each unit INDEPENDENTLY?
│       │
│       ├── One read = one FILE
│       │     CSV/delimited text → tabularTextDatastore
│       │     Excel (.xlsx/.xls) → spreadsheetDatastore
│       │     Other formats      → Custom Datastore or fileDatastore
│       │
│       └── One read = one ROW GROUP
│             Parquet → parquetDatastore
│
└── NO / UNCLEAR
    └── STOP. Ask: (1) what is the file format? (2) do you need to process
        all data as one dataset, or each file/unit independently?
        Do NOT show code until these are answered.

Optional (requires Parallel Computing Toolbox):
├── Speed up tall arrays locally → Open a parallel pool
├── Speed up readall on transforms → UseParallel
└── Speed up tall arrays on Hadoop/Spark → mapreducer (also requires MATLAB Parallel Server)

Critical rules:

• When the processing goal is unclear (continuous vs per-file), STOP and ask before writing any code. Do not show code examples, do not generate scripts, do not demonstrate both approaches. Ask which applies and wait for the answer. The correct response to ambiguity is a short clarifying question, not a menu of options with code for each.
• When data is described as "large", NEVER lead with readtable or parquetread
• For per-file or per-row-group processing, NEVER suggest tall arrays (tall merges all data into one dataset and has no concept of file or row group boundaries)
• For Parquet, the natural independent unit is the row group, not the file — parquetDatastore defaults to ReadSize = "rowgroup". Do NOT force ReadSize = "file" on a Parquet datastore unless the workflow truly needs whole-file granularity
• For parallelism, recommend parallel pool FIRST; mapreducer is only for Hadoop/Spark
• Do NOT present manual chunking (while/read loops) as the first option — tall arrays handle chunking automatically
• Do NOT present multiple options — follow the flowchart and recommend ONE clear path

Datastore + Tall Arrays (continuous dataset)

Use when: processing one large file OR multiple files as a single dataset. Use the datastore matching the format (see Decision Flowchart above).

% Single file
ds = tabularTextDatastore("largedata.csv");
tt = tall(ds);

% Multiple files
ds = tabularTextDatastore("data/*.csv");
tt = tall(ds);

% For example, compute statistics with the tall array and gather results.
% Tall handles chunking automatically. Specify DataVars to avoid errors
% on non-numeric columns.
result = groupsummary(tt, "GroupVar", {"mean", "std"}, "NumericVar");
result = gather(result);

Key points:

• Most common functions work on tall: mean, std, min, max, groupsummary, sortrows, topkrows
• Combine multiple gathers: [a, b] = gather(tallA, tallB)

DuckDB alternative (R2026a+): When the goal is to filter, aggregate, deduplicate, or sample a large file down to a small in-memory result, a single DuckDB query may be faster than datastore + tall. DuckDB queries CSV/Parquet/JSON files directly without loading them into memory. Requires Database Toolbox.

conn = duckdb();
result = fetch(conn, "SELECT * FROM read_csv_auto('large.csv') WHERE Region = 'West'");
close(conn);

For complex DuckDB workflows, see the matlab-use-duckdb skill in the reporting-and-database-access category.

Migrating from readtable (OOM on large files):

% Before:
T = readtable("large.csv");
stats = groupsummary(T, "Category", "mean");

% After:
ds = tabularTextDatastore("large.csv");
tt = tall(ds);
stats = gather(groupsummary(tt, "Category", "mean"));

tabularTextDatastore uses a stricter textscan-based parser. Key gotchas:

• TextType must be set at creation time — read-only after construction
• TrimNonNumeric unsupported — read as %q, strip on the tall array
• %f errors on non-numeric content — read as %q, convert with str2double
• ExtraColumnsRule does not exist — append "%*[^\r\n]" to TextscanFormats
• detectImportOptions does not apply — configure via datastore properties directly

See references/readtable-to-datastore-migration.md for the full property mapping.

Migrating from parquetread: Replace with parquetDatastore + tall. Types are preserved exactly — no format specifier issues. All parquetread options map 1:1 to datastore properties. See references/parquetread-to-datastore-migration.md.

Datastore + Transform (per-file)

Use when: each file in a folder should be processed independently (per-file statistics, per-file transformations, file-level aggregation).

% Set up datastore to read one file at a time
ds = tabularTextDatastore("data/*.csv");
ds.ReadSize = "file";

% For example, compute statistics by transforming the datastore with a custom function.
tds = transform(ds, @computeFileStats);
results = readall(tds);

function out = computeFileStats(data)
    numVars = vartype("numeric");
    out = table( ...
        min(data{:, numVars}, [], 1, "omitmissing"), ...
        max(data{:, numVars}, [], 1, "omitmissing"), ...
        mean(data{:, numVars}, 1, "omitmissing"), ...
        VariableNames=["Min", "Max", "Mean"]);
end

For Excel files, use spreadsheetDatastore instead of tabularTextDatastore. spreadsheetDatastore defaults to ReadSize = "file" so no override is needed. For per-sheet processing (e.g., statistics per worksheet), set ReadSize = "sheet" so each read returns exactly one sheet's data.

Key points:

• For tabularTextDatastore, set ReadSize = "file" so each read returns exactly one file's data. The default ReadSize is a row count, which can split a single file across multiple reads but it will not go across file boundaries
• transform applies a function to each read — the datastore output contains only the transformed results, not the original data. The transform function does not need to return the same number of rows as its input (e.g., computing the mean of each variable produces a single row per read)
• readall on the transformed datastore collects all per-file results
• Use "omitmissing" for missing-data flags (R2023a+). On R2022b and earlier, use "omitnan" instead.

Do NOT use tall arrays for per-file processing. Tall arrays treat all files as one continuous dataset — they have no concept of file boundaries.

Datastore + Transform (per-row-group, Parquet)

Use when: a Parquet dataset is partitioned by row group (e.g., one row group per item, sensor, region, or time bucket) and each row group must be processed independently. Row groups are the natural unit of independence in Parquet — data from different row groups should not be mixed when the partitioning encodes a meaningful grouping.

% parquetDatastore defaults ReadSize to "rowgroup" — one read = one row group.
% Do NOT set ReadSize = "file": that would mix row groups within the same file.
pds = parquetDatastore("data/");

% For example, compute statistics by transforming the datastore with a custom function.
tds = transform(pds, @computeRowGroupStats);
results = readall(tds);

function out = computeRowGroupStats(data)
    out = table( ...
        unique(data.item), ...
        mean(data.val, "omitmissi