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)[源代码]

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.

示例

Create an RDBStorage instance with customized pool_size and timeout 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)
参数
  • url (str) – URL of the storage.

  • engine_kwargs (Optional[Dict[str, Any]]) – 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 (Optional[int]) – Interval to record the heartbeat. It is recorded every interval seconds.

  • grace_period (Optional[int]) – Grace period before a running trial is failed from the last heartbeat. If it is None, the grace period will be 2 * heartbeat_interval.

  • failed_trial_callback (Optional[Callable[[optuna.Study, optuna.trial._frozen.FrozenTrial], 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 and FrozenTrial.

    注解

    The procedure to fail existing stale trials is called just before asking the study for a new trial.

返回类型

None

注解

If you use MySQL, pool_pre_ping will be set to True by default to prevent connection timeout. You can turn it off with engine_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.

引发
  • ValueError – If the given heartbeat_interval or grace_period is not a positive integer.

  • RuntimeError – If the a process that was failed by heartbeat but was actually running.

参数
  • url (str) –

  • engine_kwargs (Optional[Dict[str, Any]]) –

  • skip_compatibility_check (bool) –

  • heartbeat_interval (Optional[int]) –

  • grace_period (Optional[int]) –

  • failed_trial_callback (Optional[Callable[[optuna.Study, optuna.trial._frozen.FrozenTrial], None]]) –

返回类型

None

Methods

check_trial_is_updatable(trial_id, trial_state)

Check whether a trial state is updatable.

create_new_study([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.

fail_stale_trials(study_id)

Fail stale trials.

get_all_study_summaries()

Read a list of StudySummary objects.

get_all_trials(study_id[, deepcopy, states])

Read all trials in a study.

get_all_versions()

Return the schema version list.

get_best_trial(study_id)

Return the trial with the best value in a study.

get_current_version()

Return the schema version currently used by this storage.

get_failed_trial_callback()

Get the failed trial callback function.

get_head_version()

Return the latest schema version.

get_heartbeat_interval()

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_id_from_trial_id(trial_id)

Read the ID of a study to which a trial belongs.

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.

get_trial_id_from_study_id_trial_number(…)

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.

is_heartbeat_enabled()

Check whether the storage enables the heartbeat.

read_trials_from_remote_storage(study_id)

Make an internal cache of trials up-to-date.

record_heartbeat(trial_id)

Record the heartbeat of the trial.

remove_session()

Removes the current session.

set_study_directions(study_id, directions)

Register optimization problem directions to a study.

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(trial_id, state)

Update the state 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.

set_trial_values(trial_id, values)

Set return values of an objective function.

upgrade()

Upgrade the storage schema.

check_trial_is_updatable(trial_id, trial_state)

Check whether a trial state is updatable.

参数
引发

RuntimeError – If the trial is already finished.

返回类型

None

create_new_study(study_name=None)[源代码]

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.

参数

study_name (Optional[str]) – Name of the new study to create.

返回

ID of the created study.

引发

optuna.exceptions.DuplicatedStudyError – If a study with the same study_name already exists.

返回类型

int

create_new_trial(study_id, template_trial=None)[源代码]

Create and add a new trial to a study.

The returned trial ID is unique among all current and deleted trials.

参数
  • study_id (int) – ID of the study.

  • template_trial (Optional[optuna.trial._frozen.FrozenTrial]) – Template FronzenTrial with default user-attributes, system-attributes, intermediate-values, and a state.

返回

ID of the created trial.

引发

KeyError – If no study with the matching study_id exists.

返回类型

int

delete_study(study_id)[源代码]

Delete a study.

参数

study_id (int) – ID of the study.

引发

KeyError – If no study with the matching study_id exists.

返回类型

None

fail_stale_trials(study_id)[源代码]

Fail stale trials.

The running trials whose heartbeat has not been updated for a long time will be failed, that is, those states will be changed to FAIL. The grace period is 2 * heartbeat_interval.

参数

study_id (int) – ID of the related study.

返回

List of trial IDs of the failed trials.

返回类型

List[int]

get_all_study_summaries()[源代码]

Read a list of StudySummary objects.

返回

A list of StudySummary objects.

返回类型

List[optuna._study_summary.StudySummary]

get_all_trials(study_id, deepcopy=True, states=None)[源代码]

Read all trials in a study.

参数
  • study_id (int) – ID of the study.

  • deepcopy (bool) – Whether to copy the list of trials before returning. Set to True if you intend to update the list or elements of the list.

  • states (Optional[Tuple[optuna.trial._state.TrialState, ...]]) – Trial states to filter on. If None, include all states.

返回

List of trials in the study.

引发

KeyError – If no study with the matching study_id exists.

返回类型

List[optuna.trial._frozen.FrozenTrial]

get_all_versions()[源代码]

Return the schema version list.

返回类型

List[str]

get_best_trial(study_id)[源代码]

Return the trial with the best value in a study.

This method is valid only during single-objective optimization.

参数

study_id (int) – ID of the study.

返回

The trial with the best objective value among all finished trials in the study.

引发
  • 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.

返回类型

optuna.trial._frozen.FrozenTrial

get_current_version()[源代码]

Return the schema version currently used by this storage.

返回类型

str

get_failed_trial_callback()[源代码]

Get the failed trial callback function.

返回

The failed trial callback function if it is set, otherwise None.

返回类型

Optional[Callable[[optuna.study.Study, optuna.trial._frozen.FrozenTrial], None]]

get_head_version()[源代码]

Return the latest schema version.

返回类型

str

get_heartbeat_interval()[源代码]

Get the heartbeat interval if it is set.

返回

The heartbeat interval if it is set, otherwise None.

返回类型

Optional[int]

get_n_trials(study_id, state=None)

Count the number of trials in a study.

参数
返回

Number of trials in the study.

引发

KeyError – If no study with the matching study_id exists.

返回类型

int

get_study_directions(study_id)[源代码]

Read whether a study maximizes or minimizes an objective.

参数

study_id (int) – ID of a study.

返回

Optimization directions list of the study.

引发

KeyError – If no study with the matching study_id exists.

返回类型

List[optuna._study_direction.StudyDirection]

get_study_id_from_name(study_name)[源代码]

Read the ID of a study.

参数

study_name (str) – Name of the study.

返回

ID of the study.

引发

KeyError – If no study with the matching study_name exists.

返回类型

int

get_study_id_from_trial_id(trial_id)[源代码]

Read the ID of a study to which a trial belongs.

参数

trial_id (int) – ID of the trial.

返回

ID of the study.

引发

KeyError – If no trial with the matching trial_id exists.

返回类型

int

get_study_name_from_id(study_id)[源代码]

Read the study name of a study.

参数

study_id (int) – ID of the study.

返回

Name of the study.

引发

KeyError – If no study with the matching study_id exists.

返回类型

str

get_study_system_attrs(study_id)[源代码]

Read the optuna-internal attributes of a study.

参数

study_id (int) – ID of the study.

返回

Dictionary with the optuna-internal attributes of the study.

引发

KeyError – If no study with the matching study_id exists.

返回类型

Dict[str, Any]

get_study_user_attrs(study_id)[源代码]

Read the user-defined attributes of a study.

参数

study_id (int) – ID of the study.

返回

Dictionary with the user attributes of the study.

引发

KeyError – If no study with the matching study_id exists.

返回类型

Dict[str, Any]

get_trial(trial_id)[源代码]

Read a trial.

参数

trial_id (int) – ID of the trial.

返回

Trial with a matching trial ID.

引发

KeyError – If no trial with the matching trial_id exists.

返回类型

optuna.trial._frozen.FrozenTrial

get_trial_id_from_study_id_trial_number(study_id, trial_number)[源代码]

Read the trial id of a trial.

参数
  • study_id (int) – ID of the study.

  • trial_number (int) – Number of the trial.

返回

ID of the trial.

引发

KeyError – If no trial with the matching study_id and trial_number exists.

返回类型

int

get_trial_number_from_id(trial_id)[源代码]

Read the trial number of a trial.

注解

The trial number is only unique within a study, and is sequential.

参数

trial_id (int) – ID of the trial.

返回

Number of the trial.

引发

KeyError – If no trial with the matching trial_id exists.

返回类型

int

get_trial_param(trial_id, param_name)[源代码]

Read the parameter of a trial.

参数
  • trial_id (int) – ID of the trial.

  • param_name (str) – Name of the parameter.

返回

Internal representation of the parameter.

引发

KeyError – If no trial with the matching trial_id exists. If no such parameter exists.

返回类型

float

get_trial_params(trial_id)

Read the parameter dictionary of a trial.

参数

trial_id (int) – ID of the trial.

返回

Dictionary of a parameters. Keys are parameter names and values are internal representations of the parameter values.

引发

KeyError – If no trial with the matching trial_id exists.

返回类型

Dict[str, Any]

get_trial_system_attrs(trial_id)[源代码]

Read the optuna-internal attributes of a trial.

参数

trial_id (int) – ID of the trial.

返回

Dictionary with the optuna-internal attributes of the trial.

引发

KeyError – If no trial with the matching trial_id exists.

返回类型

Dict[str, Any]

get_trial_user_attrs(trial_id)[源代码]

Read the user-defined attributes of a trial.

参数

trial_id (int) – ID of the trial.

返回

Dictionary with the user-defined attributes of the trial.

引发

KeyError – If no trial with the matching trial_id exists.

返回类型

Dict[str, Any]

is_heartbeat_enabled()

Check whether the storage enables the heartbeat.

返回

True if the storage supports the heartbeat and the return value of get_heartbeat_interval() is an integer, otherwise False.

返回类型

bool

read_trials_from_remote_storage(study_id)[源代码]

Make an internal cache of trials up-to-date.

参数

study_id (int) – ID of the study.

引发

KeyError – If no study with the matching study_id exists.

返回类型

None

record_heartbeat(trial_id)[源代码]

Record the heartbeat of the trial.

参数

trial_id (int) – ID of the trial.

返回类型

None

remove_session()[源代码]

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.

返回类型

None

set_study_directions(study_id, directions)[源代码]

Register optimization problem directions to a study.

参数
引发
  • KeyError – If no study with the matching study_id exists.

  • ValueError – If the directions are already set and the each coordinate of passed directions is the opposite direction or NOT_SET.

返回类型

None

set_study_system_attr(study_id, key, value)[源代码]

Register an optuna-internal attribute to a study.

This method overwrites any existing attribute.

参数
  • study_id (int) – ID of the study.

  • key (str) – Attribute key.

  • value (Any) – Attribute value. It should be JSON serializable.

引发

KeyError – If no study with the matching study_id exists.

返回类型

None

set_study_user_attr(study_id, key, value)[源代码]

Register a user-defined attribute to a study.

This method overwrites any existing attribute.

参数
  • study_id (int) – ID of the study.

  • key (str) – Attribute key.

  • value (Any) – Attribute value. It should be JSON serializable.

引发

KeyError – If no study with the matching study_id exists.

返回类型

None

set_trial_intermediate_value(trial_id, step, intermediate_value)[源代码]

Report an intermediate value of an objective function.

This method overwrites any existing intermediate value associated with the given step.

参数
  • trial_id (int) – ID of the trial.

  • step (int) – Step of the trial (e.g., the epoch when training a neural network).

  • intermediate_value (float) – Intermediate value corresponding to the step.

引发
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.

返回类型

None

set_trial_param(trial_id, param_name, param_value_internal, distribution)[源代码]

Set a parameter to a trial.

参数
  • trial_id (int) – ID of the trial.

  • param_name (str) – Name of the parameter.

  • param_value_internal (float) – Internal representation of the parameter value.

  • distribution (optuna.distributions.BaseDistribution) – Sampled distribution of the parameter.

引发
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.

返回类型

None

set_trial_state(trial_id, state)[源代码]

Update the state of a trial.

参数
返回

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 of RUNNING trial to RUNNING.

引发
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.

返回类型

bool

set_trial_system_attr(trial_id, key, value)[源代码]

Set an optuna-internal attribute to a trial.

This method overwrites any existing attribute.

参数
  • trial_id (int) – ID of the trial.

  • key (str) – Attribute key.

  • value (Any) – Attribute value. It should be JSON serializable.

引发
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.

返回类型

None

set_trial_user_attr(trial_id, key, value)[源代码]

Set a user-defined attribute to a trial.

This method overwrites any existing attribute.

参数
  • trial_id (int) – ID of the trial.

  • key (str) – Attribute key.

  • value (Any) – Attribute value. It should be JSON serializable.

引发
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.

返回类型

None

set_trial_values(trial_id, values)[源代码]

Set return values of an objective function.

This method overwrites any existing trial values.

参数
  • trial_id (int) – ID of the trial.

  • values (Sequence[float]) – Values of the objective function.

引发
  • KeyError – If no trial with the matching trial_id exists.

  • RuntimeError – If the trial is already finished.

返回类型

None

upgrade()[源代码]

Upgrade the storage schema.

返回类型

None