Integrate OceanBase vector search with Spring AI Alibaba|OceanBase Database|docs|OceanBase Documentations

OceanBase supports vector data storage, vector indexing, and embedding-based vector search starting with V4.3.3. You can store vectorized data in OceanBase for further search.

The Spring AI Alibaba project is an open-source project that uses Spring AI and provides the best practices for developing Java applications with AI. It simplifies the AI application development process and adapts to cloud-native infrastructure. It helps developers quickly build AI applications.

This topic describes how to integrate the vector search capability of OceanBase with Spring AI Alibaba to implement data import and similarity search features. By configuring vector storage and search services, developers can easily build AI application scenarios based on OceanBase, supporting advanced features such as text similarity search and content recommendation.

Prerequisites

You have deployed OceanBase Database and created a MySQL-compatible user tenant.
- You have set the ob_vector_memory_limit_percentage parameter to enable vector search. We recommend that you set the value to 30.
Download JDK 17+. Make sure that you have installed Java 17 and configured the environment variables.
Download Maven. Make sure that you have installed Maven 3.6+ for building projects and managing dependencies.
Download IntelliJ IDEA or Eclipse. Choose the version that suits your operating system and install it.

Step 1: Obtain the database connection information

Contact the OceanBase deployment personnel or administrator to obtain the database connection string. For example:

obclient -h$host -P$port -u$user_name -p$password -D$database_name

Parameters:

$host: the IP address for connecting to OceanBase Database. If you connect to OceanBase Database through OceanBase Database Proxy (ODP), specify an ODP IP address. If you connect to OceanBase Database directly, specify the IP address of an OBServer node.
$port: the port for connecting to OceanBase Database. If you connect to OceanBase Database through ODP, the default port is 2883, which can be customized when you deploy ODP. If you connect to OceanBase Database directly, the default port is 2881, which can be customized when you deploy OceanBase Database.
$database_name: the name of the database to be accessed.

Notice

The user for connecting to the tenant must have the CREATE, INSERT, DROP, and SELECT privileges on the database.
$user_name: the tenant connection account. If you connect to OceanBase Database through ODP, the account is in the username@tenant name#cluster name or cluster name:tenant name:username format. If you connect to OceanBase Database directly, the account is in the username@tenant name format.
$password: the account password.

Step 2: Set up the Maven project

Maven is a project management and build tool used in this topic. This step describes how to create a Maven project and add project dependencies by configuring the pom.xml file.

Create a project

Run the following Maven command to create a project.

mvn archetype:generate -DgroupId=com.alibaba.cloud.ai.example -DartifactId=vector-oceanbase-example -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Go to the project directory.
```
cd vector-oceanbase-example
```

Configure the `pom.xml` file

The pom.xml file is the core configuration file of the Maven project, used to manage project dependencies, plugins, configurations, and other information. To build the project, you need to modify the pom.xml file and add Spring AI Alibaba, OceanBase vector storage, and other necessary dependencies.

Open the pom.xml file and replace the existing content with the following:

    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
        <parent>
            <groupId>com.alibaba.cloud.ai.example</groupId>
            <artifactId>spring-ai-alibaba-vector-databases-example</artifactId>
            <version>1.0.0</version>
        </parent>

        <artifactId>vector-oceanbase-example</artifactId>

        <properties>
            <maven.compiler.source>17</maven.compiler.source>
            <maven.compiler.target>17</maven.compiler.target>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        </properties>

        <dependencies>
            <!-- Alibaba Cloud AI starter -->
            <dependency>
                <groupId>com.alibaba.cloud.ai</groupId>
                <artifactId>spring-ai-alibaba-starter</artifactId>
            </dependency>

            <!-- Spring Boot Web support -->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>

            <!-- Spring AI auto-configuration -->
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-spring-boot-autoconfigure</artifactId>
            </dependency>

            <!-- Spring JDBC support -->
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-jdbc</artifactId>
            </dependency>

            <!-- Transformers model support -->
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-transformers</artifactId>
            </dependency>

            <!-- OceanBase Vector Database starter -->
            <dependency>
                <groupId>com.alibaba.cloud.ai</groupId>
                <artifactId>spring-ai-alibaba-starter-oceanbase-store</artifactId>
                <version>1.0.0-M6.2-SNAPSHOT</version>
            </dependency>

            <!-- OceanBase JDBC driver -->
            <dependency>
                <groupId>com.oceanbase</groupId>
                <artifactId>oceanbase-client</artifactId>
                <version>2.4.14</version>
            </dependency>
        </dependencies>

        <!-- SNAPSHOT repository configuration -->
        <repositories>
            <repository>
                <id>sonatype-snapshots</id>
                <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
                <releases>
                    <enabled>false</enabled>
                </releases>
                <snapshots>
                    <enabled>true</enabled>
                </snapshots>
            </repository>
        </repositories>
    </project>

