Semantic Layer — Business Context for NL2SQL

Inject business-domain semantics into NL2SQL prompts to reduce incorrect queries.

3|Updated May 3, 2026
One-click install
npx skills add https://github.com/ductoanoxo/Agent_SQL --skill semantic-layer-business-context-for-nl2sql
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: Semantic Layer — Business Context for NL2SQL
Source: https://github.com/ductoanoxo/Agent_SQL/tree/main/docs_mainengine/skills/semantic-layer
Command: npx skills add https://github.com/ductoanoxo/Agent_SQL --skill semantic-layer-business-context-for-nl2sql

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill prevents NL2SQL from generating incorrect queries caused by missing business meaning that does not exist explicitly in the database schema, such as KPI definitions, domain status mappings, and calculation logic.

Core Features & Use Cases

  • Business glossary for KPI logic: Defines domain terms (e.g., “Khách hàng tiềm năng”, “Doanh thu thuần”) with the exact SQL computation the model must use.
  • Synonym dictionary for entity mapping: Maps Vietnamese business language to the correct tables/columns the model should query.
  • Value profiles and few-shot examples: Supplies allowed categorical/enum values and representative Q→SQL patterns so generated WHERE/GROUP BY/ORDER BY logic follows project conventions.
  • Operational workflow for onboarding new domains/DBs: Provides a repeatable checklist to update synonyms, value profiles, glossary, and examples when new tables or business terminology are introduced.

Quick Start

Ask your AI to generate NL2SQL only after applying the Semantic Layer glossary, synonyms, and value profiles for your target domain, so a question like “Khách hàng tiềm năng tháng này” is translated using the defined KPI SQL instead of being inferred from unrelated fields.

Frequently Asked Questions about Semantic Layer — Business Context for NL2SQL

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix incorrect NL2SQL outputs when KPI definitions are missing from the database schema?

To fix incorrect NL2SQL outputs, you need a semantic layer that injects business-domain context. This Skill provides a KPI glossary with exact SQL computations, preventing the model from inferring calculation logic from unrelated database schema fields.

Why does my NL2SQL pipeline misinterpret business terms and statuses?

Your NL2SQL pipeline misinterprets business terms because raw database schemas lack domain semantics. Applying a semantic layer with a synonym dictionary and value profiles maps categorical enum values to the correct tables and columns for accurate query generation.

What is the best way to translate Vietnamese business language into correct SQL queries?

The best way to translate Vietnamese business language into SQL is by using a semantic layer synonym dictionary. It maps domain terminology directly to the correct database tables and columns, ensuring the NL2SQL model queries the right entities.

How do I onboard a new database to an NL2SQL pipeline without losing business context?

You can onboard a new database by following a repeatable checklist to update synonyms, value profiles, and the KPI glossary. This operational workflow ensures new tables and business terminology are correctly mapped before generating SQL.

Can I use few-shot examples to enforce WHERE and GROUP BY logic in NL2SQL?

Yes, you can enforce WHERE and GROUP BY logic by providing few-shot example patterns. This Skill supplies representative Question to SQL patterns so the generated queries follow your specific project conventions and domain calculation rules.

Do I need a business glossary to calculate domain metrics like Doanh thu thuần in NL2SQL?

You need a business glossary to calculate domain metrics like Doanh thu thuần accurately. The glossary defines these KPIs with the exact SQL computation the model must use, overriding any incorrect logic inferred from the raw schema.