srielau opened a new pull request, #56040:
URL: https://github.com/apache/spark/pull/56040
### What changes were proposed in this pull request?
Adds user-facing documentation for the SQL Standard PATH feature
introduced in Spark 4.2 (SPARK-56939 and related): the `SET PATH`
statement, the `current_path()` function, path-based resolution of
unqualified routines, tables, views, and session variables, and the
supporting infrastructure (`system.builtin` / `system.session` namespaces
with `builtin.` / `session.` shortcuts, `spark.sql.path.enabled`,
`spark.sql.defaultPath`).
New pages:
- `docs/sql-ref-syntax-aux-conf-mgmt-set-path.md` — reference for the
`SET PATH` statement, including a dedicated subsection on how
`DEFAULT_PATH` is derived and how to change it.
- `docs/sql-ref-function-current-path.md` — reference for the
`current_path()` builtin.
Modified pages:
- `docs/sql-ref-name-resolution.md` — new *SQL Path* section that
introduces the concept, the `system.builtin` / `system.session`
namespaces and their 2-part shortcuts, the path-walk for unqualified
DML / queries vs the current-schema rule for DDL, the frozen-path
behavior for persistent views and SQL UDFs, and the *Reserved names and
collisions* subsection. Table / view and function resolution sections
rewritten accordingly.
- `docs/sql-ref-identifier.md` — *Reserved system names* table
linking back to the canonical description.
- `docs/sql-ref-syntax-aux-describe-function.md` — examples for SQL
UDF `Function / Type / Input / Returns` output, qualified builtin
lookup (`system.builtin.abs`), and the `SQL Path:` row in
`DESCRIBE FUNCTION EXTENDED`.
- `docs/sql-ref-syntax-aux-describe-table.md` — example for the
`SQL Path` row in `DESCRIBE EXTENDED` on a view.
- `docs/sql-ref-syntax-ddl-create-view.md`, `create-sql-function.md`,
`create-function.md` — document the `session` /
`system.session` qualifier on temporary objects
(`INVALID_TEMP_OBJ_QUALIFIER` otherwise), and add frozen-path examples.
- `docs/sql-ref-syntax-ddl-drop-view.md`, `drop-function.md` —
clarify `DROP TEMPORARY FUNCTION` vs `DROP VIEW` semantics and the
qualifiers accepted in each.
- `docs/sql-ref-syntax-ddl-create-database.md` — note discouraging
the schema names `session` and `builtin`.
- `docs/sql-ref-syntax-aux-conf-mgmt-set.md`,
`docs/sql-ref-syntax-aux-conf-mgmt.md`, `docs/sql-ref-syntax.md`
— cross-link `SET PATH`.
- `docs/sql-migration-guide.md` — 4.1 → 4.2 entries for the
`builtin.x` / `session.x` resolution change, the new temp-object
qualifiers, and the opt-in PATH feature.
### Why are the changes needed?
The PATH feature (SPARK-56939 and friends) shipped without external
documentation. Users have no published place to learn about `SET PATH`,
`current_path()`, the `system.builtin` / `system.session` namespaces, or
the path-walking resolution rules; the behavior change for partially
qualified `builtin.x` / `session.x` references is also a 4.1 → 4.2
migration concern that needs to be called out.
### Does this PR introduce _any_ user-facing change?
No. This change is documentation-only.
### How was this patch tested?
- Markdown lint clean on every touched file.
- Spot-checked for non-ASCII typographic characters; none introduced.
- Cross-checked every behavioral claim against the relevant test suites:
`sql-tests/inputs/sql-path.sql`, `SetPathSuite`,
`FunctionQualificationSuite`, `RelationQualificationSuite`,
`SQLFunctionSuite`, and `DescribeTableSuite`
(*DESCRIBE EXTENDED AS JSON for view shows SQL Path when PATH is
enabled*).
Local Jekyll build was attempted but blocked on Ruby 3 / Bundler 2.4.22
which were not installed in the local environment; relying on the GitHub
docs CI to validate the HTML build.
### Was this patch authored or co-authored using generative AI tooling?
Generated-by: Cursor (Claude Opus 4.7)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
