Saving/Resuming Study with RDB Backend

An RDB backend enables persistent experiments (i.e., to save and resume a study) as well as access to history of studies. In addition, we can run multi-node optimization tasks with this feature, which is described in Easy Parallelization.

In this section, let’s try simple examples running on a local environment with SQLite DB.

Note

You can also utilize other RDB backends, e.g., PostgreSQL or MySQL, by setting the storage argument to the DB’s URL. Please refer to SQLAlchemy’s document for how to set up the URL.

New Study

We can create a persistent study by calling create_study() function as follows. An SQLite file example.db is automatically initialized with a new study record.

import logging
import sys

import optuna

# Add stream handler of stdout to show the messages
optuna.logging.get_logger("optuna").addHandler(logging.StreamHandler(sys.stdout))
study_name = "example-study"  # Unique identifier of the study.
storage_name = f"sqlite:///{study_name}.db"
study = optuna.create_study(study_name=study_name, storage=storage_name)

A new study created in RDB with name: example-study

To run a study, call optimize() method passing an objective function.

def objective(trial):
    x = trial.suggest_float("x", -10, 10)
    return (x - 2) ** 2


study.optimize(objective, n_trials=3)

Trial 0 finished with value: 1.1619114698854875 and parameters: {'x': 0.9220800262146138}. Best is trial 0 with value: 1.1619114698854875.
Trial 1 finished with value: 1.0759075999820262 and parameters: {'x': 0.9627403410996713}. Best is trial 1 with value: 1.0759075999820262.
Trial 2 finished with value: 132.06905444150175 and parameters: {'x': -9.4921301089703}. Best is trial 1 with value: 1.0759075999820262.

Resume Study

To resume a study, instantiate a Study object passing the study name example-study and the DB URL sqlite:///example-study.db.

study = optuna.create_study(study_name=study_name, storage=storage_name, load_if_exists=True)
study.optimize(objective, n_trials=3)

Using an existing study with `study_name='example-study'` instead of creating a new one.
Trial 3 finished with value: 128.50867509453496 and parameters: {'x': -9.336166684313307}. Best is trial 1 with value: 1.0759075999820262.
Trial 4 finished with value: 57.38298432775601 and parameters: {'x': 9.575155729604244}. Best is trial 1 with value: 1.0759075999820262.
Trial 5 finished with value: 4.531185615518382 and parameters: {'x': 4.128658172539307}. Best is trial 1 with value: 1.0759075999820262.

Note that the storage doesn’t store the state of the instance of samplers and pruners. When we resume a study with a sampler whose seed argument is specified for reproducibility, you need to restore the sampler with using pickle as follows:

import pickle

# Save the sampler with pickle to be loaded later.
with open("sampler.pkl", "wb") as fout:
    pickle.dump(study.sampler, fout)

restored_sampler = pickle.load(open("sampler.pkl", "rb"))
study = optuna.create_study(
    study_name=study_name, storage=storage_name, load_if_exists=True, sampler=restored_sampler
)
study.optimize(objective, n_trials=3)

Experimental History

Note that this section requires the installation of Pandas:

$ pip install pandas

We can access histories of studies and trials via the Study class. For example, we can get all trials of example-study as:

study = optuna.create_study(study_name=study_name, storage=storage_name, load_if_exists=True)
df = study.trials_dataframe(attrs=("number", "value", "params", "state"))

Using an existing study with `study_name='example-study'` instead of creating a new one.

The method trials_dataframe() returns a pandas dataframe like:

print(df)

   number       value  params_x     state
0       0    1.161911  0.922080  COMPLETE
1       1    1.075908  0.962740  COMPLETE
2       2  132.069054 -9.492130  COMPLETE
3       3  128.508675 -9.336167  COMPLETE
4       4   57.382984  9.575156  COMPLETE
5       5    4.531186  4.128658  COMPLETE

A Study object also provides properties such as trials, best_value, best_params (see also Lightweight, versatile, and platform agnostic architecture).

