InsightsCheck: verify the AI Insights installation state

InsightsCheck queries the database for the current state of the AI Insights installation. Use it to verify the layer is installed and healthy before calling any other insights tools. When USE_INSIGHTS_LAYER is disabled via environment variable, the tool returns immediately without making a database query.

Parameters

InsightsCheck takes no parameters.

Returns

success

boolean

required

true when the status check completed without error; false if an unexpected exception occurred.

data

object

Present when success is true. Contains all layer status fields.

Show data fields

layerEnabledViaEnvironment

boolean

required

true unless USE_INSIGHTS_LAYER is explicitly set to false, 0, no, off, or disabled. The environment variable is opt-out only — missing or empty means enabled.

aiInsightsSchemaExists

boolean

required

true if the AIInsights schema is present in the connected database.

ddlAuditTableExists

boolean

required

true if the dbo.DDL_AuditLog table exists. This table captures DDL change events for watermark-based insight invalidation.

ddlAuditTriggerEnabled

boolean

required

true if the database-level DDL_Audit trigger is present and enabled. Without this trigger, schema changes are not automatically captured.

schemaInsightsCount

integer

required

Current row count in AIInsights.SchemaInsights. A count of 0 on an installed layer means no baselines or authored insights have been written yet.

lastProcessedAuditId

integer

required

The highest DDL_AuditLog row ID that has already been processed by the insights pipeline. Acts as the DDL processing watermark.

lastProcessedAt

datetime | null

required

Timestamp of when the last DDL processing run completed. null if DDL processing has never run.

error

string

Present only when success is false. Contains the exception message.

If USE_INSIGHTS_LAYER=false, all boolean fields are false, integer fields are 0, and lastProcessedAt is null — without issuing any database query.

Call InsightsCheck after InstallInsightsLayer to confirm all objects were created successfully. A fully-installed layer should have aiInsightsSchemaExists, ddlAuditTableExists, and ddlAuditTriggerEnabled all returning true.

Overview

Inspection Tools

Write & DDL Tools

Insights Tools

InsightsCheck: verify the AI Insights installation state

Parameters

Returns

Build docs developers (and LLMs) love

Overview

Inspection Tools

Write & DDL Tools

Insights Tools

Documentation Index

​Parameters

​Returns

Build docs developers (and LLMs) love

Parameters

Returns