> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ovalbee.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ovalbee.com/_mcp/server.

# Random sample

> Draws a random sample of images from a source dataset, with their annotations. Images drawn in earlier runs are skipped, so each run returns new ones. The Sample output always holds only the latest sample, and a destination dataset, if set, collects every sample.

## Overview

Draws a random sample of images from a dataset, with their annotations. An image drawn once is never drawn again by the same node, so each run returns new images.

`LAST_RUN` opens the latest sample, with or without a destination. A destination dataset collects every sample. A hidden `ALL_SAMPLED_ASSETS` output points to the history dataset that prevents later runs of the same node from selecting those images again. The badge shows the latest sample size and opens `LAST_RUN`.

```mermaid
flowchart LR
  n1["Dataset"] --> n2["Random sample"] --> n3["Dataset"]
```

## How it works

Compares the source images with the node's sampling history.

Chooses a random sample from the images that haven't been drawn before.

Adds the images and their annotations to `LAST_RUN` and to the history dataset.

## FAQ

#### What if fewer images remain than the requested sample size?

The node samples every remaining image without failing.

#### What happens when every image has already been sampled?

The node stops the flow, returns no `LAST_RUN` dataset, and shows a badge count of zero. The existing history dataset remains available.

#### What happens to the sample dataset on a rerun?

The node writes each sample into its own output dataset, named after the source, such as `Random sample (Cats)`: created on the first run, a new empty version of it on every rerun, so `LAST_RUN` holds only the latest sample. Switching to a source with another name starts a new dataset, and switching back continues the old one. A destination you select is not versioned: each run adds its images to it, so it collects every sample.

#### How do I sample images again that were drawn before?

The sampling history belongs to this node and has no reset. A newly added Random sample node starts with an empty history.

#### Can this node sample videos?

No. This version samples image assets only.

## Inputs

**`From dataset`** `dataset` — required

Source dataset the assets are drawn from. Assets drawn in earlier runs are skipped, so each run returns new ones. Key: `SRC_DATASET`.

---

**`Destination dataset`** `dataset`

Dataset that collects every sample - each run adds its images to it. Leave empty to keep only the Sample output. Key: `DST_DATASET`.

---

**`Sample size`** `integer` — required, default: 10

Number of assets to draw. Fewer are returned when the source has no unseen assets left. Minimum: `1`. Step: `1`. Key: `SAMPLE_SIZE`.

---

## Outputs

**`Sample`** `dataset`

Dataset with the images drawn by the latest run, named after the source dataset. A rerun writes a new version of it, and a new source starts a new dataset. Shown as an artifact. Key: `LAST_RUN`.

---

**`Last Sample Images Count`** `string`

Short badge with the number of images the latest run sampled, such as 10 images sampled. Shown on the node as a badge. Selecting the badge opens `LAST_RUN`. Key: `LAST_SAMPLE_IMAGES_COUNT`.

---

**`All Sampled Assets`** `dataset`

ID of the dataset containing all images sampled by this node across runs. Hidden from the flow editor. Key: `ALL_SAMPLED_ASSETS`.

---

## JSON config

Machine-readable node interface for automation and advanced usage.

#### Show JSON

```json
{
  "name": "Random sample",
  "description": "Draws a random sample of images from a source dataset, with their annotations. Images drawn in earlier runs are skipped, so each run returns new ones. The Sample output always holds only the latest sample, and a destination dataset, if set, collects every sample.",
  "category": "Sample",
  "namespace": "ovalbee",
  "templateKey": "sample/random_sample",
  "version": "v1",
  "inputs": [
    {
      "key": "SRC_DATASET",
      "label": "From dataset",
      "type": "dataset",
      "description": "Source dataset the assets are drawn from. Assets drawn in earlier runs are skipped, so each run returns new ones.",
      "required": true,
      "default": null,
      "visibleWhen": null,
      "options": {
        "creatable": false
      }
    },
    {
      "key": "DST_DATASET",
      "label": "Destination dataset",
      "type": "dataset",
      "description": "Dataset that collects every sample - each run adds its images to it. Leave empty to keep only the Sample output.",
      "required": false,
      "default": null,
      "visibleWhen": null
    },
    {
      "key": "SAMPLE_SIZE",
      "label": "Sample size",
      "type": "number",
      "description": "Number of assets to draw. Fewer are returned when the source has no unseen assets left.",
      "required": true,
      "default": 10,
      "visibleWhen": null,
      "options": {
        "type": "integer",
        "min": 1,
        "step": 1
      }
    }
  ],
  "outputs": [
    {
      "key": "LAST_RUN",
      "label": "Sample",
      "type": "dataset",
      "description": "Dataset with the images drawn by the latest run, named after the source dataset. A rerun writes a new version of it, and a new source starts a new dataset.",
      "artifact": true,
      "badge": false,
      "badgeOpens": null,
      "hidden": false
    },
    {
      "key": "LAST_SAMPLE_IMAGES_COUNT",
      "label": "Last Sample Images Count",
      "type": "string",
      "description": "Short badge with the number of images the latest run sampled, such as 10 images sampled.",
      "artifact": false,
      "badge": true,
      "badgeOpens": "LAST_RUN",
      "hidden": false
    },
    {
      "key": "ALL_SAMPLED_ASSETS",
      "label": "All Sampled Assets",
      "type": "dataset",
      "description": "ID of the dataset containing all images sampled by this node across runs.",
      "artifact": false,
      "badge": false,
      "badgeOpens": null,
      "hidden": true
    }
  ]
}
```