# Dataset

## class nominal.core.Dataset(rid, name, description, properties, labels, bounds, is_archived)

Bases: `HasRid`, `MarkableMixin`, `RefreshableConjureMixin`[`EnrichedDataset`]

A collection of channels populated by uploaded files and streamed data.

### rid: str

### name: str

### description: str | None

### properties: NominalProperties

### labels: Sequence[str]

### bounds: DatasetBounds | None

### is_archived: bool

### property nominal_url: str

Returns a URL to the page in the nominal app containing this dataset

### add_ardupilot_dataflash(path, tags=None)

Add a Dataflash file to an existing dataset.

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the Dataflash file to add to this dataset.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file.

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_ardupilot_dataflash_from_io(dataflash, *, file_name=None, tags=None)

Add an ArduPilot Dataflash file from a binary stream.

Parameters:
:   - **dataflash** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      Binary stream consumed from its current position. Seeking is not required;
      the caller retains ownership and must close it.
    - **file_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Upload filename. The .bin extension is added only when the name has no extension.
      Defaults to this dataset’s name.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Key-value pairs applied as tags to all data uniformly in the file.

Returns:
:   Dataset file after upload and ingestion submission. Call
    [`DatasetFile.poll_until_ingestion_completed`](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile.poll_until_ingestion_completed "nominal.core.DatasetFile.poll_until_ingestion_completed") to wait for ingestion.