print("Best params: ", study.best_params)
print("Best value: ", study.best_value)
print("Best Trial: ", study.best_trial)
print("Trials: ", study.trials)

Best params:  {'x': 0.9627403410996713}
Best value:  1.0759075999820262
Best Trial:  FrozenTrial(number=1, state=<TrialState.COMPLETE: 1>, values=[1.0759075999820262], datetime_start=datetime.datetime(2026, 9, 7, 5, 20, 51, 216075), datetime_complete=datetime.datetime(2026, 9, 7, 5, 20, 51, 238529), params={'x': 0.9627403410996713}, user_attrs={}, system_attrs={}, intermediate_values={}, distributions={'x': FloatDistribution(high=10.0, log=False, low=-10.0, step=None)}, trial_id=2, value=None)
Trials:  [FrozenTrial(number=0, state=<TrialState.COMPLETE: 1>, values=[1.1619114698854875], datetime_start=datetime.datetime(2026, 9, 7, 5, 20, 51, 163662), datetime_complete=datetime.datetime(2026, 9, 7, 5, 20, 51, 198549), params={'x': 0.9220800262146138}, user_attrs={}, system_attrs={}, intermediate_values={}, distributions={'x': FloatDistribution(high=10.0, log=False, low=-10.0, step=None)}, trial_id=1, value=None), FrozenTrial(number=1, state=<TrialState.COMPLETE: 1>, values=[1.0759075999820262], datetime_start=datetime.datetime(2026, 9, 7, 5, 20, 51, 216075), datetime_complete=datetime.datetime(2026, 9, 7, 5, 20, 51, 238529), params={'x': 0.9627403410996713}, user_attrs={}, system_attrs={}, intermediate_values={}, distributions={'x': FloatDistribution(high=10.0, log=False, low=-10.0, step=None)}, trial_id=2, value=None), FrozenTrial(number=2, state=<TrialState.COMPLETE: 1>, values=[132.06905444150175], datetime_start=datetime.datetime(2026, 9, 7, 5, 20, 51, 252858), datetime_complete=datetime.datetime(2026, 9, 7, 5, 20, 51, 273853), params={'x': -9.4921301089703}, user_attrs={}, system_attrs={}, intermediate_values={}, distributions={'x': FloatDistribution(high=10.0, log=False, low=-10.0, step=None)}, trial_id=3, value=None), FrozenTrial(number=3, state=<TrialState.COMPLETE: 1>, values=[128.50867509453496], datetime_start=datetime.datetime(2026, 9, 7, 5, 20, 51, 322722), datetime_complete=datetime.datetime(2026, 9, 7, 5, 20, 51, 352525), params={'x': -9.336166684313307}, user_attrs={}, system_attrs={}, intermediate_values={}, distributions={'x': FloatDistribution(high=10.0, log=False, low=-10.0, step=None)}, trial_id=4, value=None), FrozenTrial(number=4, state=<TrialState.COMPLETE: 1>, values=[57.38298432775601], datetime_start=datetime.datetime(2026, 9, 7, 5, 20, 51, 366618), datetime_complete=datetime.datetime(2026, 9, 7, 5, 20, 51, 388425), params={'x': 9.575155729604244}, user_attrs={}, system_attrs={}, intermediate_values={}, distributions={'x': FloatDistribution(high=10.0, log=False, low=-10.0, step=None)}, trial_id=5, value=None), FrozenTrial(number=5, state=<TrialState.COMPLETE: 1>, values=[4.531185615518382], datetime_start=datetime.datetime(2026, 9, 7, 5, 20, 51, 400846), datetime_complete=datetime.datetime(2026, 9, 7, 5, 20, 51, 421717), params={'x': 4.128658172539307}, user_attrs={}, system_attrs={}, intermediate_values={}, distributions={'x': FloatDistribution(high=10.0, log=False, low=-10.0, step=None)}, trial_id=6, value=None)]