Optimizing data for AI

IBM watsonx BI is a powerful analytics tool that uses large language models (LLMs) to run complex, multi-step BI queries on your data. While watsonx BI has contextual understanding of data and can quickly respond to your questions, the quality of data determines the quality of the generated responses.

What LLM uses to understand your data and questions

To enhance the quality of the generated query and the final answer, it is important to provide clear and comprehensive context to the LLM.

The following factors are used by the LLM to understand questions and the context of your data when it generates query statements:

  1. Column semantics

    • Descriptive names and business definitions

    • Data types and expected value ranges

    • Sample values for disambiguation

  2. Relationship intelligence

    • Join paths between tables

    • Cardinality and referential integrity

    • Conditional join logic

  3. Calculation logic

    • Metric formulas and dependencies

    • Aggregation rules (SUM, AVG, COUNT DISTINCT)

    • Time-based calculations and period comparisons

  4. Operational semantics

    • Default filters and scoping rules

    • Required column combinations

    • Business-specific terminology mappings

  5. AI instructions

    • Custom guidance for ambiguous scenarios

    • Organizational reporting standards

    • Domain-specific interpretation rules

Here are some things that you can do to prepare your data for use by AI.

Create a variety of metrics

Define a variety of metrics and ground answers in these standardized metric definitions for accuracy and consistency. IBM watsonx BI uses metrics and the underlying enriched metadata that is used to define metrics, to answer your questions and provide insights.

Use unique names for data assets

To avoid ambiguity and confusion, use unique and descriptive names for data assets, including metrics.

Each asset and column needs a display name and description

You can review the metadata enrichment results and make necessary changes to display names and descriptions if:

  • You use Watsonx BI on IBM Software Hub
  • You use watsonx.data intelligence in watsonx BI as a Service for metadata enrichment

A similar review page is not available in watsonx BI as a Service if you use using watsonx BI's native enrichment.

You can also access the metadata enrichment from the Project asset tab by selecting the relevant metadata enrichment asset.

You can accept the AI-suggested name and description or click Edit to add your own.

Metadata enrichment review page
Metadata enrichment review page displays the AI generated terms and assignments.

When you edit the Display name or Description in the metadata enrichment asset, the updates might get overwritten if enrichment is rerun or if a metric definition is deleted or edited. To avoid this issue, make your changes in the semantic data model instead.

When the confidence score of an AI-suggested name or description does not exceed the minimum threshold, the corresponding cell is blank. In that case, click the pencil icon next to the suggestion and provide a meaningful name or description for that asset or column.

Descriptions must be concise and reflect the purpose of the column. During query generation in a conversation, the AI uses both the identifier, name, and description (potentially with sampled data) to select the best columns to answer the question. Avoid repetitive descriptions, where every description includes the same text, especially when the repeated content is how users frequently ask questions.

Model data in the semantic model to help query generation

Add clear column identifiers

To help the LLM understand the table schema correctly and easily, make sure that the column identifiers are unique and clearly worded.

Identifiers identify objects and are used to generate SQL queries in expressions.

Column identifiers need to be worded in a way that aligns with how users are likely to ask questions.

For example, if an asset is about product sales or revenue, the column identifier SALES_YEAR/SALES_DATE would work better than CURRENT_YEAR/CURRENT_DATE, as it describes what the temporal columns represent. Similarly, if the asset is about sales target, use column identifiers such as SALES_TARGET_YEAR/SALES_TARGET_DATE.

However, when multiple fact metrics come into play (for example, revenue + planned revenue in a single metric definition with a shared time dimension), having more general temporal column identifiers might be beneficial.

To change the column identifier in a metric definition:

  1. On the Data and Metrics tab, open the semantic data model that has the metric definition you want to edit.

  2. Click Advanced mode on the Metrics overview page.

    Navigating to advanced mode from Metrics overview

  3. Under the metric definition, select the column that you want to add the identifier to.

  4. Open its Properties tab and enter the value in the Identifier field,

    An identifier's first character must be a letter or an underscore. Subsequent characters can be letters, numbers, or underscores, without spaces.

  5. Under Actions, click Save to save the semantic data model.

  6. Select the metric definition that you changed and click Export metric definition. Exporting the metric definition runs metadata enrichment again and updates the existing metric, making it available for use in conversations.

