Data model instructions

Data model instructions let you define global rules that guide how Spotter interprets and answers questions on a data model.

These instructions apply broadly across queries and users, helping Spotter consistently handle default behavior, ambiguity, and recurring data nuances.

See Data model instructions in action.

What are data model instructions?

The data model instructions feature allows you to provide the Spotter system with global rules that it should follow across all relevant queries. Unlike Spotter context, which is tied to a specific reference question, a data model instruction is a standalone directive designed to teach the system a core concept, a default behavior, or a specific data nuance.

These instructions are globally applicable and influence all queries made by any user on the data model, unlike other coaching methods that may also apply at user-level.

Create data model instructions

You can create data model instructions either during a conversation or directly on the data model.

Give instructions in Spotter

To give instructions in Spotter, follow these steps:

  1. Open Spotter and ask a question. For example, you could say, “Show me the sales for the last month.”

  2. Let’s say your company defines “last month” as the last 30 days. If Spotter answers your question with the date filter “last month,” you can add context to correct its answer.

  3. Click the caret next to the name of the data source in the search bar and select Data model instructions.

    Select caret.
    Select Data model instructions

  4. In the text box that appears, type your instruction. For example, you could say, “When I ask for last month, use ‘last 30 days’ as a filter.”

  5. Click Save.

  6. When the pop-up closes, Spotter displays an acknowledgement that Instructions have been updated. Click Regenerate last answer to see the updated answer to your question and verify that Spotter has understood your instructions.

Give instructions on a Model

To give instructions on a Model, follow these steps:

  1. Open the Data workspace and select your Model. You must have edit access to the Model to add instructions.

  2. Click the Instructions tab.

  3. In the text box, type your instruction. For example, you could say, “When I ask for last month, use ‘last 30 days’ as a filter.”

  4. Click Save changes.

Best practices for writing instructions

Be specific and direct

Write your instruction as a clear command to ensure the system applies your rule correctly and predictably. For example, "Exclude all sales from 'Internal Test' accounts" is better than "I don’t usually want to see our internal test accounts in reports."

In many cases, using preferential language like "Prefer A over B" can be more effective than a hard command like "Use A".

Group instructions by concept

Instead of creating many separate instructions for small, related rules, it is better to group them. Focus on teaching all the logic related to a particular business concept in a single, well-structured instruction. This helps the system understand the full context and know which rules to apply when a user’s query mentions that concept.

Match your data’s language

Write instructions using the exact names for columns and the precise values stored in your data. This removes guesswork for the system and leads to more predictable results.

Example

Instead of a generic (less effective) instruction: "Exclude canceled orders when calculating total revenue", use a more precise (more effective) instruction: "Exclude orders where order_status = 'CANCELLED-USER' when calculating total revenue".

Scope and access

To add or manage data model instructions, you must have data model editing access.

Data model instructions apply at the Model level and affect all users querying the Model.

Because these instructions influence many queries, they should be written carefully and reviewed for accuracy and consistency.

Limitations and key considerations

No automatic override behavior

A data model instruction does not automatically override a user’s direct query if they conflict. Instead, both the user’s query and the instruction are sent to the Model, which can lead to unpredictable results or confusing answers. This makes writing clear, specific instructions critical.

Not recommended for mathematical formulas

Data model instructions are not well-suited for teaching the system mathematical formulas or complex calculations. For these scenarios, we recommend other coaching methods, such as providing a reference question with natural language context.

Avoid conflicting coaching

The instructions you provide must be coherent with each other and with reference questions and business terms. Contradictory information will confuse the model and lead to unpredictable results.

Unsupported capabilities

To set clear expectations, please note that several advanced “agentic” behaviors are not currently supported by data model instructions. These include:

  • Enforcing specific chart types or visualizations.

  • Prompting the user with follow-up questions.

  • Defining conditional query logic (for example, “if the first query returns no data, run a second query”).

  • Question deflection (preventing the system from answering certain questions).

Was this page helpful?
×