GetInsight: read a cached insight for a database object

GetInsight reads a single row from AIInsights.SchemaInsights for the specified object and also returns a freshness value computed against the live schema. If the live schema fingerprint has changed since the insight was last authored — for example because the object was altered or dropped — the stored row is automatically archived to AIInsights.InsightHistory and the freshness becomes StaleArchived.

Parameters

objectName

string

required

Object name without schema prefix (e.g. TableProblems). Case follows the SQL Server collation of the connected database.

schemaName

string

Schema name. Pass dbo explicitly when the object lives in the default schema. Pass null only when the schema is genuinely unknown.

objectType

string

Object type label as stored in AIInsights.SchemaInsights. Must be one of: Table, View, Procedure, Function, Trigger. Defaults to Table when omitted.

Returns

success

boolean

required

true when the lookup completed without an unhandled exception.

data

object

Present when success is true.

Show data fields

insight

object | null

The cached insight row, or null when no row exists for the requested object.

Show insight fields

insightId

integer

Auto-generated primary key of the row in AIInsights.SchemaInsights.

objectType

string

Object type label: Table, View, Procedure, Function, or Trigger.

schemaName

string | null

Schema name of the object.

objectName

string

Object name without schema prefix.

columnName

string | null

Column name for column-level insights; null for object-level insights.

description

string | null

Short single-sentence description of the object.

businessPurpose

string | null

Why this object exists from a business or operational perspective.

dataPatterns

string | null

Typical data volume, key columns, hot filters, and partitioning hints.

usageGuidelines

string | null

Preferred joins, filters, gotchas, and analyst guidance.

JSON array string of related object names, e.g. ["Buildings","Suppliers"].

llmModel

string | null

Identifier of the LLM or process that authored the insight. auto-mechanical indicates a low-confidence baseline placeholder.

confidence

decimal | null

Confidence score between 0 and 1. Baselines generated by RebuildBaselineInsights have a confidence of 0.30.

lastAnalyzed

datetime

Timestamp when the insight row was last written.

analyzedBy

string | null

Agent name, ticket ID, or analyst name that authored the insight.

version

integer

Monotonically incrementing version counter for the row.

schemaFingerprint

string | null

Hash of the live schema metadata at the time the insight was written. Used for staleness detection.

insightFreshness

string

required

Computed freshness of the insight relative to the live schema. One of:

Value	Meaning
`Fresh`	The cached insight matches the current schema fingerprint.
`StaleArchived`	The object’s schema changed; the old insight was archived.
`Absent`	No insight row exists for this object.
`LayerDisabled`	The insights layer is disabled via `USE_INSIGHTS_LAYER`.
`AccessDenied`	Insufficient permissions to read schema metadata.
`DefinitionUnavailable`	The object definition cannot be retrieved (e.g. encrypted).

error

string

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

GetInsight requires the AI Insights layer to be installed via InstallInsightsLayer and USE_INSIGHTS_LAYER to be enabled (the default). When the layer is disabled, insightFreshness is always LayerDisabled.

Prefer DescribeTable, DescribeView, or GetObject for schema introspection — those tools embed the insight data automatically in their response. Use GetInsight only when you need a direct cache read without pulling full schema metadata.

After receiving StaleArchived or Absent, investigate the object and call UpsertInsight to write a fresh authored insight.

Overview

Inspection Tools

Write & DDL Tools

Insights Tools

GetInsight: read a cached insight for a database object

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