feat: Add sql-query-explainer kit#150
Open
Saadonweb wants to merge 8 commits intoLamatic:mainfrom
Open
Conversation
This configuration defines the SQL Query Explainer workflow, detailing its purpose, version, author, tags, steps, and relevant links.
This document outlines the SQL Query Explainer AgentKit template, detailing its purpose, operational flow, and use cases for understanding SQL queries without execution.
This README provides an overview of the SQL Query Explainer workflow, detailing its purpose, output structure, use cases, prerequisites, and usage instructions.
This file implements a SQL Query Explainer flow that accepts a raw SQL query and returns a structured JSON explanation, including a summary, clause breakdown, performance concerns, and optimization suggestions.
Add structured explanation format for SQL query analysis.
Contributor
WalkthroughThis pull request introduces a new SQL Query Explainer kit—a complete template containing flow definitions, configuration files, system and user prompts, and documentation. The kit enables SQL analysis through an LLM-powered workflow without executing queries or requiring database connections. Changes
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 0/1 reviews remaining, refill in 60 minutes.Comment |
PR Validation ResultsNew Contributions Detected
Check Results
Errors
🛑 Please fix the errors above before this PR can be merged. Refer to CONTRIBUTING.md and CLAUDE.md for the expected folder structure. |
Author
|
Submitting as part of the Lamatic This kit adds a SQL Query Explainer agent — accepts any SQL query, returns a structured JSON explanation with summary, clause-by-clause breakdown, performance concerns, and optimisation suggestions. Please apply the |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@kits/sql-query-explainer/prompts/sql-query-explainer_explain-query_user.md`:
- Around line 1-3: The prompt injects raw user SQL via
{{triggerNode_1.output.query}} without delimiters; wrap the interpolated value
in an explicit fenced block or clear delimiter (e.g., triple backticks or
labeled sql fence) so the model treats it strictly as data rather than
instructions—update the template in sql-query-explainer_explain-query_user.md to
place {{triggerNode_1.output.query}} inside that fenced block (or equivalent
delimiter) and ensure any leading/trailing whitespace is preserved but outside
text of the prompt.
In `@kits/sql-query-explainer/README.md`:
- Around line 42-52: Add an "Environment variables" section to the README.md
(near the "Prerequisites" and "Usage" sections) that explicitly documents
required env vars for this kit: either list each variable name, its purpose, and
example/default value if any, or state "No environment variables required" if
none are needed; update the README headings to include "Environment variables"
so contributors know where to look.
- Around line 11-23: The README currently implies the API returns a parsed
object but the code forwards generatedResponse directly into the explanation
field, so the API actually emits JSON text; update the README wording and
example to clearly state that explanation is a JSON string (text) that clients
must JSON.parse, and change the example block to show the field as JSON text (or
show parsing example) so consumers know to parse the explanation value
generatedResponse into an object before reading summary, clauses,
performance_concerns, optimisation_suggestions, dialect_hint, and
example_output_description.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Pro
Run ID: 22c2965f-73eb-43ca-bd09-7a2b3862cd9b
📒 Files selected for processing (8)
kits/sql-query-explainer/.gitignorekits/sql-query-explainer/README.mdkits/sql-query-explainer/agent.mdkits/sql-query-explainer/flows/sql-query-explainer.tskits/sql-query-explainer/lamatic.config.tskits/sql-query-explainer/model-configs/sql-query-explainer_explain-query.tskits/sql-query-explainer/prompts/sql-query-explainer_explain-query_system.mdkits/sql-query-explainer/prompts/sql-query-explainer_explain-query_user.md
Comment on lines
+1
to
+3
| SQL Query: | ||
|
|
||
| {{triggerNode_1.output.query}} |
Contributor
There was a problem hiding this comment.
Mission risk: delimit the SQL before interpolation.
Raw interpolation here mixes user data with prompt instructions, which makes prompt-injection and instruction-smuggling easier. Wrap the query in an explicit fenced block or another delimiter so the model treats it as data.
Suggested fix
SQL Query:
-{{triggerNode_1.output.query}}
+```sql
+{{triggerNode_1.output.query}}
+```📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| SQL Query: | |
| {{triggerNode_1.output.query}} | |
| SQL Query: | |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 1-1: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@kits/sql-query-explainer/prompts/sql-query-explainer_explain-query_user.md`
around lines 1 - 3, The prompt injects raw user SQL via
{{triggerNode_1.output.query}} without delimiters; wrap the interpolated value
in an explicit fenced block or clear delimiter (e.g., triple backticks or
labeled sql fence) so the model treats it strictly as data rather than
instructions—update the template in sql-query-explainer_explain-query_user.md to
place {{triggerNode_1.output.query}} inside that fenced block (or equivalent
delimiter) and ensure any leading/trailing whitespace is preserved but outside
text of the prompt.
Comment on lines
+11
to
+23
| The API response contains an `explanation` field with a JSON object: | ||
|
|
||
| ```json | ||
| { | ||
| "summary": "Plain-English description of what the query does.", | ||
| "dialect_hint": "PostgreSQL", | ||
| "clauses": [ | ||
| { "clause": "SELECT", "explanation": "Retrieves user ID, name, and order count." } | ||
| ], | ||
| "performance_concerns": ["LEFT JOIN on large table without index on user_id."], | ||
| "optimisation_suggestions": ["Add index on orders.user_id."], | ||
| "example_output_description": "Up to 20 rows with user ID, name, order count sorted descending." | ||
| } |
Contributor
There was a problem hiding this comment.
Mission clarity: describe the response as JSON text, not a parsed object.
The flow forwards generatedResponse directly into explanation, so the API emits JSON text unless another step parses it. Update the wording/example so consumers know they need to parse the field.
Suggested wording tweak
- The API response contains an `explanation` field with a JSON object:
+ The API response contains an `explanation` field containing JSON text for the explanation object:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| The API response contains an `explanation` field with a JSON object: | |
| ```json | |
| { | |
| "summary": "Plain-English description of what the query does.", | |
| "dialect_hint": "PostgreSQL", | |
| "clauses": [ | |
| { "clause": "SELECT", "explanation": "Retrieves user ID, name, and order count." } | |
| ], | |
| "performance_concerns": ["LEFT JOIN on large table without index on user_id."], | |
| "optimisation_suggestions": ["Add index on orders.user_id."], | |
| "example_output_description": "Up to 20 rows with user ID, name, order count sorted descending." | |
| } | |
| The API response contains an `explanation` field containing JSON text for the explanation object: | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@kits/sql-query-explainer/README.md` around lines 11 - 23, The README
currently implies the API returns a parsed object but the code forwards
generatedResponse directly into the explanation field, so the API actually emits
JSON text; update the README wording and example to clearly state that
explanation is a JSON string (text) that clients must JSON.parse, and change the
example block to show the field as JSON text (or show parsing example) so
consumers know to parse the explanation value generatedResponse into an object
before reading summary, clauses, performance_concerns, optimisation_suggestions,
dialect_hint, and example_output_description.
Comment on lines
+42
to
+52
| ## Prerequisites | ||
|
|
||
| - A Lamatic.ai account ([lamatic.ai](https://lamatic.ai)) | ||
| - An LLM provider connected in your Lamatic workspace | ||
|
|
||
| ## Usage | ||
|
|
||
| 1. Import this template into your Lamatic workspace | ||
| 2. Connect your LLM provider credentials | ||
| 3. Deploy the flow | ||
| 4. Send a POST request with a `query` field containing your SQL |
Contributor
There was a problem hiding this comment.
Mission requirement: add an environment-variables section.
The README currently covers setup and usage, but it never states whether the kit needs any env vars or explicitly that none are required. That leaves the kit documentation incomplete for contributors. As per coding guidelines, kits/**/README.md: Every kit must have a README.md that documents setup, environment variables, and usage.
Suggested addition
## Prerequisites
- A Lamatic.ai account
- An LLM provider connected in your Lamatic workspace
+
+## Environment Variables
+
+- None required. This kit uses the connected LLM provider configured in Lamatic.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ## Prerequisites | |
| - A Lamatic.ai account ([lamatic.ai](https://lamatic.ai)) | |
| - An LLM provider connected in your Lamatic workspace | |
| ## Usage | |
| 1. Import this template into your Lamatic workspace | |
| 2. Connect your LLM provider credentials | |
| 3. Deploy the flow | |
| 4. Send a POST request with a `query` field containing your SQL | |
| ## Prerequisites | |
| - A Lamatic.ai account ([lamatic.ai](https://lamatic.ai)) | |
| - An LLM provider connected in your Lamatic workspace | |
| ## Environment Variables | |
| - None required. This kit uses the connected LLM provider configured in Lamatic. | |
| ## Usage | |
| 1. Import this template into your Lamatic workspace | |
| 2. Connect your LLM provider credentials | |
| 3. Deploy the flow | |
| 4. Send a POST request with a `query` field containing your SQL |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@kits/sql-query-explainer/README.md` around lines 42 - 52, Add an "Environment
variables" section to the README.md (near the "Prerequisites" and "Usage"
sections) that explicitly documents required env vars for this kit: either list
each variable name, its purpose, and example/default value if any, or state "No
environment variables required" if none are needed; update the README headings
to include "Environment variables" so contributors know where to look.
|
Hi @Saadonweb! 👋 Before this PR can be reviewed by maintainers, please resolve all comments and requested changes from the CodeRabbit automated review. Steps to follow:
This helps keep the review process efficient for everyone. Thank you! 🙏 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Checklist
1. Select Contribution Type
kits/<category>/<kit-name>/)bundles/<bundle-name>/)templates/<template-name>/)2. General Requirements
kebab-caseand matches the flow IDREADME.md(purpose, setup, usage)3. File Structure (Check what applies)
config.jsonpresent with valid metadata (name, description, tags, steps, author, env keys)flows/<flow-name>/(where applicable) include:config.json(Lamatic flow export)inputs.jsonmeta.jsonREADME.md.env.examplewith placeholder values only (kits only)config.jsonnode graphs (changes via Lamatic Studio export)4. Validation
npm install && npm run devworks locally (kits: UI runs; bundles/templates: flows are valid)[kit] Add <name> for <use case>)