Introduction

AI Functions Oracle Analytics Cloud (OAC) let workbook authors apply large language models directly to row-level data. Instead of exporting data to a separate application, authors can generate labels, summaries, classifications, filters, and group-level narratives inside analytics content.

This article explains the underlying architecture, practical prompting and performance techniques, validation steps, and common troubleshooting paths for reliable implementation.

Understanding the Architecture

The integration has three layers:

  1. The external model provider receives the prompt and returns generated text.
  2. Oracle Autonomous AI Database stores the provider credential and AI profile, and exposes the profile through DBMS_CLOUD_AI.
  3. Oracle Analytics Cloud connects to that database, registers the profile as a catalog model asset, and invokes it from AI Functions in workbooks and other authoring surfaces.


Recommendations for Prompting and Performance

  1. State exactly what the model should return, including order, length, delimiter, casing, or allowed labels.
  2. Keep row-level input concise. More input increases latency, token usage, and the chance of inconsistent output.
  3. Label combined fields clearly – for example, Title:, Description:, and Department: etc. Use consistent separators.
  4. Cast non-string fields to strings before passing them to an AI Function.
  5. Use deterministic SQL for deterministic logic. Reserve AI Functions for semantic tasks that benefit from model reasoning.
  6. Test on a small filtered sample before running a model call across a large dataset.
  7. Whenever you can, use data flows in OAC to generate the content and store it in the dataset and database tables, especially for row-level input functions (such as AI_FILTER and AI_GENERATE). Use the resultant datasets for reporting.
  8. Treat generated content as model output, not source-of-truth data; validate it for sensitive or consequential use cases.

Validation Checklist

  1. The database user can execute DBMS_CLOUD_AI.
  2. The database can reach the provider endpoint through the configured ACL and network path.
  3. The credential is valid, secret, and not embedded anywhere in source control.
  4. The AI profile is enabled and DBMS_CLOUD_AI.GENERATE returns the expected test value.
  5. The OAC connection points to the same Oracle Autonomous AI Lakehouse as the dataset and profile.
  6. The model asset is registered in Shared Folders when shared access is required.
  7. Authors and consumers have the required catalog permissions.
  8. The workbook calculation validates and returns the requested output format on representative rows.

Choose the Right AI Function

AI_GENERATE: Create one text result per row

Use it for enrichment, summarization, classification, rewriting, explanation, and tag generation.

AI_GENERATE(COMMENT_TEXT,
  ‘Classify this comment as positive, negative, or neutral. Return one lowercase word.’,
  <MODEL_ID>)

AI_FILTER: Keep rows that satisfy a semantic condition

Use it when the condition is easier to express in natural language than with deterministic rules.

AI_FILTER(‘Is this request urgent?’, REQUEST_TEXT, <MODEL_ID>)

AI_AGG: Generate a response across a group of rows

Use it for grouped summaries or themes. Keep the group size and input text controlled to manage latency and token use.

AI_AGG(REVIEW_TEXT,
  ‘Summarize these reviews in two sentences. Return only the summary.’,
  <MODEL_ID>)

Troubleshooting Tips

The database test can’t reach the provider

Confirm the hostname in the ACL, DNS resolution, database egress, provider endpoint availability, and any private-network routing or proxy requirements.

The provider returns an authentication or quota error

Rotate and update the credential, verify provider-side API enablement, and check quotas, billing, regional availability, and model access.

The AI profile doesn’t appear in OAC

Confirm that the profile is enabled, owned by the user used in the OAC connection, and located in the same database as the dataset. Retest the connection and reopen the registration dialog.

The model doesn’t appear in the workbook picker

Verify that the registered model is stored in Shared Folders and that the author has Read-Only or higher access. Also verify that the workbook dataset uses the same database connection.

The output is too verbose or inconsistent

Tighten the prompt. Specify allowed values, output length, delimiter, and a return-only instruction. Test the result over several representative rows before scaling up.

Call to Action

Start with a narrow enrichment use case and validate it on a small workbook sample. Once reliable, expand the pattern to data flows, preparation, and semantic-model calculations on your instance.

For AI model configuration and registration in OAC, refer to the Step-by-Step Guide to Using AI Functions in Oracle Analytics Cloud.

If you have questions, post them in the Oracle Analytics Community and we’ll follow up with answers.