Implementation:Explodinggradients Ragas Dataset Constructor

Knowledge Sources	Domains	Last Updated
explodinggradients/ragas	LLM Evaluation, Data Management	2026-02-10

Overview

The Dataset Constructor creates and manages typed, list-like evaluation dataset containers backed by pluggable storage backends in the Ragas evaluation toolkit.

Description

The Dataset class is a concrete subclass of DataTable that provides a Python list-like interface for managing evaluation data entries. It supports optional Pydantic model validation, multiple storage backends resolved via a string registry or direct instance injection, and lifecycle operations including save(), load(), reload(), and to_pandas(). The DataTable base class (lines 31-455) implements all the core logic, while Dataset (lines 458-465) sets DATATABLE_TYPE = "Dataset" to route backend calls to the correct storage namespace.

Usage

Use the Dataset constructor when:

Creating a new evaluation dataset for storing test inputs and expected outputs
Loading a previously saved dataset from local CSV, JSONL, or other backends
Iterating over evaluation rows to feed into metrics or experiment functions
Converting evaluation data to pandas DataFrames for exploratory analysis
Splitting data into training and test sets for metric alignment

Code Reference

Source Location: src/ragas/dataset.py, lines 458-465 (Dataset class), lines 31-455 (DataTable base class)

Signature:

class Dataset(DataTable[T]):
    DATATABLE_TYPE = "Dataset"

# DataTable constructor (inherited by Dataset):
def __init__(
    self,
    name: str,
    backend: Union[BaseBackend, str],
    data_model: Optional[Type[T]] = None,
    data: Optional[List[Any]] = None,
    **kwargs,
)

Import:

from ragas import Dataset

Key Methods:

Method	Signature	Description
`__init__`	`(name, backend, data_model=None, data=None, **kwargs)`	Initialize a dataset with a name, backend, and optional data model
`append`	`(item: Union[Dict, BaseModel]) -> None`	Add a validated entry to the dataset
`save`	`() -> None`	Persist the dataset to the configured backend
`load`	`(name, backend, data_model=None, **kwargs) -> Dataset`	Class method to load a dataset from a backend
`to_pandas`	`() -> DataFrame`	Convert all entries to a pandas DataFrame
`from_pandas`	`(dataframe, name, backend, data_model=None, **kwargs) -> Dataset`	Class method to create a dataset from a DataFrame
`reload`	`() -> None`	Refresh in-memory data from the backend
`train_test_split`	`(test_size=0.2, random_state=None) -> Tuple[DataTable, DataTable]`	Split into training and test sets
`validate_with`	`(data_model: Type[T]) -> Self`	Apply Pydantic validation to an unvalidated dataset
`__iter__`	`() -> Iterator`	Iterate over all dataset entries
`__len__`	`() -> int`	Return the number of entries
`__getitem__`	`(index) -> Union[Dict, T]`	Access an entry by index

I/O Contract

Inputs:

Parameter	Type	Required	Description
`name`	`str`	Yes	Identifier for the dataset (used in backend storage)
`backend`	`Union[BaseBackend, str]`	Yes	Backend instance or registry name (e.g., `"local/csv"`, `"local/jsonl"`)
`data_model`	`Optional[Type[T]]`	No	Pydantic BaseModel subclass for entry validation
`data`	`Optional[List[Any]]`	No	Initial data to populate the dataset
`**kwargs`	`Any`	No	Additional arguments passed to the backend constructor (e.g., `root_dir` for local backends)

Outputs:

Output	Type	Description
Dataset instance	`Dataset[T]`	A list-like, iterable container of evaluation data entries
`.to_pandas()` return	`pandas.DataFrame`	Tabular representation of all entries
`.save()` return	`None`	Persists data to the configured backend (side effect)

Usage Examples

Creating a dataset with a string backend:

from ragas import Dataset

# Create a dataset backed by local CSV storage
dataset = Dataset("my_eval_data", "local/csv", root_dir="./data")

# Add evaluation entries as dictionaries
dataset.append({"user_input": "What is Python?", "response": "A programming language."})
dataset.append({"user_input": "What is 2+2?", "response": "4"})

# Save to disk
dataset.save()

Creating a typed dataset with a Pydantic model:

from pydantic import BaseModel
from ragas import Dataset

class EvalRow(BaseModel):
    user_input: str
    response: str
    reference: str

# Create a typed dataset with validation
dataset = Dataset("typed_eval", "local/csv", data_model=EvalRow, root_dir="./data")

# Entries are validated against EvalRow on append
dataset.append(EvalRow(
    user_input="What is Python?",
    response="A programming language.",
    reference="Python is a high-level programming language."
))

dataset.save()

Loading an existing dataset:

from ragas import Dataset

# Load without validation (returns dicts)
dataset = Dataset.load("my_eval_data", "local/csv", root_dir="./data")

# Load with validation (returns model instances)
typed_dataset = Dataset.load("typed_eval", "local/csv", data_model=EvalRow, root_dir="./data")

# Iterate over entries
for row in dataset:
    print(row["user_input"])

Converting to pandas for analysis:

from ragas import Dataset

dataset = Dataset.load("my_eval_data", "local/csv", root_dir="./data")
df = dataset.to_pandas()
print(df.describe())

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment