pretensor 0.1.0__py3-none-any.whl

pretensor/core/__init__.py

@@ -0,0 +1 @@
+"""Core graph storage, schema DDL, and build pipeline."""

pretensor/core/builder.py

@@ -0,0 +1,307 @@
+"""Build a Kuzu graph from a pipeline :class:`SchemaSnapshot`."""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from pretensor.config import GraphConfig, PretensorConfig
+from pretensor.connectors.models import Column, SchemaSnapshot, ViewDependency
+from pretensor.core.ids import (
+    column_node_id,
+    fk_edge_id,
+    lineage_edge_id,
+    table_node_id,
+)
+from pretensor.core.store import KuzuStore
+from pretensor.graph_models.edge import GraphEdge, LineageEdge
+from pretensor.graph_models.node import GraphNode
+from pretensor.intelligence.discovery import RelationshipDiscovery
+from pretensor.intelligence.embeddings import embeddings_disabled_via_env
+from pretensor.intelligence.pipeline import run_intelligence_layer_sync
+from pretensor.intelligence.steps_embedding import compute_table_embeddings
+from pretensor.visibility.filter import VisibilityFilter
+
+__all__ = ["GraphBuilder", "table_node_id", "fk_edge_id"]
+
+logger = logging.getLogger(__name__)
+
+
+def _filtered_snapshot_for_visibility(
+    snapshot: SchemaSnapshot,
+    visibility_filter: VisibilityFilter,
+) -> SchemaSnapshot:
+    """Drop hidden tables and view dependencies that touch hidden tables."""
+    visible_tables = [
+        t
+        for t in snapshot.tables
+        if visibility_filter.is_table_visible(
+            snapshot.connection_name, t.schema_name, t.name
+        )
+    ]
+    keys = {(t.schema_name, t.name) for t in visible_tables}
+    deps: list[ViewDependency] = []
+    for dep in snapshot.view_dependencies:
+        if (dep.source_schema, dep.source_table) not in keys:
+            continue
+        if (dep.target_schema, dep.target_table) not in keys:
+            continue
+        deps.append(dep)
+    return snapshot.model_copy(
+        update={"tables": visible_tables, "view_dependencies": deps}
+    )
+
+
+class GraphBuilder:
+    """Writes table nodes and foreign-key edges from a snapshot."""
+
+    def build(
+        self,
+        snapshot: SchemaSnapshot,
+        store: KuzuStore,
+        *,
+        run_relationship_discovery: bool = True,
+        replace_mode: str = "full",
+        graph_config: GraphConfig | None = None,
+        config: PretensorConfig | None = None,
+        visibility_filter: VisibilityFilter | None = None,
+    ) -> None:
+        """Populate ``store`` from ``snapshot`` (replaces existing graph content).
+
+        When ``run_relationship_discovery`` is True, runs heuristic discovery and
+        writes ``INFERRED_JOIN`` edges that are not already explicit FKs.
+
+        Args:
+            replace_mode: ``full`` clears the entire graph (default per-connection index).
+                ``connection`` removes only nodes/edges for ``snapshot.connection_name``
+                (unified multi-DB graph file).
+            graph_config: Deprecated. Use ``config.graph`` instead. If both are given,
+                ``config.graph`` takes precedence.
+            config: Full pluggable configuration.  When provided, its ``scorer_registry``
+                and ``combiner`` are forwarded to :class:`RelationshipDiscovery` and
+                its ``graph`` field is forwarded to the intelligence pipeline.
+        """
+        store.ensure_schema()
+        effective_embeddings = (config or PretensorConfig()).embeddings
+        if not effective_embeddings.index_tables and store.has_any_table_embeddings():
+            logger.warning(
+                "Rebuilding without --embeddings: previously computed table "
+                "embeddings will be dropped with the old graph rows. Re-run "
+                "with --embeddings to recompute them."
+            )
+        if replace_mode == "connection":
+            store.clear_connection_subgraph(snapshot.connection_name)
+        else:
+            store.clear_graph()
+
+        snap = (
+            _filtered_snapshot_for_visibility(snapshot, visibility_filter)
+            if visibility_filter is not None
+            else snapshot
+        )
+
+        for table in snap.tables:
+            grants_json = (
+                json.dumps(table.grants, ensure_ascii=False) if table.grants else None
+            )
+            node = GraphNode(
+                node_id=table_node_id(
+                    snap.connection_name, table.schema_name, table.name
+                ),
+                connection_name=snap.connection_name,
+                database=snap.database,
+                schema_name=table.schema_name,
+                table_name=table.name,
+                row_count=table.row_count,
+                row_count_source=table.row_count_source,
+                comment=table.comment,
+                table_type=table.table_type,
+                seq_scan_count=table.seq_scan_count,
+                idx_scan_count=table.idx_scan_count,
+                insert_count=table.insert_count,
+                update_count=table.update_count,
+                delete_count=table.delete_count,
+                is_partitioned=table.is_partitioned,
+                partition_key=table.partition_key,
+                grants_json=grants_json,
+                access_read_count=table.access_read_count,
+                access_write_count=table.access_write_count,
+                days_since_last_access=table.days_since_last_access,
+                potentially_unused=table.potentially_unused,
+                table_bytes=table.table_bytes,
+                clustering_key=table.clustering_key,
+            )
+            store.upsert_table(node)
+            col_names = [c.name for c in table.columns]
+            if visibility_filter is not None:
+                allowed_cols = visibility_filter.visible_columns(
+                    snap.connection_name,
+                    table.schema_name,
+                    table.name,
+                    col_names,
+                )
+                allowed_set = set(allowed_cols)
+                pending = [c for c in table.columns if c.name in allowed_set]
+            else:
+                pending = list(table.columns)
+            written: set[str] = set()
+            while pending:
+                progressed = False
+                next_pass: list[Column] = []
+                for col in pending:
+                    parent_id: str | None = None
+                    if col.parent_column is not None:
+                        if col.parent_column not in written:
+                            next_pass.append(col)
+                            continue
+                        parent_id = column_node_id(
+                            snap.connection_name,
+                            table.schema_name,
+                            table.name,
+                            col.parent_column,
+                        )
+                    cid = column_node_id(
+                        snap.connection_name, table.schema_name, table.name, col.name
+                    )
+                    mcv_json = (
+                        json.dumps(col.most_common_values, ensure_ascii=False)
+                        if col.most_common_values
+                        else None
+                    )
+                    hb_json = (
+                        json.dumps(col.histogram_bounds, ensure_ascii=False)
+                        if col.histogram_bounds
+                        else None
+                    )
+                    store.upsert_column_for_table(
+                        column_node_id=cid,
+                        connection_name=snap.connection_name,
+                        database=snap.database,
+                        schema_name=table.schema_name,
+                        table_name=table.name,
+                        column_name=col.name,
+                        data_type=col.data_type,
+                        nullable=col.nullable,
+                        is_primary_key=col.is_primary_key,
+                        is_foreign_key=col.is_foreign_key,
+                        table_node_id=node.node_id,
+                        comment=col.comment,
+                        default_value=col.default_value,
+                        is_indexed=col.is_indexed,
+                        check_constraints=col.check_constraints,
+                        ordinal_position=col.ordinal_position,
+                        most_common_values_json=mcv_json,
+                        histogram_bounds_json=hb_json,
+                        stats_correlation=col.stats_correlation,
+                        column_cardinality=col.column_cardinality,
+                        index_type=col.index_type,
+                        index_is_unique=col.index_is_unique,
+                        parent_column_id=parent_id,
+                        is_array=col.is_array,
+                    )
+                    written.add(col.name)
+                    progressed = True
+                if not progressed and next_pass:
+                    logger.warning(
+                        "build: %d column(s) for table %s.%s skipped — "
+                        "unresolvable parent_column reference(s): %s",
+                        len(next_pass),
+                        table.schema_name,
+                        table.name,
+                        ", ".join(col.name for col in next_pass),
+                    )
+                    break
+                pending = next_pass
+
+        known = {
+            table_node_id(snap.connection_name, t.schema_name, t.name)
+            for t in snap.tables
+        }
+
+        for table in snap.tables:
+            for fk in table.foreign_keys:
+                src_id = table_node_id(
+                    snap.connection_name, fk.source_schema, fk.source_table
+                )
+                dst_id = table_node_id(
+                    snap.connection_name, fk.target_schema, fk.target_table
+                )
+                if src_id not in known or dst_id not in known:
+                    continue
+                edge = GraphEdge(
+                    edge_id=fk_edge_id(fk),
+                    source_node_id=src_id,
+                    target_node_id=dst_id,
+                    source_column=fk.source_column,
+                    target_column=fk.target_column,
+                    constraint_name=fk.constraint_name,
+                )
+                store.merge_fk_edge(edge)
+
+        lineage_by_id: dict[str, LineageEdge] = {}
+        for dep in snap.view_dependencies:
+            src_id = table_node_id(
+                snap.connection_name, dep.source_schema, dep.source_table
+            )
+            dst_id = table_node_id(
+                snap.connection_name, dep.target_schema, dep.target_table
+            )
+            if src_id not in known or dst_id not in known:
+                continue
+            eid = lineage_edge_id(snap.connection_name, dep)
+            src_label = f"{snap.connection_name}:{dep.object_name}"
+            cand = LineageEdge(
+                edge_id=eid,
+                source_node_id=src_id,
+                target_node_id=dst_id,
+                source=src_label,
+                lineage_type=dep.lineage_type,
+                confidence=float(dep.confidence),
+            )
+            existing = lineage_by_id.get(eid)
+            if existing is None or cand.confidence > existing.confidence:
+                lineage_by_id[eid] = cand
+        for ledge in lineage_by_id.values():
+            store.upsert_lineage_edge(ledge)
+
+        effective_config = config or PretensorConfig()
+        effective_graph_cfg = (
+            effective_config.graph if config else (graph_config or GraphConfig())
+        )
+
+        # Compute embeddings right after schema rows land and BEFORE
+        # relationship discovery, so the embedding relationship scorer, the
+        # clustering blend, and the classify role vote all read vectors
+        # from THIS run instead of lagging one index cycle behind.
+        embeddings_precomputed = False
+        if (
+            effective_config.embeddings.index_tables
+            and not embeddings_disabled_via_env()
+        ):
+            compute_table_embeddings(store, snap.database)
+            embeddings_precomputed = True
+
+        if run_relationship_discovery:
+            from pretensor.intelligence.semantic import (
+                extend_with_embedding_scorer,
+            )
+
+            scorers = extend_with_embedding_scorer(
+                effective_config.scorer_registry,
+                store=store,
+                database_key=snap.database,
+                threshold=effective_config.embeddings.join_threshold,
+            )
+            RelationshipDiscovery(
+                store,
+                scorers=scorers,
+                combiner=effective_config.combiner,
+                graph_config=effective_graph_cfg,
+            ).discover(snap)
+
+        run_intelligence_layer_sync(
+            store,
+            snap.database,
+            config=effective_config,
+            embeddings_precomputed=embeddings_precomputed,
+        )

