DBAPI Integration with Milvus Vector Database: Practical Guide to HTTP Executor Parameter Mapping

What is Milvus?

Milvus is an open-source vector database designed specifically for AI applications, supporting the storage, indexing, and similarity search of massive vector datasets. It is widely used in scenarios such as RAG (Retrieval-Augmented Generation), semantic search, and recommendation systems.

Milvus provides a complete RESTful API interface, enabling operations like inserting, querying, and searching vector data via the HTTP protocol.

Why Use DBAPI to Connect to Milvus?

Directly calling Milvus's HTTP API requires manually constructing request URLs, building request parameters, and handling authentication and authorization. By integrating Milvus through DBAPI's HTTP executor, you gain:

• Unified API Management: All Milvus operations are managed uniformly via DBAPI APIs, with out-of-the-box support for permissions, rate limiting, and monitoring.
• Simplified Parameter Mapping: Custom mapping modes automatically convert business parameters into the required request format for Milvus, eliminating the need for callers to worry about Milvus interface details.
• Security Controls: Inherits DBAPI’s token-based authentication and IP firewall capabilities.
• Zero-Code Integration: No integration code is needed—everything is configured through simple settings.

Key Feature: Custom Parameter Mapping with the HTTP Executor

DBAPI Enterprise Edition 4.5.0 enhances the HTTP executor with a custom mapping mode. Using a JSON template combined with ${} placeholders and Groovy expressions, you can flexibly map caller-provided parameters into the target API’s request body format.

