DatAInsights Composer States and MessagesPremium
The DatAInsights Composer shows a message when a request needs clarification, cannot produce a visualization, or fails. Handle onStateChange to track state changes, or localize the built-in messages.
During normal operation, the component moves from empty to generating and then generated. Follow-up prompts enter refining; stopping a request returns to the previous state.
Clarifications
In the clarification state, the component asks for more detail. This happens when the request could match more than one dataset, when no dataset can be resolved for it, or when your own AI client or message returns a clarification. The default AI client does not ask about vague prompts. It chooses the most plausible fields and lets the user refine the result. The next prompt answers the question and is sent with the original request, so short answers retain their context.
Errors and Unsupported Requests
The component keeps the current visualization when a request cannot be completed:
unsupported—The request cannot be fulfilled with the available data or visualization types. A declined request does not fireonError.error—An AI client call failed. The component firesonError, and the user can retry.
The following example uses a failing AI client to demonstrate the error message.
Validation Messages
Every configuration is validated against its dataset, and an invalid configuration is never rendered. If the AI generates an invalid configuration, the component keeps the current visualization and shows the validation message in the unsupported state, so the user can rephrase the prompt. If a configuration that you supply or restore through configs, defaultConfigs, or the History is invalid, the component shows the message in the invalidConfig state instead. The messages are listed in the states and message keys.
If a filter matches no rows in a non-empty dataset, the component shows the noDataMessage text, No data matches this request. Try different values or a different wording. For AI results, it keeps the current visualization and shows the message in the unsupported state. For a supplied visualization, it shows the message instead of the visualization. This check is skipped when you handle onDataProcess.
The following example filters sales orders to a territory that is not in the dataset.
States and Message Keys
The following table lists each state, when it is active, the message keys that supply its text, and the label of the submit button. The table omits the datAInsightsComposer. prefix of the keys. You can customize every key through localization.
| State | When it is active | Message keys | Submit button |
|---|---|---|---|
empty | No visualization is shown yet. | title, promptPlaceholder | generateButton |
generating | The first request is in flight. | generatingMessage | generatingButton, with stopButton as its tooltip and accessible name |
generated | A visualization is shown. | loadingMessage while the data loads or onDataProcess is pending, noDataMessage when a filter matches no rows, renderErrorMessage when a visualization fails to render | refineButton opens the refine prompt |
refining | A refine request is in flight. | refineFieldLabel, generatingMessage | generatingButton, with stopButton as its tooltip and accessible name |
clarification | The AI needs more detail, or the dataset for the prompt cannot be resolved. | clarificationMessage, datasetNotResolvedMessage, ambiguousDatasetMessage; the AI can also return its own text | generateButton, or applyButton in the refine prompt |
unsupported | The AI declined the request, returned a configuration that fails validation, or returned a filter that matches no rows. | aiDeclinedMessage or unsupportedMessage, followed by unsupportedAlternativesMessage, alternativesListSeparator, and alternativesLastMessage; noDataMessage or the validation keys of invalidConfig when the result is rejected | tryAgainButton, or applyButton in the refine prompt |
error | An AI client call failed. | aiServiceErrorMessage | tryAgainButton, or applyButton in the refine prompt |
invalidConfig | A supplied or restored configuration fails validation and is not rendered. | invalidConfigMessage, invalidStructureMessage, disallowedTypeMessage, componentTypeChangedMessage, tooManyCategoriesMessage | generateButton |
The refine prompt appears after the user selects Refine. When a visualization is already shown, the message appears above the refine prompt instead of the main prompt, so the submit button keeps the applyButton label.
To show your own text, pass a message to the component. It replaces the built-in message and puts the component in the state that matches its type: clarification, unsupported, or error.