pretensor/core/dsn_crypto.py

@@ -0,0 +1,51 @@
+"""Fernet encryption for DSN strings at rest under ``.pretensor/``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cryptography.fernet import Fernet, InvalidToken
+
+from pretensor.core.secure_io import (
+    atomic_write_bytes,
+    secure_mkdir,
+    warn_if_world_readable,
+)
+from pretensor.errors import PretensorError
+
+__all__ = ["DSNEncryptor", "DSNDecryptError"]
+
+
+class DSNDecryptError(PretensorError, RuntimeError):
+    """Raised when an encrypted DSN cannot be decrypted."""
+
+
+class DSNEncryptor:
+    """Symmetric encryption for connection strings (key file beside registry)."""
+
+    def __init__(self, key_path: Path) -> None:
+        self._key_path = key_path
+        self._fernet = Fernet(self._load_or_create_key())
+
+    def _load_or_create_key(self) -> bytes:
+        # The directory holding the sole secret that decrypts every DSN is
+        # created 0o700, and the key file 0o600, so a local user on a shared
+        # host cannot read it. An existing too-loose key triggers a warning.
+        secure_mkdir(self._key_path.parent)
+        if self._key_path.exists():
+            warn_if_world_readable(self._key_path)
+            return self._key_path.read_bytes().strip()
+        key = Fernet.generate_key()
+        atomic_write_bytes(self._key_path, key + b"\n", mode=0o600)
+        return key
+
+    def encrypt(self, dsn: str) -> str:
+        """Return urlsafe base64 ciphertext."""
+        return self._fernet.encrypt(dsn.encode("utf-8")).decode("ascii")
+
+    def decrypt(self, token: str) -> str:
+        """Recover the original DSN or raise :class:`DSNDecryptError`."""
+        try:
+            return self._fernet.decrypt(token.encode("ascii")).decode("utf-8")
+        except InvalidToken as exc:
+            raise DSNDecryptError("Invalid encrypted DSN or wrong keystore") from exc

pretensor/core/graph_schema_manager.py

@@ -0,0 +1,246 @@
+"""Schema creation and idempotent column migration for the Kuzu graph.
+
+Extracted from :class:`~pretensor.core.store.KuzuStore` to isolate the
+schema-migration concern from the rest of the store layer.
+:class:`GraphSchemaManager` is composed inside ``KuzuStore``; it owns every
+``ensure_schema`` DDL call and every ``_ensure_*`` / ``_drop_*`` column-migration
+helper so that ``KuzuStore`` can focus on query, upsert, and read operations.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import kuzu
+
+from pretensor.core import schema as graph_schema
+
+logger = logging.getLogger(__name__)
+
+# Kept in sync with ``pretensor.intelligence.embeddings.EMBEDDING_DIM`` (384).
+# Duplicated here to avoid the circular import created by
+# ``intelligence/__init__.py`` eagerly loading ``cluster_labeler`` (which itself
+# imports ``KuzuStore``). The schema DDL literal ``FLOAT[384]`` and this
+# constant are both asserted against the real ``EMBEDDING_DIM`` in tests.
+_SCHEMA_TABLE_EMBEDDING_DIM = 384
+
+
+class GraphSchemaManager:
+    """Owns schema creation and idempotent column migrations for the Kuzu graph."""
+
+    def __init__(self, conn: kuzu.Connection) -> None:
+        self._conn = conn
+
+    def _add_column_if_missing(self, table: str, col_name: str, col_type: str) -> None:
+        try:
+            self._conn.execute(f"ALTER TABLE {table} ADD {col_name} {col_type}")
+        except RuntimeError as exc:
+            message = str(exc).lower()
+            if col_name.lower() in message and "already has" in message:
+                return
+            logger.warning("%s ALTER for %s: %s", table, col_name, exc)
+
+    def _drop_column_if_present(self, table: str, col_name: str) -> None:
+        try:
+            self._conn.execute(f"ALTER TABLE {table} DROP {col_name}")
+        except RuntimeError as exc:
+            message = str(exc).lower()
+            if "does not have" in message or "does not exist" in message:
+                return
+            logger.debug("%s DROP for %s: %s", table, col_name, exc)
+
+    def ensure_schema(self) -> None:
+        """Create node and relationship tables if they do not exist."""
+        self._conn.execute(graph_schema.DDL_CREATE_TABLE_NODE)
+        self._ensure_schema_table_entity_type_column()
+        self._ensure_schema_table_table_type_column()
+        self._ensure_schema_table_catalog_enrichment_columns()
+        self._ensure_schema_table_classification_columns()
+        self._ensure_schema_table_dbt_enrichment_columns()
+        self._ensure_schema_table_description_tags_columns()
+        self._ensure_schema_table_staleness_columns()
+        self._ensure_schema_table_row_count_source_column()
+        self._ensure_schema_table_embedding_column()
+        self._drop_schema_table_legacy_dbt_columns()
+        self._conn.execute(graph_schema.DDL_CREATE_COLUMN_NODE)
+        self._ensure_schema_column_description_column()
+        self._ensure_schema_column_enrichment_columns()
+        self._ensure_schema_column_stats_columns()
+        self._ensure_schema_column_catalog_enrichment_columns()
+        self._ensure_schema_column_nested_columns()
+        self._conn.execute(graph_schema.DDL_CREATE_HAS_COLUMN_REL)
+        self._conn.execute(graph_schema.DDL_CREATE_HAS_SUBCOLUMN_REL)
+        self._conn.execute(graph_schema.DDL_CREATE_ENTITY_NODE)
+        self._conn.execute(graph_schema.DDL_CREATE_REPRESENTS_REL)
+        self._conn.execute(graph_schema.DDL_CREATE_FK_REL)
+        self._ensure_fk_constraint_name_column()
+        self._conn.execute(graph_schema.DDL_CREATE_INFERRED_JOIN_REL)
+        self._conn.execute(graph_schema.DDL_CREATE_LINEAGE_REL)
+        self._conn.execute(graph_schema.DDL_CREATE_SAME_ENTITY_REL)
+        self._conn.execute(graph_schema.DDL_CREATE_CLUSTER_NODE)
+        self._ensure_cluster_stale_column()
+        self._ensure_cluster_schema_pattern_column()
+        self._conn.execute(graph_schema.DDL_CREATE_IN_CLUSTER_REL)
+        self._conn.execute(graph_schema.DDL_CREATE_JOIN_PATH_NODE)
+        self._ensure_join_path_stale_column()
+        self._conn.execute(graph_schema.DDL_CREATE_METRIC_TEMPLATE_NODE)
+        self._ensure_metric_template_stale_column()
+        self._ensure_metric_template_dialect_column()
+        self._conn.execute(graph_schema.DDL_CREATE_METRIC_DEPENDS_REL)
+        self._conn.execute(graph_schema.DDL_CREATE_SEMANTIC_METRIC_NODE)
+        self._conn.execute(graph_schema.DDL_CREATE_SEMANTIC_DIMENSION_NODE)
+        self._conn.execute(graph_schema.DDL_CREATE_SEMANTIC_BUSINESS_RULE_NODE)
+        self._conn.execute(graph_schema.DDL_CREATE_SEMANTIC_METRIC_DEPENDS_REL)
+        self._conn.execute(graph_schema.DDL_CREATE_SEMANTIC_DIMENSION_LEVEL_REL)
+        self._conn.execute(graph_schema.DDL_CREATE_SEMANTIC_RULE_APPLIES_TO_REL)
+        self._conn.execute(graph_schema.DDL_CREATE_EXTERNAL_CONSUMER_NODE)
+        self._conn.execute(graph_schema.DDL_CREATE_CONSUMES_REL)
+
+    def _ensure_schema_table_entity_type_column(self) -> None:
+        """Add ``entity_type`` to ``SchemaTable`` when upgrading older graph files."""
+        self._add_column_if_missing("SchemaTable", "entity_type", "STRING")
+
+    def _ensure_schema_table_table_type_column(self) -> None:
+        """Add ``table_type`` to ``SchemaTable`` when upgrading older graph files."""
+        self._add_column_if_missing("SchemaTable", "table_type", "STRING")
+
+    def _ensure_schema_table_catalog_enrichment_columns(self) -> None:
+        """Add usage, partition, grant, and Snowflake catalog fields for older graphs."""
+        for col_name, col_type in (
+            ("seq_scan_count", "INT64"),
+            ("idx_scan_count", "INT64"),
+            ("insert_count", "INT64"),
+            ("update_count", "INT64"),
+            ("delete_count", "INT64"),
+            ("is_partitioned", "BOOL"),
+            ("partition_key", "STRING"),
+            ("grants_json", "STRING"),
+            ("access_read_count", "INT64"),
+            ("access_write_count", "INT64"),
+            ("days_since_last_access", "INT64"),
+            ("potentially_unused", "BOOL"),
+            ("table_bytes", "INT64"),
+            ("clustering_key", "STRING"),
+        ):
+            self._add_column_if_missing("SchemaTable", col_name, col_type)
+
+    def _ensure_schema_table_classification_columns(self) -> None:
+        """Add classifier fields for older graph files."""
+        for col_name, col_type in (
+            ("role", "STRING"),
+            ("role_confidence", "DOUBLE"),
+            ("classification_signals", "STRING"),
+        ):
+            self._add_column_if_missing("SchemaTable", col_name, col_type)
+
+    def _ensure_schema_table_dbt_enrichment_columns(self) -> None:
+        """Add dbt semantic-layer fields for older graph files."""
+        for col_name, col_type in (
+            ("has_external_consumers", "BOOL"),
+            ("test_count", "INT64"),
+        ):
+            self._add_column_if_missing("SchemaTable", col_name, col_type)
+
+    def _ensure_schema_table_description_tags_columns(self) -> None:
+        """Add first-class ``description`` and ``tags`` for dbt / LLM context."""
+        for col_name, col_type in (
+            ("description", "STRING"),
+            ("tags", "STRING[]"),
+        ):
+            self._add_column_if_missing("SchemaTable", col_name, col_type)
+
+    def _ensure_schema_table_staleness_columns(self) -> None:
+        """Add dbt source-freshness fields (``staleness_status``/``staleness_as_of``)."""
+        for col_name, col_type in (
+            ("staleness_status", "STRING"),
+            ("staleness_as_of", "STRING"),
+        ):
+            self._add_column_if_missing("SchemaTable", col_name, col_type)
+
+    def _ensure_schema_table_row_count_source_column(self) -> None:
+        """Add ``row_count_source`` for older graph files (view-count provenance)."""
+        self._add_column_if_missing("SchemaTable", "row_count_source", "STRING")
+
+    def _ensure_schema_table_embedding_column(self) -> None:
+        """Add ``embedding FLOAT[384]`` to ``SchemaTable`` for older graph files."""
+        self._add_column_if_missing(
+            "SchemaTable",
+            "embedding",
+            f"FLOAT[{_SCHEMA_TABLE_EMBEDDING_DIM}]",
+        )
+
+    def _drop_schema_table_legacy_dbt_columns(self) -> None:
+        """Drop legacy duplicates ``dbt_description`` and ``tags_json``.
+
+        These were superseded by the first-class ``description`` / ``tags``
+        fields added in the dbt enrichment update. Older graph files that were
+        written before the consolidation may still have them; silently drop if
+        present.
+        """
+        for col_name in ("dbt_description", "tags_json"):
+            self._drop_column_if_present("SchemaTable", col_name)
+
+    def _ensure_schema_column_description_column(self) -> None:
+        """Add ``description`` on ``SchemaColumn`` for dbt column docs."""
+        self._add_column_if_missing("SchemaColumn", "description", "STRING")
+
+    def _ensure_schema_column_enrichment_columns(self) -> None:
+        """Add column comment / constraint fields for older Kuzu files."""
+        for col_name, col_type in (
+            ("comment", "STRING"),
+            ("default_value", "STRING"),
+            ("is_indexed", "BOOL"),
+            ("check_constraints_json", "STRING"),
+            ("ordinal_position", "INT64"),
+        ):
+            self._add_column_if_missing("SchemaColumn", col_name, col_type)
+
+    def _ensure_schema_column_stats_columns(self) -> None:
+        """Add planner statistics mirror fields for older Kuzu files."""
+        for col_name, col_type in (
+            ("most_common_values_json", "STRING"),
+            ("histogram_bounds_json", "STRING"),
+            ("stats_correlation", "DOUBLE"),
+        ):
+            self._add_column_if_missing("SchemaColumn", col_name, col_type)
+
+    def _ensure_schema_column_catalog_enrichment_columns(self) -> None:
+        """Add catalog cardinality and index-detail fields for older Kuzu files."""
+        for col_name, col_type in (
+            ("column_cardinality", "INT64"),
+            ("index_type", "STRING"),
+            ("index_is_unique", "BOOL"),
+        ):
+            self._add_column_if_missing("SchemaColumn", col_name, col_type)
+
+    def _ensure_schema_column_nested_columns(self) -> None:
+        """Add nested-column linkage fields for older Kuzu files."""
+        for col_name, col_type in (
+            ("parent_column_id", "STRING"),
+            ("is_array", "BOOL"),
+        ):
+            self._add_column_if_missing("SchemaColumn", col_name, col_type)
+
+    def _ensure_fk_constraint_name_column(self) -> None:
+        """Add ``constraint_name`` to ``FK_REFERENCES`` when upgrading older graph files."""
+        self._add_column_if_missing("FK_REFERENCES", "constraint_name", "STRING")
+
+    def _ensure_cluster_stale_column(self) -> None:
+        """Add ``stale`` to ``Cluster`` when upgrading older graph files."""
+        self._add_column_if_missing("Cluster", "stale", "BOOL")
+
+    def _ensure_cluster_schema_pattern_column(self) -> None:
+        """Add ``schema_pattern`` to ``Cluster`` when upgrading older graph files."""
+        self._add_column_if_missing("Cluster", "schema_pattern", "STRING")
+
+    def _ensure_join_path_stale_column(self) -> None:
+        """Add ``stale`` to ``JoinPath`` when upgrading older graph files."""
+        self._add_column_if_missing("JoinPath", "stale", "BOOL")
+
+    def _ensure_metric_template_stale_column(self) -> None:
+        """Add ``stale`` to ``MetricTemplate`` when upgrading older graph files."""
+        self._add_column_if_missing("MetricTemplate", "stale", "BOOL")
+
+    def _ensure_metric_template_dialect_column(self) -> None:
+        """Add ``dialect`` to ``MetricTemplate`` when upgrading older graph files."""
+        self._add_column_if_missing("MetricTemplate", "dialect", "STRING")