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.

    Spotter answer showing a filter for order date = last month.

  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.”

    Data model instructions displaying "When I say 'last month'

  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.

    Regenerate last answer.

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.”

    Instructions in a Model

  4. Click Save changes.

Key use cases

Data model instructions are a versatile tool for shaping how the system interprets queries and presents answers. The primary use cases are:

Data filtering and refinement

Apply automatic filters to ensure analyses are consistent and accurate. This can be broken down into two main types:

Applying conditional filters

Teach Spotter to apply different logic based on the user’s query.

Example

To use different fulfillment centers based on the product line, you can instruct: "For queries about 'Electronics' sales, filter for Fulfillment_Center = 'FC-West'. For 'Apparel' sales, filter for Fulfillment_Center = 'FC-East'".

Applying default filters

Set up a rule that always applies a filter to clean up data.

Example

To ensure internal test data is always excluded from revenue analysis, you can instruct: "When calculating revenue, always exclude transactions where Account_Type = 'Internal Test'".

Column selection and prioritization

Guide the system to use the correct columns for analysis, filtering, or aggregations.

Example

If a query for "market" could ambiguously use a City or Canvas Market column, you can direct the system with: "Prefer Canvas Market column over City column for filtering market values".

Example

To ensure counts are always accurate, you can specify the column to use for counting: "For counting customers, always use the unique count of ‘Customer Cred ID’".

Answer enrichment

Automatically add more detail to answers to make them more comprehensive without requiring the user to ask for every column explicitly.

Example

If a user asks for basic provider information, you can enrich the answer with more detail using the instruction: "Provider demographic info is name, address, tax info, class and state code".

Date handling

Manage how the system handles date and time analysis, especially when a user omits a time frame.

Example

To prevent expensive, wide-ranging queries and align with common user preferences, you can set a default time period: "If a query does not specify a time period, apply a default filter for the 'last 30 days'".

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".

Be clear about when the instruction should apply

Every instruction should make it obvious to the system whether it applies to all queries or only in specific situations.

For rules that should always be in effect, use the word 'always' explicitly

For example, "Always apply the filter 'Customer_Type = 'paid' when analyzing customer data on this data model." "Always exclude rows where Account_Name = 'thoughtspot, inc.' from all analysis."

For rules that are situational or should yield to the user’s intent, use "unless" or "if…​ then" language to define the boundary

For example, "Always apply a default filter for 'last 30 days' unless the user specifies a different time period in their query." "For queries about 'Electronics' sales, filter for Fulfillment_Center = 'FC-West'. For 'Apparel' sales, filter for Fulfillment_Center = 'FC-East'."

If you do not specify when the instructions should apply, the system must guess-- and guessing leads to inconsistent behavior across queries.

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. Before adding a new instruction, review your existing instructions, reference questions, and business terms to ensure they tell a consistent story. If two coaching assets define the same concept differently, the system cannot reliably choose between them and results will be unpredictable.

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).

How to validate your instructions

After adding an instruction, it is important to verify that it works as intended and does not interfere with unrelated queries.

  1. Test the target query. If adding instructions from a conversation, click Regenerate last answer to confirm the instruction is being applied to the query you wrote it for. Review the generated answer and verify that the expected filter, column, or behavior is reflected.

  2. Test with unrelated queries. Ask two or three questions that are not related to the instruction and verify the instruction is not incorrectly applied. For example, if you added an instruction to always filter to paid customers, try a query like, "What are the top 5 product categories by revenue?" and confirm the paid customer filter is not being forced onto a query where it does not belong.

  3. Test edge cases. If your instruction uses conditional logic like "unless the user specifies a time period," test both paths: a query without a time period (to confirm the default applies), and a query with an explicit time period (to confirm the exception is upheld).

Was this page helpful?
×