Skip to main content
Glama
Teradata

Teradata MCP Server

Official
by Teradata
OverviewSchemaSourceRelated ServersDiscussions(1)Admin
Python
Remote

Sql Execute Full Pipeline

sql_Execute_Full_Pipeline
Idempotent

Runs the complete query clustering pipeline to identify high-CPU queries and group similar SQL for optimization, enabling DBAs to target resource-intensive workloads.

Instructions

COMPLETE SQL QUERY CLUSTERING PIPELINE FOR HIGH-USAGE QUERY OPTIMIZATION

This tool executes the entire SQL query clustering workflow to identify and analyze high CPU usage queries for optimization opportunities. It's designed for database performance analysts and DBAs who need to systematically identify query optimization candidates.

FULL PIPELINE WORKFLOW:

  1. Query Log Extraction: Extracts SQL queries from DBC.DBQLSqlTbl with comprehensive performance metrics

  2. Performance Metrics Calculation: Computes CPU skew, I/O skew, PJI (Physical to Logical I/O ratio), UII (Unit I/O Intensity)

  3. Query Tokenization: Tokenizes SQL text using {sql_clustering_config.get('model', {}).get('model_id', 'bge-small-en-v1.5')} tokenizer via ivsm.tokenizer_encode

  4. Embedding Generation: Creates semantic embeddings using ivsm.IVSM_score with ONNX models

  5. Vector Store Creation: Converts embeddings to vector columns via ivsm.vector_to_columns

  6. K-Means Clustering: Groups similar queries using TD_KMeans with optimal K from configuration

  7. Silhouette Analysis: Calculates clustering quality scores using TD_Silhouette

  8. Statistics Generation: Creates comprehensive cluster statistics with performance aggregations

PERFORMANCE METRICS EXPLAINED:

  • AMPCPUTIME: Total CPU seconds across all AMPs (primary optimization target)

  • CPUSKW/IOSKW: CPU/I/O skew ratios (>2.0 indicates distribution problems)

  • PJI: Physical-to-Logical I/O ratio (higher = more CPU-intensive)

  • UII: Unit I/O Intensity (higher = more I/O-intensive relative to CPU)

  • LogicalIO: Total logical I/O operations (indicates scan intensity)

  • NumSteps: Query plan complexity (higher = more complex plans)

CONFIGURATION (from sql_opt_config.yml):

  • Uses top {default_max_queries} queries by CPU time (configurable)

  • Creates {default_optimal_k} clusters by default (configurable via optimal_k parameter)

  • Embedding model: {sql_clustering_config.get('model', {}).get('model_id', 'bge-small-en-v1.5')}

  • Vector dimensions: {sql_clustering_config.get('embedding', {}).get('vector_length', 384)}

  • All database and table names are configurable

OPTIMIZATION WORKFLOW: After running this tool, use:

  1. sql_Analyze_Cluster_Stats to identify problematic clusters

  2. sql_Retrieve_Cluster_Queries to get actual SQL from target clusters

  3. LLM analysis to identify patterns and propose specific optimizations

USE CASES:

  • Identify query families consuming the most system resources

  • Find queries with similar patterns but different performance

  • Discover optimization opportunities through clustering analysis

  • Prioritize DBA effort on highest-impact query improvements

  • Understand workload composition and resource distribution

PREREQUISITES:

  • DBC.DBQLSqlTbl and DBC.DBQLOgTbl must be accessible

  • Embedding models and tokenizers must be installed in feature_ext_db

  • Sufficient space in feature_ext_db for intermediate and final tables

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
optimal_kNo
max_queriesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.2.1
    • addedInput schema / additionalProperties
      Added value: +false
    • addedInput schema / properties / max_queries / anyOf
      Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]
    • removedInput schema / properties / max_queries / title
      Removed value: -"Max Queries"
    • removedInput schema / properties / max_queries / type
      Removed value: -"integer"
    • addedInput schema / properties / optimal_k / anyOf
      Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]
    • removedInput schema / properties / optimal_k / title
      Removed value: -"Optimal K"
    • removedInput schema / properties / optimal_k / type
      Removed value: -"integer"
  2. Addedv1.0.0

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as non-read-only and idempotent; the description adds that it 'extracts', 'creates', 'converts' tables, and requires 'sufficient space in feature_ext_db for intermediate and final tables.' It does not detail overwrite behavior, but the write side effects and prerequisites are disclosed beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with bold sections, numbered workflow steps, metric definitions, use cases, and prerequisites. The purpose is front-loaded; while some use-case bullets restate the purpose, the organization makes the length acceptable for a complex pipeline.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

It covers the full pipeline, metrics, configuration, prerequisites, and downstream tools, which is substantial for a tool with no output schema and only two optional params. It does not specify exact output table names or return behavior, but an agent has enough to invoke and understand the side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the burden. It explains max_queries as 'top {default_max_queries} queries by CPU time (configurable)' and optimal_k as 'creates {default_optimal_k} clusters by default (configurable via optimal_k parameter)'. It doesn't give exact defaults or value ranges, but adds semantics the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'executes the entire SQL query clustering workflow to identify and analyze high CPU usage queries for optimization opportunities.' It clearly distinguishes this tool from downstream siblings by framing it as the full pipeline and listing sql_Analyze_Cluster_Stats and sql_Retrieve_Cluster_Queries as follow-up steps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly targets DBAs and performance analysts and gives a post-run workflow: 'After running this tool, use: 1. sql_Analyze_Cluster_Stats ... 2. sql_Retrieve_Cluster_Queries ...'. This gives clear context for when it precedes siblings, though it does not state explicit when-not-to-use conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools