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]

RDBバックエンド用のストレージクラス。

ライブラリ利用者はこのクラスをインスタンス化できますが、このクラスが提供する属性は直接アクセスすることを想定していません。

使用例

カスタマイズした pool_size と timeout 設定で RDBStorage インスタンスを作成します。

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。
engine_kwargs (dict[str, Any] | None) – sqlalchemy.engine.create_engine 関数に渡すキーワード引数の辞書。
skip_compatibility_check (bool) – スキーマ互換性チェックをスキップするフラグ（True で有効）。
heartbeat_interval (int | None) –
ハートビートを記録する間隔（秒単位）。 interval ごとに記録されます。 heartbeat_interval は None または正の整数である必要があります。

Note

ハートビートは optimize() で使用することを想定しています。 ask() と tell() を使用する場合は機能しません。
grace_period (int | None) – 最後のハートビートから実行中のトライアルが失敗するまでの猶予期間。 grace_period は None または正の整数である必要があります。 None の場合、猶予期間は 2 * heartbeat_interval になります。
failed_trial_callback (Callable[['optuna.study.Study', FrozenTrial], None] | None) –
古いトライアルが失敗した後に呼び出されるコールバック関数。関数は以下の型の2つのパラメータをこの順序で受け取る必要があります: Study と FrozenTrial。

Note

既存の古いトライアルを失敗させる処理は、新しいトライアルを要求する直前に行われます。
skip_table_creation (bool) – テーブル作成をスキップするフラグ（True で有効）。

Note

MySQLを使用する場合、接続タイムアウトを防ぐためにデフォルトで pool_pre_ping が True に設定されます。 engine_kwargs['pool_pre_ping']=False で無効にできますが、目的関数の実行時間が MySQL の wait_timeout より長い場合は有効にしておくことをお勧めします。

Note

並列最適化に SQLite3 を使用することは推奨しません。詳細は FAQ SQLite3 で並列最適化を実行する際に発生するエラーを解決するには？を参照してください。

Note

主にクラスタ環境では、実行中のトライアルが予期せず終了することがよくあります。トライアルの失敗を検出したい場合は、ハートビート機構を使用してください。 heartbeat_interval、grace_period、failed_trial_callback を使用ケースに応じて適切に設定してください。詳細はチュートリアルおよび Exampleページを参照してください。

See also

RetryFailedTrialCallback を使用して、ハートビートで検出された失敗したトライアルを自動的に再試行できます。

メソッド

