Cheat sheet

Everything starts from a nominal.Client, and each object hands you the next.

Client

c = nominal.Client.fromProfile()

Action	MATLAB
Connect from a stored profile	nominal.Client.fromProfile()
Connect with an API key	nominal.Client.fromToken("<api-key>")
Either, whichever is available	nominal.Client.connect()
Who am I (also a credential check)	c.whoAmI()
Search assets by name	c.assets("<search text>")
Search datasets by name	c.datasets("<search text>")
Search runs	c.runs("<search text>", Labels=…, Properties=…, StartAfter=t0)
List every asset (slow, unpaginated)	c.assets()
List every dataset (slow, unpaginated)	c.datasets()
Get an asset by RID	c.assetByRid(rid)
Get an asset by name, creating if absent	c.getOrCreateAsset(name)
Create an asset, even if the name exists	c.createAsset(name)
Get a dataset by RID	c.datasetByRid(rid)
Create a dataset attached to no asset	c.createDataset(name)
Get a run by RID	c.runByRid(rid)
Create a run from tagged data, no asset	c.createRun(name, ds, Tags=…, StartTime=…, EndTime=…)
Create an event	c.createEvent(assetRids, name)
…with properties	c.createEvent(rids, name, Properties=struct(status="pass"))
Upload and ingest a CSV or Parquet file	c.ingest(path, TimestampColumn=…)
…tagging every point in it	c.ingest(path, …, Tags=struct(UUT="A"))
Run a SQL query	c.query(sql)
SQL result too big for memory	c.queryExportUrl(sql)
Workspace / base URL	c.WorkspaceRid, c.BaseUrl

Asset

a = c.getOrCreateAsset("<asset name>")

Action	MATLAB
Identity and metadata	a.Rid, a.Name, a.Description, a.Url, a.Labels
Read one property	a.property("<key>")
All properties, as a containers.Map	a.Properties
Set or remove one, keeping the rest	a = a.setProperty("<key>", "<value>"), a.removeProperty("<key>")
Everything attached to it, with tag filters	a.datasources()
…re-read from Nominal	a.datasources(Refresh=true)
Read a channel as the asset sees it	a.fetch("<channel>", t0, t1), a.fetch(…, RefName="<ref name>")
A dataset already on it, by name	a.getAttachedDataset(name)
Attach a dataset you already have	a.addDataset(ds), a.addDataset(ds, "<ref name>")
…only the series with these tags	a.addDataset(ds, Tags=struct(UUT="A"))
…a tag key that isn’t a field name	a.addDataset(ds, Tags=dictionary("test-stand", "3"))
Rename a reference name	a.renameRefName("<old>", "<new>")
Detach a data source	a.removeDataset("<ref name>")
Ensure it has a dataset of that name	a.getOrCreateDataset(name)
…without adopting an existing one	a.getOrCreateDataset(name, AttachExisting=false)
Start a run on it	a.run(name), a.run(name, startTime)
Change metadata	a.update(Name=…, Description=…, Labels=…, Properties=…)

An asset object is a snapshot taken when it was fetched. update() returns a new object instead of changing the one you have. datasources() asks Nominal once and reuses the answer until you pass Refresh=true.

Dataset names are not unique in Nominal, so getOrCreateDataset resolves in three steps and prints which one it took:

1. A dataset of that name already on the asset is returned.

2. Otherwise a dataset of that exact name elsewhere in the workspace is attached to the asset and returned.

3. Otherwise one is created.

Step 2 is how “the dataset for serial 12345678” finds the one a colleague already made. Because it changes your asset based on a name match, you can turn it off with AttachExisting=false. If several datasets share the name, it errors and lists their RIDs. Attach the one you meant with a.addDataset(c.datasetByRid(rid)).

refName is the dataset’s name within the asset. It is only used when attaching, and you can leave it out: a free one is chosen ("default" on an asset with none, otherwise the dataset’s own name). Supply one when an asset has two sources measuring the same thing, such as a CAN log and a test rig both reporting engine temp, and you want to tell them apart.

An asset holds a dataset once per tag filter. Attaching the same dataset again with the same Tags moves it to the new refName. Attaching it with different Tags adds it alongside.

Dataset

ds = a.getOrCreateDataset("<dataset name>")

Action	MATLAB
Identity and metadata	ds.Rid, ds.Name, ds.Description, ds.Labels
Read one property	ds.property("<key>")
All properties, as a containers.Map	ds.Properties
Set or remove one, keeping the rest	ds = ds.setProperty("<key>", "<value>"), ds.removeProperty("<key>")
What channels are in it	ds.channels()
Which assets hold it	ds.assets()
Open a live stream	ds.stream()
Write a block already in memory	ds.write(channels, t, V)
…tagging every point	ds.write(channels, t, V, Tags=struct(UUT="A"))
Read one channel back	ds.fetch("<channel>", t0, t1)
Read it decimated, for plotting	ds.fetch("<channel>", t0, t1, Buckets=2000)
…one tag set, when it has several	ds.fetch("<channel>", t0, t1, Tags=struct(UUT="A"))
Export channels to a file	ds.export("out.mat", channels, t0, t1)
Export to a download link instead	ds.exportUrl(channels, t0, t1)
Read one channel’s units	ds.channelMetadata("<channel>")
Declare a channel’s units	ds.setChannelMetadata("rpm", "double", Unit="1/min")
Change metadata	ds.update(Name=…, Labels=…, Properties=…)

Run

r = a.run("burn-12")

Action	MATLAB
Identity and metadata	r.Rid, r.Name, r.Description, r.Url, r.Number, r.Labels
Timing	r.StartTime, r.EndTime
Assets it belongs to	r.AssetRids
Put it on another asset too	r = r.addAsset(dut)
Take it off one	r = r.removeAsset(dut)
Read one property	r.property("<key>")
All properties, as a containers.Map	r.Properties
Set or remove one, keeping the rest	r = r.setProperty("<key>", "<value>"), r.removeProperty("<key>")
Close it	r.finish(), r.finish(endTime)
Read a channel over the run’s window	r.fetch("<channel>"), r.fetch("<channel>", RefName="<ref name>")
Change metadata	r.update(Name=…, Labels=…, Properties=…)

Stream and Channel

s = ds.stream()

Action	MATLAB
Get a write address for a channel	s.channel("rpm")
Push an N-by-C block across channels	s.push(channels, t, V)
Push one channel	ch.push(t, v)
Tag every later point on an address	ch.tag("bank", "1")
Flush and close	delete(s)

Event

e = c.createEvent(rids, "overspeed")

Action	MATLAB
Read it back	e.Rid, e.Name, e.Type, e.Timestamp, e.Duration, e.AssetRids
Read one property	e.property("<key>")
All properties, as a containers.Map	e.Properties

IngestJob

job = c.ingest("<file>.csv", …)

Action	MATLAB
Where the data is landing	job.DatasetRid
Check progress	job.status()
Block until it finishes	job.wait()

Free functions

Action	MATLAB
Current time, full nanosecond precision	nominal.now()
datetime → int64 nanoseconds	nominal.toNanos(dt), nominal.toNanosVector(dt)
int64 nanoseconds → UTC datetime	nominal.fromNanos(nanos)
Shut the toolbox down, closing every connection	nominal.shutdown()