sdmxlib 0.27.0__tar.gz → 0.27.2__tar.gz

{sdmxlib-0.27.0 → sdmxlib-0.27.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sdmxlib
-Version: 0.27.0
+Version: 0.27.2
 Summary: SDMX structural metadata library for Python
 Keywords: sdmx,statistics,metadata,datastructure
 Author: gabrielgellner

{sdmxlib-0.27.0 → sdmxlib-0.27.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.27.0"
+version = "0.27.2"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{sdmxlib-0.27.0 → sdmxlib-0.27.2}/src/sdmxlib/local/_registry.py

@@ -30,6 +30,7 @@ stashes the URI; the DuckDB connection is opened by ``open()`` /
         local.add(...)
 """
 
+from collections import OrderedDict
 from collections.abc import Iterable
 from pathlib import Path
 from typing import Any, Self
@@ -57,6 +58,90 @@ _ITEM_TO_SCHEME: dict[str, tuple[str, str]] = {
 }
 
 
+DEFAULT_RESOLVE_CACHE_SIZE = 256
+
+
+class _LRUDict(OrderedDict[str, Any]):
+    """Bounded LRU mapping used as the registry-level resolver cache.
+
+    Subclasses :class:`OrderedDict` so it can be passed wherever the
+    resolver expects ``dict[str, Any]``. Inserts evict least-recently-used
+    entries past ``maxsize``; reads via :meth:`get` move keys to the end.
+    ``maxsize == 0`` disables caching — inserts are silently dropped, so
+    the structure stays empty.
+
+    Tracks ``hits`` / ``misses`` for :meth:`Registry.resolve_cache_info`;
+    ``__contains__`` is treated as internal control flow (the resolver
+    uses it for dedup) and is not counted.
+    """
+
+    def __init__(self, maxsize: int) -> None:
+        super().__init__()
+        if maxsize < 0:
+            msg = f"resolve_cache_size must be >= 0, got {maxsize}"
+            raise ValueError(msg)
+        self.maxsize = maxsize
+        self.hits = 0
+        self.misses = 0
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        if self.maxsize == 0:
+            return
+        if key in self:
+            self.move_to_end(key)
+        super().__setitem__(key, value)
+        while len(self) > self.maxsize:
+            self.popitem(last=False)
+
+    def get(self, key: str, default: Any = None) -> Any:  # type: ignore[override]
+        if super().__contains__(key):
+            self.hits += 1
+            self.move_to_end(key)
+            return super().__getitem__(key)
+        self.misses += 1
+        return default
+
+    def reset_stats(self) -> None:
+        self.hits = 0
+        self.misses = 0
+
+
+class _CallScopedMemo(dict[str, Any]):
+    """Per-call resolver memo layered over a persistent LRU cache.
+
+    Two reasons for the overlay rather than passing the LRU directly:
+
+    1. **Correctness under tight cache sizes (incl. ``maxsize=0``).** The
+       resolver writes URN→target during one phase and reads them back in
+       a later phase of the same call. If those writes went straight to
+       the LRU, an entry could be evicted before the read — leaving Refs
+       unresolved for callers using a small (or disabled) cache. The
+       overlay holds in-flight entries in an unbounded per-call dict so
+       single-call resolution is independent of cache size.
+    2. **Promote-on-success.** Entries written during the call enter the
+       LRU only at the end of the call, via :meth:`promote`. That keeps
+       partial-failure semantics clean: if a call raises midway, the LRU
+       is unchanged.
+    """
+
+    def __init__(self, lru: _LRUDict) -> None:
+        super().__init__()
+        self._lru = lru
+
+    def __contains__(self, key: object) -> bool:
+        return super().__contains__(key) or self._lru.__contains__(key)
+
+    def get(self, key: str, default: Any = None) -> Any:  # type: ignore[override]
+        if super().__contains__(key):
+            return super().__getitem__(key)
+        return self._lru.get(key, default)
+
+    def promote(self) -> None:
+        """Copy this call's resolved entries into the persistent LRU."""
+        for k, v in self.items():
+            self._lru[k] = v
+
+
 class Registry:
     """DuckDB-backed persistent SDMX artefact store.
 
@@ -86,12 +171,22 @@ class Registry:
         uri: str | Path,
         *,
         source_registry: str | None = None,
+        resolve_cache_size: int = DEFAULT_RESOLVE_CACHE_SIZE,
     ) -> None:
+        """Open or wrap a DuckDB-backed registry.
+
+        ``resolve_cache_size`` bounds the LRU of resolved Ref targets that
+        :meth:`get` / :meth:`get_all` / :meth:`to_registry` share across
+        calls. Pass ``0`` to disable caching (matches pre-v0.27.2 behaviour
+        — one full read per Ref). The cache is cleared on every mutation
+        (``add`` / ``drop`` / ``replace``) for invalidation correctness.
+        """
         self._uri = Path(uri) if isinstance(uri, str) else uri
         self._source_registry = source_registry
         self._conn: duckdb.DuckDBPyConnection | None = None
         self._cursor: duckdb.DuckDBPyConnection | None = None
         self._owns_connection = True
+        self._resolve_cache: _LRUDict = _LRUDict(resolve_cache_size)
 
     @property
     def uri(self) -> Path:
@@ -137,6 +232,7 @@ class Registry:
         conn: duckdb.DuckDBPyConnection,
         *,
         source_registry: str | None = None,
+        resolve_cache_size: int = DEFAULT_RESOLVE_CACHE_SIZE,
     ) -> Self:
         """Wrap an existing DuckDB connection.
 
@@ -144,6 +240,9 @@ class Registry:
         Registry leaves the connection open. Use this when the connection
         is shared with another component (e.g. a co-located DuckLake catalog)
         that owns its lifecycle.
+
+        ``resolve_cache_size`` configures the resolver LRU; see
+        :meth:`__init__`.
         """
         instance = cls.__new__(cls)
         instance._uri = Path(":connection:")  # noqa: SLF001 — alternate constructor sets private state
@@ -151,6 +250,7 @@ class Registry:
         instance._conn = conn  # noqa: SLF001
         instance._cursor = None  # noqa: SLF001
         instance._owns_connection = False  # noqa: SLF001
+        instance._resolve_cache = _LRUDict(resolve_cache_size)  # noqa: SLF001
         instance._initialise_schema()  # noqa: SLF001
         return instance
 
@@ -209,9 +309,14 @@ class Registry:
 
         ``source_registry`` overrides the registry-level default for this
         call. ``None`` (default) means "use the registry-level default."
+
+        Clears the resolver cache: any cached resolved target may now be
+        stale (e.g. a freshly-added Codelist replaces the one a previous
+        ``get`` had cached).
         """
         tag = source_registry if source_registry is not None else self._source_registry
         writers.put_artefact(self._c, artefact, source_registry=tag)
+        self._resolve_cache.clear()
 
     def add_all(
         self,
@@ -256,70 +361,180 @@ class Registry:
         if result is None:
             return None
         if not isinstance(result, (LazyCodelist, LazyHierarchy)):
-            self._resolve_refs(result, set())
+            memo = _CallScopedMemo(self._resolve_cache)
+            self._resolve_refs(result, memo=memo)
+            memo.promote()
         return result  # type: ignore[return-value]
 
     def get_all[T](self, artefact_type: "type[T]") -> "list[T]":
-        """All artefacts of the given Python type."""
+        """All artefacts of the given Python type.
+
+        Resolution shares one call-scoped memo across the batch and is
+        backed by the registry's persistent ``_resolve_cache``, so any
+        parent scheme referenced by multiple artefacts is loaded once,
+        not once per artefact.
+        """
         results = readers.get_all(self._c, artefact_type)
+        memo = _CallScopedMemo(self._resolve_cache)
         for r in results:
             if not isinstance(r, (LazyCodelist, LazyHierarchy)):
-                self._resolve_refs(r, set())
+                self._resolve_refs(r, memo=memo)
+        memo.promote()
         return results  # type: ignore[return-value]
 
     # ── Ref resolution ─────────────────────────────────────────────────
 
-    def _resolve_refs(self, obj: Any, visited: set[int]) -> None:
-        """Walk attrs fields, resolving ``Ref`` targets from DuckDB."""
+    def _resolve_refs(  # noqa: C901
+        self,
+        obj: Any,
+        *,
+        memo: "dict[str, Any] | None" = None,
+        walked: "set[int] | None" = None,
+    ) -> None:
+        """Resolve every unresolved ``Ref`` in *obj*'s attrs graph.
+
+        Two-phase batched walk:
+
+        1. **Collect** — recursive Python-only walk that visits every attrs
+           field reachable from *obj*. Records ``(owner, field_name, Ref)``
+           tuples for unresolved Refs; no SQL.
+        2. **Resolve** — deduplicate URNs, partition into item URNs
+           (resolved by loading the parent scheme once and looking up the
+           item) vs top-level URNs (one SQL fetch per distinct URN). Both
+           paths populate a shared per-call memo keyed by URN string.
+        3. **Assign** — mutate the Ref fields with ``Ref.of(urn, target)``.
+
+        Newly resolved targets enter a new frontier and are walked in turn
+        so transitive references resolve in the same call (e.g. a DSD ref
+        resolves to a Codelist whose embedded Refs also get resolved).
+
+        Idempotent: already-resolved Refs are skipped. ``memo`` and
+        ``walked`` may be passed in to share state across multiple
+        artefacts (used by :meth:`get_all` and :meth:`to_registry`).
+        """
+        if memo is None:
+            memo = {}
+        if walked is None:
+            walked = set()
+
+        frontier: list[Any] = [obj]
+        while frontier:
+            pending: list[tuple[Any, str, Ref[Any]]] = []
+            for item in frontier:
+                self._collect_refs(item, walked, pending)
+            frontier = []
+
+            if not pending:
+                break
+
+            # Deduplicate the URNs we still need to resolve.
+            needed: list[SdmxUrn[Any]] = []
+            seen: set[str] = set()
+            for _owner, _name, ref in pending:
+                urn_str = str(ref.urn)
+                if urn_str in memo or urn_str in seen:
+                    continue
+                seen.add(urn_str)
+                needed.append(ref.urn)
+
+            if needed:
+                self._resolve_urns(needed, memo)
+
+            for owner, name, ref in pending:
+                if ref._resolved is not None:  # noqa: SLF001
+                    continue
+                target = memo.get(str(ref.urn))
+                if target is None:
+                    continue
+                setattr(owner, name, Ref.of(ref.urn, target))
+                if id(target) not in walked:
+                    frontier.append(target)
+
+    def _collect_refs(
+        self,
+        obj: Any,
+        walked: set[int],
+        pending: "list[tuple[Any, str, Ref[Any]]]",
+    ) -> None:
+        """Pure-Python walk that records unresolved Refs into *pending*."""
         if not attrs.has(type(obj)) or isinstance(obj, type):
             return
         oid = id(obj)
-        if oid in visited:
+        if oid in walked:
             return
-        visited.add(oid)
+        walked.add(oid)
 
         for f in attrs.fields(type(obj)):
             value = getattr(obj, f.name, None)
             if value is None:
                 continue
             if isinstance(value, Ref):
-                self._resolve_ref_field(obj, f.name, value)
+                if value._resolved is None:  # noqa: SLF001
+                    pending.append((obj, f.name, value))
             elif isinstance(value, ItemList):
                 for item in value:
-                    self._resolve_refs(item, visited)
+                    self._collect_refs(item, walked, pending)
             elif attrs.has(type(value)) and not isinstance(value, type):
-                self._resolve_refs(value, visited)
-
-    def _resolve_ref_field(self, obj: Any, name: str, ref: "Ref[Any]") -> None:
-        """Resolve a single Ref field from DuckDB and set it on *obj*."""
-        if ref._resolved is not None:  # noqa: SLF001
-            return
+                self._collect_refs(value, walked, pending)
 
-        urn_str = str(ref.urn)
-        target = self._resolve_target(urn_str)
-        if target is not None:
-            resolved = Ref.of(ref.urn, target)
-            setattr(obj, name, resolved)
+    def _resolve_urns(  # noqa: C901
+        self,
+        urns: "list[SdmxUrn[Any]]",
+        memo: "dict[str, Any]",
+    ) -> None:
+        """Bulk-load the targets for *urns*, populating *memo* in place.
 
-    def _resolve_target(self, urn_str: str) -> Any | None:
-        """Load an artefact by URN string for Ref resolution."""
-        parsed = SdmxUrn.parse(urn_str)
-        if parsed.item_id is not None:
-            return self._resolve_item_urn(parsed)
+        Item URNs (Code, Concept, …) are grouped by their parent scheme
+        URN so each scheme is loaded at most once per call, regardless of
+        how many of its items the caller asked for. This is what makes
+        large Hierarchies and wide DSDs O(distinct parent schemes) in SQL
+        round-trips instead of O(refs).
+        """
+        item_urns_by_parent: dict[str, list[SdmxUrn[Any]]] = {}
+        top_urns: list[SdmxUrn[Any]] = []
+        for parsed in urns:
+            if parsed.item_id is None:
+                top_urns.append(parsed)
+                continue
+            parent_urn_str = self._parent_scheme_urn(parsed)
+            if parent_urn_str is None:
+                continue
+            item_urns_by_parent.setdefault(parent_urn_str, []).append(parsed)
 
-        return readers.get_artefact(self._c, urn_str)
+        for parent_urn_str, item_urns in item_urns_by_parent.items():
+            sample = item_urns[0]
+            scheme_info = _ITEM_TO_SCHEME.get(sample.artefact_class)
+            if scheme_info is None:
+                continue
+            _scheme_class_name, items_attr = scheme_info
+            parent = self._load_parent_scheme(parent_urn_str, sample, memo)
+            if parent is None:
+                continue
+            items = getattr(parent, items_attr, None)
+            if items is None or not hasattr(items, "get"):
+                continue
+            for parsed in item_urns:
+                target = items.get(parsed.item_id)
+                if target is not None:
+                    memo[str(parsed)] = target
+
+        for parsed in top_urns:
+            urn_str = str(parsed)
+            if urn_str in memo:
+                continue
+            target = readers.get_artefact(self._c, urn_str)
+            if target is not None:
+                memo[urn_str] = target
 
-    def _resolve_item_urn(self, parsed: "SdmxUrn[Any]") -> Any | None:
-        """Resolve an item-level URN by loading its parent scheme."""
+    def _parent_scheme_urn(self, parsed: "SdmxUrn[Any]") -> str | None:
+        """Build the parent scheme URN string for an item-level URN, or None."""
         scheme_info = _ITEM_TO_SCHEME.get(parsed.artefact_class)
         if scheme_info is None:
             return None
-
-        scheme_class_name, items_attr = scheme_info
+        scheme_class_name, _items_attr = scheme_info
         scheme_cls = _TYPE_REGISTRY.get(scheme_class_name)
         if scheme_cls is None:
             return None
-
         parent_urn = SdmxUrn.make(
             scheme_cls,
             package=parsed.package,
@@ -328,31 +543,39 @@ class Registry:
             id=parsed.id,
             version=parsed.version,
         )
-        parent_urn_str = str(parent_urn)
+        return str(parent_urn)
 
-        # Try exact match first
+    def _load_parent_scheme(
+        self,
+        parent_urn_str: str,
+        sample: "SdmxUrn[Any]",
+        memo: "dict[str, Any]",
+    ) -> Any | None:
+        """Load (eager) a parent scheme for item resolution, memoized.
+
+        Honours the version=``"latest"`` fallback that the previous
+        per-ref resolver used.
+        """
+        cached = memo.get(parent_urn_str)
+        if cached is not None:
+            return cached
         parent = readers.get_artefact(self._c, parent_urn_str, eager=True)
-
-        # Fallback for version="latest" — find by agency+id
-        if parent is None and parsed.version == "latest":
-            row = self._c.execute(
-                """
-                SELECT urn FROM artefact
-                WHERE artefact_type = ? AND agency_id = ? AND resource_id = ?
-                """,
-                [scheme_class_name, parsed.agency, parsed.id],
-            ).fetchone()
-            if row:
-                parent = readers.get_artefact(self._c, row[0], eager=True)
-
-        if parent is None:
-            return None
-
-        items = getattr(parent, items_attr, None)
-        if items is None:
-            return None
-
-        return items.get(parsed.item_id) if hasattr(items, "get") else None
+        if parent is None and sample.version == "latest":
+            scheme_info = _ITEM_TO_SCHEME.get(sample.artefact_class)
+            if scheme_info is not None:
+                scheme_class_name, _ = scheme_info
+                row = self._c.execute(
+                    """
+                    SELECT urn FROM artefact
+                    WHERE artefact_type = ? AND agency_id = ? AND resource_id = ?
+                    """,
+                    [scheme_class_name, sample.agency, sample.id],
+                ).fetchone()
+                if row:
+                    parent = readers.get_artefact(self._c, row[0], eager=True)
+        if parent is not None:
+            memo[parent_urn_str] = parent
+        return parent
 
     # ── Ref ────────────────────────────────────────────────────────────────
 
@@ -383,14 +606,51 @@ class Registry:
     # ── Mutations ─────────────────────────────────────────────────────────
 
     def drop(self, urn: "SdmxUrn[Any]") -> bool:
-        """Remove an artefact by URN. Returns True if it existed."""
-        return writers.drop_artefact(self._c, str(urn))
+        """Remove an artefact by URN. Returns True if it existed.
+
+        Clears the resolver cache (cached resolved targets may reference
+        the dropped artefact).
+        """
+        result = writers.drop_artefact(self._c, str(urn))
+        self._resolve_cache.clear()
+        return result
 
     def replace(self, old_urn: "SdmxUrn[Any]", new: Any) -> None:
-        """Remove the old artefact and add the new one."""
+        """Remove the old artefact and add the new one.
+
+        Each leg clears the resolver cache via :meth:`add` / :meth:`drop`;
+        the net effect is a single fully-cleared cache at the end.
+        """
         writers.drop_artefact(self._c, str(old_urn))
         self.add(new)
 
+    # ── Resolver cache ────────────────────────────────────────────────────
+
+    def clear_resolve_cache(self) -> None:
+        """Purge the resolver cache and reset hit/miss counters.
+
+        Useful for explicit invalidation hooks (e.g. a webhook telling the
+        service that upstream metadata changed without going through this
+        registry's mutation API). Cache also clears automatically on every
+        ``add`` / ``drop`` / ``replace``.
+        """
+        self._resolve_cache.clear()
+        self._resolve_cache.reset_stats()
+
+    def resolve_cache_info(self) -> dict[str, int]:
+        """Return resolver cache stats: size, max_size, hits, misses.
+
+        Intended for ops dashboards and integration tests asserting cache
+        behaviour. ``size == 0`` after construction or any mutation; rises
+        as ``get`` / ``get_all`` populate it, capped at ``max_size``.
+        """
+        return {
+            "size": len(self._resolve_cache),
+            "max_size": self._resolve_cache.maxsize,
+            "hits": self._resolve_cache.hits,
+            "misses": self._resolve_cache.misses,
+        }
+
     # ── Direct SQL helpers ────────────────────────────────────────────────
 
     def code_map(self, codelist_urn: "str | SdmxUrn[Any]", *, lang: str) -> dict[str, str]:
@@ -419,11 +679,20 @@ class Registry:
     # ── Escape hatch ──────────────────────────────────────────────────────
 
     def to_registry(self) -> InMemoryRegistry:
-        """Load everything into an in-memory Registry with full Ref interning."""
+        """Load everything into an in-memory Registry with full Ref interning.
+
+        Resolution uses the registry's persistent ``_resolve_cache`` so each
+        parent scheme is read at most once even when many artefacts
+        reference it.
+        """
         reg = InMemoryRegistry()
+        memo = _CallScopedMemo(self._resolve_cache)
         rows = self._c.execute("SELECT urn, artefact_type FROM artefact").fetchall()
         for urn_str, _artefact_type in rows:
             obj = readers.get_artefact(self._c, urn_str, eager=True)
-            if obj is not None:
-                reg.add(obj)
+            if obj is None:
+                continue
+            self._resolve_refs(obj, memo=memo)
+            reg.add(obj)
+        memo.promote()
         return reg

{sdmxlib-0.27.0 → sdmxlib-0.27.2}/src/sdmxlib/storage/readers.py

@@ -99,30 +99,154 @@ def _read_annotations(
     conn: duckdb.DuckDBPyConnection,
     owner_urn: str,
 ) -> Annotations:
-    """Read annotations and their text for any annotated entity."""
+    """Read annotations and their text for a single annotated entity.
+
+    Prefer :func:`_read_annotations_for_owners` when loading annotations
+    for many siblings — this single-owner helper still issues 1+N queries.
+    """
     rows = conn.execute(
         """
-        SELECT id, annotation_id, title, annotation_type, url
-        FROM annotation
-        WHERE owner_urn = ?
-        ORDER BY ordinal
+        SELECT a.id, a.annotation_id, a.title, a.annotation_type, a.url,
+               atxt.lang, atxt.text
+        FROM annotation a
+        LEFT JOIN annotation_text atxt ON atxt.annotation_id = a.id
+        WHERE a.owner_urn = ?
+        ORDER BY a.ordinal, a.id
         """,
         [owner_urn],
     ).fetchall()
     if not rows:
         return Annotations()
+    return _annotations_from_joined_rows(rows)
+
+
+def _annotations_from_joined_rows(
+    rows: list[tuple[Any, ...]],
+) -> Annotations:
+    """Build an :class:`Annotations` from joined annotation+annotation_text rows.
+
+    Each row is ``(db_id, annotation_id, title, annotation_type, url, lang, text)``.
+    Rows for a single annotation are contiguous; LEFT-JOIN nulls in (lang, text)
+    indicate annotations with no text.
+    """
     result: list[Annotation] = []
-    for row in rows:
-        db_id, ann_id, title, ann_type, url = row
-        text_rows = conn.execute(
-            "SELECT lang, text FROM annotation_text WHERE annotation_id = ?",
-            [db_id],
-        ).fetchall()
-        text = InternationalString.of(dict(text_rows)) if text_rows else InternationalString()
+    current_db_id: object = object()
+    texts: dict[str, str] = {}
+    current_ann_fields: tuple[Any, ...] | None = None
+
+    def flush() -> None:
+        if current_ann_fields is None:
+            return
+        ann_id, title, ann_type, url = current_ann_fields
+        text = InternationalString.of(texts) if texts else InternationalString()
         result.append(Annotation(id=ann_id, title=title, type=ann_type, url=url, text=text))
+
+    for row in rows:
+        db_id, ann_id, title, ann_type, url, lang, text_val = row
+        if db_id != current_db_id:
+            flush()
+            current_db_id = db_id
+            current_ann_fields = (ann_id, title, ann_type, url)
+            texts = {}
+        if lang is not None:
+            texts[lang] = text_val
+    flush()
     return Annotations(result)
 
 
+def _read_annotations_subtree(
+    conn: duckdb.DuckDBPyConnection,
+    artefact_urn: str,
+) -> dict[str, Annotations]:
+    """Bulk-load annotations for an artefact and every item beneath it.
+
+    Item URNs reuse the parent artefact's ``agency:id(version)`` suffix and
+    append ``.item_id`` (see :func:`writers._make_item_urn`), so a single
+    ``OR owner_urn LIKE '%=<suffix>.%'`` clause covers the parent plus every
+    code / concept / component / hierarchy node, regardless of item class.
+
+    Returns ``{owner_urn: Annotations}`` for owners that have at least one
+    annotation. Callers should default missing keys to ``Annotations()``.
+    """
+    suffix = artefact_urn.partition("=")[2]
+    pattern = f"%={suffix}.%"
+    return _read_annotations_for_owners_predicate(
+        conn,
+        "owner_urn = ? OR owner_urn LIKE ?",
+        [artefact_urn, pattern],
+    )
+
+
+def _read_annotations_for_owners_predicate(
+    conn: duckdb.DuckDBPyConnection,
+    predicate: str,
+    params: list[Any],
+) -> dict[str, Annotations]:
+    """Bulk-load annotations matching a WHERE predicate against ``annotation``.
+
+    Lower-level than :func:`_read_annotations_for_owners` (which expects a
+    subquery yielding owner URNs); this one inlines a predicate that
+    references ``owner_urn`` directly, so a single ``LIKE`` scan can cover
+    "this artefact and every item under it" without a subquery.
+    """
+    rows = conn.execute(
+        f"""
+        SELECT a.owner_urn, a.id, a.annotation_id, a.title, a.annotation_type, a.url,
+               atxt.lang, atxt.text
+        FROM annotation a
+        LEFT JOIN annotation_text atxt ON atxt.annotation_id = a.id
+        WHERE {predicate}
+        ORDER BY a.owner_urn, a.ordinal, a.id
+        """,
+        params,
+    ).fetchall()
+    return _group_annotations_by_owner(rows)
+
+
+def _group_annotations_by_owner(
+    rows: list[tuple[Any, ...]],
+) -> dict[str, Annotations]:
+    """Group joined annotation rows by ``owner_urn`` (the first column)."""
+    if not rows:
+        return {}
+    result: dict[str, Annotations] = {}
+    current_owner: str | None = None
+    bucket: list[tuple[Any, ...]] = []
+    for row in rows:
+        owner = row[0]
+        if owner != current_owner:
+            if current_owner is not None and bucket:
+                result[current_owner] = _annotations_from_joined_rows(bucket)
+            current_owner = owner
+            bucket = []
+        bucket.append(row[1:])
+    if current_owner is not None and bucket:
+        result[current_owner] = _annotations_from_joined_rows(bucket)
+    return result
+
+
+def _read_annotations_for_owners(
+    conn: duckdb.DuckDBPyConnection,
+    owner_subquery: str,
+    params: list[Any],
+) -> dict[str, Annotations]:
+    """Bulk-load annotations for every owner returned by ``owner_subquery``.
+
+    Issues a single SQL query that joins ``annotation`` with
+    ``annotation_text``. ``owner_subquery`` is a SELECT fragment that
+    yields owner_urn strings — typically scoped by the parent artefact
+    (e.g. ``"SELECT concept_urn FROM concept WHERE scheme_urn = ?"``).
+
+    Returns ``{owner_urn: Annotations}``. Owners with no annotations are
+    absent from the result; callers should default to ``Annotations()``.
+    """
+    return _read_annotations_for_owners_predicate(
+        conn,
+        f"a.owner_urn IN ({owner_subquery})",
+        params,
+    )
+
+
 def _read_spine(conn: duckdb.DuckDBPyConnection, urn: str) -> dict[str, Any] | None:
     """Read artefact metadata from the spine table."""
     row = conn.execute(
@@ -156,7 +280,8 @@ def _read_codelist_eager(conn: duckdb.DuckDBPyConnection, urn: str) -> Codelist
         return None
     name = _read_istring(conn, urn, "name")
     desc = _read_istring(conn, urn, "description")
-    anns = _read_annotations(conn, urn)
+    annotations_by_owner = _read_annotations_subtree(conn, urn)
+    anns = annotations_by_owner.get(urn, Annotations())
 
     rows = conn.execute(
         """
@@ -170,14 +295,13 @@ def _read_codelist_eager(conn: duckdb.DuckDBPyConnection, urn: str) -> Codelist
     codes: list[Code] = []
     for row in rows:
         code_urn, code_id, parent_id, name_map, desc_map = row
-        code_anns = _read_annotations(conn, code_urn)
         codes.append(
             Code(
                 id=code_id,
                 parent_id=parent_id,
                 name=_map_to_istring(name_map),
                 description=_map_to_istring(desc_map),
-                annotations=code_anns,
+                annotations=annotations_by_owner.get(code_urn, Annotations()),
             )
         )
 
@@ -352,7 +476,8 @@ def _read_data_structure(conn: duckdb.DuckDBPyConnection, urn: str) -> DataStruc
         return None
     name = _read_istring(conn, urn, "name")
     desc = _read_istring(conn, urn, "description")
-    anns = _read_annotations(conn, urn)
+    annotations_by_owner = _read_annotations_subtree(conn, urn)
+    anns = annotations_by_owner.get(urn, Annotations())
 
     comp_rows = conn.execute(
         """
@@ -390,7 +515,10 @@ def _read_data_structure(conn: duckdb.DuckDBPyConnection, urn: str) -> DataStruc
             }
             else "Dimension"
         )
-        comp_anns = _read_annotations(conn, _component_urn(urn, urn_class, comp_id_raw))
+        comp_anns = annotations_by_owner.get(
+            _component_urn(urn, urn_class, comp_id_raw),
+            Annotations(),
+        )
         comp_type, comp = _deserialize_component(row, comp_anns)
         match comp_type:
             case "Dimension":
@@ -455,7 +583,8 @@ def _read_concept_scheme(conn: duckdb.DuckDBPyConnection, urn: str) -> ConceptSc
         return None
     name = _read_istring(conn, urn, "name")
     desc = _read_istring(conn, urn, "description")
-    anns = _read_annotations(conn, urn)
+    annotations_by_owner = _read_annotations_subtree(conn, urn)
+    anns = annotations_by_owner.get(urn, Annotations())
 
     rows = conn.execute(
         """
@@ -482,7 +611,7 @@ def _read_concept_scheme(conn: duckdb.DuckDBPyConnection, urn: str) -> ConceptSc
                 max_length=repr_max_length,
             )
 
-        c_anns = _read_annotations(conn, c_urn)
+        c_anns = annotations_by_owner.get(c_urn, Annotations())
         concepts.append(
             Concept(
                 id=c_id,
@@ -511,7 +640,8 @@ def _read_hierarchy(conn: duckdb.DuckDBPyConnection, urn: str) -> "Hierarchy | N
         return None
     name = _read_istring(conn, urn, "name")
     desc = _read_istring(conn, urn, "description")
-    anns = _read_annotations(conn, urn)
+    annotations_by_owner = _read_annotations_subtree(conn, urn)
+    anns = annotations_by_owner.get(urn, Annotations())
 
     # SDMX 3.1: read Level definitions
     level_rows = conn.execute(
@@ -556,7 +686,7 @@ def _read_hierarchy(conn: duckdb.DuckDBPyConnection, urn: str) -> "Hierarchy | N
         if level_id and level_id in levels_by_id:
             level = levels_by_id[level_id]
 
-        node_anns = _read_annotations(conn, node_urn)
+        node_anns = annotations_by_owner.get(node_urn, Annotations())
         node = HierarchicalCode(
             id=node_id,
             code=code_ref,
@@ -670,7 +800,8 @@ def _read_category_scheme(conn: duckdb.DuckDBPyConnection, urn: str) -> "Categor
         return None
     name = _read_istring(conn, urn, "name")
     desc = _read_istring(conn, urn, "description")
-    anns = _read_annotations(conn, urn)
+    annotations_by_owner = _read_annotations_subtree(conn, urn)
+    anns = annotations_by_owner.get(urn, Annotations())
 
     rows = conn.execute(
         """
@@ -686,7 +817,7 @@ def _read_category_scheme(conn: duckdb.DuckDBPyConnection, urn: str) -> "Categor
 
     for row in rows:
         cat_urn, cat_id, parent_id, c_name, c_desc = row
-        cat_anns = _read_annotations(conn, cat_urn)
+        cat_anns = annotations_by_owner.get(cat_urn, Annotations())
         cat = Category(
             id=cat_id,
             name=_map_to_istring(c_name),
@@ -774,38 +905,43 @@ def _read_agency_scheme(conn: duckdb.DuckDBPyConnection, urn: str) -> "AgencySch
         return None
     name = _read_istring(conn, urn, "name")
     desc = _read_istring(conn, urn, "description")
-    anns = _read_annotations(conn, urn)
+    annotations_by_owner = _read_annotations_subtree(conn, urn)
+    anns = annotations_by_owner.get(urn, Annotations())
 
     rows = conn.execute(
         "SELECT agency_urn, agency_id, parent_id, name, description FROM agency WHERE scheme_urn = ?",
         [urn],
     ).fetchall()
 
-    agencies: list[Agency] = []
-    for row in rows:
-        ag_urn, ag_id, _parent_id, ag_name, ag_desc = row
-        # Contacts
-        contact_rows = conn.execute(
-            """
-            SELECT contact_name, department, role, phones, uris, emails
-            FROM agency_contact WHERE agency_urn = ?
-            ORDER BY ordinal
-            """,
-            [ag_urn],
-        ).fetchall()
-        contacts = [
+    # Bulk-load contacts once, grouped by agency_urn.
+    contacts_by_agency: dict[str, list[Contact]] = {}
+    contact_rows = conn.execute(
+        """
+        SELECT agency_urn, contact_name, department, role, phones, uris, emails
+        FROM agency_contact
+        WHERE agency_urn IN (SELECT agency_urn FROM agency WHERE scheme_urn = ?)
+        ORDER BY agency_urn, ordinal
+        """,
+        [urn],
+    ).fetchall()
+    for cr in contact_rows:
+        ag_urn_c, c_name, c_dept, c_role, c_phones, c_uris, c_emails = cr
+        contacts_by_agency.setdefault(ag_urn_c, []).append(
             Contact(
-                name=_map_to_istring(cr[0]),
-                department=_map_to_istring(cr[1]),
-                role=_map_to_istring(cr[2]),
-                phones=tuple(cr[3] or []),
-                uris=tuple(cr[4] or []),
-                emails=tuple(cr[5] or []),
+                name=_map_to_istring(c_name),
+                department=_map_to_istring(c_dept),
+                role=_map_to_istring(c_role),
+                phones=tuple(c_phones or []),
+                uris=tuple(c_uris or []),
+                emails=tuple(c_emails or []),
             )
-            for cr in contact_rows
-        ]
+        )
 
-        ag_anns = _read_annotations(conn, ag_urn)
+    agencies: list[Agency] = []
+    for row in rows:
+        ag_urn, ag_id, _parent_id, ag_name, ag_desc = row
+        contacts = contacts_by_agency.get(ag_urn, [])
+        ag_anns = annotations_by_owner.get(ag_urn, Annotations())
         agencies.append(
             Agency(
                 id=ag_id,
@@ -835,7 +971,8 @@ def _read_data_provider_scheme(conn: duckdb.DuckDBPyConnection, urn: str) -> "Da
         return None
     name = _read_istring(conn, urn, "name")
     desc = _read_istring(conn, urn, "description")
-    anns = _read_annotations(conn, urn)
+    annotations_by_owner = _read_annotations_subtree(conn, urn)
+    anns = annotations_by_owner.get(urn, Annotations())
 
     rows = conn.execute(
         "SELECT provider_urn, provider_id, name, description FROM data_provider WHERE scheme_urn = ?",
@@ -845,7 +982,7 @@ def _read_data_provider_scheme(conn: duckdb.DuckDBPyConnection, urn: str) -> "Da
     providers: list[DataProvider] = []
     for row in rows:
         p_urn, p_id, p_name, p_desc = row
-        p_anns = _read_annotations(conn, p_urn)
+        p_anns = annotations_by_owner.get(p_urn, Annotations())
         providers.append(
             DataProvider(
                 id=p_id,
@@ -925,7 +1062,8 @@ def _read_metadata_structure(conn: duckdb.DuckDBPyConnection, urn: str) -> "Meta
         return None
     name = _read_istring(conn, urn, "name")
     desc = _read_istring(conn, urn, "description")
-    anns = _read_annotations(conn, urn)
+    annotations_by_owner = _read_annotations_subtree(conn, urn)
+    anns = annotations_by_owner.get(urn, Annotations())
 
     rows = conn.execute(
         """
@@ -983,7 +1121,7 @@ def _read_metadata_structure(conn: duckdb.DuckDBPyConnection, urn: str) -> "Meta
             start_value,
             end_value,
         )
-        attr_anns = _read_annotations(conn, attr_urn)
+        attr_anns = annotations_by_owner.get(attr_urn, Annotations())
 
         node = MetadataAttribute(
             id=attr_id,