更新数据

本文档介绍如何使用Java、Python语言进行更新表数据,支持的更新操作有add、delete。

相关依赖

Java

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-sdk-ha3engine-vector</artifactId>
    <version>1.1.11</version>
</dependency>

python

# Requires: Python >=3.6
pip install alibabacloud_ha3engine_vector

Go

go get github.com/aliyun/alibabacloud-ha3-go-sdk@v1.1.12-vector

Java异步

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>aliyun-sdk-ha3engine-async</artifactId>
  <version>1.1.4</version>
</dependency>

参数说明

Java、Python SDK中都需要配置如下5个必要参数(endpointinstance_id、access_user_name、access_pass_word、data_source_name):

  • endpoint:私网/公网域名

可在实例详情页中网络信息和API入口查看:

image.png

重要

开启公网访问后可以在本地通过公网域名(包含public的域名)调用实例,需要参考添加白名单配置访问的白名单IP,否则会报禁止访问的错误,建议您使用前先ping下,确定可访问。

若有ECS机器,可通过配置相同的交换机通过API域名调用实例。

  • instance_id:实例ID

image.png

  • access_user_name:用户名

  • access_pass_word:密码

用户名和密码可以在实例详情页中API入口处进行查看:(密码是购买实例时设置的,可以修改)

image.png

  • data_source_name:API推送数据的数据源名称,默认为实例id_表名:

image.png

如上图所示,data_source_name=ha-cn-zpr3dgzxg04_test_image_vector

数据更新demo

add 操作示例

Java

import com.aliyun.ha3engine.vector.Client;
import com.aliyun.ha3engine.vector.models.Config;
import com.aliyun.ha3engine.vector.models.PushDocumentsRequest;
import com.aliyun.ha3engine.vector.models.PushDocumentsResponse;
import com.aliyun.tea.TeaException;
import org.junit.Before;
import org.junit.Test;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;

/**
 * @author alibaba
 */
public class PushDoc {

    /**
     * 问天引擎client
     */
    private Client client;

    @Before
    public void clientInit() throws Exception {
        /*
          初始化问天引擎client
         */
        Config config = new Config();

        // 实例名称,可在实例详情页左上角查看,例:ha-cn-i7*****605
        config.setInstanceId("ha-cn-i7*****605");
        // 用户名,可在实例详情页>API入口 查看
        config.setAccessUserName("username");
        // 密码,可在实例详情页>API入口 修改
        config.setAccessPassWord("password");
        // API域名,可在实例详情页>API入口 查看
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");

        client = new Client(config);
    }

    @Test
    public void add() throws Exception {
        // 文档推送的表名称,是实例id与表名的拼接,中间用下划线连接
        String tableName = "<instance_id>_<table_name>";

        // 文档推送的文档主键字段.
        String pkField = "<field_pk>";

        try {
            // 文档推送外层结构, 可添加对文档操作的结构体. 结构内支持一个或多个文档操作内容.
            ArrayList<Map<String, ?>> documents = new ArrayList<>();

            // 添加文档
            Map<String, Object> add2Document = new HashMap<>();
            Map<String, Object> add2DocumentFields = new HashMap<>();

            // 插入文档内容信息, keyValue 成对匹配.
            // field_pk 字段需与 pkField 字段配置一致.
            add2DocumentFields.put("<field_pk>", "<field_pk_value>");
            add2DocumentFields.put("<field_map_key_1>", "<field_map_value_1>");
            add2DocumentFields.put("<field_map_key_2>", "<field_map_value_2>");

            // 问天引擎支持的多值属性类型,索引内配置为"multi_value": true
            ArrayList<Object> addDocumentMultiFields = new ArrayList<>();
            addDocumentMultiFields.add("multi_value_1");
            addDocumentMultiFields.add("multi_value_2");
            add2DocumentFields.put("<multi_value_key>", addDocumentMultiFields);

            // 将文档内容添如 add2Document 结构.
            add2Document.put("fields", add2DocumentFields);
            // 新增对应的文档命令: add
            add2Document.put("cmd", "add");
            documents.add(add2Document);

            // 推送数据
            PushDocumentsRequest request = new PushDocumentsRequest();
            request.setBody(documents);
            PushDocumentsResponse response = client.pushDocuments(tableName, pkField, request);
            String responseBody = response.getBody();

            System.out.println("result:" + responseBody);

        } catch (TeaException e) {
            System.out.println(e.getCode());
            System.out.println(e.getMessage());
            Map<String, Object> exceptionData = e.getData();
            System.out.println(com.aliyun.teautil.Common.toJSONString(exceptionData));
        }
    }
}

