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.
Files changed (58) hide show
  1. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/PKG-INFO +3 -1
  2. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/README.md +2 -0
  3. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/pyproject.toml +6 -1
  4. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/authorization-objects.md +31 -3
  5. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/bit-byte-functions.md +1 -1
  6. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/guidelines.md +6 -5
  7. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/index.md +3 -1
  8. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/object-store.md +2 -2
  9. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/open-table-format.md +4 -4
  10. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/path-analysis.md +30 -0
  11. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/sql-basics.md +49 -0
  12. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/text-analytics.md +48 -0
  13. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-utility.md +1 -1
  14. tdsql_mcp-1.5.0/skills/teradata-sql-analytics/syntax/vector-collections.md +270 -0
  15. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/vector-search.md +2 -0
  16. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/src/tdsql_mcp/server.py +46 -17
  17. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/.claude-plugin/plugin.json +0 -0
  18. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/.env.example +0 -0
  19. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/.gitignore +0 -0
  20. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/CLAUDE.md +0 -0
  21. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/docs/architecture.md +0 -0
  22. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/requirements.txt +0 -0
  23. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/README.md +0 -0
  24. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/SKILL.md +0 -0
  25. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/aggregate-functions.md +0 -0
  26. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/ai-text-analytics.md +0 -0
  27. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/association-analysis.md +0 -0
  28. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/byom-model-loading.md +0 -0
  29. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/byom-scoring.md +0 -0
  30. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/catalog-views.md +0 -0
  31. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/conditional.md +0 -0
  32. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/data-cleaning.md +0 -0
  33. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/data-exploration.md +0 -0
  34. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/data-prep.md +0 -0
  35. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/data-types-casting.md +0 -0
  36. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/date-time.md +0 -0
  37. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/embeddings.md +0 -0
  38. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/fit-transform-pattern.md +0 -0
  39. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/geospatial.md +0 -0
  40. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/hypothesis-testing.md +0 -0
  41. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/json-functions.md +0 -0
  42. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/llm-providers.md +0 -0
  43. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/ml-functions.md +0 -0
  44. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/ml-patterns.md +0 -0
  45. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/model-evaluation.md +0 -0
  46. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/numeric-functions.md +0 -0
  47. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/query-tuning.md +0 -0
  48. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/string-functions.md +0 -0
  49. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-concepts.md +0 -0
  50. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-data-prep.md +0 -0
  51. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-diagnostics.md +0 -0
  52. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-dsp.md +0 -0
  53. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-estimation.md +0 -0
  54. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-forecasting.md +0 -0
  55. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/uaf-formula-rules.md +0 -0
  56. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/utility-functions.md +0 -0
  57. {tdsql_mcp-1.4.5 → tdsql_mcp-1.5.0}/skills/teradata-sql-analytics/syntax/window-functions.md +0 -0
  58. {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.4.5
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.4.5"
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"
@@ -1,6 +1,6 @@
1
1
  # Teradata Authorization Objects
2
2
 
3
- Authorization objects store external service credentials securely inside Teradata, decoupling
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 **only** when using the `AS DEFINER` or `AS INVOKER` forms in an `EXTERNAL SECURITY` clause. Not needed for plain auth. |
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
@@ -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 alone would act as '0000FFFF'XB is NOT correct: it acts as 'FFFF0000'XB (upper bytes)
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 resolved column list for a view or derived query
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 | Manual SQL pattern (ROW_NUMBER + QUALIFY) | `data-cleaning` |
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)` on very few AMPs | Data skew | Check for skewed join key values |
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, and stats collection patterns: `get_syntax_help(topic="query-tuning")`.
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: describe_table Does Not Work for Foreign Tables
23
+ ## CRITICAL: DBC.ColumnsV-Based Schema Tools Do Not Work for Foreign Tables
24
24
 
25
- `describe_table` queries `DBC.ColumnsV`, which does not cover foreign tables. To inspect a foreign table's columns, use:
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;
@@ -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. Pass them through `execute_query` as-is:
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 this, NOT describe_table)
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
- `describe_table` queries `DBC.ColumnsV`, which does not cover OTF tables. Always use `HELP TABLE` for OTF table schema inspection.
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
- Use `execute_query` to run these — they query the external catalog, not DBC views.
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 must come from a computation (e.g. `1.0/0.0`), not a literal.
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
- if cur.description is None:
172
+ sets = _read_result_sets(cur, max_rows)
173
+ if not sets:
145
174
  return json.dumps({"rows": [], "row_count": 0, "truncated": False})
146
- columns = [desc[0] for desc in cur.description]
147
- rows = cur.fetchmany(max_rows)
148
- result = [
149
- dict(zip(columns, (_maybe_parse_json(v) for v in row)))
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
- return json.dumps({"status": "success", "rowcount": cur.rowcount}, default=str)
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