Clarified confusion between model identity (UUID) versus model name for database operations. store uses UUID for replacement, load by name fetches the first match. Creating FairModel('New Name') generates a new UUID and thus a new, distinct model.

Author: coreyneskey

pyfair/utility/database.py

@@ -35,28 +35,33 @@ class FairDatabase(object):
     >>> query_output_string = db2.query('SELECT uuid, json FROM model')
 
     """
+
     def __init__(self, path):
         self._path = pathlib.Path(path)
         self._initialize()
 
     def _initialize(self):
         """Initialize database with tables if necessary."""
         with sqlite3.connect(self._path) as conn:
-            conn.execute("""CREATE TABLE IF NOT EXISTS models (
+            conn.execute(
+                """CREATE TABLE IF NOT EXISTS models (
                 uuid string,
                 name string,
                 creation_date text NOT NULL,
                 json string NOT NULL,
                 CONSTRAINT model_pk PRIMARY KEY (uuid));
-            """)
-            conn.execute("""CREATE TABLE IF NOT EXISTS results (
+            """
+            )
+            conn.execute(
+                """CREATE TABLE IF NOT EXISTS results (
                 uuid string,
                 mean real NOT NULL,
                 stdev real NOT NULL,
                 min real NOT NULL,
                 max real NOT NULL,
                 CONSTRAINT results_pk PRIMARY KEY (uuid));
-            """)
+            """
+            )
 
     def _dict_factory(self, cursor, row):
         """Convenience function for sqlite queries"""
@@ -69,17 +74,24 @@ def _dict_factory(self, cursor, row):
     def load(self, name_or_uuid):
         """Loads a model from the database
 
-        This takes a name or UUID and looks up the model using a UUID
-        function using self._load_uuid(). If that fails, it attempts to
-        look of the funciton by name using self._load_name().
+        This takes a name or UUID. It first attempts to interpret the input
+        as a UUID and load directly. If that fails (e.g., the input is not
+        in UUID format), it attempts to load by model name.
+
+        If loading by name, the method retrieves the *first* model found
+        matching that name (based on internal database ordering). If multiple
+        distinct models (with different UUIDs) share the same name, this
+        may not be the most recent or a specific version unless names are
+        managed uniquely. For precise loading, using the model's UUID is
+        recommended.
 
         Parameters
         ----------
         name_or_uuid : str
             The name model or its UUID string
 
         Returns
-        -------
+        ------
         FairModel or FairMetaModel
             The model or metamodel corresponding with the input UUID string
             or input name string.
@@ -89,6 +101,9 @@ def load(self, name_or_uuid):
         FairException
             When the UUID or name does not exist in the database
 
+        See Also
+        --------
+        store : Method for storing models. Note its behavior regarding UUIDs.
         """
         # If it is a valid UUID
         try:
@@ -110,9 +125,9 @@ def _load_name(self, name):
             cursor.execute("SELECT uuid FROM models WHERE name = ?", (name,))
             result = cursor.fetchone()
             if not result:
-                raise FairException('Name for model not found.')
+                raise FairException("Name for model not found.")
             # Use model UUID query to load via _load_uuid function
-            model = self._load_uuid(result['uuid'])
+            model = self._load_uuid(result["uuid"])
             return model
 
     def _load_uuid(self, uuid):
@@ -125,17 +140,17 @@ def _load_uuid(self, uuid):
             cursor.execute("SELECT * FROM models WHERE uuid = ?", (uuid,))
             model_data = cursor.fetchone()
             if not model_data:
-                raise FairException('UUID for model not found.')
+                raise FairException("UUID for model not found.")
             # Load model type based on json
-            json_data = model_data['json']
+            json_data = model_data["json"]
             model_param_data = json.loads(json_data)
-            model_type = model_param_data['type']
-            if model_type == 'FairMetaModel':
+            model_type = model_param_data["type"]
+            if model_type == "FairMetaModel":
                 model = FairMetaModel.read_json(json_data)
-            elif model_type == 'FairModel':
+            elif model_type == "FairModel":
                 model = FairModel.read_json(json_data)
             else:
-                raise FairException('Unrecognized model type.')
+                raise FairException("Unrecognized model type.")
         return model
 
     def store(self, model_or_metamodel):
@@ -147,10 +162,31 @@ def store(self, model_or_metamodel):
         statistics about the risk are stored in the 'results' table, and 2)
         the model data is stored in the 'models' table.
 
+        The model's UUID (obtained via `model_or_metamodel.get_uuid()`) is used
+        as the primary key in the database.
+
+        If a record with the same UUID already exists, `INSERT OR REPLACE`
+        semantics are used, meaning the existing record for that UUID will be
+        overwritten with the data from the model being stored. This is how
+        updates to an existing model (identified by its UUID) should be performed:
+        load the model, modify the loaded instance, then store that same instance.
+
+        Creating a new `FairModel()` instance results in a new, unique UUID.
+        Storing such a new instance will always create a new record or replace
+        an existing record *only if that new UUID happened to match an old one*
+        (which is astronomically unlikely for standard UUIDs).
+        It does not replace based on model name.
+
+        Parameters
+        ----------
+        model_or_metamodel : FairModel or FairMetaModel
+            The model instance to store.
+
         Raises
         ------
         FairException
             If model or metamodel is not yet calculated
+            and thus not ready for storage.
 
         """
         m = model_or_metamodel
@@ -160,30 +196,25 @@ def store(self, model_or_metamodel):
         # Export from model
         meta = json.loads(m.to_json())
         json_data = m.to_json()
-        results = m.export_results()['Risk']
+        results = m.export_results()["Risk"]
         # Write to database
         with sqlite3.connect(self._path) as conn:
             cursor = conn.cursor()
             # Write model data
             cursor.execute(
                 """INSERT OR REPLACE INTO models VALUES(?, ?, ?, ?)""",
-                (
-                    meta['model_uuid'], 
-                    meta['name'], 
-                    meta['creation_date'], 
-                    json_data
-                )
+                (meta["model_uuid"], meta["name"], meta["creation_date"], json_data),
             )
             # Write cached results
             cursor.execute(
                 """INSERT OR REPLACE INTO results VALUES(?, ?, ?, ?, ?)""",
                 (
-                    meta['model_uuid'], 
+                    meta["model_uuid"],
                     results.mean(axis=0),
                     results.std(axis=0),
                     results.min(axis=0),
-                    results.max(axis=0)
-                )
+                    results.max(axis=0),
+                ),
             )
         # Vacuum database
         conn = sqlite3.connect(self._path)