Extend SQL Diagnostics: Attach Source Spans to Function Argument Type Errors
- Dominant language
- Rust
- Stars
- 9.3k
- Forks
- 2.4k
- Avg merge
- 3d 7h
- Merged PRs (30d)
- 344
Description
## Summary
Following the SQL Diagnostics framework introduced in v46.0.0, I'd like to extend
it to cover function argument type errors — one of the most common and confusing
error categories for end users.
## Motivation
The 46.0.0 release blog explicitly noted:
> "Currently, diagnostics cover unresolved table/column references, missing GROUP BY
> columns, ambiguous references, wrong number of UNION columns, type mismatches, and
> a few others. **Future releases will extend this to more error types.**"
Right now, calling a function with a wrong argument type produces a generic error
with no source location:
```sql
SELECT sqrt('hello');
```
### Describe the solution you'd like
The user gets no span, no pointer to which argument is wrong, and no hint about
what type was expected. Compare this to how a missing GROUP BY column now renders
with a precise highlight in the query text — the UX gap is significant.
## Proposed Change
Extend the existing `Diagnostic` / `DiagnosticEntry` framework
(`datafusion/common/src/diagnostic.rs`) so that when the planner/type-coercion
layer rejects a scalar function call due to argument type mismatch, the emitted
error includes:
1. A `Diagnostic` that attaches a **source span** pointing to the offending
argument expression in the original SQL query text.
2. A human-readable note of the form:
`"function 'sqrt' does not support argument of type Utf8 at position 1;
expected a numeric type"`
This matches the style and severity conventions already used in the existing
diagnostic emission sites.
## Scope
Minimum viable coverage :
- [ ] Math functions called with a non-numeric argument
e.g. `SELECT sqrt('hello')`, `SELECT abs(true)`
- [ ] String functions called with a non-string argument
e.g. `SELECT length(3.14)` (where implicit coercion does not apply)
- [ ] Sqllogictest `.slt` test cases verifying the diagnostic text is present
in the error output for each covered case
- [ ] No regression in existing tests
Out of scope for this PR :
- Aggregate or window function argument errors
- Errors arising from the wrong *number* of arguments (separate error path)
## Files I Plan to Touch
| File | Reason |
|------|--------|
| `datafusion/sql/src/planner/expr.rs` | Where SQL AST exprs are resolved; span info is available here |
| `datafusion/expr/src/type_coercion/functions.rs` | Where argument type checking fires |
| `datafusion/common/src/diagnostic.rs` | `Diagnostic` / `DiagnosticEntry` types — read-only reference |
| `datafusion/sqllogictest/test_files/` | New `.slt` test cases |
## Questions Before I Start
1. **Is this the right layer to attach spans?** My reading is that `expr.rs` in
the planner is the right place (since the AST span is still available there),
rather than deeper in `type_coercion/`. Happy to be corrected.
2. **Is @eliaperantoni or another committer willing to be the supervising
maintainer for this?** Per the contributor guide, I want to confirm there's
someone interested in reviewing before investing significant time. I don't want
to submit a PR that sits unreviewed.
3. **Any prior art or in-flight PRs I should be aware of?** I searched open issues
and PRs and didn't find an active effort here, but I may have missed something.
## References
- [DataFusion 46.0.0 release blog — SQL Diagnostics section](https://datafusion.apache.org/blog/2025/03/24/datafusion-46.0.0/)
- [`datafusion/common/src/diagnostic.rs`](https://github.com/apache/datafusion/blob/main/datafusion/common/src/diagnostic.rs)
- Contributor guide: [Discussing New Features](https://datafusion.apache.org/contributor-guide/roadmap.html)
Happy to iterate on scope or approach based on feedback here before writing any code.
### Describe alternatives you've considered
_No response_
### Additional context
_No response_
Contributor guide
Research direction
Start by reading datafusion/sql/src/planner/expr.rs and datafusion/expr/src/type_coercion/functions.rs, using datafusion/common/src/diagnostic.rs as the diagnostic API reference. Determine where function argument type errors can retain the SQL argument span, then add coverage in datafusion/sqllogictest/test_files/. Done means math and string mismatch cases report the offending span and diagnostic text without regressions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust, sql
- Domain
- backend-api-design, databases, testing
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100