#3843 AI table column renames for consistency

- Rename PromptNickname to Prompt_Nickname and DefaultPrompt to Default_Prompt in AI Prompts table
- Add Model_Nickname column to AI Providers table and rename DefaultModel to Default_Model
- Update @aimodel lookup to match against both Model_Nickname and AI_Model
- Trim AI payload to Context size when specified (0 or NULL = unlimited)
- Update Using_AI.md documentation to reflect all changes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: BrentOzar

Documentation/Using_AI.md

@@ -45,32 +45,32 @@ If you want to override the default prompts, create a table to store your prompt
 ```sql
 CREATE TABLE dbo.Blitz_AI_Prompts
 (Id INT IDENTITY(1,1) PRIMARY KEY CLUSTERED,
- PromptNickname NVARCHAR(200),
+ Prompt_Nickname NVARCHAR(200),
  AI_System_Prompt NVARCHAR(4000),
  Default_Prompt BIT DEFAULT 0);
- 
-INSERT INTO dbo.Blitz_AI_Prompts (PromptNickname, Default_Prompt, AI_System_Prompt)
+
+INSERT INTO dbo.Blitz_AI_Prompts (Prompt_Nickname, Default_Prompt, AI_System_Prompt)
   VALUES ('sp_BlitzCache Default', 1, 'You are a very senior database developer working with Microsoft SQL Server and Azure SQL DB. You focus on real-world, actionable advice that will make a big difference, quickly. You value everyone''s time, and while you are friendly and courteous, you do not waste time with pleasantries or emoji because you work in a fast-paced corporate environment.
 
     You have a query that isn''t performing to end user expectations. You have been tasked with making serious improvements to it, quickly. You are not allowed to change server-level settings or make frivolous suggestions like updating statistics. Instead, you need to focus on query changes or index changes. 
     
     Do not offer followup options: the customer can only contact you once, so include all necessary information, tasks, and scripts in your initial reply. Render your output in Markdown, as it will be shown in plain text to the customer.');
 
-INSERT INTO dbo.Blitz_AI_Prompts (PromptNickname, Default_Prompt, AI_System_Prompt)
+INSERT INTO dbo.Blitz_AI_Prompts (Prompt_Nickname, Default_Prompt, AI_System_Prompt)
   VALUES ('sp_BlitzCache Index Tuning', 0, 'You are a very senior database developer working with Microsoft SQL Server and Azure SQL DB. You focus on real-world, actionable advice that will make a big difference, quickly. You value everyone''s time, and while you are friendly and courteous, you do not waste time with pleasantries or emoji because you work in a fast-paced corporate environment.
 
     You have a query that isn''t performing to end user expectations. You have been tasked with making serious improvements to it, quickly, but you are only allowed to make index changes. You are not allowed to make changes to the query, server-level settings, database settings, etc.
     
     Do not offer followup options: the customer can only contact you once, so include all necessary information, tasks, and scripts in your initial reply. Render your output in Markdown, as it will be shown in plain text to the customer.');
 
-INSERT INTO dbo.Blitz_AI_Prompts (PromptNickname, Default_Prompt, AI_System_Prompt)
+INSERT INTO dbo.Blitz_AI_Prompts (Prompt_Nickname, Default_Prompt, AI_System_Prompt)
   VALUES ('sp_BlitzCache Deadlock Tuning', 0, 'You are a very senior database developer working with Microsoft SQL Server and Azure SQL DB. You focus on real-world, actionable advice that will make a big difference, quickly. You value everyone''s time, and while you are friendly and courteous, you do not waste time with pleasantries or emoji because you work in a fast-paced corporate environment.
 
     You have a query that is experiencing deadlocks and blocking. You have been tasked with making serious improvements to it, quickly. You are not allowed to change server-level or database-level settings nor make frivolous suggestions like updating statistics. Instead, you need to focus on query changes or index changes that will reduce blocking and deadlocks.
     
     Do not offer followup options: the customer can only contact you once, so include all necessary information, tasks, and scripts in your initial reply. Render your output in Markdown, as it will be shown in plain text to the customer.');
 
-INSERT INTO dbo.Blitz_AI_Prompts (PromptNickname, Default_Prompt, AI_System_Prompt)
+INSERT INTO dbo.Blitz_AI_Prompts (Prompt_Nickname, Default_Prompt, AI_System_Prompt)
   VALUES ('sp_BlitzCache Modernize', 0, 'You are a very senior database developer working with Microsoft SQL Server and Azure SQL DB. You focus on real-world, actionable advice that will make a big difference, quickly. You value everyone''s time, and while you are friendly and courteous, you do not waste time with pleasantries or emoji because you work in a fast-paced corporate environment.
 
     You have been given a legacy query that needs to be modernized. Our goals are to make the query run faster, make it easier to understand, easier to maintain, and to take advantage of new features up to and including SQL Server 2025. You have been tasked with making serious improvements to it, quickly, without touching server-level settings, database-level settings, indexes, or statistics.
@@ -195,22 +195,22 @@ CREATE TABLE dbo.Blitz_AI_Providers
  Default_Model BIT DEFAULT 0);
 
 /* OpenAI - fast, cheap model, default: */
-INSERT INTO dbo.Blitz_AI_Providers (Model_Nickname, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, Timeout_Seconds, DefaultModel)
+INSERT INTO dbo.Blitz_AI_Providers (Model_Nickname, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, Timeout_Seconds, Default_Model)
 VALUES (N'ChatGPT Fast', N'gpt-5-nano', N'https://api.openai.com/v1/chat/completions',
     N'https://api.openai.com/', 30, 1);
 
 /* OpenAI - highest quality, slowest, most expensive model: */
-INSERT INTO dbo.Blitz_AI_Providers (Model_Nickname, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, Timeout_Seconds, DefaultModel)
+INSERT INTO dbo.Blitz_AI_Providers (Model_Nickname, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, Timeout_Seconds, Default_Model)
 VALUES (N'ChatGPT Slow', N'gpt-5.4', N'https://api.openai.com/v1/chat/completions',
     N'https://api.openai.com/', 230, 0);
 
 /* Gemini - fast, cheap model: */
-INSERT INTO dbo.Blitz_AI_Providers (Model_Nickname, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, Timeout_Seconds, DefaultModel)
+INSERT INTO dbo.Blitz_AI_Providers (Model_Nickname, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, Timeout_Seconds, Default_Model)
 VALUES (N'Gemini Fast', N'gemini-3-flash-preview', N'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent',
     N'https://generativelanguage.googleapis.com/', 30, 0);
 
 /* Gemini - highest quality, slowest, most expensive model: */
-INSERT INTO dbo.Blitz_AI_Providers (Model_Nickname, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, Timeout_Seconds, DefaultModel)
+INSERT INTO dbo.Blitz_AI_Providers (Model_Nickname, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, Timeout_Seconds, Default_Model)
 VALUES (N'Gemini Slow', N'gemini-3-1-pro-preview', N'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent',
     N'https://generativelanguage.googleapis.com/', 230, 0);
 ```
