Note

This is the documentation for the current state of the development branch of Qiskit Experiments. The documentation or APIs here can change prior to being released.

ExperimentService

class ExperimentService(*args, **kwargs)[source]

Interface definition for experiment database service.

This interface defines the methods needed by ExperimentData to interact with an experiment database service, whether local or remote.

Note

Some of the type signatures of the methods of this protocol could change in future versions of Qiskit Experiments without a transition period.

Attributes

options

Return service options dictionary.

Returns:

Dictionary of service options

Methods

analysis_result(result_id, json_decoder=None)[source]

Retrieve a single analysis result from the database.

Parameters:

  • result_id (str) – Analysis result ID

  • json_decoder (type[JSONDecoder] | None) – Custom JSON decoder

Returns:

Retrieved analysis result data

Return type:

DbAnalysisResultData

analysis_results(experiment_id=None, limit=None, json_decoder=None, **filters)[source]

Query analysis results from the database.

Parameters:

  • experiment_id (str | None) – Filter by experiment ID

  • limit (int | None) – Maximum number of results

  • json_decoder (type[JSONDecoder] | None) – Custom JSON decoder

  • **filters – Additional filter parameters

Returns:

List of analysis results

Return type:

list

create_analysis_results(data, blocking=True, max_workers=100, json_encoder=None)[source]

Create multiple analysis results in the database.

Parameters:

  • data (list) – List of analysis result data to save

  • blocking (bool) – Whether to wait for completion

  • max_workers (int) – Maximum number of worker threads

  • json_encoder (type[JSONEncoder] | None) – Custom JSON encoder

Returns:

Status dictionary or handler object

create_figures(experiment_id, figure_list, blocking=True, max_workers=100)[source]

Create multiple figures in the database.

Parameters:

  • experiment_id (str) – Experiment ID

  • figure_list (list) – List of (figure, name) tuples

  • blocking (bool) – Whether to wait for completion

  • max_workers (int) – Maximum number of worker threads

Returns:

Status dictionary or handler object

create_or_update_analysis_result(data, json_encoder=None, create=True, max_attempts=3)[source]

Create or update an analysis result in the database.

Parameters:

  • data (DbAnalysisResultData) – Analysis result data to save

  • json_encoder (type[JSONEncoder] | None) – Custom JSON encoder

  • create (bool) – Whether to attempt create first

  • max_attempts (int) – Maximum number of attempts

Returns:

Analysis result ID

Return type:

str

create_or_update_experiment(data, json_encoder=None, create=True, max_attempts=3, **kwargs)[source]

Create or update an experiment in the database.

Parameters:

  • data (DbExperimentData) – Experiment data to save

  • json_encoder (type[JSONEncoder] | None) – Custom JSON encoder

  • create (bool) – Whether to attempt create first

  • max_attempts (int) – Maximum number of attempts

  • **kwargs – Additional parameters

Returns:

Experiment data of the experiment

Return type:

DbExperimentData

create_or_update_figure(experiment_id, figure, figure_name=None, create=True, max_attempts=3)[source]

Create or update a figure in the database.

Parameters:

  • experiment_id (str) – Experiment ID

  • figure (bytes | str) – Figure data or file path

  • figure_name (str | None) – Name for the figure

  • create (bool) – Whether to attempt create first

  • max_attempts (int) – Maximum number of attempts

Returns:

Tuple of (figure_name, size)

Return type:

tuple

delete_analysis_result(result_id)[source]

Delete an analysis result from the database.

Parameters:

result_id (str) – Analysis result ID to delete

delete_experiment(experiment_id)[source]

Delete an experiment from the database.

Parameters:

experiment_id (str) – Experiment ID to delete

delete_figure(experiment_id, figure_name)[source]

Delete a figure from the database.

Parameters:

  • experiment_id (str) – Experiment ID

  • figure_name (str) – Name of the figure to delete

experiment(experiment_id, json_decoder=None)[source]

Retrieve a single experiment from the database.

Parameters:

  • experiment_id (str) – Experiment ID

  • json_decoder (type[JSONDecoder] | None) – Custom JSON decoder

Returns:

Retrieved experiment data

Return type:

DbExperimentData

figure(experiment_id, figure_name, file_name=None)[source]

Retrieve a figure from the database.

Parameters:

  • experiment_id (str) – Experiment ID

  • figure_name (str) – Name of the figure

  • file_name (str | None) – Optional local file to save to

Returns:

Figure bytes if file_name is None, otherwise size written

Return type:

bytes | int

file_delete(experiment_id, file_name)[source]

Delete a file from the database

Parameters:

  • experiment_id (str) – Experiment ID

  • file_name (str) – Name for the file

file_download(experiment_id, file_name, json_decoder=None)[source]

Download a file from the database.

Parameters:

  • experiment_id (str) – Experiment ID

  • file_name (str) – Name of the file

  • json_decoder (type[JSONDecoder] | None) – Custom JSON decoder

Returns:

Deserialized file data

Return type:

dict

file_upload(experiment_id, file_name, file_data, json_encoder=None)[source]

Upload a file to the database.

Parameters:

  • experiment_id (str) – Experiment ID

  • file_name (str) – Name for the file

  • file_data (dict | str | bytes) – File data (dict or JSON string or file bytes)

  • json_encoder (type[JSONEncoder] | None) – Custom JSON encoder

files(experiment_id)[source]

Retrieve the file list for an experiment.

Parameters:

experiment_id (str) – Experiment ID

Returns:

Dictionary with file list metadata

Return type:

dict