StorageInterface

Module: iqm.station_control.interface.storage_interface

class StorageInterface

Bases: Serializable

Interface for managing the persistence and retrieval of quantum data.

This interface handles all passive operations: querying historical records, managing metadata for observations and sequences, and retrieving characterization data.

Generic query methods (query_observations(), query_runs(), etc.) utilize a Django-inspired double-underscore lookup syntax: field__lookup=value. Note double-underscore in the name, to separate field names like dut_field from lookup types like in.

As a convenience, when no lookup type is provided (like in dut_label="foo"), the lookup type is assumed to be exact (dut_label__exact="foo"). Other supported lookup types are:

• range: Range test (inclusive).

  For example, created_timestamp__range=(datetime(2023, 10, 12), datetime(2024, 10, 14))

• in: In a given iterable; often a list, tuple, or queryset.

  For example, dut_field__in=["QB1.frequency", "gates.measure.constant.QB2.frequency"]

• icontains: Case-insensitive containment test.

  For example, origin_uri__icontains="local"

• overlap: Returns objects where the data shares any results with the values passed.

  For example, tags__overlap=["calibration=good", "2023-12-04"]

• contains: The returned objects will be those where the values passed are a subset of the data.

  For example, tags__contains=["calibration=good", "2023-12-04"]

• isnull: Takes either True or False, which correspond to SQL queries of IS NULL and IS NOT NULL, respectively.

  For example, end_timestamp__isnull=False

In addition to model fields (like “dut_label”, “dut_field”, “created_timestamp”, “invalid”, etc.), all of our generic query methods accept also following shared query parameters:

• latest: str. Return only the latest item for this field, based on “created_timestamp”.

  For example, latest="invalid" would return only one result (latest “created_timestamp”) for each different “invalid” value in the database. Thus, maximum three results would be returned, one for each invalid value of True, False, and None.

• order_by: str. Prefix with “-” for descending order, for example “-created_timestamp”.

• limit: int: Default 20. If 0 (or negative number) is given, then pagination is not used, i.e. limit=infinity.

• offset: int. Default 0.

Our generic query methods are not fully generalized yet, thus not all fields and lookup types are supported. Check query method’s own documentation for details about currently supported query parameters.

Generic query methods will return a list of objects, but with additional (optional) “meta” attribute, which contains metadata, like pagination details. The client can ignore this data, or use it to implement pagination logic for example to fetch all results available.

Methods

create_observation_set	Create an observation set in the database.
create_observations	Create observations in the database.
create_sequence_metadata	Create and persist new sequence metadata in the database.
finalize_observation_set	Finalize an observation set in the database.
get_calibration_set	Get a calibration set from the database for the given calibration set ID.
get_calibration_set_quality_metric_set	Get the latest quality metric set for the given calibration set ID.
get_chip_design_record	Get the chip design record for the given DUT label.
get_dut_fields	Get available fields for a specific DUT label from the database.
get_dynamic_quantum_architecture	Get the dynamic quantum architecture for the given calibration set ID.
get_observation_set	Get an observation set from the database.
get_observation_set_observations	Get the constituent observations of an observation set from the database.
get_run	Get run data from the database.
get_sequence_result	Get sequence result from the database.
query_observation_sets	Query observation sets from the database.
query_observations	Query observations from the database.
query_runs	Query runs from the database.
query_sequence_metadatas	Query sequence metadatas from the database.
save_sequence_result	Save sequence result in the database.
update_observation_set	Update an observation set in the database.
update_observations	Update observations in the database.

abstractmethod get_chip_design_record(dut_label)

Get the chip design record for the given DUT label.

Parameters:

dut_label (str)

Return type:

dict[str, Any]

abstractmethod get_run(run_id)

Get run data from the database.

Parameters:

run_id (str | UUID)

Return type:

RunData

abstractmethod query_runs(**kwargs)

Query runs from the database.

Runs are queried by the given query parameters. Currently supported query parameters:

• run_id: uuid.UUID

• run_id__in: list[uuid.UUID]

• sweep_id: uuid.UUID

• sweep_id__in: list[uuid.UUID]

• username: str

• username__in: list[str]

• username__contains: str

• username__icontains: str

• experiment_label: str

• experiment_label__in: list[str]

• experiment_label__contains: str

• experiment_label__icontains: str

• experiment_name: str

• experiment_name__in: list[str]

• experiment_name__contains: str

• experiment_name__icontains: str

• software_version_set_id: int

• software_version_set_id__in: list[int]

• begin_timestamp__range: tuple[datetime, datetime]

• end_timestamp__range: tuple[datetime, datetime]

• end_timestamp__isnull: bool

Returns:

Queried runs with some query related metadata.

Return type:

ListWithMeta[RunLite]

abstractmethod create_observations(observation_definitions)

Create observations in the database.

Parameters:

observation_definitions (Sequence[ObservationDefinition]) – A sequence of observation definitions, each containing the content of the observation which will be created.

Returns:

Created observations, each including also the database created fields like ID and timestamps.

Return type:

ListWithMeta[ObservationData]

abstractmethod query_observations(**kwargs)

Query observations from the database.

Observations are queried by the given query parameters. Currently supported query parameters:

• observation_id: int

• observation_id__in: list[int]

• dut_label: str

