AI Assistant Best Practices

The GoodData AI Assistant helps you explore and understand your data through natural language. It can generate insights, visualizations, and metrics automatically, but the quality of its responses depends on how well your semantic model is structured and how clearly you guide its behavior.

This guide explains how to prepare your workspace, name and describe data objects, and use AI Memory effectively so that the Assistant always provides accurate, relevant, and consistent results.

Use Clear Naming Conventions

Clear and descriptive names help the Assistant understand what each metric, attribute, or fact represents and choose the correct one when responding.

When using abbreviations, include their full meaning in the description so the Assistant can interpret them correctly.

Tips

• Use names that clearly describe each object’s meaning and purpose.
• When using abbreviations that are not standard, explain them in the description. Example: If a metric is called CLV, include “Customer Lifetime Value” in the description.
• Keep names distinct to help the Assistant select the correct object.
• Use the Semantic Quality Agent to detect unclear or confusing object names.

Use Descriptions and Synonyms Wisely

Descriptions and synonyms help the Assistant understand relationships and use data objects correctly.

If you use acronyms in object titles, spell them out in the description and explain the object’s purpose. Each description should be unique—avoid copying text between objects.

Tips

• Write clear, detailed descriptions that explain what the object measures.
• Add synonyms in the object’s description or define them in AI Memory.

Example: If your attribute title is Client Name, add synonyms such as Customer Name and Account Holder.

See [AI Memory] to learn more about defining synonyms.

Set the Right Default Attribute Labels

Attributes can have multiple labels, such as Customer ID or Customer Name. The default label determines which value appears in responses and visualizations.

If you want the Assistant to use friendly, human-readable values, set the name label as the default. This makes responses easier to read and understand.

Use AI Memory to Guide Behavior

[AI Memory] lets you define reusable patterns and business rules that guide how the Assistant responds. You can use it to set tone, default logic, and contextual behavior.

There are two types of AI Memory instructions: Always-On Instructions and Conditional Instructions.

Always-On Instructions

Always-on instructions apply to all responses, regardless of the user’s query. They are useful for defining tone, persona, and default behavior.

Examples

• Use a friendly tone.
• Respond as a financial analyst.
• If no date is provided as a filter, use the last 30 days.

Conditional Instructions

Conditional instructions apply only when certain conditions are met. They use simple “if–then” logic to make sure the Assistant behaves correctly in specific contexts.

Examples

• If the user asks about revenue, include both total and net revenue. Without this instruction, the Assistant might select only one.
• If the region is Europe, use West and South as filter values. This helps as attribute values are currently not visible to the Assistant.
• If the user asks about orders but does not specify a date, use Processed Date. This ensures consistent date handling.

Good practices

• Write clear, simple conditions that the Assistant can follow easily.
• Use conditional logic to define business-specific rules.

Don’t do examples

• When using the current version of the AI Assistant, do not rely on it to accurately differentiate between similar metrics. Provide clear instructions so it can tell them apart.
• In the current version, the AI Assistant supports only exact attribute filtering. It cannot yet recognize similar or partial values. Don’t expect it to infer attribute values automatically. For now, add low-cardinality attributes to AI Memory to help it apply filters correctly.

Troubleshooting Tips for Better Responses

If your question does not produce the expected result, check the following areas to improve outcomes.

The Assistant Doesn’t Find the Right Object

• Verify that the relevant metric, attribute, fact, or date exists in your workspace.
• Check that its title and description are clear.
• Confirm that facts support the correct aggregations (SUM, AVG, MIN, MAX).
• If a numeric attribute should be aggregated, convert it to a fact.
• If renaming does not help, use AI Memory to guide the Assistant’s choice.
• If the object is missing, add it to your Logical Data Model (LDM) or create a new metric.

The Assistant Struggles with Complex or Custom Logic

• Check whether a predefined metric already exists.
• If not, create one and describe its logic clearly.
• Add AI Memory instructions explaining when and how to use it.

See Create Metrics for more details on building metrics.

The Assistant Uses the Wrong Date