Add column labels and descriptions

Make sure that a meaningful label and description is available for metric columns in the semantic data model. The order of priority for the label and description when used in a conversation is as follows:

  1. User defined in the semantic data model

  2. User defined in the metadata enrichment asset

  3. AI-suggested or generated in the metadata enrichment asset

Write the label and description that uses your business context and the language that your users use when they ask questions.

Descriptions need to be 512 characters or less to help ensure a balance between accuracy and effectiveness.

Include values in the description to specify time periods

For example, if months are represented as Jan, Feb, Mar in your data, include that in the description. “Month values are abbreviated as Jan, Feb, Mar....

If values follow a known standard, mention the standard name in the description

For example, “Country codes follow ISO 3166 standard” or “Currency codes use ISO 4217”.

Reflect user language preferences

For example, if there is a column that is called Manager, but your business users use the word Boss, then reflect that in the description.

If you want AI to use Cost of goods sold column to answer questions about Cost breakdown, then add that phrase to the description of the column.

To add column labels and descriptions in the semantic data model, follow these steps:

  1. Open the semantic data model that contains the metric definition from the Data and Metrics tab.

  2. Click the Advanced mode.

  3. Under the metric definition, select the column.

  4. On the Properties tab, enter the label and description.

  5. Under Actions, click Save to save the semantic data model.

  6. Select the updated metric definition and click Export metric definition.

Review column “Usage”, “Aggregate” and “Nullable” fields

In the semantic data model, check the column properties to ensure that the Usage, Aggregate, and Supports NULL values fields for each column are correct.

  • Usage: This property applies to tables and controls how the query engine understands and processes the table, and its child objects, in a query.

  • Aggregate: This property applies to columns, and defines the type of aggregation that is applied to a summary column.

  • Supports NULL values: Specifies whether a column supports null values. By default, this property value is inherited from the source. You can change this value.

For example, for a numerical column that is called Revenue, the Usage field must be Measure, rather than Attribute. If the sum of the revenue is commonly used in a question, the default Aggregate should be Total, rather than Average.

Sometimes data such as “unit_cost” or “unit_sale_price” is treated like a Measure. However, these are attributes of a product.

Check values in column properties
An open Properties panel displays the usage, aggregate, and null value fields.

Add instructions and context for AI

Use the AI instructions and context field to provide instructions and context that the LLM follows when it interprets and answers questions about a specific metric. This field helps standardize complex business logic and reduce ambiguity.

To add or modify instructions for a metric:

  1. Open the metric’s menu in Advanced mode and select Edit metric definition.

  2. Go to the Details tab.

  3. Enter or update your plain text instructions directly in the AI instructions and context field.

  4. Save the semantic data model.

  5. From the metric's menu, select Export metric definition to apply the instructions to the metric in the project.

This field supports plain text and a maximum of 10,000 characters. You can also add your instructions in Markdown though plain text is preferred for clarity.

How AI instructions are used

The instructions that you provide, apply to only the metric where the instructions are defined. Use AI instructions in scenarios where consistent interpretation depends on rules, such as when:

  • Your dataset uses business‑specific terminology that differs from column names

  • You use standard calculation methods or rules, such as weighted averages or variance formulas

  • Certain columns must always appear together for context

  • You rely on default filters or display preferences

  • You need to enforce organizational reporting standards, such as fiscal or seasonal time logic

When you ask a question about a metric that has instructions, watsonx BI notifies the LLM that the metric has custom rules and applies the rules during interpretation.

Watsonx BI produces an SQL that aligns with expected patterns and validated behaviors.

Best practices for AI instructions

The instructions that you provide in watsonx BI are for AI systems, not humans. Prioritize directness and conciseness over grammar.

Best practices for writing AI instructions
Best practice Details
Enter context-specific instructions only Enter instructions or helpful context directly into the field without an introduction.

Avoid: Follow these rules or These are instructions you must follow for every question.
Define the exact behavior and avoid vague directions Tip: To reference columns, remember to use the column identifier.

