> For the complete documentation index, see [llms.txt](https://docs.marpledata.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.marpledata.com/docs/sdk/overview/matlab-sdk.md).

# MATLAB SDK

<figure><img src="/files/bvGCIiB0aaHdFFEzQLEH" alt=""><figcaption><p>MATLAB allows for complex custom analysis on data that is stored in Marple DB</p></figcaption></figure>

### Installation

1. Get the latest `matlab/` folder from the [Marple SDK repository](https://github.com/marpledata/marple-sdk/tree/main/matlab) (or pin a release tag `matlab-v*`).
2. Add that folder to your MATLAB path:

```matlab
addpath(genpath('/path/to/marple-sdk/matlab'));
```

3. Create `config.json` in the same directory as `DB.m`:

```json
{
    // might be a different URL if you have self-hosted or VPC Marple
    "api_url": "https://db.marpledata.com/api/v1",
    "api_key": "<your-api-token-here>",
    "workspace": "<name of your workspace>"
}
```

4. Create the client:

```matlab
mdb = DB.from_config();
% or: mdb = DB(api_url, api_key);
```

You can use [MATLAB Online](https://matlab.mathworks.com/) for testing (free tier available).

### Usage

```matlab
mdb = DB.from_config();

% list streams (always a cell array)
mdb.get_streams()

% list datasets in a stream (includes metadata)
mdb.get_datasets('flight data')

% download a signal as a table (time in nanoseconds)
mdb.get_data('2025-11-04-cessna-looping-test.tdms', 'altitude')
```

`get_data` returns a MATLAB table with a `time` column and a column named after the signal. Time is nanoseconds (UTC when the source used datetimes).

#### Upload a file and wait for import

```matlab
dataset = mdb.push_file('flight data', 'run.csv', Metadata=struct('pilot', 'Ada'));
mdb.wait_for_import('flight data', dataset.id, Timeout=60);
T = mdb.get_data(dataset.path, 'altitude');
```

Use `Overwrite=true` to replace an existing dataset with the same name. For MATLAB `.mat` files, create a files stream with `Plugin="mat"`.

<div align="left"><figure><img src="/files/RLAP2xrEcYqFXaTDzy1y" alt=""><figcaption><p>Example output from mdb.get_data()</p></figcaption></figure></div>

#### Add signals (custom ingest)

```matlab
ds = mdb.add_dataset('flight data', 'custom-run');
% table with int64 ns time + value and/or value_text, or a timetable
mdb.add_signal('flight data', ds.id, 'altitude', my_table, Overwrite=false);
```

Upload returns after the API accepts completion; the Iceberg commit may still be running, so the signal may not be readable immediately.

#### Other helpers

* `create_stream(name, ...)` — create a stream (`Type`, `Plugin`, `PluginArgs`, …)
* `get_signals(stream_name, dataset_id)` — list signals
* `update_metadata(stream_name, dataset_id, metadata)` — merge dataset metadata
* `clear_cache()` — delete the local parquet cache
* `health()` — API health check

See `DB.m` and `matlab/example.m` in the repository for the full surface. Version history: `matlab/CHANGELOG.md`.

### Resampling / combining signals

Combine tables with built-in MATLAB functions, for example:

```matlab
data = mdb.get_data('2025-11-04-cessna-looping-test.tdms', 'altitude');

t1 = datetime(data.time/1e9, 'ConvertFrom', 'posixtime', 'TimeZone', 'UTC');
TT = table2timetable(table(t1, data.altitude, 'VariableNames', {'time', 'altitude'}), 'RowTimes', 'time');
TT_altitude = retime(TT, 'regular', 'nearest', 'TimeStep', seconds(2));

TT_all_data = synchronize(TT_altitude, TT_speed, TT_battery, 'union', 'nearest');
```

### Caching

Downloaded parquet files are cached under, call `mdb.clear_cache()` to remove the folder

```
_marplecache/<workspace>/<datapool>/dataset=<id>/signal=<id>/
```

### Compatibility (older MATLAB)

MATLAB older than R2023a cannot read ZSTD-compressed Parquet. On first use the SDK downloads a small `parquet-transcode` helper into `matlab/_marplecache/` (Windows x64, macOS ARM, Linux x64). The same helper is used when uploading via `add_signal`.

## Discover the MATLAB SDK in 1 minute

{% embed url="<https://youtu.be/trH-LmBoTLY>" %}

Want to discover more Marple features in 1 minute? Check out other [1 Minute Marple videos](/docs/other-resources/1-minute-marple-videos.md)