Update UDA warnings and docs

maarten-ic · olivhoenen · commit 3230a0ded32f · 2025-10-13T13:55:00.000+02:00
diff --git a/docs/source/lazy_loading.rst b/docs/source/lazy_loading.rst
@@ -90,4 +90,13 @@ Lazy loading of data may speed up your programs, but also comes with some limita
     more efficient to do a full :code:`get()` or :code:`get_slice()` when you intend to
     use most of the data stored in an IDS.
 5.  When using IMAS-Python with remote data access (i.e. the UDA backend), a full
-    :code:`get()` or :code:`get_slice()` is more efficient than lazy loading.
+    :code:`get()` or :code:`get_slice()` may be more efficient than using lazy loading.
+
+    It is recommended to add the parameter ``;cache_mode=none`` [#cache_mode_none]_ to
+    the end of a UDA IMAS URI when using lazy loading: otherwise the UDA backend will
+    still load the full IDS from the remote server.
+
+
+.. [#cache_mode_none] The option ``cache_mode=none`` requires IMAS Core version 5.5.1 or
+    newer, and a remote UDA server with `IMAS UDA-Plugins
+    <https://github.com/iterorganization/UDA-Plugins>`__ version 1.7.0 or newer.
diff --git a/imas/backends/imas_core/db_entry_al.py b/imas/backends/imas_core/db_entry_al.py
@@ -9,6 +9,8 @@
 from typing import Any, Deque, List, Optional, Union
 from urllib.parse import urlparse
 
+from packaging.version import Version
+
 from imas.backends.db_entry_impl import GetSampleParameters, GetSliceParameters
 from imas.db_entry import DBEntryImpl
 from imas.exception import DataEntryException, LowlevelError
@@ -187,13 +189,7 @@ def get(
         if lazy and self.backend == "ascii":
             raise RuntimeError("Lazy loading is not supported by the ASCII backend.")
         if self.backend == "uda":
-            # cache_mode=none doesn't work right now, so the warning won't recommend it
-            # See: https://jira.iter.org/browse/IMAS-5644
-            if lazy and self._querydict.get("cache_mode") != "none":
-                logger.warning(
-                    "The UDA backend will load all IDS data from the remote server. "
-                    "Lazy loading with the UDA backend may therefore still be slow."
-                )
+            self._check_uda_warnings(lazy)
 
         # Mixing contexts can be problematic, ensure all lazy contexts are closed:
         self._clear_lazy_ctx_cache()
@@ -350,3 +346,28 @@ def list_all_occurrences(self, ids_name: str) -> List[int]:
                 "Access Layer 5.1 or newer is required."
             ) from None
         return occurrence_list
+
+    def _check_uda_warnings(self, lazy: bool) -> None:
+        """Various checks / warnings for the UDA backend."""
+        cache_mode = self._querydict.get("cache_mode")
+        if lazy and cache_mode != "none":
+            # cache_mode=none requires imas core 5.5.1 or newer, and a recent enough UDA
+            # server plugin (which we cannot check...)
+            cache_mode_hint = ""
+            if ll_interface._al_version >= Version("5.5.1"):
+                cache_mode_hint = (
+                    "\nYou may add the parameter ';cache_mode=none' to the IMAS URI "
+                    "to avoid loading all of the data from the remote server."
+                )
+            logger.warning(
+                "The UDA backend will load all IDS data from the remote server. "
+                "Lazy loading with the UDA backend may therefore still be slow.%s",
+                cache_mode_hint,
+            )
+
+        if cache_mode == "none" and ll_interface._al_version < Version("5.5.1"):
+            logger.warning(
+                "UDA option 'cache_mode=None' may not work correctly with "
+                "IMAS Core version %s.",
+                ll_interface._al_version,
+            )
