> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# vsql_ai extension for MySQL

> The vsql_ai extension calls Claude, Gemini, OpenAI, and local Ollama models from SQL, returning prompt answers and embedding vectors inside a query.

Most database AI work follows the same shape: read rows, send them to a model,
wait, write the answers back. `vsql_ai` removes the middle by calling the model
from SQL. Two functions cover it, one for a prompt and one for an embedding,
and both work against Anthropic Claude, Google Gemini, OpenAI, or a model
running locally through Ollama.

|                                   |                                                             |
| --------------------------------- | ----------------------------------------------------------- |
| **Maintainer**                    | VillageSQL                                                  |
| **Source and full documentation** | [villagesql/vsql-ai](https://github.com/villagesql/vsql-ai) |
| **License**                       | GPL-2.0                                                     |

## Install

`vsql_ai.veb` is already in the server's `lib/veb/` directory if you installed
VillageSQL with the install script, the Docker image, or a release tarball.
Install it into the server with one statement:

```sql theme={null}
INSTALL EXTENSION vsql_ai;
```

Confirm it is there:

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_ai';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_ai        |
+----------------+
```

To build it yourself, follow the build instructions in the
[repository](https://github.com/villagesql/vsql-ai).

## What it adds

| Function                                       | Returns | What it does                                 |
| ---------------------------------------------- | ------- | -------------------------------------------- |
| `ai_prompt(provider, model, api_key, prompt)`  | text    | Sends a prompt and returns the model's reply |
| `ai_embedding(provider, model, api_key, text)` | text    | Returns the embedding vector as a JSON array |

`provider` is `anthropic`, `google`, `openai`, or `local`. A local model runs
through Ollama and takes an empty API key. `ai_embedding` supports Google,
OpenAI, and local models.

## Example

Ask a local model a question:

```sql theme={null}
SELECT ai_prompt('local', 'llama3.2', '', 'Reply with exactly one word: the capital of France.') AS answer;
```

```
+--------+
| answer |
+--------+
| Paris. |
+--------+
```

A model answers in its own words, so your reply will differ from that one.

Turn text into a vector and check its width:

```sql theme={null}
SELECT JSON_LENGTH(ai_embedding('local', 'nomic-embed-text', '', 'Machine learning')) AS dimensions;
```

```
+------------+
| dimensions |
+------------+
|        768 |
+------------+
```

A hosted provider takes the same call with a key:

```sql theme={null}
SET @api_key = '...';
SELECT ai_prompt('anthropic', 'claude-opus-5', @api_key, 'Hello!');
```

<Note>
  On VillageSQL 0.0.6 and earlier the result carries the binary character set,
  and two things follow. A JSON function or a `JSON` column rejects it, so the
  embedding example above fails there with
  `ERROR 3144 (22032): Cannot create a JSON value from a string with CHARACTER
      SET 'binary'.` Inside `JSON_OBJECT()` or `JSON_ARRAY()` it is accepted but
  base64-encoded, so `SELECT JSON_OBJECT('v', ai_prompt(...))` gives
  `{"v": "base64:type15:UGFyaXMu"}`. Wrap the call in
  `CONVERT(... USING utf8mb4)` on those versions. It is unnecessary on 0.0.7 and
  later, where the examples above run as written.
</Note>

<Warning>
  Each call blocks its statement while the model answers, and each call costs
  whatever the provider charges. One call per row across a large table is slow
  and expensive. Keep an API key out of the statement text, where it would land
  in the query log, by setting it into a variable first.
</Warning>

## See also

* [Setting up an AI API key](/docs/guides/ai-api-setup) — where to put the key and how to keep it out of logs
* [AI prompts in MySQL](/docs/guides/ai-prompts-in-mysql) — prompting patterns that survive contact with a table
* [Generating vector embeddings](/docs/guides/vector-embeddings) — storing vectors and searching them
* [Install extensions](/docs/mysql-8.4/stable/install) — how `INSTALL EXTENSION` works and where the server looks for a bundle
* [Available extensions](/docs/mysql-8.4/stable/extensions) — the full catalog
* [villagesql/vsql-ai](https://github.com/villagesql/vsql-ai) — source, build instructions, and the known limitations