Kyvos Dialogs Context Setup Best Practices Guide
Overview
These guidelines provide a structured framework to ensure Kyvos Dialogs generates accurate, governed, and business‑aligned responses. They help users and administrators maintain consistency in natural‑language interpretation, protect semantic integrity, and ensure SQL generation follows approved enterprise logic. By defining clear standards, these guidelines improve reliability, reduce ambiguity, and enable a trusted self‑service analytics experience.
Kyvos enables natural language querying across one or more Semantic Models (SMs), allowing users to interact with data intuitively and efficiently. Based on specific business requirements, related Semantic Models are logically grouped within an AI Space. AI Space serves as a governance and organization layer, providing better control, security, and manageability of Semantic Models. By grouping models with similar business domains or use cases, AI Spaces help ensure that queries are contextually relevant, easier to manage, and aligned with organizational analytics objectives.
Semantic model - AI settings
Describe the Business Purpose and Usage of the Semantic Model (SM)
Select the Desired SM > AI Settings > Context > Set “Business Context” field manually or Ask Kyvos Copilot to generate the business context through LLM.
Manual Way: Clearly defining the business purpose and intended usage of a SM provides essential context for Large Language Models (LLMs). This context enables LLMs to accurately discover, interpret, and query the semantic model, resulting in more precise, relevant, and business-aligned insights across data and metadata.
Through Ask Kyvos Copilot: If the user is not familiar with the business context of the model, they can leverage the “Ask Copilot” feature in Kyvos.
Click on “Ask Kyvos Copilot” > Put few lines you know about the SM > Click on Generate so that LLM will generate business context for the SSM > Click on “Accept”
This feature assists users in identifying and establishing the appropriate business context for the selected semantic model, ensuring the model is correctly understood and effectively utilized for analytical and operational needs.
For Example – Use the below mentioned recommend format to provide the business context for the SM
Business Purpose
This semantic model structures order, customer, and product data to support analysis of sales performance, customer activity, and product demand over time.
Usage
Business users query this model to track order trends, analyze customer behavior, compare product performance, and answer day-to-day business questions using natural language.
Provide Tags and Business context for each column in the SM
Select the Desired SM > AI Settings > Columns Metadata > Set the Tags and the Business context for each column of SM
The tags and the Business context for each column of SM can be set manually or through “Ask Kyvos Copilot” to generate the tags and Business context by LLM.
Manual Way: Always provide proper tags and business context to each column, which will be used to pick columns for querying correctly. Tags should ideally contain the synonyms or business language that the customer will use to refer to specific columns. Leverage ‘Ask Kyvos Copilot’ to generate the tags and description.
Hide all unnecessary Levels, Attributes, and Measures not required for conversational analytics.
Special characters must not be present in the name of the semantic model, tags, and description.
Ensure that you clearly define the Keys field for level and attributes for which you want a different sort order than the order of the display field.
Through Ask Kyvos Copilot: If the user is not familiar with the Tags and business context of the columns, they can leverage the “Ask Copilot” feature in Kyvos.
Click on “Ask Kyvos Copilot” > Select the desired columns > Provide additional context for these columns > Click on Generate so that LLM will generate Tags and Business context for these columns > Click on “Accept”. This feature assists users in identifying and establishing the appropriate Tags and business context for the columns.
Create an AI Space object on top of semantic model
It is strongly recommended to run Dialogs on an AI space object instead of directly on a semantic model.
The AI space object serves as a future-ready context layer for conversational analytics, built on top of Kyvos data and metadata. All upcoming enhancements and capabilities will be developed on the AI space framework.
Even if your business use case involves only a single semantic model, you should include that model within an AI space and expose the AI space to Dialogs.
AI Space - AI settings
Describe the Business Purpose and Usage for AI Space
Select the desired AI Space > Context > Business Context > Provide Business context for the AI space
Clearly defining the business purpose and intended usage of the AI space provides essential context for Large Language Models (LLMs). This context enables LLMs to accurately discover, interpret, and query resulting in more precise, relevant, and business-aligned insights across different SMs present in the AI space.
For Example – Use the below mentioned format to provide the business context for the AI space. This is for reference.
Business Purpose
This AI space structures order, customer, and product data to support analysis of sales performance, customer activity, and product demand over time.
Usage
Business users query this AI space to track order trends, analyze customer behavior, compare product performance, and answer day-to-day business questions using natural language.
Define Query Instruction for AI Space
Select the desired AI Space > Context > Query Instructions > Provide Query Instructions for the AI space
Query instruction guides/explains Kyvos Dialogs to translate natural‑language questions into governed, accurate, and reliable SQL to get expected output.
Query Instructions define the high‑level behavioral rules that Kyvos Dialogs follows when interpreting user questions and constructing SQL queries.
For more detail, refer to the section – “QUERY INSTRUCTION AND VERIFIED QUERIES …”
For Example – Use the following format to provide the Query instructions. This is for reference –
--- Enterprise governance rules ---
-Exclude rows where net_sales = 0 and aum = 0 unless the user explicitly asks for zero-value records.
--- Business defaults ---
-Apply report_year = 'TY' as the default time filter when the user does not specify a time range. 'TY' represents the current financial year.
-For questions referring to last year, apply report_year = 'LY'.
-Always exclude rows where plan_type = 'Direct' when analyzing distributor performance, unless the user explicitly requests Direct Plan data.
-Include only rows where fund_status = 'Active' by default. Override only when the user explicitly asks for inactive or all funds.
---CROSS-SEMANTIC Correlation ---
-Join semantic models only using fund_code, distributor_code, investor_id, or date as join keys.
-JOIN Sales semantic + AUM semantic using fund_code and month.
-JOIN Sales semantic + Distributor Master semantic using distributor_code.
--- Time logic ---
-When the question contains no time reference, filter on the maximum value of fiscal_year_week where report_year = 'TY'.
-For "Last N weeks"** : select the latest N distinct values of fiscal_year_week where report_year = 'TY', ordered descending, and limit to N.
--- ANALYSIS PATTERNS ---
**YoY Comparison**
Triggers: YoY, year-over-year, vs last year, compare TY and LY
Context: Standardized comparison between current-year (TY) and last-year (LY) performance on aligned weeks.
Logic:
Identify TY weeks from the query and map LY weeks using comparativeyearweek.
Aggregate metrics separately for report_year = 'TY' and report_year = 'LY'.
Align TY and LY results using comparativeyearweek to present the YoY comparison with optional variance.
Do not apply any additional default time filters beyond what the query specifies.
**Net Sales vs AUM Combined View**
Triggers: Sales and AUM together, Net Sales with AUM, combined performance
Context: When a question requires both transactional sales data and AUM data, which reside in separate semantic models.
Logic:
Join Sales and AUM semantic models on fund_code and date.
Show fund_name, net_sales, aum, financial_year.
Define Verified Queries for AI Space
Select the desired AI Space > Context > Verified Queries > Click on Manage Queries > Click on “+” icon to add new Query > Provide Natural Language of the Query > Provide SQL Query > Click on Apply
Define pre‑approved, deterministic queries for high‑value business questions that must always produce consistent results.
Users can like and save important results as Verified Queries.
When a user asks a question, the system semantically searches for the most relevant Verified Queries, retrieves the closest matches, and uses them to guide SQL generation.For more detail, refer to the section – “QUERY INSTRUCTION AND VERIFIED QUERIES …”
Considerations
Kyvos Dialogs leverages a Large Language Model (LLM) to convert natural language to SQL, which might sometimes produce inaccurate generation. Always verify the answer by checking the information in the answer. In case of an error or incorrect response, try regenerating the answer by re-submitting the question.
Layout adjustments like resizing visuals or precise alignment aren't possible through Kyvos Dialogs.
To generate natural language titles, summaries, and key insights for visualizations, Kyvos needs to send some data to LLMs. If you have concerns about data sharing with LLMs, you can enable or disable this feature by setting the value of the Allow to send data to LLM property to ‘Yes’ or ‘No’ on the GenAI Configuration page.
QUERY INSTRUCTION AND VERIFIED QUERIES AUTHORING GUIDE FOR AI SPACE
This guide defines how AI converts natural-language questions into governed, reliable SQL using two complementary instruction systems:
A. Query Instructions
Key areas governed by Query Instructions may include:
Enterprise Governance: Enforce organizational policies such as data access controls, compliance constraints, and security guidelines to ensure only authorized and compliant queries are generated.
Business Defaults: Apply standard business assumptions (for example, default measures, currencies, regions, or time periods) to ensure consistent interpretations in the absence of explicit user input.
Cross‑Entity Relationships: Define how facts and dimensions relate across multiple semantic entities, enabling the AI to generate accurate joins and multi‑entity queries.
Time Logics: Standardize handling of time‑based calculations such as year‑to‑date (YTD), period‑over‑period (PoP), rolling windows, and custom time comparisons.
Analysis Pattern: Guide the AI toward recognized analytical approaches (e.g., trend analysis, variance analysis, top‑N, ranking) to deliver insights that match business expectations.
B. Verified Queries
Define pre‑approved, deterministic queries for high‑value business questions that must always produce consistent results.
Users can like and save important results as Verified Queries.
When a user asks a question, the system semantically searches for the most relevant Verified Queries, retrieves the closest matches, and uses them to guide SQL generation.
How it helps
Verified Queries:
Standardize answers across recurring KPI scenarios
Improve consistency and reliability
Reduce the size and complexity of Query Instructions
Ensure that governance rules are applied intelligently and selectively
Query Instructions provide the global rules, whereas Verified Queries provide specific guidance for known, high‑value questions
2. Query Instructions
Purpose:
Applies across all Semantic models inside the AI space.
Establish enterprise-wide rules
Standardize time logic, comparison logic, and glossaries
Govern cross-Semantic interactions
2.2. Core Writing Principles of Query Instructions
Every rule of the Query Instruction must be:
Direct - Use imperative system actions: “Always”, “Include”, “Filter”.
Example: Always use Product Brand as the default dimension unless the user explicitly specifies another dimension.Action-Oriented - State expected behavior, not explanations.
Example: “Filter on maximum of fiscal year week for report year = 'TY' when the question contains no time reference.”Unambiguous - Each rule must have only one possible interpretation.
Example: “For ‘Last N weeks’, select the latest N distinct values of fiscal year week where report year = 'TY', ordered descending, and limit to N.”Technically Precise – Refer exact column name
Example: “For YoY comparisons, aggregate TY and LY separately and join them using `comparativeyearweek` with no additional default filters.”Exception-Aware- Any rule that overrides the default must explicitly state the condition.
Example: “Always include Product Activity when a question compares stores using store code or store name, unless the question specifies a different breakdown.”
2.3. Writing Format of Query Instructions
A valid format includes:
Query Instruction Category:
A concise, business‑friendly name that reflects the analytical intent.
It would be written as --- <Pattern Category> ---
Pattern Name:
A short label for this analysis.
It would be written as *** <Pattern Name> ***
Triggers: Phrases that should activate this pattern
Context: What business problem this analysis solves (optional)
Logic:
points of what to show,
what to filter
logic to use
EXAMPLE –
--- Outlier Analysis ---
**AHT Outlier Analysis**
Triggers: Top X% AHT Outlier, Highest AHT agents, AHT outliers
Context: Identify agents with exceptionally high handling times that may indicate inefficiency or complex call patterns.
Logic:
Get following fields: Agent, LOB, Tenure, Present Days, AHT, Handled Calls, Talk Time%, Hold Time%, Wrap Time% fields
Having AHT is greater than 0.
Show the highest AHT on top.
**Low AHT Outlier Analysis**
Triggers: Top X% AGS Outlier, Highest AGS agents, AGS outliers
Context: Identify agents with exceptionally low handling times that may indicate efficiency or simple call patterns.
Logic:
Get following fields: Agent, LOB, Tenure, Present Days, AHT, Handled Calls, Talk Time%, Hold Time%, Wrap Time% fields
Having AHT is greater than 1.
Show the lowest AHT on top.
2.4. Incorrect vs Correct Instruction Writing Guide (Query Instructions)
Below are expanded explanations showing why each “correct” version is superior.
Incorrect vs Correct Instruction Writing — with Principal Category
Examples | Incorrect Way of Writing | Correct Way of Writing | Category (Core Writing Principle) |
Ambiguous Dimension Handling | “If brand is not clear, maybe use product brand. Try to understand what the user means.” | “When there is ambiguity in dimension selection, use Product Brand as the default filtering field unless the question explicitly specifies another dimension.” | Direct; Unambiguous Exception‑Aware |
Default Time Filtering | “If no time is mentioned, take latest week.” | “If the question does not contain any time reference, apply a filter on the maximum value of fiscal year week for the current reporting year.” | Technically Precise Action‑Oriented Unambiguous |
Week Interpretation | “Handle last few weeks properly.” | “For ‘Last N weeks’, select the latest N distinct values of fiscal year week for report year = ‘TY’, ordered descending, and filter only top 10” | Technically Precise Unambiguous Action‑Oriented |
Year Filtering | “For this year use TY and for last year use LY.” | “For questions referring to this year, apply report year = ‘TY’. For questions referring to last year, apply report year = ‘LY’.” | Direct Unambiguous Technically Precise |
YoY Comparison Logic | “If user asks YoY, compare with last year sales.” | **YoY Comparison**
| Name space pattern Technically Precise Action‑Oriented Unambiguous Exception‑Aware |
Store‑Level Comparison | “When comparing stores, check product also.” | “When a question compares individual stores using store code or store name and asks for reasons or drivers, always include analysis by Product Activity. Apply this rule only for store‑level comparisons.” | Exception‑Aware Direct Action‑Oriented |
2.5. COMPLETE EXAMPLES (Query Instructions)
Note
The example sections below use optional headers (such as “REQUIRED OUTPUT FIELDS”) to clearly separate different instruction categories. While these headers are not mandatory, we recommend using them because they improve structure and make the instructions easier to manage.
Example
--- REQUIRED OUTPUT FIELDS ---
Always include fund_name and financial_year in all query results.
Always include distributor_code and distributor_name together whenever distributor-level data appears in the result.
Always include net_sales and aum together when the question involves performance reporting.
--- DEFAULT FILTERS ---
Apply report_year = 'TY' as the default time filter when the user does not specify a time range. 'TY' represents the current financial year.
For questions referring to last year, apply report_year = 'LY'.
Always exclude rows where plan_type = 'Direct' when analyzing distributor performance, unless the user explicitly requests Direct Plan data.
Include only rows where fund_status = 'Active' by default. Override only when the user explicitly asks for inactive or all funds.
Include only distributors that have at least one transaction in the selected period by default. Override only when the user explicitly asks for inactive distributors.
Exclude rows where net_sales = 0 and aum = 0 unless the user explicitly asks for zero-value records.
--- TIME LOGIC ---
When the question contains no time reference, filter on the maximum value of fiscal_year_week where report_year = 'TY'.
**For "Last N weeks"** : select the latest N distinct values of fiscal_year_week where report_year = 'TY', ordered descending, and limit to N.
** MTD means Month-To-Date **: include all dates from the start of the current month up to but excluding the current month-end. When asked for MTD, always exclude the current incomplete month.
** YTD means Year-To-Date **: include all dates from the start of the current financial year up to but excluding the current month. When asked for YTD, always exclude the current month.
--- BUSINESS GLOSSARY ---
Revenue refers to the net_sales column.
AUM refers to the eop_aum (End-of-Period AUM) column.
Top means the highest 10 records ranked by the primary KPI in the question, unless the user specifies a different count.
Growth means (Current Period Value – Previous Period Value) / Previous Period Value, unless a growth column already exists in the semantic model.
--CROSS-SEMANTIC Correlation--
Join semantic models only using fund_code, distributor_code, investor_id, or date as join keys.
JOIN Sales semantic + AUM semantic using fund_code and month.
JOIN Sales semantic + Distributor Master semantic using distributor_code.
--- ANALYSIS PATTERNS ---
**YoY Comparison**
Triggers: YoY, year-over-year, vs last year, compare TY and LY
Context: Standardized comparison between current-year (TY) and last-year (LY) performance on aligned weeks.
Logic:
Identify TY weeks from the query and map LY weeks using comparativeyearweek.
Aggregate metrics separately for report_year = 'TY' and report_year = 'LY'.
Align TY and LY results using comparativeyearweek to present the YoY comparison with optional variance.
Do not apply any additional default time filters beyond what the query specifies.
**Net Sales vs AUM Combined View**
Triggers: Sales and AUM together, Net Sales with AUM, combined performance
Context: When a question requires both transactional sales data and AUM data, which reside in separate semantic models.
Logic:
Join Sales and AUM semantic models on fund_code and date.
Show fund_name, net_sales, aum, financial_year.
Verified Queries
Use Verified Queries for frequently asked, high‑value business questions where results must remain consistent across users and time.
They ensure deterministic answers, standardize KPI reporting, and reduce ambiguity in how recurring business questions are interpreted and executed.
The system automatically incorporates the most relevant Verified Queries during SQL generation whenever the user’s question matches their intent. This ensures consistent, governed outcomes without requiring users to apply the logic manually.
How to Use Verified Queries
Users can save trusted queries as Verified Queries.
When a new question is asked, the system retrieves the most relevant matches using a semantic search.
The retrieved Verified Queries are then used to influence and guide SQL generation, ensuring consistent and governed outcomes across similar questions.
Steps to Save a Verified Query
Get an answer: Ask a question and review the AI-generated result.
Like the response: When user gets an answer then user can click the like button
Verify the query: User can add current response to verified queries by clicking on the Verify button
Add Context (Optional): User may add additional context to help the system match a broader range of similar questions. Then click Verify.
Confirmation: Once we click on verify, then the query is saved. Once verified, the query is saved and will be used to guide future SQL generation for semantically similar question
How to Manage Verified Queries
To review saved Verified Queries: Go to AI Space → Context → Verified Queries.
To edit a Verified Query: Open the query, update the SQL or context, and click Verify to save changes.
Go to AI Space or Semantic model: To check same on AI space or semantic model , user can go to AI space
User can click on the Context of AI space or semantic model and observe the Verified Queries added.
User can edit the verified Queries and again save the changes by clicking on Verify to save changes.
Example
In the example shown, product_name_store is defined as the preferred product‑name field.
From now on, any query asking for Top N product sales will automatically use product_name_store.
Query saved
SELECT `product_name` AS `product_name_store`, `product_id` AS `product_id_store`, SUM(`Total Sales`) AS `total_sales_store`
FROM `Business_Catalog`.`Retail_Superstore`
GROUP BY `product_name`, `product_id`
ORDER BY `total_sales_store` DESC, `product_name_store`, `product_id_store`
LIMIT 5APPENDIX — EXAMPLE QUERY INSTRUCTION PATTERNS FOR SPECIFIC MODELS
This appendix provides example query instruction patterns that have been observed to work effectively with specific AI providers and model versions.
These patterns are intended as practical and commonly used references and starting points for authoring high-quality query instructions. They illustrate how certain prompt structures behave with specific models and can help reduce trial-and-error during setup.
QUERY INSTRUCTIONS — EXAMPLE PATTERNS & TEMPLATES
This section is organized into two parts:
Section 1 — Generic Templates
Reusable templates for authoring new query instruction patterns like mtd, ytd, yoy or mom patterns, which are common in BI world and are used by most of our customers but in different contexts and fields. Hence, we have come up with the templates so that teams can replace placeholders with respective domain-specific details.Section 2 — Example Instruction Patterns
Concrete query instruction patterns that have been tested with specific AI models. Use these as reference implementations when creating or refining your own instructions.
SECTION 1 — GENERIC TEMPLATES FOR NEW INSTRUCTIONS
The templates below are reusable starting points for authoring new query instruction patterns. Copy a template, replace placeholders with your domain-specific details, and test with your chosen AI provider before deploying. Use the Tested With field only as documentation (it is not required to be included in the deployed instruction text).
TEMPLATE A — Relative Date Anchoring
Use when: Your data does not use real-time dates and you need the AI to treat a fixed date as “today”.
--- Relative Dates ---
**relative month**
Logic: Always build the “relative month” by combining these individual calculations:
Always calculate the current month
Always assign <BASE_YEAR> as the “current year”
**relative day of month**
Logic: Always build the “relative day of month” by calculating the current day of month.
**relative quarter**
Logic: Always build the “relative quarter” by combining these individual calculations:
Always calculate the current quarter
Always assign <BASE_YEAR> as the “current year”
**relative day of quarter**
Logic: Always build the “relative day of quarter” by calculating the current day of quarter.
**relative year**
Logic: Always build the “relative year” as <BASE_YEAR>.
**relative date**
Logic: Always build the “relative date” as the current date in <BASE_YEAR>.
Placeholders:
<BASE_YEAR> — The year your data is anchored to (e.g., 2023, 2024).
Example (filled):
--- Relative Dates --- relative month · Always calculate the current month · Always assign 2023 as the “current year” relative day of month relative quarter · Always calculate the current quarter · Always assign 2023 as the “current year” relative day of quarter relative year relative date | Tested With Azure OpenAI (GPT-4.1) Apr 2026 |
TEMPLATE B - Period-to-Date Filter (MTD / QTD / YTD / PMTD / PYTD / PQTD)
Use when: Users ask “month to date”, “prior year to date”, or similar period-based questions and you need the AI to filter correctly.
**<PATTERN_NAME>**
Triggers: <TRIGGER_1>, <TRIGGER_2>, <TRIGGER_3>
Logic: Always filter the [[Month field from date hierarchy]] <= relative month and relative day of month.
For prior-period variants, use this Logic instead:
Logic: Always filter the [[Month field from date hierarchy]] <= (relative month - 1 month) + relative day of month.
Placeholders:
<PATTERN_NAME> — Short label (e.g., mtd, pytd, pqtd).