Raises:
:   [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – The stream is open in text mode.

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_ardupilot_dataflash_to_dataset(path, tags=None)

Add a Dataflash file to an existing dataset.

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the Dataflash file to add to this dataset.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file.

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_avro_stream(path, *, timestamp_type=None, tags=None)

Upload an avro-stream file, which must match the schema shown below.

This is a “stream-like” file format to support
use cases where a columnar/tabular format does not make sense. This closely matches Nominal’s streaming
API, making it useful for use cases where network connection drops during streaming and a backup file needs
to be created.

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the .avro or .avro.gz file to upload
    - **timestamp_type** ([*Epoch*](https://dev.nominal.io/python/ref/generated/nominal.ts.Epoch.md#nominal.ts.Epoch "nominal.ts.Epoch") *|* [*Relative*](https://dev.nominal.io/python/ref/generated/nominal.ts.Relative.md#nominal.ts.Relative "nominal.ts.Relative") *|* [*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'epoch_picoseconds'**,* *'epoch_nanoseconds'**,* *'epoch_microseconds'**,* *'epoch_milliseconds'**,* *'epoch_seconds'**,* *'epoch_minutes'**,* *'epoch_hours'**,* *'epoch_days'**]* *|* *None*)

      How to read the numbers in the file’s `timestamps` field: an absolute epoch
      (`ts.Epoch`, or its string literal) or an offset from a start (`ts.Relative`). Defaults to
      “epoch_nanoseconds”.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Key-value tags applied to all data in the file. Tags in the records themselves take
      precedence – these only fill keys a record does not already set.

Returns:
:   Reference to the ingesting DatasetFile

Raises:
:   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – `path` does not end in .avro or .avro.gz, or `timestamp_type` has no numeric
    representation (e.g. an ISO 8601 or custom string format).

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

> **Note**
>
> For struct columns, values should be converted to JSON strings and wrapped in the JsonStruct record type.

> **Note**
>
> The previous schema with only “double” and “string” value types is still fully supported.

> **Note**
>
> If this schema is not used, ingestion will fail.

The required schema is:

```python
{
    "type": "record",
    "name": "AvroStream",
    "namespace": "io.nominal.ingest",
    "fields": [
        {
            "name": "channel",
            "type": "string",
            "doc": "Channel/series name (e.g., 'vehicle_id', 'col_1', 'temperature')",
        },
        {
            "name": "timestamps",
            "type": {"type": "array", "items": "long"},
            "doc": "Array of numeric timestamps; see timestamp_type for how they are read",
        },
        {
            "name": "values",
            "type": {"type": "array", "items": [
                "double",
                "string",
                "long",
                {"type": "record", "name": "DoubleArray", "fields": [{"name": "items", "type": {"type": "array", "items": "double"}}]},
                {"type": "record", "name": "StringArray", "fields": [{"name": "items", "type": {"type": "array", "items": "string"}}]},
                {"type": "record", "name": "JsonStruct", "fields": [{"name": "json", "type": "string"}]}
            ]},
            "doc": "Array of values. Can be doubles, longs, strings, arrays, or JSON structs",
        },
        {
            "name": "tags",
            "type": {"type": "map", "values": "string"},
            "default": {},
            "doc": "Key-value metadata tags",
        },
    ],
}
```

### add_channel(name, data_type, *, description=None, unit=None)

Create a new channel (series metadata) for this data source.

This creates the channel metadata entry without uploading any data points.
Use this to pre-register channels before streaming data to them.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      The name of the channel to create.
    - **data_type** ([*ChannelDataType*](https://dev.nominal.io/python/ref/generated/nominal.core.ChannelDataType.md#nominal.core.ChannelDataType "nominal.core.channel.ChannelDataType"))

      The data type of the channel (e.g., DOUBLE, STRING, LOG, INT).
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optional human-readable description of the channel.
    - **unit** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optional unit symbol to associate with the channel.

Returns:
:   The created or existing Channel object. Existing channels are returned unchanged.

Raises:
:   - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – Error creating the channel or fetching its metadata via gRPC.
    - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – Channel metadata was not found after creation.

Return type:
:   [*Channel*](https://dev.nominal.io/python/ref/generated/nominal.core.Channel.md#nominal.core.Channel "nominal.core.channel.Channel")

### add_containerized(extractor: str | ContainerizedExtractor, sources: Mapping[str, Path | str], *, arguments: Mapping[str, str] | None = None, tags: Mapping[str, str] | None = None) → IngestionJob

### add_containerized(extractor: str | ContainerizedExtractor, sources: Mapping[str, Path | str], *, arguments: Mapping[str, str] | None = None, tags: Mapping[str, str] | None = None, timestamp_column: str, timestamp_type: Iso8601 | Epoch | Relative | Custom | Literal['iso_8601', 'epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days']) → IngestionJob

Add data from proprietary data formats using a pre-registered custom extractor.

A containerized extraction runs asynchronously and may emit multiple output files, so this returns
the tracking [`IngestionJob`](https://dev.nominal.io/python/ref/generated/nominal.core.IngestionJob.md#nominal.core.IngestionJob "nominal.core.IngestionJob") immediately rather than a single file, and `job.cancel()` cancels it.

Waiting takes two stages: the container finishes producing files, then those files finish
ingesting. `job.as_files_ingested()` covers both — it re-reads the file list while the job runs,
so it picks up outputs that do not exist yet at the time of the call. `job.dataset_files()`, by
contrast, returns only the files that exist when it is called, which is empty until a manifest
extractor’s container has exited; and `job.status` is a snapshot, so polling it requires
`job.refresh()` to advance it.

Parameters:
:   - **extractor** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*ContainerizedExtractor*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerizedExtractor.md#nominal.core.ContainerizedExtractor "nominal.core.containerized_extractor.ContainerizedExtractor"))

      ContainerizedExtractor instance (or rid of one) to use for extracting and ingesting data.
    - **sources** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      Mapping of environment variables to source files to use with the extractor.

      **Note:** These must match the registered inputs of the active container image exactly.
    - **arguments** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Mapping of key-value pairs of input arguments to the extractor.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Key-value pairs of tags to apply to all data ingested from the containerized extractor run.
    - **timestamp_column** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      the column in the extractor’s output that contains the timestamp data.
      Provided together with `timestamp_type`, overrides the active container image’s
      `default_timestamp_metadata` for this ingest; if omitted, the image’s default is
      used. See [`ContainerImage.default_timestamp_metadata`](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerImage.md#nominal.core.ContainerImage.default_timestamp_metadata "nominal.core.ContainerImage.default_timestamp_metadata") for the full resolution order.

      **Note:** This is applied uniformly to all output files.

      Must be provided with a `timestamp_type` or a ValueError will be raised.
    - **timestamp_type** ([*Iso8601*](https://dev.nominal.io/python/ref/generated/nominal.ts.Iso8601.md#nominal.ts.Iso8601 "nominal.ts.Iso8601") *|* [*Epoch*](https://dev.nominal.io/python/ref/generated/nominal.ts.Epoch.md#nominal.ts.Epoch "nominal.ts.Epoch") *|* [*Relative*](https://dev.nominal.io/python/ref/generated/nominal.ts.Relative.md#nominal.ts.Relative "nominal.ts.Relative") *|* [*Custom*](https://dev.nominal.io/python/ref/generated/nominal.ts.Custom.md#nominal.ts.Custom "nominal.ts.Custom") *|* [*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'iso_8601'**,* *'epoch_picoseconds'**,* *'epoch_nanoseconds'**,* *'epoch_microseconds'**,* *'epoch_milliseconds'**,* *'epoch_seconds'**,* *'epoch_minutes'**,* *'epoch_hours'**,* *'epoch_days'**]* *|* *None*)

      the type of timestamp data in the extractor’s output.

      **Note:** This is applied uniformly to all output files.

      Must be provided with a `timestamp_column` or a ValueError will be raised.

Returns:
:   An [`IngestionJob`](https://dev.nominal.io/python/ref/generated/nominal.core.IngestionJob.md#nominal.core.IngestionJob "nominal.core.IngestionJob") handle for the asynchronous containerized ingest.

Return type:
:   [*IngestionJob*](https://dev.nominal.io/python/ref/generated/nominal.core.IngestionJob.md#nominal.core.IngestionJob "nominal.core.ingestion_job.IngestionJob")

### add_from_io(dataset, timestamp_column, timestamp_type, file_type=FileTypes.CSV, file_name=None, tag_columns=None, tags=None)

Append to a dataset from a file-like object.

Parameters:
:   - **dataset** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      a file-like object containing the data to append to the dataset.
    - **timestamp_column** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      the column in the dataset that contains the timestamp data.
    - **timestamp_type** ([*Iso8601*](https://dev.nominal.io/python/ref/generated/nominal.ts.Iso8601.md#nominal.ts.Iso8601 "nominal.ts.Iso8601") *|* [*Epoch*](https://dev.nominal.io/python/ref/generated/nominal.ts.Epoch.md#nominal.ts.Epoch "nominal.ts.Epoch") *|* [*Relative*](https://dev.nominal.io/python/ref/generated/nominal.ts.Relative.md#nominal.ts.Relative "nominal.ts.Relative") *|* [*Custom*](https://dev.nominal.io/python/ref/generated/nominal.ts.Custom.md#nominal.ts.Custom "nominal.ts.Custom") *|* [*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'iso_8601'**,* *'epoch_picoseconds'**,* *'epoch_nanoseconds'**,* *'epoch_microseconds'**,* *'epoch_milliseconds'**,* *'epoch_seconds'**,* *'epoch_minutes'**,* *'epoch_hours'**,* *'epoch_days'**]*)

      the type of timestamp data in the dataset.
    - **file_type** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* [*FileType*](https://dev.nominal.io/python/ref/generated/nominal.core.FileType.md#nominal.core.FileType "nominal.core.filetype.FileType"))

      a (extension, mimetype) pair describing the type of file.
    - **file_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Upload filename. An existing extension is preserved; otherwise the selected type
      supplies the default extension. Defaults to this dataset’s name.
    - **tag_columns** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      a dictionary mapping tag keys to column names.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_journal_json(path: Path | str, *, channel: str | None = None) → DatasetFile

### add_journal_json(path: Path | str, *, channel: str | None = None, timestamp_column: str, timestamp_type: Epoch | Literal['epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days']) → DatasetFile

Add a journald jsonl file to an existing dataset.

Supports any journald-style jsonl file, with a few expectations:
:   - The file must be .jsonl or .jsonl.gz, and each line must be a json object.
    - Each line must hold a timestamp field and a `MESSAGE` field carrying the primary log message.
      The timestamp field is `__REALTIME_TIMESTAMP` unless `timestamp_column` names another one.
      Lines missing either field are skipped.
    - Every other top-level field becomes a log arg, with its value converted to a string.

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to journal json file to ingest
    - **channel** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optionally, a channel name to use for ingested logs (defaults to ‘logs’)
    - **timestamp_column** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optionally, the name of the field in each json payload holding a timestamp.
      Defaults to __REALTIME_TIMESTAMP.
    - **timestamp_type** ([*Epoch*](https://dev.nominal.io/python/ref/generated/nominal.ts.Epoch.md#nominal.ts.Epoch "nominal.ts.Epoch") *|* [*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'epoch_picoseconds'**,* *'epoch_nanoseconds'**,* *'epoch_microseconds'**,* *'epoch_milliseconds'**,* *'epoch_seconds'**,* *'epoch_minutes'**,* *'epoch_hours'**,* *'epoch_days'**]* *|* *None*)

      Optionally, how to read the numbers in that field, given as a `ts.Epoch` or its
      string literal, e.g. `"epoch_microseconds"`. Defaults to microseconds since the unix epoch.

Returns:
:   DatasetFile object which can be used to poll for ingestion completion

Raises:
:   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – if only one of `timestamp_column` / `timestamp_type` is given, or if
    `timestamp_type` is not an absolute epoch type.

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_journal_json_from_io(journal: BinaryIO, *, file_type: tuple[str, str] | FileType | None = None, file_name: str | None = None, channel: str | None = None) → DatasetFile

### add_journal_json_from_io(journal: BinaryIO, *, file_type: tuple[str, str] | FileType | None = None, file_name: str | None = None, channel: str | None = None, timestamp_column: str, timestamp_type: Epoch | Literal['epoch_picoseconds', 'epoch_nanoseconds', 'epoch_microseconds', 'epoch_milliseconds', 'epoch_seconds', 'epoch_minutes', 'epoch_hours', 'epoch_days']) → DatasetFile

Add journald-style JSONL logs from a binary stream.

Parameters:
:   - **journal** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      Binary stream consumed from its current position. Seeking is not required;
      the caller retains ownership and must close it.
    - **file_type** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* [*FileType*](https://dev.nominal.io/python/ref/generated/nominal.core.FileType.md#nominal.core.FileType "nominal.core.filetype.FileType") *|* *None*)

      [`FileTypes.JOURNAL_JSONL`](https://dev.nominal.io/python/ref/generated/nominal.core.FileTypes.md#nominal.core.FileTypes.JOURNAL_JSONL "nominal.core.FileTypes.JOURNAL_JSONL") or [`FileTypes.JOURNAL_JSONL_GZ`](https://dev.nominal.io/python/ref/generated/nominal.core.FileTypes.md#nominal.core.FileTypes.JOURNAL_JSONL_GZ "nominal.core.FileTypes.JOURNAL_JSONL_GZ"), supplied as a
      [`FileType`](https://dev.nominal.io/python/ref/generated/nominal.core.FileType.md#nominal.core.FileType "nominal.core.FileType") or an `(extension, mimetype)` pair. When omitted or `None`, infer
      from `file_name`. Without `file_name`, supply an explicit type. Compressed
      bytes must be supplied for the gzip format; contents are not inspected.
    - **file_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Upload filename. An existing extension is preserved; otherwise the selected type
      supplies the default extension. Defaults to this dataset’s name.
    - **channel** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Log channel name. Defaults to ‘logs’ when omitted.
    - **timestamp_column** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Timestamp field. Defaults to __REALTIME_TIMESTAMP when omitted.
    - **timestamp_type** ([*Epoch*](https://dev.nominal.io/python/ref/generated/nominal.ts.Epoch.md#nominal.ts.Epoch "nominal.ts.Epoch") *|* [*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'epoch_picoseconds'**,* *'epoch_nanoseconds'**,* *'epoch_microseconds'**,* *'epoch_milliseconds'**,* *'epoch_seconds'**,* *'epoch_minutes'**,* *'epoch_hours'**,* *'epoch_days'**]* *|* *None*)

      Absolute epoch unit for that field. Defaults to epoch microseconds when omitted.
      Pass this together with `timestamp_column`.

Returns:
:   Dataset file after upload and ingestion submission. Call
    [`DatasetFile.poll_until_ingestion_completed`](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile.poll_until_ingestion_completed "nominal.core.DatasetFile.poll_until_ingestion_completed") to wait for ingestion.

Raises:
:   - [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – The stream is open in text mode.
    - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – The format cannot be inferred or is not journal JSONL, only one timestamp
      option is supplied, or the timestamp type is not an absolute epoch type.

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

> **Note**
>
> Records must contain a timestamp and a `MESSAGE` field, as described by [`add_journal_json`](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset.add_journal_json "nominal.core.Dataset.add_journal_json").

### add_journal_json_to_dataset(path, *, channel=None, timestamp_column=None, timestamp_type=None)

Add a journald jsonl file to an existing dataset.

Supports any journald-style jsonl file, with a few expectations:
:   - The file must be .jsonl or .jsonl.gz, and each line must be a json object.
    - Each line must hold a timestamp field and a `MESSAGE` field carrying the primary log message.
      The timestamp field is `__REALTIME_TIMESTAMP` unless `timestamp_column` names another one.
      Lines missing either field are skipped.
    - Every other top-level field becomes a log arg, with its value converted to a string.

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to journal json file to ingest
    - **channel** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optionally, a channel name to use for ingested logs (defaults to ‘logs’)
    - **timestamp_column** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optionally, the name of the field in each json payload holding a timestamp.
      Defaults to __REALTIME_TIMESTAMP.
    - **timestamp_type** ([*Epoch*](https://dev.nominal.io/python/ref/generated/nominal.ts.Epoch.md#nominal.ts.Epoch "nominal.ts.Epoch") *|* [*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'epoch_picoseconds'**,* *'epoch_nanoseconds'**,* *'epoch_microseconds'**,* *'epoch_milliseconds'**,* *'epoch_seconds'**,* *'epoch_minutes'**,* *'epoch_hours'**,* *'epoch_days'**]* *|* *None*)

      Optionally, how to read the numbers in that field, given as a `ts.Epoch` or its
      string literal, e.g. `"epoch_microseconds"`. Defaults to microseconds since the unix epoch.

Returns:
:   DatasetFile object which can be used to poll for ingestion completion

Raises:
:   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – if only one of `timestamp_column` / `timestamp_type` is given, or if
    `timestamp_type` is not an absolute epoch type.

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_mcap(path, include_topics=None, exclude_topics=None, tags=None, ignore_invalid_topics=None)

Add an MCAP file to an existing dataset.

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the MCAP file to add to this dataset
    - **include_topics** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      If present, list of topics to restrict ingestion to.
      If not present, defaults to all protobuf-encoded topics present in the MCAP.
    - **exclude_topics** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      If present, list of topics to not ingest from the MCAP.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file.
    - **ignore_invalid_topics** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") *|* *None*)

      If true, ignore invalid MCAP topics and continue ingesting valid topics.

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_mcap_from_io(mcap, include_topics=None, exclude_topics=None, file_name=None, *, tags=None, ignore_invalid_topics=None)

Add data to this dataset from an MCAP file-like object.

The mcap must be a file-like object in binary mode, e.g. open(path, “rb”) or io.BytesIO.
If the file is not in binary-mode, the requests library blocks indefinitely.

Parameters:
:   - **mcap** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      Binary file-like MCAP stream
    - **include_topics** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      If present, list of topics to restrict ingestion to.
      If not present, defaults to all protobuf-encoded topics present in the MCAP.
    - **exclude_topics** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      If present, list of topics to not ingest from the MCAP.
    - **file_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Upload filename. The .mcap extension is added only when the name has no extension.
      Defaults to this dataset’s name.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file.
    - **ignore_invalid_topics** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") *|* *None*)

      If true, ignore invalid MCAP topics and continue ingesting valid topics.

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_mcap_to_dataset(path, include_topics=None, exclude_topics=None, tags=None, ignore_invalid_topics=None)

Add an MCAP file to an existing dataset.

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the MCAP file to add to this dataset
    - **include_topics** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      If present, list of topics to restrict ingestion to.
      If not present, defaults to all protobuf-encoded topics present in the MCAP.
    - **exclude_topics** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      If present, list of topics to not ingest from the MCAP.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file.
    - **ignore_invalid_topics** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") *|* *None*)

      If true, ignore invalid MCAP topics and continue ingesting valid topics.

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_mcap_to_dataset_from_io(mcap, include_topics=None, exclude_topics=None, file_name=None, *, tags=None, ignore_invalid_topics=None)

Add data to this dataset from an MCAP file-like object.

The mcap must be a file-like object in binary mode, e.g. open(path, “rb”) or io.BytesIO.
If the file is not in binary-mode, the requests library blocks indefinitely.

Parameters:
:   - **mcap** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      Binary file-like MCAP stream
    - **include_topics** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      If present, list of topics to restrict ingestion to.
      If not present, defaults to all protobuf-encoded topics present in the MCAP.
    - **exclude_topics** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      If present, list of topics to not ingest from the MCAP.
    - **file_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Upload filename. The .mcap extension is added only when the name has no extension.
      Defaults to this dataset’s name.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file.
    - **ignore_invalid_topics** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") *|* *None*)

      If true, ignore invalid MCAP topics and continue ingesting valid topics.

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_mcap_video(path, *, channel, topic, tags=None, overwrite_overlapping=False)

Upload video data from an MCAP file to this dataset as a channel.

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the MCAP file (must end in `mcap`) containing H264/H265 video data.
    - **channel** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the video channel within this dataset that the file’s frames belong to.
    - **topic** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      MCAP topic containing the video data; per-frame timestamps come from this topic’s messages.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file.
    - **overwrite_overlapping** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      If True, segments from other files on this channel that overlap with the
      newly added file will be deleted before inserting the new segments.

Returns:
:   Reference to the created (still-ingesting) video dataset file.

Raises:
:   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – `path` does not end in `mcap`.

Return type:
:   [*VideoDatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoDatasetFile.md#nominal.core.VideoDatasetFile "nominal.core.video_dataset_file.VideoDatasetFile")

### add_mcap_video_from_io(mcap, file_name, *, channel, topic, file_type=FileTypes.MCAP, tags=None, overwrite_overlapping=False)

Upload video data from a binary MCAP file-like object to this dataset as a channel.

The mcap must be a file-like object in binary mode, e.g. open(path, “rb”) or io.BytesIO.

Parameters:
:   - **mcap** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      File-like binary object containing MCAP data with H264/H265 video.
    - **file_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Upload filename. An existing extension is preserved; otherwise the selected type supplies the default.
    - **channel** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the video channel within this dataset that the file’s frames belong to.
    - **topic** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      MCAP topic containing the video data; per-frame timestamps come from this topic’s messages.
    - **file_type** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* [*FileType*](https://dev.nominal.io/python/ref/generated/nominal.core.FileType.md#nominal.core.FileType "nominal.core.filetype.FileType"))

      Metadata about the type of file (e.g. MCAP).
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file.
    - **overwrite_overlapping** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      If True, segments from other files on this channel that overlap with the
      newly added file will be deleted before inserting the new segments.

Returns:
:   Reference to the created (still-ingesting) video dataset file.

Raises:
:   [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – `mcap` is open in text mode rather than binary mode.

Return type:
:   [*VideoDatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoDatasetFile.md#nominal.core.VideoDatasetFile "nominal.core.video_dataset_file.VideoDatasetFile")

### add_tabular_data(path, timestamp_column, timestamp_type, tag_columns=None, tags=None)

Append to a dataset from tabular data on-disk.

Currently, the supported filetypes are:
:   - .csv / .csv.gz
    - .parquet / .parquet.gz
    - .parquet.tar / .parquet.tar.gz / .parquet.zip

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the file on disk to add to the dataset.
    - **timestamp_column** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Column within the file containing timestamp information.

      **Note:** This is omitted as a channel from the data added to Nominal, and is instead used
      to set the timestamps for all other uploaded data channels.
    - **timestamp_type** ([*Iso8601*](https://dev.nominal.io/python/ref/generated/nominal.ts.Iso8601.md#nominal.ts.Iso8601 "nominal.ts.Iso8601") *|* [*Epoch*](https://dev.nominal.io/python/ref/generated/nominal.ts.Epoch.md#nominal.ts.Epoch "nominal.ts.Epoch") *|* [*Relative*](https://dev.nominal.io/python/ref/generated/nominal.ts.Relative.md#nominal.ts.Relative "nominal.ts.Relative") *|* [*Custom*](https://dev.nominal.io/python/ref/generated/nominal.ts.Custom.md#nominal.ts.Custom "nominal.ts.Custom") *|* [*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'iso_8601'**,* *'epoch_picoseconds'**,* *'epoch_nanoseconds'**,* *'epoch_microseconds'**,* *'epoch_milliseconds'**,* *'epoch_seconds'**,* *'epoch_minutes'**,* *'epoch_hours'**,* *'epoch_days'**]*)

      Type of timestamp data contained within the `timestamp_column` e.g. ‘epoch_seconds’.
    - **tag_columns** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      a dictionary mapping tag keys to column names.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_tabular_data_to_dataset(path, timestamp_column, timestamp_type, tag_columns=None, tags=None)

Append to a dataset from tabular data on-disk.

Currently, the supported filetypes are:
:   - .csv / .csv.gz
    - .parquet / .parquet.gz
    - .parquet.tar / .parquet.tar.gz / .parquet.zip

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the file on disk to add to the dataset.
    - **timestamp_column** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Column within the file containing timestamp information.

      **Note:** This is omitted as a channel from the data added to Nominal, and is instead used
      to set the timestamps for all other uploaded data channels.
    - **timestamp_type** ([*Iso8601*](https://dev.nominal.io/python/ref/generated/nominal.ts.Iso8601.md#nominal.ts.Iso8601 "nominal.ts.Iso8601") *|* [*Epoch*](https://dev.nominal.io/python/ref/generated/nominal.ts.Epoch.md#nominal.ts.Epoch "nominal.ts.Epoch") *|* [*Relative*](https://dev.nominal.io/python/ref/generated/nominal.ts.Relative.md#nominal.ts.Relative "nominal.ts.Relative") *|* [*Custom*](https://dev.nominal.io/python/ref/generated/nominal.ts.Custom.md#nominal.ts.Custom "nominal.ts.Custom") *|* [*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'iso_8601'**,* *'epoch_picoseconds'**,* *'epoch_nanoseconds'**,* *'epoch_microseconds'**,* *'epoch_milliseconds'**,* *'epoch_seconds'**,* *'epoch_minutes'**,* *'epoch_hours'**,* *'epoch_days'**]*)

      Type of timestamp data contained within the `timestamp_column` e.g. ‘epoch_seconds’.
    - **tag_columns** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      a dictionary mapping tag keys to column names.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_to_dataset_from_io(dataset, timestamp_column, timestamp_type, file_type=FileTypes.CSV, file_name=None, tag_columns=None, tags=None)

Append to a dataset from a file-like object.

Parameters:
:   - **dataset** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      a file-like object containing the data to append to the dataset.
    - **timestamp_column** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      the column in the dataset that contains the timestamp data.
    - **timestamp_type** ([*Iso8601*](https://dev.nominal.io/python/ref/generated/nominal.ts.Iso8601.md#nominal.ts.Iso8601 "nominal.ts.Iso8601") *|* [*Epoch*](https://dev.nominal.io/python/ref/generated/nominal.ts.Epoch.md#nominal.ts.Epoch "nominal.ts.Epoch") *|* [*Relative*](https://dev.nominal.io/python/ref/generated/nominal.ts.Relative.md#nominal.ts.Relative "nominal.ts.Relative") *|* [*Custom*](https://dev.nominal.io/python/ref/generated/nominal.ts.Custom.md#nominal.ts.Custom "nominal.ts.Custom") *|* [*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'iso_8601'**,* *'epoch_picoseconds'**,* *'epoch_nanoseconds'**,* *'epoch_microseconds'**,* *'epoch_milliseconds'**,* *'epoch_seconds'**,* *'epoch_minutes'**,* *'epoch_hours'**,* *'epoch_days'**]*)

      the type of timestamp data in the dataset.
    - **file_type** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* [*FileType*](https://dev.nominal.io/python/ref/generated/nominal.core.FileType.md#nominal.core.FileType "nominal.core.filetype.FileType"))

      a (extension, mimetype) pair describing the type of file.
    - **file_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Upload filename. An existing extension is preserved; otherwise the selected type
      supplies the default extension. Defaults to this dataset’s name.
    - **tag_columns** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      a dictionary mapping tag keys to column names.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### add_video(path: Path | str, *, channel: str, start: datetime | int, tags: Mapping[str, str] | None = None, overwrite_overlapping: bool = False) → VideoDatasetFile

### add_video(path: Path | str, *, channel: str, frame_timestamps: Sequence[int], tags: Mapping[str, str] | None = None, overwrite_overlapping: bool = False) → VideoDatasetFile

Upload a video file to this dataset as a channel.

Parameters:
:   - **path** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Path to the H264/H265-encoded video file to add to this dataset.
    - **channel** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the video channel within this dataset that the file’s frames belong to.
    - **start** ([*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Starting timestamp of the video file in absolute UTC time (datetime or epoch nanoseconds).
      Exactly one of `start` or `frame_timestamps` must be provided.
    - **frame_timestamps** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")*]* *|* *None*)

      Per-frame absolute nanosecond timestamps. Most usecases should instead use the
      ‘start’ parameter, unless precise per-frame metadata is available and desired.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file.
    - **overwrite_overlapping** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      If True, segments from other files on this channel that overlap with the
      newly added file will be deleted before inserting the new segments.

Returns:
:   Reference to the created (still-ingesting) video dataset file.

Raises:
:   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – neither or both of `start` and `frame_timestamps` were provided.

Return type:
:   [*VideoDatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoDatasetFile.md#nominal.core.VideoDatasetFile "nominal.core.video_dataset_file.VideoDatasetFile")

### add_video_from_io(video: BinaryIO, file_name: str, *, channel: str, start: datetime | int, file_type: tuple[str, str] | FileType = FileTypes.MP4, tags: Mapping[str, str] | None = None, overwrite_overlapping: bool = False) → VideoDatasetFile

### add_video_from_io(video: BinaryIO, file_name: str, *, channel: str, frame_timestamps: Sequence[int], file_type: tuple[str, str] | FileType = FileTypes.MP4, tags: Mapping[str, str] | None = None, overwrite_overlapping: bool = False) → VideoDatasetFile

Upload video data from a binary file-like object to this dataset as a channel.

The video must be a file-like object in binary mode, e.g. open(path, “rb”) or io.BytesIO,
containing H264 or H265-encoded video data.

Parameters:
:   - **video** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      File-like object containing video data encoded in H264 or H265.
    - **file_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Upload filename. An existing extension is preserved; otherwise the selected type supplies the default.
    - **channel** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the video channel within this dataset that the file’s frames belong to.
    - **start** ([*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Starting timestamp of the video file in absolute UTC time (datetime or epoch nanoseconds).
      Exactly one of `start` or `frame_timestamps` must be provided.
    - **frame_timestamps** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")*]* *|* *None*)

      Per-frame absolute nanosecond timestamps. Most usecases should instead use the
      ‘start’ parameter, unless precise per-frame metadata is available and desired.
    - **file_type** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* [*FileType*](https://dev.nominal.io/python/ref/generated/nominal.core.FileType.md#nominal.core.FileType "nominal.core.filetype.FileType"))

      Metadata about the type of video file, e.g., MP4 vs. MKV.
    - **tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      key-value pairs to apply as tags to all data uniformly in the file.
    - **overwrite_overlapping** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      If True, segments from other files on this channel that overlap with the
      newly added file will be deleted before inserting the new segments.

Returns:
:   Reference to the created (still-ingesting) video dataset file.

Raises:
:   - [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – `video` is open in text mode rather than binary mode.
    - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – neither or both of `start` and `frame_timestamps` were provided.

Return type:
:   [*VideoDatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoDatasetFile.md#nominal.core.VideoDatasetFile "nominal.core.video_dataset_file.VideoDatasetFile")

### apply_markings(markings)

Apply markings to this resource, leaving any already-applied markings in place.

Applying a marking that is already applied is a no-op rather than an error.

Parameters:
:   **markings** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

    Markings, or marking RIDs, to apply.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the request fails, including when a marking is archived or the user
    lacks permission to change markings on this resource.

### archive()

Archive this dataset.
Archived datasets are not deleted, but are hidden from the UI.

> **Note**
>
> This does not update the instance in place; call [`refresh()`](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset.refresh "nominal.core.Dataset.refresh") to see the change reflected.

### batch_add_channels(channels)

Create multiple channels (series metadata) for this data source in batches.

Parameters:
:   **channels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*CreateChannelRequest*](https://dev.nominal.io/python/ref/generated/nominal.core.CreateChannelRequest.md#nominal.core.CreateChannelRequest "nominal.core.channel.CreateChannelRequest")*]*)

    Sequence of CreateChannelRequest objects.

Returns:
:   A BatchAddChannelsResult with the created channels and any requests that were
    not found after creation (i.e. silently dropped by the server).

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – A channel name appears more than once in `channels`.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – Error creating channels or fetching their metadata via gRPC.

Return type:
:   [*BatchAddChannelsResult*](https://dev.nominal.io/python/ref/generated/nominal.core.BatchAddChannelsResult.md#nominal.core.BatchAddChannelsResult "nominal.core.channel.BatchAddChannelsResult")

> **Note**
>
> Existing channels are returned unchanged. Repeated names anywhere in `channels`
> raise ValueError before any requests are sent, even if their metadata matches.
>
> Batches are written sequentially; earlier batches remain applied if a later batch fails.

### batch_update_or_create_channels(channels)

Create or update multiple channels (series metadata) for this data source in batches.

For each request, creates the channel if it does not already exist. If it does exist,
updates the locator and any provided `unit` and [`description`](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset.description "nominal.core.Dataset.description") fields while preserving
existing values for fields left as None.

Parameters:
:   **channels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*CreateChannelRequest*](https://dev.nominal.io/python/ref/generated/nominal.core.CreateChannelRequest.md#nominal.core.CreateChannelRequest "nominal.core.channel.CreateChannelRequest")*]*)

    Sequence of CreateChannelRequest objects.

Returns:
:   A BatchAddChannelsResult with the upserted channels and any requests that were
    not found afterwards (i.e. silently dropped by the server).

Return type:
:   [*BatchAddChannelsResult*](https://dev.nominal.io/python/ref/generated/nominal.core.BatchAddChannelsResult.md#nominal.core.BatchAddChannelsResult "nominal.core.channel.BatchAddChannelsResult")

> **Note**
>
> If the same channel name appears more than once within a single batch, the entire
> batch will fail. Callers are responsible for deduplicating channel names before
> passing them to this method. Earlier batches remain applied if a later batch fails.

### get_channel(name)

Return type:
:   [*Channel*](https://dev.nominal.io/python/ref/generated/nominal.core.Channel.md#nominal.core.Channel "nominal.core.channel.Channel")

### get_channels(*, names=None)

Look up the metadata for all matching channels associated with this datasource

Parameters:
:   **names** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

    List of channel names to look up metadata for.

Yields:
:   Yields a sequence of channel metadata objects which match the provided query parameters

Return type:
:   [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")[[*Channel*](https://dev.nominal.io/python/ref/generated/nominal.core.Channel.md#nominal.core.Channel "nominal.core.channel.Channel")]

### get_dataset_file(dataset_file_id)

Retrieve the given dataset file by ID

Parameters:
:   **dataset_file_id** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

    ID of the file to retrieve from the dataset

Returns:
:   Metadata for the requested dataset file

Raises:
:   [**FileNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#FileNotFoundError "(in Python v3.15)") – Details about the requested file could not be found

Return type:
:   [*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")

### get_log_stream(batch_size=50_000, max_wait=timedelta(seconds=1))

Stream to asynchronously write log data to a dataset.

Parameters:
:   - **batch_size** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Number of records to upload at a time to Nominal.

      **Note:** Raising this may improve performance in high latency scenarios.
    - **max_wait** ([*timedelta*](https://docs.python.org/3/library/datetime.html#datetime.timedelta "(in Python v3.15)"))

      Maximum number of seconds to allow data to be locally buffered
      before streaming to Nominal.

Returns:
:   Write stream object configured to send logs to nominal. This may be used as a context manager
    (so that resources are automatically released upon exiting the context), or if not used as a context
    manager, should be explicitly `close()`-ed once no longer needed.

Return type:
:   *WriteStreamBase*[[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")]

### get_video_file(dataset_file_id)

Retrieve a video dataset file by ID.

Raises:
:   - [**FileNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#FileNotFoundError "(in Python v3.15)") – the file does not exist in this dataset.
    - [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – the ID identifies a non-video dataset file.

Return type:
:   [*VideoDatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoDatasetFile.md#nominal.core.VideoDatasetFile "nominal.core.video_dataset_file.VideoDatasetFile")

### get_write_stream(batch_size: int = 250000, max_wait: timedelta = timedelta(seconds=0.25), implementation: Literal['rust', 'rust_experimental'] | None = None, file_fallback: PathLike | None = None, log_level: str | None = None, num_workers: int | None = None, track_metrics: bool = False) → DataStream

### get_write_stream(batch_size: int = 250000, max_wait: timedelta = timedelta(seconds=0.25), implementation: Literal['python', 'json', 'protobuf', 'experimental'] = None) → DataStream

### get_write_stream(batch_size: int = 250000, max_wait: timedelta = timedelta(seconds=0.25), *, data_format: Literal['rust', 'rust_experimental'], file_fallback: PathLike | None = None, log_level: str | None = None, num_workers: int | None = None, track_metrics: bool = False) → DataStream

### get_write_stream(batch_size: int = 250000, max_wait: timedelta = timedelta(seconds=0.25), *, data_format: Literal['python', 'json', 'protobuf', 'experimental']) → DataStream

Stream to write timeseries data to a datasource.

Data is written asynchronously.

Parameters:
:   - **batch_size** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      How big the batch can get before writing to Nominal.
    - **max_wait** ([*timedelta*](https://docs.python.org/3/library/datetime.html#datetime.timedelta "(in Python v3.15)"))

      How long a batch can exist before being flushed to Nominal.
    - **implementation** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'python'**,* *'rust'**,* *'json'**,* *'protobuf'**,* *'experimental'**,* *'rust_experimental'**]* *|* *None*)

      Streaming implementation to use: ‘rust’ or ‘python’. When omitted, uses ‘rust’
      if `nominal-streaming` is available, otherwise ‘python’. Automatic selection cannot fall back
      to ‘python’ when `file_fallback`, `log_level`, or `num_workers` is supplied,
      or when `track_metrics=True`.

      **Note:** ‘json’, ‘protobuf’, and ‘rust_experimental’ are deprecated spellings of
      ‘python’, ‘python’, and ‘rust’ respectively.

      **Note:** ‘experimental’ is deprecated and retains its Python metrics implementation.
      Use `implementation='rust'` with `track_metrics=True` to migrate.
    - **file_fallback** ([*Path*](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filepath to write failed batches to during streaming.

      **Note:** Expects a .avro filename.

      **Note:** Supported only by the Rust backend.
    - **log_level** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Log level to use in underlying rust streaming code.

      **Note:** Should be a rust log level e.g. ‘debug’, ‘trace’, ‘info’, etc.

      **Note:** Supported only by the Rust backend.
    - **num_workers** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Number of Rust upload workers and runtime worker threads.

      **Note:** Use with care– this may have large impacts on streaming performance.

      **Note:** Supported only by the Rust backend.
    - **track_metrics** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      Emit request round-trip time and point staleness in seconds as
      `__nominal.metric.*` channels on the same dataset. Staleness is the SDK machine’s
      wall-clock UTC time minus the point timestamp; future timestamps produce negative values.
      Request metrics measure the oldest and newest points immediately before and after a
      successful upload. `enqueue_from_dict` also emits `enque_dict_start_staleness` and
      `enque_dict_end_staleness`, measured at the start and end of the enqueue. Disabled by default.

      **Note:** Request metrics are best-effort and travel with later data uploads. Pending request
      metrics are not sent separately on close and may be dropped if their buffer fills.

      **Note:** Supported only by the Rust backend.
    - **data_format** ([*Literal*](https://docs.python.org/3/library/typing.html#typing.Literal "(in Python v3.15)")*[**'python'**,* *'rust'**,* *'json'**,* *'protobuf'**,* *'experimental'**,* *'rust_experimental'**]* *|* *None*)

      Deprecated name for `implementation`. Passing both is an error.

Returns:
:   Write stream object configured to send data to nominal. This may be used as a context manager
    (so that resources are automatically released upon exiting the context), or if not used as a context
    manager, should be explicitly `close()`-ed once no longer needed.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – both `implementation` and `data_format` were given, or the implementation is unknown.
    - [**ImportError**](https://docs.python.org/3/builtins/exceptions.html#ImportError "(in Python v3.15)") – `nominal-streaming` is not installed and rust streaming was asked for, either
      explicitly via `implementation` or implicitly by passing a rust-only argument.

Return type:
:   *WriteStreamBase*[[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") | [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)") | [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")]

### list_files(*, successful_only=True)

List files ingested to this dataset.

If successful_only, yields files with a ‘success’ ingest status only.

Return type:
:   [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")[[*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")]

### list_markings()

The markings currently applied to this resource.

Markings the user does not have permission to read are omitted.

> **Note**
>
> The service filters unreadable markings out of the response, so this may be a strict
> subset of what is actually applied. Treat it as “what I can see”, not “what is there”:
> a resource can carry markings that never appear here. Use [`apply_markings`](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset.apply_markings "nominal.core.Dataset.apply_markings") and
> [`remove_markings`](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset.remove_markings "nominal.core.Dataset.remove_markings"), which name their targets outright, rather than computing a desired
> set from this list.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the request fails.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking")]

### list_video_files(*, successful_only=True)

List video files ingested to this dataset.

If successful_only, yields successfully-ingested video files only; otherwise also
yields queued, ingesting, failed, and deletion-state video files.

Return type:
:   [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")[[*VideoDatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.VideoDatasetFile.md#nominal.core.VideoDatasetFile "nominal.core.video_dataset_file.VideoDatasetFile")]

### refresh()

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### remove_markings(markings)

Remove markings from this resource.

Removing a marking that is not applied is a no-op rather than an error.

Parameters:
:   **markings** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

    Markings, or marking RIDs, to remove.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the request fails.

### search_channels(exact_match=(), fuzzy_search_text='', *, data_types=None)

Look up channels associated with a datasource.

Parameters:
:   - **exact_match** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      Filter the returned channels to those whose names match all provided strings
      (case insensitive).
    - **fuzzy_search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Filters the returned channels to those whose names fuzzily match the provided string.
    - **data_types** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*ChannelDataType*](https://dev.nominal.io/python/ref/generated/nominal.core.ChannelDataType.md#nominal.core.ChannelDataType "nominal.core.channel.ChannelDataType")*]* *|* *None*)

      Filter the returned channels to those that match any of the provided types

Yields:
:   Channel objects for each matching channel

Return type:
:   [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")[[*Channel*](https://dev.nominal.io/python/ref/generated/nominal.core.Channel.md#nominal.core.Channel "nominal.core.channel.Channel")]

### search_files(*, start=None, end=None, file_tags=None)

Search for files within this dataset.
Filters are ANDed together. Time range uses overlap semantics: a file is included if its
time range overlaps with [start, end], i.e. `file.end >= start AND file.start <= end`.

Parameters:
:   - **start** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Inclusive lower bound of the search window. Files whose time range ends at or
      after this timestamp are returned — including files that started before `start`
      but still overlap the window. Files ending entirely before `start` are excluded.

      **Note:** Truncated to whole seconds — sub-second precision is dropped.
    - **end** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Inclusive upper bound of the search window. Files whose time range starts at or
      before this timestamp are returned — including files that end after `end` but
      still overlap the window. Files starting entirely after `end` are excluded.

      **Note:** Truncated to whole seconds — sub-second precision is dropped.
    - **file_tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A mapping of key-value tag pairs that must ALL be present on a dataset file to be included.

Returns:
:   All dataset files within this dataset which match all of the provided conditions

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")]

### set_channel_prefix_tree(delimiter='.')

Index channels hierarchically by a given delimiter.

Primarily, the result of this operation is to prompt the frontend to represent channels
in a tree-like manner that allows folding channels by common roots.

### set_channel_units(channels_to_units, validate_schema=False, allow_display_only_units=False)

Set units for channels based on a provided mapping of channel names to units.

Updates are sent sequentially in batches of at most 10,000 matching channels.
Each batch is atomic. If a later batch fails, earlier batches remain applied and
subsequent batches are not sent.

Parameters:
:   - **channels_to_units** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*Unit*](https://dev.nominal.io/python/ref/generated/nominal.core.Unit.md#nominal.core.Unit "nominal.core.unit.Unit") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None**]*)

      A mapping of channel names to unit symbols.

      **Note:** Any existing units may be cleared from a channel by providing None as a symbol.
    - **validate_schema** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      If true, raises a ValueError if non-existent channel names are provided in
      `channels_to_units`. Default is False.
    - **allow_display_only_units** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      If true, allow units that would be treated as display-only by Nominal.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – Unsupported unit symbol provided
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – Error validating or updating units via gRPC (e.g. NominalNotFoundError).
    - **conjure_python_client.ConjureHTTPError** – Error completing requests.

### unarchive()

Unarchives this dataset, allowing it to show up in the ‘All Datasets’ pane in the UI.

> **Note**
>
> This does not update the instance in place; call [`refresh()`](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset.refresh "nominal.core.Dataset.refresh") to see the change reflected.

### update(*, name=None, description=None, properties=None, labels=None)

Replace dataset metadata.
Updates the current instance, and returns it.

Only the metadata passed in will be replaced, the rest will remain untouched.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Replacement name.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Replacement description.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")*]* *|* *None*)

      String or numeric properties. Integers are stored as floats.
      None leaves properties unchanged; an empty mapping clears them.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Replacement labels.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

> **Note**
>
> This replaces the metadata rather than appending it. To append to labels or properties, merge them before
> calling this method. E.g.:
>
> ```python
> new_labels = ["new-label-a", "new-label-b"]
> for old_label in dataset.labels:
>     new_labels.append(old_label)
> dataset = dataset.update(labels=new_labels)
> ```

Raises:
:   [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – If a property value is a boolean or is not a string, integer, or float.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### update_bounds(*, start, end)

Update the bounds (start and end timestamps) of the dataset.
Updates the current instance, and returns it.

Parameters:
:   - **start** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      The start timestamp of the dataset bounds. Can be a datetime, ISO 8601 string,
      or integer nanoseconds since epoch.
    - **end** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      The end timestamp of the dataset bounds. Can be a datetime, ISO 8601 string,
      or integer nanoseconds since epoch.

Returns:
:   The updated Dataset instance with new bounds.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### write_logs(logs, channel_name='logs', batch_size=1000)

Stream logs to the datasource.

This method executes synchronously, i.e. it blocks until all logs are sent to the API.
Logs are sent in batches. The logs can be any iterable of LogPoints, including a generator.

Parameters:
:   - **logs** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*LogPoint*](https://dev.nominal.io/python/ref/generated/nominal.core.LogPoint.md#nominal.core.LogPoint "nominal.core.log.LogPoint")*]*)

      LogPoints to stream to Nominal.
    - **channel_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the channel to stream logs to.
    - **batch_size** ([*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Number of logs to send to the API at a time.

Example

```python
from typing import Iterable

from nominal.core import LogPoint

def parse_logs_from_file(file_path: str) -> Iterable[LogPoint]:
    # 2025-04-08T14:26:28.679052Z [INFO] Sent ACTUATE_MOTOR command
    with open(file_path, "r") as f:
        for line in f:
            timestamp, level, message = line.removesuffix("\n").split(maxsplit=2)
            yield LogPoint.create(timestamp, message, {"level": level.removeprefix("[").removesuffix("]")})

dataset = client.get_dataset("dataset_rid")
logs = parse_logs_from_file("logs.txt")
dataset.write_logs(logs)
```