Best Practice > Improving Question Interpretation and Response Generation

Intended audience: developers administrators

AO Platform: 4.5

Overview

The following Best Practice guidance is a compilation of issues and scenarios that have been found and documented during practical implementations of Ontologies and associated Easy Answers solutions, resulting in enrichments of the Ontologies, guidance on how to formulate questions for optimal interpretation, and response generation, as well as process and documentation recommendations.

Section: Technical

Case Sensitivity in Synonym Matching

What - Ensure that synonyms used in queries are case-sensitive where necessary to avoid mismatches.
Why - Case sensitivity in synonym matching ensures that queries return accurate and relevant results based on the intended context.
How - Configure synonyms in the ontology to be case-sensitive when required. Test synonym usage across different scenarios to verify accuracy.

Apply Contradiction Rules in Data Queries

What - Introduce contradiction rules in your data queries to handle exceptions and avoid conflicting criteria.
Why - This prevents erroneous query results when default criteria conflict with specific user queries, ensuring only relevant data is retrieved.
How - Define contradiction rules that specify conditions under which default filters should be ignored. Use these rules to refine queries dynamically based on the presence of specific criteria, such as status or is closed.

Use Contains Ignore Case for Name Matching

What - Incorporate contains ignore case logic for matching person names in queries to accommodate variations and partial matches.
Why - This approach ensures that searches for names are flexible and can handle cases where only a part of the name is provided, improving user experience and query accuracy.
How - Implement the logic to use contains ignore case for the person MSO name field. This should be set as the default behavior, but allow modifications if needed.

Ensure Consistent Alias Naming

What - Ensure that alias names used in queries are consistent and correctly mapped to the entities they represent.
Why - Consistent alias naming prevents query errors and ensures clarity in query logic, reducing the risk of using incorrect or undefined aliases.
How - Review query generation logic to verify alias mappings. Cross-check alias names with table definitions and ensure they are correctly defined. Debug and fix any alias-related issues identified during query execution.

Simplify Queries by Avoiding Redundant Filters

What - Avoid adding redundant filters or criteria in data queries and leverage simple solutions where possible.
Why - Overcomplicating queries with unnecessary filters can lead to inefficiencies and potential errors, whereas simple solutions are more robust and easier to manage.
How - Review existing query criteria and remove any that are redundant or covered by other logic. Simplify logic to handle common cases and use prompts to handle exceptions. Instead of adding multiple filters for closed cases, use a single prompt to manage exceptions.

Handle Null Values in SQL Queries

What - When returning single columns from a query, ensure thatnull valuesare filtered out to maintain data integrity.
Why - Filtering out null values prevents incorrect data interpretations and ensures the accuracy of query results.
How - Use ontology-level prompts to filter out null values when a single column is returned. Apply `IS NOT NULL` conditions in the semantic SQL for specific properties. Test scenarios where null values might occur to ensure filters are applied correctly.

Standardize Query Prompts for Consistency

What - Implement standardized query prompts to ensure consistent responses from the system, especially when dealing with complex or similar terminologies.
Why - To avoid inconsistencies and ensure that queries return predictable and accurate results, particularly important in environments with overlapping terminologies.
How - Define common prompt structures for recurring queries. Use synonyms and synonym bags to capture all possible variations of a term. Regularly update and sync the ontology to include the most recent changes.

Using Prompts to Override Default Criteria

What - Implement prompts to override default criteria when specific conditions are met, such as when a user query specifies a status.
Why - Prompts allow for more flexible and dynamic query building, ensuring that user intent is accurately captured without default criteria interfering.
How - Define prompts that can detect when a query specifies a particular condition (e.g., a status). Ensure the prompt logic is clear and includes all potential variants of the specified condition.

Implement Distinct to Avoid Duplicates

What - When performing self-joins or similar operations, use `DISTINCT` to avoid duplicate entries in query results.
Why - Avoiding duplicates ensures cleaner, more accurate datasets and prevents potential downstream errors in data processing or analysis.
How - Review the query logic to identify potential points of duplication. Integrate the `DISTINCT` keyword in the SQL query to filter out duplicates. Test the query to ensure that it returns the expected results without duplicates.

Set Up Clean Test Environments

What - Set up a new environment with a clean database and Elasticsearch to ensure tests are conducted without legacy issues.
Why - A clean environment helps in isolating issues specific to new code changes and prevents legacy data or configurations from affecting test results.
How - Establish a separate environment for major testing phases. Ensure databases and other services like Elasticsearch are reset to a known state. Use this environment to reproduce issues that cannot be replicated in the current setup.

