fmu-sumo 2.3.7__py3-none-any.whl → 2.3.9__py3-none-any.whl

fmu/sumo/explorer/objects/_search_context.py

@@ -1,19 +1,28 @@
+from __future__ import annotations
+
+import json
 import uuid
 import warnings
 from datetime import datetime
 from io import BytesIO
-from typing import Dict, List, Tuple
+from typing import TYPE_CHECKING, Any, Dict, List, Tuple, Union
 
 import deprecation
 import httpx
-from sumo.wrapper import SumoClient
 
-import fmu.sumo.explorer.objects as objects
+from fmu.sumo.explorer import objects
 from fmu.sumo.explorer.cache import LRUCache
 
+if TYPE_CHECKING:
+    from sumo.wrapper import SumoClient
+
+
+# Type aliases
+SelectArg = Union[bool, str, Dict[str, Union[str, List[str]]], List[str]]
+
 
 def _gen_filter_none():
-    def _fn(value):
+    def _fn(_):
         return None, None
 
     return _fn
@@ -128,7 +137,11 @@ _filterspec = {
     "relative_path": [_gen_filter_gen, "file.relative_path.keyword"],
     "tagname": [_gen_filter_gen, "data.tagname.keyword"],
     "dataformat": [_gen_filter_gen, "data.format.keyword"],
-    "iteration": [_gen_filter_gen, "fmu.iteration.name.keyword"],
+    "iteration": [
+        _gen_filter_gen,
+        "fmu.iteration.name.keyword",
+    ],  # FIXME: to be removed
+    "ensemble": [_gen_filter_gen, "fmu.ensemble.name.keyword"],
     "realization": [_gen_filter_gen, "fmu.realization.id"],
     "aggregation": [_gen_filter_gen, "fmu.aggregation.operation.keyword"],
     "stage": [_gen_filter_gen, "fmu.context.stage.keyword"],
@@ -142,6 +155,7 @@ _filterspec = {
     "stratigraphic": [_gen_filter_bool, "data.stratigraphic"],
     "is_observation": [_gen_filter_bool, "data.is_observation"],
     "is_prediction": [_gen_filter_bool, "data.is_prediction"],
+    "standard_result": [_gen_filter_gen, "data.standard_result.name.keyword"],
     "complex": [_gen_filter_complex, None],
     "has": [_gen_filter_none, None],
 }
@@ -211,7 +225,7 @@ class Pit:
         self._id = res.json()["id"]
         return self
 
-    def __exit__(self, exc_type, exc_value, traceback):
+    def __exit__(self, *_):
         if self._id is not None:
             self._sumo.delete("/pit", params={"id": self._id})
             pass
@@ -224,7 +238,7 @@ class Pit:
         self._id = res.json()["id"]
         return self
 
-    async def __aexit__(self, exc_type, exc_value, traceback):
+    async def __aexit__(self, *_):
         if self._id is not None:
             await self._sumo.delete_async("/pit", params={"id": self._id})
             pass
@@ -254,14 +268,34 @@ class SearchContext:
         self._visible = visible
         self._hidden = hidden
         self._field_values = {}
+        self._field_values_and_counts = {}
         self._hits = None
         self._cache = LRUCache(capacity=200)
         self._length = None
-        self._select = {
+        self._select: SelectArg = {
             "excludes": ["fmu.realization.parameters"],
         }
         return
 
+    def __str__(self):
+        length = len(self)
+        if length == 0:
+            return "None"
+        else:
+            preview = [self[i].metadata for i in range(min(5, length))]
+            return f"Data Preview:\n{json.dumps(preview, indent=4)}"
+
+    def __repr__(self):
+        cls = self.__class__.__name__
+        length = len(self)
+        if length == 0:
+            return f"<{cls}: {length} objects>"
+        else:
+            if len(self.classes) == 1:
+                return f"<{cls}: {length} objects of type {self.classes[0]}>"
+            else:
+                return f"<{cls}: {length} objects of types {self.classes}>"
+
     @property
     def _query(self):
         must = self._must[:]
@@ -282,7 +316,7 @@ class SearchContext:
             else:
                 return {"bool": {"must": must, "must_not": must_not}}
 
-    def _to_sumo(self, obj, blob=None):
+    def _to_sumo(self, obj, blob=None) -> objects.Document:
         cls = obj["_source"]["class"]
         if cls == "case":
             return objects.Case(self._sumo, obj)
@@ -295,6 +329,9 @@ class SearchContext:
             "table": objects.Table,
             "cpgrid": objects.CPGrid,
             "cpgrid_property": objects.CPGridProperty,
+            "iteration": objects.Iteration,  # FIXME: to be removed
+            "ensemble": objects.Ensemble,
+            "realization": objects.Realization,
         }.get(cls)
         if constructor is None:
             warnings.warn(f"No constructor for class {cls}")
@@ -319,7 +356,7 @@ class SearchContext:
             self._length = res["count"]
         return self._length
 
-    def __search_all(self, query, size=1000, select=False):
+    def __search_all(self, query, size: int = 1000, select: SelectArg = False):
         all_hits = []
         query = {
             "query": query,
@@ -356,10 +393,12 @@ class SearchContext:
             pass
         return all_hits
 
-    def _search_all(self, select=False):
+    def _search_all(self, select: SelectArg = False):
         return self.__search_all(query=self._query, size=1000, select=select)
 
-    async def __search_all_async(self, query, size=1000, select=False):
+    async def __search_all_async(
+        self, query, size: int = 1000, select: SelectArg = False
+    ):
         all_hits = []
         query = {
             "query": query,
@@ -398,7 +437,7 @@ class SearchContext:
             pass
         return all_hits
 
-    async def _search_all_async(self, select=False):
+    async def _search_all_async(self, select: SelectArg = False):
         return await self.__search_all_async(
             query=self._query, size=1000, select=select
         )
@@ -477,7 +516,7 @@ class SearchContext:
         assert await self.length_async() == 1
         return await self.getitem_async(0)
 
-    def select(self, sel):
+    def select(self, sel) -> SearchContext:
         """Specify what should be returned from elasticsearch.
         Has the side effect of clearing the lru cache.
         sel is either a single string value, a list of string value,
@@ -521,7 +560,7 @@ class SearchContext:
         self._cache.clear()
         return self
 
-    def get_object(self, uuid: str) -> Dict:
+    def get_object(self, uuid: str) -> objects.Document:
         """Get metadata object by uuid
 
         Args:
@@ -549,7 +588,7 @@ class SearchContext:
 
         return self._to_sumo(obj)
 
-    async def get_object_async(self, uuid: str) -> Dict:
+    async def get_object_async(self, uuid: str) -> objects.Document:
         """Get metadata object by uuid
 
         Args:
@@ -579,6 +618,7 @@ class SearchContext:
         return self._to_sumo(obj)
 
     def _maybe_prefetch(self, index):
+        assert isinstance(self._hits, list)
         uuid = self._hits[index]
         if self._cache.has(uuid):
             return
@@ -595,6 +635,7 @@ class SearchContext:
         return
 
     async def _maybe_prefetch_async(self, index):
+        assert isinstance(self._hits, list)
         uuid = self._hits[index]
         if self._cache.has(uuid):
             return
@@ -613,13 +654,13 @@ class SearchContext:
     def get_objects(
         self,
         uuids: List[str],
-        select: List[str] = None,
+        select: SelectArg,
     ) -> List[Dict]:
         size = (
             1000
             if select is False
             else 100
-            if isinstance(select, list)
+            if isinstance(select, (list, dict))
             else 10
         )
         return self.__search_all(
@@ -627,15 +668,13 @@ class SearchContext:
         )
 
     async def get_objects_async(
-        self,
-        uuids: List[str],
-        select: List[str] = None,
+        self, uuids: List[str], select: SelectArg
     ) -> List[Dict]:
         size = (
             1000
             if select is False
             else 100
-            if isinstance(select, list)
+            if isinstance(select, (list, dict))
             else 10
         )
         return await self.__search_all_async(
@@ -763,6 +802,23 @@ class SearchContext:
 
         return all_buckets
 
+    def get_field_values_and_counts(self, field: str) -> Dict[str, int]:
+        """Get List of unique values with occurrence counts for a given field
+
+        Arguments:
+            - field (str): a metadata field
+
+        Returns:
+            A mapping from unique values to count.
+        """
+        if field not in self._field_values_and_counts:
+            buckets = {
+                b["key"]: b["doc_count"] for b in self._get_buckets(field)
+            }
+            self._field_values_and_counts[field] = buckets
+
+        return self._field_values_and_counts[field]
+
     def get_field_values(self, field: str) -> List:
         """Get List of unique values for a given field
 
@@ -792,6 +848,26 @@ class SearchContext:
         """
         return self.get_field_values(field)
 
+    async def get_field_values_and_counts_async(
+        self, field: str
+    ) -> Dict[str, int]:
+        """Get List of unique values with occurrence counts for a given field
+
+        Arguments:
+            - field (str): a metadata field
+
+        Returns:
+            A mapping from unique values to count.
+        """
+        if field not in self._field_values_and_counts:
+            buckets = {
+                b["key"]: b["doc_count"]
+                for b in await self._get_buckets_async(field)
+            }
+            self._field_values_and_counts[field] = buckets
+
+        return self._field_values_and_counts[field]
+
     async def get_field_values_async(self, field: str) -> List:
         """Get List of unique values for a given field
 
@@ -874,17 +950,33 @@ class SearchContext:
         return objects.Cases(self, uuids)
 
     @property
+    @deprecation.deprecated(details="Use the method 'ensembles' instead.")
     def iterations(self):
         """Iterations from current selection."""
         uuids = self.get_field_values("fmu.iteration.uuid.keyword")
         return objects.Iterations(self, uuids)
 
     @property
+    @deprecation.deprecated(
+        details="Use the method 'ensembles_async' instead."
+    )
     async def iterations_async(self):
         """Iterations from current selection."""
         uuids = await self.get_field_values_async("fmu.iteration.uuid.keyword")
         return objects.Iterations(self, uuids)
 
+    @property
+    def ensembles(self):
+        """Ensembles from current selection."""
+        uuids = self.get_field_values("fmu.ensemble.uuid.keyword")
+        return objects.Ensembles(self, uuids)
+
+    @property
+    async def ensembles_async(self):
+        """Ensembles from current selection."""
+        uuids = await self.get_field_values_async("fmu.ensemble.uuid.keyword")
+        return objects.Ensembles(self, uuids)
+
     @property
     def realizations(self):
         """Realizations from current selection."""
@@ -900,8 +992,8 @@ class SearchContext:
         return objects.Realizations(self, uuids)
 
     @property
-    def template_paths(search_context):  # noqa: N805
-        return {obj.template_path for obj in search_context}
+    def template_paths(self) -> List[str]:
+        return {obj.template_path for obj in self}
 
     @property
     def metrics(self):
@@ -987,7 +1079,6 @@ class SearchContext:
             f = filters.get(k)
             if f is None:
                 raise Exception(f"Don't know how to generate filter for {k}")
-                pass
             _must, _must_not = f(v)
             if _must:
                 must.append(_must)
@@ -1023,46 +1114,46 @@ class SearchContext:
         return sc
 
     @property
-    def surfaces(self):
+    def surfaces(self) -> SearchContext:
         return self._context_for_class("surface")
 
     @property
-    def tables(self):
+    def tables(self) -> SearchContext:
         return self._context_for_class("table")
 
     @property
-    def cubes(self):
+    def cubes(self) -> SearchContext:
         return self._context_for_class("cube")
 
     @property
-    def polygons(self):
+    def polygons(self) -> SearchContext:
         return self._context_for_class("polygons")
 
     @property
-    def dictionaries(self):
+    def dictionaries(self) -> SearchContext:
         return self._context_for_class("dictionary")
 
     @property
-    def grids(self):
+    def grids(self) -> SearchContext:
         return self._context_for_class("cpgrid")
 
     @property
-    def grid_properties(self):
+    def grid_properties(self) -> SearchContext:
         return self._context_for_class("cpgrid_property")
 
-    def _get_object_by_class_and_uuid(self, cls, uuid):
+    def _get_object_by_class_and_uuid(self, cls, uuid) -> Any:
         obj = self.get_object(uuid)
         if obj.metadata["class"] != cls:
             raise Exception(f"Document of type {cls} not found: {uuid}")
         return obj
 
-    async def _get_object_by_class_and_uuid_async(self, cls, uuid):
+    async def _get_object_by_class_and_uuid_async(self, cls, uuid) -> Any:
         obj = await self.get_object_async(uuid)
         if obj.metadata["class"] != cls:
             raise Exception(f"Document of type {cls} not found: {uuid}")
         return obj
 
-    def get_case_by_uuid(self, uuid: str):
+    def get_case_by_uuid(self, uuid: str) -> objects.Case:
         """Get case object by uuid
 
         Args:
@@ -1073,7 +1164,7 @@ class SearchContext:
         """
         return self._get_object_by_class_and_uuid("case", uuid)
 
-    async def get_case_by_uuid_async(self, uuid: str):
+    async def get_case_by_uuid_async(self, uuid: str) -> objects.Case:
         """Get case object by uuid
 
         Args:
@@ -1091,6 +1182,7 @@ class SearchContext:
             "_source": {
                 "includes": [
                     "$schema",
+                    "class",
                     "source",
                     "version",
                     "access",
@@ -1101,7 +1193,7 @@ class SearchContext:
             },
         }
 
-    def get_iteration_by_uuid(self, uuid: str):
+    def get_iteration_by_uuid(self, uuid: str) -> objects.Iteration:
         """Get iteration object by uuid
 
         Args:
@@ -1109,14 +1201,27 @@ class SearchContext:
 
         Returns: iteration object
         """
-        res = self._sumo.post(
-            "/search", json=self._iteration_query(uuid)
-        ).json()
-        obj = res["hits"]["hits"][0]
-        obj["_id"] = uuid
-        return objects.Iteration(self._sumo, obj)
-
-    async def get_iteration_by_uuid_async(self, uuid: str):
+        try:
+            obj = self.get_object(uuid)
+            assert isinstance(obj, objects.Iteration)
+            return obj
+        except Exception:
+            res = self._sumo.post(
+                "/search", json=self._iteration_query(uuid)
+            ).json()
+            hits = res["hits"]["hits"]
+            if len(hits) == 0:
+                raise Exception(f"Document not found: {uuid}")
+            obj = hits[0]
+            obj["_id"] = uuid
+            obj["_source"]["class"] = "iteration"
+            ret = self._to_sumo(obj)
+            self._cache.put(uuid, ret)
+            return ret
+
+    async def get_iteration_by_uuid_async(
+        self, uuid: str
+    ) -> objects.Iteration:
         """Get iteration object by uuid
 
         Args:
@@ -1124,16 +1229,99 @@ class SearchContext:
 
         Returns: iteration object
         """
-        res = (
-            await self._sumo.post_async(
-                "/search", json=self._iteration_query(uuid)
-            )
-        ).json()
-        obj = res["hits"]["hits"][0]
-        obj["_id"] = uuid
-        return objects.Iteration(self._sumo, obj)
+        try:
+            obj = await self.get_object_async(uuid)
+            assert isinstance(obj, objects.Iteration)
+            return obj
+        except Exception:
+            res = (
+                await self._sumo.post_async(
+                    "/search", json=self._iteration_query(uuid)
+                )
+            ).json()
+            hits = res["hits"]["hits"]
+            if len(hits) == 0:
+                raise Exception(f"Document not found: {uuid}")
+            obj = hits[0]
+            obj["_id"] = uuid
+            obj["_source"]["class"] = "iteration"
+            ret = self._to_sumo(obj)
+            self._cache.put(uuid, ret)
+            return ret
+
+    def _ensemble_query(self, uuid):
+        return {
+            "query": {"term": {"fmu.ensemble.uuid.keyword": {"value": uuid}}},
+            "size": 1,
+            "_source": {
+                "includes": [
+                    "$schema",
+                    "class",
+                    "source",
+                    "version",
+                    "access",
+                    "masterdata",
+                    "fmu.case",
+                    "fmu.ensemble",
+                ],
+            },
+        }
+
+    def get_ensemble_by_uuid(self, uuid: str) -> objects.Ensemble:
+        """Get ensemble object by uuid
+
+        Args:
+            uuid (str): ensemble uuid
+
+        Returns: ensemble object
+        """
+        try:
+            obj = self.get_object(uuid)
+            assert isinstance(obj, objects.Ensemble)
+            return obj
+        except Exception:
+            res = self._sumo.post(
+                "/search", json=self._ensemble_query(uuid)
+            ).json()
+            hits = res["hits"]["hits"]
+            if len(hits) == 0:
+                raise Exception(f"Document not found: {uuid}")
+            obj = hits[0]
+            obj["_id"] = uuid
+            obj["_source"]["class"] = "ensemble"
+            ret = self._to_sumo(obj)
+            self._cache.put(uuid, ret)
+            return ret
+
+    async def get_ensemble_by_uuid_async(self, uuid: str) -> objects.Ensemble:
+        """Get ensemble object by uuid
 
-    def _realization_query(self, uuid):
+        Args:
+            uuid (str): ensemble uuid
+
+        Returns: ensemble object
+        """
+        try:
+            obj = await self.get_object_async(uuid)
+            assert isinstance(obj, objects.Ensemble)
+            return obj
+        except Exception:
+            res = (
+                await self._sumo.post_async(
+                    "/search", json=self._ensemble_query(uuid)
+                )
+            ).json()
+            hits = res["hits"]["hits"]
+            if len(hits) == 0:
+                raise Exception(f"Document not found: {uuid}")
+            obj = hits[0]
+            obj["_id"] = uuid
+            obj["_source"]["class"] = "ensemble"
+            ret = self._to_sumo(obj)
+            self._cache.put(uuid, ret)
+            return ret
+
+    def _realization_query(self, uuid) -> Dict:
         return {
             "query": {
                 "term": {"fmu.realization.uuid.keyword": {"value": uuid}}
@@ -1142,18 +1330,20 @@ class SearchContext:
             "_source": {
                 "includes": [
                     "$schema",
+                    "class",
                     "source",
                     "version",
                     "access",
                     "masterdata",
                     "fmu.case",
                     "fmu.iteration",
+                    "fmu.ensemble",
                     "fmu.realization",
                 ],
             },
         }
 
-    def get_realization_by_uuid(self, uuid: str):
+    def get_realization_by_uuid(self, uuid: str) -> objects.Realization:
         """Get realization object by uuid
 
         Args:
@@ -1161,14 +1351,25 @@ class SearchContext:
 
         Returns: realization object
         """
-        res = self._sumo.post(
-            "/search", json=self._realization_query(uuid)
-        ).json()
-        obj = res["hits"]["hits"][0]
-        obj["_id"] = uuid
-        return objects.Realization(self._sumo, obj)
+        try:
+            obj = self.get_object(uuid)
+            assert isinstance(obj, objects.Realization)
+            return obj
+        except Exception:
+            res = self._sumo.post(
+                "/search", json=self._realization_query(uuid)
+            ).json()
+            hits = res["hits"]["hits"]
+            if len(hits) == 0:
+                raise Exception(f"Document not found: {uuid}")
+            obj = hits[0]
+            obj["_id"] = uuid
+            obj["_source"]["class"] = "realization"
+            return self._to_sumo(obj)
 
-    async def get_realization_by_uuid_async(self, uuid: str):
+    async def get_realization_by_uuid_async(
+        self, uuid: str
+    ) -> objects.Realization:
         """Get realization object by uuid
 
         Args:
@@ -1176,16 +1377,25 @@ class SearchContext:
 
         Returns: realization object
         """
-        res = (
-            await self._sumo.post_async(
-                "/search", json=self._realization_query(uuid)
-            )
-        ).json()
-        obj = res["hits"]["hits"][0]
-        obj["_id"] = uuid
-        return objects.Realization(self._sumo, obj)
+        try:
+            obj = await self.get_object_async(uuid)
+            assert isinstance(obj, objects.Realization)
+            return obj
+        except Exception:
+            res = (
+                await self._sumo.post_async(
+                    "/search", json=self._realization_query(uuid)
+                )
+            ).json()
+            hits = res["hits"]["hits"]
+            if len(hits) == 0:
+                raise Exception(f"Document not found: {uuid}")
+            obj = hits[0]
+            obj["_id"] = uuid
+            obj["_source"]["class"] = "realization"
+            return self._to_sumo(obj)
 
-    def get_surface_by_uuid(self, uuid: str):
+    def get_surface_by_uuid(self, uuid: str) -> objects.Surface:
         """Get surface object by uuid
 
         Args:
@@ -1196,7 +1406,7 @@ class SearchContext:
         """
         return self._get_object_by_class_and_uuid("surface", uuid)
 
-    async def get_surface_by_uuid_async(self, uuid: str):
+    async def get_surface_by_uuid_async(self, uuid: str) -> objects.Surface:
         """Get surface object by uuid
 
         Args:
@@ -1207,7 +1417,7 @@ class SearchContext:
         """
         return await self._get_object_by_class_and_uuid_async("surface", uuid)
 
-    def get_polygons_by_uuid(self, uuid: str):
+    def get_polygons_by_uuid(self, uuid: str) -> objects.Polygons:
         """Get polygons object by uuid
 
         Args:
@@ -1218,7 +1428,7 @@ class SearchContext:
         """
         return self._get_object_by_class_and_uuid("polygons", uuid)
 
-    async def get_polygons_by_uuid_async(self, uuid: str):
+    async def get_polygons_by_uuid_async(self, uuid: str) -> objects.Polygons:
         """Get polygons object by uuid
 
         Args:
@@ -1229,7 +1439,7 @@ class SearchContext:
         """
         return await self._get_object_by_class_and_uuid_async("polygons", uuid)
 
-    def get_table_by_uuid(self, uuid: str):
+    def get_table_by_uuid(self, uuid: str) -> objects.Table:
         """Get table object by uuid
 
         Args:
@@ -1240,7 +1450,7 @@ class SearchContext:
         """
         return self._get_object_by_class_and_uuid("table", uuid)
 
-    async def get_table_by_uuid_async(self, uuid: str):
+    async def get_table_by_uuid_async(self, uuid: str) -> objects.Table:
         """Get table object by uuid
 
         Args:
@@ -1251,7 +1461,9 @@ class SearchContext:
         """
         return await self._get_object_by_class_and_uuid_async("table", uuid)
 
-    def _verify_aggregation_operation(self):
+    def _verify_aggregation_operation(
+        self,
+    ) -> Tuple[Dict, List[str], List[int]]:
         query = {
             "query": self._query,
             "size": 1,
@@ -1261,7 +1473,7 @@ class SearchContext:
                 for k in [
                     "fmu.case.uuid",
                     "class",
-                    "fmu.iteration.name",
+                    "fmu.ensemble.name",
                     "data.name",
                     "data.tagname",
                     "data.content",
@@ -1269,6 +1481,8 @@ class SearchContext:
             },
         }
         sres = self._sumo.post("/search", json=query).json()
+        if len(sres["hits"]["hits"]) == 0:
+            raise Exception("No matching realizations found.")
         prototype = sres["hits"]["hits"][0]
         conflicts = [
             k
@@ -1291,8 +1505,15 @@ class SearchContext:
         rids = [hit["_source"]["fmu"]["realization"]["id"] for hit in hits]
         return prototype, uuids, rids
 
-    def _aggregate(self, columns=None, operation=None):
-        prototype, uuids, rids = self._verify_aggregation_operation()
+    def _aggregate(self, columns=None, operation=None) -> objects.Child:
+        assert (
+            operation != "collection"
+            or columns is not None
+            and len(columns) == 1
+        ), "Exactly one column required for collection aggregation."
+        prototype, uuids, rids = self.filter(
+            column=columns
+        )._verify_aggregation_operation()
         spec = {
             "object_ids": uuids,
             "operations": [operation],
@@ -1300,9 +1521,8 @@ class SearchContext:
         del prototype["_source"]["fmu"]["realization"]
         del prototype["_source"]["_sumo"]
         del prototype["_source"]["file"]
-        del prototype["_source"]["access"]
         if "context" in prototype["_source"]["fmu"]:
-            prototype["_source"]["fmu"]["context"]["stage"] = "iteration"
+            prototype["_source"]["fmu"]["context"]["stage"] = "ensemble"
             pass
         prototype["_source"]["fmu"]["aggregation"] = {
             "id": str(uuid.uuid4()),
@@ -1330,10 +1550,11 @@ class SearchContext:
             raise ex
         blob = BytesIO(res.content)
         res = self._to_sumo(prototype, blob)
+        assert isinstance(res, objects.Child)
         res._blob = blob
         return res
 
-    def aggregate(self, columns=None, operation=None):
+    def aggregate(self, columns=None, operation=None) -> objects.Child:
         if len(self.hidden) > 0:
             return self.hidden._aggregate(columns=columns, operation=operation)
         else:
@@ -1341,7 +1562,9 @@ class SearchContext:
                 columns=columns, operation=operation
             )
 
-    async def _verify_aggregation_operation_async(self):
+    async def _verify_aggregation_operation_async(
+        self,
+    ) -> Tuple[Dict, List[str], List[int]]:
         query = {
             "query": self._query,
             "size": 1,
@@ -1351,7 +1574,7 @@ class SearchContext:
                 for k in [
                     "fmu.case.uuid",
                     "class",
-                    "fmu.iteration.name",
+                    "fmu.ensemble.name",
                     "data.name",
                     "data.tagname",
                     "data.content",
@@ -1359,6 +1582,8 @@ class SearchContext:
             },
         }
         sres = (await self._sumo.post_async("/search", json=query)).json()
+        if len(sres["hits"]["hits"]) == 0:
+            raise Exception("No matching realizations found.")
         prototype = sres["hits"]["hits"][0]
         conflicts = [
             k
@@ -1381,12 +1606,21 @@ class SearchContext:
         rids = [hit["_source"]["fmu"]["realization"]["id"] for hit in hits]
         return prototype, uuids, rids
 
-    async def _aggregate_async(self, columns=None, operation=None):
+    async def _aggregate_async(
+        self, columns=None, operation=None
+    ) -> objects.Child:
+        assert (
+            operation != "collection"
+            or columns is not None
+            and len(columns) == 1
+        ), "Exactly one column required for collection aggregation."
         (
             prototype,
             uuids,
             rids,
-        ) = await self._verify_aggregation_operation_async()
+        ) = await self.filter(
+            column=columns
+        )._verify_aggregation_operation_async()
         spec = {
             "object_ids": uuids,
             "operations": [operation],
@@ -1394,9 +1628,8 @@ class SearchContext:
         del prototype["_source"]["fmu"]["realization"]
         del prototype["_source"]["_sumo"]
         del prototype["_source"]["file"]
-        del prototype["_source"]["access"]
         if "context" in prototype["_source"]["fmu"]:
-            prototype["_source"]["fmu"]["context"]["stage"] = "iteration"
+            prototype["_source"]["fmu"]["context"]["stage"] = "ensemble"
             pass
         prototype["_source"]["fmu"]["aggregation"] = {
             "id": str(uuid.uuid4()),
@@ -1424,10 +1657,13 @@ class SearchContext:
             raise ex
         blob = BytesIO(res.content)
         res = self._to_sumo(prototype, blob)
+        assert isinstance(res, objects.Child)
         res._blob = blob
         return res
 
-    async def aggregate_async(self, columns=None, operation=None):
+    async def aggregate_async(
+        self, columns=None, operation=None
+    ) -> objects.Child:
         length_hidden = await self.hidden.length_async()
         if length_hidden > 0:
             return await self.hidden._aggregate_async(
@@ -1438,33 +1674,55 @@ class SearchContext:
                 columns=columns, operation=operation
             )
 
-    def aggregation(self, column=None, operation=None):
+    def aggregation(self, column=None, operation=None) -> objects.Child:
         assert operation is not None
         assert column is None or isinstance(column, str)
         sc = self.filter(aggregation=operation, column=column)
         numaggs = len(sc)
         assert numaggs <= 1
         if numaggs == 1:
-            return sc[0]
-        else:
-            return self.filter(realization=True).aggregate(
-                columns=[column] if column is not None else None,
-                operation=operation,
-            )
+            agg = sc.single
+            assert isinstance(agg, objects.Child)
+            ts = agg.metadata["_sumo"]["timestamp"]
+            reals = self.filter(
+                realization=True,
+                complex={"range": {"_sumo.timestamp": {"lt": ts}}},
+            ).realizationids
+            if set(reals) == set(
+                agg.metadata["fmu"]["aggregation"]["realization_ids"]
+            ):
+                return agg
+        # ELSE
+        return self.filter(realization=True).aggregate(
+            columns=[column] if column is not None else None,
+            operation=operation,
+        )
 
-    async def aggregation_async(self, column=None, operation=None):
+    async def aggregation_async(
+        self, column=None, operation=None
+    ) -> objects.Child:
         assert operation is not None
         assert column is None or isinstance(column, str)
         sc = self.filter(aggregation=operation, column=column)
         numaggs = await sc.length_async()
         assert numaggs <= 1
         if numaggs == 1:
-            return await sc.getitem_async(0)
-        else:
-            return await self.filter(realization=True).aggregate_async(
-                columns=[column] if column is not None else None,
-                operation=operation,
-            )
+            agg = await sc.single_async
+            assert isinstance(agg, objects.Child)
+            ts = agg.metadata["_sumo"]["timestamp"]
+            reals = await self.filter(
+                realization=True,
+                complex={"range": {"_sumo.timestamp": {"lt": ts}}},
+            ).realizationids_async
+            if set(reals) == set(
+                agg.metadata["fmu"]["aggregation"]["realization_ids"]
+            ):
+                return agg
+        # ELSE
+        return await self.filter(realization=True).aggregate_async(
+            columns=[column] if column is not None else None,
+            operation=operation,
+        )
 
     @deprecation.deprecated(
         details="Use the method 'aggregate' instead, with parameter 'operation'."
@@ -1648,6 +1906,28 @@ class SearchContext:
         """List of unique object names."""
         return await self.get_field_values_async("data.name.keyword")
 
+    @property
+    def classes(self) -> List[str]:
+        """List of class names."""
+        return self.get_field_values("class.keyword")
+
+    @property
+    async def classes_async(self) -> List[str]:
+        """List of class names."""
+        return await self.get_field_values_async("class.keyword")
+
+    @property
+    def standard_results(self) -> List[str]:
+        """List of standard result names."""
+        return self.get_field_values("data.standard_result.name.keyword")
+
+    @property
+    async def standard_results_async(self) -> List[str]:
+        """List of standard result names."""
+        return await self.get_field_values_async(
+            "data.standard_result.name.keyword"
+        )
+
 
 def _gen_filter_doc(spec):
     fmap = {
@@ -1702,7 +1982,7 @@ Examples:
     Match one value::
 
         surfs = case.surfaces.filter(
-                    iteration="iter-0",
+                    ensemble="iter-0",
                     name="my_surface_name"
                 )