> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/platform-development/bring-your-own-vector-db.md).
# Bring Your Own Vector Database
Use your organization's own vector database when creating a knowledge base—supported types, required fields, version and network requirements, and limitations after creation
By default, knowledge bases store vectors in the vector database provided by MaiAgent. If your organization requires index data to remain in an environment it manages, you can connect to your organization's own vector database when creating a knowledge base. MaiAgent still handles file parsing, chunking, and vectorization, but writes the resulting vectors and passages to your database and reads from it during retrieval. This page is intended for customer IT teams, DBAs, and SI partners responsible for preparing databases, network access, and accounts.
{% hint style="info" %}
**Different from the “Database” feature**: The admin console's [Database](https://docs.maiagent.ai/build/database/create-database) feature connects to relational databases (PostgreSQL, MySQL, SQL Server, Oracle, SynxDB) that Text to SQL queries, allowing Agents to look up data. The bring-your-own vector database described here stores a knowledge base's vectors and passages. The two are configured separately and do not affect each other.
**How this page complements the user manual**: For general knowledge base creation steps (name, parser, Embedding model, and so on), see [How to Create a Knowledge Base: Basic Settings](https://docs.maiagent.ai/build/knowledge-base/km-basic-settings) in the user manual. Check whether the feature is enabled under [Organization Overview: Advanced Features](https://docs.maiagent.ai/org/overview/organization-overview#advanced-features). This page covers only vector database specifications and integration requirements.
{% endhint %}
## Availability
| Condition | Description |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| “Custom Vector Database Connection” is enabled for the organization | An Enterprise edition feature. For SaaS, MaiAgent must enable it for your organization; contact your sales representative. It is enabled by default for organizations created after on-premises or private cloud installation |
| Creator's role permissions | “Knowledge Base Permissions” are required to create a knowledge base |
Once enabled, the knowledge base creation dialog includes a Vector Database tab. Organizations without this feature cannot see the tab, and API requests with custom connections are also rejected (`This organization is not authorized to use custom vector database endpoints.`).
## Supported Database Types
On the Vector Database tab, select Use a Custom Vector Database, then choose a type under Select Vector Database Type. The platform supports the following four types; the options actually available are those listed in the form:
| Type | Endpoint URL Format | Authentication Fields | RRF Hybrid Retrieval |
| ----------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Elasticsearch | URL, such as `https://es.acme.com:9200` | API Key (optional; leave blank if the cluster does not require authentication) | Can be enabled or disabled; requires an Enterprise, Platinum, or Trial license |
| OpenSearch | URL; **must use `https://`** | Username, Password (required) | Must be enabled |
| Oracle AI Database 26ai | DSN, such as `oracle.acme.com:1521/ORCLPDB1`; TNS descriptor strings are also accepted | Username, Password (required) | Unsupported; automatically disabled |
| SynxDB | `synxdb.acme.com:5432/vectors`, or `postgresql://synxdb.acme.com:5432/vectors` | Username, Password (required) | Unsupported; automatically disabled |
RRF (Reciprocal Rank Fusion) combines and ranks keyword retrieval and semantic vector retrieval results. Vector retrieval still works normally when RRF is disabled or the database does not support it.
## Version, Account, and Network Requirements
Before creating a knowledge base, click Test Connection. When you submit the creation request, the platform verifies the connection again from the server side (with a 10-second timeout). If it cannot connect, it does not create the knowledge base and returns `Vector database connection failed. Please check if the database is running.`.
| Type | Version | Required Account Permissions |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Elasticsearch | The connection test does not check the version; it reads the license type to determine whether RRF is available | Create indexes; write, query, and delete documents; read license information (if unavailable, RRF is treated as unsupported) |
| OpenSearch | **2.19.0 or later**; the connection test fails immediately for earlier versions | Create indexes; write, query, and delete documents; create search pipelines (the platform creates an RRF pipeline named `maiagent-rrf-pipeline`) |
| Oracle AI Database 26ai | **23.4 or later** (AI Vector Search is available starting with Oracle 23ai) | Create tables and vector indexes; read, write, and delete data |
| SynxDB | The server must have pgvector (the `vector` extension) installed | Create tables and indexes in the `public` schema; read, write, and delete data. If the `vector` extension is not yet enabled, the account also needs permission to enable it, or a DBA must enable it first |
**Network**: MaiAgent servers initiate all connections. Your database must allow connections from MaiAgent servers (common ports: Elasticsearch/OpenSearch 9200, Oracle 1521, SynxDB 5432).
* **SaaS**: The database must be reachable from MaiAgent's cloud services. If you need to add source IPs to a firewall allowlist, contact your MaiAgent representative to obtain them.
* **On-Premises and Private Cloud**: Verify that routing and firewall access from the MaiAgent hosts to the database are enabled.
{% hint style="warning" %}
OpenSearch accepts only `https://` because credentials are sent with every request. Using `https://` is also recommended for Elasticsearch.
{% endhint %}
## Data Layout
* MaiAgent creates indexes (Elasticsearch/OpenSearch) or tables (Oracle, SynxDB) in your database, with names that include `agent_` and are based on the Embedding model. Knowledge bases using the same Embedding model in the same database share an index or table, with data distinguished by knowledge base.
* Do not manually rename, delete, or recreate these indexes and tables, or directly modify their data. Add, delete, and reparse files through MaiAgent.
* When you delete a knowledge base, the platform schedules cleanup of its vector data in your database. Keep the connection available until cleanup finishes.
* For billing items, see [Credits Billing System](https://docs.maiagent.ai/others/credits) in the user manual.
## Limitations After Creation
| Item | Rule |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Changing the vector database | **Not allowed**. After creation, the Vector Database tab displays “The vector database configuration is locked after the knowledge base is created and cannot be modified.” To switch databases or return to the system default, create a new knowledge base and upload the files again |
| Adjusting RRF | Elasticsearch allows toggling it during editing; after a license upgrade, click Recheck and enable it |
| Moving files to another knowledge base | The destination knowledge base must use the same vector settings. See [Moving Knowledge Base Files](https://docs.maiagent.ai/build/knowledge-base/km-file-move) in the user manual |
| Database temporarily unreachable | Retrieval and file processing for that knowledge base fail during this period. Connection information remains stored on the knowledge base, so no reconfiguration is needed once connectivity is restored |
## Create via API
Use `POST /api/v1/knowledge-bases/` with the following fields to create a knowledge base using your own vector database. For the complete field list, see [Knowledge Bases (New)](https://docs.maiagent.ai/api/api-reference/zhi-shi-ku-xin-ban) on the API documentation site:
| Field | Description |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `vectorDatabaseType` | `elasticsearch`, `opensearch`, `oracle`, or `synxdb` |
| `vectorDatabaseUrl` | Endpoint URL or DSN; leave blank to use the system default |
| `vectorDatabaseApiKey` | Elasticsearch API Key |
| `opensearchUsername`, `opensearchPassword` | OpenSearch credentials |
| `oracleUser`, `oraclePassword` | Oracle credentials |
| `synxdbUser`, `synxdbPassword` | SynxDB credentials |
| `enableRrf` | Whether to enable RRF; always `false` for Oracle and SynxDB, and must be `true` for OpenSearch |
When reading a knowledge base, password fields are not returned. Elasticsearch and OpenSearch URLs and API Keys are returned masked. Before creation, you can call `POST /api/v1/validate-credentials/vector-database/{類型}/` to test the connection separately. This is also the endpoint used by Test Connection in the admin console.
## Frequently Asked Questions
Why can't I see the “Vector Database” tab when creating a knowledge base?
“Custom Vector Database Connection” has not been enabled for your organization. This is an Enterprise edition feature; contact your sales representative to enable it.
Why is RRF automatically disabled even though the Elasticsearch connection succeeds?
RRF requires an Enterprise, Platinum, or Trial license. Keep it disabled without one of these licenses; otherwise, the cluster rejects retrieval requests. After upgrading your license, click Recheck on the knowledge base editing screen.
Why does the OpenSearch connection test report that the version is too old?
MaiAgent uses OpenSearch search pipelines for RRF, which requires version 2.19.0 or later. Upgrade your cluster first.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/tech/en/platform-development/bring-your-own-vector-db.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.