dataowl 0.2.0__tar.gz → 0.3.0__tar.gz

{dataowl-0.2.0 → dataowl-0.3.0}/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-08
+
+Write behaviour from the Delta history (`history`).
+
+### Added
+- `dataowl.history(table, *, spark=None, limit=None)` returning a `HistoryAnalysis` with
+  `to_dict()` and `show()`. `limit` reads only the newest `limit` commits.
+- Observation window (oldest and newest commit, calendar days, commits), commits per day
+  (median, min, max, with 0 for days without commits), commits per hour of day, and
+  commits per operation with `WRITE (overwrite)` as its own category.
+- Inserted, updated and deleted rows per operation from `operationMetrics`
+  (`numTargetRowsInserted`, `numTargetRowsUpdated` and `numTargetRowsDeleted` for `MERGE`,
+  `numOutputRows` for `WRITE`, `WRITE (overwrite)` and `... AS SELECT`, `numUpdatedRows`
+  for `UPDATE`, `numDeletedRows` for `DELETE`): commits with the metric out of all, sum,
+  median and max.
+- The session time zone (`current_timezone()`) as a fact. Days and hours are counted in
+  that time zone.
+- Notes in the output: the history is limited by `delta.logRetentionDuration`, rows
+  replaced by `WRITE (overwrite)` are not counted as deleted, and the oldest day in the
+  window may be incomplete.
+
+### Changed
+- `inspect` and `analyze` raise `TableNotFoundError` when the catalog does not exist.
+  Before, every fact in `inspect` was `n/a` and `analyze` raised `RuntimeError` about the
+  schema.
+
 ## [0.2.0] - 2026-10-08
 
 Column analysis (`analyze`) and an excerpt of the Delta history in `inspect`.

