> For the complete documentation index, see [llms.txt](https://mariadb.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mariadb.com/docs/mariadb-cloud/cloud-ai/ai-retrieval/database-knowledge-bases.md).

# Database Knowledge Bases

Create a MariaDB Cloud AI Retrieval database knowledge base, build its semantic map, customize it, and query your data in natural language.

A database knowledge base answers questions about the data in a MariaDB service. You ask a question in natural language. AI Retrieval turns it into an SQL query, checks that the query only reads data, runs it, and returns the rows. It can also write an answer from the rows.

For a short walkthrough, see [Quickstart](https://mariadb.com/docs/mariadb-cloud/cloud-ai/ai-retrieval/quickstart.md#create-a-database-knowledge-base).

## Before You Begin

* You need a MariaDB service that holds the data, and a database user that can read it. AI Retrieval sees only the tables and columns that this user can see. To limit what a knowledge base can read, see [Access and Security](https://mariadb.com/docs/mariadb-cloud/cloud-ai/ai-retrieval/access-and-security.md#database-knowledge-bases).
* If the service restricts connections with an IP allowlist, add the AI Retrieval IP address to it. See [Network Access for Database Knowledge Bases](https://mariadb.com/docs/mariadb-cloud/cloud-ai/ai-retrieval/access-and-security.md#network-access-for-database-knowledge-bases).

## Create a Database Knowledge Base

1. In the portal, select **AI Retrieval** in the navigation, and then **Create Knowledge Base**.
2. For **Type**, select **Database Knowledge Base**.
3. Enter a **Name**, and optionally a **Description**.
4. Under **Datasource**, select your service. The hostname, the port, and the credentials of the service are filled in. You can change them, for example to use a user with fewer privileges.
5. Select **Fetch schemas**, and select the **Schema** whose tables the knowledge base can query. If the list cannot be loaded, enter the schema name.
6. Under **Tables**, check the tables that the knowledge base can use. All tables of the schema are included at first. Clear the check box of a table to leave it out, or expand a table to leave out some of its columns. **Exclude all tables** and **Include all tables** change every table at once. Keep at least one table and one of its columns. In an expanded table, each column also has an optional **Description** and, for text columns, a **Literals index** option. For what these do, see [Edit Descriptions and Columns](#edit-descriptions-and-columns).
7. Optionally, expand **Advanced Options** and set these options:
   * **Custom Instructions**: business terminology, domain context, and query conventions that AI Retrieval follows when it writes queries. For example: "revenue" always means net revenue after refunds, and test accounts are always filtered out.
   * **Default max rows**, under **SQL Limits**: the most rows that a question returns, unless the question sets its own limit. The default is 20, and the value can be from 1 to 10,000.
8. Select **Create Knowledge Base**.

A column that you leave out is not described to the model, but the database user can still read it. Grant the user only the columns that the knowledge base should reach.

<figure><img src="https://3360768873-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvPz15Lz0Iw3P3yKR3Prd%2Fuploads%2Fgit-blob-55afd3ab48aff71006ec1cfa83480b0269d840ea%2Fai-retrieval-database-tables.png?alt=media" alt="The Tables section of the Create Knowledge Base form with the customers table expanded. Each of its columns id, name, country, and signed_up has a check box, its data type, a Description field, and a Literals index option."><figcaption><p>The Tables section with a table expanded</p></figcaption></figure>

<figure><img src="https://3360768873-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvPz15Lz0Iw3P3yKR3Prd%2Fuploads%2Fgit-blob-5a98a4b2b68b78bda95857eca0962055531c404b%2Fai-retrieval-database-create.png?alt=media" alt="The Create Knowledge Base form with Database Knowledge Base selected, the service docs-demo, the schema shop, and its four tables listed."><figcaption><p>The Create Knowledge Base form for a database knowledge base</p></figcaption></figure>

AI Retrieval connects to the database and synchronizes its schema. This usually takes a few minutes. If no database is connected within 15 minutes, the setup is marked as failed. When the knowledge base is ready, use **Test** to ask a question, or **Connect** to call it from your application.

## The Semantic Map

The semantic map is the metadata layer that AI Retrieval builds automatically over the connected database. Schema metadata, including indexes and column relations, and exploration queries that a model generates feed table descriptions, two-tier column descriptions, and a column literals index. AI Retrieval uses the semantic map to turn a question into an SQL query.

The semantic map improves as you use it. AI Retrieval indexes failed SQL queries to steer later queries, and it updates column descriptions when your questions clarify what a column means.

AI Retrieval builds the semantic map automatically when you create the knowledge base, including a description of each table with sample rows. You do not need to change anything to start asking questions. The steps in [Customize the Semantic Map](#customize-the-semantic-map) are optional.

The semantic map covers up to 100 tables in each database schema and up to 1,000 columns in each table. AI Retrieval skips the other tables and columns automatically.

Synchronize the schema again after you change the tables of the database. Some changes in the portal also apply only after the next sync. In that case, the knowledge base page shows **Some schema changes apply only after the next sync**. Select **Sync Now**.

## Customize the Semantic Map

Customize the semantic map only when you want to change what AI Retrieval uses, for example to correct a description or to keep a table out of every query.

<figure><img src="https://3360768873-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvPz15Lz0Iw3P3yKR3Prd%2Fuploads%2Fgit-blob-b3f91ef7cfc4878da3bb018da670fe5064de7ae7%2Fai-retrieval-database-kb-ready.png?alt=media" alt="The page of a Ready database knowledge base, with its data source, the statistics of 4 tables, 16 columns, and 0 golden queries, and the Schema Annotations table that lists the tables orders, customers, order_items, and products, each with the status Retrievable."><figcaption><p>The page of a database knowledge base, with the Schema Annotations table</p></figcaption></figure>

### Choose How Each Table Is Used

Each table of the semantic map has a status that decides when AI Retrieval puts it into the context of a question:

| Status                    | Effect                                                               |
| ------------------------- | -------------------------------------------------------------------- |
| **Retrievable** (default) | AI Retrieval includes the table when it is relevant to the question. |
| **Always Include**        | AI Retrieval always includes the table.                              |
| **Never Include**         | AI Retrieval never includes the table.                               |

The status is set by the first sync. In the current release, the annotation editor shows it but cannot change it.

### Edit Descriptions and Columns

1. Open the knowledge base. The **Schema Annotations** section lists the tables of the semantic map.
2. Select **Edit Annotations**.
3. Select a table, and change its **Table description** or the description of a column.
4. Select **Save**.

Descriptions apply right away. In the same editor, you can also control the columns:

| Setting            | What it does                                                                                                                                                                                             | When it applies  |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| **Included**       | Only included columns are mapped and shown to the model.                                                                                                                                                 | At the next sync |
| **Literals Index** | Indexes the distinct values of a column, so that a question can match them. Use it for text columns with a limited set of values, such as categories or statuses. It is available for text columns only. | At the next sync |

If a column was dropped from the database, the editor marks it as **No longer in the database**.

## Test a Database Knowledge Base

1. Open the knowledge base and select **Test**.
2. Enter a question about your data, and select **Test Query**.

The results show the **Generated SQL** and the rows that it returned. If more rows are available than the results show, the drawer says so. These options change the test:

| Option          | Effect                                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **SQL Results** | Includes the result rows in the response, next to the generated answer. When it is off, the SQL is generated but not run.      |
| **SQL Limit**   | The maximum number of rows that the generated query returns.                                                                   |
| **Multi Turn**  | Keeps the conversation history across questions, so that a follow-up question builds on the earlier ones. It is on by default. |

The Test drawer has two tabs, **Retrieve** and **Retrieve & Generate**.

<figure><img src="https://3360768873-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvPz15Lz0Iw3P3yKR3Prd%2Fuploads%2Fgit-blob-255993b58109b65c7f42bddd92b506af865089a2%2Fai-retrieval-database-test.png?alt=media" alt="The Test Knowledge Base drawer of a database knowledge base on the Retrieve tab, with the question Which customer ordered the most widgets, the generated SQL query, and one row with the columns customer_id, name, and widget_quantity."><figcaption><p>The Test drawer of a database knowledge base</p></figcaption></figure>

## Query a Database Knowledge Base with the API

Select **Connect** on the knowledge base to see its endpoints and examples. A database knowledge base has two endpoints:

| Endpoint                   | Result                                                                                     |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| Retrieve rows              | Turns the question into SQL, runs it against the connected database, and returns the rows. |
| Retrieve rows and generate | Does the same, and also answers in plain language from the SQL and the returned rows.      |

Authenticate with an API key, in the same way as for a document knowledge base. See [Connect Your Application](https://mariadb.com/docs/mariadb-cloud/cloud-ai/ai-retrieval/document-knowledge-bases.md#connect-your-application).

## Ask Follow-Up Questions

A database knowledge base can answer a series of questions as one conversation. Each question can refer to the earlier ones, for example "Show the top customers this year" followed by "Only the ones in Germany". AI Retrieval refines the SQL query from the context of the earlier questions.

To use this from the API, send the same `session_key` value with each request of the conversation. Without a `session_key`, each request is answered on its own.

## Safeguards

AI Retrieval protects your data when it runs a generated query:

* **Read-only statements.** AI Retrieval runs only statements that read data: `SELECT`, `WITH`, `SHOW`, `DESCRIBE`, and `EXPLAIN`. It rejects any other statement, such as `INSERT`, `UPDATE`, `DELETE`, or a DDL statement.
* **Row limit.** A query returns at most the number of rows that the question or the knowledge base sets, and never more than 10,000.
* **Timeout.** A query that runs for more than 30 seconds is stopped.

The database user is the main control over what a knowledge base can read. Use a user that has read privileges on the data that the knowledge base needs, and nothing more.

## Next Steps

{% content-ref url="/pages/P8jIKgH1GRY4u4S0mHqc" %}
[Access and Security](https://mariadb.com/docs/mariadb-cloud/cloud-ai/ai-retrieval/access-and-security.md)
{% endcontent-ref %}

{% content-ref url="/pages/p23sE0E1EKazqhWykMGo" %}
[Usage and Billing](https://mariadb.com/docs/mariadb-cloud/cloud-ai/ai-retrieval/usage-and-billing.md)
{% endcontent-ref %}

<sub>*This page is: Copyright © 2026 MariaDB. All rights reserved.*</sub>

{% @marketo/form formId="4316" %}
