Database Service (qiskit_experiments.database_service)

This subpackage contains classes used to define the data structure of an experiment, including its data, metadata, analysis results, and figures, as well as the interface to an experiment database service. An experiment database service allows one to store, retrieve, and query experiment related data.

DbExperimentDataV1 is the main class that defines the structure of experiment data, which consists of the following:

• Results from circuit execution, which is called data in this class. The DbExperimentDataV1.add_data() method allows you to add circuit jobs and job results. If jobs are added, the method asynchronously waits for them to finish and extracts job results. DbExperimentDataV1.data() can then be used to retrieve this data. Note that this data is not saved in the database. It is included in this class only for convenience.

• Experiment metadata. This is a freeform keyword-value dictionary. You can use this to save extra information, such as the physical qubits the experiment operated on, in the database. DbExperimentDataV1.set_metadata() and DbExperimentDataV1.metadata() are methods to set and retrieve metadata, respectively.

• Analysis results. It is likely that some analysis is to be done on the experiment data once the circuit jobs finish, and the result of this analysis can be stored in the database. Similar to DbExperimentDataV1, DbAnalysisResultV1 defines the data structure of an analysis result and provides methods to interface with the database. Being a separate class, DbAnalysisResultV1 allows you to modify an analysis result without modifying the experiment data.

• Figures. Some analysis functions also generate figures, which can also be saved in the database.

DatabaseServiceV1 provides low-level abstract interface for accessing the database, such as DatabaseServiceV1.create_experiment() for creating a new experiment entry and DatabaseServiceV1.update_experiment() for updating an existing entry. DbExperimentDataV1 has methods that wrap around some of these low-level database methods. For example, DbExperimentDataV1.save() calls DatabaseServiceV1.create_experiment() under the cover to save experiment related data. The low-level methods are only expected to be used when you want to interact with the database directly - for example, to retrieve a saved analysis result.

Currently only IBM Quantum provides this database service. See the Experiment module in the IBM Quantum provider for more details.

Classes

DbExperimentData()	Base common type for all versioned DbExperimentData classes.
DbExperimentDataV1([experiment_type, ...])	Class to define and handle experiment data stored in a database.
DbAnalysisResult()	Base common type for all versioned DbAnalysisResult abstract classes.
DbAnalysisResultV1(name, value, ...[, ...])	Class representing an analysis result for an experiment.
DatabaseService()	Base common type for all versioned DatabaseService abstract classes.
DatabaseServiceV1()	Interface for providing experiment database service.

Exceptions

DbExperimentDataError(*message)	Base class for errors raised by experiment service data.
DbExperimentEntryExists(*message)	Errors raised when an experiment entry already exists.
DbExperimentEntryNotFound(*message)	Errors raised when an experiment entry cannot be found.