Use: Always include retailer_city and retailer_type_en.

Avoid: Include relevant columns.
Use consistent terminology For example, if you choose a term such as current, use it consistently throughout the instructions.
Avoid conflicting rules Ensure that the instructions do not contradict each other. Review them together for alignment.
Don’t assume prior knowledge and define all required formulas and logic explicitly Use: Calculate the margin as (Total Gross Profit / Total Revenue) × 100.

Avoid: Use the standard margin calculation.

Examples of AI instructions

Calendar or season logic
Treat "current year" as the latest CalendarYear available in the data.

Interpret seasons as:
Winter = December, January, February
Spring = March, April, May
Summer = June, July, August
Fall = September, October, November

Use these definitions when users reference seasons.

Fiscal year interpretation

The fiscal year starts in April and ends in March of the following calendar year.
When users reference a fiscal year (for example, FY2023), interpret it as April 2022–March 2023.

Monthly headcount metric

This table contains monthly headcount. Treat each month independently.

Without date filters:
Return SUM(headcount)
WHERE month_end_date = MAX(month_end_date)

For a specific month and year (for example, January 2025):
Return SUM(headcount)
WHERE EXTRACT(month FROM month_end_date) = 1
AND EXTRACT(year FROM month_end_date) = 2025

For more examples, see Adding instructions and context for AI.

Remove unnecessary columns from the data

Remove columns from metric definitions that might not be useful in answering questions by deleting them or hiding them from the base table or metric definition.

For example, if a metric definition contains both COMPANY_KEY and COMPANY_ID columns, the AI might have difficulty deciding which one to choose when generating the query. If a business user is likely to only ask for COMPANY_ID, remove the COMPANY_KEY column from the metric definition or hide it. Any columns that you hide, appear in gray, and are moved to the end of the semantic model panel.

If you have multiple language-specific versions of the same column, such as the PRODUCT_TYPE_ columns in the following example, you can create a new unified PRODUCT_TYPE column with an expression that can automatically pick the appropriate language-specific version, and hide the other redundant PRODUCT_TYPE_ columns.

Edit calculation to create a unified column
A calculations displays in the Expression editor.

Ensure data quality

Ensure that column values are correct and relevant.

Sampled column values are used by the LLM to construct well-formed filters. When you ask a question, watsonx BI’s NER step extracts filter values from the question, converts them into embeddings, and compares the filter embeddings with the columns’ sampled embeddings that are stored in Cloud Object Storage (COS). The matched sampled columns feed in to the prompt to help the LLM craft appropriate filter expressions, which are used in the WHERE clause of the final query statement.

For example, if a metric definition contains a MONTH_NAME column, the sampled values from that column should only contain valid month names.

Use column expressions for abstracting complex logic

Use column expressions for calculations or transformations that encapsulate complex logic.

You can create column expressions in the semantic data model. Select a column and in the column properties, click the View or edit link in the Expression field. Add the necessary logic for this column to the Expression editor. Here is an example of an expression for the EXECUTIVE_INDICATOR column, which is a binary Y or N value that determined by the corresponding value in the BAND column.

Creating a column expression
The View or edit link displays in the Expression field

Let’s say, you have a Status column with multiple cell values like Todo, In progress, Reviewing, Icebox, and Done. Your organization defines an open state as a status that is not in Done or Icebox. You can create a calculation column that is called Is_open and create an expression that returns Y/N based on the value from Status column, making it easier for the LLM understand the logic.

Column expression
A column expression displays in the Expression editor

Give your expressions column identifiers that map to how your users will reference the data. For example, the Is_open expression we created, is a good name if this is how users refer to open or closed items. However, if users generally refer to items as active or inactive items then Is_active would be a better name.

Use column expressions to filter data

Use column expressions to filter out unnecessary data from the metric definition before exporting it to create or update a metric.

Filter applied to a table
Semantic model panel shows a table with a filter applied to it.

For example, if a table includes product names in all languages and you only want the English names, you can add a filter to the table and apply it on the “product_language” column to filter out unnecessary values.

Applying a filter through an expression
A filter displays in the Expression editor.