---
sidebar:
  hidden: true
title: roboto.experimental.topics.decode.common
---
What reading one file of a read plan's partition takes and gives.

## Module Contents

### FileDecodeParams

```python
class roboto.experimental.topics.decode.common.FileDecodeParams
```

`from roboto.experimental.topics.decode import FileDecodeParams`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/decode/common.py#L69-L82)

What decoding a file takes beyond the read plan: how to reach the file and whether to cache it.

Caching applies to Parquet files only; MCAP files always stream.

**Attributes**

- **FileDecodeParams.cache_dir** (`pathlib.Path`): Directory Parquet files are cached under.
- **FileDecodeParams.cache_policy** (`roboto.storage.CachePolicy`): Whether fetched Parquet files are cached to local disk.
- **FileDecodeParams.signed_url_resolver** (`SignedUrlResolver`): Mints a signed download URL for a file.

### FileDecoder

```python
class roboto.experimental.topics.decode.common.FileDecoder
```

`from roboto.experimental.topics.decode import FileDecoder`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/decode/common.py#L85-L134)

Bases: `abc.ABC`

Decodes the fields one file supplies to a partition into RecordBatches.

Opening a decoder opens its file, so its fields are known before the first batch. Close it when done, or use it as a context manager.

**Properties**

- **FileDecoder.value_fields** (`list[pyarrow.Field]`, abstract): The value columns, one per top-level field the file supplies, sorted by name, comparing Unicode code points.

  Each struct keeps the fields the file supplies, in the order the file stores them.

#### FileDecoder.batches()

```python
@abstractmethod
def batches() -> collections.abc.Iterator[pyarrow.RecordBatch]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/decode/common.py#L112-L123)

The window's rows, in the file's stored row order; iterate it once.

A partition that declares a `data_range` gets only the window's rows inside that slice of the file. Each batch has the columns of [`topic_data_schema()`](/reference/python-sdk/roboto/experimental/topics/batch_transforms#roboto.experimental.topics.batch_transforms.topic_data_schema) over [`value_fields`](/reference/python-sdk/roboto/experimental/topics/decode/common#roboto.experimental.topics.decode.common.FileDecoder.value_fields): the row number, the timestamp, then the value columns. A row's number is its 0-based position among the file's rows of the topic, counting every stored row, including rows outside the window or the `data_range` and rows with a null timestamp, so a row has the same number in every file of its partition. The timestamp is absolute: the stored value in nanoseconds plus the partition's `time_offset_ns`. Batch boundaries carry no meaning.

**Returns**

- `collections.abc.Iterator[pyarrow.RecordBatch]`

#### FileDecoder.close()

```python
@abstractmethod
def close() -> None
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/decode/common.py#L126-L127)

Release the file. Safe to call more than once.

**Returns**

- `None`

#### FileDecoder.struct_field_names()

```python
@abstractmethod
def struct_field_names(
    path: roboto.domain.topics.record.FieldPath,
) -> Optional[list[str]]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/decode/common.py#L130-L134)

The names of the fields of the struct at `path` in the file, in the file's order.

`None` when the file has no struct at `path`.

**Parameters**

- **path** (`roboto.domain.topics.record.FieldPath`)

**Returns**

- `Optional[list[str]]`

### FileDecoderOpener

```python
roboto.experimental.topics.decode.common.FileDecoderOpener
```

`from roboto.experimental.topics.decode import FileDecoderOpener`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/decode/common.py#L137-L137)

Opens a [`FileDecoder`](/reference/python-sdk/roboto/experimental/topics/decode/common#roboto.experimental.topics.decode.common.FileDecoder) of a group's file for its partition and the partition's window.

The window is absolute and includes both ends. A decoder keeps the rows whose absolute timestamp lies in it.

### ScanTaskGroup

```python
class roboto.experimental.topics.decode.common.ScanTaskGroup
```

`from roboto.experimental.topics.decode import ScanTaskGroup`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/decode/common.py#L46-L65)

The scan tasks of a partition that read one file, and the fields they supply.

Every scan task in the group agrees on the file's format, transformations and topic name.

**Attributes**

- **ScanTaskGroup.format** (`roboto.domain.topics.RepresentationStorageFormat`)

- **ScanTaskGroup.object** (`roboto.experimental.topics.read_plan.ReadPlanObjectRef`)

- **ScanTaskGroup.supplies** (`tuple[SuppliedField, ...]`): In the order of the leaf-most paths they come from.

  For one path, the supplied field at the path itself comes before the subtrees inside it, which come in plan order. Empty when the file is read only for its row numbers and timestamps.

- **ScanTaskGroup.topic_name** (`str | None`): The topic the scan tasks read from the file; see [`topic_name`](/reference/python-sdk/roboto/experimental/topics/read_plan#roboto.experimental.topics.read_plan.ReadPlanScanTask.topic_name).

### SignedUrlResolver

```python
roboto.experimental.topics.decode.common.SignedUrlResolver
```

`from roboto.experimental.topics.decode.common import SignedUrlResolver`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/decode/common.py#L30-L30)

Resolves a file id (`fs_node_id`) to a signed download URL.

### SuppliedField

```python
class roboto.experimental.topics.decode.common.SuppliedField
```

`from roboto.experimental.topics.decode import SuppliedField`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/experimental/topics/decode/common.py#L35-L42)

The field at `path`, which one file supplies to the read, less the fields at `excluded`, which other scan tasks supply (they may read the same file).

**Attributes**

- **SuppliedField.excluded** (`tuple[roboto.domain.topics.record.FieldPath, ...]`) = `()`: Paths strictly inside `path`, none inside another.
- **SuppliedField.path** (`roboto.domain.topics.record.FieldPath`)