diff --git a/AGENTS.md b/AGENTS.md index f26d6e6..a392553 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,10 @@ # Oracle DB Skills — Agent Instructions -This repository is a collection of 128 standalone reference guides for Oracle Database and Oracle Container Registry database-category images. Each file covers one topic with explanations, practical examples, best practices, and common mistakes. +This repository is a collection of 149 standalone reference guides for Oracle Database and Oracle Container Registry database-category images. Each file covers one topic with explanations, practical examples, best practices, and common mistakes. ## How to Use This Collection -1. **Find the right skill** — scan `SKILLS.md` at the repo root for a flat index of all skills with descriptions, or use the category routing below. +1. **Find the right skill** — scan `SKILLS.md` at the repo root for a flat index of all skills with descriptions, or use the category routing below. For AI and containers, prefer the category-specific sub-index when the question is still broad. 2. **Load on demand** — read only the specific skill file(s) relevant to the user's task. Do not attempt to load all files at once. 3. **Apply the guidance** — use the content to answer questions, generate code, or review existing work. @@ -13,6 +13,7 @@ This repository is a collection of 128 standalone reference guides for Oracle Da ``` skills/ ├── admin/ Database administration (backup, recovery, users, redo/undo) +├── ai/ AI Database topics (Select AI, AI Agent, AI Vector Search, RAG guidance) ├── appdev/ Application development (JSON, XML, spatial, text, pooling) ├── architecture/ Infrastructure (RAC, Multitenant, Exadata, In-Memory, OCI) ├── containers/ OCR Database-category container repositories @@ -34,6 +35,7 @@ skills/ | User asks about… | Load from | |------------------|-----------| | Backup, recovery, RMAN, redo/undo logs, users | `skills/admin/` | +| Select AI, Select AI for Python, AI Agent, AI Vector Search, vector indexes, semantic search, RAG on Oracle AI Database | `skills/ai/SKILLS.md` | | JDBC, connection pooling, JSON, XML, spatial, full-text, transactions, property graphs | `skills/appdev/` | | RAC, CDB/PDB, Exadata, In-Memory, OCI, ATP/ADW, Data Guard | `skills/architecture/` | | ERD, data modeling, partitioning, tablespaces | `skills/design/` | @@ -47,10 +49,14 @@ skills/ | Privileges, VPD, TDE, encryption, auditing, network security | `skills/security/` | | SQL patterns, window functions, CTEs, dynamic SQL, injection | `skills/sql-dev/` | | SQLcl commands, scripting, Liquibase CLI, MCP server, CI/CD | `skills/sqlcl/` | -| Oracle Container Registry images, container pull commands, tags, and OCR repository selection | `skills/containers/` | +| Oracle Container Registry images, container pull commands, tags, and OCR repository selection | `skills/containers/SKILLS.md` | ## Key Skills to Know +- **`skills/ai/SKILLS.md`** — task router for the AI category +- **`skills/ai/ai-vector-search.md`** — entry point for Oracle AI Vector Search concepts and routing +- **`skills/ai/select-ai.md`** — entry point for Select AI concepts and routing +- **`skills/ai/select-ai-python.md`** — routing between `select_ai`, SQL, and PL/SQL Select AI use from Python - **`skills/sqlcl/sqlcl-mcp-server.md`** — how to connect AI assistants (including Claude) to Oracle via the SQLcl MCP server - **`skills/migrations/migration-assessment.md`** — start here for any database migration project - **`skills/performance/explain-plan.md`** — foundation for all SQL performance work @@ -58,6 +64,8 @@ skills/ - **`skills/devops/schema-migrations.md`** — Liquibase/Flyway with Oracle in CI/CD pipelines - **`skills/containers/container-selection-matrix.md`** — quick decision matrix for choosing the right OCR database-category image +For the complete AI index and task router: `skills/ai/SKILLS.md` + ## Common Container Skills (Primary) - **`skills/containers/adb-free.md`** — Autonomous Database Free container image with ADW/ATP guidance diff --git a/CLAUDE.md b/CLAUDE.md index ef7801b..1c60531 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## What This Repository Is -A library of 128 standalone Oracle Database and OCR container reference guides (skill files) organized by category under `skills/`. Each file covers one topic with explanations, examples, and version-specific notes. There is no build system, test suite, or compilation step — this is a pure Markdown content library. +A library of 149 standalone Oracle Database and OCR container reference guides (skill files) organized by category under `skills/`. Each file covers one topic with explanations, examples, and version-specific notes. There is no build system, test suite, or compilation step — this is a pure Markdown content library. ## Adding or Modifying Skill Files @@ -35,14 +35,17 @@ These files must stay in sync when skills are added or renamed: | [AGENTS.md](AGENTS.md) | Category routing table for AI agents | | [SKILL.md](SKILL.md) | Root metadata for skills.sh CLI discovery | | [skills-index.md](skills-index.md) | Completion tracking checklist | +| [skills/ai/SKILLS.md](skills/ai/SKILLS.md) | AI sub-index and task router (not counted as a standalone skill) | +| [skills/containers/SKILLS.md](skills/containers/SKILLS.md) | Container sub-index and task router (not counted as a standalone skill) | -When adding a new skill file, update all four of these files. +When adding a new skill file, update the root discovery files above. If the skill is in a category with a local sub-index, update that sub-index too. ## Category Routing | Topic | Directory | |-------|-----------| | Backup, recovery, RMAN, redo/undo, users | `skills/admin/` | +| Select AI, Select AI for Python, AI Agent, AI Vector Search, vector indexes, semantic search, RAG on Oracle AI Database | `skills/ai/SKILLS.md` | | JDBC, connection pooling, JSON, XML, spatial, full-text, transactions, property graphs | `skills/appdev/` | | RAC, CDB/PDB, Exadata, In-Memory, OCI, ATP/ADW, Data Guard | `skills/architecture/` | | ERD, data modeling, partitioning, tablespaces | `skills/design/` | @@ -56,10 +59,14 @@ When adding a new skill file, update all four of these files. | Privileges, VPD, TDE, encryption, auditing, network security | `skills/security/` | | SQL patterns, window functions, CTEs, dynamic SQL, injection | `skills/sql-dev/` | | SQLcl commands, scripting, Liquibase CLI, MCP server, CI/CD | `skills/sqlcl/` | -| Oracle Container Registry images, container pull commands, tags, and OCR repository selection | `skills/containers/` | +| Oracle Container Registry images, container pull commands, tags, and OCR repository selection | `skills/containers/SKILLS.md` | ## Key Starting Points +- [skills/ai/SKILLS.md](skills/ai/SKILLS.md) — task router for the AI category +- [skills/ai/ai-vector-search.md](skills/ai/ai-vector-search.md) — entry point for Oracle AI Vector Search concepts and routing +- [skills/ai/select-ai.md](skills/ai/select-ai.md) — entry point for Select AI concepts and routing +- [skills/ai/select-ai-python.md](skills/ai/select-ai-python.md) — routing between `select_ai`, SQL, and PL/SQL Select AI use from Python - [skills/sqlcl/sqlcl-mcp-server.md](skills/sqlcl/sqlcl-mcp-server.md) — connecting AI assistants to Oracle via the SQLcl MCP server - [skills/migrations/migration-assessment.md](skills/migrations/migration-assessment.md) — start here for any migration project - [skills/performance/explain-plan.md](skills/performance/explain-plan.md) — foundation for SQL performance work diff --git a/README.md b/README.md index 2173ed2..e5ab820 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Oracle DB Skills -Oracle DB Skills is a curated library of 128 practical, documentation-backed guides for working with Oracle Database and Oracle Container Registry database-category images, organized by domain: SQL and PL/SQL development, performance tuning, security, administration, monitoring, architecture, DevOps, migrations, SQLcl, ORDS, Oracle-specific features, and container-image repositories. The guides include actionable examples, best practices, common pitfalls, sources, and Oracle version compatibility notes where relevant. +Oracle DB Skills is a curated library of 149 practical, documentation-backed guides for working with Oracle Database and Oracle Container Registry database-category images, organized by domain: SQL and PL/SQL development, AI Database topics, performance tuning, security, administration, monitoring, architecture, DevOps, migrations, SQLcl, ORDS, Oracle-specific features, and container-image repositories. The guides include actionable examples, best practices, common pitfalls, sources, and Oracle version compatibility notes where relevant. ## Version Coverage Standard @@ -25,6 +25,7 @@ Oracle DB Skills is a curated library of 128 practical, documentation-backed gui | [SQL Development](#sql-development) | 6 | `skills/sql-dev/` | | [Performance & Tuning](#performance--tuning) | 7 | `skills/performance/` | | [Application Development](#application-development) | 14 | `skills/appdev/` | +| [AI Database](#ai-database) | 21 | `skills/ai/` | | [Security](#security) | 6 | `skills/security/` | | [Administration](#administration) | 5 | `skills/admin/` | | [Monitoring & Diagnostics](#monitoring--diagnostics) | 5 | `skills/monitoring/` | @@ -106,6 +107,56 @@ Oracle DB Skills is a curated library of 128 practical, documentation-backed gui --- +## AI Database + +`skills/ai/` + +Complete AI task index: `skills/ai/SKILLS.md` +(`skills/ai/SKILLS.md` is an index helper and is not counted as a standalone skill guide.) + +### Start Here + +| File | Description | +|------|-------------| +| `select-ai.md` | Select AI overview, capability boundaries, and routing guide | +| `ai-vector-search.md` | Oracle AI Vector Search overview, capability boundaries, and routing guide | + +### Select AI + +| File | Description | +|------|-------------| +| `select-ai-accuracy.md` | cross-cutting Select AI accuracy workflow: scope, metadata, inspection, case sensitivity, and feedback | +| `select-ai-annotations.md` | annotation DDL, profile integration, annotation views, and Select AI metadata usage | +| `select-ai-profiles.md` | AI profile lifecycle, attributes, provider configuration, session activation | +| `select-ai-security.md` | privilege model, metadata/data exposure controls, private endpoints, and AI proxy security | +| `select-ai-prompts.md` | prompt wording rules, `showprompt`, prompt augmentation, and action guidance | +| `select-ai-actions.md` | `SELECT AI` / `DBMS_CLOUD_AI.GENERATE` actions, `showprompt`, `chat`, `translate`, `summarize` | +| `select-ai-python.md` | routing between `select_ai`, `SELECT AI`, and package-based Select AI use from Python | +| `select-ai-metadata.md` | `object_list`, metadata controls, comments, annotations, constraints, data access | +| `select-ai-feedback.md` | `feedback` action, `DBMS_CLOUD_AI.FEEDBACK`, feedback vector index, SQL refinement workflow | +| `select-ai-rag.md` | Select AI RAG flow, vector-index integration, `embedding_model`, `enable_sources` | + +### AI Vector Search + +| File | Description | +|------|-------------| +| `vector-data-type.md` | `VECTOR` type definitions, dense/sparse formats, restrictions, vector descriptors | +| `vector-embeddings.md` | ONNX models, third-party embeddings, chunking, `DBMS_VECTOR_CHAIN` pipelines | +| `vector-packages.md` | `DBMS_VECTOR`, `DBMS_VECTOR_CHAIN`, `DBMS_HYBRID_VECTOR`, reranking, generated text, package selection | +| `vector-operations.md` | distance metrics, operators, exact/approximate search, vector SQL functions | +| `vector-indexes.md` | IVF/HNSW, `CREATE VECTOR INDEX`, advisor procedures, restrictions | +| `hybrid-vector-search.md` | `CREATE HYBRID VECTOR INDEX`, `DBMS_HYBRID_VECTOR`, hybrid query patterns | + +### Advanced / Diagnostics + +| File | Description | +|------|-------------| +| `select-ai-agent.md` | `DBMS_CLOUD_AI_AGENT`, teams, agents, tasks, tools, built-in tool support | +| `select-ai-synthetic-data.md` | `GENERATE_SYNTHETIC_DATA`, params, monitoring status tables, metadata-clone workflows | +| `vector-diagnostics.md` | vector views, memory pool, initialization parameters, diagnostic routing | + +--- + ## Security `skills/security/` @@ -305,6 +356,7 @@ oracle-db-skills/ ├── skills-index.md # Full checklist of all files with completion status └── skills/ ├── admin/ # Administration + ├── ai/ # AI Database ├── appdev/ # Application Development ├── architecture/ # Architecture & Infrastructure ├── containers/ # OCR Database-category container repositories diff --git a/SKILL.md b/SKILL.md index f82220f..9ea6ddf 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,15 +1,15 @@ --- name: oracle-db-skills -description: 128 Oracle Database and OCR container reference guides covering SQL, PL/SQL, performance tuning, security, ORDS, SQLcl, container images, migrations, and more. Load individual skill files on demand for expert guidance on any Oracle topic. +description: 149 Oracle Database and OCR container reference guides covering SQL, PL/SQL, AI Database topics, performance tuning, security, ORDS, SQLcl, container images, migrations, and more. Load individual skill files on demand for expert guidance on any Oracle topic. --- # Oracle DB Skills -A collection of 128 standalone reference guides for Oracle Database and OCR database-category container images. Each file covers one topic with explanations, practical examples, best practices, and common mistakes. +A collection of 149 standalone reference guides for Oracle Database and OCR database-category container images. Each file covers one topic with explanations, practical examples, best practices, and common mistakes. ## How to Use -1. **Find the right skill** using the category routing table below. +1. **Find the right skill** using the category routing table below. For AI and containers, prefer the category-specific sub-index when the question is still broad. 2. **Read only the file(s)** relevant to the user's task — do not load all files at once. 3. **Apply the guidance** to answer questions, generate code, or review existing work. @@ -18,6 +18,7 @@ A collection of 128 standalone reference guides for Oracle Database and OCR data | User asks about… | Read from | |------------------|-----------| | Backup, recovery, RMAN, redo/undo logs, users | `skills/admin/` | +| Select AI, Select AI for Python, AI Agent, AI Vector Search, vector indexes, semantic search, RAG on Oracle AI Database | `skills/ai/SKILLS.md` | | JDBC, connection pooling, JSON, XML, spatial, full-text, transactions, property graphs | `skills/appdev/` | | RAC, CDB/PDB, Exadata, In-Memory, OCI, ATP/ADW, Data Guard | `skills/architecture/` | | ERD, data modeling, partitioning, tablespaces | `skills/design/` | @@ -31,13 +32,14 @@ A collection of 128 standalone reference guides for Oracle Database and OCR data | Privileges, VPD, TDE, encryption, auditing, network security | `skills/security/` | | SQL patterns, window functions, CTEs, dynamic SQL, injection | `skills/sql-dev/` | | SQLcl commands, scripting, Liquibase CLI, MCP server, CI/CD | `skills/sqlcl/` | -| Oracle Container Registry images, container pull commands, tags, and OCR repository selection | `skills/containers/` | +| Oracle Container Registry images, container pull commands, tags, and OCR repository selection | `skills/containers/SKILLS.md` | ## Skills Directory ``` skills/ ├── admin/ Database administration (backup, recovery, users, redo/undo) +├── ai/ AI Database topics (Select AI, AI Agent, AI Vector Search, RAG guidance) ├── appdev/ Application development (JSON, XML, spatial, text, pooling) ├── architecture/ Infrastructure (RAC, Multitenant, Exadata, In-Memory, OCI) ├── containers/ OCR Database-category container repositories @@ -56,6 +58,10 @@ skills/ ## Key Starting Points +- **`skills/ai/SKILLS.md`** — task router for the AI category +- **`skills/ai/ai-vector-search.md`** — entry point for Oracle AI Vector Search concepts and routing +- **`skills/ai/select-ai.md`** — entry point for Select AI concepts and routing +- **`skills/ai/select-ai-python.md`** — routing between `select_ai`, SQL, and PL/SQL Select AI use from Python - **`skills/sqlcl/sqlcl-mcp-server.md`** — connecting AI assistants to Oracle via the SQLcl MCP server - **`skills/migrations/migration-assessment.md`** — start here for any database migration project - **`skills/performance/explain-plan.md`** — foundation for all SQL performance work diff --git a/SKILLS.md b/SKILLS.md index c409614..359e000 100644 --- a/SKILLS.md +++ b/SKILLS.md @@ -1,6 +1,6 @@ # Oracle DB Skills -128 Oracle Database and OCR container reference guides for AI agents. Each file is a standalone skill covering one topic with examples, best practices, and common mistakes. +149 Oracle Database and OCR container reference guides for AI agents. Each file is a standalone skill covering one topic with examples, best practices, and common mistakes. **Install:** `npx skills add krisrice/oracle-db-skills` @@ -39,6 +39,27 @@ | `skills/appdev/nodejs-oracledb.md` | appdev | node-oracledb driver, async/await, pools, result sets, LOBs | | `skills/appdev/dotnet-oracle.md` | appdev | ODP.NET managed driver, EF Core, array binding, OracleParameter | | `skills/appdev/golang-oracle.md` | appdev | godror driver, database/sql interface, named binds, REF CURSORs | +| `skills/ai/ai-vector-search.md` | ai | AI Vector Search overview, capability boundaries, and routing to storage, query, index, and hybrid-search skills | +| `skills/ai/hybrid-vector-search.md` | ai | `CREATE HYBRID VECTOR INDEX`, `DBMS_HYBRID_VECTOR`, hybrid query patterns | +| `skills/ai/select-ai.md` | ai | Select AI overview, capability boundaries, and routing to profiles, actions, metadata, feedback, RAG, and agent skills | +| `skills/ai/select-ai-accuracy.md` | ai | cross-cutting Select AI accuracy workflow: scope, metadata, inspection, case sensitivity, and feedback | +| `skills/ai/select-ai-annotations.md` | ai | annotation DDL, profile integration, annotation views, and Select AI metadata usage | +| `skills/ai/select-ai-actions.md` | ai | `SELECT AI` / `DBMS_CLOUD_AI.GENERATE` actions, `showprompt`, `chat`, `translate`, `summarize` | +| `skills/ai/select-ai-agent.md` | ai | `DBMS_CLOUD_AI_AGENT`, teams, agents, tasks, tools, built-in tool support | +| `skills/ai/select-ai-feedback.md` | ai | `feedback` action, `DBMS_CLOUD_AI.FEEDBACK`, feedback vector index, SQL refinement workflow | +| `skills/ai/select-ai-metadata.md` | ai | `object_list`, metadata controls, comments, annotations, constraints, data access | +| `skills/ai/select-ai-prompts.md` | ai | prompt wording rules, `showprompt`, prompt augmentation, action choice, and metadata-based guidance | +| `skills/ai/select-ai-profiles.md` | ai | AI profile lifecycle, attributes, provider configuration, session activation | +| `skills/ai/select-ai-python.md` | ai | routing between `select_ai`, `SELECT AI`, and package-based Select AI use from Python | +| `skills/ai/select-ai-rag.md` | ai | Select AI RAG flow, vector-index integration, `embedding_model`, `enable_sources` | +| `skills/ai/select-ai-security.md` | ai | privilege model, metadata/data exposure controls, private endpoints, and AI proxy security | +| `skills/ai/select-ai-synthetic-data.md` | ai | `GENERATE_SYNTHETIC_DATA`, params, monitoring status tables, metadata-clone workflows | +| `skills/ai/vector-data-type.md` | ai | `VECTOR` type definitions, dense/sparse formats, restrictions, vector descriptors | +| `skills/ai/vector-diagnostics.md` | ai | vector views, memory pool, initialization parameters, diagnostic routing | +| `skills/ai/vector-embeddings.md` | ai | ONNX models, third-party embeddings, chunking, `DBMS_VECTOR_CHAIN` pipelines | +| `skills/ai/vector-packages.md` | ai | `DBMS_VECTOR`, `DBMS_VECTOR_CHAIN`, `DBMS_HYBRID_VECTOR`, reranking, generated text, package selection | +| `skills/ai/vector-indexes.md` | ai | IVF/HNSW, `CREATE VECTOR INDEX`, advisor procedures, restrictions | +| `skills/ai/vector-operations.md` | ai | distance metrics, operators, exact/approximate search, vector SQL functions | | `skills/security/privilege-management.md` | security | Least privilege, roles, DBMS_PRIVILEGE_CAPTURE, avoiding PUBLIC grants | | `skills/security/row-level-security.md` | security | VPD/FGAC, DBMS_RLS, application contexts, all policy types | | `skills/security/data-masking.md` | security | Oracle Data Redaction (DBMS_REDACT), full/partial/regexp/random redaction | diff --git a/skills-index.md b/skills-index.md index 1c14b62..4e4f9df 100644 --- a/skills-index.md +++ b/skills-index.md @@ -47,6 +47,29 @@ A tracking file for skills.md topics to create for working with Oracle DB. - [x] `dotnet-oracle.md` — ODP.NET managed driver, EF Core, array binding, OracleParameter - [x] `golang-oracle.md` — godror driver, database/sql interface, named binds, REF CURSORs +## AI Database +- [x] `ai-vector-search.md` — overview, capability boundaries, and routing to vector storage, SQL, indexing, and hybrid search skills +- [x] `hybrid-vector-search.md` — `CREATE HYBRID VECTOR INDEX`, `DBMS_HYBRID_VECTOR`, hybrid query patterns +- [x] `select-ai.md` — overview, capability boundaries, and routing to profiles, actions, metadata, feedback, RAG, and agent skills +- [x] `select-ai-accuracy.md` — cross-cutting Select AI accuracy workflow: scope, metadata, inspection, case sensitivity, and feedback +- [x] `select-ai-annotations.md` — annotation DDL, profile integration, annotation views, and Select AI metadata usage +- [x] `select-ai-actions.md` — `SELECT AI` / `DBMS_CLOUD_AI.GENERATE` actions, `showprompt`, `chat`, `translate`, `summarize` +- [x] `select-ai-agent.md` — `DBMS_CLOUD_AI_AGENT`, teams, agents, tasks, tools, built-in tool support +- [x] `select-ai-feedback.md` — `feedback` action, `DBMS_CLOUD_AI.FEEDBACK`, feedback vector index, SQL refinement workflow +- [x] `select-ai-metadata.md` — `object_list`, metadata controls, comments, annotations, constraints, data access +- [x] `select-ai-prompts.md` — prompt wording rules, `showprompt`, prompt augmentation, action choice, and metadata-based guidance +- [x] `select-ai-profiles.md` — AI profile lifecycle, attributes, provider configuration, session activation +- [x] `select-ai-python.md` — routing between `select_ai`, `SELECT AI`, and package-based Select AI use from Python +- [x] `select-ai-rag.md` — Select AI RAG flow, vector-index integration, `embedding_model`, `enable_sources` +- [x] `select-ai-security.md` — privilege model, metadata/data exposure controls, private endpoints, and AI proxy security +- [x] `select-ai-synthetic-data.md` — `GENERATE_SYNTHETIC_DATA`, params, monitoring status tables, metadata-clone workflows +- [x] `vector-data-type.md` — `VECTOR` type definitions, dense/sparse formats, restrictions, vector descriptors +- [x] `vector-diagnostics.md` — vector views, memory pool, initialization parameters, diagnostic routing +- [x] `vector-embeddings.md` — ONNX models, third-party embeddings, chunking, `DBMS_VECTOR_CHAIN` pipelines +- [x] `vector-packages.md` — `DBMS_VECTOR`, `DBMS_VECTOR_CHAIN`, `DBMS_HYBRID_VECTOR`, reranking, generated text, package selection +- [x] `vector-indexes.md` — IVF/HNSW, `CREATE VECTOR INDEX`, advisor procedures, restrictions +- [x] `vector-operations.md` — distance metrics, operators, exact/approximate search, vector SQL functions + ## Security - [x] `privilege-management.md` — Least privilege, roles, system vs object privileges - [x] `row-level-security.md` — VPD/FGAC, RLS policies, application contexts diff --git a/skills/ai/SKILLS.md b/skills/ai/SKILLS.md new file mode 100644 index 0000000..562f222 --- /dev/null +++ b/skills/ai/SKILLS.md @@ -0,0 +1,77 @@ +# AI Skills Index + +Complete index for AI-related skills in `skills/ai/`. Start with the overview guides when the question is broad, then load the narrower skill that matches the task. + +## Start Here + +| File | Description | +|------|-------------| +| `select-ai.md` | Select AI overview, capability boundaries, and routing to the right Select AI skill | +| `ai-vector-search.md` | AI Vector Search overview, capability boundaries, and routing to the right vector-search skill | + +## Task Routing + +| If you need to... | Read | +|-------------------|------| +| understand what Select AI covers before choosing an implementation path | `select-ai.md` | +| use Select AI from Python or choose between `select_ai`, SQL, and PL/SQL paths | `select-ai-python.md` | +| manage Select AI conversations, vector indexes, or async object workflows from Python | `select-ai-python.md` | +| improve overall Select AI NL2SQL accuracy | `select-ai-accuracy.md` | +| configure providers, credentials, models, or session activation | `select-ai-profiles.md` | +| secure Select AI with privileges, metadata scoping, data-access controls, private endpoints, or AI proxy patterns | `select-ai-security.md` | +| choose between `showsql`, `runsql`, `showprompt`, `chat`, or `agent` | `select-ai-actions.md` | +| design and audit Select AI annotations for NL2SQL | `select-ai-annotations.md` | +| shape prompts, inspect prompt augmentation, or guide prompt wording | `select-ai-prompts.md` | +| improve NL2SQL with `object_list`, comments, annotations, or constraints | `select-ai-metadata.md` | +| apply or troubleshoot SQL refinement feedback | `select-ai-feedback.md` | +| use Select AI with a vector store for RAG | `select-ai-rag.md` | +| build teams, agents, tasks, or tools with `DBMS_CLOUD_AI_AGENT` | `select-ai-agent.md` | +| inspect agent history views or resume a `WAITING_FOR_HUMAN` run | `select-ai-agent.md` | +| generate synthetic data with Select AI | `select-ai-synthetic-data.md` | +| understand what Oracle AI Vector Search covers before choosing storage or indexing details | `ai-vector-search.md` | +| define `VECTOR` columns, formats, dense/sparse storage, or restrictions | `vector-data-type.md` | +| chunk content, import ONNX models, or build embedding pipelines | `vector-embeddings.md` | +| choose between `DBMS_VECTOR`, `DBMS_VECTOR_CHAIN`, and `DBMS_HYBRID_VECTOR` package APIs | `vector-packages.md` | +| use reranking, summarization, generated text, or other package-level vector helpers | `vector-packages.md` | +| choose distance metrics, operators, or exact versus approximate SQL | `vector-operations.md` | +| choose between IVF and HNSW or use vector-index advisors | `vector-indexes.md` | +| implement keyword + semantic retrieval with hybrid vector indexes | `hybrid-vector-search.md` | +| inspect vector memory, initialization parameters, or vector-specific views | `vector-diagnostics.md` | + +## Select AI + +| File | Description | +|------|-------------| +| `select-ai.md` | Select AI overview, capability boundaries, and routing guide | +| `select-ai-python.md` | routing between `select_ai`, `SELECT AI`, and package-based Select AI use from Python | +| `select-ai-accuracy.md` | cross-cutting Select AI accuracy workflow: scope, metadata, inspection, case sensitivity, and feedback | +| `select-ai-annotations.md` | annotation DDL, profile integration, annotation views, and Select AI metadata usage | +| `select-ai-profiles.md` | AI profile lifecycle, attributes, provider configuration, session activation | +| `select-ai-security.md` | privilege model, metadata/data exposure controls, private endpoints, and AI proxy security | +| `select-ai-prompts.md` | prompt wording rules, `showprompt`, prompt augmentation, and action guidance | +| `select-ai-actions.md` | `SELECT AI` / `DBMS_CLOUD_AI.GENERATE` actions, `showprompt`, `chat`, `translate`, `summarize` | +| `select-ai-metadata.md` | `object_list`, metadata controls, comments, annotations, constraints, data access | +| `select-ai-feedback.md` | `feedback` action, `DBMS_CLOUD_AI.FEEDBACK`, feedback vector index, SQL refinement workflow | +| `select-ai-rag.md` | Select AI RAG flow, vector-index integration, `embedding_model`, `enable_sources` | +| `select-ai-agent.md` | `DBMS_CLOUD_AI_AGENT`, teams, agents, tasks, tools, built-in tool support | +| `select-ai-synthetic-data.md` | `GENERATE_SYNTHETIC_DATA`, params, monitoring status tables, metadata-clone workflows | + +## AI Vector Search + +| File | Description | +|------|-------------| +| `ai-vector-search.md` | AI Vector Search overview, capability boundaries, and routing guide | +| `vector-data-type.md` | `VECTOR` type definitions, dense/sparse formats, restrictions, vector descriptors | +| `vector-embeddings.md` | ONNX models, third-party embeddings, chunking, `DBMS_VECTOR_CHAIN` pipelines | +| `vector-packages.md` | `DBMS_VECTOR`, `DBMS_VECTOR_CHAIN`, `DBMS_HYBRID_VECTOR`, reranking, generated text, package selection | +| `vector-operations.md` | distance metrics, operators, exact/approximate search, vector SQL functions | +| `vector-indexes.md` | IVF/HNSW, `CREATE VECTOR INDEX`, advisor procedures, restrictions | +| `hybrid-vector-search.md` | `CREATE HYBRID VECTOR INDEX`, `DBMS_HYBRID_VECTOR`, hybrid query patterns | + +## Advanced / Diagnostics + +| File | Description | +|------|-------------| +| `select-ai-agent.md` | agent teams, tasks, and tools for Select AI workflows | +| `select-ai-synthetic-data.md` | synthetic data generation workflows and monitoring | +| `vector-diagnostics.md` | vector memory pool, initialization parameters, and diagnostic views | diff --git a/skills/ai/ai-vector-search.md b/skills/ai/ai-vector-search.md new file mode 100644 index 0000000..de58981 --- /dev/null +++ b/skills/ai/ai-vector-search.md @@ -0,0 +1,96 @@ +# AI Vector Search in Oracle AI Database + +## Overview + +Oracle AI Vector Search adds semantic retrieval to Oracle Database. Oracle documents it as combining vector search over unstructured content with relational search over business data in one system. + +This file is the entry point for the AI Vector Search skill set. Start here when the question is broad, then load the narrower skill that matches the storage, query, indexing, or diagnostics task. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Core concepts and workflow | Oracle AI Vector Search User's Guide, **Overview of Oracle AI Vector Search** | +| `VECTOR` column definitions | Oracle AI Vector Search User's Guide, **Create Tables Using the VECTOR Data Type** | +| Distance functions and shorthand operators | Oracle AI Vector Search User's Guide, **VECTOR_DISTANCE** | +| Similarity and hybrid search | Oracle AI Vector Search User's Guide, **Query Data With Similarity and Hybrid Searches** | +| Vector index guidance | Oracle AI Vector Search User's Guide, **Guidelines for Using Vector Indexes** | +| Hybrid vector indexing | Oracle AI Database SQL Language Reference, **CREATE HYBRID VECTOR INDEX** | +| Packaged APIs | Oracle AI Vector Search User's Guide, **DBMS_VECTOR**, **DBMS_VECTOR_CHAIN**, and **DBMS_HYBRID_VECTOR** | + +--- + +## Start Here When + +- you need a broad orientation to Oracle AI Vector Search before choosing a design path +- you are not yet sure whether the task is mainly about `VECTOR` storage, embedding pipelines, vector SQL, vector indexes, or hybrid search +- you want the right next skill instead of reading every vector-search file + +If you already know the exact task, go straight to `skills/ai/SKILLS.md` or use the routing table below. + +--- + +## Minimal Workflow + +Oracle's current AI Vector Search documentation fits this mental model: + +1. Store embeddings in a `VECTOR` column with the right dimensions and format. +2. Query with `VECTOR_DISTANCE` or shorthand operators. +3. Add a vector index when approximate search is needed for performance. +4. Use a hybrid vector index when the workload needs both keyword and semantic retrieval in one path. + +Minimal documented entry points: + +```sql +CREATE TABLE my_vectors ( + id NUMBER, + embedding VECTOR(768, FLOAT32) +); + +SELECT id +FROM my_vectors +ORDER BY VECTOR_DISTANCE(embedding, :query_vector, COSINE) +FETCH FIRST 10 ROWS ONLY; + +CREATE VECTOR INDEX my_vectors_ivf_idx ON my_vectors (embedding) +ORGANIZATION NEIGHBOR PARTITIONS +DISTANCE COSINE; +``` + +--- + +## Routing by Task + +| Task | Read next | +|------|-----------| +| define `VECTOR` columns, dense versus sparse storage, formats, or restrictions | `vector-data-type.md` | +| build chunking, ONNX, or embedding pipelines | `vector-embeddings.md` | +| choose between `DBMS_VECTOR`, `DBMS_VECTOR_CHAIN`, and `DBMS_HYBRID_VECTOR` package APIs | `vector-packages.md` | +| choose metrics, operators, or exact versus approximate SQL patterns | `vector-operations.md` | +| choose between IVF and HNSW or use advisor procedures | `vector-indexes.md` | +| build keyword + semantic retrieval with `CREATE HYBRID VECTOR INDEX` or `DBMS_HYBRID_VECTOR` | `hybrid-vector-search.md` | +| inspect memory, parameters, or vector-specific views | `vector-diagnostics.md` | + +For the full task index across the AI category, read `skills/ai/SKILLS.md`. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c (generic):** AI Vector Search is not part of the generic 19c baseline. +- **Oracle AI Database 23.4 / 23ai:** `VECTOR`, similarity search, and vector indexing enter the product surface. Some newer capabilities in later docs require a higher `COMPATIBLE` setting. +- **Oracle AI Database 23.6 / 26ai docs:** Current documentation includes hybrid vector indexes, richer packaged APIs, release-update guidance, and additional diagnostics content. + +--- + +## Sources + +- [Oracle AI Vector Search User's Guide - Overview of Oracle AI Vector Search](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/overview-ai-vector-search.html) +- [Oracle AI Vector Search User's Guide - Create Tables Using the VECTOR Data Type](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/create-tables-using-vector-data-type.html) +- [Oracle AI Vector Search User's Guide - VECTOR_DISTANCE](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/vector_distance.html) +- [Oracle AI Vector Search User's Guide - Query Data With Similarity and Hybrid Searches](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/query-data-similarity-searches.html) +- [Oracle AI Vector Search User's Guide - Guidelines for Using Vector Indexes](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/guidelines-using-vector-indexes.html) +- [Oracle AI Database SQL Language Reference - CREATE VECTOR INDEX](https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/create-vector-index.html) +- [Oracle AI Database SQL Language Reference - CREATE HYBRID VECTOR INDEX](https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/create-hybrid-vector-index.html) diff --git a/skills/ai/hybrid-vector-search.md b/skills/ai/hybrid-vector-search.md new file mode 100644 index 0000000..24edadf --- /dev/null +++ b/skills/ai/hybrid-vector-search.md @@ -0,0 +1,199 @@ +# Hybrid Vector Search in Oracle AI Database + +## Overview + +Hybrid vector search combines Oracle Text-style keyword search with vector similarity search. Oracle documents this both as a query pattern and as a first-class indexing path through `CREATE HYBRID VECTOR INDEX`. + +Use this file when you need keyword constraints and semantic similarity in the same retrieval workflow. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Hybrid search concepts | Oracle AI Vector Search User's Guide, **Query Data With Similarity and Hybrid Searches** | +| Hybrid index DDL | Oracle AI Vector Search User's Guide, **CREATE HYBRID VECTOR INDEX** | +| SQL reference | Oracle AI Database SQL Language Reference, **CREATE HYBRID VECTOR INDEX** | +| Query API | Oracle AI Vector Search User's Guide, **DBMS_HYBRID_VECTOR** | +| Guidelines and restrictions | Oracle AI Vector Search User's Guide, **Guidelines and Restrictions for Hybrid Vector Indexes** | + +--- + +## Hybrid Index DDL + +Oracle documents this minimal DDL pattern: + +```sql +CREATE HYBRID VECTOR INDEX my_hybrid_idx on + doc_table(text_column) + PARAMETERS('MODEL my_doc_model'); +``` + +Oracle documents `MODEL` as the in-database ONNX embedding model used by the hybrid index. + +The same syntax page documents `VECTOR_IDXTYPE` and notes that IVF is the default if you omit it. + +--- + +## Query with `DBMS_HYBRID_VECTOR.SEARCH` + +Oracle documents `DBMS_HYBRID_VECTOR.SEARCH` as a unified query API for hybrid indexes: + +```sql +SELECT DBMS_HYBRID_VECTOR.SEARCH( +json('{ "hybrid_index_name" : "my_hybrid_idx", + "vector": + { "search_text" : "stock fraud" }, + "text" : + { "contains" : "$ABC AND $Corporation" }, + "return": + { "topN" : 10 } + }')) +FROM dual; +``` + +Use the `vector` section for semantic intent and the `text` section for explicit lexical conditions. + +--- + +## Filters and Predicate Control + +Oracle documents several distinct filtering and constraint paths in `DBMS_HYBRID_VECTOR.SEARCH`. + +### Keyword Filters + +Use the `text` section for Oracle Text-style lexical constraints: + +- `text.contains` +- `text.search_text` +- `text.json_textcontains` + +Use `text.contains` when you need explicit Oracle Text query syntax. Use `text.search_text` when you want Oracle to derive the text query from plain search text. + +### Structured Filters + +Oracle also documents a top-level `filter_by` JSON expression for structured predicates on returned rows. + +Documented examples include relational-style comparisons such as: + +- equals +- greater-than / less-than +- compound expressions +- JSON `passing` values + +Use `filter_by` when the query needs business predicates such as price, status, region, or other non-text attributes in addition to hybrid relevance. + +### Path-Based Filtering + +Oracle documents `vector.inpath` as a way to restrict search to specific JSON paths that match the vectorizer path lists. + +Use this when the hybrid index is built over JSON content and only certain document paths should participate in semantic search. + +--- + +## Filter Hints for Vector Evaluation + +Oracle documents `filter_type` inside the `vector` section as a vector-index hint for how filtering should interact with vector index evaluation. + +The documented values are: + +- `PRE_W` +- `PRE_WO` +- `IN_W` +- `IN_WO` +- `POST_WO` + +Oracle documents these as index-hint choices tied to HNSW or IVF behavior, not as generic business predicates. + +Use `filter_type` only when you are tuning the vector-evaluation plan. Use `filter_by` or ordinary SQL predicates when you are expressing business conditions. + +Documented example: + +```sql +SELECT DBMS_HYBRID_VECTOR.SEARCH( +json('{ "hybrid_index_name" : "my_hybrid_idx", + "vector": + { "search_text" : "leadership experience", + "search_mode" : "DOCUMENT", + "filter_type" : "IN_WO" }, + "return": + { "topN" : 10 } + }')) +FROM dual; +``` + +--- + +## Additional Helpers + +Oracle documents these `DBMS_HYBRID_VECTOR` package members: + +- `SEARCH` +- `SEARCHPIPELINE` +- `GET_SQL` +- `GET_HYBRID_SQL` +- `GET_SQL_TEMPLATE` + +Use them when you want generated SQL or search-pipeline composition instead of only a direct search call. + +--- + +## Restrictions and Guidelines + +Oracle documents hybrid vector indexes as a single domain index that combines Oracle Text and vector indexing structures. Because of that: + +- failures in either the text or vector portion can fail the whole index build +- vector memory constraints still apply +- Oracle Text indexing guidelines still apply + +Treat hybrid indexing as a combined search design, not as a thin wrapper over an ordinary vector index. + +--- + +## Best Practices + +- Use a hybrid vector index when documents need both meaning-based retrieval and exact text focus. +- Use `text.contains` for lexical constraints, `filter_by` for structured business predicates, and `filter_type` only for vector-plan tuning. +- Use `vector.inpath` when JSON path scope matters more than whole-document recall. +- Review both Oracle Text and vector-index restrictions before creating the index. +- Use `GET_SQL` or `GET_HYBRID_SQL` when you need to inspect generated search SQL. +- Keep model selection, text search design, and vector index type aligned in one review. + +--- + +## Common Mistakes + +### Mistake 1: Treating Hybrid Search as Purely Application-Side Logic + +Oracle documents `CREATE HYBRID VECTOR INDEX` and `DBMS_HYBRID_VECTOR` as first-class database features. + +### Mistake 2: Ignoring Oracle Text Requirements + +A hybrid vector index includes an Oracle Text component, so text-index design constraints still matter. + +### Mistake 3: Treating `filter_type` as a Business Filter + +Oracle documents `filter_type` as a vector index hint. It is not the same as `filter_by`, ordinary SQL predicates, or Oracle Text query conditions. + +### Mistake 4: Assuming Hybrid Index Creation Can Ignore Vector Memory + +Oracle documents vector-memory and vector-index guidelines as still relevant for hybrid index creation. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c:** Hybrid vector indexes are not available. +- **Oracle Database 23ai:** Oracle documents the hybrid vector index path as part of AI Vector Search. +- **Oracle AI Database 26ai:** Current documentation includes additional predicate support and expanded hybrid-vector features. + +--- + +## Sources + +- [Oracle AI Vector Search User's Guide - Query Data With Similarity and Hybrid Searches](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/query-data-similarity-and-hybrid-searches.html) +- [Oracle AI Vector Search User's Guide - CREATE HYBRID VECTOR INDEX](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/create-hybrid-vector-index.html) +- [Oracle AI Database SQL Language Reference - CREATE HYBRID VECTOR INDEX](https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/create-hybrid-vector-index.html) +- [Oracle AI Vector Search User's Guide - DBMS_HYBRID_VECTOR](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_hybrid_vector-vecse.html) +- [Oracle AI Vector Search User's Guide - Guidelines and Restrictions for Hybrid Vector Indexes](https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/guidelines-and-restrictions-hybrid-vector-indexes.html) diff --git a/skills/ai/select-ai-accuracy.md b/skills/ai/select-ai-accuracy.md new file mode 100644 index 0000000..440644e --- /dev/null +++ b/skills/ai/select-ai-accuracy.md @@ -0,0 +1,221 @@ +# Select AI Accuracy Improvement in Oracle AI Database + +## Overview + +Oracle documents several concrete ways to improve Select AI SQL generation quality. These include better schema metadata, profile controls, prompt inspection, case-sensitivity controls, and SQL refinement feedback. + +Use this file when the question is not about one feature in isolation, but about how to improve Select AI NL2SQL accuracy overall. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| SQL-generation intent, prompt augmentation, and usage guidance | Autonomous Database documentation, **Generate SQL from Natural Language Prompts Using Select AI** | +| `SELECT AI` usage notes | Autonomous Database documentation, **Use AI Keyword to Enter Prompts** | +| Metadata improvements for SQL generation | Autonomous Database release notes, **Interact with metadata to improve Select AI SQL query generation** | +| Practical examples for comments, annotations, constraints, object restrictions, and case sensitivity | Autonomous Database documentation, **Examples of Using Select AI** | +| Metadata controls and object-list modes | SQL Developer Web documentation, **Create AI Profile** | +| Feedback-based refinement | Autonomous Database documentation, **Feedback** | + +--- + +## Start with Metadata, Not Prompt Tricks + +Oracle explicitly documents that, for better NL2SQL results, you should: + +- use database views or tables with contextual column names +- add column comments explaining stored values +- add annotations to metadata sent to the LLM +- add foreign key and referential constraints so the LLM can generate accurate `JOIN` conditions + +Oracle also documents prompt augmentation as schema-metadata augmentation. For SQL generation, Select AI augments the user prompt with schema metadata only, not table contents. + +That means Select AI accuracy is primarily a metadata and scope problem before it is a prompt-style problem. + +--- + +## Keep the Object Scope Narrow + +Oracle documents `object_list` as the core scoping control for NL2SQL. + +Use `object_list` to keep the LLM focused on the relevant tables, views, or graphs instead of exposing a broad schema by default. + +Oracle also documents: + +- `enforce_object_list` +- `object_list_mode` + +The examples show that: + +- `enforce_object_list = true` restricts the LLM to the listed objects +- `enforce_object_list = false` allows the LLM to use other tables and views based on prior knowledge + +SQL Developer Web documents `Object List Mode` values: + +- `None` +- `All` +- `Automated` +- `Selected Tables` + +Use these controls when the schema is large or when prompt scope must stay inside a reviewed object boundary. + +--- + +## Add Metadata That Improves SQL Generation + +Oracle documents three metadata flags that directly improve generated SQL: + +- `"comments":"true"` +- `"annotations":"true"` +- `"constraints":"true"` + +Oracle's release notes tie each one to SQL-generation quality: + +- comments provide table and column descriptions +- annotations add extra metadata to the LLM prompt +- constraints provide foreign key and referential key information for accurate `JOIN` conditions + +Use all three deliberately when the schema is not self-explanatory from object names alone. + +--- + +## Use `showprompt`, `showsql`, and `explainsql` for Inspection + +Oracle documents separate actions for: + +- `showsql` +- `explainsql` +- `showprompt` +- `runsql` + +Use them in this order when accuracy matters: + +1. `showprompt` to inspect augmented context +2. `showsql` to inspect the generated SQL +3. `explainsql` when you want a more detailed explanation of the SQL +4. `runsql` only after the generation path looks correct + +Oracle also documents that `showprompt` supports NL2SQL and RAG, but not `explainsql`, `narrate`, or synthetic data generation. + +--- + +## Handle Case Sensitivity Explicitly + +Oracle documents `case_sensitive_values` as a profile attribute and provides examples showing how it changes generated predicates. + +Oracle's examples show: + +- with `"case_sensitive_values":"false"`, the generated SQL can normalize values with `UPPER(...)` +- double quotes in the prompt can preserve case-sensitive matching even when the profile is case-insensitive + +Use this when query accuracy depends on exact values rather than loose normalization. + +--- + +## Use Feedback for NL2SQL Refinement + +Oracle documents `feedback` and `DBMS_CLOUD_AI.FEEDBACK` as ways to improve SQL-generation accuracy for NL2SQL actions. + +Oracle explains that feedback: + +- stores approved or corrected SQL for future use +- uses vector search to find similar historical prompts +- sends top matching examples as metadata to the LLM as part of the augmented prompt + +Use feedback when the same business phrasing recurs and the generated SQL needs to learn from prior corrections. + +Do not use feedback for RAG profiles. + +--- + +## Prompt Guidance That Oracle Explicitly Documents + +Oracle documents several prompt-specific rules that affect outcome quality: + +- use the correct action instead of using `chat` for SQL-generation problems +- special characters in prompts follow Oracle quoting rules +- `SELECT AI` only works in `SELECT` +- case-sensitive values can be expressed with double quotes + +Oracle also explicitly warns that LLMs are subject to hallucinations and results are not always correct. + +Treat prompt wording as the last layer in the accuracy stack, after metadata scope and inspection workflow. + +--- + +## Improvement Workflow + +The Oracle-documented improvement path can be summarized as: + +1. use contextual object and column names +2. restrict scope with `object_list` +3. enable comments, annotations, and constraints as needed +4. inspect prompt augmentation with `showprompt` +5. inspect generated SQL with `showsql` or `explainsql` +6. control case sensitivity when values matter +7. use feedback to refine recurring NL2SQL patterns + +This is the most documentation-backed route to better accuracy without relying on undocumented prompt-engineering advice. + +--- + +## Routing to Neighbor Skills + +| If the task narrows to... | Read | +|---------------------------|------| +| annotation design and annotation dictionary views | `select-ai-annotations.md` | +| prompt wording, `showprompt`, and prompt augmentation | `select-ai-prompts.md` | +| object scoping, comments, constraints, and `case_sensitive_values` | `select-ai-metadata.md` | +| profile attributes and lifecycle | `select-ai-profiles.md` | +| feedback procedures and operational constraints | `select-ai-feedback.md` | + +--- + +## Best Practices + +- Improve metadata before attempting broad prompt-engineering changes. +- Keep `object_list` as narrow as the use case allows. +- Enable comments, annotations, and constraints only for reviewed objects inside the AI profile scope. +- Use inspection actions before trusting `runsql`. +- Use feedback only for recurring NL2SQL correction patterns. + +--- + +## Common Mistakes + +### Mistake 1: Treating Accuracy as Only a Prompt-Wording Problem + +Oracle documents metadata augmentation, object scoping, comments, annotations, and constraints as core to SQL-generation quality. + +### Mistake 2: Letting the LLM See Too Many Objects + +Oracle documents `object_list`, `enforce_object_list`, and object-list modes because broad schema scope hurts control and can reduce relevance. + +### Mistake 3: Skipping Inspection and Going Straight to `runsql` + +Oracle documents `showprompt`, `showsql`, and `explainsql` as separate inspection paths for a reason. + +### Mistake 4: Using Feedback for RAG + +Oracle documents feedback for NL2SQL refinement, not for RAG grounding. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c (generic):** Select AI accuracy features are not part of the generic 19c baseline. +- **Autonomous AI Database 19c / Oracle AI Database 19.30:** Core NL2SQL prompting and some profile controls are documented, but newer enhancements such as annotations, automated object-list mode, and feedback are not universally available. +- **Oracle AI Database 26ai:** Current documentation includes comments, annotations, constraints, `showprompt`, richer metadata controls, and feedback-based SQL refinement. + +--- + +## Sources + +- [Autonomous Database documentation - Generate SQL from Natural Language Prompts Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database/doc/use-select-ai-generate-sql-natural-language-prompts.html) +- [Autonomous Database documentation - Use AI Keyword to Enter Prompts](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-keyword-prompts.html) +- [Autonomous Database release notes - Interact with metadata to improve Select AI SQL query generation](https://docs.oracle.com/en-us/iaas/releasenotes/autonomous-database-dedicated/adbd-selectai-sqlquerygen.htm) +- [Autonomous Database documentation - Examples of Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-examples.html) +- [SQL Developer Web documentation - Create AI Profile](https://docs.oracle.com/en/database/oracle/sql-developer-web/sdwad/create-ai-profile.html) +- [Autonomous Database documentation - Feedback](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-feedback.html) diff --git a/skills/ai/select-ai-actions.md b/skills/ai/select-ai-actions.md new file mode 100644 index 0000000..0597b34 --- /dev/null +++ b/skills/ai/select-ai-actions.md @@ -0,0 +1,154 @@ +# Select AI Actions in Oracle AI Database + +## Overview + +Select AI exposes prompt actions through the `AI` keyword and through `DBMS_CLOUD_AI.GENERATE`. These actions cover NL2SQL, prompt inspection, chat, summarization, translation, feedback, and agent execution. + +Use this file when you need to choose the right Select AI action and understand the exact syntax Oracle documents for prompt execution. If you need the Python object methods such as `Profile.run_sql()` or `AsyncProfile.show_sql()`, start with `select-ai-python.md` and use this file for the underlying action semantics. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| `AI` keyword syntax and action list | Autonomous Database documentation, **Use AI Keyword to Enter Prompts** | +| Action examples | Autonomous Database documentation, **Examples of Using Select AI** | +| Function-based execution | Autonomous Database documentation, **DBMS_CLOUD_AI Package** | +| Capability support by release | Oracle Database Select AI Capability Matrix | + +--- + +## `AI` Keyword Syntax + +Oracle documents the `AI` keyword syntax as: + +```sql +SELECT AI action natural_language_prompt +``` + +Oracle explicitly documents that you cannot run PL/SQL statements, DDL statements, or DML statements using the `AI` keyword. + +--- + +## Action Families + +Oracle documents these actions for current Select AI environments: + +- `runsql` +- `showsql` +- `showprompt` +- `explainsql` +- `narrate` +- `summarize` +- `translate` +- `chat` +- `feedback` +- `agent` + +Use them by outcome: + +- SQL generation and execution: `runsql`, `showsql`, `explainsql` +- Prompt inspection: `showprompt` +- Natural-language output: `narrate`, `chat`, `summarize`, `translate` +- Refinement and orchestration: `feedback`, `agent` + +--- + +## Documented `SELECT AI` Examples + +Oracle's examples page includes these exact forms: + +```sql +SELECT AI how many customers exist; + +SELECT AI showsql how many customers exist; + +SELECT AI narrate how many customers exist; + +SELECT AI explainsql how many customers in San Francisco are married; + +SELECT AI chat what is Autonomous AI Database; +``` + +Use `runsql` when you want the executed result. Use `showsql` when you want to inspect generated SQL first. + +--- + +## `DBMS_CLOUD_AI.GENERATE` + +Oracle documents `DBMS_CLOUD_AI.GENERATE` for stateless use from SQL and PL/SQL contexts: + +```sql +SELECT DBMS_CLOUD_AI.GENERATE(prompt => 'how many customers', + profile_name => 'OPENAI', + action => 'showsql') +FROM dual; +``` + +Use named arguments and only pass `params` when the feature you are using documents it explicitly. + +--- + +## `showprompt` + +Oracle documents `showprompt` as a way to inspect the constructed prompt that Select AI sends to the model. + +Oracle also documents functional limits: + +- `showprompt` supports NL2SQL and RAG +- `showprompt` does not support synthetic data generation +- `showprompt` does not support `explainsql` +- `showprompt` does not support `narrate` + +Use `showprompt` when debugging metadata augmentation, object-list selection, or RAG grounding. + +--- + +## `summarize` and `translate` + +Oracle treats summarization and translation as first-class Select AI actions and also documents `DBMS_CLOUD_AI.SUMMARIZE` and `DBMS_CLOUD_AI.TRANSLATE` as functional interfaces. + +Use `summarize` for large input text or files when you want condensed output. Use `translate` when your target is language translation, not SQL generation. + +--- + +## Best Practices + +- Use `showsql` before `runsql` for NL2SQL validation. +- Use `showprompt` when debugging why the model is seeing the wrong context. +- Use `DBMS_CLOUD_AI.GENERATE` with explicit `profile_name` in environments where the `AI` keyword is not available. +- Keep `chat` separate from SQL inspection workflows. Oracle documents them as different actions for a reason. + +--- + +## Common Mistakes + +### Mistake 1: Treating `chat` as the Default Action for SQL Work + +If the task is NL2SQL, Oracle already provides `showsql`, `runsql`, and `explainsql`. Use those first. + +### Mistake 2: Assuming `SELECT AI` Works in Every Client Surface + +Oracle documents that the `AI` keyword is not supported in Database Actions or APEX Service. + +### Mistake 3: Using `showprompt` Where Oracle Does Not Support It + +Oracle documents clear exclusions for `showprompt`. Do not assume it works for every action family. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c (generic):** Select AI actions are not part of the generic 19c baseline. +- **Autonomous AI Database 19c / Oracle AI Database 19.30:** Core actions such as NL2SQL and chat are documented in the capability matrix, but newer actions such as `feedback` are not universally available. +- **Oracle AI Database 23.26.1 / 26ai docs:** Current documentation includes the broadest action surface, including `showprompt`, `feedback`, and `agent`. + +--- + +## Sources + +- [Autonomous Database documentation - Use AI Keyword to Enter Prompts](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-keyword-prompts.html) +- [Autonomous Database documentation - Examples of Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-examples.html) +- [Autonomous Database documentation - DBMS_CLOUD_AI Package](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-ai-package.html) +- [Oracle Database Select AI Capability Matrix](https://docs.oracle.com/en/database/oracle/oracle-database/26/saicm/index.html) diff --git a/skills/ai/select-ai-agent.md b/skills/ai/select-ai-agent.md new file mode 100644 index 0000000..9211cbb --- /dev/null +++ b/skills/ai/select-ai-agent.md @@ -0,0 +1,278 @@ +# Select AI Agent in Oracle AI Database + +## Overview + +Select AI Agent is Oracle's autonomous agent framework inside Oracle AI Database and Autonomous AI Database. Oracle documents it as combining planning, tool use, reflection, and memory to support multi-turn workflows. + +Use this file when you need agent teams, tasks, tools, built-in tools, or `DBMS_CLOUD_AI_AGENT`. If the question is specifically about `select_ai.agent.*` classes in Python, start with `select-ai-python.md` and use this file for the database-side agent model. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Agent overview and concepts | Oracle Database Select AI User's Guide, **Select AI Agent** | +| Agent architecture and ReAct pattern | Oracle Database Select AI User's Guide, **Select AI Agent** | +| End-to-end SQL and PL/SQL examples | Oracle Database Select AI User's Guide, **Examples of Using Select AI Agent** | +| Package and view support | `DBMS_CLOUD_AI_AGENT` Package, Views, and History Views | +| Capability and tool support by release | Oracle Database Select AI Capability Matrix | +| Package object support | Oracle Database Select AI Capability Matrix | + +--- + +## Agent Architecture + +Oracle documents four architectural layers for Select AI Agent: + +- Planning +- Tool Use +- Reflection +- Memory Management + +Oracle also documents the ReAct pattern as the reasoning-and-acting pattern used by the framework. + +Use this model when deciding whether a workflow really needs agent orchestration instead of a simpler Select AI prompt action. + +--- + +## Core Objects + +Oracle documents the `DBMS_CLOUD_AI_AGENT` package for managing: + +- teams +- agents +- tasks +- tools + +The capability matrix lists core procedures and functions including: + +- `CREATE_TEAM` +- `CREATE_AGENT` +- `CREATE_TASK` +- `CREATE_TOOL` +- `ENABLE_*` and `DISABLE_*` +- `DROP_*` +- `RUN_TEAM` +- `RUN_TOOL` +- `GET_TEAM` +- `SET_TEAM` +- `SET_ATTRIBUTE` +- `SET_ATTRIBUTES` + +## Built-In Tools + +The capability matrix documents these built-in tool categories: + +- `SQL` +- `RAG` +- `WEBSEARCH` +- `NOTIFICATION` +- custom PL/SQL + +Oracle documents agent workflows as being able to combine built-in tools, custom PL/SQL procedures, and external REST services. + +Oracle's examples page makes the built-in categories more concrete: + +- `NOTIFICATION` includes `EMAIL` and `SLACK` +- `WEBSEARCH` examples use an OpenAI credential path +- `SQL` and `RAG` tools point at Select AI profiles + +Treat tool creation as explicit configuration, not as an implicit prompt capability. + +--- + +## Minimal Lifecycle Pattern + +Oracle's examples show the core object lifecycle in this order: + +1. create an agent with `CREATE_AGENT` +2. create tools with `CREATE_TOOL` +3. create tasks with `CREATE_TASK` +4. assemble them into a team with `CREATE_TEAM` +5. run with `SELECT AI AGENT ...` or `DBMS_CLOUD_AI_AGENT.RUN_TEAM` + +Documented examples: + +```sql +BEGIN + DBMS_CLOUD_AI_AGENT.CREATE_AGENT( + agent_name => 'CustomerAgent', + attributes =>'{ + "profile_name": "GOOGLE", + "role": "You are an experienced customer agent who deals with customers return request." + }' + ); +END; +/ + +BEGIN + DBMS_CLOUD_AI_AGENT.CREATE_TASK( + task_name => 'FETCH_LOGS_TASK', + attributes =>'{ + "instruction": "Fetch the log entries from the database based on user request: {query}", + "tools": ["log_fetcher"], + "enable_human_tool" : "true" + }' + ); +END; +/ + +BEGIN + DBMS_CLOUD_AI_AGENT.CREATE_TEAM( + team_name => 'Ops_Issues_Solution_Team', + attributes => '{"agents": [{"name":"Data_Engineer","task" : "fetch_logs_task"}, + {"name":"Ops_Manager","task" : "analyze_log_task"}], + "process": "sequential"}'); +END; +/ +``` + +Use these examples as the canonical mental model for how the package is intended to be assembled. + +--- + +## How to Use It + +Oracle documents two primary entry points: + +- the Select AI `agent` action +- `DBMS_CLOUD_AI_AGENT.RUN_TEAM` + +Use the `agent` action when you want conversational agent behavior from prompt execution. Use `RUN_TEAM` when you need an explicit package-based invocation path. + +Oracle's examples also document a client-surface distinction: + +- use `SELECT AI AGENT ...` on SQL command line style surfaces +- use `DBMS_CLOUD_AI_AGENT.RUN_TEAM` in Database Actions or APEX Service + +Oracle explicitly notes that Database Actions and APEX Service should pass the team with the `team_name` argument to `RUN_TEAM` instead of using `SET_TEAM`. + +--- + +## History Views and Troubleshooting + +Oracle documents both object views and run-history views for Select AI Agent. + +Object and attribute views include: + +- `USER_AI_AGENTS` +- `USER_AI_AGENT_TOOLS` +- `USER_AI_AGENT_TASKS` +- `USER_AI_AGENT_TEAMS` +- corresponding `*_ATTRIBUTES` views + +Run-history views include: + +- `USER_AI_AGENT_TEAM_HISTORY` +- `USER_AI_AGENT_TASK_HISTORY` +- `USER_AI_AGENT_TOOL_HISTORY` + +Oracle's examples also use `USER_CLOUD_AI_CONVERSATION_PROMPTS` when reviewing the latest team run. + +Use these views when you need to: + +- confirm what agents, tasks, tools, and teams exist +- audit tool usage and outputs +- inspect the latest run state +- debug prompts, responses, and task-level results + +Documented troubleshooting queries include: + +```sql +select * from USER_AI_AGENT_TOOL_HISTORY +order by START_DATE desc; + +select * from USER_AI_AGENT_TASK_HISTORY +order by START_DATE desc; + +select * from USER_AI_AGENT_TEAM_HISTORY +order by START_DATE desc; +``` + +--- + +## `WAITING_FOR_HUMAN` and Resuming Runs + +Oracle documents `WAITING_FOR_HUMAN` as a task-history state for agent teams that pause pending user input or approval. + +When you run a team through `DBMS_CLOUD_AI_AGENT.RUN_TEAM`, Oracle documents resuming the same team by passing the original `conversation_id` in `params`: + +```sql +DECLARE + v_response VARCHAR2(4000); +BEGIN + v_response := DBMS_CLOUD_AI_AGENT.RUN_TEAM( + team_name => '', + user_prompt => 'response to request', + params => '{"conversation_id": ""}' + ); + DBMS_OUTPUT.PUT_LINE(v_response); +END; +``` + +Oracle documents that, in this state, `user_prompt` acts as the human response that resumes the workflow. + +--- + +## Prerequisites + +Oracle documents that Select AI Agent requires: + +- privileges for `DBMS_CLOUD_AI_AGENT` +- the underlying privileges required for Select AI +- configuration of any tools the agent will use + +Do not treat agent setup as isolated from profile, credentials, or tool governance. + +--- + +## Best Practices + +- Start with a narrow team and a small tool set before expanding to complex workflows. +- Use built-in tools when the workflow already matches Oracle's documented SQL or RAG paths. +- Add custom PL/SQL tools only when the workflow needs domain-specific operations that Select AI does not already provide. +- Inspect `USER_AI_AGENT_*` history views when debugging team behavior instead of treating the run as opaque. +- Use `RUN_TEAM` with `conversation_id` for stateless clients that need resume behavior. +- Keep agent privileges aligned with the actual tools and data paths it can invoke. + +--- + +## Common Mistakes + +### Mistake 1: Using an Agent When a Single Select AI Action Would Do + +If the task is only NL2SQL, explanation, or summarization, the simpler Select AI actions are usually the right entry point. + +### Mistake 2: Treating Tools as Purely Prompt-Level Concepts + +Oracle documents a concrete package and tool model around teams, tasks, and tools. Configure those objects explicitly. + +### Mistake 3: Ignoring Version and Tool Availability Differences + +The capability matrix shows that agent support and built-in tools vary by release line and service type. + +### Mistake 4: Treating Database Actions and SQL Command Line as the Same Runtime Surface + +Oracle documents different invocation patterns for SQL command line versus Database Actions or APEX Service. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c (generic):** Select AI Agent is not part of the generic 19c baseline. +- **Autonomous AI Database 19c / Oracle Database 19.29+:** Oracle documents `DBMS_CLOUD_AI_AGENT` package and views support starting with this line. +- **Oracle AI Database 23.26 / 26ai docs:** Current documentation includes the broadest Select AI Agent surface, including examples, views, history views, and `WAITING_FOR_HUMAN` resume guidance. +- **Capability matrix:** Tool and service availability still varies by release and deployment type, so verify the exact environment before depending on a specific built-in tool. + +--- + +## Sources + +- [Oracle Database Select AI User's Guide - Select AI Agent](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/select-ai-agent1.html) +- [Oracle Database Select AI User's Guide - Select AI Agent Details](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/select-ai-agent2.html) +- [Oracle Database Select AI User's Guide - Examples of Using Select AI Agent](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/examples-using-select-ai-agent1.html) +- [Oracle Database Select AI Capability Matrix](https://docs.oracle.com/en/database/oracle/oracle-database/26/saicm/index.html) +- [DBMS_CLOUD_AI_AGENT Views](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/dbms_cloud_ai_agent-views.html) +- [DBMS_CLOUD_AI_AGENT History Views](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/dbms-cloud-ai-agent-views-history.html) +- [DBMS_CLOUD_AI_AGENT Package](https://docs.oracle.com/en/cloud/paas/autonomous-database/dedicated/dbmzc/) diff --git a/skills/ai/select-ai-annotations.md b/skills/ai/select-ai-annotations.md new file mode 100644 index 0000000..514594b --- /dev/null +++ b/skills/ai/select-ai-annotations.md @@ -0,0 +1,194 @@ +# Select AI Annotations in Oracle AI Database + +## Overview + +Oracle documents Select AI annotations as metadata that can be added to database objects and then included in the metadata sent to the LLM for SQL generation. + +Use this file when you need to design, add, inspect, or enable annotations for Select AI NL2SQL workflows. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Select AI annotation example | Autonomous Database documentation, **Examples of Using Select AI** | +| Metadata improvements for SQL generation | Autonomous Database release notes, **Interact with metadata to improve Select AI SQL query generation** | +| SQL annotation syntax | Oracle AI Database SQL Language Reference, **annotations_clause** | +| Annotation inventory views | Oracle Database Reference, **ALL_ANNOTATIONS** and **ALL_ANNOTATIONS_USAGE** | + +--- + +## What Select AI Uses + +Oracle documents that Select AI can integrate annotations by adding them to the metadata that is sent to the LLM. + +Enable this behavior in the AI profile with: + +```sql +"annotations" : "true" +``` + +Oracle's Select AI examples show this profile pattern: + +```sql +BEGIN + DBMS_CLOUD_AI.CREATE_PROFILE( + profile_name => 'GOOGLE_ANNOTATIONS', + attributes => '{"provider": "google", + "credential_name": "GOOGLE_CRED", + "object_list": [{"owner": "ADB_USER", "name": "emp2"}], + "annotations" : "true" + }'); +END; +/ +``` + +--- + +## How Oracle Annotations Work + +Oracle documents annotations as centrally stored application metadata for schema objects. + +The SQL Language Reference states: + +- annotations can be added at `CREATE` time +- annotations can be added, dropped, or replaced with `ALTER` +- annotations are additive +- an annotation has a name and an optional value +- the name and value are freeform text fields + +Oracle documents supported schema objects including tables, views, materialized views, and indexes. Oracle also documents column-level annotations in table DDL. + +--- + +## Table-Level and Column-Level Annotation Patterns + +Oracle documents column-level and table-level annotation patterns such as: + +```sql +CREATE TABLE employee ( + id NUMBER(5) + ANNOTATIONS(Identity, Display 'Employee ID', "Group" 'Emp_Info'), + ename VARCHAR2(50) + ANNOTATIONS(Display 'Employee Name', "Group" 'Emp_Info'), + sal NUMBER + ANNOTATIONS(Display 'Employee Salary', UI_Hidden) +) ANNOTATIONS (Display 'Employee Table'); +``` + +Oracle's Select AI example also shows annotations designed for SQL generation: + +```sql +CREATE TABLE emp2 ( + empno NUMBER, + ename VARCHAR2(50) ANNOTATIONS (display 'lastname'), + salary NUMBER ANNOTATIONS ("person_salary", "column_hidden"), + deptno NUMBER ANNOTATIONS (display 'department') +)ANNOTATIONS (requires_audit 'yes', version '1.0', owner 'HR Organization'); +``` + +This shows that Select AI can consume both table-level and column-level annotations when `annotations` is enabled in the profile. + +--- + +## Annotation DDL Operations + +Oracle documents the following operations in `annotations_clause`: + +- `ADD` +- `DROP` +- `REPLACE` + +Oracle documents `ADD` as the default operation for `CREATE` statements. + +Example from the SQL Language Reference: + +```sql +ALTER TABLE employee + MODIFY ename ANNOTATIONS ( + DROP "Group", + DROP IF EXISTS missing_annotation, + REPLACE Display 'Emp name' + ); +``` + +Use `REPLACE` when the annotation already exists and the value needs to be changed. + +--- + +## Inspecting and Auditing Annotations + +Oracle documents dictionary views for annotation inventory and usage. + +Use: + +- `USER_ANNOTATIONS` +- `ALL_ANNOTATIONS` +- `USER_ANNOTATIONS_USAGE` +- `ALL_ANNOTATIONS_USAGE` + +Oracle documents `ALL_ANNOTATIONS` as the list of annotation names accessible to the current user, and `ALL_ANNOTATIONS_USAGE` as usage information that includes object name, object type, column name, annotation name, and annotation value. + +These views are the documented way to verify what annotation metadata exists before enabling `"annotations":"true"` in a profile. + +--- + +## Relationship to Comments and Constraints + +Oracle's Select AI examples and release notes group these metadata controls together: + +- `comments` +- `annotations` +- `constraints` + +Oracle documents: + +- comments improve SQL generation by adding table and column comments to LLM metadata +- annotations improve SQL generation by adding annotations to LLM metadata +- constraints improve SQL generation by adding foreign key and referential key constraints for accurate `JOIN` conditions + +Use annotations as one metadata source, not as the only metadata source in an NL2SQL design. + +--- + +## Best Practices + +- Enable `"annotations":"true"` only when the annotated objects are intentionally part of the AI profile scope. +- Use column-level annotations when the extra metadata applies to one attribute rather than the whole table. +- Use annotation inventory and usage views to review metadata before enabling it for Select AI. +- Combine annotations with comments and constraints when the docs show that all three improve SQL generation in different ways. + +--- + +## Common Mistakes + +### Mistake 1: Adding Database Annotations but Not Enabling Them in the AI Profile + +Oracle documents that Select AI uses annotations only when `"annotations":"true"` is specified in the profile. + +### Mistake 2: Expecting Annotations to Replace Constraint Metadata + +Oracle documents constraints separately for accurate `JOIN` generation. Annotations are not documented as the substitute for foreign-key metadata. + +### Mistake 3: Skipping Annotation Inventory Checks + +Oracle documents dictionary views for annotation names and usage. Use them to verify what will be exposed as metadata. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c (generic):** Select AI annotations are not part of the generic 19c baseline. +- **Oracle AI Database 19.28+:** Oracle documents SQL annotation syntax in the SQL Language Reference. +- **Oracle AI Database 26ai:** Oracle documents Select AI integration for annotations and annotation dictionary views such as `ALL_ANNOTATIONS` and `ALL_ANNOTATIONS_USAGE`. + +--- + +## Sources + +- [Autonomous Database documentation - Examples of Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-examples.html) +- [Autonomous Database release notes - Interact with metadata to improve Select AI SQL query generation](https://docs.oracle.com/en-us/iaas/releasenotes/autonomous-database-dedicated/adbd-selectai-sqlquerygen.htm) +- [Oracle AI Database SQL Language Reference - annotations_clause](https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/annotations_clause.html) +- [Oracle Database Reference - ALL_ANNOTATIONS](https://docs.oracle.com/en/database/oracle/oracle-database/26/refrn/ALL_ANNOTATIONS.html) +- [Oracle Database Reference - ALL_ANNOTATIONS_USAGE](https://docs.oracle.com/en/database/oracle/oracle-database/26/refrn/ALL_ANNOTATIONS_USAGE.html) diff --git a/skills/ai/select-ai-feedback.md b/skills/ai/select-ai-feedback.md new file mode 100644 index 0000000..47e9291 --- /dev/null +++ b/skills/ai/select-ai-feedback.md @@ -0,0 +1,115 @@ +# Select AI Feedback in Oracle AI Database + +## Overview + +Oracle documents `feedback` as a Select AI capability for improving SQL generation quality. Feedback is aimed at NL2SQL correction and refinement, not RAG grounding. + +Use this file when you need to understand the `feedback` action, the `DBMS_CLOUD_AI.FEEDBACK` procedure, and the operational constraints around profile-wide SQL refinement. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Feedback feature overview | Autonomous Database documentation, **Feedback** | +| Feedback examples | Autonomous Database documentation, **Examples of Using Select AI** | +| Capability support by release | Oracle Database Select AI Capability Matrix | +| Package support | Autonomous Database documentation, **DBMS_CLOUD_AI Package** | + +--- + +## What Feedback Is For + +Oracle documents feedback as a way to improve subsequent SQL generation for NL2SQL actions such as: + +- `runsql` +- `showsql` +- `explainsql` + +Oracle also documents that feedback is not for RAG profiles. Use it when the generated SQL is wrong or when you want to affirm that the generated SQL is correct. + +--- + +## Documented `SELECT AI feedback` Forms + +Oracle's examples page documents these feedback patterns: + +```sql +SELECT AI feedback for query "select ai showsql how many watch histories in total", please use sum instead of count; + +SELECT AI feedback please use sum instead of count for sql_id 1v1z68ra6r9zf; + +SELECT AI feedback the result is correct; +``` + +These three forms correspond to: + +- feedback on a specific prompt text +- feedback on a specific `SQL_ID` +- feedback on the last generated SQL + +--- + +## `DBMS_CLOUD_AI.FEEDBACK` + +Oracle documents `DBMS_CLOUD_AI.FEEDBACK` as the procedural interface for the same feature. + +Use the procedure when you need feedback control from SQL or PL/SQL workflows instead of the `AI` keyword interaction style. + +Oracle also documents that first use of feedback creates a default vector index named `_FEEDBACK_VECINDEX`. + +--- + +## Operational Constraints + +Oracle explicitly documents these constraints: + +- feedback is for NL2SQL, not RAG +- to use the last generated SQL, server output configuration matters +- querying `V$MAPPED_SQL` requires the needed `SELECT` privileges +- do not use the feedback action in applications where multiple users share database sessions under one database user that owns the AI profile + +That last point matters because feedback changes profile-level behavior, not only the current end user experience. + +--- + +## Best Practices + +- Use feedback only after inspecting the generated SQL or its result. +- Use prompt-text or `SQL_ID` targeting when you need deterministic correction scope. +- Treat positive feedback as a deliberate signal, not as routine click-through. +- Keep separate profiles for distinct business domains so feedback stays semantically coherent. + +--- + +## Common Mistakes + +### Mistake 1: Using Feedback on a RAG Profile + +Oracle documents feedback for NL2SQL refinement. It is not the correction mechanism for RAG grounding. + +### Mistake 2: Sharing One Feedback-Enabled Profile Across Unrelated Users + +Oracle explicitly warns against using feedback in shared-session application patterns. + +### Mistake 3: Assuming Feedback Is Session-Local + +Oracle documents a profile-level feedback vector index. Treat feedback as a maintained asset, not a temporary session note. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Autonomous AI Database 19c:** The capability matrix marks `feedback` as unavailable. +- **Oracle AI Database 19.30:** The capability matrix marks `feedback` as available. +- **Oracle AI Database 23.26.1 / 26ai docs:** Current documentation includes `feedback`, examples, and the `DBMS_CLOUD_AI.FEEDBACK` procedure. + +--- + +## Sources + +- [Autonomous Database documentation - Feedback](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-feedback.html) +- [Autonomous Database documentation - Examples of Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-examples.html) +- [Oracle Database Select AI Capability Matrix](https://docs.oracle.com/en/database/oracle/oracle-database/26/saicm/index.html) +- [Autonomous Database documentation - DBMS_CLOUD_AI Package](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-ai-package.html) diff --git a/skills/ai/select-ai-metadata.md b/skills/ai/select-ai-metadata.md new file mode 100644 index 0000000..ae7a22a --- /dev/null +++ b/skills/ai/select-ai-metadata.md @@ -0,0 +1,131 @@ +# Select AI Metadata Controls in Oracle AI Database + +## Overview + +Select AI quality depends on the metadata made available to the model. Oracle documents controls for object-list scoping, comments, annotations, constraints, case sensitivity, and data access management. + +Use this file when you need to control what metadata Select AI can see and how that metadata is used for NL2SQL generation. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Metadata controls in profile creation | SQL Developer Web documentation, **Create AI Profile** | +| NL2SQL metadata attributes by release | Oracle Database Select AI Capability Matrix | +| Prompt augmentation and metadata scope | Oracle Autonomous Database documentation, **About Select AI** | +| SQL-generation improvement examples | Autonomous Database documentation, **Examples of Using Select AI** | +| Data access controls | Autonomous Database documentation, **DBMS_CLOUD_AI Package** | + +--- + +## Object List and Object List Modes + +Oracle documents `object_list` as the primary NL2SQL scoping control. SQL Developer Web also documents object-list modes: + +- `None` +- `All` +- `Automated` +- `Selected Tables` + +Oracle documents `Enforce Object List` as an additional control that restricts the AI to the chosen object list. + +The capability matrix also documents: + +- `object_list` +- `object_list_mode` +- `enforce_object_list` + +Use `object_list` when you want deterministic scope. Use `object_list_mode = Automated` when you want Oracle to narrow schema context dynamically on supported releases. + +--- + +## Comments, Annotations, and Constraints + +Oracle documents these profile metadata controls: + +- `comments` +- `annotations` +- `constraints` + +Their purpose is distinct: + +- `comments` exposes table and column comments to the AI +- `annotations` exposes extra descriptive metadata attached to objects +- `constraints` exposes primary-key, foreign-key, and related relationship information + +Use these controls when schema names alone are not enough for correct SQL generation. + +--- + +## Case Sensitivity and Values + +The capability matrix documents `case_sensitive_values` as an NL2SQL profile attribute. + +Use it when values must preserve case-sensitive behavior instead of being normalized loosely by prompt interpretation. + +--- + +## Data Access Controls + +Oracle documents `ENABLE_DATA_ACCESS` and `DISABLE_DATA_ACCESS` in `DBMS_CLOUD_AI`. + +Use these controls when administrators need to prevent table data or vector-search documents from being sent to the LLM. Oracle notes that disabling such access also disables related response paths such as `narrate` for RAG workflows. + +--- + +## Practical Scope Example + +Oracle's examples show `object_list` as JSON entries containing owner and object name pairs: + +```sql +"object_list": [{"owner": "SH", "name": "customers"}, + {"owner": "SH", "name": "countries"}] +``` + +Use this pattern to keep NL2SQL scope narrow instead of exposing a whole schema by default. + +--- + +## Best Practices + +- Keep `object_list` as small as the use case allows. +- Enable `constraints` when joins matter. +- Enable `comments` and `annotations` when business meaning is not obvious from identifiers alone. +- Use `Enforce Object List` when you need stronger guardrails around what the AI may consider. +- Review data access controls before enabling RAG or broad metadata augmentation. + +--- + +## Common Mistakes + +### Mistake 1: Enabling a Broad Schema Without Reviewing Metadata Exposure + +Oracle documents that schema metadata can be sent to the AI provider. Broad scope is a governance choice, not only a usability choice. + +### Mistake 2: Expecting Accurate Multi-Table SQL Without Relationship Metadata + +If joins matter, omitting `constraints` removes documented relationship context that helps the model reason about keys. + +### Mistake 3: Assuming `Object List Mode` Exists on Older Releases + +SQL Developer Web documentation explicitly notes that `Object List Mode` is not available with Oracle AI Database 19c. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c (generic):** Select AI metadata controls are not part of the generic 19c baseline. +- **Oracle AI Database 19c / 19.30:** The capability matrix documents `object_list`, `comments`, `constraints`, and `case_sensitive_values`, but not newer features such as `object_list_mode` or `annotations` everywhere. +- **Oracle AI Database 23.26.1 / 26ai docs:** Current documentation includes `object_list_mode`, `annotations`, and automated relevant-object selection. + +--- + +## Sources + +- [SQL Developer Web documentation - Create AI Profile](https://docs.oracle.com/en/database/oracle/sql-developer-web/sdwad/create-ai-profile.html) +- [Oracle Database Select AI Capability Matrix](https://docs.oracle.com/en/database/oracle/oracle-database/26/saicm/index.html) +- [Oracle Database Select AI User's Guide - About Select AI](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/select-ai-about.html) +- [Autonomous Database documentation - Examples of Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-examples.html) +- [Autonomous Database documentation - DBMS_CLOUD_AI Package](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-ai-package.html) diff --git a/skills/ai/select-ai-profiles.md b/skills/ai/select-ai-profiles.md new file mode 100644 index 0000000..82e38a3 --- /dev/null +++ b/skills/ai/select-ai-profiles.md @@ -0,0 +1,191 @@ +# Select AI Profiles in Oracle AI Database + +## Overview + +Select AI is configured through AI profiles. A profile binds together the AI provider, credentials, model selection, conversation settings, NL2SQL metadata scope, and optional RAG vector-index settings. + +Use this file when you need to create, activate, inspect, or update Select AI profiles. Use the other Select AI skills for prompt actions, metadata controls, feedback, RAG, synthetic data, or agents. If you need the Python wrappers `select_ai.Profile` or `ProfileAttributes`, start with `select-ai-python.md` and return here for profile semantics. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Profile concepts and provider support | Oracle Database Select AI User's Guide, **About Select AI** | +| Capability and attribute support by release | Oracle Database Select AI Capability Matrix | +| `DBMS_CLOUD_AI` profile procedures | Autonomous Database documentation, **DBMS_CLOUD_AI Package** | +| Create profile UI and object-list settings | SQL Developer Web documentation, **Create AI Profile** | +| End-to-end profile examples | Autonomous Database documentation, **Examples of Using Select AI** | + +--- + +## Create and Activate a Profile + +Oracle documents `DBMS_CLOUD_AI.CREATE_PROFILE` as the starting point for profile creation: + +```sql +DBMS_CLOUD_AI.CREATE_PROFILE + profile_name IN VARCHAR2, + attributes IN CLOB DEFAULT NULL, + status IN VARCHAR2 DEFAULT NULL, + description IN CLOB DEFAULT NULL +); +``` + +Oracle documents `DBMS_CLOUD_AI.SET_PROFILE` as the session-level activation step: + +```sql +BEGIN + DBMS_CLOUD_AI.SET_PROFILE(profile_name => 'GENAI'); +END; +/ +``` + +Use `DBMS_CLOUD_AI.GET_PROFILE` to inspect the active profile for the current session. + +--- + +## Attribute Groups + +The capability matrix groups profile attributes into stable categories. + +### AI Provider Attributes + +Representative provider attributes documented in the capability matrix include: + +- `provider` +- `credential_name` +- `provider_endpoint` +- `region` +- `azure_deployment_name` +- `azure_embedding_deployment_name` +- `azure_resource_name` +- `oci_apiformat` +- `oci_compartment_id` +- `oci_endpoint_id` +- `oci_runtimetype` + +### General and LLM Attributes + +- `conversation` +- `model` +- `max_tokens` +- `seed` +- `stop_tokens` +- `temperature` + +### NL2SQL Attributes + +- `object_list` +- `object_list_mode` +- `enforce_object_list` +- `comments` +- `annotations` +- `constraints` +- `case_sensitive_values` + +### RAG Attributes + +- `embedding_model` +- `vector_index_name` +- `enable_sources` + +### Translation Attributes + +- `source_language` +- `target_language` + +Use the capability matrix when you need the exact support status of an individual attribute on Autonomous AI Database 19c, Oracle AI Database 19.30, Oracle AI Database 23.26.1, or later environments. + +--- + +## Profile Lifecycle Procedures + +Oracle documents these profile-management procedures and functions in `DBMS_CLOUD_AI`: + +- `CREATE_PROFILE` +- `GET_PROFILE` +- `SET_PROFILE` +- `SET_ATTRIBUTE` +- `SET_ATTRIBUTES` +- `ENABLE_PROFILE` +- `DISABLE_PROFILE` +- `DROP_PROFILE` +- `GRANT_PROFILE_ACCESS` +- `REVOKE_PROFILE_ACCESS` +- `ENABLE_DATA_ACCESS` +- `DISABLE_DATA_ACCESS` + +Use the lifecycle procedures instead of recreating profiles for every change. Keep the profile name stable and update attributes deliberately. + +--- + +## Example Attribute Payload + +Oracle's examples page shows profile creation with a JSON attribute payload: + +```sql +BEGIN + DBMS_CLOUD_AI.CREATE_PROFILE( + profile_name =>'GENAI', + attributes =>'{"provider": "oci", + "credential_name": "GENAI_CRED", + "object_list": [{"owner": "SH", "name": "customers"}, + {"owner": "SH", "name": "countries"}, + {"owner": "SH", "name": "supplementary_demographics"}, + {"owner": "SH", "name": "profits"}, + {"owner": "SH", "name": "promotions"}, + {"owner": "SH", "name": "products"}] + }'); +END; +/ +``` + +This example is intentionally small but shows the two most common profile concerns: + +- selecting a provider and credential path +- constraining NL2SQL scope through `object_list` + +--- + +## Best Practices + +- Keep one profile per clear use case instead of one profile that mixes unrelated schemas, models, and RAG settings. +- Use `SET_ATTRIBUTE` or `SET_ATTRIBUTES` for controlled updates instead of dropping and recreating a profile unnecessarily. +- Keep provider credentials and profile scope separate in your design review. They are different risk surfaces. +- Use the capability matrix before depending on attributes such as `object_list_mode`, `annotations`, `embedding_model`, or `vector_index_name`. + +--- + +## Common Mistakes + +### Mistake 1: Treating Profile Creation as Provider Setup Only + +Oracle profiles are not only provider configuration. They also define metadata scope, NL2SQL behavior, conversations, and optional RAG settings. + +### Mistake 2: Assuming All Attributes Exist on All Releases + +The capability matrix explicitly varies support by release and service type. Do not assume `object_list_mode`, `annotations`, or RAG attributes exist everywhere. + +### Mistake 3: Activating a Profile Without Reviewing Its Metadata Scope + +Oracle documents that schema metadata can be sent to the AI provider. Profile activation is therefore a governance decision, not only a session convenience. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c (generic):** Select AI is not a standard 19c on-premises baseline feature. +- **Autonomous AI Database 19c / Oracle AI Database 19.30:** The capability matrix documents support for core profile management, but not every newer NL2SQL or RAG attribute. +- **Oracle AI Database 23.26.1 / 26ai docs:** Current documentation includes the broadest profile surface, including newer attributes for metadata controls and RAG. + +--- + +## Sources + +- [Oracle Database Select AI User's Guide - About Select AI](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/select-ai-about.html) +- [Oracle Database Select AI Capability Matrix](https://docs.oracle.com/en/database/oracle/oracle-database/26/saicm/index.html) +- [Autonomous Database documentation - DBMS_CLOUD_AI Package](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-ai-package.html) +- [SQL Developer Web documentation - Create AI Profile](https://docs.oracle.com/en/database/oracle/sql-developer-web/sdwad/create-ai-profile.html) +- [Autonomous Database documentation - Examples of Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-examples.html) diff --git a/skills/ai/select-ai-prompts.md b/skills/ai/select-ai-prompts.md new file mode 100644 index 0000000..326de9a --- /dev/null +++ b/skills/ai/select-ai-prompts.md @@ -0,0 +1,184 @@ +# Select AI Prompt Guidance in Oracle AI Database + +## Overview + +Oracle documents prompt behavior for Select AI through action usage notes, prompt augmentation rules, and examples for NL2SQL and RAG. + +Use this file when you need to decide how to phrase prompts, when to use `showsql` or `showprompt`, how prompt augmentation works, or what Oracle explicitly documents as improving Select AI results. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| `SELECT AI` syntax and usage notes | Autonomous Database documentation, **Use AI Keyword to Enter Prompts** | +| Prompt augmentation data | Oracle Database Select AI User's Guide, **About Select AI** | +| SQL generation scope and intended use | Autonomous Database documentation, **Generate SQL from Natural Language Prompts Using Select AI** | +| Action examples | Autonomous Database documentation, **Examples of Using Select AI** | + +--- + +## Start with the Right Action + +Oracle documents different Select AI actions for different prompt outcomes: + +- `showsql` displays the SQL statement +- `explainsql` explains the generated SQL in natural language +- `runsql` runs the generated SQL +- `chat` sends the prompt directly to the LLM +- `showprompt` displays the constructed prompt sent to the model + +Oracle also documents that Select AI focuses on SQL query generation, while general requests can be submitted with the `chat` action. + +Use the action that matches the task before changing prompt wording. + +--- + +## Understand Prompt Augmentation + +Oracle documents prompt augmentation as part of Select AI's design. + +For SQL generation: + +- the database augments the user-specified prompt with schema metadata +- this metadata may include schema definitions, table comments, column comments, and data dictionary content +- the database does not provide table or view contents for SQL generation + +For RAG: + +- Select AI retrieves vector-store content using semantic similarity search +- the retrieved content becomes part of the augmented prompt + +Use this distinction when deciding whether to improve metadata, improve prompt wording, or move the workflow to RAG. + +--- + +## Use `showprompt` to Inspect the Constructed Prompt + +Oracle documents `showprompt` as the action that displays the constructed prompt sent to the generative AI model. + +Oracle also documents these limits: + +- `showprompt` supports NL2SQL and RAG +- `showprompt` does not support synthetic data generation +- `showprompt` does not support `explainsql` +- `showprompt` does not support `narrate` + +Use `showprompt` when you need to inspect prompt augmentation rather than only the generated SQL. + +--- + +## Prompt Text Rules Oracle Explicitly Documents + +Oracle documents these prompt-usage rules: + +- the syntax is `SELECT AI action natural_language_prompt` +- `SELECT AI` works only in `SELECT` +- PL/SQL, DDL, and DML statements cannot be run using the `AI` keyword +- special character rules apply according to Oracle guidelines + +Documented example: + +```sql +select ai how many customers in SF don''t own their own home +``` + +When using case-sensitive values, Oracle's examples show that double quotes in the prompt can preserve case-sensitive matching even when `case_sensitive_values` is set to `false`. + +Documented example: + +```sql +select ai showsql how many people watch "Inception"; +``` + +--- + +## What Oracle Documents as Improving Results + +Oracle explicitly documents these result-improvement measures for NL2SQL: + +- use database views or tables with contextual column names +- add column comments explaining stored values +- add annotations to the metadata sent to the LLM +- add foreign key and referential constraints to the metadata for accurate `JOIN` conditions + +Oracle's examples also document profile controls that affect prompt interpretation: + +- `object_list` +- `enforce_object_list` +- `case_sensitive_values` + +Treat prompt wording and metadata design as part of the same workflow. + +--- + +## Restricting Prompt Scope + +Oracle documents `enforce_object_list` as a way to restrict table access and instruct the LLM to use only the tables specified in the AI profile. + +Oracle's documented example also shows the contrast: + +- with `enforce_object_list = true`, the generated SQL is limited to the named objects +- with `enforce_object_list = false`, the LLM can use other tables and views based on prior knowledge + +Use this control when prompt scope must stay inside an approved object set. + +--- + +## Hallucination and Review Guidance + +Oracle explicitly warns that LLMs are subject to hallucinations and that results are not always correct. + +Oracle documents that: + +- `SELECT AI` may fail to generate SQL +- `SELECT AI` may generate SQL that cannot be run +- the generated SQL may produce incorrect results + +Oracle also notes that, in such cases, Select AI may respond with information to assist in generating valid SQL. + +Use `showsql`, `explainsql`, and `showprompt` as inspection tools before treating an answer path as production-ready. + +--- + +## Best Practices + +- Use `showsql` when validating NL2SQL prompts. +- Use `showprompt` when you need to inspect augmented prompt content. +- Use `explainsql` when you need a more detailed explanation than `showsql`. +- Use contextual object names, comments, annotations, and constraints because Oracle documents them as improving SQL generation. +- Use quoted values in prompts when the query needs case-sensitive matching. + +--- + +## Common Mistakes + +### Mistake 1: Using `chat` for a SQL-generation Problem + +Oracle documents Select AI as focused on SQL generation and reserves `chat` for general requests. + +### Mistake 2: Changing Prompt Wording Without Inspecting Augmentation + +Oracle documents `showprompt` specifically to inspect the constructed prompt. + +### Mistake 3: Assuming Prompt Text Alone Controls Result Quality + +Oracle documents metadata augmentation, comments, annotations, and constraints as part of SQL-generation quality. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c (generic):** Select AI prompt features are not part of the generic 19c baseline. +- **Autonomous AI Database 19c / Oracle AI Database 19.30:** Core `SELECT AI` usage notes and NL2SQL workflows are documented, but newer features such as `showprompt` and `feedback` are not universally available. +- **Oracle AI Database 26ai:** Current documentation includes prompt augmentation for RAG, `showprompt`, metadata enhancements, and updated action guidance. + +--- + +## Sources + +- [Autonomous Database documentation - Use AI Keyword to Enter Prompts](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-keyword-prompts.html) +- [Oracle Database Select AI User's Guide - About Select AI](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/select-ai-about.html) +- [Autonomous Database documentation - Generate SQL from Natural Language Prompts Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database/doc/use-select-ai-generate-sql-natural-language-prompts.html) +- [Autonomous Database documentation - Examples of Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-examples.html) diff --git a/skills/ai/select-ai-python.md b/skills/ai/select-ai-python.md new file mode 100644 index 0000000..0690097 --- /dev/null +++ b/skills/ai/select-ai-python.md @@ -0,0 +1,322 @@ +# Select AI for Python in Oracle AI Database + +## Overview + +Select AI for Python is Oracle's `select_ai` client library for using Select AI capabilities from Python. Oracle documents it as a Python surface over `DBMS_CLOUD_AI`, with support for profiles, conversations, vector indexes, synthetic data generation, feedback, and agent workflows. + +Use this file when the question is specifically about using Select AI from Python, or when you need to choose between these Python implementation paths: + +- the `select_ai` object model +- Python code that sends `SELECT AI ...` SQL to the database +- Python code that calls `DBMS_CLOUD_AI` or `DBMS_CLOUD_AI_AGENT` + +For generic driver topics such as connection pooling, binds, LOBs, and low-level SQL execution, read `skills/appdev/python-oracledb.md`. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Select AI for Python overview, supported platforms, classes | Oracle Database Select AI User's Guide, **Select AI for Python** | +| Python installation, connection, profile, action, async, vector-index examples | Oracle documentation, **Select AI for Python** | +| Python object model reference for profiles, conversations, vector indexes, and agents | Oracle GitHub, **Select AI for Python documentation** | +| Python agent classes | Autonomous Database documentation, **Select AI Agent for Python** | +| Privilege and HTTP-access helper APIs | Oracle documentation, **Select AI for Python** | +| Vector index Python API details | Oracle documentation, **Select AI for Python** | + +--- + +## Choose the Python Entry Point + +| If you need to... | Prefer | Read next | +|---|---|---| +| use a Python object model for profiles, conversations, vector indexes, or async workflows | `select_ai` | this file, then `select-ai-profiles.md` | +| manage prompt history or conversation context from Python | `select_ai` conversations | this file, then `select-ai-prompts.md` | +| configure privileges, HTTP access, or security boundaries from a Python caller | Python helper APIs plus database-side Select AI controls | this file, then `select-ai-security.md` and `skills/appdev/python-oracledb.md` | +| issue one-off Select AI prompts from Python code that already executes SQL | `SELECT AI ...` through your existing driver path | `select-ai-actions.md` and `skills/appdev/python-oracledb.md` | +| invoke package-level Select AI or agent APIs from Python | `DBMS_CLOUD_AI` / `DBMS_CLOUD_AI_AGENT` through your existing driver path | `select-ai-actions.md`, `select-ai-profiles.md`, `select-ai-agent.md`, and `skills/appdev/python-oracledb.md` | +| create or manage vector indexes for Python-driven RAG | `select_ai` vector-index objects | this file, then `select-ai-rag.md` | +| use Python agent, vector-index, or async helper classes | `select_ai` | this file, then `select-ai-agent.md` or `select-ai-rag.md` | + +The important distinction is that `select_ai` is a Python client library with its own classes, while `SELECT AI` and `DBMS_CLOUD_AI` remain database-side SQL and PL/SQL entry points. + +--- + +## What the `select_ai` Library Adds + +Oracle documents these Python-specific capabilities: + +- synchronous and asynchronous connection helpers +- provider classes such as `OpenAIProvider`, `AzureProvider`, `OCIGenAIProvider`, `AWSProvider`, `GoogleProvider`, `AnthropicProvider`, `CohereProvider`, and `HuggingFaceProvider` +- `Profile` and `ProfileAttributes` +- `Conversation` and `ConversationAttributes` +- `VectorIndex` and `VectorIndexAttributes` +- synthetic-data helpers +- privilege and HTTP-access helper functions +- `select_ai.agent` classes for tools, tasks, agents, and teams + +Use `select_ai` when you want a Python-native object model instead of constructing every interaction as raw SQL or PL/SQL text. + +--- + +## Install and Connect + +Oracle documents installation from PyPI: + +```bash +python3 -m pip install select_ai --upgrade --user +``` + +Oracle also documents that `select_ai` installs `python-oracledb` and `pandas` as dependencies. + +Minimal synchronous connection: + +```python +import select_ai + +user = "" +password = "" +dsn = "" + +select_ai.connect(user=user, password=password, dsn=dsn) +``` + +Minimal asynchronous connection: + +```python +import select_ai + +user = "" +password = "" +dsn = "" + +await select_ai.async_connect(user=user, password=password, dsn=dsn) +``` + +Oracle documents that wallet and proxy-related parameters such as `wallet_location`, `wallet_password`, `https_proxy`, and `https_proxy_port` can also be passed to `connect()` and `async_connect()`. + +--- + +## Profile-Centered Workflow + +Oracle's Python documentation uses a profile object as the main workflow surface. + +Documented profile creation pattern: + +```python +import select_ai + +provider = select_ai.OCIGenAIProvider( + region="us-chicago-1", oci_apiformat="GENERIC" +) +profile_attributes = select_ai.ProfileAttributes( + credential_name="my_oci_ai_profile_key", + object_list=[{"owner": "SH"}], + provider=provider, +) +profile = select_ai.Profile( + profile_name="oci_ai_profile", + attributes=profile_attributes, + description="MY OCI AI Profile", + replace=True, +) +``` + +This surface maps directly to the profile concepts covered in `select-ai-profiles.md`. Use this Python API when the application wants Python objects; use the database-side package procedures when the application prefers explicit SQL or PL/SQL calls. + +--- + +## Conversations and Prompt History + +Oracle documents conversation support as a first-class Python capability and lists `ConversationAttributes` among the supported classes. + +Use the Python conversation objects when the application needs: + +- prompt history across turns +- chat-style interactions with preserved context +- a Python object model instead of manual conversation-id handling + +For prompt shaping and inspection semantics, continue to use `select-ai-prompts.md`. For pure SQL or PL/SQL conversation flows, use the database-side Select AI documentation instead of the Python wrapper. + +--- + +## Prompt Actions from Python + +Oracle documents profile methods that mirror the Select AI action families: + +- `run_sql()` +- `show_sql()` +- `explain_sql()` +- `narrate()` +- `chat()` +- `show_prompt()` +- `summarize()` +- `translate()` +- feedback methods such as `add_positive_feedback()` and `add_negative_feedback()` + +Documented action examples: + +```python +import select_ai + +profile = select_ai.Profile(profile_name="oci_ai_profile") + +df = profile.run_sql(prompt="How many promotions ?") +response = profile.show_sql("How many promotions?") +answer = profile.chat(prompt="What is OCI ?") +``` + +Oracle documents `run_sql()` as the default action and shows it returning a pandas DataFrame. + +Use this Python API when the application wants action methods on a profile object. If your code already uses SQL cursors and you only need the database-side syntax, use the documented `SELECT AI` and `DBMS_CLOUD_AI.GENERATE` paths in `select-ai-actions.md`. + +--- + +## Async Workflows + +Oracle documents asynchronous counterparts for connections, profiles, conversations, vector indexes, and agent objects. + +Documented async profile example: + +```python +import select_ai + +await select_ai.async_connect(user=user, password=password, dsn=dsn) +async_profile = await select_ai.AsyncProfile( + profile_name="async_oci_ai_profile", +) +df = await async_profile.run_sql("How many promotions?") +response = await async_profile.show_sql("How many promotions?") +``` + +Use the async surface when the application is already structured around `async` and `await`. Current Oracle documentation explicitly notes Python 3.14 support for Select AI for Python. + +--- + +## Fetch and Update Existing Objects + +Current Oracle documentation highlights two Python API improvements across proxy objects: + +- `fetch()` to retrieve an existing object from the database +- `set_attribute()` and `set_attributes()` for consistent updates + +Use these methods when the application wants to treat Select AI objects as long-lived Python resources instead of repeatedly recreating them. + +This applies across the Python object model, including profiles, conversations, and vector indexes. + +--- + +## Vector Indexes from Python + +Oracle documents `VectorIndex` and `VectorIndexAttributes` as the Python surface for RAG-oriented vector-index management. + +The current Python guide documents capabilities such as: + +- create or replace a vector index +- enable or disable a vector index +- delete a vector index +- fetch an existing vector index object +- manage attributes such as `chunk_size`, `chunk_overlap`, `location`, `object_storage_credential_name`, `profile_name`, `refresh_rate`, `similarity_threshold`, `vector_distance_metric`, and `pipeline_name` + +Oracle also documents that creating a vector index populates it from an object-store location using an async scheduler job. + +Use `VectorIndex` when the application wants a Python-managed RAG ingestion path. Use `select-ai-rag.md` for the Select AI semantics around vector-index-backed retrieval. + +--- + +## Vector Index and Agent Routing + +Oracle documents Python classes for vector-index and agent workflows: + +- `VectorIndex` and `VectorIndexAttributes` +- `select_ai.agent.Tool` +- `select_ai.agent.Task` +- `select_ai.agent.Agent` +- `select_ai.agent.Team` +- async equivalents for both vector-index and agent objects + +Use `select_ai` when you want those workflows modeled as Python objects. Then read: + +- `select-ai-rag.md` for Select AI RAG and vector-index semantics +- `select-ai-agent.md` for database-side agent architecture, built-in tools, and `DBMS_CLOUD_AI_AGENT` + +Oracle's Python agent documentation also calls out: + +- synchronous classes: `Tool`, `Task`, `Agent`, `Team` +- asynchronous classes: `AsyncTool`, `AsyncTask`, `AsyncAgent`, `AsyncTeam` +- tool families for NLSQL, web search, RAG, PL/SQL, notifications, and custom functions + +Use the Python agent classes when the application wants to orchestrate agent objects directly in Python. Use `select-ai-agent.md` when the question is about database-side package orchestration, views, or SQL/PLSQL runtime behavior. + +--- + +## Privileges and HTTP Access + +Oracle documents privilege and HTTP access as separate setup areas. + +Python helper APIs include: + +- `select_ai.grant_privileges` +- `select_ai.revoke_privileges` +- `select_ai.grant_http_access` +- `select_ai.revoke_http_access` + +Oracle also documents updated privilege coverage for `DBMS_CLOUD`, `DBMS_CLOUD_AI`, `DBMS_CLOUD_AI_AGENT`, and `DBMS_CLOUD_PIPELINE`. + +Do not treat Python client setup as replacing the underlying database privilege model. Use `select-ai-security.md` for the database-side meaning of metadata scope, data-access switches, private endpoints, and AI proxy controls. + +--- + +## Best Practices + +- Choose one primary Python surface per workflow: `select_ai` object methods or explicit SQL/PL/SQL calls. +- Keep driver concerns in `skills/appdev/python-oracledb.md` and Select AI semantics in the `skills/ai/` files. +- Use `show_sql()` or `show_prompt()` during debugging before automating `run_sql()` flows. +- Use `fetch()` and `set_attribute()` / `set_attributes()` when the workflow updates existing Select AI objects over time. +- Use `VectorIndex` objects for Python-managed RAG ingestion instead of hand-assembling the same lifecycle as raw SQL if the application already depends on `select_ai`. +- Use the same Select AI profile and metadata guidance from `select-ai-profiles.md`, `select-ai-metadata.md`, and `select-ai-accuracy.md` even when the caller is Python. +- Check platform certification before standardizing on `select_ai` outside Autonomous Database 19c and Autonomous AI Database 26ai. + +--- + +## Common Mistakes + +### Mistake 1: Treating `select_ai` as a Replacement for All Python Database Access + +`select_ai` is a Select AI client library. It does not replace general SQL, pooling, LOB, or transaction guidance from `python-oracledb`. + +### Mistake 2: Sending Python Driver Questions to the Wrong Skill + +If the question is about pools, binds, thin versus thick mode, or generic SQL execution, use `skills/appdev/python-oracledb.md` instead of Select AI skills. + +### Mistake 3: Treating Database-Side and Python-Side Entry Points as the Same Interface + +The underlying capability is Select AI, but the user-facing surfaces differ. `select_ai.Profile.run_sql()` and `SELECT AI ...` are different implementation paths and should be routed differently. + +### Mistake 4: Assuming `select_ai` Is Certified Everywhere + +Oracle documents certification for Autonomous Database 19c and Autonomous AI Database 26ai, and states that other platforms may work but are not certified. + +### Mistake 5: Routing Every Python Question to `select_ai` + +If the user is really asking about pools, binds, generic SQL execution, or PL/SQL invocation mechanics, the right landing file is still `skills/appdev/python-oracledb.md`. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c (generic):** `select_ai` is not a generic 19c baseline feature. +- **Autonomous Database 19c:** Oracle documents Select AI for Python as certified. +- **Autonomous AI Database 26ai:** Oracle documents Select AI for Python as certified. Current 26ai-era documentation includes async, vector-index, feedback, synthetic-data, and agent workflows. +- **Other platforms:** Oracle states that Select AI for Python may work on other platforms, but it is not certified there. + +--- + +## Sources + +- [Oracle Database Select AI User's Guide - Select AI for Python](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/select-ai-python.html) +- [Oracle documentation - Select AI for Python](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/pysai/G41793_03.pdf) +- [Oracle documentation - Select AI for Python Release 1.2.2](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/pysai/G41793_04.pdf) +- [Oracle GitHub - Select AI for Python documentation](https://oracle.github.io/python-select-ai/) +- [Autonomous Database documentation - Select AI Agent for Python](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-agent-python.html) diff --git a/skills/ai/select-ai-rag.md b/skills/ai/select-ai-rag.md new file mode 100644 index 0000000..80dc613 --- /dev/null +++ b/skills/ai/select-ai-rag.md @@ -0,0 +1,148 @@ +# Select AI RAG in Oracle AI Database + +## Overview + +Select AI with Retrieval Augmented Generation (RAG) augments prompts with content retrieved from a vector store by semantic similarity search. Oracle documents this as a way to reduce hallucinations and ground responses in enterprise content. + +Use this file when you need to configure Select AI for vector-store-backed answers instead of pure NL2SQL. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| RAG concepts and workflow | Oracle Database Select AI User's Guide, **Select AI with Retrieval Augmented Generation (RAG)** | +| RAG setup examples | Autonomous Database documentation, **Examples of Using Select AI** | +| RAG capability and attributes | Oracle Database Select AI Capability Matrix | +| Vector-index procedures in Select AI | Autonomous Database documentation, **DBMS_CLOUD_AI Package** | + +--- + +## RAG Workflow + +Oracle documents the RAG flow at a high level as: + +1. the user submits a prompt +2. Select AI generates embeddings for the prompt using the configured embedding model +3. a vector index retrieves semantically similar content +4. the retrieved content is added to the augmented prompt +5. the LLM produces a grounded response + +Oracle documents `narrate` as the main action used in the end-to-end RAG examples. + +--- + +## RAG Profile Attributes + +The capability matrix documents these RAG-related profile attributes: + +- `embedding_model` +- `vector_index_name` +- `enable_sources` + +Use `embedding_model` for prompt and chunk embeddings, `vector_index_name` to bind the profile to the prepared vector index, and `enable_sources` when you want source visibility in the response. + +--- + +## Create and Manage Vector Indexes for Select AI + +Oracle documents `DBMS_CLOUD_AI` procedures to create and manage vector indexes for Select AI: + +- `CREATE_VECTOR_INDEX` +- `UPDATE_VECTOR_INDEX` +- `ENABLE_VECTOR_INDEX` +- `DISABLE_VECTOR_INDEX` +- `DROP_VECTOR_INDEX` +- `GRANT_VECTOR_INDEX_ACCESS` +- `REVOKE_VECTOR_INDEX_ACCESS` + +The capability matrix documents vector-index attributes such as: + +- `chunk_overlap` +- `chunk_size` +- `location` +- `match_limit` +- `object_storage_credential_name` +- `pipeline_name` +- `profile_name` +- `refresh_rate` +- `similarity_threshold` +- `vector_db_provider` +- `vector_dimension` +- `vector_distance_metric` +- `vector_table_name` + +--- + +## In-Database Transformer Models + +Oracle documents that Select AI RAG can use imported ONNX transformer models inside the database. + +Oracle's examples page shows `embedding_model` using the `database:` prefix: + +```sql +BEGIN + DBMS_CLOUD_AI.CREATE_PROFILE( + profile_name => 'OCI_GENAI', + attributes => '{"provider": "oci", + "model": "meta.llama-3.3-70b-instruct", + "credential_name": "GENAI_CRED", + "vector_index_name": "MY_INDEX", + "embedding_model": "database: MY_ONNX_MODEL"}' + ); +END; +/ +``` + +Use this path when you want in-database embedding generation instead of a remote embedding provider. + +--- + +## Sources in Responses + +Oracle documents source-aware output for RAG. When source visibility is enabled, the response can include the documents used for grounding. + +Use this when reviewability matters more than terse output. + +--- + +## Best Practices + +- Use RAG when the answer depends on unstructured content, not when the answer is already in relational tables. +- Keep the AI profile and vector index aligned on embedding model and dimensions. +- Enable sources when you need reviewable answers. +- Treat vector-index lifecycle procedures as part of the application pipeline, not as one-time setup. + +--- + +## Common Mistakes + +### Mistake 1: Using RAG and NL2SQL Interchangeably + +Oracle documents RAG as a vector-store retrieval path. It is not the same mechanism as NL2SQL prompt augmentation over relational metadata. + +### Mistake 2: Forgetting That RAG Support Is Version-Dependent + +The capability matrix does not show RAG support everywhere that basic Select AI exists. + +### Mistake 3: Configuring a Profile Without a Matching Vector Index + +`vector_index_name` and `embedding_model` are part of the profile contract. Configure them deliberately. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Autonomous AI Database 19c:** The capability matrix marks RAG as unavailable. +- **Oracle AI Database 19.30:** The capability matrix marks RAG as unavailable. +- **Oracle AI Database 23.26.1 / 26ai docs:** Current documentation includes RAG, vector-index management, `enable_sources`, and in-database transformer model support. + +--- + +## Sources + +- [Oracle Database Select AI User's Guide - Select AI with Retrieval Augmented Generation (RAG)](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/select-ai-retrieval-augmented-generation.html) +- [Autonomous Database documentation - Examples of Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-examples.html) +- [Oracle Database Select AI Capability Matrix](https://docs.oracle.com/en/database/oracle/oracle-database/26/saicm/index.html) +- [Autonomous Database documentation - DBMS_CLOUD_AI Package](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-ai-package.html) diff --git a/skills/ai/select-ai-security.md b/skills/ai/select-ai-security.md new file mode 100644 index 0000000..24a95e7 --- /dev/null +++ b/skills/ai/select-ai-security.md @@ -0,0 +1,227 @@ +# Select AI Security in Oracle AI Database + +## Overview + +Select AI security is not one switch. Oracle documents separate controls for privilege grants, metadata scope, data exposure to LLMs, network access to providers, private model connectivity, and sidecar-style federation. + +Use this file when the question is about securing Select AI usage, reviewing what can be sent to the LLM, or deciding which Oracle control applies to NL2SQL, `narrate`, RAG, synthetic data generation, or AI proxy database patterns. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Select AI prerequisites and privilege grants | Oracle Autonomous Database documentation, **Manage AI Profiles** | +| Agent package privilege coverage | Oracle documentation, **Select AI for Python** | +| Metadata augmentation and NL2SQL usage guidelines | Oracle Autonomous Database documentation, **Generate SQL from Natural Language Prompts Using Select AI** | +| Data-access switches for `narrate`, RAG, and synthetic data | Oracle Autonomous Database documentation, **DBMS_CLOUD_AI Package** | +| Private model connectivity | Oracle Autonomous Database documentation, **Private Endpoint Access for Select AI Models** | +| AI proxy database and sidecar architecture | Oracle Database Select AI User's Guide, **Use an AI Proxy Database for Select AI NL2SQL** | +| Capability coverage by release | Oracle Database Select AI Capability Matrix | + +--- + +## Security Boundaries by Workflow + +Oracle documents different data-exposure behavior for different Select AI workflows. + +For NL2SQL prompt augmentation: + +- the database augments the prompt with schema metadata only +- this metadata may include schema definitions, table and column comments, and data-dictionary or catalog content +- for SQL generation, Select AI does not provide table or view contents to the LLM + +Oracle separately documents that `narrate` can provide query results to the LLM, and that RAG can provide retrieved vector-store content to the LLM. + +This distinction matters: + +- securing NL2SQL starts with metadata scope +- securing `narrate`, RAG, and synthetic data starts with both metadata scope and data-access controls + +--- + +## Prerequisites and Privilege Controls + +Oracle documents these baseline prerequisites for Select AI: + +- `EXECUTE` on `DBMS_CLOUD_AI` +- network ACL access for the AI provider endpoint +- provider credentials + +For RAG-oriented Select AI, Oracle also documents: + +- `EXECUTE` on `DBMS_CLOUD_PIPELINE` +- sufficient quota in a tablespace for vector-index storage + +For Select AI Agent, Oracle separately documents: + +- `EXECUTE` on `DBMS_CLOUD_AI_AGENT` + +Representative documented privilege examples: + +```sql +GRANT EXECUTE ON DBMS_CLOUD_AI TO ADB_USER; + +GRANT EXECUTE ON DBMS_CLOUD_PIPELINE TO ADB_USER; + +GRANT EXECUTE ON DBMS_CLOUD_AI_AGENT TO ADB_USER; +``` + +Representative documented network ACL example: + +```sql +BEGIN + DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE( + host => 'api.openai.com', + ace => xs$ace_type(privilege_list => xs$name_list('http'), + principal_name => 'ADB_USER', + principal_type => xs_acl.ptype_db) + ); +END; +/ +``` + +Use package privileges, network ACLs, and provider credentials as separate review items. They control different parts of the attack surface. + +--- + +## Metadata Scope Controls + +Oracle documents `object_list`, `object_list_mode`, and `enforce_object_list` as profile controls for narrowing what metadata Select AI may use. + +Use these controls to restrict the metadata sent for NL2SQL generation: + +- `object_list` to specify schemas, tables, or views +- `enforce_object_list` to restrict SQL generation to the chosen objects +- `object_list_mode = automated` on supported releases to limit metadata to relevant tables dynamically + +Oracle also documents `comments`, `annotations`, and `constraints` as metadata sources that may be added to the prompt. + +Use `select-ai-metadata.md` for the detailed semantics of those attributes. Use this file when the question is whether a broader metadata scope is acceptable from a governance standpoint. + +--- + +## Data Access Controls for Results and Documents + +Oracle documents `ENABLE_DATA_ACCESS` and `DISABLE_DATA_ACCESS` as administrator-only procedures. + +These procedures control whether Select AI may send actual database or vector-store content to the LLM for: + +- `narrate` +- Retrieval Augmented Generation (RAG) +- synthetic data generation + +Documented syntax: + +```sql +BEGIN + DBMS_CLOUD_AI.DISABLE_DATA_ACCESS(); +END; +/ + +BEGIN + DBMS_CLOUD_AI.ENABLE_DATA_ACCESS(); +END; +/ +``` + +Use these procedures when administrators need a hard control over whether result rows or retrieved documents can leave the database boundary for LLM processing. + +--- + +## Private Connectivity to Models + +Oracle documents private endpoint support for Select AI model access through Ollama or Llama.cpp deployed behind a private endpoint inside a VCN. + +Oracle's documented architecture uses: + +- a jump server in a public subnet for controlled SSH access +- private subnets for the Autonomous AI Database and AI model servers +- security lists and controlled routing + +Use this pattern when the requirement is to keep model access and prompt traffic off the public internet. + +Private endpoint guidance is about network isolation. It does not replace object-list scope, data-access switches, or ordinary database privilege review. + +--- + +## AI Proxy Database and Sidecar Security + +Oracle documents Select AI sidecar architecture as an AI proxy database pattern. + +In this pattern: + +- Select AI runs in Autonomous AI Database or Oracle AI Database +- remote data remains in its source system +- Select AI reads metadata from local views, external tables, or federated tables that expose remote objects +- the AI proxy database coordinates federated execution across Oracle and non-Oracle systems + +Oracle explicitly documents that this approach relies on metadata, not physical data movement, and that external systems remain authoritative for their data and enforce their own security controls. + +Oracle also documents that Select AI uses existing database roles, security mechanisms, and policies in place to protect data across linked databases. + +Use this pattern when you want to extend NL2SQL to external data without duplicating data into the Select AI database. + +--- + +## Routing to Core Oracle Security Skills + +Select AI-specific controls do not replace normal Oracle security controls. Use the existing security skills when the question goes deeper into these areas: + +- `skills/security/privilege-management.md` for least privilege and role design +- `skills/security/row-level-security.md` for VPD or FGAC +- `skills/security/auditing.md` for Unified Auditing and FGA +- `skills/security/network-security.md` for ACLs, TLS, and network hardening + +Select AI sits on top of those controls. It does not bypass them. + +--- + +## Best Practices + +- Keep `object_list` narrow and review it as a security boundary, not only a usability setting. +- Distinguish metadata exposure from data exposure. Oracle documents them separately. +- Disable data access when `narrate`, RAG, or synthetic data should not send actual content to the LLM. +- Treat private endpoint access as a network-isolation control, not as a substitute for least privilege. +- In sidecar deployments, review both the AI proxy database controls and the source-system controls. + +--- + +## Common Mistakes + +### Mistake 1: Assuming NL2SQL Sends Table Data by Default + +Oracle documents that SQL-generation prompt augmentation uses schema metadata only, not table or view contents. + +### Mistake 2: Forgetting That `narrate`, RAG, and Synthetic Data Have a Different Exposure Model + +Oracle documents separate data-access procedures for these features because they can send actual data or retrieved content to the LLM. + +### Mistake 3: Treating `object_list` as Only a Convenience Feature + +Oracle documents `object_list` and `enforce_object_list` as concrete scope controls. They are part of the security posture. + +### Mistake 4: Treating AI Proxy Databases as Data Copies + +Oracle documents the sidecar pattern as metadata-driven federation where source systems remain authoritative and enforce their own controls. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c (generic):** Select AI security controls are not part of the generic 19c baseline. +- **Autonomous AI Database 19c / Oracle AI Database 19.30:** Oracle documents core Select AI prerequisites, package privileges, ACL setup, and metadata-scoping controls, but newer controls such as automated object-list mode are not part of every earlier release line. +- **Oracle AI Database 23.26.1 / 26ai docs:** Current documentation includes the broadest Select AI security-related surface, including private endpoint guidance, AI proxy database guidance, annotations, and automated relevant-object selection. + +--- + +## Sources + +- [Oracle Autonomous Database documentation - Manage AI Profiles](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/manage-ai-profiles.html) +- [Oracle documentation - Select AI for Python Release 1.2.2](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/pysai/G41793_04.pdf) +- [Oracle Autonomous Database documentation - Generate SQL from Natural Language Prompts Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database/doc/use-select-ai-generate-sql-natural-language-prompts.html) +- [Oracle Autonomous Database documentation - DBMS_CLOUD_AI Package](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-ai-package.html) +- [Oracle Autonomous Database documentation - Private Endpoint Access for Select AI Models](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/private-endpoint-access-select-ai-models.html) +- [Oracle Database Select AI User's Guide - Use an AI Proxy Database for Select AI NL2SQL](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/select-ai-sidecar-databases.html) +- [Oracle Database Select AI Capability Matrix](https://docs.oracle.com/en/database/oracle/oracle-database/26/saicm/index.html) diff --git a/skills/ai/select-ai-synthetic-data.md b/skills/ai/select-ai-synthetic-data.md new file mode 100644 index 0000000..089551b --- /dev/null +++ b/skills/ai/select-ai-synthetic-data.md @@ -0,0 +1,136 @@ +# Select AI Synthetic Data Generation in Oracle AI Database + +## Overview + +Oracle documents synthetic data generation as a Select AI capability for populating schemas or metadata clones without using sensitive source data. The feature is exposed through `DBMS_CLOUD_AI.GENERATE_SYNTHETIC_DATA`. + +Use this file when you need schema-conforming synthetic data for development, testing, demos, or training. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Synthetic data overview | Oracle Database Select AI User's Guide, **Synthetic Data Generation** | +| Function syntax | Autonomous Database documentation, **DBMS_CLOUD_AI Package** | +| End-to-end examples | Autonomous Database documentation, **Examples of Using Select AI** | +| Monitoring status tables | Autonomous Database documentation, **Synthetic Data Generation** | +| Capability support by release | Oracle Database Select AI Capability Matrix | + +--- + +## Single-Table and Multi-Table Syntax + +Oracle documents this single-table form: + +```sql +DBMS_CLOUD_AI.GENERATE_SYNTHETIC_DATA( + profile_name IN VARCHAR2, + object_name IN DBMS_ID, + owner_name IN DBMS_ID, + record_count IN NUMBER, + user_prompt IN CLOB DEFAULT NULL, + params IN CLOB DEFAULT NULL +); +``` + +Oracle documents this multi-table form: + +```sql +DBMS_CLOUD_AI.GENERATE_SYNTHETIC_DATA( + profile_name IN VARCHAR2, + object_list IN CLOB, + params IN CLOB DEFAULT NULL +); +``` + +--- + +## Documented Example + +Oracle documents this multi-table example: + +```sql +BEGIN + DBMS_CLOUD_AI.GENERATE_SYNTHETIC_DATA( + profile_name => 'GENAI', + object_list => '[{"owner": "ADB_USER", "name": "Director","record_count":5}, + {"owner": "ADB_USER", "name": "Movie_Actor","record_count":5}, + {"owner": "ADB_USER", "name": "Actor","record_count":10}, + {"owner": "ADB_USER", "name": "Movie","record_count":5,"user_prompt":"all movies are released in 2009"}]' + ); +END; +/ +``` + +Oracle also documents `params` such as `sample_rows` and `table_statistics` for improving realism. + +--- + +## Monitoring and Troubleshooting + +Oracle documents that large synthetic data jobs are split into chunks and tracked in a status table named: + +```text +SYNTHETIC_DATA$_STATUS +``` + +Use this status table to inspect chunk progress, rows loaded, and per-table aggregation after generation starts. + +--- + +## Benefits Oracle Documents + +Oracle documents synthetic data generation for: + +- populating metadata clones +- starting projects when real data is unavailable +- validating user experiences with realistic data +- supporting AI and machine learning work without exposing sensitive data + +Use it when you need shape and variety, not production truth. + +--- + +## Best Practices + +- Use a dedicated Select AI profile for synthetic data generation instead of sharing the same profile with NL2SQL or RAG workloads. +- Start with a small `record_count` and review output before scaling up. +- Use `user_prompt` only for targeted shaping, not as a substitute for schema design. +- Review `table_statistics` options when realism matters more than random variety. + +--- + +## Common Mistakes + +### Mistake 1: Treating Synthetic Data as a Generic `chat` or `narrate` Workflow + +Oracle documents synthetic data generation as a separate `DBMS_CLOUD_AI` capability with its own function and monitoring pattern. + +### Mistake 2: Ignoring the Status Table for Large Jobs + +Oracle explicitly documents chunk-level status tracking. Use it instead of guessing whether the generation completed correctly. + +### Mistake 3: Assuming Support Is Uniform Across Releases + +The capability matrix shows that synthetic data generation support differs by service type and release line. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Autonomous AI Database 19c:** The capability matrix marks synthetic data generation as supported. +- **Oracle AI Database 19.30:** The capability matrix marks synthetic data generation as supported. +- **Oracle AI Database 23.7+:** The capability matrix marks synthetic data generation as unavailable. +- **Oracle AI Database 23.26.1 / 26ai docs:** Current documentation includes function syntax, examples, and monitoring guidance. + +--- + +## Sources + +- [Oracle Database Select AI User's Guide - Select AI](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/select-ai.html) +- [Autonomous Database documentation - Synthetic Data Generation](https://docs.oracle.com/en-us/iaas/autonomous-database-shared/doc/select-ai-synthetic-data-generation.html) +- [Autonomous Database documentation - DBMS_CLOUD_AI Package](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-ai-package.html) +- [Autonomous Database documentation - Examples of Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-examples.html) +- [Oracle Database Select AI Capability Matrix](https://docs.oracle.com/en/database/oracle/oracle-database/26/saicm/index.html) diff --git a/skills/ai/select-ai.md b/skills/ai/select-ai.md new file mode 100644 index 0000000..23d6fbe --- /dev/null +++ b/skills/ai/select-ai.md @@ -0,0 +1,100 @@ +# Select AI in Oracle AI Database + +## Overview + +Select AI adds natural-language interfaces on top of Oracle Database and Autonomous Database. Oracle documents it as covering NL2SQL, SQL explanation, prompt inspection, feedback-driven SQL refinement, retrieval augmented generation (RAG), synthetic data generation, and agent workflows. + +This file is the entry point for the Select AI skill set. Start here when the question is broad, then load the narrower skill that matches the task. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Concepts, supported platforms, and workflow | Oracle Database Select AI User's Guide, **About Select AI** | +| Capability coverage by release | Oracle Database Select AI Capability Matrix | +| Prompt actions and `SELECT AI` keyword | Autonomous Database documentation, **Use AI Keyword to Enter Prompts** | +| Action and feedback examples | Autonomous Database documentation, **Examples of Using Select AI** | +| AI profiles and attributes | Autonomous Database documentation, **DBMS_CLOUD_AI Package** | +| Metadata controls and object-list modes | SQL Developer Web documentation, **Create AI Profile** | +| Agent workflows | Oracle Database Select AI User's Guide, **Select AI Agent** | + +--- + +## Start Here When + +- you need a broad orientation to Select AI before reading implementation details +- you are not yet sure whether the task is mainly about profiles, actions, metadata, feedback, RAG, or agents +- you want the right next skill instead of reading every Select AI file + +If you already know the exact task, go straight to `skills/ai/SKILLS.md` or use the routing table below. + +--- + +## Minimal Workflow + +Oracle's current Select AI documentation fits this mental model: + +1. Create and enable an AI profile. +2. Choose an action such as `showsql`, `runsql`, `chat`, `showprompt`, `feedback`, or `agent`. +3. Control prompt augmentation with `object_list`, comments, constraints, annotations, or RAG sources. +4. Add feedback, synthetic data generation, or agent teams only when the workflow requires them. + +Minimal documented entry points: + +```sql +BEGIN + DBMS_CLOUD_AI.SET_PROFILE(profile_name => 'OPENAI'); +END; +/ + +SELECT AI showsql how many customers exist; + +SELECT DBMS_CLOUD_AI.GENERATE(prompt => 'how many customers exist', + profile_name => 'OPENAI', + action => 'showsql') +FROM dual; +``` + +Use `DBMS_CLOUD_AI.GENERATE` when `SELECT AI` is not supported in the client surface. + +--- + +## Routing by Task + +| Task | Read next | +|------|-----------| +| use Select AI from Python or choose between `select_ai`, `SELECT AI`, and `DBMS_CLOUD_AI` from Python | `select-ai-python.md` | +| improve overall Select AI NL2SQL accuracy | `select-ai-accuracy.md` | +| design and audit Select AI annotations | `select-ai-annotations.md` | +| configure providers, credentials, models, or session activation | `select-ai-profiles.md` | +| secure Select AI with privileges, metadata scoping, data-access controls, private endpoints, or AI proxy patterns | `select-ai-security.md` | +| shape prompts, inspect prompt augmentation, or decide between `showsql`, `explainsql`, and `showprompt` | `select-ai-prompts.md` | +| choose between `showsql`, `runsql`, `showprompt`, `chat`, `translate`, `summarize`, or `agent` | `select-ai-actions.md` | +| improve SQL generation with `object_list`, comments, annotations, or constraints | `select-ai-metadata.md` | +| refine generated SQL with `feedback` or `DBMS_CLOUD_AI.FEEDBACK` | `select-ai-feedback.md` | +| use Select AI with vector-store-backed RAG | `select-ai-rag.md` | +| generate synthetic data | `select-ai-synthetic-data.md` | +| build teams, agents, tasks, or tools with `DBMS_CLOUD_AI_AGENT` | `select-ai-agent.md` | + +For the full task index across the AI category, read `skills/ai/SKILLS.md`. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c (generic):** Select AI is not part of the generic 19c baseline. +- **Autonomous AI Database 19c / Oracle AI Database 19.30:** Core profile and action workflows are documented, but newer features such as `feedback`, agent workflows, synthetic data generation, `annotations`, and automated object-list mode are not part of the generic 19c baseline. +- **Oracle AI Database 23.26.1 / 26ai docs:** Current documentation includes the broadest Select AI surface, including `feedback`, RAG integration, agent workflows, synthetic data generation, `annotations`, and automated object selection. + +--- + +## Sources + +- [Oracle Database Select AI User's Guide - About Select AI](https://docs.oracle.com/en/database/oracle/oracle-database/26/selai/select-ai-about.html) +- [Oracle Database Select AI Capability Matrix](https://docs.oracle.com/en/database/oracle/oracle-database/26/saicm/index.html) +- [Autonomous Database documentation - Use AI Keyword to Enter Prompts](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-keyword-prompts.html) +- [Autonomous Database documentation - Examples of Using Select AI](https://docs.oracle.com/en-us/iaas/autonomous-database-serverless/doc/select-ai-examples.html) +- [Autonomous Database documentation - DBMS_CLOUD_AI Package](https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-ai-package.html) +- [SQL Developer Web documentation - Create AI Profile](https://docs.oracle.com/en/database/oracle/sql-developer-web/sdwad/create-ai-profile.html) diff --git a/skills/ai/vector-data-type.md b/skills/ai/vector-data-type.md new file mode 100644 index 0000000..ddb1bb2 --- /dev/null +++ b/skills/ai/vector-data-type.md @@ -0,0 +1,127 @@ +# VECTOR Data Type in Oracle AI Database + +## Overview + +The `VECTOR` data type is the storage foundation for Oracle AI Vector Search. Oracle documents it as a built-in type for storing embeddings directly in database tables, alongside relational data. + +Use this file when you need to define vector columns correctly, choose fixed versus flexible shapes, and understand the documented restrictions on vector columns. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| `VECTOR` overview and examples | Oracle AI Vector Search User's Guide, **Create Tables Using the VECTOR Data Type** | +| New feature notes | Oracle AI Database 26ai New Features Guide, **Vector Data Type** | +| Constructors and descriptors | Oracle AI Vector Search User's Guide, **Vector Constructors, Converters, Descriptors, Arithmetic Operators and Aggregate Functions** | + +--- + +## Minimal and Fixed Definitions + +Oracle documents the minimal form as: + +```sql +CREATE TABLE my_vectors (id NUMBER, embedding VECTOR); +``` + +Oracle also documents fixed-shape columns: + +```sql +CREATE TABLE my_vectors (id NUMBER, embedding VECTOR(768, INT8)); +``` + +When you omit dimensions and format, Oracle allows vectors of different dimensions and formats in the same column. Oracle also warns that vectors from different embedding models are not comparable for similarity search. + +--- + +## Dimension Element Formats + +Oracle documents these dimension element formats: + +- `INT8` +- `FLOAT32` +- `FLOAT64` +- `BINARY` + +Oracle also documents `DENSE` and `SPARSE` storage forms. + +```sql +VECTOR(number_of_dimensions, dimension_element_format, SPARSE) +``` + +Use a fixed dimension and format when your embedding model is stable. Use a flexible column only when experimentation requires it. + +--- + +## Restrictions Oracle Documents + +Important documented restrictions include: + +- IVF vector indexes cannot be created on `SPARSE` vectors +- a `VECTOR` column cannot be part of a primary key +- a `VECTOR` column cannot be part of a foreign key +- a `VECTOR` column cannot be part of a unique constraint +- a `VECTOR` column cannot be part of a check constraint +- a `VECTOR` column cannot be a partitioning key +- non-vector indexes such as B-tree, bitmap, text, and spatial indexes cannot be created on a `VECTOR` column + +These are table-design constraints, not only index-design constraints. + +--- + +## Related Functions + +Oracle documents vector functions and descriptors around the data type, including: + +- `TO_VECTOR` +- `FROM_VECTOR` +- `VECTOR_SERIALIZE` +- `VECTOR_NORM` +- `VECTOR_DIMS` +- `VECTOR_DIMENSION_COUNT` +- `VECTOR_DIMENSION_FORMAT` + +Use these when you need conversion, inspection, or SQL-level manipulation of vector values. + +--- + +## Best Practices + +- Fix dimensions and element format when your model contract is stable. +- Keep vectors from different embedding models out of the same production search set. +- Use `SPARSE` only when you understand the resulting index restrictions. +- Store business metadata alongside the vector column so results remain filterable and explainable. + +--- + +## Common Mistakes + +### Mistake 1: Using One Flexible Column for Mixed Embedding Spaces + +Oracle explicitly warns that vectors from different embedding models are not comparable for similarity search. + +### Mistake 2: Expecting Ordinary Index Types on a `VECTOR` Column + +Oracle documents that vector columns cannot use ordinary B-tree, bitmap, text, or spatial indexes. + +### Mistake 3: Designing Constraints Around the Vector Column Itself + +Oracle documents that vector columns cannot participate in several common constraint and key patterns. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c:** The `VECTOR` data type is not available. +- **Oracle Database 23ai:** Oracle introduces the `VECTOR` data type. Oracle documents `COMPATIBLE` requirements beginning with the 23ai vector feature line. +- **Oracle AI Database 26ai:** Oracle documents expanded support such as sparse vectors and more vector functions around the type. + +--- + +## Sources + +- [Oracle AI Vector Search User's Guide - Create Tables Using the VECTOR Data Type](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/create-tables-using-vector-data-type.html) +- [Oracle AI Database 26ai New Features Guide - Vector Data Type](https://docs.oracle.com/en/database/oracle/oracle-database/26/nfcoa/vector-data-type.html) +- [Oracle AI Vector Search User's Guide - Your Vector Documentation Map to GenAI Prompts](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/your-vector-documentation-map-genai-prompts.html) diff --git a/skills/ai/vector-diagnostics.md b/skills/ai/vector-diagnostics.md new file mode 100644 index 0000000..3b536fb --- /dev/null +++ b/skills/ai/vector-diagnostics.md @@ -0,0 +1,114 @@ +# Vector Diagnostics in Oracle AI Database + +## Overview + +Oracle AI Vector Search includes dictionary views, initialization parameters, memory-pool views, and PL/SQL packages for operational diagnosis. + +Use this file when you need to inspect vector memory usage, understand vector-specific parameters, or map a troubleshooting task to the right diagnostic view. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Topic map for diagnostics | Oracle AI Vector Search User's Guide, **Your Vector Documentation Map to GenAI Prompts** | +| Vector memory pool view | Oracle AI Vector Search User's Guide, **V$VECTOR_MEMORY_POOL** | +| Vector restrictions and vector pool sizing | Oracle Database Release Notes, **Restrictions for Oracle AI Vector Search** | +| Vector statistics and parameters | Oracle AI Vector Search topic map, **Oracle AI Vector Search Statistics and Initialization Parameters** | +| Package landscape | Oracle AI Vector Search User's Guide, **DBMS_VECTOR**, **DBMS_VECTOR_CHAIN**, **DBMS_HYBRID_VECTOR** | + +--- + +## `V$VECTOR_MEMORY_POOL` + +Oracle documents `V$VECTOR_MEMORY_POOL` for inspecting Vector Memory allocation. + +The documented example is: + +```sql +select CON_ID, POOL, ALLOC_BYTES/1024/1024 as ALLOC_BYTES_MB, +USED_BYTES/1024/1024 as USED_BYTES_MB +from V$VECTOR_MEMORY_POOL order by 1,2; +``` + +Oracle documents the pool as containing: + +- a `1MB` pool for in-memory neighbor-graph index allocations +- a `64K` pool for metadata + +Use this view first when troubleshooting HNSW memory pressure. + +--- + +## Initialization Parameters + +Oracle documents `VECTOR_MEMORY_SIZE` as the parameter for sizing the Vector Pool manually. + +The release-notes restrictions page also documents behavior when `VECTOR_MEMORY_SIZE` is set to `1` and `sga_target` is greater than `0`: HNSW index creation can automatically grow the vector memory pool to satisfy the new index. + +Use parameter review together with `V$VECTOR_MEMORY_POOL` instead of treating memory pressure as an opaque index failure. + +--- + +## Vector-Specific Views + +The Oracle AI Vector Search topic map groups diagnostics into: + +- text processing views +- views related to vector indexes and hybrid vector indexes +- vector-search statistics and initialization parameters + +Use the topic map as the routing index when you need a more specialized view than `V$VECTOR_MEMORY_POOL`. + +--- + +## Package Landscape + +Oracle documents the vector package landscape as: + +- `DBMS_VECTOR` for index operations, model loading, accuracy reports, and memory advisory +- `DBMS_VECTOR_CHAIN` for chunking, embedding, reranking, text generation, and summarization +- `DBMS_HYBRID_VECTOR` for hybrid search SQL generation and search execution + +## Best Practices + +- Start with memory and parameter inspection before rebuilding HNSW indexes. +- Use the topic map to choose the right diagnostic view family instead of guessing from generic `DBA_*` views. +- Use `DBMS_VECTOR` status and advisor procedures before changing index shape or memory size. +- Keep release notes in view because some vector restrictions are platform-specific. + +--- + +## Common Mistakes + +### Mistake 1: Troubleshooting HNSW Without Checking Vector Memory + +Oracle documents a dedicated vector memory pool and a dedicated view for it. + +### Mistake 2: Treating All Vector Failures as DDL Problems + +Oracle documents separate diagnostics for memory, package operations, and index health. + +### Mistake 3: Ignoring Platform Restrictions + +Oracle documents AI Vector Search restrictions in release notes, including ONNX platform limits and vector-pool sizing behavior. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c:** Vector diagnostics do not exist because AI Vector Search is not available. +- **Oracle Database 23ai:** Oracle introduces vector-specific views, parameters, and package diagnostics with AI Vector Search. +- **Oracle AI Database 26ai:** Current documentation includes the full diagnostics map, `V$VECTOR_MEMORY_POOL`, and expanded package references. + +--- + +## Sources + +- [Oracle AI Vector Search User's Guide - Your Vector Documentation Map to GenAI Prompts](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/your-vector-documentation-map-genai-prompts.html) +- [Oracle AI Vector Search User's Guide - V$VECTOR_MEMORY_POOL](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/vvector_memory_pool.html) +- [Oracle Database Release Notes - Restrictions for Oracle AI Vector Search](https://docs.oracle.com/en/database/oracle/oracle-database/26/rnrdm/issues-all-platforms-2.html) +- [Oracle AI Vector Search User's Guide - DBMS_VECTOR](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_vector-vecse.html) +- [Oracle AI Vector Search User's Guide - DBMS_VECTOR_CHAIN](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_vector_chain-vecse.html) +- [Oracle AI Vector Search User's Guide - DBMS_HYBRID_VECTOR](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_hybrid_vector-vecse.html) diff --git a/skills/ai/vector-embeddings.md b/skills/ai/vector-embeddings.md new file mode 100644 index 0000000..2aeccd0 --- /dev/null +++ b/skills/ai/vector-embeddings.md @@ -0,0 +1,332 @@ +# Vector Embeddings in Oracle AI Database + +## Overview + +Oracle AI Vector Search supports embedding generation both inside the database and through third-party REST providers. Oracle documents chunking, embedding generation, ONNX model import, custom vocabulary and language data, and relational storage as part of the vector workflow. + +Use this file when you need to generate embeddings, choose between SQL and PL/SQL vector-generation surfaces, choose between database and remote providers, or build chunking-plus-embedding pipelines. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Embedding workflow topic map | Oracle AI Vector Search User's Guide, **Your Vector Documentation Map to GenAI Prompts** | +| Vector-generation overview and stage model | Oracle AI Vector Search User's Guide, **Generate Vector Embeddings** | +| SQL and PL/SQL generation surfaces | Oracle AI Vector Search User's Guide, **About SQL Functions to Generate Embeddings** and **About PL/SQL Packages to Generate Embeddings** | +| Chunking utility details | Oracle AI Vector Search User's Guide, **UTL_TO_CHUNKS** | +| Third-party embedding access | Oracle AI Vector Search User's Guide, **Access Third-Party Models for Vector Generation Leveraging Third-Party REST APIs** | +| ONNX import and in-database embeddings | Oracle AI Vector Search User's Guide, **Import ONNX Models into Oracle AI Database End-to-End Example** | +| Custom vocabulary and language data | Oracle AI Vector Search User's Guide, **Create and Use Custom Vocabulary** and **Create and Use Custom Language Data** | +| `DBMS_VECTOR_CHAIN` overview | Oracle AI Vector Search User's Guide, **DBMS_VECTOR_CHAIN** | +| `CREATE_PREFERENCE` for reusable vectorizer settings | Oracle AI Vector Search User's Guide, **CREATE_PREFERENCE** | +| Package reference details | Oracle Database PL/SQL Packages and Types Reference, **DBMS_VECTOR_CHAIN** | + +--- + +## Choose the Execution Surface + +Oracle documents two major execution surfaces for vector generation: + +- SQL functions such as `VECTOR_CHUNKS` and `VECTOR_EMBEDDING` +- PL/SQL packages such as `DBMS_VECTOR` and `DBMS_VECTOR_CHAIN` + +Oracle positions SQL functions as the path for on-the-fly or parallel chunking and embedding operations inside the database. Oracle positions PL/SQL packages as the path for chunking, embedding, text generation, text processing, and similarity-search workflows that can also reach external REST providers. + +Oracle also documents an internal package split: + +- `DBMS_VECTOR` is the lightweight package for common vector operations +- `DBMS_VECTOR_CHAIN` is the advanced package with text processing, `UTL_TO_TEXT`, `UTL_TO_SUMMARY`, and chunker helper procedures + +Use SQL functions when the workflow is centered on relational queries and scoring. Use `DBMS_VECTOR` for lighter-weight embedding workflows. Use `DBMS_VECTOR_CHAIN` when the workflow needs chainable transformation steps, text extraction, chunker helper procedures, or provider JSON payloads. + +--- + +## Stage Model for Embedding Pipelines + +Oracle documents vector generation as a staged transformation process: + +1. optional file-to-text conversion +2. optional chunking +3. embedding generation +4. relational storage and later indexing or retrieval + +This stage model is why Oracle exposes multiple utilities instead of only one embedding call. + +Typical mappings: + +- file to text: `UTL_TO_TEXT` +- text to chunks: `UTL_TO_CHUNKS` +- one text string to one vector: `UTL_TO_EMBEDDING` +- many chunks to many vectors: `UTL_TO_EMBEDDINGS` + +--- + +## Database and Third-Party Providers + +Oracle documents two main provider patterns for embeddings: + +- in-database ONNX embedding models +- third-party REST providers such as Cohere, Google AI, Hugging Face, Generative AI, OpenAI-compatible providers, Vertex AI, Mistral AI, and local Ollama or Private AI endpoints + +Oracle documents provider selection through JSON parameters passed to vector utility functions. + +For the database provider, Oracle documents: + +```json +{ + "provider" : "database", + "model" : "" +} +``` + +Oracle documents additional provider details that matter during design: + +- text embedding can use `cohere`, `googleai`, `huggingface`, `ocigenai`, `openai`, `vertexai`, `mistralai`, `ollama`, or `privateai` +- image embedding is only documented with Vertex AI +- local providers can use `host: "local"` for supported providers such as `ollama` and `privateai` + +Use in-database providers when you want Oracle-managed ONNX execution. Use REST providers when the model lives outside the database or when your organization standardizes on an external embedding service. + +--- + +## `UTL_TO_TEXT` + +Oracle documents `UTL_TO_TEXT` as the conversion step for binary or text documents before chunking. + +Documented parameters include: + +- `plaintext` +- `charset` +- `format` + +Oracle documents these `format` values: + +- `BINARY` for rich content such as PDF or Word +- `TEXT` for plain text +- `IGNORE` for no conversion + +Use `UTL_TO_TEXT` when the source is a file-oriented document instead of already normalized text. + +--- + +## Chunking and Embedding Functions + +Oracle documents the chainable utility functions in `DBMS_VECTOR_CHAIN`: + +- `UTL_TO_TEXT` +- `UTL_TO_CHUNKS` +- `UTL_TO_EMBEDDING` +- `UTL_TO_EMBEDDINGS` +- `UTL_TO_SUMMARY` +- `UTL_TO_RERANK` +- `UTL_TO_GENERATE_TEXT` + +Use `UTL_TO_TEXT` and `UTL_TO_CHUNKS` before embedding when your source is a document rather than already normalized text. + +--- + +## `UTL_TO_CHUNKS` Parameters That Matter + +Oracle documents `UTL_TO_CHUNKS` with these key JSON parameters: + +- `by` +- `max` +- `overlap` +- `split` +- `custom_list` +- `vocabulary` +- `language` +- `normalize` +- `norm_options` +- `extended` + +These parameters drive most chunk-quality decisions: + +- `by` can be `characters`, `words`, or `vocabulary` +- `max` changes meaning depending on `by` +- `split` can be `none`, `newline`, `blankline`, `space`, `recursively`, `sentence`, or `custom` +- `overlap` is documented as `5%` to `20%` of `max` +- `normalize` defaults to `all`, with options such as `punctuation`, `whitespace`, and `widechar` + +Oracle also documents that sentence-aware chunking depends on language-specific punctuation and abbreviation rules, which is why `language` and custom language data matter. + +--- + +## Custom Vocabulary and Language Data + +Oracle documents two helper procedures for improving chunking: + +- `CREATE_VOCABULARY` +- `CREATE_LANG_DATA` + +Use `CREATE_VOCABULARY` when chunking by tokenizer vocabulary instead of by words or characters. Oracle explicitly notes that the vocabulary file should match the embedding model used for chunking. + +Use `CREATE_LANG_DATA` when sentence boundaries or abbreviations need language-specific handling beyond the built-in defaults. + +These helpers matter most when: + +- the embedding model uses token boundaries that differ materially from whitespace words +- the corpus uses domain-specific abbreviations +- the language is segmented or punctuation-heavy + +--- + +## Example: Text to Vector + +Oracle documents this `DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING` signature: + +```sql +DBMS_VECTOR_CHAIN.UTL_TO_EMBEDDING ( + DATA IN CLOB, + PARAMS IN JSON default NULL +) return VECTOR; +``` + +Oracle also documents the simple usage pattern: + +```sql +select dbms_vector_chain.utl_to_embedding('Hello world', json(:params)) from dual; +``` + +Use this form when you want an explicit SQL-level embedding call instead of a larger pipeline. + +--- + +## `UTL_TO_EMBEDDINGS` for Batch Pipelines + +Oracle documents `UTL_TO_EMBEDDINGS` as the array-oriented embedding call for chunk pipelines. + +Oracle's documented example chains text extraction, chunking, and embedding in one relational flow: + +```sql +CREATE TABLE doc_chunks AS +(SELECT dt.id doc_id, et.embed_id, et.embed_data, TO_VECTOR(et.embed_vector) embed_vector + FROM documentation_tab dt, + dbms_vector.utl_to_embeddings( + dbms_vector.utl_to_chunks( + dbms_vector.utl_to_text(dt.data), + json('{"normalize":"all"}')), + json('{"provider":"database", "model":"doc_model"}')) t, + JSON_TABLE( + t.column_value, '$[*]' + COLUMNS ( + embed_id NUMBER PATH '$.embed_id', + embed_data VARCHAR2(4000) PATH '$.embed_data', + embed_vector CLOB PATH '$.embed_vector')) et +); +``` + +Use this shape when the workflow needs reproducible relational storage of chunk text plus embeddings. + +--- + +## In-Database ONNX Model Import + +Oracle documents the in-database ONNX path around `DBMS_VECTOR.LOAD_ONNX_MODEL` and `VECTOR_EMBEDDING`. + +The documented flow is: + +1. prepare a directory object +2. grant directory access and `CREATE MINING MODEL` +3. load the ONNX embedding model with `DBMS_VECTOR.LOAD_ONNX_MODEL` +4. generate embeddings with `VECTOR_EMBEDDING` + +Documented examples: + +```sql +EXECUTE DBMS_VECTOR.LOAD_ONNX_MODEL( + 'DM_DUMP', + 'my_embedding_model.onnx', + 'doc_model'); + +SELECT VECTOR_EMBEDDING(doc_model USING 'hello' AS data) AS embedding; +``` + +Use this path when the model should execute inside Oracle AI Database instead of through a remote provider. + +--- + +## Chunking Preferences for Hybrid Pipelines + +Oracle documents `DBMS_VECTOR_CHAIN.CREATE_PREFERENCE` for reusable vectorizer preferences. + +The package reference shows a vectorizer example that combines chunking and hybrid-index preferences: + +```sql +begin + DBMS_VECTOR_CHAIN.CREATE_PREFERENCE( + 'my_vec_spec', + DBMS_VECTOR_CHAIN.VECTORIZER, + json('{ "vector_idxtype" : "hnsw", + "model" : "my_doc_model", + "by" : "words", + "max" : 100, + "overlap" : 10, + "language" : "english" }')); +end; +/ +``` + +Use preferences when you need repeatable chunking and vectorization behavior across jobs or indexes. + +--- + +## Best Practices + +- Choose SQL functions for scoring-oriented SQL flows and PL/SQL utilities for chainable transformation workflows. +- Keep chunking and embedding settings stable within one corpus. +- Match `CREATE_VOCABULARY` output, `by: "vocabulary"` chunking, and the embedding model tokenizer when using token-aware chunking. +- Use an in-database ONNX model when you need database-local embedding generation. +- Use third-party providers only after reviewing their endpoint, credential, and cost model. +- Preserve source text and document metadata together with the embedding output. + +--- + +## Common Mistakes + +### Mistake 1: Mixing Providers Without a Deliberate Compatibility Plan + +Oracle documents many provider options, but compatibility of embeddings is still a model-space concern. + +### Mistake 2: Embedding Large Documents Without Chunking + +Oracle documents chunking and text extraction utilities because document pipelines usually need them before embedding. + +### Mistake 3: Using Vocabulary Chunking Without Matching the Tokenizer + +Oracle explicitly notes that the chosen model should match the vocabulary file used for chunking. + +### Mistake 4: Treating Text Generation APIs as Embedding APIs + +`UTL_TO_GENERATE_TEXT` and `UTL_TO_EMBEDDING` are different operations. Use the one that matches the workflow. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c:** Oracle AI Vector Search embedding features are not available. +- **Oracle Database 23ai:** Oracle introduces the vector workflow, including ONNX model import and embedding utilities. +- **Oracle AI Database 26ai:** Current documentation includes `DBMS_VECTOR_CHAIN`, third-party embedding access, and end-to-end chunking and embedding pipelines. + +--- + +## Sources + +- [Oracle AI Vector Search User's Guide - Your Vector Documentation Map to GenAI Prompts](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/your-vector-documentation-map-genai-prompts.html) +- [Oracle AI Vector Search User's Guide - Understand the Stages of Data Transformations](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/understand-stages-data-transformations.html) +- [Oracle AI Vector Search User's Guide - About SQL Functions to Generate Embeddings](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/sql-functions-generate-embeddings.html) +- [Oracle AI Vector Search User's Guide - About Chainable Utility Functions and Common Use Cases](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/chainable-utility-functions-and-common-use-cases.html) +- [Oracle AI Vector Search User's Guide - UTL_TO_TEXT](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/utl_to_text.html) +- [Oracle AI Vector Search User's Guide - UTL_TO_CHUNKS](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/utl_to_chunks-dbms_vector_chain.html) +- [Oracle AI Vector Search User's Guide - UTL_TO_EMBEDDING and UTL_TO_EMBEDDINGS](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/utl_to_embedding-and-utl_to_embeddings-dbms_vector_chain.html) +- [Oracle AI Vector Search User's Guide - Access Third-Party Models for Vector Generation Leveraging Third-Party REST APIs](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/access-third-party-models-vector-generation-leveraging-third-party-rest-apis.html) +- [Oracle AI Vector Search User's Guide - Import ONNX Models into Oracle AI Database End-to-End Example](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/import-onnx-models-oracle-ai-database-end-end-example.html) +- [Oracle AI Vector Search User's Guide - SQL Quick Start Using a Vector Embedding Model Uploaded into the Database](https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/sql-quick-start-using-vector-embedding-model-uploaded-database.html) +- [Oracle AI Vector Search User's Guide - DBMS_VECTOR](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_vector-vecse.html) +- [Oracle AI Vector Search User's Guide - CREATE_VOCABULARY](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/create_vocabulary.html) +- [Oracle AI Vector Search User's Guide - CREATE_LANG_DATA](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/create_lang_data.html) +- [Oracle AI Vector Search User's Guide - CREATE_PREFERENCE](https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/create_preference.html) +- [Oracle AI Vector Search User's Guide - DBMS_VECTOR_CHAIN](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_vector_chain-vecse.html) +- [Oracle Database PL/SQL Packages and Types Reference - DBMS_VECTOR_CHAIN](https://docs.oracle.com/en/database/oracle/oracle-database/26/arpls/dbms_vector_chain1.html) diff --git a/skills/ai/vector-indexes.md b/skills/ai/vector-indexes.md new file mode 100644 index 0000000..8dd2677 --- /dev/null +++ b/skills/ai/vector-indexes.md @@ -0,0 +1,146 @@ +# Vector Indexes in Oracle AI Database + +## Overview + +Oracle AI Vector Search supports approximate vector indexes for high-speed similarity search. Oracle documents IVF and HNSW as the two primary vector-index families and provides SQL DDL plus `DBMS_VECTOR` management procedures. + +Use this file when you need to choose an index family, create indexes, or inspect vector-index health and memory planning. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Vector index guidance | Oracle AI Vector Search User's Guide, **Guidelines for Using Vector Indexes** | +| IVF syntax | Oracle AI Vector Search User's Guide, **Inverted File Flat CREATE INDEX** | +| SQL reference | Oracle AI Database SQL Language Reference, **CREATE VECTOR INDEX** | +| Index status, checkpoint, and advisor procedures | Oracle AI Vector Search User's Guide, **Vector Index Status, Checkpoint, and Advisor Procedures** | +| New feature notes | Oracle AI Database 26ai New Features Guide, **Vector Indexes** | + +--- + +## Index Families + +Oracle documents these two primary vector-index families: + +- IVF: `ORGANIZATION NEIGHBOR PARTITIONS` +- HNSW: `ORGANIZATION INMEMORY NEIGHBOR GRAPH` + +Oracle documents vector indexes as the approximate-search path that trades some accuracy for speed. + +--- + +## Documented IVF Example + +Oracle documents this IVF example: + +```sql +CREATE VECTOR INDEX galaxies_ivf_idx ON galaxies (embedding) +ORGANIZATION NEIGHBOR PARTITIONS +DISTANCE COSINE +WITH TARGET ACCURACY 95; +``` + +Oracle documents IVF parameters including: + +- `DISTANCE` +- `WITH TARGET ACCURACY` +- `TYPE IVF` +- `NEIGHBOR PARTITIONS` +- `SAMPLES_PER_PARTITION` +- `MIN_VECTORS_PER_PARTITION` + +--- + +## Metric Matching + +Oracle's index guidance documents that the distance function in the SQL statement must match the distance function used by the vector index for the optimizer to use that index. + +Keep metric choice aligned across: + +- the embedding model +- the vector index +- the query predicate + +--- + +## Restrictions and Planning + +Oracle documents several important restrictions and planning points: + +- IVF cannot index `SPARSE` vectors +- HNSW uses the Vector Memory Pool +- unsupported targets include external tables, IOTs, global temporary tables, materialized views, immutable tables, and function-based vector indexes + +Use HNSW when low-latency approximate search and memory-backed structures fit the workload. Use IVF when its partitioned layout and target-accuracy model fit better. + +--- + +## `DBMS_VECTOR` for Index Operations + +Oracle documents `DBMS_VECTOR` procedures and functions for operational work around vector indexes, including: + +- `CREATE_INDEX` +- `REBUILD_INDEX` +- `GET_INDEX_STATUS` +- `INDEX_ACCURACY_QUERY` +- `INDEX_ACCURACY_REPORT` +- `INDEX_VECTOR_MEMORY_ADVISOR` + +Oracle documents the memory advisor with examples such as: + +```sql +exec DBMS_VECTOR.INDEX_VECTOR_MEMORY_ADVISOR( + INDEX_TYPE=>'HNSW', + NUM_VECTORS=>10000, + DIM_COUNT=>768, + DIM_TYPE=>'FLOAT32', + PARAMETER_JSON=>'{"accuracy":90}', + RESPONSE_JSON=>:response_json); +``` + +Use the advisor before assuming the current Vector Memory Pool is sufficient for HNSW. + +--- + +## Best Practices + +- Choose the index family after deciding metric, memory model, and target latency. +- Use the same distance metric in queries and indexes. +- Use `INDEX_VECTOR_MEMORY_ADVISOR` before large HNSW deployments. +- Revisit IVF organization when Oracle indicates reorganization or rebuild is needed. + +--- + +## Common Mistakes + +### Mistake 1: Treating IVF and HNSW as Interchangeable + +Oracle documents different storage, memory, and maintenance behavior for the two index families. + +### Mistake 2: Ignoring Memory Planning for HNSW + +Oracle documents HNSW as an in-memory neighbor graph. Size the Vector Memory Pool deliberately. + +### Mistake 3: Expecting Approximate Indexes to Fix a Bad Embedding Design + +Oracle documents indexing as a search-acceleration feature, not as a correction layer for bad embeddings or wrong metrics. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c:** Vector indexes are not available. +- **Oracle Database 23ai:** Oracle introduces vector indexes and the `CREATE VECTOR INDEX` statement. +- **Oracle AI Database 26ai:** Oracle documents additional vector-index features such as auto IVF reorganization, scalar-quantized HNSW, and RAC-aware HNSW enhancements. + +--- + +## Sources + +- [Oracle AI Vector Search User's Guide - Guidelines for Using Vector Indexes](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/guidelines-using-vector-indexes.html) +- [Oracle AI Vector Search User's Guide - Inverted File Flat CREATE INDEX](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/inverted-file-flat-index-creation-syntax-and-parameters.html) +- [Oracle AI Database SQL Language Reference - CREATE VECTOR INDEX](https://docs.oracle.com/en/database/oracle/oracle-database/26/sqlrf/create-vector-index.html) +- [Oracle AI Vector Search User's Guide - Vector Index Status, Checkpoint, and Advisor Procedures](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/vector-index-status-checkpoint-and-advisor-procedures.html) +- [Oracle AI Database 26ai New Features Guide - Vector Indexes](https://docs.oracle.com/en/database/oracle/oracle-database/26/nfcoa/vector-indexes.html) diff --git a/skills/ai/vector-operations.md b/skills/ai/vector-operations.md new file mode 100644 index 0000000..adeda24 --- /dev/null +++ b/skills/ai/vector-operations.md @@ -0,0 +1,130 @@ +# Vector Operations in Oracle AI Database + +## Overview + +Oracle AI Vector Search exposes SQL operators and functions for distance calculation, exact search, approximate search, vector arithmetic, and related vector operations. + +Use this file when you need to write vector SQL, choose a distance metric, or understand how Oracle expects query predicates to interact with vector indexes. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Distance metrics | Oracle AI Vector Search User's Guide, **VECTOR_DISTANCE** and the vector topic map | +| Distance function and operators | Oracle AI Vector Search User's Guide, **VECTOR_DISTANCE** | +| Similarity-search SQL | Oracle AI Vector Search User's Guide, **Query Data With Similarity and Hybrid Searches** | +| Vector constructors and descriptors | Oracle AI Vector Search User's Guide, **Vector Constructors, Converters, Descriptors, Arithmetic Operators and Aggregate Functions** | + +--- + +## Distance Metrics + +Oracle documents these vector distance metrics: + +- `COSINE` +- `DOT` +- `EUCLIDEAN` +- `EUCLIDEAN_SQUARED` +- `MANHATTAN` +- `HAMMING` +- `JACCARD` + +Oracle explicitly documents that `JACCARD` requires `BINARY` vectors. + +--- + +## `VECTOR_DISTANCE` and Shorthand Operators + +Oracle documents `VECTOR_DISTANCE(expr1, expr2, metric)` as the general function. + +Oracle also documents shorthand operators: + +```sql +expr1 <-> expr2 +expr1 <=> expr2 +expr1 <#> expr2 +``` + +Oracle documents the mappings as: + +- `<->` -> Euclidean / `L2_DISTANCE` +- `<=>` -> cosine distance +- `<#>` -> negative inner product / dot-product ordering + +--- + +## Exact and Approximate Search + +Oracle documents: + +- exact similarity search without a vector index +- approximate similarity search using a vector index + +Use approximate search when you want vector-index acceleration. Use exact search when correctness is more important than latency or when validating relevance. + +--- + +## Similarity Search SQL + +Oracle documents vector search as ordinary SQL that can be combined with filters, joins, and other relational predicates. + +Use this as the default mental model: vector search is not outside SQL. It is SQL with vector predicates and vector-aware indexes. + +--- + +## Constructors and Descriptors + +Oracle documents functions around vector inspection and manipulation, including: + +- `TO_VECTOR` +- `FROM_VECTOR` +- `VECTOR_SERIALIZE` +- `VECTOR_NORM` +- `VECTOR_DIMS` +- `VECTOR_DIMENSION_COUNT` +- `VECTOR_DIMENSION_FORMAT` + +Use these when you need conversion, inspection, or debugging rather than only search. + +--- + +## Best Practices + +- Match the metric to the embedding model's expected vector space. +- Keep the query metric aligned with the vector index metric. +- Use exact search as a validation baseline before tuning approximate search. +- Combine vector predicates with ordinary SQL filters when business scope matters. + +--- + +## Common Mistakes + +### Mistake 1: Treating All Metrics as Semantically Equivalent + +Oracle documents several metrics because they are not interchangeable. + +### Mistake 2: Using `JACCARD` on Non-Binary Vectors + +Oracle documents `JACCARD` specifically for `BINARY` vectors. + +### Mistake 3: Forgetting That Search Is Still SQL + +Oracle vector operations are designed to participate in ordinary SQL. Use relational filters and joins where they belong. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c:** Vector operations are not available. +- **Oracle Database 23ai:** Oracle introduces vector functions and operators together with AI Vector Search. +- **Oracle AI Database 26ai:** Current documentation includes newer metric coverage such as Jaccard distance and a broader vector-operations surface. + +--- + +## Sources + +- [Oracle AI Vector Search User's Guide - VECTOR_DISTANCE](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/vector_distance.html) +- [Oracle AI Vector Search User's Guide - Query Data With Similarity and Hybrid Searches](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/query-data-similarity-and-hybrid-searches.html) +- [Oracle AI Vector Search User's Guide - Your Vector Documentation Map to GenAI Prompts](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/your-vector-documentation-map-genai-prompts.html) diff --git a/skills/ai/vector-packages.md b/skills/ai/vector-packages.md new file mode 100644 index 0000000..a524119 --- /dev/null +++ b/skills/ai/vector-packages.md @@ -0,0 +1,173 @@ +# Vector Packages in Oracle AI Database + +## Overview + +Oracle AI Vector Search exposes package-level APIs in addition to SQL DDL and query syntax. Oracle documents three main package families: + +- `DBMS_VECTOR` +- `DBMS_VECTOR_CHAIN` +- `DBMS_HYBRID_VECTOR` + +Use this file when you need to choose the right package for vector index operations, embedding and chunking pipelines, reranking and text-generation helpers, or hybrid-search execution. + +--- + +## Documentation Map + +| Topic | Oracle documentation | +|---|---| +| Vector package overview | Oracle AI Vector Search User's Guide, **DBMS_VECTOR**, **DBMS_VECTOR_CHAIN**, and **DBMS_HYBRID_VECTOR** | +| `DBMS_VECTOR` operations | Oracle AI Vector Search User's Guide, **DBMS_VECTOR** | +| `DBMS_VECTOR_CHAIN` operations | Oracle AI Vector Search User's Guide, **DBMS_VECTOR_CHAIN** | +| `DBMS_HYBRID_VECTOR` operations | Oracle AI Vector Search User's Guide, **DBMS_HYBRID_VECTOR** | +| Package reference details | Oracle Database PL/SQL Packages and Types Reference, **DBMS_VECTOR_CHAIN** | + +--- + +## Choose the Package by Task + +Oracle's current package split is functional: + +- use `DBMS_VECTOR` for vector index creation, rebuild, status, accuracy reporting, model loading, and memory advisory +- use `DBMS_VECTOR_CHAIN` for text extraction, chunking, embedding generation, reranking, summarization, and text generation +- use `DBMS_HYBRID_VECTOR` for hybrid search execution and generated SQL helpers + +If the task is ordinary vector SQL or DDL rather than package APIs, start with `vector-operations.md`, `vector-indexes.md`, or `hybrid-vector-search.md` instead. + +--- + +## `DBMS_VECTOR` + +Oracle documents `DBMS_VECTOR` as the operational package for vector indexes and related utilities. + +Representative procedures and functions documented in the user guide include: + +- `CREATE_INDEX` +- `REBUILD_INDEX` +- `GET_INDEX_STATUS` +- `INDEX_ACCURACY_QUERY` +- `INDEX_ACCURACY_REPORT` +- `INDEX_VECTOR_MEMORY_ADVISOR` + +Documented example: + +```sql +exec DBMS_VECTOR.INDEX_VECTOR_MEMORY_ADVISOR( + INDEX_TYPE=>'HNSW', + NUM_VECTORS=>10000, + DIM_COUNT=>768, + DIM_TYPE=>'FLOAT32', + PARAMETER_JSON=>'{"accuracy":90}', + RESPONSE_JSON=>:response_json); +``` + +Use `DBMS_VECTOR` when the question is about index lifecycle, index health, or vector-memory planning. + +--- + +## `DBMS_VECTOR_CHAIN` + +Oracle documents `DBMS_VECTOR_CHAIN` for chainable document and model workflows. + +Representative functions documented in the user guide and package reference include: + +- `UTL_TO_TEXT` +- `UTL_TO_CHUNKS` +- `UTL_TO_EMBEDDING` +- `UTL_TO_EMBEDDINGS` +- `UTL_TO_SUMMARY` +- `UTL_TO_RERANK` +- `UTL_TO_GENERATE_TEXT` + +Documented example: + +```sql +select dbms_vector_chain.utl_to_embedding('Hello world', json(:params)) from dual; +``` + +Use `DBMS_VECTOR_CHAIN` when the workflow is about chunking, embeddings, reranking, summarization, or text generation rather than index management. + +--- + +## `DBMS_HYBRID_VECTOR` + +Oracle documents `DBMS_HYBRID_VECTOR` for hybrid-search execution and helper SQL generation. + +Representative package members documented in the user guide include: + +- `SEARCH` +- `SEARCHPIPELINE` +- `GET_SQL` +- `GET_HYBRID_SQL` +- `GET_SQL_TEMPLATE` + +Documented example: + +```sql +SELECT DBMS_HYBRID_VECTOR.SEARCH( +json('{ "hybrid_index_name" : "my_hybrid_idx", + "vector": + { "search_text" : "stock fraud" }, + "text" : + { "contains" : "$ABC AND $Corporation" }, + "return": + { "topN" : 10 } + }')) +FROM dual; +``` + +Use `DBMS_HYBRID_VECTOR` when the workload needs hybrid retrieval with both lexical and semantic components. + +--- + +## Routing to Neighbor Skills + +| If the task is... | Read | +|-------------------|------| +| vector SQL operators, distance metrics, or exact versus approximate SQL | `vector-operations.md` | +| vector index family selection or `CREATE VECTOR INDEX` | `vector-indexes.md` | +| chunking, provider choice, and embedding workflows | `vector-embeddings.md` | +| hybrid vector index design and restrictions | `hybrid-vector-search.md` | +| views, memory pool, and initialization parameters | `vector-diagnostics.md` | + +--- + +## Best Practices + +- Choose the package by workflow type before looking for subprogram names. +- Use `DBMS_VECTOR` for index management, not document-pipeline work. +- Use `DBMS_VECTOR_CHAIN` when the task includes reranking, summarization, or text generation. +- Use `DBMS_HYBRID_VECTOR` only when the query path is explicitly hybrid. + +--- + +## Common Mistakes + +### Mistake 1: Treating `DBMS_VECTOR` as the Package for All Vector Work + +Oracle splits index management and pipeline helpers across multiple packages. + +### Mistake 2: Looking for Reranking in the Wrong Package + +Oracle documents reranking in `DBMS_VECTOR_CHAIN`, not `DBMS_VECTOR`. + +### Mistake 3: Using `DBMS_HYBRID_VECTOR` for Pure Vector SQL + +Oracle documents it for hybrid-search execution and generated SQL helpers, not as the general package for all vector queries. + +--- + +## Oracle Version Notes (19c vs 26ai) + +- **Oracle Database 19c:** Vector packages are not available because AI Vector Search is not available. +- **Oracle Database 23ai:** Oracle introduces the vector package surface together with AI Vector Search. +- **Oracle AI Database 26ai:** Current documentation includes the broadest package surface across index operations, chainable embedding workflows, and hybrid-search helpers. + +--- + +## Sources + +- [Oracle AI Vector Search User's Guide - DBMS_VECTOR](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_vector-vecse.html) +- [Oracle AI Vector Search User's Guide - DBMS_VECTOR_CHAIN](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_vector_chain-vecse.html) +- [Oracle AI Vector Search User's Guide - DBMS_HYBRID_VECTOR](https://docs.oracle.com/en/database/oracle/oracle-database/26/vecse/dbms_hybrid_vector-vecse.html) +- [Oracle Database PL/SQL Packages and Types Reference - DBMS_VECTOR_CHAIN](https://docs.oracle.com/en/database/oracle/oracle-database/26/arpls/dbms_vector_chain1.html) diff --git a/skills/appdev/python-oracledb.md b/skills/appdev/python-oracledb.md index fc51a3c..58bd156 100644 --- a/skills/appdev/python-oracledb.md +++ b/skills/appdev/python-oracledb.md @@ -7,6 +7,8 @@ - **Thin mode** (default): pure Python, no Oracle Client libraries required. Supports most features. - **Thick mode**: requires Oracle Client (Instant Client or full client). Required for advanced features like Advanced Queuing, Sharding, and some proxy authentication scenarios. +For Select AI-specific Python workflows, including the `select_ai` client library and routing between Python, SQL, and PL/SQL Select AI entry points, read `skills/ai/select-ai-python.md`. + ```bash pip install oracledb ```