{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":23810,"path":"intelligent-experiences/knowledge-graph/ai-instructiona-and-examples.md","title":"Improving Natural Language Queries with Tag configuration","bundle":null,"doc_type":null,"release":"australia","body":"\n# Improving Natural Language Queries with Tag configuration\n\nAI instructions add more business context to natural language queries. They guide users and promote responses that more closely align with their needs and expectations.\n\n## AI instructions\n\nAI instructions help clarify how the knowledge graph interprets user queries and accesses data. When a user submits a query, relevant instructions at all applicable levels like node, property, and edge are considered.\n\nAI Instructions are persistent, declarative guidance applied at three levels:\n\n- Node \\(entity/table\\) level\n- Property \\(column/attribute\\) level\n- Edge \\(relationship\\) level\n\n## The Always Include flag\n\nThe option to set an **Always include** flag enables users to indicate that a particular instruction should be considered unconditionally. This is useful for enforcing critical business filters, such as always excluding certain asset statuses unless requested otherwise.\n\nInstructions:\n\n- Use **Always include** for business-critical filters that must apply regardless of user query phrasing.\n- Omit **Always include** for context-sensitive instructions that should only apply when relevant.\n- Verify that flagged instructions do not conflict with each other or produce duplicate results.\n\nThe following table shows common scenarios where AI instructions improve query accuracy and provide better business context.\n\n\n
\n\nNo.\n\n\n\nInstruction Pattern\n\n\n\nExample Query\n\n\n\nBehavior without AI instruction\n\n\n\nSample AI instructions\n\n\n\nBehavior with AI instruction\n\n
\n\n1\n\n\n\nPreventing incorrect traversal paths\n\n\n\nWhich companies are located in New York?\n\n\n\nWhen no instructions are added, the query goes from core\\_company to cmn\\_location table and filters on city field by default. But if your use case requires to query location from city field of core\\_company table, you need to write an AI instruction to guide the system on the traversal path.\n\n\n\nTable Instruction on `core_company` table: `For company-city queries, always use core_company.city directly. Do NOT traverse through cmn_location.` This instruction avoids the system from using cmn\\_location path for city-based company queries.\n\n\n\nWhen instruction is added, the query matches with city field in core\\_company table and then filters city=New York and returns all matching companies.\n\n
\n\n2\n\n\n\nProviding column specific context\n\n\n\nWho hosted BBS0000013 brown bag session?\n\n\n\nWhen there is no AI instruction, the system will return sys\\_id without traversing to host\\_s. You need to add an instruction on host\\_s column to provide business context to use this column when query is about host.\n\n\n\nColumn Instruction on `host_s` of `x_snc_brown_bags_sessions` table: `Use s.host_s or :host_s relationship for the host of a brown bag session, NOT s.sys_created_by`\n\n\n\nWhen instructions are added, the query correctly returns the name from host\\_s column.\n\n
\n\n3\n\n\n\nProviding column specific context\n\n\n\nWhat is Kelsey Rodriguez's tenure in current role \\(months\\)?\n\n\n\nWhen there is no AI instruction, the system may not give accurate result as it may provide incorrect information for tenure column. You need to add an instruction to guide the system to refer right column for such queries.\n\n\n\nColumn instruction on `time_in_current_role` column: `Prioritize this column when query contains 'tenure in current role'`\n\n\n\nWhen instructions are added, the query correctly returns the time from `time_in_current_role` column.\n\n
\n\n4\n\n\n\nProviding context on what to prioritize in case of similar tables\n\n\n\nGive me name of Allison Hill's reports having goals pastdue >0?\n\n\n\nWhen there is no AI instruction, LLM will directly refer to “sys\\_user” table to fetch user details instead of traversing to WDF table where this information is stored.\n\n We need to add an instruction to guide LLM to refer right table when there are similar tables.\n\n\n\nTable instruction on WDF table – “x\\_snc\\_wdf\\_user”\n\n *“Always give more priority to \"* x\\_snc\\_wdf\\_user”*over sys\\_user and other glide tables”*\n\n\n\nWhen instructions are added, the query correctly refers to WDF table and return results.\n\n
\n\n5\n\n\n\nProviding context on what to prioritize in case of similar tables\n\n\n\nWhat is your job title?\n\n\n\nWhen there is no AI instruction, LLM will directly refer to “*sn\\_hr\\_core\\_job*” table to fetch job details instead of traversing to*sn\\_hr\\_core\\_profile\"* table where this information is stored.\n\n We need to add an instruction to guide LLM to refer right table when there are similar tables.\n\n\n\nTable instruction on table – “*sn\\_hr\\_core\\_profile*”\n\n *“Always give more priority to \"sn\\_hr\\_core\\_profile\" over “sn\\_hr\\_core\\_job” when user specifically asks about job titles.*\n\n\n\nWhen instructions are added, the query correctly refers to “sn\\_hr\\_core\\_profile” table and return results.\n\n
\n\n6\n\n\n\nDisambiguate among multiple similar and confusing choice values\n\n\n\nWhat are the hardware models that are in normalized state?\n\n\n\nWhen there is no AI instruction, LLM will refer to “normalized” choice value of “normalization status” column which could confuse LLM whether to use other choice values or not as “normalization status” field has 5 choice values \\(normalized, manufacturer normalized, manually normalized, partially normalized, match not found\\).\n\n We need to add instruction to guide LLM on which all choices to include in normalization status.\n\n\n\nColumn instruction on “Column- normalization status”:\n\n *“Always consider normalization status as normalized when choice values is any of the following choices: “normalized, manufacturer normalized, manually normalized”*\n\n\n\nWhen instructions are added, the query correctly considers all 3 choices “normalized, manufacturer normalized, manually normalized” as normalized state and return results.\n\n
## Best practices for AI instructions\n\nFollow these guidelines when creating AI instructions to verify optimal performance and accuracy:\n\n- Write clear, unambiguous, and actionable instructions tied to business logic. Always reference the correct tables \\(nodes\\), columns \\(properties\\), and relationships \\(edges\\). Use flags like Always include only when enforcing true default business behavior.\n- Avoid vague or contradictory instructions. Instructions that do not align with the underlying data model can confuse the system and lead to incorrect results. For example, an instruction like \"Filter by manufacturer\" without specifying the column or condition is ambiguous.\n- Use conditions to control when logic applies. Clearly state when an instruction should be applied \\(for example, only when the user asks for host information\\), rather than applying logic universally.\n- Keep instructions focused and generalized. Instructions should guide intent interpretation across similar queries, not solve a single one-off case.\n- Do not duplicate logic already handled elsewhere. Avoid restating filters or constraints that are already enforced through data filters to avoid conflict.\n\n## Support for Synonyms, Data Filters and hidden columns\n\nSynonyms:\n\nKnowledge Graph supports configuring synonyms for tables, columns, edges, and reverse edges to enhance flexibility and user-friendliness. Synonyms enable users to define alternate names for these entities, accommodating different terminologies.\n\n- Each entity can have up to five synonyms.\n- Synonyms promote broad coverage for commonly used alternate terms.\n- Maintaining a manageable synonym set reduces ambiguity in query resolution.\n\nData Filters:\n\nData filters are applied deterministically as post-processing rules to refine query results. After initial Cypher generation, filters are systematically applied to promote consistency and reliability of outcomes.\n\n- Filters are applied after Cypher generation, not during.\n- Dynamic filters enable real-time adaptation based on user context.\n- Improves precision and relevance of returned data. Does not modify the core graph query.\n\nHidden columns:\n\nHidden columns cannot be queried and do not appear in the result.\n\nFor example: add Employee number as hidden columns for sys\\_user table to hide the employee number from query results.\n\n"}}