# `Aludel.Datasets`
[🔗](https://github.com/ccarvalho-eng/aludel/blob/main/lib/aludel/datasets.ex#L1)

Context for reusable evaluation datasets and suite population.

# `change_dataset`

```elixir
@spec change_dataset(Aludel.Datasets.Dataset.t(), map()) :: Ecto.Changeset.t()
```

Returns a dataset changeset without persisting it.

# `change_entry`

```elixir
@spec change_entry(Aludel.Datasets.DatasetEntry.t(), map()) :: Ecto.Changeset.t()
```

Returns an entry changeset without persisting it.

# `create_dataset`

```elixir
@spec create_dataset(map()) ::
  {:ok, Aludel.Datasets.Dataset.t()} | {:error, Ecto.Changeset.t()}
```

Creates a reusable dataset from the supplied attributes.

# `create_entry`

```elixir
@spec create_entry(Aludel.Datasets.Dataset.t(), map()) ::
  {:ok, Aludel.Datasets.DatasetEntry.t()} | {:error, Ecto.Changeset.t()}
```

Creates an ordered entry in a dataset.

When no position is supplied, the entry is appended atomically. Concurrent
inserts serialize on the dataset row so they cannot claim the same position.

# `delete_dataset`

```elixir
@spec delete_dataset(Aludel.Datasets.Dataset.t()) ::
  {:ok, Aludel.Datasets.Dataset.t()} | {:error, Ecto.Changeset.t()}
```

Deletes a dataset.

Associated entries are removed according to the repository constraint.

# `delete_entry`

```elixir
@spec delete_entry(Aludel.Datasets.DatasetEntry.t()) ::
  {:ok, Aludel.Datasets.DatasetEntry.t()} | {:error, Ecto.Changeset.t()}
```

Deletes a dataset entry.

# `get_dataset`

```elixir
@spec get_dataset(binary()) :: Aludel.Datasets.Dataset.t() | nil
```

Fetches a dataset by ID.

Returns `nil` for an invalid UUID or a dataset that does not exist.

# `get_dataset!`

```elixir
@spec get_dataset!(binary()) :: Aludel.Datasets.Dataset.t()
```

Fetches a dataset by ID and raises `Ecto.NoResultsError` when it does not exist.

# `get_dataset_with_entries!`

```elixir
@spec get_dataset_with_entries!(binary()) :: Aludel.Datasets.Dataset.t()
```

Fetches a dataset with its entries preloaded in stable order.

Raises `Ecto.NoResultsError` when the dataset does not exist.

# `get_entry`

```elixir
@spec get_entry(Aludel.Datasets.Dataset.t(), binary()) ::
  Aludel.Datasets.DatasetEntry.t() | nil
```

Fetches an entry by ID within a dataset.

Returns `nil` for an invalid UUID, a missing entry, or an entry owned by a
different dataset.

# `list_datasets`

```elixir
@spec list_datasets() :: [Aludel.Datasets.Dataset.t()]
```

Lists datasets alphabetically by name.

# `list_entries`

```elixir
@spec list_entries(Aludel.Datasets.Dataset.t(), keyword()) :: [
  Aludel.Datasets.DatasetEntry.t()
]
```

Lists a dataset's entries in stable position and insertion order.

Pass `metadata: %{...}` to retain entries whose JSON metadata contains every
supplied key and value.

# `populate_suite`

```elixir
@spec populate_suite(Aludel.Datasets.Dataset.t(), Aludel.Evals.Suite.t()) ::
  {:ok, [Aludel.Evals.TestCase.t()]} | {:error, term()}
```

Copies entries from a dataset into an evaluation suite.

Entries already linked to the suite through `source_dataset_entry_id` are
skipped. The operation is transactional and safe to repeat.

# `update_dataset`

```elixir
@spec update_dataset(Aludel.Datasets.Dataset.t(), map()) ::
  {:ok, Aludel.Datasets.Dataset.t()} | {:error, Ecto.Changeset.t()}
```

Updates a dataset's name, description, or metadata.

# `update_entry`

```elixir
@spec update_entry(Aludel.Datasets.DatasetEntry.t(), map()) ::
  {:ok, Aludel.Datasets.DatasetEntry.t()} | {:error, Ecto.Changeset.t()}
```

Updates an entry while preserving its dataset ownership.

Any `dataset_id` attribute is discarded.

---

*Consult [api-reference.md](api-reference.md) for complete listing*