Repository navigation
Conversation
There was a problem hiding this comment.
Copilot review overview
🟢 Approval recommended
The documentation-only proposal is clearly scoped, with no unresolved blocking issues.
Review effort: Balanced
Findings: None
What changed in this PR
Proposes an optional execute_query MCP interoperability profile for engines and catalogs without changing Ossie’s core model or runtime behavior.
Changes:
- Defines request/result schemas, CSV encoding, diagnostics and lifecycle guidance.
- Adds examples and conformance requirements.
- Links the working draft from the documentation index.
| File | Description |
|---|---|
| docs/proposals/execute-query-mcp.md | Defines the proposed execution profile, schemas and examples. |
| docs/index.md | Links the draft and clarifies its proposal status. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
@jbonofre curious on your take on this thread. Directionally, is an Ossie MCP interopability meant to be tied to Ossie semantics? Is the goal to guide clients toward portable Ossie query interfaces, or also to standardize the execution of vendor-specific query languages compiled outside Ossie? |
|
@christianeu-db I replied on the mailing list. |
…odes The query is the aggregation query of apache/ossie#246 §5.1.1 at cc0d070: measures, dimensions, where, having, order_by objects, limit. The MCP tool takes it as one JSON object and names the revision in its description and answers. A condition in the wrong clause is refused instead of moved. Every PlanError carries a code: #246's where its trigger matches, otherwise a common code of apache/ossie#529 (QUERY_INVALID, UNSUPPORTED_QUERY). The "no direct join from one root" refusal splits into E_NO_PATH, E3013 and UNSUPPORTED_QUERY for paths the planner cannot follow. A refused query is a tool error in #529's envelope, with structured name suggestions. An explicit order_by sorts NULL as the highest value, as #246 says. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The MCP tool is execute_query, with the profile's inputSchema and outputSchema copied unchanged. Its arguments are data_source_id, the model name and a hash of the model, and the Layer 3 query object. An answer embeds the rows as CSV in the profile's encoding and describes them in structuredContent: model and revision, a typed preview, row count, completeness, the SQL under extensions. Without a limit, 100 rows come back and the answer says truncated when there were more. list_model describes the binding. Replies pass the profile's offline checker (validation/validate_mcp.py at b5418ee). Query.from_dict accepts what the profile's query schema accepts: other values are INVALID_ARGUMENT, and the shape codes are #246's, including E_EMPTY_SCALAR_QUERY. An empty result asks ClickHouse for its columns, which clickhouse-connect leaves out of an empty grouped result. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…odes The query is the aggregation query of apache/ossie#246 §5.1.1 at cc0d070: measures, dimensions, where, having, order_by objects, limit. The MCP tool takes it as one JSON object and names the revision in its description and answers. A condition in the wrong clause is refused instead of moved. Every PlanError carries a code: #246's where its trigger matches, otherwise a common code of apache/ossie#529 (QUERY_INVALID, UNSUPPORTED_QUERY). The "no direct join from one root" refusal splits into E_NO_PATH, E3013 and UNSUPPORTED_QUERY for paths the planner cannot follow. A refused query is a tool error in #529's envelope, with structured name suggestions. An explicit order_by sorts NULL as the highest value, as #246 says. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The MCP tool is execute_query, with the profile's inputSchema and outputSchema copied unchanged. Its arguments are data_source_id, the model name and a hash of the model, and the Layer 3 query object. An answer embeds the rows as CSV in the profile's encoding and describes them in structuredContent: model and revision, a typed preview, row count, completeness, the SQL under extensions. Without a limit, 100 rows come back and the answer says truncated when there were more. list_model describes the binding. Replies pass the profile's offline checker (validation/validate_mcp.py at b5418ee). Query.from_dict accepts what the profile's query schema accepts: other values are INVALID_ARGUMENT, and the shape codes are #246's, including E_EMPTY_SCALAR_QUERY. An empty result asks ClickHouse for its columns, which clickhouse-connect leaves out of an empty grouped result. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Exchanges captured over MCP from this branch, the profile's offline checker (apache/ossie#529 validation/validate_mcp.py at b5418ee) run on them, and a model with two unrelated facts with its expected answers written by hand: the evidence behind the Layer 3 report to dev@ossie, reproducible from the README. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…odes The query is the aggregation query of apache/ossie#246 §5.1.1 at cc0d070: measures, dimensions, where, having, order_by objects, limit. The MCP tool takes it as one JSON object and names the revision in its description and answers. A condition in the wrong clause is refused instead of moved. Every PlanError carries a code: #246's where its trigger matches, otherwise a common code of apache/ossie#529 (QUERY_INVALID, UNSUPPORTED_QUERY). The "no direct join from one root" refusal splits into E_NO_PATH, E3013 and UNSUPPORTED_QUERY for paths the planner cannot follow. A refused query is a tool error in #529's envelope, with structured name suggestions. An explicit order_by sorts NULL as the highest value, as #246 says. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The MCP tool is execute_query, with the profile's inputSchema and outputSchema copied unchanged. Its arguments are data_source_id, the model name and a hash of the model, and the Layer 3 query object. An answer embeds the rows as CSV in the profile's encoding and describes them in structuredContent: model and revision, a typed preview, row count, completeness, the SQL under extensions. Without a limit, 100 rows come back and the answer says truncated when there were more. list_model describes the binding. Replies pass the profile's offline checker (validation/validate_mcp.py at b5418ee). Query.from_dict accepts what the profile's query schema accepts: other values are INVALID_ARGUMENT, and the shape codes are #246's, including E_EMPTY_SCALAR_QUERY. An empty result asks ClickHouse for its columns, which clickhouse-connect leaves out of an empty grouped result. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Exchanges captured over MCP from this branch, the profile's offline checker (apache/ossie#529 validation/validate_mcp.py at b5418ee) run on them, and a model with two unrelated facts with its expected answers written by hand: the evidence behind the Layer 3 report to dev@ossie, reproducible from the README. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…odes The query is the aggregation query of apache/ossie#246 §5.1.1 at cc0d070: measures, dimensions, where, having, order_by objects, limit. The MCP tool takes it as one JSON object and names the revision in its description and answers. A condition in the wrong clause is refused instead of moved. Every PlanError carries a code: #246's where its trigger matches, otherwise a common code of apache/ossie#529 (QUERY_INVALID, UNSUPPORTED_QUERY). The "no direct join from one root" refusal splits into E_NO_PATH, E3013 and UNSUPPORTED_QUERY for paths the planner cannot follow. A refused query is a tool error in #529's envelope, with structured name suggestions. An explicit order_by sorts NULL as the highest value, as #246 says. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The MCP tool is execute_query, with the profile's inputSchema and outputSchema copied unchanged. Its arguments are data_source_id, the model name and a hash of the model, and the Layer 3 query object. An answer embeds the rows as CSV in the profile's encoding and describes them in structuredContent: model and revision, a typed preview, row count, completeness, the SQL under extensions. Without a limit, 100 rows come back and the answer says truncated when there were more. list_model describes the binding. Replies pass the profile's offline checker (validation/validate_mcp.py at b5418ee). Query.from_dict accepts what the profile's query schema accepts: other values are INVALID_ARGUMENT, and the shape codes are #246's, including E_EMPTY_SCALAR_QUERY. An empty result asks ClickHouse for its columns, which clickhouse-connect leaves out of an empty grouped result. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
| } | ||
| ] | ||
| }, | ||
| "query": { |
There was a problem hiding this comment.
I'm wondering whether we could also support Layer 2 SQL.
This would use Ossie SQL's declarative extensions for querying measures on datasets via AGG(). Like Layer 3, these queries would ultimately be compiled to native SQL. For example, joins involving AGG() would likely be rewritten as correlated subqueries.
The reason I ask is that Layer 2 is now merged / we'll hopefully have some compliance tests for it soon.
Layer 3 still remains a draft (but hopefully, the community can align on an MVP to merge)
orca-review-bot
left a comment
There was a problem hiding this comment.
Nice work on the generator + --check drift setup. It mirrors generate-spec-types.py well, and the checker's passed/failed/unverified split is clear.
Main blocker: main now has core-spec/wide_table_semantics.md, and its Layer 3 query is dimensions / metrics / a single filter. It explicitly excludes row listings, sorting, limits and metric predicates (§3.2). This profile still binds #246 at cc0d0709 (measures, fields, where/having, order_by, limit) and cites error codes main doesn't define. Can we retarget to wide_table_semantics.md, or explain why #246 stays the target?
Other items:
.github/workflows/validation-ci.ymlconflicts with main. Can you rebase?- Can we add tests in
validation/tests/test_validate_mcp.pyfor empty/mixed shapes, so the expected error code is pinned? - How does this line up with #568 (HTTP/Arrow) and #573 (REST)?
Checked and fine: JSON files are covered by dev/.rat-excludes (**/*.json), and no new deps were added.
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
| [specification versus implementation](https://lists.apache.org/thread/wpj5nnpodysds1vqd2s1vxhzw0vkcndy), | ||
| and the [REST proposal](https://lists.apache.org/thread/hf71m6g1g1bnhqj5v0f4kc0rf4h8g4kg). | ||
| Query semantics are those of the [Layer 3 Foundation draft][layer3], pinned to | ||
| `cc0d0709` from [#246](https://github.com/apache/ossie/pull/246). This profile |
There was a problem hiding this comment.
| "type": "object", "additionalProperties": false, | ||
| "properties": { | ||
| "dimensions": { "$ref": "#/$defs/projection" }, | ||
| "measures": { "$ref": "#/$defs/projection" }, |
There was a problem hiding this comment.
Main's Layer 3 calls these metrics (wide_table_semantics.md §3.2). Can we rename here and in the output schema $defs? The query part is filter there, not where.
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
| "fields": { "allOf": [{ "$ref": "#/$defs/projection" }], "minItems": 1 }, | ||
| "where": { "$ref": "#/$defs/predicate" }, | ||
| "having": { "$ref": "#/$defs/predicate" }, | ||
| "order_by": { |
There was a problem hiding this comment.
order_by, limit, fields and having aren't Layer 3 parts on main. §3.2 says sorting, limits, row listings and metric predicates are not supported. Should these be dropped, or marked as profile extensions?
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
| only in `extensions` or flattened to `QUERY_INVALID`. For example, | ||
| `E_NAME_NOT_FOUND`, `E_NO_PATH`, `E_AMBIGUOUS_PATH` and | ||
| `E3013_NO_STITCHING_DIMENSION` retain their defined triggers. | ||
| Mixed/empty query shapes use `E_MIXED_QUERY_SHAPE`, |
There was a problem hiding this comment.
E_MIXED_QUERY_SHAPE, E_EMPTY_SCALAR_QUERY (and E3013_NO_STITCHING_DIMENSION at :254) aren't in main's error list. Also, the inputSchema already rejects empty/mixed shapes, so a host validating arguments never reaches these codes. Can we say which code (INVALID_ARGUMENT vs the Foundation code) clients should expect here?
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
| json.loads(block) | ||
| for block in re.findall(r"```json\n(.*?)\n```", PROFILE.read_text(encoding="utf-8"), re.S) | ||
| ] | ||
| schemas = [block for block in blocks if "$schema" in block] |
There was a problem hiding this comment.
nit: this breaks as soon as the doc gains another block with $schema. Can we select the input/output schemas by an explicit marker instead, e.g. a ```json input-schema info string?
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
| **schema, | ||
| } | ||
| files[f"execute-query-{name}.schema.json"] = json.dumps(schema, indent=2) + "\n" | ||
| arguments = next(block for block in blocks if "data_source_id" in block) |
There was a problem hiding this comment.
nit: this binds to whichever example with data_source_id comes first. Can we tag the canonical example so reordering the doc can't swap it?
🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.
Proposal
Define an optional, model-resolved Layer 3
execute_queryprofile implemented by engines/catalogs, not an Ossie-hosted server or a core-model change.dimensions/measures) and scalar (fields) shapes are disjoint; portable expression fragments, filters, ordering/NULL placement and query-level limits have an explicit JSON Schema. Native query strings andlanguageare excluded.error.code; replacements are the same Layer 3 object type. Advertise capability limits and refuse unsupported evaluation rather than inventing semantics.Adds the proposed contract and examples under
docs/proposals/, plus an implementor-facing conformance kit undervalidation/mcp/. Existing model schemas, converters and query-engine behavior are unchanged.Implementor conformance kit
validate_mcp.pychecks capturedtools/listdeclarations and final tool results: request/repair shapes, status/source/model consistency, embedded CSV, encoding metadata and preview fidelity.Discussion
Related to #510 and the dev@ declarative-scope discussion. Revised to the agreed Layer 3 scope; #246 remains a proposed, pinned dependency, not an adopted standard. This PR specifies serialization/execution envelopes, not new join/grain rules or a Layer 2/native escape hatch.
0.4-draftreplaces0.3-draftnative strings/language and string repair suggestions; this is a breaking proposal revision, not a change to a released implementation. The draft uses pinned MCP tools/resources and Tasks specifications. Preview selection remains guidance; embedded CSV, encoding, diagnostics and Task delivery are retained.Validation
195 validation tests pass, including 78 endpoint-checker cases; Ruff passes on the new Python tooling. Generated schemas/examples are in sync and the synthetic capture passes with explicit unchecked scope. The proposal's separate 138 schema cases cover MCP latest/preview, legacy compatibility and Tasks examples.
git diff --checkpasses; ASF headers are present. No new dependency beyond the existingjsonschematooling, no vendored source, and no query-engine/converter changes.AI assistance
Prepared with AI assistance; tests and schema/example validation were executed locally.