How do you troubleshoot schema evolution issues when querying a DuckLake table over time?

Schema evolution issues in a DuckLake table, unexpected column types, missing data for older snapshots, queries returning different shapes than expected, generally trace back to the interaction between a table's schema history and whichever specific snapshot or point in time a query is actually reading.

1. Confirm which snapshot or time-travel point the query is actually targeting - a query without an explicit snapshot/timestamp reads the current schema and data; querying an older snapshot may reflect an earlier schema version, which can explain apparent inconsistencies if this isn't accounted for.
2. Check the table's recorded schema evolution history - DuckLake tracks schema changes over time in its catalog; reviewing that history clarifies exactly when a column was added, renamed, or had its type changed, and how older data is reconciled against the current schema.
3. Check for type-widening versus type-narrowing changes - schema evolution generally handles compatible changes (like widening an integer column to a larger type) more gracefully than incompatible ones (like changing a column's fundamental type in an ambiguous way), which may require explicit handling.
4. Check whether inlined data reflects the schema correctly - since inlined rows and Parquet-backed rows are read through a unified view, confirm both are being reconciled against the same current schema rather than one lagging behind after a recent schema change.
5. Reproduce with a minimal query against a specific known snapshot - isolating the issue to a specific snapshot and schema version narrows down whether the problem is with the schema evolution itself or with how a particular query is interpreting the data.

Because DuckLake's metadata (including schema history) lives in an actual queryable SQL database rather than scattered across file-based metadata, directly querying the catalog's own metadata tables for a table's schema evolution history is often the most direct way to understand exactly what changed and when, rather than trying to infer it indirectly from query result anomalies alone.