文档中心

向量数据库VikingDB

请输入

检索(Search)

searchByKeywords

概述

SearchByKeywords 用于关键词检索，适用于带有 text 字段向量化配置（vectorize 参数）的索引，支持多个关键词的检索。

方法定义

public DataApiResponse<SearchResult> searchByKeywords(SearchByKeywordsRequest request)
            throws ApiClientException, VectorApiException

请求参数

请求参数为 SearchByKeywordsRequest，SearchByKeywordsRequest 实例包含的参数如下表所示。

参数	类型	是否必选	说明
keywords	List[String]	是	关键词列表，列表元素 1-10 个，元素不允许为空字符串
caseSensitive	Boolean	否	是否区分大小写。默认 false。
filter	Map[String, Object]	否	过滤条件，详见标量过滤默认为空，不做过滤。过滤条件包含 must、must_not、range、range_out 四类查询算子，包含 and 和 or 两种对查询算子的组合。
outputFields	List[String]	否	要返回的标量字段列表。用户不传 outputFields 时，返回所有标量字段用户传一个空列表不返回标量字段 outputFields 格式错误或者过滤字段不是 collection 里的字段时，接口返回错误
limit	Integer	否	检索结果数量，最大 5000 个。
offset	Integer	否	偏移量。仅分页场景下使用，不建议设置过大值，否则有深分页影响。默认值为 0。设置值至少为 0，语义和 MySQL 的 offset 相同。
advance	SearchAdvance	否	高级参数，详见检索公共参数

返回参数

属性	类型	说明
data	List[SearchItem]	见下
filterMatchedCount	Integer	筛选匹配数量
totalReturnCount	Integer	返回数量
realTextQuery	String	实际参与检索的文本查询
tokenUsage	Object	token 使用情况

List[SearchItem]

属性	类型	说明
id	Object	主键 id。
fields	Map[String, Object]	请求返回中的 fields 字段
score	Float	相似度
annScore	Float	ANN 得分

示例

运行示例前，请完成以下准备：
按“安装与 client 初始化”文档在 Java 项目中引入 VikingDB V2 SDK，并将示例放入可执行的 main 方法后编译运行。
AK/SK 在火山引擎控制台“密钥管理”中创建；Host 和 Region 取自地域和访问域名，并按代码读取方式配置相应环境变量。
Collection、Index 名称从 VikingDB 控制台对应资源详情获取，Task ID 使用创建或查询任务接口返回的 ID。请将代码中的 <YOUR_...> 占位符全部替换为真实值。
若示例包含 TOS 路径，请从 TOS 控制台确认桶名和对象路径，并替换为真实的 <YOUR_BUCKET_NAME>/<YOUR_TOS_PATH>。

请求参数

package org.example.newsubproduct.data.search;


import com.volcengine.vikingdb.runtime.core.ClientConfig;
import com.volcengine.vikingdb.runtime.core.auth.AuthWithAkSk;
import com.volcengine.vikingdb.runtime.enums.Scheme;
import com.volcengine.vikingdb.runtime.exception.VectorApiException;
import com.volcengine.vikingdb.runtime.vector.model.request.*;
import com.volcengine.vikingdb.runtime.vector.model.response.*;
import com.volcengine.vikingdb.runtime.vector.service.VectorService;

import java.util.Arrays;

public class SearchByKeywords {

    public static void main(String[] args) {
        VectorService vectorService = null;
        try {
            vectorService = new VectorService(
                    Scheme.HTTPS,
                    "api-vikingdb.vikingdb.cn-beijing.volces.com", // 填写向量库数据面v2的域名  https://www.volcengine.com/docs/84313/1792715
                    "cn-beijing",
                    new AuthWithAkSk(System.getenv("AK"), System.getenv("SK")),
                    ClientConfig.builder().build()
            );
        } catch (Exception e) {
            System.err.println("Client initialization failed: " + e.getMessage());
            e.printStackTrace();
            return;
        }

        SearchByKeywordsRequest request = SearchByKeywordsRequest.builder()
                .collectionName("<YOUR_COLLECTION_NAME>") // 替换为您的集合名称
                .indexName("<YOUR_INDEX_NAME>") // 替换为您的索引名称
                .keywords(Arrays.asList("keyword1", "keyword2"))
                .limit(10)
                .build();

        try {
            DataApiResponse<SearchResult> response = vectorService.searchByKeywords(request);
            System.out.println("request success:");
            System.out.println(response);
        } catch (VectorApiException vectorApiException) {
            System.err.println("request vectorApiException:");
            System.out.println("apiName: " + vectorApiException.getApiName());
            System.out.println("httpStatusCode: " + vectorApiException.getHttpStatusCode());
            System.out.println("code: " + vectorApiException.getCode());
            System.out.println("message: " + vectorApiException.getMessage());
            System.out.println("requestId: " + vectorApiException.getRequestId());
            System.out.println("responseContext: " + vectorApiException.getResponseContext().getBody());
        } catch (Exception e) {
            System.err.println("request exception, message : " + e.getMessage());
            e.printStackTrace();
        }
    }


}

返回示例

最近更新时间：2026.09.08 12:02:54

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

请求参数 #

返回示例 #

请求参数

返回示例