Create a Semantic Enrichment

Before You Create an Enrichment

Consider what type of context you want to provide:

• Are you defining a business term or metric?
• Are you explaining how to calculate something?
• Are you providing data quality guidance for a specific field?
• Are you describing a relationship between objects?
• Are you setting a default filter or condition?

This helps determine the right scope (data space, object, or field) and how to phrase the enrichment statement.

Create an Enrichment

1. Navigate to the Semantic Enrichments list view.
2. Click New Semantic Enrichment.
3. Enter a Name that clearly identifies the enrichment's purpose. Example: "Active Customer Definition" or "Revenue Field Guidance".
4. Select the Scope:
   • Object: Applies to a specific Data Lake Object (DLO) or Data Model Object (DMO). Use for object-specific guidance.
   • Field: Applies to a specific field within an object. Use for field-level interpretation.
5. If you selected Object or Field scope, choose the target object or field from the dropdown.
6. In the Semantic Statement field, write your enrichment in clear, plain language. Be specific about when and how the rule applies. You can write multi-sentence enrichments for complex business rules. Examples:
   • "Active customers are those with status = 'Active' and at least one order in the last 90 days."
   • "Use amount_usd__c for revenue calculations. This field represents deal size in US dollars."
   • "When filtering email_address, always use lowercase comparisons because some legacy data has mixed case values."
   • "High-value opportunities are defined as amount_usd__c greater than $100,000 and stage equals either 'Proposal' or 'Negotiation'. For regional analysis, use region__c field, not the billing address state. Historical high-value opportunities from before 2023 used a different threshold of $50,000 due to inflation adjustments."
7. (Optional) Add Tags to organize related enrichments. Use consistent tags like "revenue," "customer-segmentation," or "data-quality" to make enrichments easier to find and manage later. Tags are for organization only and don't affect which enrichments the agent retrieves.
8. (Optional) Check Critical if this enrichment must always be considered by the agent. Use it for foundational business rules or data quality constraints. Marking too many enrichments as Critical causes context bloat and slows down queries, so use it sparingly.
9. (Optional, but recommended) Add Lookup Summaries to improve semantic enrichment retrieval. These are keywords or phrases that you expect to appear in users' questions. For example, if the semantic statement defines customer lifetime value, add lookup summaries such as "CLV" and "customer lifetime value."
10. Click Save.

Writing Effective Semantic Statements

A semantic statement teaches the agent how to turn a plain-language question into the right query against your data. Every effective statement answers three questions:

• What is the rule? The instruction the agent should follow.
• Why does it exist? The reasoning behind it.
• What happens if it's ignored? The wrong answer you're trying to prevent.

The "why" matters most. A rule with no reasoning gets followed literally and breaks on any question you didn't anticipate. A rule with reasoning lets the agent handle cases you never wrote down. Compare a weak statement that gives only the rule with a strong statement that adds the reasoning and consequence:

• Weak (rule only): "Always filter Status = 'Active'."
• Strong (rule, reasoning, and consequence): "Always filter Status = 'Active' on every query. The table stores both active and archived customer records. Without this filter, results mix in archived customers who are no longer relevant. This applies even when the user asks about one named customer."

Follow these guidelines when you write a statement:

Be specific

Instead of "Use the revenue field," write "Use amount_usd__c for revenue calculations because it represents deal size in US dollars and is consistently populated."

Explain the why

Don't just state a rule—explain the reason. "Filter by status = 'Active' because inactive customers shouldn't appear in reporting."

Use examples

When defining calculations, show the formula or logic. "Customer lifetime value = total_revenue / months_active * average_customer_lifespan_months."

State conditions clearly

If a rule only applies in certain cases, say when. "For opportunity queries, exclude stage = 'Closed Lost' unless explicitly requested."

Avoid jargon

Write in plain language the agent can parse. If you must use domain-specific terms, define them.

Best Practices for Semantic Statements

• One rule per statement. Don't combine unrelated rules. When the agent retrieves a statement, it pulls the whole thing, so a statement that covers five topics adds four irrelevant rules every time one matches.
• Lead with the rule, then explain the why. State the instruction first, then the reasoning, then the consequence of getting it wrong.
• Say what not to do. If two fields or values are easy to confuse, name the wrong one explicitly. "Never use the ship date for revenue questions" is as valuable as naming the right field.
• Spell out values the agent can't guess. The agent sees field names, not the values inside them. List the valid set when it's short and non-obvious.
• Clarify formats and units. If a number is stored as a multiplier, a percentage, or in cents, say so. Otherwise "less than 2x" or "over 50%" gets misread.
• Attach each statement to the narrowest correct target. A rule about one field belongs on that field. A rule spanning several fields belongs on the object. This keeps unrelated questions clean and surfaces the right rule at the right time.
• Use Critical only for rules that apply to almost every question. A Critical statement is always applied. Non-critical statements are pulled in only when the question matches their lookup summaries. Reserve Critical for universal rules and keep the count small.
• Write lookup summaries in the words your users actually type. These are the trigger phrases that surface a non-critical statement. Use real phrasing, synonyms, and abbreviations, not technical descriptions.

Types of Context You Can Add

Semantic statements can capture many kinds of business context. Common types include:

Test Your Enrichment

After creating an enrichment, test it by asking the agent a question that should trigger it. Review the agent's response and check the View More Details section to see if the enrichment was applied correctly. If the agent didn't use the enrichment as expected:

• Make sure the enrichment is Active.
• Check that the scope (data space, object, or field) matches your question.
• Revise the semantic statement to be more specific or add relevant tags.
• If the enrichment is foundational, mark it as Critical.

Next Steps

See Manage Semantic Enrichments to learn how to edit, deactivate, or delete enrichments as your data model evolves.