Skip to content

docs(core-spec): clarify model declaration vs. query scope of the expression language - #536

Merged
jbonofre merged 2 commits into
apache:mainfrom
christianeu-db:docs/expr-lang-declaration-vs-query
Oct 8, 2026
Merged

jbonofre merged 2 commits into
apache:mainfrom
christianeu-db:docs/expr-lang-declaration-vs-query

Conversation

@christianeu-db

@christianeu-db christianeu-db commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

core-spec/expression_language.md scopes the expression language to the logical
layer - authoring metrics, fields, and filters - and already notes that the query
interface is defined in a separate document. However, this rule is easy to miss.

This PR makes the boundary explicit. It adds a short "Model Declaration vs.
Querying"
subsection to the Overview, and relocates the existing "query interface
is defined elsewhere" sentence out of the Namespacing section into it. The diff
therefore shows the boundary was already in the spec. This change only makes it
prominent.

The subsection states: the expression language declares a model and does not define a
query interface; and adding a dialect (OSSIE_SQL_2026 or a vendor dialect) to
declare a model does not mean Ossie can be queried in that dialect.

It also rewords the lead of the Dialects enum in core-spec/spec.md from
"Supported ... dialects" to "Dialects in which metric and field expressions can be
declared", and adds a short note under the table: OSSIE_SQL_2026 is the only
dialect whose semantics the spec defines, other dialects MAY be ignored (as
Dialect Extensions already states), and registering a dialect does not mean Ossie
supports querying in it.

This clarifies an existing distinction rather than changing behavior.

Finally, added a pointer to expression_language from spec.md to improve discoverability.

Discussed on dev@:

Related Issues

Relates to the layered-semantics workstream (#452, #354, #246). No code issue is
closed by this change.

Checklist

Specification

  • Spec changes are included in core-spec/ and follow the existing structure
  • Spec changes have been discussed on the mailing list or in a linked issue
  • Breaking changes to the spec are clearly called out in the summary (none — editorial)

Compliance

  • ASF license headers are present on all new source files (no new files; edited files retain their headers)
  • No third-party dependencies are added without PMC/IPMC approval

Ontology, Converters, Validation, Documentation, Examples, and Tests checklist items
are not applicable: this is a prose-only change to two core-spec files.

AI disclosure

Per the ASF Generative Tooling Guidance, this contribution was prepared with AI
assistance. I have reviewed and verified every change.

@github-actions github-actions Bot added the spec label Oct 8, 2026
…ression language

core-spec/expression_language.md scopes the expression language to the
logical layer (metrics, fields, filters) and already notes that the query
interface is defined in a separate document, but the boundary between using
the language to declare a model and using it to query one is easy to miss,
because the same expressions reappear when a model is queried.

Add a "Model Declaration vs. Querying" subsection to the Overview that states
the distinction explicitly, and relocate the pre-existing sentence about the
query interface being defined elsewhere out of the Namespacing section into
it. This is an editorial clarification; no functions, dialect values, or
compliance levels change.

Co-authored-by: Isaac <no-reply@databricks.com>
@christianeu-db
christianeu-db force-pushed the docs/expr-lang-declaration-vs-query branch from 6e325c0 to ff7d6c3 Compare October 8, 2026 02:58
@christianeu-db
christianeu-db marked this pull request as ready for review October 8, 2026 03:02
@jbonofre
jbonofre self-requested a review October 8, 2026 15:57
jbonofre
jbonofre previously approved these changes Oct 8, 2026

@jbonofre jbonofre left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! It's not spec change, it's documentation clarification. So no need to call for a vote.

The new "Model Declaration vs Querying" section clearly separates declaring a model from querying it, and it states that adding a dialect here doesn't imply query support. Removing the "SQL Interface will be defined in a different document" sentence is consistent with it.

Nit: the identifier-quoting paragraph still says "having the SQL Interface queried in the local dialect", which refers to an interface the spec no longer names. Rewording it to "queried in the local dialect" would be tidier.

Reword the Dialects enum lead in spec.md so that it describes declaration
rather than general support, and add a note that OSSIE_SQL_2026 is the
only dialect whose semantics the specification defines, that other
dialects MAY be ignored, and that registering a dialect does not mean
Ossie supports querying in it.

Also drop the remaining reference to the "SQL Interface" from the
identifier-quoting paragraph in expression_language.md.

Co-authored-by: Isaac <no-reply@databricks.com>
@christianeu-db

Copy link
Copy Markdown
Contributor Author

LGTM! It's not spec change, it's documentation clarification. So no need to call for a vote.

The new "Model Declaration vs Querying" section clearly separates declaring a model from querying it, and it states that adding a dialect here doesn't imply query support. Removing the "SQL Interface will be defined in a different document" sentence is consistent with it.

Nit: the identifier-quoting paragraph still says "having the SQL Interface queried in the local dialect", which refers to an interface the spec no longer names. Rewording it to "queried in the local dialect" would be tidier.

Thanks @jbonofre - really appreciate the review! I've updated the text to address the nit. I also added a pointer from spec.md to make this more discoverable from the top level spec.

@jbonofre
jbonofre merged commit 391cb70 into apache:main Oct 8, 2026
71 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants