What are AI Descriptions?
AI Descriptions are semantic metadata that explain a column’s business meaning and analytical role. Oracle Analytics AI Agents use this information to identify the most appropriate columns and calculations to answer analytical questions, interpret data correctly, and generate accurate responses.
In your datasets, typically, a field name alone rarely conveys the complete business meaning of the data. For example:
- Revenue may exclude tax.
- An order identifier may be repeated across multiple order lines.
- A percentage may be stored as 0.15 rather than 15
AI Descriptions allow you to document these important details alongside the data used by Oracle Analytics AI Agents. This additional context helps agents select the correct data, interpret values as intended, and provide more accurate responses.
This post provides some reusable templates for dataset, subject-area, and column descriptions. These AI Descriptions complement Supplemental Instruction templates. Use the AI descriptions to define what the data means, and use supplemental instructions to other use cases like defining the filtering behaviour, and response format required for a specific agent and so on.
Refer Supplemental Instruction Templates for OAC AI Agents for more examples.
Before reviewing the templates, let’s first understand AI Descriptions and how they help Oracle Analytics Cloud AI Agents interpret data accurately.
Where to add AI Descriptions?
- Dataset: open Inspect, select Search, and use AI Descriptions to review or edit the dataset and column descriptions. Save and Use Run Now when you want to start the indexing. Refer Documentation
- Subject area: an administrator can use Console → Search Index → Data Model, with Assistant indexing enabled, to maintain subject-area and column AI Descriptions. OAC also allows you to export and import for maintaining this metadata. Refer Documentation
Note: Importing and Exporting AI Descriptions of Subject Areas
For subject areas, all AI Agent indexing configuration is available in the Console. You can export the indexing configuration for a subject area to an csv file and import it back after making updates.
This approach makes it easier to manage descriptions for Subject Areas as many columns are present in the Subject Areas. After exporting the file, you can review and update descriptions manually or use an AI tool to generate suggested descriptions. Review and refine any generated content as needed, then import the updated file back into the system.
AI Descriptions vs Dataset Descriptions
Dataset Descriptions are different from AI Descriptions.
Dataset Descriptions use AI to help create a high-level description of a dataset. This description helps users understand and communicate the dataset’s purpose, content, and intended use.
AI Descriptions, on the other hand, provide semantic and business context for the dataset and its columns. Oracle Analytics AI Assistant and AI Agents use this context to understand the data, interpret values correctly, select relevant columns, and deliver more accurate responses.
Using LLM to Generate Descriptions
The Generate All feature can automatically generate descriptions for all columns, providing a useful starting point for documentation and agent configuration.
However, users should carefully review and refine the generated descriptions before using them.
To ensure the agent is aligned with its intended purpose and accurately reflects the relevant business context, users should supplement the generated content with organization-specific information. This may include domain terminology, the meaning of labels and values, applicable policies, special definitions, calculation logic, and any other context needed to interpret the data correctly.
Sample Description Templates
We are sharing a selection of templates and completed examples to support more accurate and consistent responses when working with agents. These materials are provided for illustrative and reference purposes only and should be adapted to your organization’s specific data, processes, and business requirements.
The examples are not intended to be exhaustive or prescriptive. Outcomes may vary based on the quality of the data, the context provided, and the way the agents are configured and used. The examples include:
- Metric Definitions
- Coded Categories
- Date/Time Stamps
- Fiscal periods
- IDs/ Identifiers
- Flags
- KPIs
Note: Users should apply appropriate professional judgment and discretion when using these materials.
1. Metric Definitions
Use for amounts or quantities that can be summed across a defined set of records. Specify the row-level detail, units, and exclusions.
Suggested Template
[METRIC] recorded at [GRAIN], expressed in [CURRENCY_OR_UNIT]. Includes [INCLUSIONS] and excludes [EXCLUSIONS]. Additive across [VALID_DIMENSIONS]. [NULL_OR_NEGATIVE_VALUE_MEANING]. [SPECIAL_CASES]
Example:
Net Revenue USD
Recognized sales amount per invoice line, expressed in USD using the approved posting-date exchange rate. Reflects discounts and credit adjustments; excludes tax and freight. Additive across invoice lines and posting periods. Negative values represent credits. If user asks for Sales Amount Including tax and freight use add the values from “Tax USD” and “Freight Charges USD” columns to the “Net Revenue USD” Column.
Note: Detailed descriptions also help distinguish between similarly named columns, such as Revenue, Net Revenue, and Gross Revenue, ensuring that users and AI Agents select and interpret the appropriate column correctly
2. Coded Categories
Use for status, customer segment, product class, or another business classification. Include exact stored codes when labels differ.
Suggested template
[BUSINESS_CLASSIFICATION] of [ENTITY]. Stored values: [CODE = MEANING]. Null means [NULL_MEANING]. Represents [CURRENT_OR_HISTORICAL_STATE]. Distinct from [SIMILAR_FIELD].
Example :
Order Status
Current processing status of the order. N = new, P = processing, C = completed, and X = cancelled. Null means status is unavailable. This field describes order status, not payment status.
3. Date/ Timestamp
Use when several dates describe different business events. State the event, time zone, and meaning of missing values.
Suggested Template
Date or time when [BUSINESS_EVENT] occurred. Stored in [TIME_ZONE] with [PRECISION]. Used for [ANALYSIS_PURPOSE], distinct from [OTHER_DATE_ROLE]. Null means [NULL_MEANING].
Example :
Order Created Timestamp
Timestamp when the order was first accepted, stored in UTC to the second. Used for order-intake trends. It does not represent invoice posting or shipment time. Null means the acceptance timestamp was not captured.
4. Fiscal period
Use for fiscal years, quarters, and periods. Name the calendar and explain whether the fiscal year is named by its starting or ending year.
Suggested Template
Fiscal period derived from [DATE_ROLE] using [CALENDAR]. Fiscal years run [START_TO_END] and are named by [STARTING_OR_ENDING_YEAR]. Stored format: [FORMAT]. Example [VALUE] covers [DATE_RANGE]. [CALENDAR_DEPENDENCY].
Example :
Fiscal Quarter
Fiscal quarter of Posting Date under the Corporate calendar. Fiscal years run June 1 through May 31 and are named by ending year. Labels use “FY2027 Q2” including spaces; that value covers September 1 through November 30, 2026. Use with Fiscal Calendar Name = Corporate.
5. Identifier
Use for order, customer, invoice, or account identifiers. Explain uniqueness, repetition, and how the entity should be counted.
Suggested Template
Identifier for [ENTITY]. Unique at [ENTITY_GRAIN] but repeated at [DATASET_GRAIN]. Use [APPROVED_COUNT_METHOD] to count [ENTITY]. [FORMATTING_OR_JOIN_CAVEAT].
Example :
Order ID
Text identifier for an order, repeated on each order line. Count distinct non-null values to count orders in this dataset. Preserve leading zeros. It is a label, not an amount to sum or average.
6 Flag
Use for yes or no indicators. Explain both values, unknown values, and when the classification applies.
Suggested Template
Indicates whether [CONDITION]. [TRUE_VALUE] = [TRUE_MEANING]; [FALSE_VALUE] = [FALSE_MEANING]; null = [NULL_MEANING]. Defined at [GRAIN_OR_TIME_BASIS].
Example :
Is Test Order
Indicates whether an order was identified as a test transaction when created. Y = test order; N = production order; null = classification unavailable. The value repeats across all lines of an order.
7 KPI (Business Ratio)
Use for margins, conversion rates, and other ratios. Explain calculation at the requested grouping, percentage scale, and zero handling.
Suggested Template
[BUSINESS_RATIO]. At each grouping, calculated as [AGGREGATED_NUMERATOR] / [AGGREGATED_DENOMINATOR]. Stored as [SCALE] and displayed as [FORMAT]. Zero denominator returns [RESULT]. [DIRECTION_OF_IMPROVEMENT].
Example :
Gross Margin Percentage
Share of net revenue remaining after cost of goods sold. At each grouping, calculated as SUM(Gross Profit USD) / SUM(Net Revenue USD), not an average of line percentages. Stored as a decimal: 0.25 displays as 25%. Zero revenue returns null. Higher is better.
Checklist before publishing AI Descriptions
- Verify the descriptions of the column such as definitions, codes, units, grain, and coverage with the data owner.
- Remove conflicting definitions rather than assuming one text location takes precedence.
- Keep alternate names in Synonyms.
- Make sure modelled data accurately matches the descriptions.
- Always Review generated text, complete the documented indexing steps, and test representative questions after changes.
Call to Action
- AI Descriptions for datasets
- AI Descriptions for subject areas
- Supplemental Instructions for an Oracle Analytics AI Agent
- Oracle Analytics AI Agents Best Practices
