Repository navigation
docs(core-spec): clarify model declaration vs. query scope of the expression language - #536
Conversation
…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>
6e325c0 to
ff7d6c3
Compare
jbonofre
left a comment
There was a problem hiding this comment.
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>
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. |
Summary
core-spec/expression_language.mdscopes the expression language to the logicallayer - 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_2026or a vendor dialect) todeclare 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.mdfrom"Supported ... dialects" to "Dialects in which metric and field expressions can be
declared", and adds a short note under the table:
OSSIE_SQL_2026is the onlydialect 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@:
https://lists.apache.org/thread/cfb1dljkh2c6nmzmdfx7spgg9pxr2l9v
https://lists.apache.org/thread/7qgvtz9zyplp228so7ldc2kkm7r64o4g
Related Issues
Relates to the layered-semantics workstream (#452, #354, #246). No code issue is
closed by this change.
Checklist
Specification
core-spec/and follow the existing structureCompliance
Ontology, Converters, Validation, Documentation, Examples, and Tests checklist items
are not applicable: this is a prose-only change to two
core-specfiles.AI disclosure
Per the ASF Generative Tooling Guidance, this contribution was prepared with AI
assistance. I have reviewed and verified every change.