kumoai 2.13.0.dev202511191731__cp310-cp310-macosx_11_0_arm64.whl → 2.14.0rc2__cp310-cp310-macosx_11_0_arm64.whl

kumoai/experimental/rfm/{local_graph.py → graph.py}

@@ -1,9 +1,15 @@
+from __future__ import annotations
+
 import contextlib
+import copy
 import io
 import warnings
 from collections import defaultdict
-from importlib.util import find_spec
-from typing import TYPE_CHECKING, Dict, List, Optional, Union
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from itertools import chain
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Union
 
 import pandas as pd
 from kumoapi.graph import ColumnKey, ColumnKeyGroup, GraphDefinition
@@ -11,20 +17,30 @@ from kumoapi.table import TableDefinition
 from kumoapi.typing import Stype
 from typing_extensions import Self
 
-from kumoai import in_notebook
-from kumoai.experimental.rfm import LocalTable
+from kumoai import in_notebook, in_snowflake_notebook
+from kumoai.experimental.rfm.base import ColumnSpec, DataBackend, Table
 from kumoai.graph import Edge
+from kumoai.mixin import CastMixin
+from kumoai.utils import display
 
 if TYPE_CHECKING:
     import graphviz
+    from adbc_driver_sqlite.dbapi import AdbcSqliteConnection
+    from snowflake.connector import SnowflakeConnection
+
+
+@dataclass
+class SqliteConnectionConfig(CastMixin):
+    uri: str | Path
+    kwargs: dict[str, Any] = field(default_factory=dict)
 
 
-class LocalGraph:
-    r"""A graph of :class:`LocalTable` objects, akin to relationships between
+class Graph:
+    r"""A graph of :class:`Table` objects, akin to relationships between
     tables in a relational database.
 
     Creating a graph is the final step of data definition; after a
-    :class:`LocalGraph` is created, you can use it to initialize the
+    :class:`Graph` is created, you can use it to initialize the
     Kumo Relational Foundation Model (:class:`KumoRFM`).
 
     .. code-block:: python
@@ -44,7 +60,7 @@ class LocalGraph:
         >>> table3 = rfm.LocalTable(name="table3", data=df3)
 
         >>> # Create a graph from a dictionary of tables:
-        >>> graph = rfm.LocalGraph({
+        >>> graph = rfm.Graph({
         ...     "table1": table1,
         ...     "table2": table2,
         ...     "table3": table3,
@@ -75,33 +91,55 @@ class LocalGraph:
 
     def __init__(
         self,
-        tables: List[LocalTable],
-        edges: Optional[List[Edge]] = None,
+        tables: Sequence[Table],
+        edges: Sequence[Edge] | None = None,
     ) -> None:
 
-        self._tables: Dict[str, LocalTable] = {}
-        self._edges: List[Edge] = []
+        self._tables: dict[str, Table] = {}
+        self._edges: list[Edge] = []
 
         for table in tables:
             self.add_table(table)
 
+        for table in tables:  # Use links from source metadata:
+            if not any(column.is_source for column in table.columns):
+                continue
+            for fkey in table._source_foreign_key_dict.values():
+                if fkey.name not in table:
+                    continue
+                if not table[fkey.name].is_source:
+                    continue
+                dst_table_names = [
+                    table.name for table in self.tables.values()
+                    if table.source_name == fkey.dst_table
+                ]
+                if len(dst_table_names) != 1:
+                    continue
+                dst_table = self[dst_table_names[0]]
+                if dst_table._primary_key != fkey.primary_key:
+                    continue
+                if not dst_table[fkey.primary_key].is_source:
+                    continue
+                self.link(table.name, fkey.name, dst_table.name)
+
         for edge in (edges or []):
             _edge = Edge._cast(edge)
             assert _edge is not None
-            self.link(*_edge)
+            if _edge not in self._edges:
+                self.link(*_edge)
 
     @classmethod
     def from_data(
         cls,
-        df_dict: Dict[str, pd.DataFrame],
-        edges: Optional[List[Edge]] = None,
+        df_dict: dict[str, pd.DataFrame],
+        edges: Sequence[Edge] | None = None,
         infer_metadata: bool = True,
         verbose: bool = True,
     ) -> Self:
-        r"""Creates a :class:`LocalGraph` from a dictionary of
+        r"""Creates a :class:`Graph` from a dictionary of
         :class:`pandas.DataFrame` objects.
 
-        Automatically infers table metadata and links.
+        Automatically infers table metadata and links by default.
 
         .. code-block:: python
 
@@ -115,59 +153,429 @@ class LocalGraph:
             >>> df3 = pd.DataFrame(...)
 
             >>> # Create a graph from a dictionary of data frames:
-            >>> graph = rfm.LocalGraph.from_data({
+            >>> graph = rfm.Graph.from_data({
             ...     "table1": df1,
             ...     "table2": df2,
             ...     "table3": df3,
             ... })
 
-            >>> # Inspect table metadata:
-            >>> for table in graph.tables.values():
-            ...     table.print_metadata()
-
-            >>> # Visualize graph (if graphviz is installed):
-            >>> graph.visualize()
-
         Args:
             df_dict: A dictionary of data frames, where the keys are the names
                 of the tables and the values hold table data.
+            edges: An optional list of :class:`~kumoai.graph.Edge` objects to
+                add to the graph. If not provided, edges will be automatically
+                inferred from the data in case ``infer_metadata=True``.
             infer_metadata: Whether to infer metadata for all tables in the
                 graph.
+            verbose: Whether to print verbose output.
+        """
+        from kumoai.experimental.rfm.backend.local import LocalTable
+
+        graph = cls(
+            tables=[LocalTable(df, name) for name, df in df_dict.items()],
+            edges=edges or [],
+        )
+
+        if infer_metadata:
+            graph.infer_metadata(verbose=False)
+
+            if edges is None:
+                graph.infer_links(verbose=False)
+
+        if verbose:
+            graph.print_metadata()
+            graph.print_links()
+
+        return graph
+
+    @classmethod
+    def from_sqlite(
+        cls,
+        connection: Union[
+            'AdbcSqliteConnection',
+            SqliteConnectionConfig,
+            str,
+            Path,
+            dict[str, Any],
+        ],
+        tables: Sequence[str | dict[str, Any]] | None = None,
+        edges: Sequence[Edge] | None = None,
+        infer_metadata: bool = True,
+        verbose: bool = True,
+    ) -> Self:
+        r"""Creates a :class:`Graph` from a :class:`sqlite` database.
+
+        Automatically infers table metadata and links by default.
+
+        .. code-block:: python
+
+            >>> # doctest: +SKIP
+            >>> import kumoai.experimental.rfm as rfm
+
+            >>> # Create a graph from a SQLite database:
+            >>> graph = rfm.Graph.from_sqlite('data.db')
+
+            >>> # Fine-grained control over table specification:
+            >>> graph = rfm.Graph.from_sqlite('data.db', tables=[
+            ...     'USERS',
+            ...     dict(name='ORDERS', source_name='ORDERS_SNAPSHOT'),
+            ...     dict(name='ITEMS', primary_key='ITEM_ID'),
+            ... ])
+
+        Args:
+            connection: An open connection from
+                :meth:`~kumoai.experimental.rfm.backend.sqlite.connect` or the
+                path to the database file.
+            tables: Set of table names or :class:`SQLiteTable` keyword
+                arguments to include. If ``None``, will add all tables present
+                in the database.
             edges: An optional list of :class:`~kumoai.graph.Edge` objects to
                 add to the graph. If not provided, edges will be automatically
-                inferred from the data.
+                inferred from the data in case ``infer_metadata=True``.
+            infer_metadata: Whether to infer missing metadata for all tables in
+                the graph.
             verbose: Whether to print verbose output.
+        """
+        from kumoai.experimental.rfm.backend.sqlite import (
+            Connection,
+            SQLiteTable,
+            connect,
+        )
+
+        internal_connection = False
+        if not isinstance(connection, Connection):
+            connection = SqliteConnectionConfig._cast(connection)
+            assert isinstance(connection, SqliteConnectionConfig)
+            connection = connect(connection.uri, **connection.kwargs)
+            internal_connection = True
+        assert isinstance(connection, Connection)
+
+        if tables is None:
+            with connection.cursor() as cursor:
+                cursor.execute("SELECT name FROM sqlite_master "
+                               "WHERE type='table'")
+                tables = [row[0] for row in cursor.fetchall()]
+
+        table_kwargs: list[dict[str, Any]] = []
+        for table in tables:
+            kwargs = dict(name=table) if isinstance(table, str) else table
+            table_kwargs.append(kwargs)
 
-        Note:
-            This method will automatically infer metadata and links for the
-            graph.
+        graph = cls(
+            tables=[
+                SQLiteTable(connection=connection, **kwargs)
+                for kwargs in table_kwargs
+            ],
+            edges=edges or [],
+        )
+
+        if internal_connection:
+            graph._connection = connection  # type: ignore
+
+        if infer_metadata:
+            graph.infer_metadata(verbose=False)
+
+            if edges is None:
+                graph.infer_links(verbose=False)
+
+        if verbose:
+            graph.print_metadata()
+            graph.print_links()
+
+        return graph
+
+    @classmethod
+    def from_snowflake(
+        cls,
+        connection: Union['SnowflakeConnection', dict[str, Any], None] = None,
+        tables: Sequence[str | dict[str, Any]] | None = None,
+        database: str | None = None,
+        schema: str | None = None,
+        edges: Sequence[Edge] | None = None,
+        infer_metadata: bool = True,
+        verbose: bool = True,
+    ) -> Self:
+        r"""Creates a :class:`Graph` from a :class:`snowflake` database and
+        schema.
+
+        Automatically infers table metadata and links by default.
+
+        .. code-block:: python
 
-        Example:
             >>> # doctest: +SKIP
             >>> import kumoai.experimental.rfm as rfm
-            >>> df1 = pd.DataFrame(...)
-            >>> df2 = pd.DataFrame(...)
-            >>> df3 = pd.DataFrame(...)
-            >>> graph = rfm.LocalGraph.from_data(data={
-            ...     "table1": df1,
-            ...     "table2": df2,
-            ...     "table3": df3,
-            ... })
-            >>> graph.validate()
-        """
-        tables = [LocalTable(df, name) for name, df in df_dict.items()]
 
-        graph = cls(tables, edges=edges or [])
+            >>> # Create a graph directly in a Snowflake notebook:
+            >>> graph = rfm.Graph.from_snowflake(schema='my_schema')
+
+            >>> # Fine-grained control over table specification:
+            >>> graph = rfm.Graph.from_snowflake(tables=[
+            ...     'USERS',
+            ...     dict(name='ORDERS', source_name='ORDERS_SNAPSHOT'),
+            ...     dict(name='ITEMS', schema='OTHER_SCHEMA'),
+            ... ], database='DEFAULT_DB', schema='DEFAULT_SCHEMA')
+
+        Args:
+            connection: An open connection from
+                :meth:`~kumoai.experimental.rfm.backend.snow.connect` or the
+                :class:`snowflake` connector keyword arguments to open a new
+                connection. If ``None``, will re-use an active session in case
+                it exists, or create a new connection from credentials stored
+                in environment variables.
+            tables: Set of table names or :class:`SnowTable` keyword arguments
+                to include. If ``None``, will add all tables present in the
+                current database and schema.
+            database: The database.
+            schema: The schema.
+            edges: An optional list of :class:`~kumoai.graph.Edge` objects to
+                add to the graph. If not provided, edges will be automatically
+                inferred from the data in case ``infer_metadata=True``.
+            infer_metadata: Whether to infer metadata for all tables in the
+                graph.
+            verbose: Whether to print verbose output.
+        """
+        from kumoai.experimental.rfm.backend.snow import (
+            Connection,
+            SnowTable,
+            connect,
+        )
+
+        if not isinstance(connection, Connection):
+            connection = connect(**(connection or {}))
+        assert isinstance(connection, Connection)
+
+        if database is None or schema is None:
+            with connection.cursor() as cursor:
+                cursor.execute("SELECT CURRENT_DATABASE(), CURRENT_SCHEMA()")
+                result = cursor.fetchone()
+                database = database or result[0]
+                assert database is not None
+                schema = schema or result[1]
+
+        if tables is None:
+            if schema is None:
+                raise ValueError("No current 'schema' set. Please specify the "
+                                 "Snowflake schema manually")
+
+            with connection.cursor() as cursor:
+                cursor.execute(f"""
+                SELECT TABLE_NAME
+                FROM {database}.INFORMATION_SCHEMA.TABLES
+                WHERE TABLE_SCHEMA = '{schema}'
+                """)
+                tables = [row[0] for row in cursor.fetchall()]
+
+        table_kwargs: list[dict[str, Any]] = []
+        for table in tables:
+            if isinstance(table, str):
+                kwargs = dict(name=table, database=database, schema=schema)
+            else:
+                kwargs = copy.copy(table)
+                kwargs.setdefault('database', database)
+                kwargs.setdefault('schema', schema)
+            table_kwargs.append(kwargs)
+
+        graph = cls(
+            tables=[
+                SnowTable(connection=connection, **kwargs)
+                for kwargs in table_kwargs
+            ],
+            edges=edges or [],
+        )
 
         if infer_metadata:
-            graph.infer_metadata(verbose)
+            graph.infer_metadata(verbose=False)
 
             if edges is None:
-                graph.infer_links(verbose)
+                graph.infer_links(verbose=False)
+
+        if verbose:
+            graph.print_metadata()
+            graph.print_links()
 
         return graph
 
-    # Tables ##############################################################
+    @classmethod
+    def from_snowflake_semantic_view(
+        cls,
+        semantic_view_name: str,
+        connection: Union['SnowflakeConnection', dict[str, Any], None] = None,
+        verbose: bool = True,
+    ) -> Self:
+        import yaml
+
+        from kumoai.experimental.rfm.backend.snow import (
+            Connection,
+            SnowTable,
+            connect,
+        )
+
+        if not isinstance(connection, Connection):
+            connection = connect(**(connection or {}))
+        assert isinstance(connection, Connection)
+
+        with connection.cursor() as cursor:
+            cursor.execute(f"SELECT SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW("
+                           f"'{semantic_view_name}')")
+            cfg = yaml.safe_load(cursor.fetchone()[0])
+
+        graph = cls(tables=[])
+
+        msgs = []
+        table_names = {table_cfg['name'] for table_cfg in cfg['tables']}
+        for table_cfg in cfg['tables']:
+            table_name = table_cfg['name']
+            source_table_name = table_cfg['base_table']['table']
+            database = table_cfg['base_table']['database']
+            schema = table_cfg['base_table']['schema']
+
+            primary_key: str | None = None
+            if 'primary_key' in table_cfg:
+                primary_key_cfg = table_cfg['primary_key']
+                if len(primary_key_cfg['columns']) == 1:
+                    primary_key = primary_key_cfg['columns'][0]
+                elif len(primary_key_cfg['columns']) > 1:
+                    msgs.append(f"Failed to add primary key for table "
+                                f"'{table_name}' since composite primary keys "
+                                f"are not yet supported")
+
+            columns: list[ColumnSpec] = []
+            unsupported_columns: list[str] = []
+            for column_cfg in chain(
+                    table_cfg.get('dimensions', []),
+                    table_cfg.get('time_dimensions', []),
+                    table_cfg.get('facts', []),
+            ):
+                column_name = column_cfg['name']
+                column_expr = column_cfg.get('expr', None)
+                column_data_type = column_cfg.get('data_type', None)
+
+                if column_expr is None:
+                    columns.append(ColumnSpec(name=column_name))
+                    continue
+
+                column_expr = column_expr.replace(f'{table_name}.', '')
+
+                if column_expr == column_name:
+                    columns.append(ColumnSpec(name=column_name))
+                    continue
+
+                # Drop expressions that reference other tables (for now):
+                if any(f'{name}.' in column_expr for name in table_names):
+                    unsupported_columns.append(column_name)
+                    continue
+
+                column = ColumnSpec(
+                    name=column_name,
+                    expr=column_expr,
+                    dtype=SnowTable._to_dtype(column_data_type),
+                )
+                columns.append(column)
+
+            if len(unsupported_columns) == 1:
+                msgs.append(f"Failed to add column '{unsupported_columns[0]}' "
+                            f"of table '{table_name}' since its expression "
+                            f"references other tables")
+            elif len(unsupported_columns) > 1:
+                msgs.append(f"Failed to add columns '{unsupported_columns}' "
+                            f"of table '{table_name}' since their expressions "
+                            f"reference other tables")
+
+            table = SnowTable(
+                connection,
+                name=table_name,
+                source_name=source_table_name,
+                database=database,
+                schema=schema,
+                columns=columns,
+                primary_key=primary_key,
+            )
+
+            # TODO Add a way to register time columns without heuristic usage.
+            table.infer_time_column(verbose=False)
+
+            graph.add_table(table)
+
+        for relation_cfg in cfg.get('relationships', []):
+            name = relation_cfg['name']
+            if len(relation_cfg['relationship_columns']) != 1:
+                msgs.append(f"Failed to add relationship '{name}' since "
+                            f"composite key references are not yet supported")
+                continue
+
+            left_table = relation_cfg['left_table']
+            left_key = relation_cfg['relationship_columns'][0]['left_column']
+            right_table = relation_cfg['right_table']
+            right_key = relation_cfg['relationship_columns'][0]['right_column']
+
+            if graph[right_table]._primary_key != right_key:
+                # Semantic view error - this should never be triggered:
+                msgs.append(f"Failed to add relationship '{name}' since the "
+                            f"referenced key '{right_key}' of table "
+                            f"'{right_table}' is not a primary key")
+                continue
+
+            if graph[left_table]._primary_key == left_key:
+                msgs.append(f"Failed to add relationship '{name}' since the "
+                            f"referencing key '{left_key}' of table "
+                            f"'{left_table}' is a primary key")
+                continue
+
+            if left_key not in graph[left_table]:
+                graph[left_table].add_column(left_key)
+
+            graph.link(left_table, left_key, right_table)
+
+        graph.validate()
+
+        if verbose:
+            graph.print_metadata()
+            graph.print_links()
+
+        if len(msgs) > 0:
+            title = (f"Could not fully convert the semantic view definition "
+                     f"'{semantic_view_name}' into a graph:\n")
+            warnings.warn(title + '\n'.join(f'- {msg}' for msg in msgs))
+
+        return graph
+
+    @classmethod
+    def from_relbench(
+        cls,
+        dataset: str,
+        verbose: bool = True,
+    ) -> Graph:
+        r"""Loads a `RelBench <https://relbench.stanford.edu>`_ dataset into a
+        :class:`Graph` instance.
+
+        .. code-block:: python
+
+            >>> # doctest: +SKIP
+            >>> import kumoai.experimental.rfm as rfm
+
+            >>> graph = rfm.Graph.from_relbench("f1")
+
+        Args:
+            dataset: The RelBench dataset name.
+            verbose: Whether to print verbose output.
+        """
+        from kumoai.experimental.rfm.relbench import from_relbench
+        graph = from_relbench(dataset, verbose=verbose)
+
+        if verbose:
+            graph.print_metadata()
+            graph.print_links()
+
+        return graph
+
+    # Backend #################################################################
+
+    @property
+    def backend(self) -> DataBackend | None:
+        backends = [table.backend for table in self._tables.values()]
+        return backends[0] if len(backends) > 0 else None
+
+    # Tables ##################################################################
 
     def has_table(self, name: str) -> bool:
         r"""Returns ``True`` if the graph has a table with name ``name``;
@@ -175,7 +583,7 @@ class LocalGraph:
         """
         return name in self.tables
 
-    def table(self, name: str) -> LocalTable:
+    def table(self, name: str) -> Table:
         r"""Returns the table with name ``name`` in the graph.
 
         Raises:
@@ -186,11 +594,11 @@ class LocalGraph:
         return self.tables[name]
 
     @property
-    def tables(self) -> Dict[str, LocalTable]:
+    def tables(self) -> dict[str, Table]:
         r"""Returns the dictionary of table objects."""
         return self._tables
 
-    def add_table(self, table: LocalTable) -> Self:
+    def add_table(self, table: Table) -> Self:
         r"""Adds a table to the graph.
 
         Args:
@@ -199,11 +607,18 @@ class LocalGraph:
         Raises:
             KeyError: If a table with the same name already exists in the
                 graph.
+            ValueError: If the table belongs to a different backend than the
+                rest of the tables in the graph.
         """
         if table.name in self._tables:
             raise KeyError(f"Cannot add table with name '{table.name}' to "
                            f"this graph; table names must be globally unique.")
 
+        if self.backend is not None and table.backend != self.backend:
+            raise ValueError(f"Cannot register a table with backend "
+                             f"'{table.backend}' to this graph since other "
+                             f"tables have backend '{self.backend}'.")
+
         self._tables[table.name] = table
 
         return self
@@ -234,28 +649,28 @@ class LocalGraph:
         r"""Returns a :class:`pandas.DataFrame` object containing metadata
         information about the tables in this graph.
 
-        The returned dataframe has columns ``name``, ``primary_key``,
-        ``time_column``, and ``end_time_column``, which provide an aggregate
-        view of the properties of the tables of this graph.
+        The returned dataframe has columns ``"Name"``, ``"Primary Key"``,
+        ``"Time Column"``, and ``"End Time Column"``, which provide an
+        aggregated view of the properties of the tables of this graph.
 
         Example:
             >>> # doctest: +SKIP
             >>> import kumoai.experimental.rfm as rfm
-            >>> graph = rfm.LocalGraph(tables=...).infer_metadata()
+            >>> graph = rfm.Graph(tables=...).infer_metadata()
             >>> graph.metadata  # doctest: +SKIP
-                name   primary_key  time_column  end_time_column
-            0   users      user_id            -                -
+                Name   Primary Key  Time Column  End Time Column
+            0   users  user_id      -            -
         """
         tables = list(self.tables.values())
 
         return pd.DataFrame({
-            'name':
+            'Name':
             pd.Series(dtype=str, data=[t.name for t in tables]),
-            'primary_key':
+            'Primary Key':
             pd.Series(dtype=str, data=[t._primary_key or '-' for t in tables]),
-            'time_column':
+            'Time Column':
             pd.Series(dtype=str, data=[t._time_column or '-' for t in tables]),
-            'end_time_column':
+            'End Time Column':
             pd.Series(
                 dtype=str,
                 data=[t._end_time_column or '-' for t in tables],
@@ -263,21 +678,9 @@ class LocalGraph:
         })
 
     def print_metadata(self) -> None:
-        r"""Prints the :meth:`~LocalGraph.metadata` of the graph."""
-        if in_notebook():
-            from IPython.display import Markdown, display
-            display(Markdown('### 🗂️ Graph Metadata'))
-            df = self.metadata
-            try:
-                if hasattr(df.style, 'hide'):
-                    display(df.style.hide(axis='index'))  # pandas=2
-                else:
-                    display(df.style.hide_index())  # pandas<1.3
-            except ImportError:
-                print(df.to_string(index=False))  # missing jinja2
-        else:
-            print("🗂️ Graph Metadata:")
-            print(self.metadata.to_string(index=False))
+        r"""Prints the :meth:`~Graph.metadata` of the graph."""
+        display.title("🗂️ Graph Metadata")
+        display.dataframe(self.metadata)
 
     def infer_metadata(self, verbose: bool = True) -> Self:
         r"""Infers metadata for all tables in the graph.
@@ -287,7 +690,7 @@ class LocalGraph:
 
         Note:
             For more information, please see
-            :meth:`kumoai.experimental.rfm.LocalTable.infer_metadata`.
+            :meth:`kumoai.experimental.rfm.Table.infer_metadata`.
         """
         for table in self.tables.values():
             table.infer_metadata(verbose=False)
@@ -300,42 +703,33 @@ class LocalGraph:
     # Edges ###################################################################
 
     @property
-    def edges(self) -> List[Edge]:
+    def edges(self) -> list[Edge]:
         r"""Returns the edges of the graph."""
         return self._edges
 
     def print_links(self) -> None:
-        r"""Prints the :meth:`~LocalGraph.edges` of the graph."""
-        edges = [(edge.dst_table, self[edge.dst_table]._primary_key,
-                  edge.src_table, edge.fkey) for edge in self.edges]
-        edges = sorted(edges)
-
-        if in_notebook():
-            from IPython.display import Markdown, display
-            display(Markdown('### 🕸️ Graph Links (FK ↔️ PK)'))
-            if len(edges) > 0:
-                display(
-                    Markdown('\n'.join([
-                        f'- `{edge[2]}.{edge[3]}` ↔️ `{edge[0]}.{edge[1]}`'
-                        for edge in edges
-                    ])))
-            else:
-                display(Markdown('*No links registered*'))
+        r"""Prints the :meth:`~Graph.edges` of the graph."""
+        edges = sorted([(
+            edge.dst_table,
+            self[edge.dst_table]._primary_key,
+            edge.src_table,
+            edge.fkey,
+        ) for edge in self.edges])
+
+        display.title("🕸️ Graph Links (FK ↔️ PK)")
+        if len(edges) > 0:
+            display.unordered_list(items=[
+                f"`{edge[2]}.{edge[3]}` ↔️ `{edge[0]}.{edge[1]}`"
+                for edge in edges
+            ])
         else:
-            print("🕸️ Graph Links (FK ↔️ PK):")
-            if len(edges) > 0:
-                print('\n'.join([
-                    f'• {edge[2]}.{edge[3]} ↔️ {edge[0]}.{edge[1]}'
-                    for edge in edges
-                ]))
-            else:
-                print('No links registered')
+            display.italic("No links registered")
 
     def link(
         self,
-        src_table: Union[str, LocalTable],
+        src_table: str | Table,
         fkey: str,
-        dst_table: Union[str, LocalTable],
+        dst_table: str | Table,
     ) -> Self:
         r"""Links two tables (``src_table`` and ``dst_table``) from the foreign
         key ``fkey`` in the source table to the primary key in the destination
@@ -358,11 +752,11 @@ class LocalGraph:
                 table does not exist in the graph, if the source key does not
                 exist in the source table.
         """
-        if isinstance(src_table, LocalTable):
+        if isinstance(src_table, Table):
             src_table = src_table.name
         assert isinstance(src_table, str)
 
-        if isinstance(dst_table, LocalTable):
+        if isinstance(dst_table, Table):
             dst_table = dst_table.name
         assert isinstance(dst_table, str)
 
@@ -396,9 +790,9 @@ class LocalGraph:
 
     def unlink(
         self,
-        src_table: Union[str, LocalTable],
+        src_table: str | Table,
         fkey: str,
-        dst_table: Union[str, LocalTable],
+        dst_table: str | Table,
     ) -> Self:
         r"""Removes an :class:`~kumoai.graph.Edge` from the graph.
 
@@ -410,11 +804,11 @@ class LocalGraph:
         Raises:
             ValueError: if the edge is not present in the graph.
         """
-        if isinstance(src_table, LocalTable):
+        if isinstance(src_table, Table):
             src_table = src_table.name
         assert isinstance(src_table, str)
 
-        if isinstance(dst_table, LocalTable):
+        if isinstance(dst_table, Table):
             dst_table = dst_table.name
         assert isinstance(dst_table, str)
 
@@ -428,17 +822,37 @@ class LocalGraph:
         return self
 
     def infer_links(self, verbose: bool = True) -> Self:
-        r"""Infers links for the tables and adds them as edges to the graph.
+        r"""Infers missing links for the tables and adds them as edges to the
+        graph.
 
         Args:
             verbose: Whether to print verbose output.
-
-        Note:
-            This function expects graph edges to be undefined upfront.
         """
-        if len(self.edges) > 0:
-            warnings.warn("Cannot infer links if graph edges already exist")
-            return self
+        known_edges = {(edge.src_table, edge.fkey) for edge in self.edges}
+
+        for table in self.tables.values():  # Use links from source metadata:
+            if not any(column.is_source for column in table.columns):
+                continue
+            for fkey in table._source_foreign_key_dict.values():
+                if fkey.name not in table:
+                    continue
+                if not table[fkey.name].is_source:
+                    continue
+                if (table.name, fkey.name) in known_edges:
+                    continue
+                dst_table_names = [
+                    table.name for table in self.tables.values()
+                    if table.source_name == fkey.dst_table
+                ]
+                if len(dst_table_names) != 1:
+                    continue
+                dst_table = self[dst_table_names[0]]
+                if dst_table._primary_key != fkey.primary_key:
+                    continue
+                if not dst_table[fkey.primary_key].is_source:
+                    continue
+                self.link(table.name, fkey.name, dst_table.name)
+                known_edges.add((table.name, fkey.name))
 
         # A list of primary key candidates (+score) for every column:
         candidate_dict: dict[
@@ -463,6 +877,9 @@ class LocalGraph:
                 src_table_name = src_table.name.lower()
 
                 for src_key in src_table.columns:
+                    if (src_table.name, src_key.name) in known_edges:
+                        continue
+
                     if src_key == src_table.primary_key:
                         continue  # Cannot link to primary key.
 
@@ -528,19 +945,16 @@ class LocalGraph:
                         score += 1.0
 
                     # Cardinality ratio:
-                    if len(src_table._data) > len(dst_table._data):
+                    if (src_table._num_rows is not None
+                            and dst_table._num_rows is not None
+                            and src_table._num_rows > dst_table._num_rows):
                         score += 1.0
 
                     if score < 5.0:
                         continue
 
-                    candidate_dict[(
-                        src_table.name,
-                        src_key.name,
-                    )].append((
-                        dst_table.name,
-                        score,
-                    ))
+                    candidate_dict[(src_table.name, src_key.name)].append(
+                        (dst_table.name, score))
 
         for (src_table_name, src_key_name), scores in candidate_dict.items():
             scores.sort(key=lambda x: x[-1], reverse=True)
@@ -574,6 +988,10 @@ class LocalGraph:
             raise ValueError("At least one table needs to be added to the "
                              "graph")
 
+        backends = {table.backend for table in self._tables.values()}
+        if len(backends) != 1:
+            raise ValueError("Found multiple table backends in the graph")
+
         for edge in self.edges:
             src_table, fkey, dst_table = edge
 
@@ -595,24 +1013,26 @@ class LocalGraph:
                                  f"either the primary key or the link before "
                                  f"before proceeding.")
 
-            # Check that fkey/pkey have valid and consistent data types:
-            assert src_key.dtype is not None
-            src_number = src_key.dtype.is_int() or src_key.dtype.is_float()
-            src_string = src_key.dtype.is_string()
-            assert dst_key.dtype is not None
-            dst_number = dst_key.dtype.is_int() or dst_key.dtype.is_float()
-            dst_string = dst_key.dtype.is_string()
-
-            if not src_number and not src_string:
-                raise ValueError(f"{edge} is invalid as foreign key must be a "
-                                 f"number or string (got '{src_key.dtype}'")
-
-            if src_number != dst_number or src_string != dst_string:
-                raise ValueError(f"{edge} is invalid as foreign key "
-                                 f"'{fkey}' and primary key '{dst_key.name}' "
-                                 f"have incompatible data types (got "
-                                 f"fkey.dtype '{src_key.dtype}' and "
-                                 f"pkey.dtype '{dst_key.dtype}')")
+            if self.backend == DataBackend.LOCAL:
+                # Check that fkey/pkey have valid and consistent data types:
+                assert src_key.dtype is not None
+                src_number = src_key.dtype.is_int() or src_key.dtype.is_float()
+                src_string = src_key.dtype.is_string()
+                assert dst_key.dtype is not None
+                dst_number = dst_key.dtype.is_int() or dst_key.dtype.is_float()
+                dst_string = dst_key.dtype.is_string()
+
+                if not src_number and not src_string:
+                    raise ValueError(
+                        f"{edge} is invalid as foreign key must be a number "
+                        f"or string (got '{src_key.dtype}'")
+
+                if src_number != dst_number or src_string != dst_string:
+                    raise ValueError(
+                        f"{edge} is invalid as foreign key '{fkey}' and "
+                        f"primary key '{dst_key.name}' have incompatible data "
+                        f"types (got foreign key data type '{src_key.dtype}' "
+                        f"and primary key data type '{dst_key.dtype}')")
 
         return self
 
@@ -620,7 +1040,7 @@ class LocalGraph:
 
     def visualize(
         self,
-        path: Optional[Union[str, io.BytesIO]] = None,
+        path: str | io.BytesIO | None = None,
         show_columns: bool = True,
     ) -> 'graphviz.Graph':
         r"""Visualizes the tables and edges in this graph using the
@@ -645,33 +1065,33 @@ class LocalGraph:
 
             return True
 
-        # Check basic dependency:
-        if not find_spec('graphviz'):
-            raise ModuleNotFoundError("The 'graphviz' package is required for "
-                                      "visualization")
-        elif not has_graphviz_executables():
+        try:  # Check basic dependency:
+            import graphviz
+        except ImportError as e:
+            raise ImportError("The 'graphviz' package is required for "
+                              "visualization") from e
+
+        if not in_snowflake_notebook() and not has_graphviz_executables():
             raise RuntimeError("Could not visualize graph as 'graphviz' "
                                "executables are not installed. These "
                                "dependencies are required in addition to the "
                                "'graphviz' Python package. Please install "
                                "them as described at "
                                "https://graphviz.org/download/.")
-        else:
-            import graphviz
 
-        format: Optional[str] = None
+        format: str | None = None
         if isinstance(path, str):
             format = path.split('.')[-1]
         elif isinstance(path, io.BytesIO):
             format = 'svg'
         graph = graphviz.Graph(format=format)
 
-        def left_align(keys: List[str]) -> str:
+        def left_align(keys: list[str]) -> str:
             if len(keys) == 0:
                 return ""
             return '\\l'.join(keys) + '\\l'
 
-        fkeys_dict: Dict[str, List[str]] = defaultdict(list)
+        fkeys_dict: dict[str, list[str]] = defaultdict(list)
         for src_table_name, fkey_name, _ in self.edges:
             fkeys_dict[src_table_name].append(fkey_name)
 
@@ -741,6 +1161,9 @@ class LocalGraph:
             graph.render(path, cleanup=True)
         elif isinstance(path, io.BytesIO):
             path.write(graph.pipe())
+        elif in_snowflake_notebook():
+            import streamlit as st
+            st.graphviz_chart(graph)
         elif in_notebook():
             from IPython.display import display
             display(graph)
@@ -764,8 +1187,8 @@ class LocalGraph:
     # Helpers #################################################################
 
     def _to_api_graph_definition(self) -> GraphDefinition:
-        tables: Dict[str, TableDefinition] = {}
-        col_groups: List[ColumnKeyGroup] = []
+        tables: dict[str, TableDefinition] = {}
+        col_groups: list[ColumnKeyGroup] = []
         for table_name, table in self.tables.items():
             tables[table_name] = table._to_api_table_definition()
             if table.primary_key is None:
@@ -790,7 +1213,7 @@ class LocalGraph:
     def __contains__(self, name: str) -> bool:
         return self.has_table(name)
 
-    def __getitem__(self, name: str) -> LocalTable:
+    def __getitem__(self, name: str) -> Table:
         return self.table(name)
 
     def __delitem__(self, name: str) -> None:
@@ -808,3 +1231,7 @@ class LocalGraph:
                 f'  tables={tables},\n'
                 f'  edges={edges},\n'
                 f')')
+
+    def __del__(self) -> None:
+        if hasattr(self, '_connection'):
+            self._connection.close()