Python

from alibabacloud_ha3engine_vector.client import Client
from alibabacloud_ha3engine_vector.models import Config
from alibabacloud_ha3engine_vector import models
from Tea.exceptions import TeaException, RetryError

config = Config(
    # API域名,可在实例详情页>API入口 查看
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    # 用户名,可在实例详情页>API入口 查看
    access_user_name="username",
    # 密码,可在实例详情页>API入口 修改
    access_pass_word="password")

# 初始化 引擎客户端
client = Client(config)

def push():
    # 文档推送的表名称,是实例id与表名的拼接,中间用下划线连接
    tableName = "<instance_id>_<table_name>";

    try:
        # 添加文档
        # 添加一篇文档,如果文档已经存在会先删除然后再添加。
        # =====================================================
        # 更新文档内容信息
        add2DocumentFields = {
            "id": 1,                          # 主键id,INT单值类型
            "name": "搜索",                    # STRING单值类型
            "str_arr": "a\x1Db\x1Dc\x1Dd"     # STRING多值类型
        }

        # 将文档内容添入 add2Document结构
        add2Document = {
            "fields": add2DocumentFields,
            "cmd": "add"                      # 新增对应的文档命令: add
        }

        optionsHeaders = {}
        # 文档推送外层结构, 可添加对文档操作的结构体.结构内支持 一个或多个文档操作内容.
        documentArrayList = []
        documentArrayList.append(add2Document)
        pushDocumentsRequest = models.PushDocumentsRequest(optionsHeaders, documentArrayList)

        # 文档推送的文档主键字段.
        pkField = "id"
        # 使用默认 运行时参数进行请求
        response = client.push_documents(tableName, pkField, pushDocumentsRequest)
        print(response.body)

    except TeaException as e:
        print(f"send request with TeaException : {e}")
    except RetryError as e:
        print(f"send request with Connection Exception  : {e}")

if __name__ == "__main__":
    push()

Go

主要是在程序中动态将对应的文档数据封装到Map对象中,然后通过add方法将这些Map对象添加到缓存中,最后调用pushDocuments方法,批量提交这些Map对象的文档数据。

package main

import (
	"fmt"
	"github.com/alibabacloud-go/tea/tea"
	ha3engine "github.com/aliyun/alibabacloud-ha3-go-sdk/client"
)

func main() {
	// 创建请求客户端实例
	config := &ha3engine.Config{
		// API域名,可在实例详情页>API入口 查看
		Endpoint: tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
		// 用户名,可在实例详情页>API入口 查看
		AccessUserName: tea.String("username"),
		// 密码,可在实例详情页>API入口 修改
		AccessPassWord: tea.String("password"),
	}

	// 初始化一个client, 用以发送请求.
	client, _clientErr := ha3engine.NewClient(config)

	// 如果 NewClient 过程中出现异常. 则 返回 _clientErr 且输出 错误信息.
	if _clientErr != nil {
		fmt.Println(_clientErr)
		return
	}
	docPush(client)
}

func docPush(client *ha3engine.Client) {
	pushDocumentsRequestModel := &ha3engine.PushDocumentsRequest{}
  // 文档推送的表名称,是实例id与表名的拼接,中间用下划线连接
  tableName := "<instance_id>_<table_name>"
  // 文档推送的文档主键字段
  keyField := "<field_pk>"

	a := [20]int{}
	array := []map[string]interface{}{}
	for x := range a {
		filed := map[string]interface{}{
			"fields": map[string]interface{}{
				"id":          tea.ToString(x),
				"fb_boolean":  tea.BoolValue(nil),
				"fb_datetime": "2167747200000",
				"fb_string":   "409a6b18-a10b-409e-af91-07121c45d899",
			},
			"cmd": tea.String("add"),
		}
		array = append(array, filed)

		pushDocumentsRequestModel.SetBody(array)

		// 发送请求的方法调用.
		response, _requestErr := client.PushDocuments(tea.String(dataSourceName), tea.String(keyField), pushDocumentsRequestModel)

		// 如果 发送请求 过程中出现异常. 则 返回 _requestErr 且输出 错误信息.
		if _requestErr != nil {
			fmt.Println(_requestErr)
			return
		}

		// 输出正常返回的 response 内容.
		fmt.Println(response)
	}
}