@@ -263,7 +263,7 @@ EXEC sp_BlitzCache @Top = 1, @AI = 1,
 | Parameter | Default | Description |
 |-----------|---------|-------------|
 | `@AI` | 0 | 0 = off, 1 = call AI API, 2 = generate prompt only |
-| `@AIModel` | `gpt-5-nano` | Model name. If it starts with `gemini`, the Gemini URL and payload template are used automatically. |
+| `@AIModel` | `gpt-5-nano` | Model name or nickname. Matches against both `AI_Model` and `Model_Nickname` in the providers table. If it starts with `gemini`, the Gemini URL and payload template are used automatically. |
 | `@AIURL` | `https://api.openai.com/v1/chat/completions` | API endpoint URL. Auto-detected for Gemini models. |
 | `@AICredential` | Auto-detected from URL | Database-scoped credential name. Defaults to the root of your `@AIURL` with trailing slash. |
 | `@AIConfigTable` | NULL | Three-part name of your providers config table (e.g., `master.dbo.Blitz_AI_Providers`). |
@@ -314,7 +314,7 @@ EXEC sp_BlitzIndex
 | Parameter | Default | Description |
 |-----------|---------|-------------|
 | `@AI` | 0 | 0 = off, 1 = call AI API, 2 = generate prompt only |
-| `@AIModel` | `gpt-5-nano` | Model name. Gemini models auto-detect URL and payload template. |
+| `@AIModel` | `gpt-5-nano` | Model name or nickname. Matches against both `AI_Model` and `Model_Nickname` in the providers table. Gemini models auto-detect URL and payload template. |
 | `@AIURL` | `https://api.openai.com/v1/chat/completions` | API endpoint URL. |
 | `@AICredential` | Auto-detected from URL | Database-scoped credential name. |
 | `@AIConfigTable` | NULL | Three-part name of your providers config table. |
@@ -342,4 +342,6 @@ With `@AI = 2`:
 - **Database context matters** for `@AI = 1`: you must run the query in the database where your credentials are stored, or the API call will fail.
 - **Timeout**: The default timeout is 230 seconds. Larger models may need the full timeout; smaller models like `gpt-5-nano` respond in seconds.
 - **Cost**: Each call sends your query/index data to the AI provider and costs API credits. Use `@Top = 1` with sp_BlitzCache to limit costs during testing.
