For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt, and this page is available as Markdown at /en/features/ai-assistant.md.
  • English
  • Scoped Database AI Assistant (4.0 Core Feature)

    The Database AI Assistant is a flagship Yearning v4.0 capability built directly into the authenticated workspace (bottom-right dots-02 floating trigger and /assistant view). It focuses strictly on three database workflows: platform usage guidance, metadata-grounded natural-language SQL generation, and SQL analysis & optimization.

    Unlike general-purpose chat shells, the assistant enforces four architectural guardrails: per-turn in-memory zero-leak anonymization, dialect AST structured restoration, zero direct SQL execution, and a mandatory two-stage bridge into formal AI Precheck and multi-stage Approval.

    Click the bottom-right floating launcher on the workspace to open the scoped Database AI Assistant
    Click the bottom-right floating launcher on the workspace to open the scoped Database AI Assistant

    1. Three Scoped Capabilities

    1) Role-Aware Platform Help (platform_help)

    Backed by a version-aligned help corpus with strict role filtering (normal users receive workspace guides; administrators also receive /admin/* governance guides), returning actionable steps, citations, and clickable in-app route links.

    2) Natural-Language SQL Generation + Two-Stage Order Submission (sql_generate)

    1. Permission Check First: Query-only grants permit SELECT generation; change_review flow grants unlock controlled DML (INSERT/UPDATE/DELETE) and reversible DDL (CREATE TABLE/ALTER TABLE/CREATE INDEX/DROP INDEX). Unauthorized targets return 6002 without leaking existence.
    2. Read-Only Metadata Probing & Clarification: Controlled read-only metadata tools inspect real columns, data types, nullability, default/auto-increment behavior, and indexes. If required NOT NULL columns without defaults are missing from your description, the assistant asks for clarification instead of guessing values.
    3. Zero-Leak Anonymization & AST Restoration: On cloud default providers, identifiers map via RunMapper (table_1, column_1) and business literals map via typed TurnValueMapper placeholders (:val_str_1, :val_int_1) exclusively in per-request memory. Returned SQL is parsed by the dialect lexer/AST, checked against authorized objects, and restored safely with dialect-aware quoting (6004 fail-closed on mismatch).
    4. Two-Stage Order Bridge: Clicking Run Formal AI Precheck invokes StartEphemeralRun bound to draft_id, revision, and sql_hmac. Only after precheck reaches ready can you click Confirm & Submit Order (SubmitOrderV2 with Idempotency-Key). Any edit invalidates the binding (6005).

    3) Metadata-Grounded SQL Optimization (sql_optimize)

    Paste slow SQL (plus optional user-supplied EXPLAIN output) and pick a datasource to receive AST-validated rewrites, index advice, explicit semantic-difference warnings, and verification steps. The assistant never executes EXPLAIN or queries production rows and never fabricates unmeasured benchmark claims.

    2. Encrypted Persistence, Context Compression & Guardrails

    • Encrypted History: Messages, restored SQL drafts, and compressed context summaries are encrypted at rest with AES-256-GCM (30-day default retention, max 50 active sessions per user, max 100 turns per session). Deleting a session immediately erases its encrypted records.
    • Automatic Desensitized Context Compression: When long sessions approach the model token budget, earlier turns are compressed through a desensitized call into ai_assistant_context_summaries while preserving full history for viewing.
    • Strict Prohibitions: Refuses non-database chatter (6001), never executes any SQL (including SELECT and EXPLAIN), never reads table rows, blocks TRUNCATE/DROP DATABASE/GRANT, and never bypasses formal AI Precheck or Approvals.
    Error CodeIdentifierResolution
    6001ASSISTANT_OUT_OF_SCOPERequest is outside database/Yearning scope or asks for forbidden destructive DDL
    6002ASSISTANT_DATASOURCE_FORBIDDENMissing datasource grant or DML/DDL requested on a query-only datasource
    6003ASSISTANT_ANONYMIZATION_FAILEDInput contains raw credentials/secrets (password=, sk-, DSN); remove and retry
    6004ASSISTANT_SQL_RESTORATION_INVALIDModel SQL failed dialect AST validation, object bounds, or placeholder checks
    6005ASSISTANT_DRAFT_REVISION_STALEDraft changed or has not reached ready formal precheck; click Run Formal AI Precheck
    6006ASSISTANT_CONTEXT_BUDGET_EXCEEDEDInput exceeded single-turn context budget; trim input or start a fresh session
    6007ASSISTANT_STREAM_IN_PROGRESSWait for the active reply stream to finish or click Stop