Ensure Consistent Alias Naming in SQL Queries

What - Maintain consistent alias naming conventions in SQL queries to prevent errors related to undefined or incorrect aliases.
Why - Inconsistent aliasing can lead to query failures and debugging complexities, whereas consistent naming improves readability and maintainability.
How - Establish a naming convention for query aliases. Ensure all queries are reviewed for alias consistency before deployment.

Use MSO Level for Modifications

What - Modify existing configurations at the MSO level instead of the property level when possible.
Why - This approach ensures consistency and reduces redundancy across different properties, simplifying maintenance and updates.
How - Identify the MSO level configurations. Implement changes directly at this level. Test to ensure changes propagate correctly and do not cause unintended effects.

Use SQL Prompting for Intelligent Queries

What - Utilize SQL prompting techniques to automate query generation based on known scenarios and data conditions.
Why - Automating query generation reduces manual errors, speeds up the data retrieval process, and ensures consistency in query results.
How - Define common query patterns and conditions as prompts. Implement logic to handle null values and retrieve alternative data (e.g., parent data). Test prompts to ensure they generate the correct SQL.

Section: Problem-Solving

Using Stop Words for Query Precision

What - Add frequently misinterpreted terms as stop words to prevent them from affecting query results adversely.
Why - Stop words can prevent unintended matches in queries, ensuring that the query results are precise and relevant.
How - Identify terms that are frequently misinterpreted in queries. Add these terms to the stop word list in the system configuration. Test the queries to ensure that the addition of stop words improves results.

Consistency in Query Execution

What - Address inconsistencies in query execution between local and server environments.
Why - Ensuring consistent query execution across environments is crucial for reliable system performance and accurate data retrieval.
How - Test queries in both local and server environments to identify discrepancies. Investigate recent changes in ontology or code that might affect query behavior. Raise and track issues for persistent inconsistencies.

Enable Debugging Tools for Problem Resolution

What - Use debugging settings and tools to trace and resolve issues effectively within the application.
Why - Debugging tools provide visibility into the application's internal processes, making it easier to identify and fix issues.
How - Enable debugging settings in the application or environment. Use logs to track SQL queries and other operations. Analyze logs to identify where and why issues occur.

Section: Communication

Thorough Documentation Practices

What - Maintaining comprehensive and up-to-date documentation for all processes and queries.
Why - Facilitates knowledge sharing, onboarding, and reduces the time spent on rediscovering information or solving previously encountered issues.
How - Document all processes, including commands and queries used. Regularly update documentation to reflect changes in processes or environments. Encourage team members to contribute to and review documentation regularly.

Document Query Feedback for Continuous Improvement

What - Implement a feedback loop where queries and their issues are documented and used to improve the system's response mechanisms.
Why - Continuous documentation and feedback help in identifying recurring issues and areas for improvement, enhancing the system's overall performance.
How - Collect and document all query feedback in a centralized system. Regularly review the feedback to identify patterns or frequent issues. Use insights to update prompts, synonyms, and the ontology.

Section: Quality

Testing and Monitoring Query Behavior

What - Consistently test and monitor queries to ensure they return expected results, especially after changes.
Why - Regular testing helps identify issues early, ensuring queries return consistent and accurate results.
How - Repeatedly test queries under different conditions to identify inconsistencies. Monitor query results and log any anomalies for further investigation. Use tools to debug and analyze query execution paths.

Section: Process

Use of Ontology Level Prompts

What - Incorporate ontology-level prompts to manage specific query behaviors, such as null value handling.
Why - Using ontology-level prompts allows for more granular control over data queries, improving data accuracy and system reliability.
How - Implement prompts in the ontology to manage specific data conditions. Ensure prompts are configured correctly in the admin table and tested for different scenarios.

Use Synonyms for Improved Query Handling

What - Incorporate synonyms in the ontology to handle different ways users might phrase similar queries, thus enhancing the system's ability to understand and respond accurately.
Why - Users may use different terminologies for the same concept, and synonyms help in capturing the intent accurately, reducing errors in query responses.
How - Identify common terms and their variations used in queries. Add these as synonyms in the ontology. Regularly review and update synonyms based on user feedback and query logs.

Effective Bug Reporting and Tracking

What - Create clear and detailed bug reports that specify the issue and provide context, such as when and where the issue occurs.
Why - Clear bug reports help in the efficient resolution of issues and prevent miscommunication among team members.
How - Specify the exact issue, including any error messages or incorrect behavior observed. Provide steps to reproduce the issue if possible. Mention any related issues or previous fixes that might be relevant.

Contact App Orchid | Disclaimer