Step 3: Configure the connection information of OceanBase

This step configures the application.yml file to add the connection information of OceanBase.

Create the application.yml file in the src/main/resources directory of the project and add the following content:

server:
  port: 8080

spring:
  application:
    name: oceanbase-example
  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY}  # Replace with your DashScope API Key
    vectorstore:
      oceanbase:
        enabled: true
        url: jdbc:oceanbase://xxx:xxx/xxx  # URL for connecting to OceanBase
        username: xxx                     # Username of OceanBase
        password: xxx                     # Password of OceanBase
        tableName: vector_table           # Name of the vector table (automatically created)
        defaultTopK: 2                    # Default number of similar results to return
        defaultSimilarityThreshold: 0.8   # Similarity threshold (0~1, smaller values indicate higher similarity)

Step 4: Create the main application class and controller

Create the startup class and controller class of the Spring Boot application to implement the data import and similarity search features.

Create an application startup class

Create a file named OceanBaseApplication.java in the src/main/java/com/alibaba/cloud/ai/example/vector directory, and add the following code to the file:

package com.alibaba.cloud.ai.example.vector;  // The package name must be consistent with the directory structure.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication  // Enable Spring Boot auto-configuration
public class OceanBaseApplication {
    public static void main(String[] args) {
        SpringApplication.run(OceanBaseApplication.class, args);  // Start the Spring Boot application
    }
}

The sample code creates the core startup class for the project, which is used to start the Spring Boot application.

Create a vector storage controller

Create the OceanBaseController.java file in the src/main/java/com/alibaba/cloud/ai/example/vector directory and add the following code:

package com.alibaba.cloud.ai.example.vector.controller;  // The package name must be consistent with the directory structure.

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

import com.alibaba.cloud.ai.vectorstore.oceanbase.OceanBaseVectorStore;

@RestController  // Mark the class as a REST controller.
@RequestMapping("/oceanbase")  // Set the base path to /oceanbase.
public class OceanBaseController {

    private static final Logger logger = LoggerFactory.getLogger(OceanBaseController.class);  // The logger.

    @Autowired  // Automatically inject the OceanBase vector store service.
    private OceanBaseVectorStore oceanBaseVectorStore;

    // The data import interface.
    @GetMapping("/import")
    public void importData() {
        logger.info("Start importing data");

        // Create sample data.
        HashMap<String, Object> map = new HashMap<>();
        map.put("id", "12345");
        map.put("year", "2025");
        map.put("name", "yingzi");

        // Create a list that contains three documents.
        List<Document> documents = List.of(
            new Document("The World is Big and Salvation Lurks Around the Corner"),
            new Document("You walk forward facing the past and you turn back toward the future.", Map.of("year", 2024)),
            new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", map)
        );

        // Add the documents to the vector store.
        oceanBaseVectorStore.add(documents);
    }

    // The similar document search interface.
    @GetMapping("/search")
    public List<Document> search() {
        logger.info("Start searching data");

        // Perform a similarity search for documents that contain "Spring" and return the two most similar results.
        return oceanBaseVectorStore.similaritySearch(SearchRequest.builder()
                                                     .query("Spring")
                                                     .topK(2)
                                                     .build());
    }
}

Step 5: Start and test the Maven project

Start the project using an IDE

The following example shows how to start the project using IntelliJ IDEA.

The steps are as follows:

Open the project by clicking File > Open and selecting pom.xml.
Select Open as a project.
Find the main class OceanBaseApplication.java.
Right-click and select Run 'OceanBaseApplication.main()'.

Test the project

Import the test data by visiting the following URL:
```
http://localhost:8080/oceanbase/import
```

Perform vector search by visiting the following URL:

http://localhost:8080/oceanbase/search

The expected result is as follows:

[
    {
        "id": "03fe9aad-13cc-4d25-807b-ca1bc314f571",
        "text": "Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!",
        "metadata": {
            "name": "yingzi",
            "id": "12345",
            "year": "2025",
            "distance": "7.274442499114312"
        }
    },
    {
        "id": "75864954-0a23-4fa1-8e18-b78fd870d474",
        "text": "Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!",
        "metadata": {
            "name": "yingzi",
            "id": "12345",
            "year": "2025",
            "distance": "7.274442499114312"
        }
    }
]

FAQ

OceanBase connection failure

Cause: The URL, username, or password is incorrect.
Solution: Check the OceanBase configuration in application.yml and make sure the database service is running.

Dependency conflict

Cause: Conflicts between multiple Spring Boot versions.
Solution: Run mvn dependency:tree to view the dependency tree and exclude the conflicting versions.

SNAPSHOT dependency cannot be downloaded

Cause: The SNAPSHOT repository is not configured.
Solution: Make sure that the sonatype-snapshots repository is added in pom.xml.