⚡️ Use eager_global_ordinals and improve empty search

Author: simonwoerpel

openaleph_search/index/mapping.py

@@ -203,16 +203,17 @@ def base_mapping() -> dict[str, MappingProperty]:
 
     Returns fresh dicts on each call so callers can safely mutate the result.
     """
+    ego = {"eager_global_ordinals": True} if settings.eager_global_ordinals else {}
     return {
-        Field.DATASET: {**FieldType.KEYWORD},
-        Field.SCHEMA: {**FieldType.KEYWORD},
-        Field.SCHEMATA: {**FieldType.KEYWORD},
+        Field.DATASET: {**FieldType.KEYWORD, **ego},
+        Field.SCHEMA: {**FieldType.KEYWORD, **ego},
+        Field.SCHEMATA: {**FieldType.KEYWORD, **ego},
         # for fast label display
         Field.CAPTION: {**FieldType.KEYWORD},
         # original names as matching (text) field
         Field.NAME: {**FieldType.NAME},
         # names keywords, a bit normalized
-        Field.NAMES: {**FieldType.NAME_KEYWORD},
+        Field.NAMES: {**FieldType.NAME_KEYWORD, **ego},
         # name normalizations for filters and matching
         Field.NAME_KEYS: {**FieldType.KEYWORD},
         Field.NAME_PARTS: {**FieldType.KEYWORD_COPY},
@@ -227,7 +228,7 @@ def base_mapping() -> dict[str, MappingProperty]:
         Field.TEXT: {**FieldType.TEXT},
         Field.TRANSLATION: {**FieldType.TEXT},
         # tagging
-        Field.TAGS: {**FieldType.KEYWORD},
+        Field.TAGS: {**FieldType.KEYWORD, **ego},
         # processing metadata
         Field.UPDATED_AT: {**FieldType.DATE},
         Field.CREATED_AT: {**FieldType.DATE},
@@ -239,7 +240,7 @@ def base_mapping() -> dict[str, MappingProperty]:
         # OpenAleph leaked context data probably deprecated soon
         Field.ROLE: {**FieldType.KEYWORD},
         Field.PROFILE: {**FieldType.KEYWORD},
-        Field.COLLECTION_ID: {**FieldType.KEYWORD},
+        Field.COLLECTION_ID: {**FieldType.KEYWORD, **ego},
         Field.MUTABLE: {**FieldType.BOOL},
         # length normalization
         Field.NUM_VALUES: {**FieldType.INTEGER},

openaleph_search/query/base.py

@@ -28,6 +28,8 @@
 log = get_logger(__name__)
 settings = Settings()
 
+_FACET_SAMPLER_KEY = "facets.sampled"
+
 
 class Query:
     TEXT_FIELDS: ClassVar[list[str]] = [Field.TEXT]
@@ -205,6 +207,17 @@ def get_aggregations(self) -> dict[str, Any]:
                 else:
                     aggregations.update(facet_aggregations)
 
+        # For empty queries on large indexes, wrap facet aggregations in a
+        # sampler so ES only aggregates a subset of docs per shard. Gives
+        # approximate counts but is dramatically faster.
+        if self.is_empty_query and aggregations:
+            aggregations = {
+                _FACET_SAMPLER_KEY: {
+                    "sampler": {"shard_size": settings.facet_sampler_size},
+                    "aggs": aggregations,
+                }
+            }
+
         # Significant terms aggregations
         for facet_name in self.parser.facet_significant_names:
             facet_aggregations = {}
@@ -321,6 +334,8 @@ def get_significant_text_sampler(self) -> dict[str, Any]:
 
     def get_sort(self) -> list[str | dict[str, dict[str, Any]]]:
         """Pick one of a set of named result orderings."""
+        if self.is_empty_query and not len(self.parser.sorts):
+            return ["_doc"]
         if not len(self.parser.sorts):
             return self.SORT_DEFAULT
 
@@ -466,4 +481,13 @@ def search(self) -> ObjectApiResponse:
             took=result.get("took"),
             hits=result.get("hits", {}).get("total", {}).get("value"),
         )
+
+        # Unwrap sampled facet aggregations so consumers see the same
+        # response structure regardless of whether sampling was used.
+        aggs = result.get("aggregations", {})
+        if _FACET_SAMPLER_KEY in aggs:
+            sampled = aggs.pop(_FACET_SAMPLER_KEY)
+            sampled.pop("doc_count", None)
+            aggs.update(sampled)
+
         return result

openaleph_search/query/queries.py

@@ -79,7 +79,7 @@ def get_index(self):
 
     def get_query(self) -> dict[str, Any]:
         query = self.get_inner_query()
-        if settings.query_function_score:
+        if settings.query_function_score and not self.is_empty_query:
             return self.wrap_query_function_score(query)
         return query
 
@@ -262,6 +262,11 @@ def get_index(self):
         schemata = list(self.entity.schema.matchable_schemata)
         return entities_read_index(schema=schemata)
 
+    def get_sort(self) -> list[str | dict[str, dict[str, Any]]]:
+        # Always sort by score — the match query builds scoring clauses
+        # even though the parser has no user text (is_empty_query=True).
+        return ["_score"]
+
     def get_inner_query(self) -> dict[str, Any]:
         query = match_query(
             self.entity,

openaleph_search/settings.py

@@ -61,6 +61,10 @@ class Settings(BaseSettings):
     index_boost_documents: int = 1
     index_boost_pages: int = 1
 
+    # Sampler shard_size for facet aggregations on empty queries.
+    # Uses approximate counts for faster response on large indexes.
+    facet_sampler_size: int = 5000
+
     # Sampler for significant_terms / significant_text aggregations
     significant_terms_sampler_size: int = 2000
     significant_text_sampler_size: int = 200
@@ -96,5 +100,10 @@ class Settings(BaseSettings):
     mlt_min_word_length: int = 5
     mlt_max_doc_freq: int = 500
 
+    # Pre-build global ordinals on frequently-aggregated keyword fields
+    # during refresh. Eliminates first-query latency spikes at the cost of
+    # slightly slower refreshes.
+    eager_global_ordinals: bool = True
+
     # search control
     allow_leading_wildcard: bool = False