• dut_field: str

• dut_field__in: list[str]

• tags__overlap: list[str]

• tags__contains: list[str]

• invalid: bool

• source__run_id__in: list[uuid.UUID]

• source__sequence_id__in: list[uuid.UUID]

• source__type: str

• observation_set_ids__overlap: list[uuid.UUID]

• observation_set_ids__contains: list[uuid.UUID]

Returns:

Queried observations with some query related metadata.

Return type:

ListWithMeta[ObservationData]

abstractmethod update_observations(observation_updates)

Update observations in the database.

Parameters:

observation_updates (Sequence[ObservationUpdate]) – A sequence of observation updates, each containing the content of the observation which will be updated.

Returns:

Updated observations, each including also the database created fields like ID and timestamps.

Return type:

list[ObservationData]

abstractmethod query_observation_sets(**kwargs)

Query observation sets from the database.

Observation sets are queried by the given query parameters. Currently supported query parameters:

• observation_set_id: UUID

• observation_set_id__in: list[UUID]

• observation_set_type: Literal[“calibration-set”, “generic-set”, “quality-metric-set”]

• describes_id: UUID

• describes_id__in: list[UUID]

• invalid: bool

• created_timestamp__range: tuple[datetime, datetime]

• dut_label: str

• dut_label__in: list[str]

Returns:

Queried observation sets with some query related metadata

Return type:

ListWithMeta[ObservationSetData]

abstractmethod create_observation_set(observation_set_definition)

Create an observation set in the database.

Parameters:

observation_set_definition (ObservationSetDefinition) – The content of the observation set to be created.

Returns:

The content of the observation set.

Raises:

IQMError – If creation failed.

Return type:

ObservationSetData

abstractmethod get_observation_set(observation_set_id)

Get an observation set from the database.

Parameters:

observation_set_id (str | UUID) – Observation set to retrieve.

Returns:

The content of the observation set.

Raises:

IQMError – If retrieval failed.

Return type:

ObservationSetData

abstractmethod update_observation_set(observation_set_update)

Update an observation set in the database.

Parameters:

observation_set_update (ObservationSetUpdate) – The content of the observation set to be updated.

Returns:

The content of the observation set.

Raises:

IQMError – If updating failed.

Return type:

ObservationSetData

abstractmethod finalize_observation_set(observation_set_id)

Finalize an observation set in the database.

A finalized set is nearly immutable, allowing to change only invalid flag after finalization.

Parameters:

observation_set_id (str | UUID) – Observation set to finalize.

Raises:

IQMError – If finalization failed.

Return type:

None

abstractmethod get_observation_set_observations(observation_set_id)

Get the constituent observations of an observation set from the database.

Parameters:

observation_set_id (str | UUID) – UUID of the observation set to retrieve.

Returns:

Observations belonging to the given observation set.

Return type:

list[ObservationData]

abstractmethod get_calibration_set(calibration_set_id)

Get a calibration set from the database for the given calibration set ID.

Parameters:

calibration_set_id (str | UUID | Literal['default'])

Return type:

ObservationSetWithObservationData

abstractmethod get_dynamic_quantum_architecture(calibration_set_id)

Get the dynamic quantum architecture for the given calibration set ID.

Returns:

Dynamic quantum architecture of the quantum computer for the given calibration set ID.

Parameters:

calibration_set_id (str | UUID | Literal['default'])

Return type:

DynamicQuantumArchitecture

abstractmethod get_calibration_set_quality_metric_set(calibration_set_id)

Get the latest quality metric set for the given calibration set ID.

Parameters:

calibration_set_id (str | UUID | Literal['default'])

Return type:

ObservationSetWithObservationData

abstractmethod get_dut_fields(dut_label)

Get available fields for a specific DUT label from the database.

Scans every field ever observed for the DUT, independent of any actual query need. Prefer filtering observations directly (e.g. by tags or observation set) instead of enumerating all dut fields upfront.

This method will be removed in a future release.

Parameters:

dut_label (str)

Return type:

list[DutFieldData]

abstractmethod query_sequence_metadatas(**kwargs)

Query sequence metadatas from the database.

Sequence metadatas are queried by the given query parameters. Currently supported query parameters:

• origin_id: str

• origin_id__in: list[str]

• origin_uri: str

• origin_uri__icontains: str

• created_timestamp__range: tuple[datetime, datetime]

Returns:

Sequence metadatas with some query related metadata.

Return type:

ListWithMeta[SequenceMetadataData]

abstractmethod create_sequence_metadata(sequence_metadata_definition)

Create and persist new sequence metadata in the database.

Parameters:

sequence_metadata_definition (SequenceMetadataDefinition)

Return type:

SequenceMetadataData

abstractmethod save_sequence_result(sequence_result_definition)

Save sequence result in the database.

This method creates the object if it doesn’t exist and completely replaces the “data” and “final” if it does. Timestamps are assigned by the database. “modified_timestamp” is not set on initial creation, but it’s updated on each subsequent call.

Parameters:

sequence_result_definition (SequenceResultDefinition)

Return type:

SequenceResultData

abstractmethod get_sequence_result(sequence_id)

Get sequence result from the database.

Parameters:

sequence_id (str | UUID)

Return type:

SequenceResultData

Inheritance