Integrate OceanBase Cloud Vector with Spring AI Alibaba|OceanBase Cloud| docs|Distributed Database

Integrate OceanBase Cloud Vector with Spring AI Alibaba

Last Updated：2025-11-17 13:23:16 Updated

OceanBase Database V4.3.3 and later support vector data storage, vector indexing, and embedding vector search. You can store vectorized data in OceanBase Database for future searches.

The Spring AI Alibaba project is an open source project that uses Spring AI and provides the best practices for developing Java applications with AIsy. 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 Cloud with Spring AI Alibaba to implement data import and similar search features. By configuring vector storage and search services, developers can easily build AI application scenarios based on OceanBase Database, supporting advanced features such as text similarity search and content recommendation.

Prerequisites

A transactional instance is available in your environment. For instructions on how to create the instance, see Create an transactional instance.
You have created a MySQL-compatible tenant in the instance. For instructions on how to create the tenant, see Create a MySQL-compatible tenant.
You have a MySQL database and account available under the tenant, and you have granted read and write permissions to the database account. For more information, see Create an account and Create a database (MySQL only).
You are a project admin or instance admin and have the permissions required to read and write data in the instance. If not, contact your organization admin to grant the required permissions.
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

Log in to the OceanBase Cloud console.
In the instance list page, expand the the information of the target instance.
Select Connect > Get Connection String under the target tenant.
In the pop-up window, select Public Network as the connection method.
Follow the prompts in the pop-up window to obtain the public endpoint and the connection string.

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 Database, 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 Database

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

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 Database
        username: xxx                     # Username of OceanBase Database
        password: xxx                     # Password of OceanBase Database
        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"
        }
    }
]

FAQs

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.

Previous topic

Trae

Last

Next topic

Cline