+- **Context size**: If the `Context` column in your AI Providers table has a value greater than 0, the payload will be trimmed to that length to avoid exceeding the model's context window. Set `Context` to 0 or NULL for unlimited payload size.
+- **Model nicknames**: The `@AIModel` parameter matches against both the `AI_Model` and `Model_Nickname` columns in your providers table. This lets you use friendly names like `'ChatGPT Slow'` instead of model identifiers like `'gpt-5.4'`.
 - **Security**: Your query text, index definitions, and table structures are sent to the AI provider's API. Do not use this feature if your data or schema is subject to restrictions on external sharing.

sp_BlitzCache.sql

@@ -874,20 +874,21 @@ END;
 
 CREATE TABLE #ai_providers
 (Id INT PRIMARY KEY CLUSTERED,
+ Model_Nickname NVARCHAR(200),
  AI_Model NVARCHAR(100) INDEX AI_Model,
  AI_URL NVARCHAR(500),
  AI_Database_Scoped_Credential_Name NVARCHAR(500),
  AI_Parameters NVARCHAR(4000),
  Payload_Template NVARCHAR(4000),
  Timeout_Seconds TINYINT,
  Context INT,
- DefaultModel BIT DEFAULT 0);
+ Default_Model BIT DEFAULT 0);
 
 CREATE TABLE #ai_prompts
 (Id INT PRIMARY KEY CLUSTERED,
- PromptNickname NVARCHAR(200) INDEX IX_PromptNickname,
+ Prompt_Nickname NVARCHAR(200) INDEX IX_Prompt_Nickname,
  AI_System_Prompt NVARCHAR(4000),
- DefaultPrompt BIT DEFAULT 0);
+ Default_Prompt BIT DEFAULT 0);
 
 DECLARE
     @AIConfigDatabaseName NVARCHAR(128) = CASE WHEN @AIConfigTable IS NULL THEN NULL ELSE PARSENAME(@AIConfigTable, 3) END,
@@ -913,20 +914,20 @@ END;
 IF @AIConfigTable IS NOT NULL
 BEGIN
    RAISERROR(N'Reading values from AI Provider Configuration Table', 0, 1) WITH NOWAIT;
-   SET @config_sql = N'INSERT INTO #ai_providers (Id, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, AI_Parameters, Payload_Template, Timeout_Seconds, Context, DefaultModel)
-        SELECT Id, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, AI_Parameters, Payload_Template, Timeout_Seconds, Context, DefaultModel FROM '
+   SET @config_sql = N'INSERT INTO #ai_providers (Id, Model_Nickname, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, AI_Parameters, Payload_Template, Timeout_Seconds, Context, Default_Model)
+        SELECT Id, Model_Nickname, AI_Model, AI_URL, AI_Database_Scoped_Credential_Name, AI_Parameters, Payload_Template, Timeout_Seconds, Context, Default_Model FROM '
         + CASE WHEN @AIConfigDatabaseName IS NOT NULL THEN (QUOTENAME(@AIConfigDatabaseName) + N'.') ELSE N'' END
         + CASE WHEN @AIConfigSchemaName IS NOT NULL THEN (QUOTENAME(@AIConfigSchemaName) + N'.') ELSE N'' END
-        + QUOTENAME(@AIConfigTableName) + N' WHERE DefaultModel = 1 OR @AIModel = AI_Model ; ';
+        + QUOTENAME(@AIConfigTableName) + N' WHERE Default_Model = 1 OR @AIModel = AI_Model OR @AIModel = Model_Nickname ; ';
    EXEC sp_executesql @config_sql, N'@AIModel NVARCHAR(100)', @AIModel;
 END;
 
 IF @AIModel IS NOT NULL AND @AIConfigTable IS NOT NULL