Java异步

主要是在程序中动态将对应的文档数据封装到Map对象中,再将这些Map对象通过add方法添加到缓存中,最后调用pushDocuments方法,批量提交这些Map对象文档数据。

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.PushDocumentsRequest;
import com.aliyun.ha3engine.async.models.PushDocumentsResponse;
import com.aliyun.sdk.ha3engine.async.core.AsyncConfigInfoProvider;
import com.aliyun.tea.TeaException;
import darabonba.core.client.ClientOverrideConfiguration;
import org.junit.Before;
import org.junit.Test;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;


/**
 * @author alibaba
 */
public class AddDoc {

    /**
     * 问天引擎client
     */
    private AsyncClient client;

    @Before
    public void clientInit() {
        // 配置实例的用户名密码, 可在实例详情页>API入口 查看
        AsyncConfigInfoProvider provider = AsyncConfigInfoProvider.create("username", "password");
        // 初始化异步客户端
        client = AsyncClient.builder()
                .credentialsProvider(provider)
                .overrideConfiguration(
                        ClientOverrideConfiguration.create()
                                .setEndpointOverride("ha-cn-i7*****605.public.ha.aliyuncs.com")
                                .setProtocol("http")
                ).build();
    }

    @Test
    public void add() {
        try {
            // 文档推送的表名称,是实例id与表名的拼接,中间用下划线连接
            String tableName = "<instance_id>_<table_name>";

            // 文档推送的文档主键字段
            String pkField = "<field_pk>";

            // 文档推送外层结构, 可添加对文档操作的结构体. 结构内支持一个或多个文档操作内容.
            ArrayList<Map<String, ?>> documents = new ArrayList<>();

            // 添加文档
            Map<String, Object> add2Document = new HashMap<>();
            Map<String, Object> add2DocumentFields = new HashMap<>();

            // 更新文档内容信息, keyValue 成对匹配.
            // field_pk 字段需与 pkField 字段配置一致.
            add2DocumentFields.put("<field_pk>", "<field_pk_value>");
            add2DocumentFields.put("<field_map_key_1>", "<field_map_value_1>");
            add2DocumentFields.put("<field_map_key_2>", "<field_map_value_2>");

            // 问天引擎支持的多值属性类型,索引内配置为"multi_value": true
            ArrayList<Object> addDocumentMultiFields = new ArrayList<>();
            addDocumentMultiFields.add("multi_value_1");
            addDocumentMultiFields.add("multi_value_2");
            add2DocumentFields.put("<multi_value_key>", addDocumentMultiFields);

            // 将文档内容添如 add2Document 结构.
            add2Document.put("fields", add2DocumentFields);
            // 新增对应的文档命令: add
            add2Document.put("cmd", "add");
            documents.add(add2Document);

            // 推送数据
            PushDocumentsRequest request = PushDocumentsRequest.builder().body(documents).build();
            CompletableFuture<PushDocumentsResponse> responseCompletableFuture = client.pushDocuments(tableName, pkField, request);
            String responseBody = responseCompletableFuture.get().getBody();

            System.out.println("result:" + responseBody);
        } catch (ExecutionException | InterruptedException e) {
            System.out.println(e.getMessage());
        } catch (TeaException e) {
            System.out.println(e.getCode());
            System.out.println(e.getMessage());
            Map<String, Object> abc = e.getData();
            System.out.println(com.aliyun.teautil.Common.toJSONString(abc));
        }
        
    }
}
说明

通过add推送数据时,主键相同新数据会覆盖旧数据

delete 操作示例

Java

import com.aliyun.ha3engine.vector.Client;
import com.aliyun.ha3engine.vector.models.*;
import com.aliyun.tea.TeaException;
import org.junit.Before;
import org.junit.Test;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;

/**
 * @author alibaba
 */
public class PushDoc {

    /**
     * 问天引擎client
     */
    private Client client;

    @Before
    public void clientInit() throws Exception {
        /*
          初始化问天引擎client
         */
        Config config = new Config();

        // 实例名称,可在实例详情页左上角查看,例:ha-cn-i7*****605
        config.setInstanceId("ha-cn-i7*****605");
        // 用户名,可在实例详情页>网络信息 查看
        config.setAccessUserName("username");
        // 密码,可在实例详情页>网络信息 修改
        config.setAccessPassWord("password");
        // API域名,可在实例详情页>API入口 查看
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");

        client = new Client(config);
    }