`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.
`get_all_studies`()	Read a list of `FrozenStudy` 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_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.
`record_heartbeat`(trial_id)	Record the heartbeat of the trial.
`remove_session`()	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)

トライアルの状態が更新可能かどうかを確認します。

Parameters:

trial_id (int) – トライアルのID。エラーメッセージの表示にのみ使用されます。
trial_state (TrialState) – チェックするトライアルの状態。

Raises:

UpdateFinishedTrialError – トライアルが既に終了している場合。

Return type:

None

create_new_study(directions, study_name=None)[source]

名前から新しいスタディを作成します。

名前が指定されていない場合、ストレージクラスが名前を生成します。返されるスタディIDは、現在および削除済みのすべてのスタディの中で一意です。

Parameters:

directions (Sequence[StudyDirection]) – 要素が MAXIMIZE または MINIMIZE のいずれかである方向のシーケンス。
study_name (str | None) – 作成する新しいスタディの名前。

Returns:

作成されたスタディのID。

Raises:

optuna.exceptions.DuplicatedStudyError – 同じ study_name を持つスタディが既に存在する場合。

Return type:

int

create_new_trial(study_id, template_trial=None)[source]

スタディに新しいトライアルを作成して追加します。

返されるトライアルIDは、現在および削除済みのすべてのトライアルの中で一意です。

Parameters:

study_id (int) – スタディのID。
template_trial (FrozenTrial | None) – デフォルトのユーザー属性、システム属性、中間値、および状態を持つテンプレート FrozenTrial。

Returns:

作成されたトライアルのID。

Raises:

KeyError – 一致する study_id を持つスタディが存在しない場合。

Return type:

int

delete_study(study_id)[source]

スタディを削除します。

Parameters:: study_id (int) – スタディのID。
Raises:: KeyError – 一致する study_id を持つスタディが存在しない場合。
Return type:: None

get_all_studies()[source]

FrozenStudy オブジェクトのリストを読み込みます。

Returns:: study_id でソートされた FrozenStudy オブジェクトのリスト。
Return type:: list[FrozenStudy]

get_all_trials(study_id, deepcopy=True, states=None)[source]

スタディ内のすべてのトライアルを読み込みます。

Parameters:

study_id (int) – スタディのID。
deepcopy (bool) – リストを返す前にコピーするかどうか。リストまたはその要素を更新する予定がある場合は True に設定します。
states (Container[TrialState] | None) – フィルタリングするトライアルの状態。 None の場合、すべての状態を含めます。

Returns:

スタディ内のトライアルのリスト、trial_id でソート。

Raises:

KeyError – 一致する study_id を持つスタディが存在しない場合。

Return type:

list[FrozenTrial]

get_all_versions()[source]

スキーマバージョンのリストを返します。

Return type:: list[str]

get_best_trial(study_id)[source]

スタディ内で最も良い値を持つトライアルを返します。

このメソッドは単一目的最適化の場合にのみ有効です。

Parameters:

study_id (int) – スタディのID。

Returns:

スタディ内のすべての終了したトライアルの中で最も良い目的値を持つトライアル。

Raises:

KeyError – 一致する study_id を持つスタディが存在しない場合。
RuntimeError – スタディに複数の方向がある場合。
ValueError – トライアルが完了していない場合。

Return type:

FrozenTrial

get_current_version()[source]

このストレージで現在使用されているスキーマバージョンを返します。

Return type:: str

get_failed_trial_callback()[source]

失敗したトライアルのコールバック関数を取得します。

Returns:: 設定されている場合は失敗したトライアルのコールバック関数、設定されていない場合は None。
Return type:: Callable[[Study, FrozenTrial], None] | None

get_head_version()[source]

最新のスキーマバージョンを返します。

Return type:: str

get_heartbeat_interval()[source]

ハートビート間隔を取得します。

Returns:: 設定されている場合はハートビート間隔、設定されていない場合は None。
Return type:: int | None

get_n_trials(study_id, state=None)

スタディ内のトライアル数をカウントします。

Parameters:

study_id (int) – スタディのID。
state (tuple[TrialState, ...] | TrialState | None) – フィルタリングするトライアル状態。None の場合はすべての状態を含めます。

Returns:

スタディ内のトライアル数。

Raises:

KeyError – 一致する study_id を持つスタディが存在しない場合。

Return type:

int

get_study_directions(study_id)[source]

スタディが目的値を最大化または最小化するかを読み取ります。

Parameters:: study_id (int) – スタディのID。
Returns:: スタディの最適化方向のリスト。
Raises:: KeyError – 一致する study_id を持つスタディが存在しない場合。
Return type:: list[StudyDirection]

get_study_id_from_name(study_name)[source]

スタディのIDを読み取ります。

Parameters:: study_name (str) – スタディの名前。
Returns:: スタディのID。
Raises:: KeyError – 一致する study_name を持つスタディが存在しない場合。
Return type:: int

get_study_name_from_id(study_id)[source]

スタディの名前を読み取ります。

Parameters:: study_id (int) – スタディのID。
Returns:: スタディの名前。
Raises:: KeyError – 一致する study_id を持つスタディが存在しない場合。
Return type:: str

get_study_system_attrs(study_id)[source]

スタディの optuna 内部属性を読み取ります。

Parameters:: study_id (int) – スタディのID。
Returns:: スタディの optuna 内部属性の辞書。
Raises:: KeyError – 一致する study_id を持つスタディが存在しない場合。
Return type:: dict[str, Any]

get_study_user_attrs(study_id)[source]

スタディのユーザー定義属性を読み取ります。

Parameters:: study_id (int) – スタディのID。
Returns:: スタディのユーザー属性の辞書。
Raises:: KeyError – 一致する study_id を持つスタディが存在しない場合。
Return type:: dict[str, Any]

get_trial(trial_id)[source]

トライアルを読み取ります。

Parameters:: trial_id (int) – トライアルのID。
Returns:: 一致するトライアルIDを持つトライアル。
Raises:: KeyError – 一致する trial_id を持つトライアルが存在しない場合。
Return type:: FrozenTrial

get_trial_id_from_study_id_trial_number(study_id, trial_number)[source]

トライアルのIDを読み取ります。

Parameters:

study_id (int) – スタディのID。
trial_number (int) – トライアルの番号。

Returns:

トライアルのID。

Raises:

KeyError – 一致する study_id と trial_number を持つトライアルが存在しない場合。

Return type:

int

get_trial_number_from_id(trial_id)

トライアルの番号を読み取ります。

Note

トライアル番号はスタディ内で一意であり、連番です。

Parameters:: trial_id (int) – トライアルのID。
Returns:: トライアルの番号。
Raises:: KeyError – 一致する trial_id を持つトライアルが存在しない場合。
Return type:: int

get_trial_param(trial_id, param_name)[source]

トライアルのパラメータを読み取ります。

Parameters:

trial_id (int) – トライアルのID。
param_name (str) – パラメータの名前。

Returns:

パラメータの内部表現。

Raises:

KeyError – 一致する trial_id を持つトライアルが存在しない場合。

Return type:

float

パラメータが存在しない場合。

get_trial_params(trial_id)

トライアルのパラメータ辞書を読み取ります。

Parameters:: trial_id (int) – トライアルのID。
Returns:: パラメータの辞書。キーはパラメータ名、値はパラメータ値の外部表現。
Raises:: KeyError – 一致する trial_id を持つトライアルが存在しない場合。
Return type:: dict[str, Any]

get_trial_system_attrs(trial_id)[source]

トライアルの optuna 内部属性を読み取ります。

Parameters:: trial_id (int) – トライアルのID。
Returns:: トライアルの optuna 内部属性の辞書。
Raises:: KeyError – 一致する trial_id を持つトライアルが存在しない場合。
Return type:: dict[str, Any]

get_trial_user_attrs(trial_id)[source]

トライアルのユーザー定義属性を読み取ります。

Parameters:: trial_id (int) – トライアルのID。
Returns:: トライアルのユーザー定義属性の辞書。
Raises:: KeyError – 一致する trial_id を持つトライアルが存在しない場合。
Return type:: dict[str, Any]

record_heartbeat(trial_id)[source]

トライアルのハートビートを記録します。

Parameters:: trial_id (int) – トライアルのID。
Return type:: None

remove_session()[source]

現在のセッションを削除します。

セッションは SQLAlchemy の ThreadLocalRegistry に各スレッドごとに保存されます。このメソッドは、現在のスレッドに関連付けられたセッションを閉じて削除します。特に、マルチスレッド環境では、このメソッドを 各スレッドから 呼び出すことが重要です。そうしないと、すべてのセッションと関連する DB 接続がガベージコレクタによって時折呼び出されるスレッドによって破壊されます。デフォルトでは、SQLite 接続は接続を作成したスレッド以外のスレッドから操作することは許可されていません。したがって、各スレッドから明示的に接続を閉じる必要があります。

Return type:: None

set_study_system_attr(study_id, key, value)[source]

スタディに optuna 内部属性を登録します。

このメソッドは既存の属性を上書きします。

Parameters:

study_id (int) – スタディのID。
key (str) – 属性キー。
value (Mapping[str, JSONSerializable] | Sequence[JSONSerializable] | str | int | float | bool | None) – 属性値。JSON シリアライズ可能である必要があります。

Raises:

KeyError – 一致する study_id を持つスタディが存在しない場合。

Return type:

None

set_study_user_attr(study_id, key, value)[source]

スタディにユーザー定義属性を登録します。

このメソッドは既存の属性を上書きします。

Parameters:

study_id (int) – スタディのID。
key (str) – 属性キー。
value (Any) – 属性値。JSON シリアライズ可能である必要があります。

Raises:

KeyError – 一致する study_id を持つスタディが存在しない場合。

Return type:

None

set_trial_intermediate_value(trial_id, step, intermediate_value)[source]

目的関数の中間値を報告します。

このメソッドは、指定されたステップに関連付けられた既存の中間値を上書きします。

Parameters:

trial_id (int) – トライアルのID。
step (int) – トライアルのステップ（例：ニューラルネットワークのトレーニング時のエポック）。
intermediate_value (float) – ステップに対応する中間値。

Raises:

KeyError – 一致する trial_id を持つトライアルが存在しない場合。
UpdateFinishedTrialError – トライアルがすでに終了している場合。

Return type:

None

set_trial_param(trial_id, param_name, param_value_internal, distribution)[source]

トライアルにパラメータを設定します。

Parameters:

trial_id (int) – トライアルのID。
param_name (str) – パラメータ名。
param_value_internal (float) – パラメータ値の内部表現。
distribution (BaseDistribution) – パラメータのサンプリング分布。

Raises:

KeyError – 一致する trial_id を持つトライアルが存在しない場合。
UpdateFinishedTrialError – トライアルがすでに終了している場合。

Return type:

None

set_trial_state_values(trial_id, state, values=None)[source]

トライアルの状態と値を更新します。

目的関数の戻り値を values 引数に設定します。 values 引数が None でない場合、このメソッドは既存のトライアル値を上書きします。

Parameters:

trial_id (int) – トライアルのID。
state (TrialState) – トライアルの新しい状態。
values (Sequence[float] | None) – 目的関数の値。

Returns:

状態が正常に更新された場合は True。状態が変更されなかった場合は False。この場合、このメソッドが RUNNING のトライアルの状態を RUNNING に更新しようとした場合に発生します。

Raises:

KeyError – 一致する trial_id を持つトライアルが存在しない場合。
UpdateFinishedTrialError – トライアルがすでに終了している場合。

Return type:

bool

set_trial_system_attr(trial_id, key, value)[source]

トライアルに optuna 内部属性を設定します。

このメソッドは既存の属性を上書きします。

Parameters:

trial_id (int) – トライアルのID。
key (str) – 属性キー。
value (Mapping[str, JSONSerializable] | Sequence[JSONSerializable] | str | int | float | bool | None) – 属性値。JSON シリアライズ可能である必要があります。

Raises:

KeyError – 一致する trial_id を持つトライアルが存在しない場合。
UpdateFinishedTrialError – トライアルがすでに終了している場合。

Return type:

None

set_trial_user_attr(trial_id, key, value)[source]

トライアルにユーザー定義属性を設定します。

このメソッドは既存の属性を上書きします。

Parameters:

trial_id (int) – トライアルのID。
key (str) – 属性キー。
value (Any) – 属性値。JSON シリアライズ可能である必要があります。

Raises:

KeyError – 一致する trial_id を持つトライアルが存在しない場合。
UpdateFinishedTrialError – トライアルがすでに終了している場合。

Return type:

None

upgrade()[source]

ストレージスキーマをアップグレードします。

Return type:: None