-    AND NOT EXISTS (SELECT 1 FROM #ai_providers WHERE AI_Model = @AIModel)
+    AND NOT EXISTS (SELECT 1 FROM #ai_providers WHERE AI_Model = @AIModel OR Model_Nickname = @AIModel)
 BEGIN
     DECLARE @AIModelRequested NVARCHAR(200) = @AIModel;
     DECLARE @AIFallbackModel NVARCHAR(200);
-    SELECT TOP 1 @AIFallbackModel = AI_Model FROM #ai_providers WHERE DefaultModel = 1 ORDER BY Id;
+    SELECT TOP 1 @AIFallbackModel = AI_Model FROM #ai_providers WHERE Default_Model = 1 ORDER BY Id;
     IF @AIFallbackModel IS NULL SET @AIFallbackModel = N'gpt-5-nano';
     RAISERROR('@AIModel "%s" was not found in configuration table %s. Using "%s" instead.',
         10, 1, @AIModelRequested, @AIConfigTable, @AIFallbackModel) WITH NOWAIT;
@@ -936,11 +937,11 @@ END;
 IF @AIPromptConfigTable IS NOT NULL
 BEGIN
    RAISERROR(N'Reading values from AI Prompts Table', 0, 1) WITH NOWAIT;
-   SET @config_sql = N'INSERT INTO #ai_prompts (Id, PromptNickname, AI_System_Prompt, DefaultPrompt)
-        SELECT Id, PromptNickname, AI_System_Prompt, DefaultPrompt FROM '
+   SET @config_sql = N'INSERT INTO #ai_prompts (Id, Prompt_Nickname, AI_System_Prompt, Default_Prompt)
+        SELECT Id, Prompt_Nickname, AI_System_Prompt, Default_Prompt FROM '
         + CASE WHEN @AIPromptDatabaseName IS NOT NULL THEN (QUOTENAME(@AIPromptDatabaseName) + N'.') ELSE N'' END
         + CASE WHEN @AIPromptSchemaName IS NOT NULL THEN (QUOTENAME(@AIPromptSchemaName) + N'.') ELSE N'' END
-        + QUOTENAME(@AIPromptTableName) + N' WHERE (@AIPrompt IS NULL AND DefaultPrompt = 1) OR @AIPrompt = PromptNickname ; ';
+        + QUOTENAME(@AIPromptTableName) + N' WHERE (@AIPrompt IS NULL AND Default_Prompt = 1) OR @AIPrompt = Prompt_Nickname ; ';
    EXEC sp_executesql @config_sql, N'@AIPrompt NVARCHAR(200)', @AIPrompt;
 END;
 
@@ -975,7 +976,7 @@ IF @AI > 0
             @AITimeoutSeconds = COALESCE(Timeout_Seconds, 230),
             @AIContext = Context
             FROM #ai_providers
-            WHERE DefaultModel = 1
+            WHERE Default_Model = 1
             ORDER BY Id;
     ELSE
         SELECT TOP 1 @AIModel = AI_Model,
@@ -986,19 +987,19 @@ IF @AI > 0
             @AITimeoutSeconds = COALESCE(Timeout_Seconds, 230),
             @AIContext = Context
             FROM #ai_providers
-            WHERE AI_Model = @AIModel
+            WHERE AI_Model = @AIModel OR Model_Nickname = @AIModel
             ORDER BY Id;
 
     /* Check the prompts table */
     IF @AIPrompt IS NULL
         SELECT TOP 1 @AISystemPrompt = AI_System_Prompt
             FROM #ai_prompts
-            WHERE DefaultPrompt = 1
+            WHERE Default_Prompt = 1
             ORDER BY Id;
     ELSE
         SELECT TOP 1 @AISystemPrompt = AI_System_Prompt
             FROM #ai_prompts
-            WHERE PromptNickname = @AIPrompt
+            WHERE Prompt_Nickname = @AIPrompt
             ORDER BY Id;
 
     IF @AIModel IS NULL
@@ -1056,7 +1057,7 @@ IF @AI > 0
                 @AISystemPrompt AS AISystemPrompt, @AIPayloadTemplate AS AIPayloadTemplate;
         END;
 
-    IF @AIPrompt IS NOT NULL AND NOT EXISTS (SELECT 1 FROM #ai_prompts WHERE PromptNickname = @AIPrompt)
+    IF @AIPrompt IS NOT NULL AND NOT EXISTS (SELECT 1 FROM #ai_prompts WHERE Prompt_Nickname = @AIPrompt)
         BEGIN
             RAISERROR('@AIPrompt was specified but no matching prompt was found in the prompts table.',12,1);
             RETURN;
@@ -5407,7 +5408,10 @@ Thank you.'
                 SET @AIPayload = REPLACE(@AIPayloadTemplate, N'@AIModel', @AIModel);
                 SET @AIPayload = REPLACE(@AIPayload, N'@AISystemPrompt',  REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(@AISystemPrompt, '\', '\\'), '"', '\"'), CHAR(13), '\r'), CHAR(10), '\n'), CHAR(9), '\t'));
                 SET @AIPayload = REPLACE(@AIPayload, N'@CurrentAIPrompt',  REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(@CurrentAIPrompt, '\', '\\'), '"', '\"'), CHAR(13), '\r'), CHAR(10), '\n'), CHAR(9), '\t'));
-                --SET @AIPayload = REPLACE(@AIPayload, N'@CurrentAIPrompt', @CurrentAIPrompt);
+
+                /* Trim payload to context size if specified */
+                IF @AIContext IS NOT NULL AND @AIContext > 0 AND LEN(@AIPayload) > @AIContext
+                    SET @AIPayload = LEFT(@AIPayload, @AIContext);
 
                 IF @Debug = 2
                 BEGIN