Caller Input: { "collection": "my_collection", "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }
                │ HTTP Executor Parameter Mapping
                ▼  
Milvus Receives: { "collectionName": "my_collection", "data": [{ "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }] }

Hands-On: Integrating with Milvus

Prerequisites

• DBAPI Enterprise Edition 4.5.0 or later
• A deployed Milvus service (this document uses Milvus HTTP API v2 as an example)
• A collection already created in Milvus

Step 1: Create an HTTP Data Source

In the DBAPI management console, go to Data Source Management and click "Create Data Source":

Configuration Item	Value
Name	Milvus Service
Type	HTTP
Address	http://192.168.1.100:19530

The address refers to Milvus’s HTTP port, which defaults to 19530.

Step 2: Create an Insert Vector API

Within the desired group, create an API using the HTTP executor.

Basic Information

Configuration Item	Value
API Name	Milvus Insert Vector
API Path	/milvus/insert
Access Permission	private
Request Parameters	id (bigint), vector (string), text (string)

The vector parameter is a JSON string, such as [0.1, 0.2, 0.3, ...].

Executor Configuration

Configuration Item	Value
Executor Type	HTTP Interface Proxy Executor
Data Source	Milvus Service
Method	POST
URL Path	/v2/vectordb/entities/insert
Content-Type	application/json
Parameter Passing Mode	Custom Mapping

Custom Request Headers:

Key	Value
Authorization	YOUR_MILVUS_TOKEN

If Milvus has authentication enabled, configure the token in the custom headers; the HTTP executor will automatically inject it into the forwarded request.

Request Body Template:

{"collectionName": "news_articles", "data": [{"id": ${_parameters.id}, "vector": ${_parameters.vector}, "text": ${_parameters.text}}]}

The collectionName is hardcoded in the template, so the caller does not need to pass it. The vector parameter is passed as a JSON array string, mapped directly to Milvus’s vector field.

Invocation Result

Caller Request:

POST https://127.0.0.1:8520/milvus/insert
Content-Type: application/json

{
  "id": 1001,
  "vector": [0.352, 0.187, 0.921, 0.453, 0.672],
  "text": "DBAPI Integration with Vector Database"
}

The system maps the request according to the template and forwards it to Milvus (the HTTP executor automatically adds the custom headers):

POST http://192.168.1.100:19530/v2/vectordb/entities/insert
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN

{"collectionName": "news_articles", "data": [{"id": 1001, "vector": [0.352, 0.187, 0.921, 0.453, 0.672], "text": "DBAPI Integration with Vector Database"}]}

Step 3: Create a Vector Search API

Basic Information

Configuration Item	Value
API Name	Milvus Vector Search
API Path	/milvus/search
Access Permission	private
Request Parameters	vector (string), limit (bigint)

Executor Configuration

Configuration Item	Value
Executor Type	HTTP Interface Proxy Executor
Data Source	Milvus Service
Method	POST
URL Path	/v2/vectordb/entities/search
Content-Type	application/json
Parameter Passing Mode	Custom Mapping

Request Body Template:

{"collectionName": "news_articles", "vector": ${_parameters.vector}, "limit": ${_parameters.limit}, "outputFields": ["id", "text", "vector"]}

The collectionName is hardcoded in the template, so the caller only needs to provide the vector and limit.

Invocation Result

Caller Request:

POST https://127.0.0.1:8520/milvus/search
Content-Type: application/json

{
  "vector": [0.350, 0.190, 0.910, 0.450, 0.670],
  "limit": 5
}

The system maps the request and forwards it to Milvus:

POST http://192.168.1.100:19530/v2/vectordb/entities/search
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN

{"collectionName": "news_articles", "vector": [0.350, 0.190, 0.910, 0.450, 0.670], "limit": 5, "outputFields": ["id", "text", "vector"]}

Step 4: Create an ID-Based Query API

Basic Information

Configuration Item	Value
API Name	Milvus Query Vector
API Path	/milvus/query
Access Permission	private
Request Parameters	collection (string), id (bigint)

Executor Configuration

Configuration Item	Value
Executor Type	HTTP Interface Proxy Executor
Data Source	Milvus Service
Method	POST
URL Path	/v2/vectordb/entities/query
Content-Type	application/json
Parameter Passing Mode	Custom Mapping

Request Body Template:

{"collectionName": "news_articles", "filter": "id == " + ${_parameters.id}, "outputFields": ["id", "text", "vector"]}

The filter condition is dynamically constructed using a Groovy expression (id == 1001), so the caller does not need to understand Milvus query syntax.

Invocation Result

Caller Request:

POST https://127.0.0.1:8520/milvus/query
Content-Type: application/json

{
  "id": 1001
}

The system maps the request and forwards it to Milvus:

POST http://192.168.1.100:19530/v2/vectordb/entities/query
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN

{"collectionName": "news_articles", "filter": "id == 1001", "outputFields": ["id", "text", "vector"]}

Additional Parameter Mapping Techniques

Complex Nested Structures

If a Milvus collection contains multiple vector fields or nested fields, you can construct requests flexibly using templates:

{"collectionName": ${_parameters.collection}, "data": [{"id": ${_parameters.id}, "titleVector": ${_parameters.titleVector}, "contentVector": ${_parameters.contentVector}, "metadata": {"author": ${_parameters.author}, "tags": ${_parameters.tags}}}]}

Parameter Calculations

Perform pre-processing on input parameters:

{"collectionName": ${_parameters.collection}, "vector": ${_parameters.vector}, "limit": ${_parameters.limit + 10}, "offset": ${(_parameters.page - 1) * _parameters.pageSize}}

Conditional Assignments

Dynamically set search parameters based on input values:

{"collectionName": ${_parameters.collection}, "vector": ${_parameters.vector}, "limit": ${_parameters.limit}, "params": {"nprobe": ${_parameters.precision == "high" ? 64 : 16}}}

Summary

With DBAPI’s HTTP executor and its custom parameter mapping feature, integrating with the Milvus vector database becomes remarkably straightforward:

• Callers only need to pass business-semantic parameters without worrying about Milvus API details.
• Parameter mapping templates are centrally managed; when Milvus interfaces change, simply update the templates—callers remain unaffected.
• Interfaces inherit DBAPI’s enterprise-grade capabilities, including authentication, rate limiting, and monitoring.
• Zero-code integration—everything is configured through simple settings.

Version Requirement: DBAPI Enterprise Edition 4.5.0 or later supports the HTTP executor’s custom parameter mapping feature.