If results seem incorrect, check which date attribute was used. When multiple dates exist (for example Created Date and Processed Date), specify which one should apply, or set a default in AI Memory.

Example: When asked about orders, use Processed Date by default.

Filters Don’t Work as Expected

The Assistant requires exact matches for attribute names and values, including capitalization.

Example: Filter by region: West, East

To simplify common filters, create metrics with filters embedded or use AI Memory to apply them automatically.

The Assistant Selects the Wrong Object

If the Assistant picks the wrong object or prompts you to choose, similar names or descriptions are likely the cause.

• Use unique, descriptive names for each object.
• Write distinct descriptions.
• Hide technical objects from AI with the Hide from AI property.
• Use AI Memory to set preferences.

Example: When a user asks about revenue, prefer Total Revenue (Net) unless they mention gross.

The Assistant Doesn’t Understand Free-Text Queries

The Assistant cannot interpret broad business terms like “valuable” or “priority” unless they are defined.

• Create explicit metrics such as Customer Lifetime Value, Churn Risk, or NPS.
• Add clear descriptions and synonyms that match business language.
• Use AI Memory instructions that map phrases to specific metrics.

Example: If the user asks about the most valuable customers, use the Customer Lifetime Value metric.

The Assistant Loses Context

The Assistant remembers context within the same workspace session, but context may be lost in long or topic-changing conversations.

• Start a new conversation when the topic changes by clicking Reset.
• Encourage users to refer to specific metrics rather than using vague references.
• Begin a new chat for new subjects.

Example: Show me Profit again, broken down by Region.

Build a Strong Semantic Model

A well-designed Logical Data Model (LDM) ensures consistent and accurate responses.

Align the model with business questions. Design the LDM based on the questions users need to answer. For complex setups, involve experienced modelers.

Use supported data types. Ensure that columns use supported JDBC types and that primary and foreign keys have matching data types.

Follow naming conventions. Use prefixes such as gr__ for primary keys, f__ for facts, and ls__ for labels to help GoodData interpret tables correctly.

Model facts and attributes properly. Store facts at the lowest level of detail. Avoid storing ratios or percentages directly; calculate them as metrics. Create dimension tables for reusable entities such as customers or products.

Set up relationships carefully. Define relationships clearly and use bridge tables for many-to-many links. Apply allocation factors to prevent double counting.

Avoid ambiguous paths. Ensure there is only one valid path between datasets.

Keep names and data types stable. Avoid renaming or changing data types after your model is in production.

Use aggregate awareness best practices. Align dataset granularity with your analytical needs. Use clear naming for aggregated data and avoid defining attributes directly in fact datasets if using aggregate awareness.

See Model Data and Aggregate Awareness to learn more.

Create Metrics That Support Business Questions

Metrics determine how users analyze data and how the Assistant responds.

Tips

• Use raw facts instead of pre-calculated values. Example: Store Unit Price and Units Sold, and calculate Total Revenue as a metric.
• Use MAQL for flexible and reusable metrics.
• Design metrics for reuse across dashboards.
• Keep measurement units consistent.
• Ensure all facts in a fact table share the same level of detail.
• Use IFNULL only when needed to handle missing values.
• Give each metric a clear name and description.
• Test metrics in different visualizations to confirm accuracy.
• Edit carefully, since changes to a metric affect all dashboards using it. Save a copy if needed.

See Create Metrics and MAQL Reference to learn more.

Help the Assistant Understand Business Language

Teach the Assistant how your organization defines key terms.

When users ask questions such as “Which customers are most valuable?”, the Assistant can only answer correctly if Customer Lifetime Value exists and is linked properly.

Create clear metrics for common business concepts, describe them thoroughly, and include synonyms that reflect how users speak. Use AI Memory to connect business terms to metrics and attributes.

Encourage Clear and Intent-Based Questions

Encourage users to ask complete and specific questions that include metrics, filters, and time frames.

Examples

• Instead of “How are we doing?”, say “Show me Net Revenue by Region for Q3.”
• Use clear, natural language with specific intent.
• When switching topics, start a new conversation to maintain context.

See AI Assistant Overview to learn more.