    @Test
    public void delete() throws Exception {
        // 文档推送的表名称,是实例id与表名的拼接,中间用下划线连接
        String tableName = "<instance_id>_<table_name>";

        // 文档推送的文档主键字段.
        String pkField = "<field_pk>";

        try {
            // 文档推送外层结构, 可添加对文档操作的结构体. 结构内支持一个或多个文档操作内容.
            ArrayList<Map<String, ?>> documents = new ArrayList<>();

            // 删除文档
            Map<String, Object> delete2Document = new HashMap<>();
            Map<String, Object> delete2DocumentFields = new HashMap<>();

            // 插入文档内容信息, keyValue 成对匹配.
            // field_pk 字段需与 pkField 字段配置一致.
            delete2DocumentFields.put("<field_pk>", "<field_pk_value>");

            // 将文档内容添如 delete2Document 结构.
            delete2Document.put("fields", delete2DocumentFields);
            // 删除对应的文档命令: delete
            delete2Document.put("cmd", "delete");
            documents.add(delete2Document);

            // 推送数据
            PushDocumentsRequest request = new PushDocumentsRequest();
            request.setBody(documents);
            PushDocumentsResponse response = client.pushDocuments(tableName, pkField, request);
            String responseBody = response.getBody();

            System.out.println("result:" + responseBody);

        } catch (TeaException e) {
            System.out.println(e.getCode());
            System.out.println(e.getMessage());
            Map<String, Object> exceptionData = e.getData();
            System.out.println(com.aliyun.teautil.Common.toJSONString(exceptionData));
        }
    }
}

Python

from alibabacloud_ha3engine_vector.client import Client
from alibabacloud_ha3engine_vector.models import Config
from alibabacloud_ha3engine_vector import models
from Tea.exceptions import TeaException, RetryError

config = Config(
    # API域名,可在实例详情页>API入口 查看
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    # 用户名,可在实例详情页>API入口 查看
    access_user_name="username",
    # 密码,可在实例详情页>API入口 修改
    access_pass_word="password")

# 初始化 引擎客户端
ha3EngineClient = Client(Config)


def pushDoc():
    # 文档推送的表名称,是实例id与表名的拼接,中间用下划线连接
    tableName = "<instance_id>_<table_name>";

    try:
        # 文档推送外层结构, 可添加对文档操作的结构体.结构内支持 一个或多个文档操作内容.
        documentArrayList = []

        # 删除文档
        # 删除一篇文档,删除文档时需要指定文档主键
        # 如果索引构建时采用多级hash方式,需要指定每级hash的主键。
        delete2DocumentFields = {
            "id": 1  # 主键id,INT单值类型
        }
        delete2Document = {
            "fields": delete2DocumentFields,  # 将文档内容添如 delete2Document 结构.
            "cmd": "delete"  # 删除对应的文档命令: delete
        }

        optionsHeaders = {}
        documentArrayList.append(delete2Document)
        pushDocumentsRequest = models.PushDocumentsRequest(
            optionsHeaders, documentArrayList
        )

        # 文档推送的文档主键字段.
        pkField = "id"
        # 使用默认 运行时参数进行请求
        response = ha3EngineClient.push_documents(
            tableName, pkField, pushDocumentsRequest
        )
        print(response)

    except TeaException as e:
        print(f"send request with TeaException : {e}")
    except RetryError as e:
        print(f"send request with Connection Exception  : {e}")


if __name__ == "__main__":
    pushDoc()

Go

package main

import (
    "fmt"
    "github.com/alibabacloud-go/tea/tea"
    ha3engine "github.com/aliyun/alibabacloud-ha3-go-sdk/client"
)

func main() {
    // 创建请求客户端实例
    config := &ha3engine.Config{
        // API域名,可在实例详情页>API入口 查看
        Endpoint: tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        // 用户名,可在实例详情页>API入口 查看
        AccessUserName: tea.String("username"),
        // 密码,可在实例详情页>API入口 修改
        AccessPassWord: tea.String("password"),
    }

    // 初始化一个client, 用以发送请求.
    client, _clientErr := ha3engine.NewClient(config)

    // 如果 NewClient 过程中出现异常. 则 返回 _clientErr 且输出 错误信息.
    if _clientErr != nil {
        fmt.Println(_clientErr)
        return
    }
    deleteDoc(client)
}

