# Datasets

A [dataset](https://dev.nominal.io/platform/data-model.md#data-model-dataset) holds your test data as [channels](https://dev.nominal.io/rust-client/guides/channels.md), such as `altitude` or `temperature`.

To decide whether each unit you test gets its own dataset or units share one, review [Organize and view your data](https://dev.nominal.io/platform/data-model/paradigms.md).

To use this page, first make sure you can [Connect to Nominal](https://dev.nominal.io/rust-client/guides/connect.md) and obtain a `client`.

## Create a dataset

```rust
use nominal::core::DatasetCreate;

let dataset = client
    .catalog()
    .create_dataset(
        DatasetCreate::new("Flight telemetry")
            .description("Quadcopter 456 flight logs")
            .labels(["flight-test"])
            .channel_delimiter("."), // show motor.temperature and motor.current in a tree, under motor
    )
    .await?;
println!("{}", dataset.nominal_url());
```

[`create_dataset`](https://dev.nominal.io/rust-client/ref/rust/nominal/core/struct.CatalogClient.md#method.create_dataset "nominal::core::CatalogClient::create_dataset") always makes a new dataset. [Fetch the dataset](https://dev.nominal.io/rust-client/guides/datasets.md#fetch-datasets) if you know the [RID](https://dev.nominal.io/platform/reference/glossary.md#rid) or [search](https://dev.nominal.io/rust-client/guides/datasets.md#find-datasets) first if you want to re-use an existing dataset but don’t have the RID saved.

To fill the dataset, [upload files](https://dev.nominal.io/rust-client/guides/upload.md) into it or [stream points](https://dev.nominal.io/rust-client/guides/stream.md) to it. To organize the dataset under an asset or a run, add it with [`AssetsClient::add_dataset`](https://dev.nominal.io/rust-client/ref/rust/nominal/core/struct.AssetsClient.md#method.add_dataset "nominal::core::AssetsClient::add_dataset") or [`RunsClient::add_dataset`](https://dev.nominal.io/rust-client/ref/rust/nominal/core/struct.RunsClient.md#method.add_dataset "nominal::core::RunsClient::add_dataset").

## Fetch datasets

If the RID of a dataset is known, you can fetch that dataset directly without needing to search.

```rust
let dataset = client.catalog().get_dataset("<ri.catalog.instance.dataset.identifier>").await?;
```

## Find datasets

[`search_datasets`](https://dev.nominal.io/rust-client/ref/rust/nominal/core/struct.CatalogClient.md#method.search_datasets "nominal::core::CatalogClient::search_datasets") finds datasets by label, property or name. Combine filters with [`and`](https://dev.nominal.io/rust-client/ref/rust/nominal/core/enum.DatasetQuery.md#method.and "nominal::core::DatasetQuery::and") and [`or`](https://dev.nominal.io/rust-client/ref/rust/nominal/core/enum.DatasetQuery.md#method.or "nominal::core::DatasetQuery::or"):

```rust
use nominal::core::DatasetQuery;

// Every dataset, most recently ingested first
let datasets = client.catalog().list_datasets().await?;

// Names that contain "telemetry", in any case
let datasets = client.catalog().search_datasets(DatasetQuery::substring_match("telemetry")).await?;

// The "flight-test" label, and "telemetry" in the name
let datasets = client
    .catalog()
    .search_datasets(DatasetQuery::and([
        DatasetQuery::label("flight-test"),
        DatasetQuery::substring_match("telemetry"),
    ]))
    .await?;
```

To list a dataset’s channels, see [Channels](https://dev.nominal.io/rust-client/guides/channels.md). To read its data, see [Query data with SQL](https://dev.nominal.io/rust-client/guides/sql.md). To read channels straight into memory through the REST API instead, see the [Read channel data](https://dev.nominal.io/rust-client/examples/read-channels.md) example.

## Update a dataset

[`update_dataset`](https://dev.nominal.io/rust-client/ref/rust/nominal/core/struct.CatalogClient.md#method.update_dataset "nominal::core::CatalogClient::update_dataset") changes the fields you include in the dataset update request by overwriting those fields. That is, `update_dataset(labels)` will *not* touch properties, but it *will* overwrite the current set of labels with the ones you provide.

```rust
use nominal::core::DatasetUpdate;

// The labels you set replace the dataset's labels, so start from its current ones
let mut labels = dataset.labels().to_vec();
labels.push("reviewed".to_string());
let dataset = client.catalog().update_dataset(dataset.rid(), DatasetUpdate::new().labels(labels)).await?;
```

## Archive a dataset

[`archive_dataset`](https://dev.nominal.io/rust-client/ref/rust/nominal/core/struct.CatalogClient.md#method.archive_dataset "nominal::core::CatalogClient::archive_dataset") hides a dataset from the UI without deleting it. [`unarchive_dataset`](https://dev.nominal.io/rust-client/ref/rust/nominal/core/struct.CatalogClient.md#method.unarchive_dataset "nominal::core::CatalogClient::unarchive_dataset") brings it back.

```rust
client.catalog().archive_dataset(dataset.rid()).await?;
```
