tdsql-mcp 1.4.0__tar.gz → 1.4.2__tar.gz

tdsql_mcp-1.4.2/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{                                                                                                                                                                                                                                                                                           
+   "name": "teradata-sql-analytics",                                                     
+   "description": "Teradata native function guidelines and syntax.",
+   "version": "1.0.0"
+}

{tdsql_mcp-1.4.0 → tdsql_mcp-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tdsql-mcp
-Version: 1.4.0
+Version: 1.4.2
 Summary: MCP server for Teradata Vantage — SQL execution and native analytics function reference for AI agents
 Project-URL: Homepage, https://github.com/ksturgeon-td/tdsql-mcp
 Project-URL: Repository, https://github.com/ksturgeon-td/tdsql-mcp

{tdsql_mcp-1.4.0 → tdsql_mcp-1.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tdsql-mcp"
-version = "1.4.0"
+version = "1.4.2"
 description = "MCP server for Teradata Vantage — SQL execution and native analytics function reference for AI agents"
 readme = "README.md"
 requires-python = ">=3.10"

{tdsql_mcp-1.4.0 → tdsql_mcp-1.4.2}/skills/teradata-sql-analytics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: teradata-sql-analytics
-description: Load at the start of any Teradata Vantage analytics session. Injects native function guidelines and the full syntax topic index.
+description: Load at the start of any Teradata analytics session. Injects native function guidelines and syntax.
 ---
 
 You are working with a Teradata Vantage database.
@@ -29,6 +29,11 @@ Apply these principles throughout the session:
 **1. Don't assume. Surface uncertainty and tradeoffs.**
 If you know a native function exists but haven't loaded its syntax topic, say so — don't write syntax from training knowledge. When multiple approaches fit (exact vs. approximate vector search, ARIMA vs. Holt-Winters, TD_XGBoost vs. TD_GLM), state the tradeoff and let the user decide. If the schema or task is ambiguous, ask before writing SQL.
 
+**Topic triggers — load these immediately when the task involves:**
+- Apache Iceberg, Delta Lake, Open Table Format, OTF tables, DATALAKE objects, three-tier notation (`datalake.db.table`) → read [syntax/open-table-format.md](syntax/open-table-format.md)
+- S3, Azure Blob, GCS, object store, READ_NOS, WRITE_NOS, CREATE FOREIGN TABLE, NOS foreign tables → read [syntax/object-store.md](syntax/object-store.md)
+- `describe_table` does not work for OTF or foreign tables — use `HELP TABLE` passed through `execute_query` instead
+
 **2. Minimum SQL that solves the problem. Nothing speculative.**
 Don't add columns, CTEs, or transformations that weren't requested. At Teradata scale, unnecessary work has real cost. Load only the syntax topics needed for the current task.
 

{tdsql_mcp-1.4.0 → tdsql_mcp-1.4.2}/skills/teradata-sql-analytics/syntax/catalog-views.md

@@ -98,31 +98,15 @@ WHERE DatabaseName = 'mydb' AND TableName = 'mytable'
 ORDER BY ColumnName;
 ```
 
-## Listing Accessible Databases
-
-Prefer the `list_databases` MCP tool — it calls `DBC.DatabasesV` which already filters to databases visible to the current session.
-
-`DBC.DatabasesV` answers "what databases exist and are visible to me?"  
-`DBC.AllRightsV` answers "what databases do I have explicit rights on?" (includes role-inherited grants)
-
-Use `DBC.AllRightsV` when you need to know what rights a specific user holds:
-
+## Access Rights
 ```sql
--- Databases a user has rights on (includes role-inherited grants)
-SELECT DISTINCT DatabaseName
-FROM DBC.AllRightsV
-WHERE UserName = 'some_user'
-ORDER BY DatabaseName;
-
--- Full rights detail for a user
+-- What access does the current user have on a database?
 SELECT AccessRight, DatabaseName, TableName
-FROM DBC.AllRightsV
-WHERE UserName = 'some_user'
+FROM DBC.UserRightsV
+WHERE UserName = USER
 ORDER BY DatabaseName, TableName;
 ```
 
-> **Do not use `DBC.UserRightsV` for database enumeration** — it shows only directly granted rights and misses role-inherited access. Use `DBC.AllRightsV` for a complete picture.
-
 ## Common Lookup Patterns
 ```sql
 -- Fully qualified table info in one query
@@ -149,7 +133,6 @@ These views cover registered datalakes, external servers, and OTF statistics. Th
 ### DBC.DatalakeInfoV — Registered Datalakes
 
 ```sql
--- All registered datalakes and their properties
 SELECT DatalakeName, CatalogType, CatalogURL,
        ObjectStoragePlatform, AuthorizationName, CommentString
 FROM DBC.DatalakeInfoV
@@ -161,7 +144,6 @@ Columns include: `DatalakeName`, `CatalogType` (hive/glue/unity/rest/fabric), `C
 ### DBC.ServerV — External Servers
 
 ```sql
--- All external server objects (includes datalakes)
 SELECT ServerName, ServerType, AuthorizationName, CommentString
 FROM DBC.ServerV
 ORDER BY ServerType, ServerName;
@@ -169,8 +151,6 @@ ORDER BY ServerType, ServerName;
 
 ### DBC.ManagedOTFTablesV — Managed OTF Tables
 
-Lists OTF tables that Teradata has registered as managed (created via Vantage DDL rather than discovered from the catalog):
-
 ```sql
 SELECT DatalakeName, DatabaseName, TableName, TableFormat,
        CreateTimeStamp, LastAlterTimeStamp
@@ -180,24 +160,17 @@ ORDER BY DatalakeName, DatabaseName, TableName;
 
 ### DBC.OtfStatsV — OTF Statistics
 
-Statistics collected on OTF table columns (via COLLECT STATISTICS with three-tier notation):
-
 ```sql
--- Statistics collected on OTF tables
 SELECT DatabaseName, TableName, ColumnName, StatsType,
        LastCollectTimeStamp, SampleSize
 FROM DBC.OtfStatsV
 WHERE DatabaseName = 'my_lake'
 ORDER BY TableName, ColumnName;
--- DatabaseName here is the datalake name
 ```
 
 ### DBC.AllStatsV — All Statistics (Teradata + OTF)
 
-Combined view of statistics across both relational Teradata tables and OTF tables:
-
 ```sql
--- All stats (TD + OTF) for a database
 SELECT DatabaseName, TableName, ColumnName, StatsType,
        LastCollectTimeStamp
 FROM DBC.AllStatsV

{tdsql_mcp-1.4.0 → tdsql_mcp-1.4.2}/skills/teradata-sql-analytics/syntax/data-prep.md

@@ -329,8 +329,6 @@ FROM db.campaign;
 
 Generates synthetic minority-class samples to address class imbalance in training data. Supports four oversampling strategies: standard SMOTE, ADASYN, Borderline-SMOTE, and SMOTE-NC (for mixed numeric + categorical features).
 
-> **Required:** The `ON` clause must be written as `ON ... AS InputTable PARTITION BY ANY`. Both `AS InputTable` and `PARTITION BY ANY` are required — omitting either will cause an error.
-
 > **Output contains synthetic samples only** — `UNION ALL` with the original training table to produce the full augmented dataset before training.
 
 ```sql
@@ -359,7 +357,7 @@ SELECT * FROM TD_SMOTE(
 SELECT * FROM db.training_table
 UNION ALL
 SELECT * FROM TD_SMOTE(
-    ON db.training_table AS InputTable PARTITION BY ANY
+    ON db.training_table PARTITION BY ANY
     USING
         IDColumn('id')
         ResponseColumn('label')
@@ -409,7 +407,7 @@ SELECT StatValue AS MedianValue FROM TD_UnivariateStatistics(
 
 -- Step 3: run TD_SMOTE with smotenc
 SELECT * FROM TD_SMOTE(
-    ON db.training_table AS InputTable PARTITION BY ANY
+    ON db.training_table PARTITION BY ANY
     ON db.smote_encodings AS EncodingsTable DIMENSION
     USING
         IDColumn('id')

{tdsql_mcp-1.4.0 → tdsql_mcp-1.4.2}/skills/teradata-sql-analytics/syntax/guidelines.md

@@ -6,8 +6,6 @@ Teradata Vantage has built-in distributed table operators for most analytics, ML
 
 **Before writing any SQL for analytics, transformation, or ML: check this guide and the relevant syntax topic.**
 
-> **Never write native table operator syntax from training knowledge.** Functions like `nPath`, `TD_XGBoost`, `TD_HNSW`, UAF functions, and `AI_*` functions have complex, version-specific parameter names, clause ordering, and required options. Training data knowledge of these functions is frequently incomplete or incorrect. This guide tells you **which** function to use — you must call `get_syntax_help(topic='<name>')` to load the authoritative syntax before writing any native function call.
-
 ---
 
 ## Minimize Data Movement — Critical at Teradata Scale
@@ -197,31 +195,6 @@ Native functions distribute across all AMPs. The result set returned to the agen
 | External TF-IDF | `TD_TFIDF` | `text-analytics` |
 | External word embeddings | `TD_WordEmbeddings` | `text-analytics` |
 
-### LLM-Powered Text Analytics (AI_* Functions)
-
-> **Prerequisites:** Requires an authorization object and LLM provider configuration before use. See `authorization-objects` and `llm-providers` topics. All functions use `TD_SYSFNLIB.<FunctionName>(ON ...)` — do **not** add a `PARTITION BY` clause.
-
-| Instead of this | Use this (native function) | Topic |
-|-----------------|---------------------------|-------|
-| External/post-hoc sentiment scoring | `AI_AnalyzeSentiment` | `ai-text-analytics` |
-| Per-row LLM API calls with question + context data | `AI_AskLLM` (two-table: InputTable + ContextTable, co-partitioned by key) | `ai-text-analytics` |
-| External language detection | `AI_DetectLanguage` | `ai-text-analytics` |
-| External key phrase extraction | `AI_ExtractKeyPhrases` | `ai-text-analytics` |
-| External PII masking | `AI_MaskPII` (detects PII + returns `Masked_Phrase` with `*` replacement) | `ai-text-analytics` |
-| External NER (general named entities — people, places, orgs, dates) | `AI_RecognizeEntities` | `ai-text-analytics` |
-| External PII entity detection (structured metadata, no masking) | `AI_RecognizePIIEntities` | `ai-text-analytics` |
-| External text classification with custom label set | `AI_TextClassifier` — supports single-label and multi-label | `ai-text-analytics` |
-| External summarization | `AI_TextSummarize` — supports 1–5 compression levels | `ai-text-analytics` |
-| External translation | `AI_TextTranslate` | `ai-text-analytics` |
-
-**NER/PII function selection:**
-
-| Need | Function |
-|------|----------|
-| General named entities (people, places, orgs, dates) | `AI_RecognizeEntities` |
-| PII detection + masked text output | `AI_MaskPII` |
-| PII detection + structured metadata only (no masking) | `AI_RecognizePIIEntities` |
-
 ### Vector Search
 
 | Instead of this | Use this (native function) | Topic |
@@ -230,68 +203,6 @@ Native functions distribute across all AMPs. The result set returned to the agen
 | External approximate nearest neighbor index | `TD_HNSW` / `TD_HNSWPredict` | `vector-search` |
 | External embedding storage type | `VECTOR` / `Vector32` data type | `data-types-casting` |
 
-**Inline NL Query → Embedding → Vector Search:** For RAG retrieval, use the full CTE pipeline pattern — embed the query inline with `AI_TEXTEMBEDDINGS`, normalize with `TD_VectorNormalize(Approach('UNITVECTOR'))`, and search with `TD_VectorDistance` against a pre-built corpus embedding table, all in a single SQL statement. See `vector-search` topic, "Inline NL Query → Embedding → Vector Search Pipeline" section.
-
-**Building a corpus embedding table:** Use the full workflow: source text table → `AI_TEXTEMBEDDINGS` → `TD_VectorNormalize(Approach('UNITVECTOR'))` → CTAS. See `vector-search` topic, "Full Corpus Build Workflow" section.
-
-**Vector dimension introspection:** Use `embedding.LENGTH()` to get the number of dimensions from a VECTOR column — never infer from UDT byte size. `SELECT embedding.LENGTH() AS dims FROM db.table SAMPLE 1;`
-
-**Finding the embedding model for an existing corpus:** Query `TD_SYSAI.TD_CollectionsV` or `TD_SYSAI.TD_VectorStores` to discover the model name, provider, and embedding size used to build a corpus. The query pipeline must use the exact same model — mismatched embeddings produce meaningless scores. See `vector-search` topic, "Discovering Existing Vector Stores" section.
-
-### Embeddings
-
-| Scenario | Use this | Topic |
-|----------|---------|-------|
-| REST-based embedding API (Azure, AWS Bedrock, GCP, NVIDIA NIM, LiteLLM) | `AI_TextEmbeddings` with `OutputFormat('VECTOR')` | `embeddings` |
-| In-database inference — no external API (air-gapped or latency-sensitive) | `ONNXEmbeddings` — model stored as BLOB in Vantage; requires tokenizer table | `embeddings`, `byom-model-loading` |
-| Classical word/document embeddings (GloVe-style) | `TD_WordEmbeddings` | `text-analytics` |
-| Store embeddings for reuse | CTAS with `VECTOR` column, then `TD_VectorNormalize(Approach('UNITVECTOR'))` at storage time | `embeddings`, `vector-search` |
-| Build fast approximate search index | `TD_HNSW` on normalized VECTOR column | `vector-search` |
-
-> **Always use `OutputFormat('VECTOR')`** when embeddings will be stored, normalized, or used with `TD_VectorDistance` / `TD_HNSW` / `TD_HNSWPredict`. The `VECTOR` type integrates directly with all vector search functions. See `data-types-casting` for VECTOR sizing (bytes, not dimensions).
-
-### JSON Data
-
-| Operation | Use this | Topic |
-|-----------|---------|-------|
-| Store JSON in a column | Native `JSON` type — `JSON(n)`, `STORAGE FORMAT BSON\|UBJSON` | `json-functions` |
-| Extract a scalar value from JSON | `JSONExtractValue('$.path')` or dot notation `j.field` | `json-functions` |
-| Extract multiple values / array | `JSONExtract('$..field')` → JSON array | `json-functions` |
-| Type-safe extraction (returns NULL on failure) | `JSONGETVALUE(j, '$.age' AS INTEGER)` | `json-functions` |
-| Check if a JSON path exists | `j.ExistValue('$.path')` → 1/0 | `json-functions` |
-| List all key paths in a document | `JSON_KEYS(ON (...) USING QUOTES('N'))` | `json-functions` |
-| Validate JSON string before loading | `JSON_CHECK('...')` → 'OK' or 'INVALID: reason' | `json-functions` |
-| Validate BSON binary before loading | `BSON_CHECK(bytes_col)` → 'OK' or 'INVALID: reason' | `json-functions` |
-| Convert binary JSON to text | `j.AsJSONText()` | `json-functions` |
-| Convert JSON to BSON | `j.AsBSON()` or `CAST(j AS JSON STORAGE FORMAT BSON)` | `json-functions` |
-| Estimate storage size | `j.StorageSize('BSON')` | `json-functions` |
-| SQL rows → JSON doc (simple) | `SELECT AS JSON col1, col2 FROM t` | `json-functions` |
-| SQL rows → JSON doc (hierarchical) | `JSON_COMPOSE(col, JSON_AGG(...) AS nested)` | `json-functions` |
-| SQL rows → JSON doc (any format, >64K) | `JSON_PUBLISH` table operator | `json-functions` |
-| JSON → relational rows (JSONPath) | `JSON_TABLE(ON (...) USING ROWEXPR(...) COLEXPR(...))` | `json-functions` |
-| JSON → relational rows (fast, CLOB) | `TD_JSONSHRED(ON (...) USING ROWEXPR(...) COLEXPR(...) RETURNTYPES(...))` | `json-functions` |
-| JSON → existing relational tables | `CALL SYSLIB.JSON_SHRED_BATCH(...)` | `json-functions` |
-| NVP string → JSON | `NVP2JSON('k=v&k2=v2')` | `json-functions` |
-| Vantage ARRAY → JSON | `ARRAY_TO_JSON(arr_col)` | `json-functions` |
-| ST_Geometry ↔ GeoJSON | `GeoJSONFromGeom(geom)` / `GeomFromGeoJSON(json, srid)` | `json-functions` |
-
-### BYOM — Bring Your Own Model
-
-Apply externally trained models to in-database data without moving data out of Teradata. All scoring functions share the same two-table pattern: `InputTable` + `ModelTable DIMENSION`. See `byom-model-loading` topic for model ingestion; see `byom-scoring` for full syntax.
-
-| Instead of this | Use this (native function) | Topic |
-|-----------------|---------------------------|-------|
-| Running PMML model inference externally | `PMMLPredict` | `byom-scoring` |
-| Running H2O MOJO or Driverless AI model externally | `H2OPredict` (supports contributions, stage probabilities, leaf node assignments) | `byom-scoring` |
-| Running ONNX tabular model externally | `ONNXPredict` (use `ShowModelInputFieldsMap('true')` to inspect tensor mapping) | `byom-scoring` |
-| Running Dataiku Thin JAR externally | `DataikuPredict` (model_id = fully qualified Java class name) | `byom-scoring` |
-| Running DataRobot Scoring Code externally | `DataRobotPredict` (cast DATE/TIMESTAMP to VARCHAR before scoring) | `byom-scoring` |
-| Running MLeap model externally | `MLeapPredict` | `byom-scoring` |
-| In-database text generation / seq-to-seq (translation, summarization) | `ONNXSeq2Seq` — ONNX transformer, no external API | `byom-scoring` |
-| In-database text classification (transformer) | `ONNXClassification` — supports softmax, argmax, custom output column mapping | `byom-scoring` |
-
-> **Architecture distinction:** `ONNXSeq2Seq` and `ONNXClassification` run Hugging Face ONNX transformer models entirely in-database. For REST-based LLM text tasks (sentiment, PII, translation, summarization), use the `AI_*` functions in `ai-text-analytics` instead.
-
 ### Statistical Testing
 
 | Instead of this | Use this (native function) | Topic |
@@ -397,7 +308,7 @@ For any non-trivial query, run `explain_query` before executing. Read the plan a
 - `duplicated on all AMPs` on a small table — correct broadcast strategy
 - `execute the following steps in parallel` — independent steps dispatched concurrently
 
-For full EXPLAIN interpretation guidance, optimization playbook, stats collection patterns, and hash function reference (HASHROW/HASHBUCKET/HASHAMP/HASHBAKAMP for PI skew analysis): `get_syntax_help(topic="query-tuning")`.
+For full EXPLAIN interpretation guidance, optimization playbook, and stats collection patterns: `get_syntax_help(topic="query-tuning")`.
 
 ---
 
@@ -431,8 +342,8 @@ Native functions do not cover everything. Use hand-written SQL for:
 - CASE expressions and NULL handling (`conditional`)
 - Window functions for lag/lead features, running totals (`window-functions`)
 - Schema discovery via MCP tools first — `list_databases`, `list_tables`, `describe_table` cover the common cases; fall back to manual DBC.* queries only for capabilities not covered by those tools (`catalog-views`)
-- Bit/byte manipulation — `BITAND`, `BITOR`, `BITXOR`, `BITNOT`, `SHIFTLEFT`/`SHIFTRIGHT`, `ROTATELEFT`/`ROTATERIGHT`, `GETBIT`, `SETBIT`, `COUNTSET`, `SUBBITSTR`, `TO_BYTE` — all Teradata-specific functions, **no ANSI equivalents**; do not use `&`, `|`, `^`, `~` operators (`bit-byte-functions`)
-- JSON data — native `JSON` type with BSON/UBJSON binary formats; JSONPath extraction; shredding (JSON→relational) and publishing (relational→JSON) — all in-database (`json-functions`)
+- Bit/byte manipulation — `BITAND`, `BITOR`, `BITXOR`, `BITNOT`, `SHIFTLEFT`/`SHIFTRIGHT`, `ROTATELEFT`/`ROTATERIGHT`, `GETBIT`, `SETBIT`, `COUNTSET`, `SUBBITSTR`, `TO_BYTE` — no ANSI equivalents; do not use `&`, `|`, `^`, `~` operators (`bit-byte-functions`)
+- JSON data — native `JSON` type with BSON/UBJSON binary formats; JSONPath extraction; shredding and publishing — all in-database (`json-functions`)
 - One-off computations not covered by any native function
 
 If you are unsure whether a native function exists for an operation, call `get_syntax_help(topic='index')` and check.

{tdsql_mcp-1.4.0 → tdsql_mcp-1.4.2}/skills/teradata-sql-analytics/syntax/index.md

@@ -75,7 +75,7 @@ Use `get_syntax_help(topic="<name>")` to load any topic below.
 | Topic | Description |
 |-------|-------------|
 | `catalog-views` | DBC.* system views for schema discovery |
-| `query-tuning` | EXPLAIN, PI design, hash functions (HASHROW/HASHBUCKET/HASHAMP/HASHBAKAMP), skew detection, collect stats, query rewrite tips |
+| `query-tuning` | EXPLAIN, PI design, collect stats, query rewrite tips |
 | `authorization-objects` | CREATE/REPLACE/GRANT authorization objects for external service credentials (AI functions, external procedures) |
 | `llm-providers` | LLM provider argument blocks for AI functions — Azure, AWS Bedrock, GCP, NVIDIA NIM, LiteLLM |
 | `byom-model-loading` | Loading PMML, H2O MOJO, ONNX, Dataiku, DataRobot, and MLeap models into Teradata BYOM tables; conversion workflow for ONNX embedding models |

tdsql_mcp-1.4.2/skills/teradata-sql-analytics/syntax/query-tuning.md

@@ -0,0 +1,152 @@
+# Teradata Query Tuning & EXPLAIN
+
+## EXPLAIN
+Validate syntax and preview the execution plan without running the query:
+```sql
+EXPLAIN SELECT col1, col2 FROM db.table WHERE id = 1;
+
+-- Dynamic EXPLAIN: better for correlated subqueries, multi-level nesting,
+-- or queries where intermediate sizes dramatically change the plan
+DYNAMIC EXPLAIN SELECT col1, col2 FROM db.table WHERE id = 1;
+```
+
+Use `explain_query` before executing any non-trivial query. If the plan shows critical issues (see below), fix and re-EXPLAIN before running.
+
+### EXPLAIN Phrase Glossary
+
+| Phrase | Optimizer Intent |
+|--------|-----------------|
+| `single-AMP RETRIEVE by way of the unique primary index` | Best-case tactical access — no spool, no redistribution |
+| `by way of an all-rows scan` | Full table scan — examine predicates, stats, and partitioning |
+| `redistributed by hash code` | Row movement to co-locate join keys — check skew risk |
+| `duplicated on all AMPs` | Broadcast small input to all AMPs — verify it's truly small |
+| `(group_amps)` | Spool built on subset of AMPs — potential skew signal |
+| `(all_amps)` | Spool built on every AMP — expected for large tables |
+| `SORT to order Spool n by row hash` | Preparing for merge/hash join |
+| `estimated with no confidence` | Missing statistics — unreliable cardinality estimate |
+| `estimated with low confidence` | Partial or stale statistics — conservative planning |
+| `estimated with high confidence` | Good statistics — optimizer has reliable estimates |
+| `index join confidence` | Optimizer used index stats — reliable |
+| `execute the following steps in parallel` | Independent sub-steps dispatched concurrently |
+| `RowHash match scan` | Join driven by rowhash ordering |
+| `eliminating duplicate rows` | DISTINCT or duplicate removal in spool |
+| `hash join` | Standard large-table join — efficient when well-sized |
+| `merge join` | Sorted join — efficient when inputs already sorted by join key |
+| `product join` | Cartesian join — almost always a problem on large tables |
+| `nested join` | Driven by index — efficient for small outer inputs |
+
+### Severity Classification
+
+**Critical — fix before executing:**
+- `no confidence` on large tables
+- `product join` on large tables (potential Cartesian explosion)
+- `all-rows scan` on very large tables (>1M rows) without a clear reason
+- Steps consuming >15% of total estimated time
+- `(group_amps)` materializing on very few AMPs (severe skew)
+- Massive intermediate spool (>1 GB estimated)
+
+**Warning — should investigate:**
+- `low confidence` on join or filter columns
+- Steps consuming 5–15% of total estimated time
+- Large redistributions (>500 MB spool)
+- Secondary index scans with large result sets
+- Multiple sequential redistributions
+- Missing partition elimination on a partitioned table
+
+**Good — plan is efficient:**
+- `single-AMP RETRIEVE by way of the unique primary index`
+- `high confidence` or `index join confidence` estimates
+- `duplicated on all AMPs` on a provably small table
+- `execute the following steps in parallel`
+- Spool `(Last Use)` markers correctly placed (spool freed promptly)
+- Local aggregation (no redistribution needed)
+
+## Collect Statistics
+Missing stats = bad plans. Collect on PI columns, join columns, and WHERE-clause columns:
+```sql
+COLLECT STATISTICS ON db.table COLUMN (id);
+COLLECT STATISTICS ON db.table COLUMN (customer_id, order_date);  -- composite
+COLLECT STATISTICS ON db.table INDEX (primary_index_col);
+```
+
+## Primary Index (PI) Design Principles
+- The PI determines how rows are distributed across AMPs
+- Good PI: high cardinality, frequently used in joins/filters
+- Bad PI: low cardinality (e.g., boolean, status) → AMP skew
+- Check for skew:
+```sql
+SELECT Hashamp() + 1 AS amp, COUNT(*) AS row_count
+FROM db.table
+GROUP BY Hashamp()
+ORDER BY row_count DESC;
+```
+
+## NoPI Tables (Staging / Load)
+```sql
+CREATE MULTISET TABLE db.staging_table, NO PRIMARY INDEX AS
+(SELECT * FROM db.source WHERE 1=0);
+```
+Use NoPI for temp/staging tables where you don't know the access pattern yet.
+
+## Volatile Tables (Session-Scoped Temp Tables)
+```sql
+CREATE VOLATILE TABLE tmp_results AS (
+    SELECT customer_id, SUM(amount) AS total
+    FROM db.orders
+    GROUP BY customer_id
+) WITH DATA
+ON COMMIT PRESERVE ROWS;
+
+-- Use in subsequent queries
+SELECT * FROM tmp_results WHERE total > 1000;
+```
+Volatile tables exist only for the session duration — no cleanup needed.
+
+## Derived Tables vs CTEs
+Both are equivalent in Teradata. CTEs are generally more readable:
+```sql
+-- CTE (preferred for multi-step logic)
+WITH base AS (SELECT ... FROM db.t WHERE ...),
+     agg  AS (SELECT id, SUM(val) FROM base GROUP BY id)
+SELECT * FROM agg;
+```
+
+## Filtering Early
+Push filters as close to the base table as possible:
+```sql
+-- Better: filter before join
+SELECT a.*, b.name
+FROM (SELECT * FROM db.orders WHERE order_date >= CURRENT_DATE - 30) a
+JOIN db.customers b ON a.customer_id = b.id;
+
+-- Worse: filter after join
+SELECT a.*, b.name
+FROM db.orders a JOIN db.customers b ON a.customer_id = b.id
+WHERE a.order_date >= CURRENT_DATE - 30;
+```
+
+## Avoiding Common Anti-Patterns
+```sql
+-- Avoid functions on indexed columns in WHERE (prevents PI lookup)
+-- Bad:
+WHERE EXTRACT(YEAR FROM order_date) = 2024
+-- Better:
+WHERE order_date BETWEEN DATE '2024-01-01' AND DATE '2024-12-31'
+
+-- Avoid implicit type conversions in joins
+-- Bad (CHAR vs VARCHAR mismatch):
+WHERE char_col = varchar_col
+-- Better: explicit CAST
+WHERE CAST(char_col AS VARCHAR(50)) = varchar_col
+
+-- Avoid SELECT * in production queries — enumerate needed columns
+```
+
+## Session-Level Tuning
+```sql
+-- Show current session info
+SELECT * FROM DBC.SessionInfoV WHERE SessionNo = SESSION;
+
+-- Increase spool space limit for a session (if you have rights)
+-- Usually set by DBA at user/profile level
+```

{tdsql_mcp-1.4.0 → tdsql_mcp-1.4.2}/skills/teradata-sql-analytics/syntax/sql-basics.md

@@ -118,21 +118,6 @@ CREATE TABLE db.my_table AS (
 -- CREATE OR REPLACE TABLE does not exist — to replace: DROP then CREATE, or use a staging pattern
 ```
 
-### CREATE USER — DEFAULT CHARACTER SET
-
-```sql
--- WRONG: CHARACTER SET is not valid at the user level
-CREATE USER myuser AS PASSWORD = 'secret' CHARACTER SET UNICODE;
-
--- RIGHT: the clause is DEFAULT CHARACTER SET
-CREATE USER myuser AS
-    PASSWORD = 'secret'
-    DEFAULT DATABASE = mydb
-    DEFAULT CHARACTER SET UNICODE;
-```
-
-> **`DEFAULT CHARACTER SET`**, not `CHARACTER SET`, is the correct syntax in `CREATE USER` and `MODIFY USER`. Using `CHARACTER SET` alone will fail.
-
 ### Other DDL reminders
 ```sql
 -- Teradata uses MINUS, not EXCEPT (already noted in Set Operations above)
@@ -140,75 +125,15 @@ CREATE USER myuser AS
 -- Semicolons: required in BTEQ; optional in most client tools
 ```
 
-## Reserved Words and Identifier Quoting
+## Reserved Words as Column Names in Table Operator Clauses
 
-Quote any identifier (column, table, alias) that conflicts with a reserved word using **double quotes**:
+When a column name is a Teradata reserved word (e.g. `type`, `date`, `time`, `value`, `name`, `format`, `title`), it must be double-quoted. In regular SQL projections this looks normal:
 
 ```sql
-SELECT id, "type", "format" FROM db.events;
-
-CREATE TABLE db.events (
-    id       INTEGER,
-    "type"   VARCHAR(30),   -- reserved word — must quote
-    label    VARCHAR(100)
-) PRIMARY INDEX (id);
+SELECT "type", "date" FROM db.my_table;
 ```
 
-> **Quoted identifiers are case-sensitive.** Use consistent casing — `"type"` and `"TYPE"` are different identifiers.
-
-### Teradata-Specific Reserved Words — Common Identifier Conflicts
-
-The ANSI SQL reserved words are well-known. The words below are **Teradata-only** — not in the ANSI SQL-99 standard — so agents may not recognize them as reserved. Always quote these when using them as column, table, or alias names.
-
-**Words that frequently appear as column or table names:**
-
-| Reserved word | Commonly appears as | TD since |
-|--------------|---------------------|----------|
-| `TYPE` | transaction type, event type, record type | V2R3 |
-| `FORMAT` | file format, output format, date format | V2R3 |
-| `TITLE` | document title; also controls the TD column display header | V2R3 |
-| `MODE` | processing mode, run mode, lock mode | V2R3 |
-| `ACCOUNT` | account_id, account-related tables | V2R3 |
-| `LOG` | log tables, audit logs, log level | V2R3 |
-| `LOCK` | lock status, concurrency tables | V2R3 |
-| `HASH` | hash keys, checksums, deduplication columns | V2R3 |
-| `REQUEST` | request_id, API and service event tables | V2R3 |
-| `STATISTICS` | monitoring tables, collected stats columns | V2R3 |
-| `JOURNAL` | financial journals, transaction audit logs | V2R3 |
-| `CLUSTER` | cluster_id, partition or segment label | V2R3 |
-| `NAMED` | TD column alias syntax (`expr (NAMED alias)`) — risky as a column name | V2R3 |
-| `RANK` | search rank, priority rank, competition rank | V2R3 |
-| `DATABASE` | database name columns in catalog/metadata tables | V2R3 |
-| `PERCENT` | percent_change, completion_percent, analytics columns | V2R3 |
-| `ENABLED` / `DISABLED` | feature flag columns, configuration status | V2R3 |
-| `CLASS` | object class, classification, CSS class | V2R5 |
-| `PROFILE` | user profiles, configuration profiles | V2R5 |
-| `SUMMARY` | summary text columns, reporting tables | V2R5 |
-| `THRESHOLD` | alert thresholds, monitoring limit columns | V2R5 |
-| `TRACE` | trace_id, debug or telemetry columns | V2R5 |
-
-**Teradata SQL extension keywords — these are clause keywords, not identifiers:**
-
-| Keyword | Purpose |
-|---------|---------|
-| `QUALIFY` | Filters window function results — like WHERE for OVER clauses; not in ANSI SQL |
-| `SAMPLE` | Random row sampling: `SELECT * FROM t SAMPLE 100` or `SAMPLE .05` |
-| `VOLATILE` | Session-scoped temp table: `CREATE VOLATILE TABLE ...` |
-| `LOCKING` | Lock modifier: `LOCKING TABLE t FOR ACCESS SELECT ...` |
-| `REPLACE` | TD DDL: `REPLACE VIEW` — not `CREATE OR REPLACE` |
-| `EXPLAIN` | Execution plan: `EXPLAIN SELECT ...` |
-| `FALLBACK` | Table-level data protection option at `CREATE TABLE` time |
-| `MULTISET` | Table type allowing duplicate rows: `CREATE MULTISET TABLE ...` |
-| `MACRO` | Stored parameterized query: `CREATE MACRO ...` |
-| `COLLECT` | Statistics collection: `COLLECT STATISTICS ON db.t COLUMN (col)` |
-| `BT` / `ET` | Begin Transaction / End Transaction |
-| `SEL` | Shorthand for `SELECT` |
-| `DEL` / `INS` / `UPD` | Shorthands for DELETE / INSERT / UPDATE — `DEL` and `INS` can appear as column aliases in CDC/audit schemas |
-| `CM` / `CT` / `CD` / `CS` / `CV` / `SS` / `UC` | Additional 2-letter Teradata BTEQ abbreviations — all reserved |
-
-### Reserved Words in Table Operator String Arguments
-
-In table operator clauses that take column names as **string arguments** (`Accumulate`, `IDColumn`, `TargetColumns`, `ResponseColumn`, etc.), double-quotes must be embedded **inside** the single-quoted string:
+In table operator string arguments (`ACCUMULATE`, `IDColumn`, `TargetColumns`, `Accumulate`, etc.), the double-quotes must be embedded **inside** the single-quoted string:
 
 ```sql
 -- WRONG: 'type' is a reserved word — Teradata will reject or misparse this
@@ -218,16 +143,19 @@ USING IDColumn('id') Accumulate('type', 'value')
 USING IDColumn('id') Accumulate('"type"', '"value"')
 ```
 
-This applies to any table operator clause that takes column names as string arguments:
+This applies to **any** table operator clause that takes column names as string arguments:
 
 ```sql
+-- All of these follow the same rule
 IDColumn('"type"')
 TargetColumns('"value"', '"date"', 'non_reserved_col')
 Accumulate('"type"', 'amount', '"date"')
 ResponseColumn('"value"')
 ```
 
-**When in doubt, quote it.** Double-quoting a non-reserved word inside a string argument is harmless; leaving a reserved word unquoted will cause a parse error.
+**When in doubt, quote it.** Double-quoting a non-reserved word in a string argument is harmless; leaving a reserved word unquoted will cause a parse error.
+
+Common Teradata reserved words that appear as column names: `type`, `date`, `time`, `timestamp`, `value`, `name`, `format`, `title`, `level`, `mode`, `status`, `class`, `key`, `index`, `year`, `month`, `day`, `hour`, `minute`, `second`.
 
 ## Teradata Operator Differences
 
@@ -251,29 +179,20 @@ WHERE status <> 'active'
 
 ### Three-Tier Dot Notation (OTF Tables)
 
-Open Table Format tables (Iceberg, Delta Lake) use three-tier notation: `datalake.database.table`. Database references use two tiers: `datalake.database`.
+Open Table Format tables (Iceberg, Delta Lake) use three-tier notation: `datalake.database.table`.
 
 ```sql
--- Query OTF table
 SELECT * FROM my_lake.sales_db.orders WHERE order_date >= DATE '2024-01-01';
 
 -- Join OTF table with a relational table
 SELECT o.order_id, c.name
 FROM my_lake.sales_db.orders o
 JOIN mydb.customers c ON o.customer_id = c.customer_id;
-
--- CTAS from OTF into a relational table
-CREATE TABLE mydb.orders_local AS (
-    SELECT * FROM my_lake.sales_db.orders
-) WITH DATA;
-
--- Reference OTF database
-HELP DATABASE my_lake.sales_db;
 ```
 
 ### HELP Commands — Pass Through as-is
 
-`HELP DATALAKE`, `HELP DATABASE`, and `HELP TABLE` are first-class Teradata statements for OTF and foreign table metadata. Pass them through `execute_query` exactly as written — do NOT rewrite as SELECT queries against DBC views.
+`HELP DATALAKE`, `HELP DATABASE`, and `HELP TABLE` are first-class Teradata statements for OTF and foreign table metadata. Pass them through `execute_query` exactly as written — do NOT rewrite as SELECT queries.
 
 ```sql
 HELP DATALAKE my_lake;                    -- list databases in datalake
@@ -282,12 +201,10 @@ HELP TABLE my_lake.sales_db.orders;       -- describe OTF table columns
 HELP TABLE mydb.my_foreign_table;         -- describe foreign table columns
 ```
 
-`describe_table` (which queries `DBC.ColumnsV`) does not work for OTF tables or NOS foreign tables. Always use `HELP TABLE` for schema inspection of these table types.
+`describe_table` (which queries `DBC.ColumnsV`) does not work for OTF tables or NOS foreign tables.
 
 ### READ_NOS — Two Equivalent Calling Forms
 
-You may encounter READ_NOS written in two forms — both are valid and produce identical results:
-
 ```sql
 -- Explicit form — generate this when writing new SQL
 SELECT * FROM READ_NOS (
@@ -304,5 +221,3 @@ SELECT * FROM (
   RETURNTYPE='NOSREAD_KEYS'
 ) AS d;
 ```
-
-Always generate the explicit `READ_NOS(USING(...))` form when writing new SQL.