tdsql-mcp 1.4.5__tar.gz → 1.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/PKG-INFO +3 -1
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/README.md +2 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/pyproject.toml +6 -1
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/authorization-objects.md +31 -3
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/bit-byte-functions.md +1 -1
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/guidelines.md +6 -5
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/index.md +3 -1
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/object-store.md +2 -2
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/open-table-format.md +4 -4
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/path-analysis.md +30 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/sql-basics.md +49 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/text-analytics.md +48 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-utility.md +1 -1
- tdsql_mcp-1.5.0/skills/teradata-sql-analytics/syntax/vector-collections.md +270 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/vector-search.md +2 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/src/tdsql_mcp/server.py +46 -17
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/.claude-plugin/plugin.json +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/.env.example +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/.gitignore +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/CLAUDE.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/docs/architecture.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/requirements.txt +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/README.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/SKILL.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/aggregate-functions.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/ai-text-analytics.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/association-analysis.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/byom-model-loading.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/byom-scoring.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/catalog-views.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/conditional.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/data-cleaning.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/data-exploration.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/data-prep.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/data-types-casting.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/date-time.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/embeddings.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/fit-transform-pattern.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/geospatial.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/hypothesis-testing.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/json-functions.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/llm-providers.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/ml-functions.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/ml-patterns.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/model-evaluation.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/numeric-functions.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/query-tuning.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/string-functions.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-concepts.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-data-prep.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-diagnostics.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-dsp.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-estimation.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-forecasting.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-formula-rules.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/utility-functions.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/window-functions.md +0 -0
- {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/src/tdsql_mcp/__init__.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: tdsql-mcp
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.5.0
|
|
4
4
|
Summary: MCP server for Teradata Vantage — SQL execution and native analytics function reference for AI agents
|
|
5
5
|
Project-URL: Homepage, https://github.com/ksturgeon-td/tdsql-mcp
|
|
6
6
|
Project-URL: Repository, https://github.com/ksturgeon-td/tdsql-mcp
|
|
@@ -572,6 +572,8 @@ No code changes needed — the tool auto-discovers `.md` files at call time. Top
|
|
|
572
572
|
|
|
573
573
|
`truncated: true` means more rows were available beyond the `max_rows` limit. Increase `max_rows` or add a `TOP N` / `WHERE` clause to your query.
|
|
574
574
|
|
|
575
|
+
**Stored procedures (`CALL`).** Procedures return their rows (including `status` / `err_info` result sets) after the first result set. `execute_query` returns the first result set that has columns in `rows`; any further result sets are listed under `additional_result_sets` with the same three keys. `execute_statement` adds a `result_sets` array to its response when a statement returns any (plain DDL/DML responses are unchanged).
|
|
576
|
+
|
|
575
577
|
## Notes
|
|
576
578
|
|
|
577
579
|
- The server establishes a persistent connection on startup and automatically reconnects on failure.
|
|
@@ -546,6 +546,8 @@ No code changes needed — the tool auto-discovers `.md` files at call time. Top
|
|
|
546
546
|
|
|
547
547
|
`truncated: true` means more rows were available beyond the `max_rows` limit. Increase `max_rows` or add a `TOP N` / `WHERE` clause to your query.
|
|
548
548
|
|
|
549
|
+
**Stored procedures (`CALL`).** Procedures return their rows (including `status` / `err_info` result sets) after the first result set. `execute_query` returns the first result set that has columns in `rows`; any further result sets are listed under `additional_result_sets` with the same three keys. `execute_statement` adds a `result_sets` array to its response when a statement returns any (plain DDL/DML responses are unchanged).
|
|
550
|
+
|
|
549
551
|
## Notes
|
|
550
552
|
|
|
551
553
|
- The server establishes a persistent connection on startup and automatically reconnects on failure.
|
|
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "tdsql-mcp"
|
|
7
|
-
version = "1.
|
|
7
|
+
version = "1.5.0"
|
|
8
8
|
description = "MCP server for Teradata Vantage — SQL execution and native analytics function reference for AI agents"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.10"
|
|
@@ -42,3 +42,8 @@ tdsql-mcp = "tdsql_mcp.server:main"
|
|
|
42
42
|
[tool.hatch.build.targets.wheel]
|
|
43
43
|
packages = ["src/tdsql_mcp"]
|
|
44
44
|
|
|
45
|
+
|
|
46
|
+
# src/tdsql_mcp/syntax is a symlink to the skill's syntax dir, which hatch does
|
|
47
|
+
# not follow; force-include the real files so the wheel ships the topics.
|
|
48
|
+
[tool.hatch.build.targets.wheel.force-include]
|
|
49
|
+
"skills/teradata-sql-analytics/syntax" = "tdsql_mcp/syntax"
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/authorization-objects.md
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Teradata Authorization Objects
|
|
2
2
|
|
|
3
|
-
Authorization objects store external service credentials
|
|
3
|
+
Authorization objects store external service credentials inside Teradata, decoupling
|
|
4
4
|
secrets from SQL code. They are used by NOS table operators (`READ_NOS`, `WRITE_NOS`),
|
|
5
5
|
external object access via `CREATE FOREIGN TABLE` and `CREATE DATALAKE`, and AI inference
|
|
6
6
|
functions (`AI_TextEmbeddings` and others).
|
|
@@ -9,6 +9,11 @@ Rather than embedding credentials directly in SQL, you reference a named authori
|
|
|
9
9
|
Credentials are stored once, managed centrally, and access is controlled via standard
|
|
10
10
|
Teradata permissions.
|
|
11
11
|
|
|
12
|
+
> **Partial secrecy:** The `PASSWORD` and `SESSION_TOKEN` values are not exposed by the catalog,
|
|
13
|
+
> but the `USER` value is **not secret** — it is readable in `DBC.AuthorizationsV` (column
|
|
14
|
+
> `OSUserName`) by anyone who can query that view. Keep only non-sensitive identifiers
|
|
15
|
+
> (access key ID, account name, base URL, project) in `USER`.
|
|
16
|
+
|
|
12
17
|
---
|
|
13
18
|
|
|
14
19
|
## CREATE / REPLACE AUTHORIZATION
|
|
@@ -37,7 +42,7 @@ EXTERNALID 'external_id_value'
|
|
|
37
42
|
| *(none — plain)* | **Recommended for DATALAKE and foreign tables.** Can be created in any database the creator has `CREATE AUTHORIZATION` on (including global databases). Referenced as `EXTERNAL SECURITY <db>.<auth>` with no keywords. |
|
|
38
43
|
| `AS DEFINER` | Shared access. Auth must be in the **same database** as the referencing object. Referenced as `EXTERNAL SECURITY DEFINER TRUSTED <auth>` (unqualified only — Error 3706 if qualified). |
|
|
39
44
|
| `AS INVOKER` | Exclusive access by the creating user; created in the user's own database. Referenced as `EXTERNAL SECURITY INVOKER TRUSTED <auth>`. |
|
|
40
|
-
| `TRUSTED` | Required
|
|
45
|
+
| `TRUSTED` | Required in the `CREATE`/`REPLACE` statement (`AS DEFINER TRUSTED` / `AS INVOKER TRUSTED`) **and** in the matching `EXTERNAL SECURITY` reference. Omitting it is not a syntax error: `AS DEFINER` without `TRUSTED` fails at runtime with error 5359 ("Not authorized on 2 nodes"). Not needed for plain auth. |
|
|
41
46
|
|
|
42
47
|
**Form 2 — ASSUME_ROLE:**
|
|
43
48
|
- `AUTHSERVICETYPE` — only supported value is `'ASSUME_ROLE'`
|
|
@@ -200,7 +205,10 @@ CREATE AUTHORIZATION db.td_gen_litellm_auth
|
|
|
200
205
|
USER '<litellm_base_url>'
|
|
201
206
|
PASSWORD '<litellm_api_key>';
|
|
202
207
|
|
|
203
|
-
-- Rotate credentials without dropping (use REPLACE)
|
|
208
|
+
-- Rotate credentials without dropping (use REPLACE).
|
|
209
|
+
-- REPLACE also CREATES the object if the name does not exist (no error), so a misspelled name
|
|
210
|
+
-- silently adds a second object and leaves the old credentials in place.
|
|
211
|
+
-- Confirm the change in DBC.AuthorizationsV afterwards.
|
|
204
212
|
REPLACE AUTHORIZATION db.td_gen_aws_auth
|
|
205
213
|
USER '<new_access_key>'
|
|
206
214
|
PASSWORD '<new_secret_key>';
|
|
@@ -249,6 +257,26 @@ to every database that references them, and grant to roles rather than individua
|
|
|
249
257
|
|
|
250
258
|
---
|
|
251
259
|
|
|
260
|
+
## Catalog View — DBC.AuthorizationsV
|
|
261
|
+
|
|
262
|
+
```sql
|
|
263
|
+
SELECT AuthorizationName, AuthorizationType, OSUserName, AuthServiceType
|
|
264
|
+
FROM DBC.AuthorizationsV
|
|
265
|
+
WHERE DatabaseName = 'mydb';
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
| Column | Notes |
|
|
269
|
+
|--------|-------|
|
|
270
|
+
| `AuthorizationName` | Object name |
|
|
271
|
+
| `AuthorizationType` | `U` = plain, `S` = AS DEFINER, `T` = AS INVOKER |
|
|
272
|
+
| `OSUserName` | The `USER` value in clear text (not secret — see note above) |
|
|
273
|
+
| `AuthServiceType` | `Default` for plain/DEFINER/INVOKER; `Temporary Credentials` for objects created with `SESSION_TOKEN` |
|
|
274
|
+
|
|
275
|
+
Use this view to confirm a `CREATE`, verify a `REPLACE`, or check for accidental duplicates.
|
|
276
|
+
`CREATE` on an existing name fails with error 6937 ("Authorization already exists"); `REPLACE` on a missing name silently creates a new object (see REPLACE note above).
|
|
277
|
+
|
|
278
|
+
---
|
|
279
|
+
|
|
252
280
|
## DROP AUTHORIZATION
|
|
253
281
|
|
|
254
282
|
```sql
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/bit-byte-functions.md
RENAMED
|
@@ -115,7 +115,7 @@ SELECT BITXOR(flags_col, 8) AS toggled FROM db.t;
|
|
|
115
115
|
|
|
116
116
|
-- Mask lower 2 bytes of an INTEGER — use a full-width mask; short mask is right-padded
|
|
117
117
|
SELECT BITAND(some_int_col, '0000FFFF'XB) AS lower_two_bytes FROM db.t;
|
|
118
|
-
-- 'FFFF'XB
|
|
118
|
+
-- 'FFFF'XB acts as 'FFFF0000'XB (upper bytes), NOT '0000FFFF'XB — always write masks at full width
|
|
119
119
|
```
|
|
120
120
|
|
|
121
121
|
---
|
|
@@ -158,7 +158,8 @@ SELECT TOP 1 * FROM db.large_table;
|
|
|
158
158
|
-- RIGHT: SHOW TABLE returns DDL (column names, types, constraints) — no data scan
|
|
159
159
|
SHOW TABLE db.large_table;
|
|
160
160
|
|
|
161
|
-
-- RIGHT: SHOW SELECT returns the
|
|
161
|
+
-- RIGHT: SHOW SELECT returns DDL — for tables, the column list; for system views, the underlying base-table DDL
|
|
162
|
+
-- (not the view's projected columns). Behavior on user-defined views may differ.
|
|
162
163
|
SHOW SELECT * FROM db.my_view;
|
|
163
164
|
SHOW SELECT * FROM db.large_table;
|
|
164
165
|
```
|
|
@@ -191,7 +192,7 @@ Load `get_syntax_help(topic="catalog-views")` for DBC view syntax and the full T
|
|
|
191
192
|
|-------------------------------|---------------------------|-------|
|
|
192
193
|
| Manual CASE-based outlier detection | `TD_OutlierFilterFit` / `TD_OutlierFilterTransform` | `data-cleaning` |
|
|
193
194
|
| Manual COALESCE / UPDATE for NULL fill | `TD_SimpleImputeFit` / `TD_SimpleImputeTransform` | `data-cleaning` |
|
|
194
|
-
| Manual ROW_NUMBER deduplication |
|
|
195
|
+
| Manual ROW_NUMBER deduplication | `QUALIFY ROW_NUMBER() OVER (...) = 1` — the idiomatic Teradata pattern; no dedicated native function | `data-cleaning` |
|
|
195
196
|
| Find rows containing NULLs | `TD_GetRowsWithMissingValues` / `TD_GetRowsWithoutMissingValues` | `data-cleaning` |
|
|
196
197
|
| Identify low-variance / useless columns | `TD_GetFutileColumns` | `data-cleaning` |
|
|
197
198
|
| String fuzzy matching / distance | `StringSimilarity` | `data-cleaning` |
|
|
@@ -314,7 +315,7 @@ Load `get_syntax_help(topic="catalog-views")` for DBC view syntax and the full T
|
|
|
314
315
|
| External autocorrelation / partial autocorrelation | `TD_ACF` / `TD_PACF` | `uaf-estimation` |
|
|
315
316
|
| External differencing for stationarity | `TD_DIFF` / `TD_UNDIFF` | `uaf-estimation` |
|
|
316
317
|
| External Fourier transform / frequency analysis | `TD_DFFT` / `TD_POWERSPEC` / `TD_LINESPEC` | `uaf-dsp` |
|
|
317
|
-
| External convolution / digital filtering | `TD_CONVOLVE` (with `TD_FILTERFACTORY1D` coefficients) | `uaf-dsp`, `uaf-utility` |
|
|
318
|
+
| External convolution / digital filtering | `TD_CONVOLVE` (with `TD_FILTERFACTORY1D` coefficients) ⚠ See `uaf-utility` — `TD_FILTERFACTORY1D` can insert millions of rows; use a UPI table and verify row count | `uaf-dsp`, `uaf-utility` |
|
|
318
319
|
| External wavelet transform | `TD_DWT` / `TD_IDWT` | `uaf-dsp` |
|
|
319
320
|
| External time series anomaly detection | `TD_IQR` | `uaf-data-prep` |
|
|
320
321
|
| External DTW similarity | `TD_DTW` | `uaf-forecasting` |
|
|
@@ -363,7 +364,7 @@ For any non-trivial query, run `EXPLAIN` on it before executing. Read the plan a
|
|
|
363
364
|
| `product join` | Potential Cartesian explosion | Check join conditions; add missing predicate |
|
|
364
365
|
| `all-rows scan` on large table | Full table scan | Check if PI filter or index is applicable |
|
|
365
366
|
| `redistributed by hash code` on large spool | Expensive data movement | Consider PI alignment or pre-staged table |
|
|
366
|
-
| `(group_amps)`
|
|
367
|
+
| `(group_amps)` | Inter-AMP work — not a skew signal by itself; confirm skew with a `HASHAMP()` distribution query | `query-tuning` covers the skew diagnostic |
|
|
367
368
|
|
|
368
369
|
**Green flags — plan is efficient:**
|
|
369
370
|
- `single-AMP RETRIEVE by way of the unique primary index` — best-case access
|
|
@@ -371,7 +372,7 @@ For any non-trivial query, run `EXPLAIN` on it before executing. Read the plan a
|
|
|
371
372
|
- `duplicated on all AMPs` on a small table — correct broadcast strategy
|
|
372
373
|
- `execute the following steps in parallel` — independent steps dispatched concurrently
|
|
373
374
|
|
|
374
|
-
For full EXPLAIN interpretation guidance, optimization playbook,
|
|
375
|
+
For full EXPLAIN interpretation guidance, optimization playbook, stats collection, hash-distribution skew detection, and query rewrite patterns: `get_syntax_help(topic="query-tuning")`.
|
|
375
376
|
|
|
376
377
|
---
|
|
377
378
|
|
|
@@ -45,6 +45,7 @@ Use `get_syntax_help(topic="<name>")` to load any topic below.
|
|
|
45
45
|
| `model-evaluation` | Model evaluation and explainability: TD_TrainTestSplit, TD_ClassificationEvaluator, TD_RegressionEvaluator, TD_ROC, TD_Silhouette, TD_SHAP |
|
|
46
46
|
| `ml-patterns` | End-to-end ML pipeline patterns: CTE prediction pipeline, elbow method, train/evaluate/retrain loop, class imbalance workflow, micromodeling |
|
|
47
47
|
| `vector-search` | Vector similarity search: TD_VectorDistance (exact), TD_HNSW/TD_HNSWPredict (approximate), KMeans IVF pattern |
|
|
48
|
+
| `vector-collections` | Managed RAG over Teradata tables via TD_SYSAI stored procedures: CreateCollection, Ask, SimilaritySearch, PrepareResponse, UpdateCollection, DestroyCollection, permissions; vs. raw vector functions |
|
|
48
49
|
| `embeddings` | Embedding generation: AI_TextEmbeddings (cloud/NIM REST), ONNXEmbeddings (in-database BYOM), TD_WordEmbeddings; store → normalize → index → search pipeline |
|
|
49
50
|
| `ai-text-analytics` | LLM-powered text analytics: AI_AnalyzeSentiment, AI_AskLLM, AI_DetectLanguage, AI_ExtractKeyPhrases, AI_MaskPII, AI_RecognizeEntities, AI_RecognizePIIEntities, AI_TextClassifier, AI_TextSummarize, AI_TextTranslate |
|
|
50
51
|
|
|
@@ -71,7 +72,7 @@ Use `get_syntax_help(topic="<name>")` to load any topic below.
|
|
|
71
72
|
| `object-store` | Native Object Store: CREATE FOREIGN TABLE, READ_NOS, WRITE_NOS, authorization objects |
|
|
72
73
|
| `catalog-views` | DBC.* system views for schema discovery |
|
|
73
74
|
| `open-table-format` | Apache Iceberg and Delta Lake via external object stores (S3, ADLS, GCS); HELP DATALAKE/DATABASE/TABLE commands; OTF DDL and DML |
|
|
74
|
-
| `query-tuning` | EXPLAIN, PI design, collect stats, query rewrite tips |
|
|
75
|
+
| `query-tuning` | EXPLAIN, PI design, collect stats, hash-distribution skew detection, query rewrite tips |
|
|
75
76
|
| `authorization-objects` | CREATE/REPLACE/GRANT authorization objects for external service credentials (AI functions, external procedures) |
|
|
76
77
|
| `llm-providers` | LLM provider argument blocks for AI functions — Azure, AWS Bedrock, GCP, NVIDIA NIM, LiteLLM |
|
|
77
78
|
| `byom-model-loading` | Loading PMML, H2O MOJO, ONNX, Dataiku, DataRobot, and MLeap models into Teradata BYOM tables; conversion workflow for ONNX embedding models |
|
|
@@ -95,6 +96,7 @@ Recommended topic reading order for common end-to-end tasks. Load these topics i
|
|
|
95
96
|
| **Imbalanced classes** | `data-prep` (TD_SMOTE) → `ml-patterns` (class imbalance workflow) → `model-evaluation` |
|
|
96
97
|
| **Micromodeling (per-segment models)** | `ml-functions` (TD_GLM) → `ml-patterns` (micromodeling) |
|
|
97
98
|
| **Semantic search / RAG embeddings** | `authorization-objects` → `llm-providers` → `embeddings` → `vector-search` |
|
|
99
|
+
| **RAG over a Teradata table (managed)** | `authorization-objects` → `llm-providers` → `vector-collections` |
|
|
98
100
|
| **In-database ONNX inference** | `byom-model-loading` → `embeddings` (ONNXEmbeddings) → `vector-search` |
|
|
99
101
|
| **Time series forecasting (ARIMA)** | `uaf-concepts` → `uaf-data-prep` → `uaf-estimation` → `uaf-forecasting` → `uaf-diagnostics` |
|
|
100
102
|
| **Regression on ordered series** | `uaf-concepts` → `uaf-data-prep` → `uaf-estimation` (TD_LINEAR_REGR / TD_MULTIVAR_REGR) → `uaf-diagnostics` |
|
|
@@ -20,9 +20,9 @@ NOS lets Vantage read from and write to external object storage (S3, Azure Blob/
|
|
|
20
20
|
|
|
21
21
|
---
|
|
22
22
|
|
|
23
|
-
## CRITICAL:
|
|
23
|
+
## CRITICAL: DBC.ColumnsV-Based Schema Tools Do Not Work for Foreign Tables
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
Schema inspection tools that query `DBC.ColumnsV` do not cover foreign tables. To inspect a foreign table's columns, use:
|
|
26
26
|
|
|
27
27
|
```sql
|
|
28
28
|
HELP TABLE [database_name.]foreign_table_name;
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/open-table-format.md
RENAMED
|
@@ -10,7 +10,7 @@ Teradata Vantage supports reading and writing Apache Iceberg and Delta Lake tabl
|
|
|
10
10
|
|
|
11
11
|
## CRITICAL: HELP Commands Are First-Class OTF Statements
|
|
12
12
|
|
|
13
|
-
`HELP DATALAKE`, `HELP DATABASE`, and `HELP TABLE` are the primary OTF metadata discovery commands — they query the external catalog directly. Do NOT rewrite them as `SELECT` queries.
|
|
13
|
+
`HELP DATALAKE`, `HELP DATABASE`, and `HELP TABLE` are the primary OTF metadata discovery commands — they query the external catalog directly. Do NOT rewrite them as `SELECT` queries. Run them as-is with your SQL execution tool:
|
|
14
14
|
|
|
15
15
|
```sql
|
|
16
16
|
-- List databases in a datalake
|
|
@@ -19,11 +19,11 @@ HELP DATALAKE my_datalake;
|
|
|
19
19
|
-- List tables in a datalake database
|
|
20
20
|
HELP DATABASE my_datalake.my_db;
|
|
21
21
|
|
|
22
|
-
-- Describe columns of a datalake table (use
|
|
22
|
+
-- Describe columns of a datalake table (use HELP TABLE, not a DBC.ColumnsV-based tool)
|
|
23
23
|
HELP TABLE my_datalake.my_db.my_table;
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
Schema inspection tools that query `DBC.ColumnsV` do not cover OTF tables. Always use `HELP TABLE` for OTF table schema inspection.
|
|
27
27
|
|
|
28
28
|
---
|
|
29
29
|
|
|
@@ -389,7 +389,7 @@ SELECT * FROM DBC.ServerV WHERE TableFormat = 'iceberg';
|
|
|
389
389
|
|
|
390
390
|
### HELP Commands
|
|
391
391
|
|
|
392
|
-
|
|
392
|
+
Run these as-is with your SQL execution tool — they query the external catalog, not DBC views.
|
|
393
393
|
|
|
394
394
|
```sql
|
|
395
395
|
-- List databases in a datalake
|
|
@@ -357,3 +357,33 @@ FROM nPath(
|
|
|
357
357
|
) AS dt
|
|
358
358
|
GROUP BY 1 ORDER BY 2 DESC;
|
|
359
359
|
```
|
|
360
|
+
|
|
361
|
+
---
|
|
362
|
+
|
|
363
|
+
## TD_PathSummarizer — Path Summary Generation
|
|
364
|
+
|
|
365
|
+
Builds a hierarchical path summary from ordered path-generation data by partition and sequence. Commonly used to materialize a connected tree representation of traversed states, prefixes, and parent-child relationships for downstream analysis.
|
|
366
|
+
|
|
367
|
+
```sql
|
|
368
|
+
TD_PathSummarizer (
|
|
369
|
+
ON { table | view | (query) } AS InputTable
|
|
370
|
+
PARTITION BY partition_column [,...]
|
|
371
|
+
USING
|
|
372
|
+
[ CountColumn('count_column') ]
|
|
373
|
+
[ Delimiter('delimiter') ]
|
|
374
|
+
SeqColumn('sequence_column')
|
|
375
|
+
PartitionNames('partition_column' [,...])
|
|
376
|
+
[ HashCode({ 'true' | 't' | 'yes' | 'y' | '1' |
|
|
377
|
+
'false' | 'f' | 'no' | 'n' | '0' }) ]
|
|
378
|
+
PrefixColumn('prefix_column')
|
|
379
|
+
)
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
> **Notes:**
|
|
383
|
+
> - The input must be aliased as `InputTable`
|
|
384
|
+
> - `SeqColumn`, `PartitionNames`, and `PrefixColumn` are required
|
|
385
|
+
> - `PartitionNames` must match the partition columns in the `PARTITION BY` clause
|
|
386
|
+
> - `CountColumn`, `Delimiter`, and `HashCode` are optional
|
|
387
|
+
> - CLOB columns are not supported in partition columns
|
|
388
|
+
> - The function expects path-generator-shaped sequence and prefix data
|
|
389
|
+
> - Output fields include `node`, `parent`, `children`, `cnt`, `depth`, and `prefix`
|
|
@@ -198,3 +198,52 @@ WHERE status != 'active'
|
|
|
198
198
|
-- RIGHT
|
|
199
199
|
WHERE status <> 'active'
|
|
200
200
|
```
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## External Data Access — Notation and SQL
|
|
205
|
+
|
|
206
|
+
### Three-Tier Dot Notation (OTF Tables)
|
|
207
|
+
|
|
208
|
+
Open Table Format tables (Iceberg, Delta Lake) use three-tier notation: `datalake.database.table`.
|
|
209
|
+
|
|
210
|
+
```sql
|
|
211
|
+
SELECT * FROM my_lake.sales_db.orders WHERE order_date >= DATE '2024-01-01';
|
|
212
|
+
|
|
213
|
+
-- Join OTF table with a relational table
|
|
214
|
+
SELECT o.order_id, c.name
|
|
215
|
+
FROM my_lake.sales_db.orders o
|
|
216
|
+
JOIN mydb.customers c ON o.customer_id = c.customer_id;
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### HELP Commands — Pass Through as-is
|
|
220
|
+
|
|
221
|
+
`HELP DATALAKE`, `HELP DATABASE`, and `HELP TABLE` are first-class Teradata statements for OTF and foreign table metadata. Run them as-is with your SQL execution tool — do NOT rewrite as SELECT queries.
|
|
222
|
+
|
|
223
|
+
```sql
|
|
224
|
+
HELP DATALAKE my_lake; -- list databases in datalake
|
|
225
|
+
HELP DATABASE my_lake.sales_db; -- list tables in OTF database
|
|
226
|
+
HELP TABLE my_lake.sales_db.orders; -- describe OTF table columns
|
|
227
|
+
HELP TABLE mydb.my_foreign_table; -- describe foreign table columns
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
Schema inspection tools that query `DBC.ColumnsV` do not work for OTF tables or NOS foreign tables.
|
|
231
|
+
|
|
232
|
+
### READ_NOS — Two Equivalent Calling Forms
|
|
233
|
+
|
|
234
|
+
```sql
|
|
235
|
+
-- Explicit form — generate this when writing new SQL
|
|
236
|
+
SELECT * FROM READ_NOS (
|
|
237
|
+
USING
|
|
238
|
+
LOCATION ('/S3/s3.amazonaws.com/bucket/path/')
|
|
239
|
+
AUTHORIZATION (my_auth)
|
|
240
|
+
RETURNTYPE ('NOSREAD_KEYS')
|
|
241
|
+
) AS d;
|
|
242
|
+
|
|
243
|
+
-- Implicit shorthand — valid syntax you may see in existing code; do not "fix" it
|
|
244
|
+
SELECT * FROM (
|
|
245
|
+
LOCATION='/S3/s3.amazonaws.com/bucket/path/'
|
|
246
|
+
AUTHORIZATION=my_auth
|
|
247
|
+
RETURNTYPE='NOSREAD_KEYS'
|
|
248
|
+
) AS d;
|
|
249
|
+
```
|
|
@@ -460,6 +460,54 @@ SELECT * FROM TD_TextMorph(
|
|
|
460
460
|
|
|
461
461
|
---
|
|
462
462
|
|
|
463
|
+
## TD_POSTagger — Part-of-Speech Tagging
|
|
464
|
+
|
|
465
|
+
Assigns a part-of-speech (POS) tag (for example `NN`, `VB`, `JJ`) to each word in the input text. Segments text into sentences, tokenizes each sentence, and applies a CRF-based tagger with Viterbi decoding. Emits one output row per token. English only. Commonly used to produce the `POSTagColumn` input for `TD_TextMorph`.
|
|
466
|
+
|
|
467
|
+
```sql
|
|
468
|
+
SELECT * FROM TD_POSTagger(
|
|
469
|
+
ON { db.table | db.view | (query) } AS InputTable PARTITION BY ANY
|
|
470
|
+
USING
|
|
471
|
+
TextColumn('text_col') -- required; column containing input text
|
|
472
|
+
-- allowed types: VARCHAR, CHAR, CLOB
|
|
473
|
+
-- allowed character sets: LATIN or UNICODE
|
|
474
|
+
InputLanguage('en') -- required; 'en' only (English); case-insensitive
|
|
475
|
+
[ Accumulate('id_col', 'date_col') ] -- optional; columns or range to pass through
|
|
476
|
+
-- maximum 2,045 accumulate columns
|
|
477
|
+
[ IsDebug('false') ] -- optional; default 'false'; enables trace diagnostics
|
|
478
|
+
) AS t;
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
**Output columns** (one row per token):
|
|
482
|
+
|
|
483
|
+
| Column | Type | Description |
|
|
484
|
+
|--------|------|-------------|
|
|
485
|
+
| accumulate columns | — | Columns copied from input (via `Accumulate`) |
|
|
486
|
+
| `word_sn` | BIGINT | Sequential word index per input row (starts at 1 for each new row) |
|
|
487
|
+
| `word` | VARCHAR(128) | Token text produced by the tokenizer |
|
|
488
|
+
| `pos_tag` | VARCHAR(8) | POS tag string (Penn Treebank style, e.g. `NN`, `VB`, `JJ`) |
|
|
489
|
+
|
|
490
|
+
> **Notes:**
|
|
491
|
+
> - Input is `PARTITION BY ANY`
|
|
492
|
+
> - English only — `InputLanguage('en')` is the only supported value
|
|
493
|
+
> - Rows where `TextColumn` is NULL or empty are skipped (no tokens emitted)
|
|
494
|
+
> - Contractions and punctuation are split into separate tokens (e.g. `"don't"` → `do`, `n't`; `"Hello,"` → `Hello`, `,`); decimals stay as one token (e.g. `1.60`)
|
|
495
|
+
> - Feed `word` and `pos_tag` into `TD_TextMorph` (via `WordColumn` and `POSTagColumn`) for POS-aware lemmatization
|
|
496
|
+
|
|
497
|
+
**Example:**
|
|
498
|
+
|
|
499
|
+
```sql
|
|
500
|
+
SELECT * FROM TD_POSTagger(
|
|
501
|
+
ON text_inputs AS InputTable PARTITION BY ANY
|
|
502
|
+
USING
|
|
503
|
+
TextColumn('txt')
|
|
504
|
+
InputLanguage('en')
|
|
505
|
+
Accumulate('[1:2]')
|
|
506
|
+
) AS dt1;
|
|
507
|
+
```
|
|
508
|
+
|
|
509
|
+
---
|
|
510
|
+
|
|
463
511
|
## TD_NERExtractor — Named Entity Recognition
|
|
464
512
|
|
|
465
513
|
Extracts named entities from text by matching against dictionary terms or
|
|
@@ -432,4 +432,4 @@ SELECT COUNT(*) FROM orders1 WHERE TD_ISFINITE(sales) = 0;
|
|
|
432
432
|
| `TD_ISNAN(x)` | x is NaN (Not a Number) | x is finite or infinite |
|
|
433
433
|
|
|
434
434
|
> Input: FLOAT. These are typically used to gate data before passing it to `EXECUTE FUNCTION INTO ART` pipelines.
|
|
435
|
-
> `CAST('Infinity' AS FLOAT)` fails with error 2620 — special values
|
|
435
|
+
> `CAST('Infinity' AS FLOAT)` fails with error 2620 — special float values cannot be constructed from literals or SQL arithmetic (`1.0/0.0` fails with error 2618); they arise from UAF function output (e.g. a `TD_PACF` run with extra columns) or host-language injection.
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
# Teradata Vector Collections (TD_SYSAI Stored Procedures)
|
|
2
|
+
|
|
3
|
+
High-level RAG over Teradata tables through the Vector Store SQL interface: a handful of `TD_SYSAI.*` stored procedures that build the embeddings, the index, and the retrieval + answer-generation steps for you. Docs: *Teradata Vector Store User Guide → SQL Interface for Vector Store* (Release 20.00).
|
|
4
|
+
|
|
5
|
+
> **When to use this vs. the raw functions.** Use vector collections when the goal is "ask questions over the text in these tables" and you want embedding generation, indexing, refresh, access control and LLM answering managed in one object. Use `embeddings` + `vector-search` (`AI_TextEmbeddings`, `TD_HNSW`, `TD_VectorDistance`) when you need control over each pipeline step, a custom distance or index layout, or you are not generating answers with an LLM.
|
|
6
|
+
|
|
7
|
+
> **Verification key.** Behavior marked **(verified)** was run on Teradata 20.00.31.96 (VantageCloud 3.4) with AWS Bedrock. Everything else is **documented, unverified**.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Workflow
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
CreateCollection -> CheckCollectionStatus (until 'ready') -> Ask (search + answer, one call)
|
|
15
|
+
-> SimilaritySearch (retrieval only)
|
|
16
|
+
-> PrepareResponse (answer from a context table)
|
|
17
|
+
UpdateCollection (data refresh / schema change) · DestroyCollection (drops all collection objects)
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`CreateCollection` is synchronous for small tables: it returned `collection_status = 'ready'` directly **(verified)**. Still call `CheckCollectionStatus` for large tables.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Reading results and errors
|
|
25
|
+
|
|
26
|
+
Every procedure returns a result set.
|
|
27
|
+
|
|
28
|
+
| Outcome | Result set columns | Notes |
|
|
29
|
+
|---------|--------------------|-------|
|
|
30
|
+
| Success (admin procs) | `collection_name, collection_status, status, message` (Create/Update); `status, message` (Destroy) | `status = 0` |
|
|
31
|
+
| Failure | `status, err_info` | `status = 1` invalid usage (bad JSON, bad value); `status = 2` SQL/model error (e.g. LLM call failed) |
|
|
32
|
+
|
|
33
|
+
**(verified)** Some SQL clients and MCP tools do not return a stored procedure's result set at all (rows come back empty even for failures). If a `CALL` returns nothing, confirm state with:
|
|
34
|
+
|
|
35
|
+
```sql
|
|
36
|
+
SELECT collection_name, collection_status, error_message
|
|
37
|
+
FROM TD_SYSAI.TD_CollectionsV;
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
or use a client that fetches procedure result sets (e.g. `teradatasql` with `cursor.nextset()`).
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## CreateCollection
|
|
45
|
+
|
|
46
|
+
```sql
|
|
47
|
+
CALL TD_SYSAI.CreateCollection(
|
|
48
|
+
'collection_name',
|
|
49
|
+
'CONTENT-BASED', -- collection type (see Limitations)
|
|
50
|
+
'target_database', -- database that receives the collection's index/model objects
|
|
51
|
+
'description',
|
|
52
|
+
'<collection_index_json>', -- source data (required)
|
|
53
|
+
'<collection_parameters_json>', -- embedding/chat models and tuning
|
|
54
|
+
0 -- debug: 1 writes to TD_SYSAI.vector_collection_logs
|
|
55
|
+
);
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**collection_index_json (verified)** — each value is a **list**; `object_names` entries are qualified `db.table` names:
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"object_names": ["demo_user.support_docs"],
|
|
63
|
+
"key_columns": ["doc_id"],
|
|
64
|
+
"metadata_columns": ["category"],
|
|
65
|
+
"data_columns": ["doc_text"]
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
- `data_columns` are the text columns that are embedded. `metadata_columns` are returned with results and usable in filters; they are optional **(verified)**.
|
|
70
|
+
- Using `{"object_names": {"db": ["t"]}}` fails with `object_names must be a List`.
|
|
71
|
+
|
|
72
|
+
**collection_parameters_json (verified)** — minimal working example (AWS Bedrock):
|
|
73
|
+
|
|
74
|
+
```json
|
|
75
|
+
{
|
|
76
|
+
"train_params": {"search_algorithm": "HNSW"},
|
|
77
|
+
"embedding_model": {"model_provider": "aws", "model_id": "amazon.titan-embed-text-v2:0"},
|
|
78
|
+
"chat_model": {"model_provider": "aws", "model_id": "us.anthropic.claude-haiku-4-5-20251001-v1:0"}
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
> **Credentials.** On the test system, `credentials` could be omitted entirely and embedding, search and `Ask` all worked **(verified)**. This is environment-dependent (the cluster had AWS access without per-collection keys); on other systems supply `credentials` inline or confirm the platform default with an administrator. Collection metadata (`GetCollectionInfo`, `TD_CollectionsV`) shows `credentials` as null even when supplied inline **(verified)**. Whether an authorization object (`authorization-objects` topic) can be referenced instead is **not yet confirmed**.
|
|
83
|
+
|
|
84
|
+
> **Never use `debug = 1` with inline credentials.** The debug log (`TD_SYSAI.vector_collection_logs`) records the full parameters JSON, including `api_key` and `api_secret`, in plaintext **(verified)**.
|
|
85
|
+
|
|
86
|
+
> **Chat model IDs go stale.** The documentation example `anthropic.claude-3-haiku-20240307-v1:0` fails with *"This model version has reached the end of its life"*; `anthropic.claude-3-5-haiku-20241022-v1:0` fails the same way. A current Bedrock inference-profile ID (`us.anthropic.claude-haiku-4-5-20251001-v1:0`) worked **(verified)**. Check provider availability before copying IDs.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## CheckCollectionStatus / GetCollectionInfo / ListCollections
|
|
91
|
+
|
|
92
|
+
```sql
|
|
93
|
+
CALL TD_SYSAI.CheckCollectionStatus('c'); -- collection_status, status, message
|
|
94
|
+
CALL TD_SYSAI.GetCollectionInfo('c', 0); -- basic: one row (name, status, type, description, target_database, permission, last_updated, status, message)
|
|
95
|
+
CALL TD_SYSAI.GetCollectionInfo('c', 1); -- detailed: adds error_message, embedding_datatype, use_simd, object/key/metadata/data columns,
|
|
96
|
+
-- search_params, train_params, embedding_model, chat_model, search_strategy, collection_payload ...
|
|
97
|
+
CALL TD_SYSAI.ListCollections(0); -- every collection on the system; Permission = NO_ACCESS for ones you cannot use
|
|
98
|
+
CALL TD_SYSAI.ListCollections(1); -- only collections you are authorized for
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
All **(verified)**. States seen: `ready`, `initialized`, `update_failed`. Types seen in listings: `CONTENT-BASED`, `FILE-CONTENT-BASED`. A missing collection returns `status 1`, `err_info "Collection 'x' does not exist."`.
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## SimilaritySearch (retrieval only)
|
|
106
|
+
|
|
107
|
+
```sql
|
|
108
|
+
CALL TD_SYSAI.SimilaritySearch(
|
|
109
|
+
'collection_name',
|
|
110
|
+
'natural language question', -- or NULL when passing question_vector
|
|
111
|
+
NULL, -- question_vector (NULL = embed the question with the collection's embedding model)
|
|
112
|
+
NULL, -- similarity_search_request_json (NULL = collection defaults)
|
|
113
|
+
0
|
|
114
|
+
);
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Returns one row per hit: `score, DataBaseName, TableName, TD_ID, <key columns>, <metadata columns>, <data columns>`, highest score first **(verified)**. Default `top_k` returned up to 10 rows.
|
|
118
|
+
|
|
119
|
+
**Request JSON — filter, top_k, and persisted results (verified):**
|
|
120
|
+
|
|
121
|
+
```json
|
|
122
|
+
{
|
|
123
|
+
"search_params": {"top_k": 2},
|
|
124
|
+
"filter_params": {"condition": "category <> 'returns'", "style": "PRE-FILTERING"},
|
|
125
|
+
"result_table_name": "demo_user.search_results"
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
- `style` is `PRE-FILTERING` or `POST-FILTERING` — **with a hyphen**. The documentation's underscore form (`PRE_FILTERING`) fails with `Unsupported filter style`.
|
|
130
|
+
- `condition` is a SQL predicate over the metadata columns.
|
|
131
|
+
- With `result_table_name` the hits are also written to that table (created as a NoPI table) and still returned.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Ask (retrieval + answer)
|
|
136
|
+
|
|
137
|
+
```sql
|
|
138
|
+
CALL TD_SYSAI.Ask('collection_name', 'How long do I have to return an item?', NULL, NULL, 0);
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Returns a single `response` column containing the LLM answer grounded in the retrieved rows **(verified)**. `Ask` does not create a result table **(verified)**.
|
|
142
|
+
|
|
143
|
+
The request JSON (4th argument) can override `search_params`, `chat_model`, etc. for this call (e.g. swap a retired chat model without recreating the collection). `search_strategy.search_type` **cannot** be changed per call; `hybrid_search` must be chosen when the collection is created **(verified error: "cannot be updated to hybrid_search")**.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## PrepareResponse (answer from your own context)
|
|
148
|
+
|
|
149
|
+
Generates an answer from a context table you supply — typically the `result_table_name` output of `SimilaritySearch`, optionally after re-ranking or filtering it yourself.
|
|
150
|
+
|
|
151
|
+
```sql
|
|
152
|
+
CALL TD_SYSAI.PrepareResponse('collection_name', 'When can I call support?', 'demo_user.search_results', NULL, 0);
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Returns a single `response` column **(verified)** using a `SimilaritySearch` result table as context. The 4th argument is the same request JSON (e.g. a `chat_model` override).
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## UpdateCollection
|
|
160
|
+
|
|
161
|
+
```sql
|
|
162
|
+
CALL TD_SYSAI.UpdateCollection(
|
|
163
|
+
'collection_name',
|
|
164
|
+
'new description', -- or NULL
|
|
165
|
+
NULL, -- collection_index_json (alter_operation ADD|DELETE, update_style MINOR|MAJOR, metadata_operation ADD|DELETE|MODIFY)
|
|
166
|
+
NULL, -- collection_parameters_json
|
|
167
|
+
NULL, -- New_Collection_Name
|
|
168
|
+
1, -- Data_Refresh: INTEGER, 1 = re-embed new/changed source rows
|
|
169
|
+
0
|
|
170
|
+
);
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
- `Data_Refresh` is numeric; passing `'true'` fails with a string-to-numeric conversion error **(verified)**.
|
|
174
|
+
- After inserting a row into the source table, `Data_Refresh = 1` made it searchable (it became the top hit for a matching question) **(verified)**. Rows added **without** a refresh are not found **(verified)**.
|
|
175
|
+
- Description-only update **(verified)**.
|
|
176
|
+
- MINOR vs MAJOR `update_style`, index alterations, and rename are **documented, unverified**.
|
|
177
|
+
|
|
178
|
+
---
|
|
179
|
+
|
|
180
|
+
## DestroyCollection
|
|
181
|
+
|
|
182
|
+
```sql
|
|
183
|
+
CALL TD_SYSAI.DestroyCollection('collection_name', 0);
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Drops the collection and all objects it created in `target_database` (index table, HNSW model, views) **(verified)**. Your source tables and any `result_table_name` tables are **not** dropped.
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Permissions
|
|
191
|
+
|
|
192
|
+
```sql
|
|
193
|
+
CALL TD_SYSAI.ListCollectionPermissions('collection_name'); -- User_Name, Permission (verified: creator = ADMIN)
|
|
194
|
+
CALL TD_SYSAI.ModifyCollectionPermissions('collection_name',
|
|
195
|
+
'{"user_names": ["alice","bob"], "actions": ["GRANT","REVOKE"], "permissions": ["USER","ADMIN"]}', 0);
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
The three arrays in the JSON are parallel (alice is granted USER, bob has ADMIN revoked). `ModifyCollectionPermissions` is **documented, unverified** — full action/permission lists unconfirmed.
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## Parameter reference (collection_parameters_json blocks)
|
|
203
|
+
|
|
204
|
+
| Block | Keys |
|
|
205
|
+
|-------|------|
|
|
206
|
+
| `embedding_model` | `model_provider` (`aws`\|`azure`\|`gcp`\|`nim`\|`custom`; mandatory on 3.5), `model_id`, `model_modality` (`text`; `multimodal` not on 3.4), `embedding_dims`, `base_url`, `credentials{api_key, api_secret, access_token, project_id, region, arn_role_name, bucket_name}` |
|
|
207
|
+
| `onnx_model` | `model_table, tokenizer_table, model_column, tokenizer_column, model_id_column, tokenizer_id_column, model_id, tokenizer_id` (in-database ONNX embeddings instead of a remote provider) |
|
|
208
|
+
| `chat_model` | `model_provider, model_id, model_modality` (`LLM`; `VLM` not on 3.4), `base_url, max_tokens, prompt, temperature, credentials` |
|
|
209
|
+
| `train_params` | `search_algorithm` (`FLAT`\|`IVF_FLAT`\|`HNSW`), `metric` (`COSINE`\|`EUCLIDEAN`\|`DOTPRODUCT`); IVF_FLAT: `initial_centroids_method` (`RANDOM`\|`KMEANS++`), `train_numcluster, max_iternum, stop_threshold, num_init`; HNSW: `num_layer, ef_construction, num_connPerNode, maxNum_connPerNode, num_NodesPerGraph, apply_heuristics`; `seed` |
|
|
210
|
+
| `search_params` | `top_k` **or** `search_threshold` (not both), `search_numcluster` (IVF_FLAT), `ef_search` (HNSW) |
|
|
211
|
+
| `search_strategy` | `search_type` (`semantic_search`\|`relevance_search`\|`hybrid_search`), `relevance_top_k, relevance_search_threshold`, `scoring_method` (`weighted_sum`\|`rrf`\|`weighted_rrf`), `sparse_weight, rrf_normalizer, maximal_marginal_relevance, lambda_multiplier, mmr_threshold` |
|
|
212
|
+
| top level | `embedding_datatype` (`VECTOR`\|`VECTOR32`), `use_simd, ignore_embedding_errors, batch, enable_inference_profile` |
|
|
213
|
+
|
|
214
|
+
**Defaults observed on 20.00.31.96 (verified):** `VECTOR32`, `use_simd` 0, `COSINE`, `top_k` 10, `relevance_top_k` 60, `semantic_search`; HNSW `num_layer` -1 (auto), `ef_construction` 32, `num_connPerNode` 32, `maxNum_connPerNode` 32, `apply_heuristics` true, `seed` 0; chat `max_tokens` 4096, `temperature` 0.2. `embedding_dims` is filled in from the model (1024 for `amazon.titan-embed-text-v2:0`). These differ from some values shown in the documentation's detailed-info sample; trust `GetCollectionInfo(name, 1)` on your system.
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## Limitations
|
|
219
|
+
|
|
220
|
+
| | Cloud 3.5 (20.00.32.xx) | Cloud 3.4 (20.00.31.xx) |
|
|
221
|
+
|---|---|---|
|
|
222
|
+
| Collection types | `CONTENT-BASED`, `EMBEDDING-BASED` | same |
|
|
223
|
+
| `model_provider` | mandatory | accepted |
|
|
224
|
+
| Ranking model, guardrails, telemetry | not supported | not supported |
|
|
225
|
+
| `image_columns` / `image_columns_info` | supported | not supported |
|
|
226
|
+
| Embedding `model_modality: multimodal` | supported | not supported |
|
|
227
|
+
| Chat `model_modality: VLM` | supported | not supported |
|
|
228
|
+
| `batch` | supported | not supported |
|
|
229
|
+
| Inference profile | supported | not supported |
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
## Documentation issues to know about
|
|
234
|
+
|
|
235
|
+
- JSON templates in the docs are **not literal JSON**: they contain `/* */` comments, `a | b` alternatives, missing quotes/commas (`"EUCLIDEAN | "DOTPRODUCT"`, after `apply_heuristics`), and trailing commas. Build the JSON yourself from this topic.
|
|
236
|
+
- Filter style is `PRE-FILTERING` / `POST-FILTERING` (hyphen), not the underscore form shown.
|
|
237
|
+
- The documented chat model example is retired on Bedrock (see above).
|
|
238
|
+
- `image_column` appears in the procedure signature while limitations say `image_columns`.
|
|
239
|
+
- `FILE-CONTENT-BASED` collections appear in `ListCollections` but are not listed as a supported creation type (an existing one on the test system was created outside this SQL interface; the creation path is unconfirmed).
|
|
240
|
+
- Undocumented procedures exist in `TD_SYSAI` (`RenameCollection`, `GenerateEmbeddings`, `CreateBM25Model`, `GrantCollectionAccess`, `RevokeCollectionAccess`, ...). Do not call them; use the documented ones above.
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## End-to-end example
|
|
245
|
+
|
|
246
|
+
```sql
|
|
247
|
+
-- 1. Create
|
|
248
|
+
CALL TD_SYSAI.CreateCollection('support_kb', 'CONTENT-BASED', 'demo_user', 'Support policies',
|
|
249
|
+
'{"object_names": ["demo_user.support_docs"], "key_columns": ["doc_id"], "metadata_columns": ["category"], "data_columns": ["doc_text"]}',
|
|
250
|
+
'{"train_params": {"search_algorithm": "HNSW"},
|
|
251
|
+
"embedding_model": {"model_provider": "aws", "model_id": "amazon.titan-embed-text-v2:0"},
|
|
252
|
+
"chat_model": {"model_provider": "aws", "model_id": "us.anthropic.claude-haiku-4-5-20251001-v1:0"}}', 0);
|
|
253
|
+
|
|
254
|
+
-- 2. Ready?
|
|
255
|
+
CALL TD_SYSAI.CheckCollectionStatus('support_kb');
|
|
256
|
+
|
|
257
|
+
-- 3a. One-call answer
|
|
258
|
+
CALL TD_SYSAI.Ask('support_kb', 'How long do I have to return an item?', NULL, NULL, 0);
|
|
259
|
+
|
|
260
|
+
-- 3b. Or retrieve, then answer from the retrieved rows
|
|
261
|
+
CALL TD_SYSAI.SimilaritySearch('support_kb', 'When can I call support?', NULL,
|
|
262
|
+
'{"search_params": {"top_k": 3}, "result_table_name": "demo_user.kb_hits"}', 0);
|
|
263
|
+
CALL TD_SYSAI.PrepareResponse('support_kb', 'When can I call support?', 'demo_user.kb_hits', NULL, 0);
|
|
264
|
+
|
|
265
|
+
-- 4. Refresh after the source table changes
|
|
266
|
+
CALL TD_SYSAI.UpdateCollection('support_kb', NULL, NULL, NULL, NULL, 1, 0);
|
|
267
|
+
|
|
268
|
+
-- 5. Clean up
|
|
269
|
+
CALL TD_SYSAI.DestroyCollection('support_kb', 0);
|
|
270
|
+
```
|
|
@@ -6,6 +6,8 @@ Functions for computing vector distances and building approximate nearest-neighb
|
|
|
6
6
|
|
|
7
7
|
> **Dimension introspection:** To get the number of dimensions in a VECTOR column, use the `.LENGTH()` method — do not infer from UDT byte size. `SELECT embedding.LENGTH() AS dims FROM db.embeddings SAMPLE 1;` See `data-types-casting` topic for full VECTOR type reference.
|
|
8
8
|
|
|
9
|
+
> **Managed alternative:** for question answering over table text without hand-building the embed → index → search → LLM pipeline, see `vector-collections` (`TD_SYSAI.CreateCollection` / `Ask` / `SimilaritySearch`).
|
|
10
|
+
|
|
9
11
|
---
|
|
10
12
|
|
|
11
13
|
## TD_VectorDistance
|
|
@@ -120,20 +120,48 @@ def _execute_query_internal(sql: str, params: list | None = None) -> list[dict]:
|
|
|
120
120
|
cur.close()
|
|
121
121
|
|
|
122
122
|
|
|
123
|
+
def _read_result_sets(cur, max_rows: int) -> list[dict]:
|
|
124
|
+
"""Read every result set from an executed cursor.
|
|
125
|
+
|
|
126
|
+
A stored procedure (CALL) returns its rows in a result set after the first,
|
|
127
|
+
so reading only the first set silently drops them. Sets without columns
|
|
128
|
+
(description is [] for DDL/DML and for a CALL's leading placeholder set)
|
|
129
|
+
are skipped.
|
|
130
|
+
"""
|
|
131
|
+
sets = []
|
|
132
|
+
while True:
|
|
133
|
+
if cur.description:
|
|
134
|
+
columns = [desc[0] for desc in cur.description]
|
|
135
|
+
rows = cur.fetchmany(max_rows)
|
|
136
|
+
result = [
|
|
137
|
+
dict(zip(columns, (_maybe_parse_json(v) for v in row)))
|
|
138
|
+
for row in rows
|
|
139
|
+
]
|
|
140
|
+
# Peek to detect truncation without fetching everything
|
|
141
|
+
truncated = cur.fetchone() is not None
|
|
142
|
+
sets.append({"rows": result, "row_count": len(result), "truncated": truncated})
|
|
143
|
+
if not cur.nextset():
|
|
144
|
+
return sets
|
|
145
|
+
|
|
146
|
+
|
|
123
147
|
# ---------------------------------------------------------------------------
|
|
124
148
|
# Tools
|
|
125
149
|
# ---------------------------------------------------------------------------
|
|
126
150
|
|
|
127
151
|
@mcp.tool()
|
|
128
152
|
def execute_query(sql: str, max_rows: int = 100) -> str:
|
|
129
|
-
"""Execute a SQL SELECT query and return results as JSON.
|
|
153
|
+
"""Execute a SQL SELECT query or stored procedure CALL and return results as JSON.
|
|
130
154
|
|
|
131
155
|
Args:
|
|
132
156
|
sql: The SQL query to execute.
|
|
133
|
-
max_rows: Maximum number of rows to return (default 100, capped at 10000).
|
|
157
|
+
max_rows: Maximum number of rows to return per result set (default 100, capped at 10000).
|
|
134
158
|
|
|
135
159
|
Returns:
|
|
136
160
|
JSON object with keys: rows (array), row_count (int), truncated (bool).
|
|
161
|
+
If the statement returns more than one result set (e.g. a CALL that
|
|
162
|
+
returns a status set and a data set), the first is returned in the keys
|
|
163
|
+
above and the rest are listed under additional_result_sets, each with
|
|
164
|
+
the same three keys.
|
|
137
165
|
"""
|
|
138
166
|
max_rows = min(max(1, max_rows), 10_000)
|
|
139
167
|
with _conn_lock:
|
|
@@ -141,20 +169,13 @@ def execute_query(sql: str, max_rows: int = 100) -> str:
|
|
|
141
169
|
cur = conn.cursor()
|
|
142
170
|
try:
|
|
143
171
|
cur.execute(sql)
|
|
144
|
-
|
|
172
|
+
sets = _read_result_sets(cur, max_rows)
|
|
173
|
+
if not sets:
|
|
145
174
|
return json.dumps({"rows": [], "row_count": 0, "truncated": False})
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
for row in rows
|
|
151
|
-
]
|
|
152
|
-
# Peek to detect truncation without fetching everything
|
|
153
|
-
truncated = cur.fetchone() is not None
|
|
154
|
-
return json.dumps(
|
|
155
|
-
{"rows": result, "row_count": len(result), "truncated": truncated},
|
|
156
|
-
default=str,
|
|
157
|
-
)
|
|
175
|
+
result = sets[0]
|
|
176
|
+
if len(sets) > 1:
|
|
177
|
+
result["additional_result_sets"] = sets[1:]
|
|
178
|
+
return json.dumps(result, default=str)
|
|
158
179
|
finally:
|
|
159
180
|
cur.close()
|
|
160
181
|
|
|
@@ -169,7 +190,10 @@ def execute_statement(sql: str) -> str:
|
|
|
169
190
|
sql: The SQL statement to execute.
|
|
170
191
|
|
|
171
192
|
Returns:
|
|
172
|
-
JSON object with keys: status (str), rowcount (int).
|
|
193
|
+
JSON object with keys: status (str), rowcount (int). If the statement
|
|
194
|
+
is a stored procedure CALL that returns result sets (status or error
|
|
195
|
+
rows), they are included under result_sets, each with keys rows,
|
|
196
|
+
row_count and truncated (up to 100 rows per set).
|
|
173
197
|
"""
|
|
174
198
|
_require_write()
|
|
175
199
|
with _conn_lock:
|
|
@@ -177,7 +201,12 @@ def execute_statement(sql: str) -> str:
|
|
|
177
201
|
cur = conn.cursor()
|
|
178
202
|
try:
|
|
179
203
|
cur.execute(sql)
|
|
180
|
-
|
|
204
|
+
rowcount = cur.rowcount
|
|
205
|
+
result = {"status": "success", "rowcount": rowcount}
|
|
206
|
+
sets = _read_result_sets(cur, 100)
|
|
207
|
+
if sets:
|
|
208
|
+
result["result_sets"] = sets
|
|
209
|
+
return json.dumps(result, default=str)
|
|
181
210
|
finally:
|
|
182
211
|
cur.close()
|
|
183
212
|
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/aggregate-functions.md
RENAMED
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/ai-text-analytics.md
RENAMED
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/association-analysis.md
RENAMED
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/byom-model-loading.md
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/data-exploration.md
RENAMED
|
File without changes
|
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/data-types-casting.md
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/fit-transform-pattern.md
RENAMED
|
File without changes
|
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/hypothesis-testing.md
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/model-evaluation.md
RENAMED
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/numeric-functions.md
RENAMED
|
File without changes
|
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/string-functions.md
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-formula-rules.md
RENAMED
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/utility-functions.md
RENAMED
|
File without changes
|
{tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/window-functions.md
RENAMED
|
File without changes
|
|
File without changes
|