optuna.storages.RDBStorage
- class optuna.storages.RDBStorage(url, engine_kwargs=None, skip_compatibility_check=False, *, heartbeat_interval=None, grace_period=None, failed_trial_callback=None, skip_table_creation=False)[source]
Storage class for RDB backend.
Note that library users can instantiate this class, but the attributes provided by this class are not supposed to be directly accessed by them.
Example
Create an
RDBStorage
instance with customizedpool_size
andtimeout
settings.import optuna def objective(trial): x = trial.suggest_float("x", -100, 100) return x**2 storage = optuna.storages.RDBStorage( url="sqlite:///:memory:", engine_kwargs={"pool_size": 20, "connect_args": {"timeout": 10}}, ) study = optuna.create_study(storage=storage) study.optimize(objective, n_trials=10)
- Parameters:
url (str) – URL of the storage.
engine_kwargs (dict[str, Any] | None) – A dictionary of keyword arguments that is passed to sqlalchemy.engine.create_engine function.
skip_compatibility_check (bool) – Flag to skip schema compatibility check if set to
True
.heartbeat_interval (int | None) –
Interval to record the heartbeat. It is recorded every
interval
seconds.heartbeat_interval
must beNone
or a positive integer.Note
The heartbeat is supposed to be used with
optimize()
. If you useask()
andtell()
instead, it will not work.grace_period (int | None) – Grace period before a running trial is failed from the last heartbeat.
grace_period
must beNone
or a positive integer. If it isNone
, the grace period will be 2 * heartbeat_interval.failed_trial_callback (Callable[['optuna.study.Study', FrozenTrial], None] | None) –
A callback function that is invoked after failing each stale trial. The function must accept two parameters with the following types in this order:
Study
andFrozenTrial
.Note
The procedure to fail existing stale trials is called just before asking the study for a new trial.
skip_table_creation (bool) – Flag to skip table creation if set to
True
.
Note
If you use MySQL, pool_pre_ping will be set to
True
by default to prevent connection timeout. You can turn it off withengine_kwargs['pool_pre_ping']=False
, but it is recommended to keep the setting if execution time of your objective function is longer than the wait_timeout of your MySQL configuration.Note
We would never recommend SQLite3 for parallel optimization. Please see the FAQ How can I solve the error that occurs when performing parallel optimization with SQLite3? for details.
Note
Mainly in a cluster environment, running trials are often killed unexpectedly. If you want to detect a failure of trials, please use the heartbeat mechanism. Set
heartbeat_interval
,grace_period
, andfailed_trial_callback
appropriately according to your use case. For more details, please refer to the tutorial and Example page.See also
You can use
RetryFailedTrialCallback
to automatically retry failed trials detected by heartbeat.Methods
check_trial_is_updatable
(trial_id, trial_state)Check whether a trial state is updatable.
create_new_study
(directions[, study_name])Create a new study from a name.
create_new_trial
(study_id[, template_trial])Create and add a new trial to a study.
delete_study
(study_id)Delete a study.
Read a list of
FrozenStudy
objects.get_all_trials
(study_id[, deepcopy, states])Read all trials in a study.
Return the schema version list.
get_best_trial
(study_id)Return the trial with the best value in a study.
Return the schema version currently used by this storage.
Get the failed trial callback function.
Return the latest schema version.
Get the heartbeat interval if it is set.
get_n_trials
(study_id[, state])Count the number of trials in a study.
get_study_directions
(study_id)Read whether a study maximizes or minimizes an objective.
get_study_id_from_name
(study_name)Read the ID of a study.
get_study_name_from_id
(study_id)Read the study name of a study.
get_study_system_attrs
(study_id)Read the optuna-internal attributes of a study.
get_study_user_attrs
(study_id)Read the user-defined attributes of a study.
get_trial
(trial_id)Read a trial.
Read the trial ID of a trial.
get_trial_number_from_id
(trial_id)Read the trial number of a trial.
get_trial_param
(trial_id, param_name)Read the parameter of a trial.
get_trial_params
(trial_id)Read the parameter dictionary of a trial.
get_trial_system_attrs
(trial_id)Read the optuna-internal attributes of a trial.
get_trial_user_attrs
(trial_id)Read the user-defined attributes of a trial.
record_heartbeat
(trial_id)Record the heartbeat of the trial.
Removes the current session.
set_study_system_attr
(study_id, key, value)Register an optuna-internal attribute to a study.
set_study_user_attr
(study_id, key, value)Register a user-defined attribute to a study.
set_trial_intermediate_value
(trial_id, step, ...)Report an intermediate value of an objective function.
set_trial_param
(trial_id, param_name, ...)Set a parameter to a trial.
set_trial_state_values
(trial_id, state[, values])Update the state and values of a trial.
set_trial_system_attr
(trial_id, key, value)Set an optuna-internal attribute to a trial.
set_trial_user_attr
(trial_id, key, value)Set a user-defined attribute to a trial.
upgrade
()Upgrade the storage schema.
- check_trial_is_updatable(trial_id, trial_state)
Check whether a trial state is updatable.
- Parameters:
trial_id (int) – ID of the trial. Only used for an error message.
trial_state (TrialState) – Trial state to check.
- Raises:
RuntimeError – If the trial is already finished.
- Return type:
None
- create_new_study(directions, study_name=None)[source]
Create a new study from a name.
If no name is specified, the storage class generates a name. The returned study ID is unique among all current and deleted studies.
- Parameters:
directions (Sequence[StudyDirection]) – A sequence of direction whose element is either
MAXIMIZE
orMINIMIZE
.study_name (str | None) – Name of the new study to create.
- Returns:
ID of the created study.
- Raises:
optuna.exceptions.DuplicatedStudyError – If a study with the same
study_name
already exists.- Return type:
- create_new_trial(study_id, template_trial=None)[source]
Create and add a new trial to a study.
The returned trial ID is unique among all current and deleted trials.
- Parameters:
study_id (int) – ID of the study.
template_trial (FrozenTrial | None) – Template
FrozenTrial
with default user-attributes, system-attributes, intermediate-values, and a state.
- Returns:
ID of the created trial.
- Raises:
KeyError – If no study with the matching
study_id
exists.- Return type:
- get_all_studies()[source]
Read a list of
FrozenStudy
objects.- Returns:
A list of
FrozenStudy
objects, sorted bystudy_id
.- Return type:
list[FrozenStudy]
- get_all_trials(study_id, deepcopy=True, states=None)[source]
Read all trials in a study.
- Parameters:
- Returns:
List of trials in the study, sorted by
trial_id
.- Raises:
KeyError – If no study with the matching
study_id
exists.- Return type:
- get_best_trial(study_id)[source]
Return the trial with the best value in a study.
This method is valid only during single-objective optimization.
- Parameters:
study_id (int) – ID of the study.
- Returns:
The trial with the best objective value among all finished trials in the study.
- Raises:
KeyError – If no study with the matching
study_id
exists.RuntimeError – If the study has more than one direction.
ValueError – If no trials have been completed.
- Return type:
- get_current_version()[source]
Return the schema version currently used by this storage.
- Return type:
- get_failed_trial_callback()[source]
Get the failed trial callback function.
- Returns:
The failed trial callback function if it is set, otherwise
None
.- Return type:
Callable[[Study, FrozenTrial], None] | None
- get_n_trials(study_id, state=None)
Count the number of trials in a study.
- Parameters:
study_id (int) – ID of the study.
state (tuple[TrialState, ...] | TrialState | None) – Trial states to filter on. If
None
, include all states.
- Returns:
Number of trials in the study.
- Raises:
KeyError – If no study with the matching
study_id
exists.- Return type:
- get_study_directions(study_id)[source]
Read whether a study maximizes or minimizes an objective.
- get_trial(trial_id)[source]
Read a trial.
- get_trial_id_from_study_id_trial_number(study_id, trial_number)[source]
Read the trial ID of a trial.
- get_trial_number_from_id(trial_id)
Read the trial number of a trial.
Note
The trial number is only unique within a study, and is sequential.
- get_trial_params(trial_id)
Read the parameter dictionary of a trial.
- record_heartbeat(trial_id)[source]
Record the heartbeat of the trial.
- Parameters:
trial_id (int) – ID of the trial.
- Return type:
None
- remove_session()[source]
Removes the current session.
A session is stored in SQLAlchemy’s ThreadLocalRegistry for each thread. This method closes and removes the session which is associated to the current thread. Particularly, under multi-thread use cases, it is important to call this method from each thread. Otherwise, all sessions and their associated DB connections are destructed by a thread that occasionally invoked the garbage collector. By default, it is not allowed to touch a SQLite connection from threads other than the thread that created the connection. Therefore, we need to explicitly close the connection from each thread.
- Return type:
None
- set_study_system_attr(study_id, key, value)[source]
Register an optuna-internal attribute to a study.
This method overwrites any existing attribute.
- Parameters:
- Raises:
KeyError – If no study with the matching
study_id
exists.- Return type:
None
- set_study_user_attr(study_id, key, value)[source]
Register a user-defined attribute to a study.
This method overwrites any existing attribute.
- set_trial_intermediate_value(trial_id, step, intermediate_value)[source]
Report an intermediate value of an objective function.
This method overwrites any existing intermediate value associated with the given step.
- Parameters:
- Raises:
KeyError – If no trial with the matching
trial_id
exists.RuntimeError – If the trial is already finished.
- Return type:
None
- set_trial_param(trial_id, param_name, param_value_internal, distribution)[source]
Set a parameter to a trial.
- Parameters:
- Raises:
KeyError – If no trial with the matching
trial_id
exists.RuntimeError – If the trial is already finished.
- Return type:
None
- set_trial_state_values(trial_id, state, values=None)[source]
Update the state and values of a trial.
Set return values of an objective function to values argument. If values argument is not
None
, this method overwrites any existing trial values.- Parameters:
trial_id (int) – ID of the trial.
state (TrialState) – New state of the trial.
values (Sequence[float] | None) – Values of the objective function.
- Returns:
True
if the state is successfully updated.False
if the state is kept the same. The latter happens when this method tries to update the state ofRUNNING
trial toRUNNING
.- Raises:
KeyError – If no trial with the matching
trial_id
exists.RuntimeError – If the trial is already finished.
- Return type:
- set_trial_system_attr(trial_id, key, value)[source]
Set an optuna-internal attribute to a trial.
This method overwrites any existing attribute.
- Parameters:
- Raises:
KeyError – If no trial with the matching
trial_id
exists.RuntimeError – If the trial is already finished.
- Return type:
None
- set_trial_user_attr(trial_id, key, value)[source]
Set a user-defined attribute to a trial.
This method overwrites any existing attribute.
- Parameters:
- Raises:
KeyError – If no trial with the matching
trial_id
exists.RuntimeError – If the trial is already finished.
- Return type:
None