func deleteDoc(client *ha3engine.Client) {
    pushDocumentsRequestModel := &ha3engine.PushDocumentsRequest{}
    // 文档推送的表名称,是实例id与表名的拼接,中间用下划线连接
    tableName := "<instance_id>_<table_name>"
    // 文档推送的文档主键字段
    keyField := "<field_pk>"

    var array []map[string]interface{}
    filed := map[string]interface{}{
        "fields": map[string]interface{}{
            "id": 2,
        },
        "cmd": tea.String("delete"),
    }
    array = append(array, filed)

    pushDocumentsRequestModel.SetBody(array)

    // 发送请求的方法调用.
    response, _requestErr := client.PushDocuments(tea.String(tableName), tea.String(keyField), pushDocumentsRequestModel)

    // 如果 发送请求 过程中出现异常. 则 返回 _requestErr 且输出 错误信息.
    if _requestErr != nil {
        fmt.Println(_requestErr)
        return
    }

    // 输出正常返回的 response 内容.
    fmt.Println(response)
}

Java异步

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.PushDocumentsRequest;
import com.aliyun.ha3engine.async.models.PushDocumentsResponse;
import com.aliyun.sdk.ha3engine.async.core.AsyncConfigInfoProvider;
import com.aliyun.tea.TeaException;
import darabonba.core.client.ClientOverrideConfiguration;
import org.junit.Before;
import org.junit.Test;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;


/**
 * @author alibaba
 */
public class DeleteDoc {

    /**
     * 问天引擎client
     */
    private AsyncClient client;

    @Before
    public void clientInit() {
        // 配置实例的用户名密码, 可在实例详情页>API入口 查看
        AsyncConfigInfoProvider provider = AsyncConfigInfoProvider.create("username", "password");
        // 初始化异步客户端
        client = AsyncClient.builder()
                .credentialsProvider(provider)
                .overrideConfiguration(
                        ClientOverrideConfiguration.create()
                                .setEndpointOverride("ha-cn-i7*****605.public.ha.aliyuncs.com")
                                .setProtocol("http")
                ).build();
    }

    @Test
    public void delete() throws Exception {
        try {
            // 文档推送的表名称,是实例id与表名的拼接,中间用下划线连接
            String tableName = "<instance_id>_<table_name>";

            // 文档推送的文档主键字段
            String pkField = "<field_pk>";

            // 文档推送外层结构, 可添加对文档操作的结构体. 结构内支持一个或多个文档操作内容.
            ArrayList<Map<String, ?>> documents = new ArrayList<>();

            // 删除文档
            Map<String, Object> deleteDocument = new HashMap<>();
            Map<String, Object> deleteDocumentFields = new HashMap<>();

            // 更新文档内容信息, keyValue 成对匹配.
            // field_pk 字段需与 pkField 字段配置一致.
            deleteDocumentFields.put("<field_pk>", "<field_pk_value>");

            // 将文档内容添如 deleteDocument 结构.
            deleteDocument.put("fields", deleteDocumentFields);
            // 删除对应的文档命令: delete
            deleteDocument.put("cmd", "delete");
            documents.add(deleteDocument);

            // 推送数据
            PushDocumentsRequest request = PushDocumentsRequest.builder().body(documents).build();
            CompletableFuture<PushDocumentsResponse> responseCompletableFuture = client.pushDocuments(tableName, pkField, request);
            String responseBody = responseCompletableFuture.get().getBody();

            System.out.println("result:" + responseBody);
        } catch (ExecutionException | InterruptedException e) {
            System.out.println(e.getMessage());
        } catch (TeaException e) {
            System.out.println(e.getCode());
            System.out.println(e.getMessage());
            Map<String, Object> exceptionData = e.getData();
            System.out.println(com.aliyun.teautil.Common.toJSONString(exceptionData));
        }
    }
}

说明

  • 请求的相应结果可参考流量API说明>更新数据中的相应结果

  • 不要使用go get github.com/aliyun/alibabacloud-ha3-go-sdk命令拉取git依赖,必须后面指定版本,因为向量检索版和召回引擎版的tag都在同一个github下,拉取依赖的时候需根据实例的版本拉取对应依赖