{dataowl-0.2.0 → dataowl-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dataowl
-Version: 0.2.0
+Version: 0.3.0
 Summary: Facts about Databricks data products for building dbt staging models.
 Project-URL: Homepage, https://github.com/alexD1990/dataowl
 Project-URL: Repository, https://github.com/alexD1990/dataowl
@@ -33,8 +33,10 @@ Description-Content-Type: text/markdown
 dataowl reports facts about a table in Databricks (Unity Catalog / Delta Lake): size, files,
 rows, schema, table properties and an excerpt of the Delta history, and facts about the
 columns you choose: grain and uniqueness of keys, time span and cadence of time columns, and
-how two time columns compare. It is meant for data engineers who build a dbt staging model
-and want the facts without writing exploratory SQL. It reports what exists and never gives
+how two time columns compare. From the Delta history it also reports how the table is
+written: commits per day and per hour of day, operations, and rows inserted, updated and
+deleted per operation. It is meant for data engineers who build a dbt staging model and want
+the facts without writing exploratory SQL. It reports what exists and never gives
 recommendations.
 
 ## Requirements
@@ -49,13 +51,17 @@ recommendations.
 In a Databricks notebook:
 
 ```python
-%pip install dataowl==0.2.0
+%pip install dataowl==0.3.0
 ```
 
 ## Usage
 
 dataowl works in two steps: `inspect` gives an overview of the table, and `analyze` gives
-facts about columns you choose.
+facts about columns you choose. In addition, `history` gives detailed facts from the Delta
+history about how the table is written.
+
+`inspect`, `analyze` and `history` raise `TableNotFoundError` when the table does not exist
+or is not accessible, including when the catalog does not exist.
 
 ### inspect
 
@@ -158,7 +164,86 @@ analysis.to_dict()  # JSON-serializable, like Overview.to_dict()
   validated before any query against the table's data.
 - `RuntimeError` when no SparkSession is available, and when the schema cannot be read from
   `information_schema.columns`, since the columns cannot then be validated.
-- `TableNotFoundError` when the table does not exist or is not accessible.
+- `TableNotFoundError` when the table does not exist or is not accessible, including when
+  the catalog does not exist.
+
+Every other failure makes the affected facts `n/a (<reason>)`.
+
+### history
+
+```python
+dataowl.history("catalog.schema.table").show()
+dataowl.history("catalog.schema.table", limit=100).show()  # only the newest 100 commits
+```
+
+Full signature:
+
+```python
+history(
+    table: str,
+    *,
+    spark: SparkSession | None = None,
+    limit: int | None = None,
+) -> HistoryAnalysis
+```
+
+`history` reads `DESCRIBE HISTORY` and reports:
+
+- **The observation window:** the oldest and newest commit, the number of days and the
+  number of commits. The window is shown at the top, because every other number only
+  covers this period.
+- **Commits per day:** median, min and max over every calendar day in the window. Days
+  without commits count as 0.
+- **Commits per hour of day:** the number of commits in each hour, 0–23.
+- **Operations:** the number of commits per operation, with `WRITE (overwrite)` as its own
+  category, as in `inspect`.
+- **Rows per operation:** inserted, updated and deleted rows, from `operationMetrics`.
+
+`limit` reads only the newest `limit` commits (`DESCRIBE HISTORY ... LIMIT <limit>`). Without
+`limit`, every commit in the history is read.
+
+Commit timestamps are used as Databricks returns them, in the session time zone, without
+conversion. Days and hours of day are counted in that time zone, and its name is shown as
+**Time zone** (from `current_timezone()`). The number of days counts calendar days from the
+date of the oldest commit to the date of the newest, both included.
+
+Rows per operation are based on these `operationMetrics` keys:
+
+| Operation | inserted | updated | deleted |
+|---|---|---|---|
+| `MERGE` | `numTargetRowsInserted` | `numTargetRowsUpdated` | `numTargetRowsDeleted` |
+| `WRITE`, `WRITE (overwrite)`, operations ending with `AS SELECT` | `numOutputRows` | | |
+| `UPDATE` | | `numUpdatedRows` | |
+| `DELETE` | | | `numDeletedRows` |
+
+Other combinations of operation and row type are not shown. **commits** is shown as the
+number of commits that have the metric out of all commits of the operation, for example
+`27/29`. Sum, median and max cover only the commits that have the metric, and are shown as
+`–` when none has it. If a metric has an unexpected format, only the rows per operation are
+`n/a (<reason>)`.
+
+The output ends with three notes:
+
+- The history is limited by `delta.logRetentionDuration`; the counts cover the window shown.
+- Rows replaced by `WRITE (overwrite)` are not counted as deleted.
+- The oldest day in the window may be incomplete, because `limit` or the log retention can
+  cut the history in the middle of a day.
+
+```python
+analysis = dataowl.history("catalog.schema.table")
+analysis.to_dict()  # JSON-serializable, like Overview.to_dict()
+```
+
+For views, every fact except the time zone is `n/a (Not available for views)`, and
+`DESCRIBE HISTORY` is not run.
+
+`history` raises:
+
+- `ValueError` for an invalid table name, and when `limit` is not `None` or an integer of
+  at least 1.
+- `RuntimeError` when no SparkSession is available.
+- `TableNotFoundError` when the table does not exist or is not accessible, including when
+  the catalog does not exist.
 
 Every other failure makes the affected facts `n/a (<reason>)`.
 
@@ -262,6 +347,33 @@ COMPARE  tpep_pickup_datetime → tpep_dropoff_datetime
 The data in `samples.nyctaxi.trips` is from January and February 2016, so every day in the
 rows-per-day window has 0 rows.
 
+```python
+dataowl.history("samples.nyctaxi.trips").show()
+```
+
+```text
+samples.nyctaxi.trips
+
+HISTORY  (2025-09-09 15:05 – 2026-09-14 15:07, 371 days, 223 commits)
+  Time zone:        Etc/UTC (session)
+  Commits per day:  median 1 · min 0 · max 2
+  Commits per hour of day:
+    06:00    1
+    15:00  222
+
+OPERATIONS
+  CREATE OR REPLACE TABLE AS SELECT:  212
+  SET TBLPROPERTIES:                  11
+
+ROWS
+  operation                          rows      commits  sum        median  max
+  CREATE OR REPLACE TABLE AS SELECT  inserted  212/212  4 649 584  21 932  21 932
+
+Note: history is limited by delta.logRetentionDuration; counts cover the window above.
+Note: rows replaced by WRITE (overwrite) are not counted as deleted.
+Note: the oldest day in the window may be incomplete.
+```
+
 ## Principles
 
 - **Read-only.** Only `SELECT`, `DESCRIBE` and `SHOW`. Nothing is written, optimized or
@@ -272,8 +384,8 @@ rows-per-day window has 0 rows.
 - **You choose the columns.** `analyze` only analyzes the columns you give.
 - **Unavailable facts are reported with a reason.** Missing permissions or an unsupported
   object type make the affected facts `n/a (<reason>)`; the rest of the report is still
-  produced. Only a table that does not exist or is not accessible raises
-  `TableNotFoundError`.
+  produced. Only a table that does not exist or is not accessible, including a table in a
+  catalog that does not exist, raises `TableNotFoundError`.
 
 ## Facts per object type
 
@@ -285,6 +397,7 @@ rows-per-day window has 0 rows.
 | Field count incl. nested | Spark schema | yes | yes | yes | yes | yes |
 | Change Data Feed, log and deleted file retention | `SHOW TBLPROPERTIES` | yes | attempted¹ | attempted¹ | no | attempted¹ |
 | History excerpt | `DESCRIBE HISTORY` | yes | attempted¹ | attempted¹ | no | attempted¹ |
+| `history()`: window, commits, operations, rows per operation | `DESCRIBE HISTORY` | yes | attempted¹ | attempted¹ | no | attempted¹ |
 | Rows | `COUNT(*)` | yes | MATERIALIZED_VIEW: with `count_views=True`; STREAMING_TABLE: yes | with `count_views=True` | with `count_views=True` | UNKNOWN: yes; n/a type: with `count_views=True` |
 
 ¹ The query runs. If Databricks does not support it for the object, the facts are shown as
@@ -334,6 +447,25 @@ original value is shown in the header. "n/a type" means the object type could no
 - Medians and means are rounded to one decimal and shown without decimals when the rounded
   value is whole.
 
+### history
+
+- **HISTORY (... days, ... commits)** is the oldest and newest commit, the number of
+  calendar days from the date of the oldest to the date of the newest commit, both
+  included, and the number of commits.
+- **Limit** is shown only when `limit` is given: only the newest `limit` commits are read.
+- **Time zone** is the session time zone, from `current_timezone()`. Commit timestamps,
+  days and hours of day are in this time zone.
+- **Commits per day** is the median, min and max over every day in the window, with 0 for
+  days without commits.
+- **Commits per hour of day** lists the hours of day that have commits, with the number of
+  commits.
+- **OPERATIONS** is the number of commits per operation, as in the HISTORY block of
+  `inspect`.
+- **ROWS** has one line per operation and row type (inserted, updated, deleted) with a
+  metric, see the table under **history** above. **commits** is the number of commits with
+  the metric out of all commits of the operation. **sum**, **median** and **max** cover the
+  commits with the metric, and are `–` when none has it.
+
 ## Known deviations
 
 - `information_schema.columns.ordinal_position` is documented as numbered from 1, but has

{dataowl-0.2.0 → dataowl-0.3.0}/README.md

@@ -3,8 +3,10 @@
 dataowl reports facts about a table in Databricks (Unity Catalog / Delta Lake): size, files,
 rows, schema, table properties and an excerpt of the Delta history, and facts about the
 columns you choose: grain and uniqueness of keys, time span and cadence of time columns, and
-how two time columns compare. It is meant for data engineers who build a dbt staging model
-and want the facts without writing exploratory SQL. It reports what exists and never gives
+how two time columns compare. From the Delta history it also reports how the table is
+written: commits per day and per hour of day, operations, and rows inserted, updated and
+deleted per operation. It is meant for data engineers who build a dbt staging model and want
+the facts without writing exploratory SQL. It reports what exists and never gives
 recommendations.
 
 ## Requirements
@@ -19,13 +21,17 @@ recommendations.
 In a Databricks notebook:
 
 ```python
-%pip install dataowl==0.2.0
+%pip install dataowl==0.3.0
 ```
 
 ## Usage
 
 dataowl works in two steps: `inspect` gives an overview of the table, and `analyze` gives
-facts about columns you choose.
+facts about columns you choose. In addition, `history` gives detailed facts from the Delta
+history about how the table is written.
+
+`inspect`, `analyze` and `history` raise `TableNotFoundError` when the table does not exist
+or is not accessible, including when the catalog does not exist.
 
 ### inspect
 
@@ -128,7 +134,86 @@ analysis.to_dict()  # JSON-serializable, like Overview.to_dict()
   validated before any query against the table's data.
 - `RuntimeError` when no SparkSession is available, and when the schema cannot be read from
   `information_schema.columns`, since the columns cannot then be validated.
-- `TableNotFoundError` when the table does not exist or is not accessible.
+- `TableNotFoundError` when the table does not exist or is not accessible, including when
+  the catalog does not exist.
+
+Every other failure makes the affected facts `n/a (<reason>)`.
+
+### history
+
+```python
+dataowl.history("catalog.schema.table").show()
+dataowl.history("catalog.schema.table", limit=100).show()  # only the newest 100 commits
+```
+
+Full signature:
+
+```python
+history(
+    table: str,
+    *,
+    spark: SparkSession | None = None,
+    limit: int | None = None,
+) -> HistoryAnalysis
+```
+
+`history` reads `DESCRIBE HISTORY` and reports:
+
+- **The observation window:** the oldest and newest commit, the number of days and the
+  number of commits. The window is shown at the top, because every other number only
+  covers this period.
+- **Commits per day:** median, min and max over every calendar day in the window. Days
+  without commits count as 0.
+- **Commits per hour of day:** the number of commits in each hour, 0–23.
+- **Operations:** the number of commits per operation, with `WRITE (overwrite)` as its own
+  category, as in `inspect`.
+- **Rows per operation:** inserted, updated and deleted rows, from `operationMetrics`.
+
+`limit` reads only the newest `limit` commits (`DESCRIBE HISTORY ... LIMIT <limit>`). Without
+`limit`, every commit in the history is read.
+
+Commit timestamps are used as Databricks returns them, in the session time zone, without
+conversion. Days and hours of day are counted in that time zone, and its name is shown as
+**Time zone** (from `current_timezone()`). The number of days counts calendar days from the
+date of the oldest commit to the date of the newest, both included.
+
+Rows per operation are based on these `operationMetrics` keys:
+
+| Operation | inserted | updated | deleted |
+|---|---|---|---|
+| `MERGE` | `numTargetRowsInserted` | `numTargetRowsUpdated` | `numTargetRowsDeleted` |
+| `WRITE`, `WRITE (overwrite)`, operations ending with `AS SELECT` | `numOutputRows` | | |
+| `UPDATE` | | `numUpdatedRows` | |
+| `DELETE` | | | `numDeletedRows` |
+
+Other combinations of operation and row type are not shown. **commits** is shown as the
+number of commits that have the metric out of all commits of the operation, for example
+`27/29`. Sum, median and max cover only the commits that have the metric, and are shown as
+`–` when none has it. If a metric has an unexpected format, only the rows per operation are
+`n/a (<reason>)`.
+
+The output ends with three notes:
+
+- The history is limited by `delta.logRetentionDuration`; the counts cover the window shown.
+- Rows replaced by `WRITE (overwrite)` are not counted as deleted.
+- The oldest day in the window may be incomplete, because `limit` or the log retention can
+  cut the history in the middle of a day.
+
+```python
+analysis = dataowl.history("catalog.schema.table")
+analysis.to_dict()  # JSON-serializable, like Overview.to_dict()
+```
+
+For views, every fact except the time zone is `n/a (Not available for views)`, and
+`DESCRIBE HISTORY` is not run.
+
+`history` raises:
+
+- `ValueError` for an invalid table name, and when `limit` is not `None` or an integer of
+  at least 1.
+- `RuntimeError` when no SparkSession is available.
+- `TableNotFoundError` when the table does not exist or is not accessible, including when
+  the catalog does not exist.
 
 Every other failure makes the affected facts `n/a (<reason>)`.
 
@@ -232,6 +317,33 @@ COMPARE  tpep_pickup_datetime → tpep_dropoff_datetime
 The data in `samples.nyctaxi.trips` is from January and February 2016, so every day in the
 rows-per-day window has 0 rows.
 
+```python
+dataowl.history("samples.nyctaxi.trips").show()
+```
+
+```text
+samples.nyctaxi.trips
+
+HISTORY  (2025-09-09 15:05 – 2026-09-14 15:07, 371 days, 223 commits)
+  Time zone:        Etc/UTC (session)
+  Commits per day:  median 1 · min 0 · max 2
+  Commits per hour of day:
+    06:00    1
+    15:00  222
+
+OPERATIONS
+  CREATE OR REPLACE TABLE AS SELECT:  212
+  SET TBLPROPERTIES:                  11
+
+ROWS
+  operation                          rows      commits  sum        median  max
+  CREATE OR REPLACE TABLE AS SELECT  inserted  212/212  4 649 584  21 932  21 932
+
+Note: history is limited by delta.logRetentionDuration; counts cover the window above.
+Note: rows replaced by WRITE (overwrite) are not counted as deleted.
+Note: the oldest day in the window may be incomplete.
+```
+
 ## Principles
 
 - **Read-only.** Only `SELECT`, `DESCRIBE` and `SHOW`. Nothing is written, optimized or
@@ -242,8 +354,8 @@ rows-per-day window has 0 rows.
 - **You choose the columns.** `analyze` only analyzes the columns you give.
 - **Unavailable facts are reported with a reason.** Missing permissions or an unsupported
   object type make the affected facts `n/a (<reason>)`; the rest of the report is still
-  produced. Only a table that does not exist or is not accessible raises
-  `TableNotFoundError`.
+  produced. Only a table that does not exist or is not accessible, including a table in a
+  catalog that does not exist, raises `TableNotFoundError`.
 
 ## Facts per object type
 
@@ -255,6 +367,7 @@ rows-per-day window has 0 rows.
 | Field count incl. nested | Spark schema | yes | yes | yes | yes | yes |
 | Change Data Feed, log and deleted file retention | `SHOW TBLPROPERTIES` | yes | attempted¹ | attempted¹ | no | attempted¹ |
 | History excerpt | `DESCRIBE HISTORY` | yes | attempted¹ | attempted¹ | no | attempted¹ |
+| `history()`: window, commits, operations, rows per operation | `DESCRIBE HISTORY` | yes | attempted¹ | attempted¹ | no | attempted¹ |
 | Rows | `COUNT(*)` | yes | MATERIALIZED_VIEW: with `count_views=True`; STREAMING_TABLE: yes | with `count_views=True` | with `count_views=True` | UNKNOWN: yes; n/a type: with `count_views=True` |
 
 ¹ The query runs. If Databricks does not support it for the object, the facts are shown as
@@ -304,6 +417,25 @@ original value is shown in the header. "n/a type" means the object type could no
 - Medians and means are rounded to one decimal and shown without decimals when the rounded
   value is whole.
 
+### history
+
+- **HISTORY (... days, ... commits)** is the oldest and newest commit, the number of
+  calendar days from the date of the oldest to the date of the newest commit, both
+  included, and the number of commits.
+- **Limit** is shown only when `limit` is given: only the newest `limit` commits are read.
+- **Time zone** is the session time zone, from `current_timezone()`. Commit timestamps,
+  days and hours of day are in this time zone.
+- **Commits per day** is the median, min and max over every day in the window, with 0 for
+  days without commits.
+- **Commits per hour of day** lists the hours of day that have commits, with the number of
+  commits.
+- **OPERATIONS** is the number of commits per operation, as in the HISTORY block of
+  `inspect`.
+- **ROWS** has one line per operation and row type (inserted, updated, deleted) with a
+  metric, see the table under **history** above. **commits** is the number of commits with
+  the metric out of all commits of the operation. **sum**, **median** and **max** cover the
+  commits with the metric, and are `–` when none has it.
+
 ## Known deviations
 
 - `information_schema.columns.ordinal_position` is documented as numbered from 1, but has

{dataowl-0.2.0 → dataowl-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dataowl"
-version = "0.2.0"
+version = "0.3.0"
 description = "Facts about Databricks data products for building dbt staging models."
 readme = "README.md"
 requires-python = ">=3.10"

{dataowl-0.2.0 → dataowl-0.3.0}/src/dataowl/__init__.py

@@ -9,7 +9,13 @@ from dataowl.collect.compare import collect_comparison, normalize_compare
 from dataowl.collect.constraints import collect_primary_key
 from dataowl.collect.counts import collect_row_count
 from dataowl.collect.detail import collect_detail
-from dataowl.collect.history import collect_history_excerpt
+from dataowl.collect.history import (
+    build_history_analysis,
+    collect_commits,
+    collect_history_excerpt,
+    collect_session_time_zone,
+    validate_limit,
+)
 from dataowl.collect.keys import KeyInput, collect_key_analyses, normalize_keys
 from dataowl.collect.properties import collect_properties
 from dataowl.collect.tables import collect_table_info
@@ -21,13 +27,22 @@ from dataowl.collect.timestamps import (
 from dataowl.errors import TableNotFoundError
 from dataowl.identifiers import parse_table
 from dataowl.model.analysis import ColumnAnalysis
+from dataowl.model.history import HistoryAnalysis
 from dataowl.model.overview import Overview
 from dataowl.runner import get_runner
 
 if TYPE_CHECKING:
     from pyspark.sql import SparkSession
 
-__all__ = ["ColumnAnalysis", "Overview", "TableNotFoundError", "analyze", "inspect"]
+__all__ = [
+    "ColumnAnalysis",
+    "HistoryAnalysis",
+    "Overview",
+    "TableNotFoundError",
+    "analyze",
+    "history",
+    "inspect",
+]
 
 
 def inspect(
@@ -36,8 +51,9 @@ def inspect(
     """Collect overview facts for a table.
 
     Raises ValueError for an invalid table name, RuntimeError when no SparkSession is
-    available, and TableNotFoundError when the table does not exist or is not accessible.
-    Every other failure makes the affected facts unavailable.
+    available, and TableNotFoundError when the table does not exist or is not accessible,
+    including when the catalog does not exist. Every other failure makes the affected facts
+    unavailable.
     """
     ref = parse_table(table)
     runner = get_runner(spark)
@@ -98,8 +114,8 @@ def analyze(
     None, for invalid days, and for an unknown or unsupported column. All input is validated
     before any query against the table's data. Raises RuntimeError when no SparkSession is
     available and when the schema is not available from information_schema.columns. Raises
-    TableNotFoundError when the table does not exist or is not accessible. Every other
-    failure makes the affected facts unavailable.
+    TableNotFoundError when the table does not exist or is not accessible, including when
+    the catalog does not exist. Every other failure makes the affected facts unavailable.
     """
     ref = parse_table(table)
     if key is None and timestamp is None and compare is None:
@@ -125,3 +141,27 @@ def analyze(
         timestamps=collect_timestamp_analyses(runner, ref, time_columns, days),
         comparison=collect_comparison(runner, ref, *pair) if pair is not None else None,
     )
+
+
+def history(
+    table: str, *, spark: SparkSession | None = None, limit: int | None = None
+) -> HistoryAnalysis:
+    """Collect facts about how the table is written, from DESCRIBE HISTORY.
+
+    With limit, only the newest `limit` commits are read. Timestamps are used in the session
+    time zone, which is collected as a fact.
+
+    Raises ValueError for an invalid table name and when limit is not None or an int of at
+    least 1, RuntimeError when no SparkSession is available, and TableNotFoundError when the
+    table does not exist or is not accessible, including when the catalog does not exist.
+    Every other failure makes the affected facts unavailable; for a view, the history facts
+    are unavailable.
+    """
+    ref = parse_table(table)
+    validate_limit(limit)
+    runner = get_runner(spark)
+
+    info = collect_table_info(runner, ref)
+    time_zone = collect_session_time_zone(runner)
+    result = collect_commits(runner, ref, info.object_type, limit)
+    return build_history_analysis(ref, limit, time_zone, result.commits, result.metrics_reason)

dataowl-0.3.0/src/dataowl/collect/__init__.py

@@ -0,0 +1,80 @@
+"""Collection layer: queries to raw data to model objects. The only layer that knows SQL."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from dataowl.model.facts import Fact
+from dataowl.model.overview import ObjectType
+from dataowl.runner import SqlRunner
+
+_MAX_REASON_LENGTH = 200
+
+NOT_FOR_VIEWS = "Not available for views"
+
+_CATALOG_NOT_FOUND_CLASSES = frozenset({"NO_SUCH_CATALOG_EXCEPTION", "CATALOG_NOT_FOUND"})
+_TABLE_OR_VIEW_NOT_FOUND = "TABLE_OR_VIEW_NOT_FOUND"
+_LEADING_ERROR_CLASS = re.compile(r"\[([A-Za-z0-9_.]+)\]")
+_INFORMATION_SCHEMA = re.compile(r"(?<!\w)information_schema(?!\w)", re.IGNORECASE)
+
+
+def is_view(object_type: Fact[ObjectType]) -> bool:
+    """True only when the object type is known to be VIEW."""
+    return object_type.available and object_type.value is ObjectType.VIEW
+
+
+def safe_query(
+    runner: SqlRunner, sql: str, params: dict[str, Any] | None = None
+) -> list[dict[str, Any]] | Exception:
+    """Run a query and return the rows, or the exception instead of raising it."""
+    try:
+        return runner.query(sql, params)
+    except Exception as exc:
+        return exc
+
+
+def is_catalog_not_found(exc: Exception) -> bool:
+    """True when the error says that the catalog does not exist.
+
+    The error class is read from getCondition(), then getErrorClass(), and otherwise from a
+    leading "[CLASS]" in the first line of the message. PySpark is not imported. True for
+    NO_SUCH_CATALOG_EXCEPTION and CATALOG_NOT_FOUND, and for TABLE_OR_VIEW_NOT_FOUND when the
+    first line names information_schema, quoted or not. False for everything else, including
+    access errors.
+    """
+    lines = str(exc).strip().splitlines()
+    first_line = lines[0].strip() if lines else ""
+    error_class = _error_class(exc, first_line)
+    if error_class in _CATALOG_NOT_FOUND_CLASSES:
+        return True
+    if error_class == _TABLE_OR_VIEW_NOT_FOUND:
+        return _INFORMATION_SCHEMA.search(first_line) is not None
+    return False
+
+
+def _error_class(exc: Exception, first_line: str) -> str | None:
+    for method_name in ("getCondition", "getErrorClass"):
+        method = getattr(exc, method_name, None)
+        if not callable(method):
+            continue
+        try:
+            value = method()
+        except Exception:
+            continue
+        if isinstance(value, str) and value.strip():
+            return value.strip().upper()
+    match = _LEADING_ERROR_CLASS.match(first_line)
+    return match.group(1).upper() if match else None
+
+
+def short_reason(exc: Exception) -> str:
+    """First line of the error message, at most 200 characters.
+
+    Falls back to the exception type name when the message is empty.
+    """
+    lines = str(exc).strip().splitlines()
+    reason = lines[0].strip() if lines else type(exc).__name__
+    if len(reason) > _MAX_REASON_LENGTH:
+        reason = reason[: _MAX_REASON_LENGTH - 1] + "…"
+    return reason