What are Example Queries?

Example queries in Locusive serve as predefined questions and SQL queries that help guide the system to access and interact with your database efficiently. They are one of the most powerful tools you can use to ensure that Locusive produces accurate and relevant results when handling user requests.

Structure of an Example Query

Each example query has three main fields:

1. Question: The natural language question that users might ask, such as "What are the total sales for last month?"
2. Description (Optional): A short explanation providing context for the query. This can help clarify the intent, especially for complex questions or edge cases.
3. SQL Query: The SQL statement that retrieves the relevant data from your database. This is what Locusive will use to form the correct database query based on the user's request.

By setting up example queries, you're giving Locusive a head start on how to best approach common questions, enabling faster and more accurate responses. Example queries can also be set as templates.

What are SQL Templates?

SQL Templates are a special type of example query that will be run verbatim, save for any included placeholders wrapped in {{double curly braces}}. These placeholders allow the query to be dynamically tailored based on the user's input. If Locusive identifies that a template is the best match for a user's question, it will replace the placeholders with contextually appropriate values before executing the SQL statement.

For instance:

• Question: "Show sales by region"

SELECT region, SUM(sales) 
FROM sales_data 
WHERE sale_date BETWEEN '{{start_date}}' AND '{{end_date}}' 
GROUP BY region;

In this example, {{start_date}} and {{end_date}} are placeholders that Locusive will replace based on the user's request.

Why Use Example Queries and SQL Templates?

Faster and More Accurate Results

When Locusive uses an example query or SQL template to fulfill a request, it can skip a lot of the reasoning and interpretation that is usually necessary to understand how to query your database. This means that example queries and templates are the fastest way to get accurate results.

• Example Queries: Provide pre-built SQL statements that Locusive can use as a reference when constructing its own queries.
• SQL Templates: Take this a step further, offering fully executable SQL code that only requires specific values to be filled in before running.

SQL Templates Provide Superior Accuracy

While both example queries and SQL templates are useful, templates are often the preferred choice for two key reasons:

1. Verbatim Execution: SQL templates run the SQL code exactly as provided (after placeholders are replaced), avoiding any potential misinterpretation by the LLM. This can ensure that queries are consistent and meet your specific needs every time.
2. Controlled Logic: Since the template's SQL is provided by the original person setting it up (rather than dynamically generated by an AI), there is greater control over the logic and structure of the query, resulting in more predictable and correct results.
   
   

Best Practices for Creating Example Queries & SQL Templates

1. Identify Common Questions
   Consider the most frequent or important questions your users are likely to ask. These are great candidates for example queries. For instance:

   • "What are the top-selling products this quarter?"
   • "How many new customers did we acquire last month?"

2. Use Placeholders Effectively
   For templates, use {{double curly braces}} to identify parts of the query that might change based on the user's request. Ensure the placeholders are descriptive enough for Locusive to determine the correct replacements (e.g., {{customer_id}} or {{start_date}}).

3. Provide Clear Descriptions
   While optional, including a description can help the system understand the intent behind the example query, particularly if it’s complex or might be misinterpreted.

4. Optimize for Templates When Possible
   If you have a standard way of querying your database for a particular question, set it up as a template. Because the SQL will be run verbatim (with placeholders replaced), you’ll benefit from faster, more accurate, and more consistent results.
   

5. Provide a Wide Variety:
   The more templates and queries that our system has to reference, the more accurate your database queries will be. Provide as many examples as you can and Locusive will automatically select the most relevant ones for any given request.
   
   

How to Set Up an Example Query or SQL Template

​

1. Navigate to Integrations
   In your Locusive dashboard, go to the Integrations page, and select the database or data source you want to create an example query for.

2. Create a New Example Query
   Under the Example Queries section, click Add New Query. Fill in the fields for Question, (Optional) Description, and SQL Query.

3. Configure as a Template (Optional)
   If the query can be run directly by replacing placeholders with user-specific values, mark it as a Template and ensure all placeholders are wrapped in {{double curly braces}}.

4. Save and Test
   Save the example query or template, and test it by submitting a relevant request through Locusive to confirm that the query produces the desired results.

Conclusion

Example queries and SQL templates are powerful ways to enhance Locusive's performance by providing predefined logic and context for handling your users’ requests. They not only improve the speed of responses but also provide more precise answers by leveraging pre-built queries that reflect your specific data structure. Where possible, use SQL templates to achieve the best accuracy and efficiency, ensuring your users get the most value out of Locusive.