Use OpenSearch Vector Search Edition SDKs to query data - OpenSearch

OpenSearch Vector Search Edition SDKs support multiple query strategies. Use the table below to find the right approach for your use case, then jump to the corresponding section for code examples.

Query type	Use when
Vector-based query	Finding records similar to a query vector (nearest neighbor search)
Primary key-based query	Fetching specific records by ID
Prediction-based query	Querying with raw text or images — the SDK vectorizes the input automatically
Batch query	Running multiple independent queries in a single request to reduce network overhead
Multi-query	Querying a single table with multiple sub-queries and merging results
Hybrid query by using a single vector	Combining dense and sparse vector scoring in one request
Hybrid query by using multiple vectors	Combining dense and sparse vector scoring across multiple sub-queries in one request
Hybrid query based on vectors and text	Combining vector similarity with full-text search

All examples use the same four SDK clients: Java, Python, Go, and Java (asynchronous).

Prerequisites

Before you begin, ensure that you have:

An OpenSearch Vector Search Edition instance
The instance endpoint, username, and password (viewable in the API Endpoint section of the Instance Details page)
The instance ID (viewable in the upper-left corner of the Instance Details page)

Dependencies

Add the SDK dependency for your language.

Java

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

Python

# Requires: Python >=3.6
pip install alibabacloud_ha3engine_vector==1.1.17

Go

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

Asynchronous Java

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

Configuration parameters

The following parameters apply to the Java and Python SDKs. Configure them when initializing the client.

Parameter	Description
`endpoint`	The internal or public endpoint of the instance. View it in the Network Information and API Endpoint sections of the Instance Details page. Enable Public Access to get a public endpoint (the endpoint URL contains the word `public`). Use the internal endpoint when accessing the instance from an Elastic Compute Service (ECS) instance on the same vSwitch.
`instance_id`	The instance ID. View it in the upper-left corner of the Instance Details page.
`access_user_name`	The username. View it in the API Endpoint section of the Instance Details page.
`access_pass_word`	The password. Set at purchase; modifiable from the Instance Details page.

For information about configuring an IP address allowlist for public endpoint access, see the Network Information section in "View instance details."

Vector-based query

Vector-based queries find the top K records most similar to a query vector. Pass query parameters in QueryRequest.

Query parameters

Parameter	Required	Description
`table_name`	Yes	The name of the table to query.
`vector`	Yes	The query vector. Its dimension must match the vector index dimension.
`vector_count`	No	The number of vectors in the vector field. Set to `2` if the field contains two vectors.
`top_k`	No	The number of results to return.
`include_vector`	No	Whether to include vector values in the response.
`output_fields`	No	The list of fields to return.
`filter`	No	A filter expression to narrow results. See Filter expression.
`search_params`	No	Additional query parameters. See QcSearcher and HNSW configuration.
`queries`	No	A list of sub-queries to execute in a single request.

Simple query

Java

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;

import com.aliyun.ha3engine.vector.Client;
import com.aliyun.ha3engine.vector.models.Config;
import com.aliyun.ha3engine.vector.models.QueryRequest;
import com.aliyun.ha3engine.vector.models.SearchResponse;
import com.aliyun.tea.TeaException;

import org.junit.Before;
import org.junit.Test;

public class Demo {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        // Instance ID — viewable in the upper-left corner of the Instance Details page.
        config.setInstanceId("ha-cn-i7*****605");
        // Username — viewable in the API Endpoint section of the Instance Details page.
        config.setAccessUserName("username");
        // Password — set at purchase; modifiable from the Instance Details page.
        config.setAccessPassWord("password");
        // API endpoint — viewable in the API Endpoint section of the Instance Details page.
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");

        client = new Client(config);
    }

    @Test
    public void query() throws Exception {
        try {
            QueryRequest request = new QueryRequest();
            request.setTableName("gist");                                  // Required.
            request.setVector(Arrays.asList(0.183762561f, 0.738372617f)); // Required.
            request.setTopK(100);                                          // Optional.
            request.setIncludeVector(true);                               // Optional.

            SearchResponse searchResponse = client.query(request);
            System.out.println("Result:\n" + searchResponse.getBody());
        } 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, QueryRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

request = QueryRequest(
    table_name="gist",
    vector=[0.1, 0.2, 0.3],
    include_vector=True,
    top_k=10)
result = client.query(request)

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }

    query(client)
}

func query(client *ha3engine.Client) {
    request := &ha3engine.QueryRequest{}
    request.SetTableName("test1")

    ids := make([]*float32, 4)
    ids[0] = tea.Float32(0.1)
    ids[1] = tea.Float32(0.2)
    ids[2] = tea.Float32(0.3)
    ids[3] = tea.Float32(0.4)
    request.SetVector(ids)

    response, err := client.Query(request)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.QueryRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
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.Arrays;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class SimpleQuery {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 simpleQuery() {
        try {
            QueryRequest queryRequest = QueryRequest.builder()
                    .tableName("table_name")
                    .indexName("index_name")
                    .vector(Arrays.asList(0.0001575F, 0.00682848F))
                    .topK(10)
                    .includeVector(true)
                    .build();

            CompletableFuture<SearchResponse> future = client.query(queryRequest);
            String responseBody = future.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));
        }
    }
}

Query based on multiple vectors

Specify multiple vectors in a single request. The SDK merges results and returns the top K records across all vectors.

Java

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;

import com.aliyun.ha3engine.vector.Client;
import com.aliyun.ha3engine.vector.models.Config;
import com.aliyun.ha3engine.vector.models.QueryRequest;
import com.aliyun.ha3engine.vector.models.SearchResponse;
import com.aliyun.tea.TeaException;

import org.junit.Before;
import org.junit.Test;

public class Demo {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        config.setInstanceId("ha-cn-i7*****605");
        config.setAccessUserName("username");
        config.setAccessPassWord("password");
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");
        client = new Client(config);
    }

    @Test
    public void query() throws Exception {
        try {
            QueryRequest request = new QueryRequest();
            request.setTableName("gist");
            request.setVector(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f));
            request.setVectorCount(2);   // Two vectors concatenated in the vector field.
            request.setTopK(100);
            request.setIncludeVector(true);
            request.setOutputFields(new ArrayList<String>());
            request.setFilter("a>10");

            SearchResponse searchResponse = client.query(request);
            System.out.println("Result:\n" + searchResponse.getBody());
        } 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, QueryRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

request = QueryRequest(
    table_name="t1",
    vector=[0.1, 0.2, 0.3, 0.4],
    vector_count=2,
    include_vector=True,
    filter="a > 10",
    output_fields=["a", "b"],
    top_k=10)
result = client.query(request)

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }
    multiVectorQuery(client)
}

func multiVectorQuery(client *ha3engine.Client) {
    request := &ha3engine.QueryRequest{}
    request.SetTableName("test1")

    // Eight floats representing two concatenated vectors.
    ids := make([]*float32, 8)
    ids[0] = tea.Float32(0.1)
    ids[1] = tea.Float32(0.2)
    ids[2] = tea.Float32(0.3)
    ids[3] = tea.Float32(0.4)
    ids[4] = tea.Float32(0.1)
    ids[5] = tea.Float32(0.2)
    ids[6] = tea.Float32(0.3)
    ids[7] = tea.Float32(0.4)

    request.SetVector(ids)
    request.SetVectorCount(2)

    response, err := client.Query(request)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.QueryRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
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.Arrays;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class MultiVectorQuery {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 multiVectorQuery() {
        try {
            QueryRequest queryRequest = QueryRequest.builder()
                    .tableName("test1")
                    .indexName("vector")
                    .vector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F,
                                         0.62498F, 0.886408F, 0.586114F, 0.043189F))
                    .vectorCount(2)
                    .topK(10)
                    .includeVector(false)
                    .build();

            CompletableFuture<SearchResponse> future = client.query(queryRequest);
            String responseBody = future.get().getBody();
            System.out.println("query 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));
        }
    }
}

Namespace-based query

Namespaces partition a vector index into isolated subsets. When a namespace is configured on a vector index, every query against that index must include the namespace.

If you configure a namespace for a vector index, you must specify the namespace in all queries against that index.

Java

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;

import com.aliyun.ha3engine.vector.Client;
import com.aliyun.ha3engine.vector.models.Config;
import com.aliyun.ha3engine.vector.models.QueryRequest;
import com.aliyun.ha3engine.vector.models.SearchResponse;
import com.aliyun.tea.TeaException;

import org.junit.Before;
import org.junit.Test;

public class Demo {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        config.setInstanceId("ha-cn-i7*****605");
        config.setAccessUserName("username");
        config.setAccessPassWord("password");
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");
        client = new Client(config);
    }

    @Test
    public void query() throws Exception {
        try {
            QueryRequest request = new QueryRequest();
            request.setTableName("gist");
            request.setVector(Arrays.asList(0.183762561f, 0.738372617f));
            request.setNamespace("namespace");
            request.setTopK(100);
            request.setIncludeVector(true);

            SearchResponse searchResponse = client.query(request);
            System.out.println("Result:\n" + searchResponse.getBody());
        } 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, QueryRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

request = QueryRequest(
    table_name="t1",
    namespace="space_b",
    vector=[0.1, 0.2],
    include_vector=True,
    top_k=10)
result = client.query(request)

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }
    nameSpaceQuery(client)
}

func nameSpaceQuery(client *ha3engine.Client) {
    request := &ha3engine.QueryRequest{}
    request.SetTableName("test1")

    ids := make([]*float32, 4)
    ids[0] = tea.Float32(0.1)
    ids[1] = tea.Float32(0.2)
    ids[2] = tea.Float32(0.3)
    ids[3] = tea.Float32(0.4)
    request.SetVector(ids)
    request.SetNamespace("1")

    response, err := client.Query(request)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.QueryRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
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.Arrays;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class NameSpaceQuery {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 nameSpaceQuery() {
        try {
            QueryRequest queryRequest = QueryRequest.builder()
                    .tableName("test1")
                    .indexName("vector")
                    .namespace("1")
                    .vector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F))
                    .topK(10)
                    .includeVector(false)
                    .build();

            CompletableFuture<SearchResponse> future = client.query(queryRequest);
            String responseBody = future.get().getBody();
            System.out.println("query 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));
        }
    }
}

Query based on multiple namespaces

Send a single request that targets multiple namespaces and receives merged results.

Java

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;

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;

public class Demo {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        config.setInstanceId("ha-cn-i7*****605");
        config.setAccessUserName("username");
        config.setAccessPassWord("password");
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");
        client = new Client(config);
    }

    @Test
    public void multiQuery() throws Exception {
        try {
            MultiQueryRequest request = new MultiQueryRequest();
            request.setTableName("gist");
            request.setTopK(3);
            request.setIncludeVector(true);

            QueryRequest query1 = new QueryRequest();
            query1.setVector(Arrays.asList(0.1f, 0.2f, 0.3f));
            query1.setNamespace("space_a");

            QueryRequest query2 = new QueryRequest();
            query2.setVector(Arrays.asList(0.1f, 0.2f, 0.3f));
            query2.setNamespace("space_b");

            request.setQueries(Arrays.asList(query1, query2));

            SearchResponse searchResponse = client.multiQuery(request);
            System.out.println("Result:\n" + searchResponse.getBody());
        } 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, QueryRequest, MultiQueryRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

q1 = QueryRequest(vector=[0.1, 0.2, 0.3], namespace="space_a")
q2 = QueryRequest(vector=[0.4, 0.5, 0.6], namespace="space_b")
request = MultiQueryRequest(
    table_name="gist",
    queries=[q1, q2],
    top_k=3,
    include_vector=True)
result = client.multi_query(request)

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }
    multiNameSpaceQuery(client)
}

func multiNameSpaceQuery(client *ha3engine.Client) {
    array := make([]*float32, 4)
    value1, value2, value3, value4 := float32(1.23), float32(4.56), float32(7.89), float32(7.89)
    array[0] = &value1
    array[1] = &value2
    array[2] = &value3
    array[3] = &value4

    query1 := &ha3engine.QueryRequest{}
    query1.SetVector(array)
    query1.SetNamespace("space_a")

    query2 := &ha3engine.QueryRequest{}
    query2.SetVector(array)
    query2.SetNamespace("space_b")

    request := &ha3engine.MultiQueryRequest{}
    request.SetTableName("test2")

    queries := make([]*ha3engine.QueryRequest, 2)
    queries[0] = query1
    queries[1] = query2
    request.SetQueries(queries)
    request.SetTopK(10)
    request.SetIncludeVector(false)
    request.SetOrder("DESC")

    response, err := client.MultiQuery(request)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.MultiQueryRequest;
import com.aliyun.ha3engine.async.models.QueryRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
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.Arrays;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class MultiNameSpaceQuery {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 multiNameSpaceQuery() {
        try {
            QueryRequest query1 = QueryRequest.builder()
                    .vector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F))
                    .namespace("space_a")
                    .build();
            QueryRequest query2 = QueryRequest.builder()
                    .vector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F))
                    .namespace("space_b")
                    .build();
            MultiQueryRequest request = MultiQueryRequest.builder()
                    .tableName("test1")
                    .topK(3)
                    .includeVector(false)
                    .queries(Arrays.asList(query1, query2))
                    .build();

            CompletableFuture<SearchResponse> future = client.multiQuery(request);
            String responseBody = future.get().getBody();
            System.out.println("multiQuery 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));
        }
    }
}

Query by using filter conditions

Add a filter expression to any vector query to restrict results to matching records. For the full filter syntax, see Filter expression.

Java

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;

import com.aliyun.ha3engine.vector.Client;
import com.aliyun.ha3engine.vector.models.Config;
import com.aliyun.ha3engine.vector.models.QueryRequest;
import com.aliyun.ha3engine.vector.models.SearchResponse;
import com.aliyun.tea.TeaException;

import org.junit.Before;
import org.junit.Test;

public class Demo {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        config.setInstanceId("ha-cn-i7*****605");
        config.setAccessUserName("username");
        config.setAccessPassWord("password");
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");
        client = new Client(config);
    }

    @Test
    public void query() throws Exception {
        try {
            QueryRequest request = new QueryRequest();
            request.setTableName("gist");
            request.setVector(Arrays.asList(0.183762561f, 0.738372617f));
            request.setTopK(100);
            request.setIncludeVector(true);
            request.setOutputFields(new ArrayList<String>());
            request.setFilter("a>10");

            SearchResponse searchResponse = client.query(request);
            System.out.println("Result:\n" + searchResponse.getBody());
        } 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, QueryRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

request = QueryRequest(
    table_name="t1",
    vector=[0.1, 0.2],
    include_vector=True,
    filter="a > 10",
    output_fields=["a", "b"],
    top_k=10)
result = client.query(request)

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }
    filterQuery(client)
}

func filterQuery(client *ha3engine.Client) {
    request := &ha3engine.QueryRequest{}
    request.SetTableName("test1")

    ids := make([]*float32, 4)
    ids[0] = tea.Float32(0.1)
    ids[1] = tea.Float32(0.2)
    ids[2] = tea.Float32(0.3)
    ids[3] = tea.Float32(0.4)
    request.SetVector(ids)
    request.SetFilter("count>25")

    response, err := client.Query(request)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.QueryRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
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.Arrays;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class FilterQuery {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 filterQuery() {
        try {
            QueryRequest queryRequest = QueryRequest.builder()
                    .tableName("test1")
                    .indexName("vector")
                    .vector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F))
                    .topK(10)
                    .filter("count>25")
                    .includeVector(false)
                    .build();

            CompletableFuture<SearchResponse> future = client.query(queryRequest);
            String responseBody = future.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));
        }
    }
}

Primary key-based query

Fetch specific records by their primary key IDs using FetchRequest. This is a direct point lookup — no vector similarity scoring is involved.

Java

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Map;

import com.aliyun.ha3engine.vector.Client;
import com.aliyun.ha3engine.vector.models.Config;
import com.aliyun.ha3engine.vector.models.FetchRequest;
import com.aliyun.ha3engine.vector.models.SearchResponse;
import com.aliyun.tea.TeaException;

import org.junit.Before;
import org.junit.Test;

public class Demo {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        config.setInstanceId("ha-cn-i7*****605");
        config.setAccessUserName("username");
        config.setAccessPassWord("password");
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");
        client = new Client(config);
    }

    @Test
    public void fetch() throws Exception {
        try {
            FetchRequest request = new FetchRequest();
            request.setTableName("gist");
            request.setIds(Arrays.asList("1", "2"));
            SearchResponse searchResponse = client.fetch(request);
            System.out.println("Result:\n" + searchResponse.getBody());
        } 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, FetchRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

request = FetchRequest(table_name="gist", ids=["1", "2"])
result = client.fetch(request)

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }
    fetch(client)
}

func fetch(client *ha3engine.Client) {
    request := &ha3engine.FetchRequest{}
    request.SetTableName("test1")

    ids := make([]*string, 3)
    ids[0] = tea.String("1")
    ids[1] = tea.String("2")
    ids[2] = tea.String("3")
    request.SetIds(ids)

    response, err := client.Fetch(request)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.FetchRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
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.Arrays;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class PrimaryKeyQuery {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 primaryKeyQuery() {
        try {
            FetchRequest fetchRequest = FetchRequest.builder()
                    .tableName("table_name")
                    .ids(Arrays.asList("1", "2"))
                    .build();
            CompletableFuture<SearchResponse> future = client.fetch(fetchRequest);
            String responseBody = future.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));
        }
    }
}

Prediction-based query

Use prediction-based queries when OpenSearch Vector Search Edition vectorizes the input for you — pass raw text or image data and let the service convert it to a vector before running the search.

Two parameters control the vectorization:

content: The input to vectorize. In text vectorization scenarios, provide text. In image vectorization scenarios, provide text or a Base64-encoded image.
modal: The modality. Set to text to query by text in both text and image vectorization scenarios.

Java

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

import java.util.Map;

public class InferenceQuery {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        config.setInstanceId("ha-cn-i7*****605");
        config.setAccessUserName("username");
        config.setAccessPassWord("password");
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");
        client = new Client(config);
    }

    @Test
    public void inferenceQuery() throws Exception {
        try {
            QueryRequest request = new QueryRequest();
            request.setTableName("test");
            request.setContent("Child");           // The content to vectorize.
            request.setModal("text");              // The modality.
            request.setTopK(100);
            request.setSearchParams("{\\\"qc.searcher.scan_ratio\\\":0.01}");
            SearchResponse searchResponse = client.inferenceQuery(request);
            System.out.println("Result:\n" + searchResponse.getBody());
        } 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, QueryRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

def inference_query():
    request = QueryRequest(
        table_name="test",
        content="Puppy",
        modal="text",
        namespace="123",
        search_params="{\\\"qc.searcher.scan_ratio\\\":0.01}",
        top_k=10)
    result = client.inference_query(request)
    print(result.body)

if __name__ == "__main__":
    inference_query()

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }
    inferenceQuery(client)
}

func inferenceQuery(client *ha3engine.Client) {
    request := &ha3engine.QueryRequest{}
    request.SetTableName("test1")
    request.SetContent("Puppy")
    request.SetNamespace("123")
    request.SetModal("text")

    response, err := client.InferenceQuery(request)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.QueryRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
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.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class InferenceQuery {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 inferenceQuery() {
        try {
            QueryRequest queryRequest = QueryRequest.builder()
                    .tableName("test2")
                    .indexName("source_text_vector")
                    .namespace("1")
                    .modal("text")
                    .content("Test text-to-vector conversion")
                    .topK(10)
                    .includeVector(false)
                    .build();

            CompletableFuture<SearchResponse> future = client.inferenceQuery(queryRequest);
            String responseBody = future.get().getBody();
            System.out.println("queryInference 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));
        }
    }
}

Multi-query

Use MultiQueryRequest to send multiple vector sub-queries against a single table in one request. Results from all sub-queries are merged and returned together.

Java

import java.util.Arrays;
import java.util.Map;

import com.aliyun.ha3engine.vector.Client;
import com.aliyun.ha3engine.vector.models.Config;
import com.aliyun.ha3engine.vector.models.MultiQueryRequest;
import com.aliyun.ha3engine.vector.models.QueryRequest;
import com.aliyun.ha3engine.vector.models.SearchResponse;
import com.aliyun.tea.TeaException;

import org.junit.Before;
import org.junit.Test;

public class Demo {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        config.setInstanceId("ha-cn-i7*****605");
        config.setAccessUserName("username");
        config.setAccessPassWord("password");
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");
        client = new Client(config);
    }

    @Test
    public void query() throws Exception {
        try {
            MultiQueryRequest multiQueryRequest = new MultiQueryRequest();
            multiQueryRequest.setTableName("test1");
            multiQueryRequest.setTopK(50);
            multiQueryRequest.setOutputFields(Arrays.asList("content", "name", "age"));
            multiQueryRequest.setOrder("DESC");

            QueryRequest queryRequest = new QueryRequest();
            queryRequest.setIndexName("vector");
            queryRequest.setNamespace("space_a");
            queryRequest.setVector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F));

            multiQueryRequest.setQueries(Arrays.asList(queryRequest));

            SearchResponse searchResponse = client.multiQuery(multiQueryRequest);
            System.out.println(searchResponse.getBody());
        } 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, MultiQueryRequest, QueryRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

def multi_query():
    query1 = QueryRequest(
        table_name="test",
        vector=[0.1, 0.2, 0.3, 0.4],
        include_vector=True,
        search_params="{\\\"qc.searcher.scan_ratio\\\":0.01}",
        top_k=10)
    request = MultiQueryRequest(
        table_name="test",
        queries=[query1],
        top_k=10)
    result = client.multi_query(request)
    print(result.body)

if __name__ == "__main__":
    multi_query()

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }
    multiQuery(client)
}

func multiQuery(client *ha3engine.Client) {
    query := &ha3engine.QueryRequest{}
    query.SetTableName("test1")

    array := make([]*float32, 4)
    v1, v2, v3, v4 := float32(1.23), float32(4.56), float32(7.89), float32(7.89)
    array[0] = &v1
    array[1] = &v2
    array[2] = &v3
    array[3] = &v4
    query.SetVector(array)

    request := &ha3engine.MultiQueryRequest{}
    request.SetTableName("test1")

    queries := make([]*ha3engine.QueryRequest, 1)
    queries[0] = query
    request.SetQueries(queries)
    request.SetTopK(10)
    request.SetIncludeVector(true)
    request.SetOrder("DESC")

    response, err := client.MultiQuery(request)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.MultiQueryRequest;
import com.aliyun.ha3engine.async.models.QueryRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
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.Arrays;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class SearchDoc {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 searchDoc() {
        try {
            QueryRequest queryRequest = QueryRequest.builder()
                    .indexName("content_vector")
                    .namespace("150086193")
                    .vector(Arrays.asList(0.0001575F, 0.00682848F))
                    .build();
            MultiQueryRequest multiQueryRequest = MultiQueryRequest.builder()
                    .tableName("hybrid")
                    .topK(10)
                    .outputFields(Arrays.asList("content", "source", "instance_id"))
                    .filter("type='TEXT'")
                    .order("DESC")
                    .queries(Arrays.asList(queryRequest))
                    .build();

            CompletableFuture<SearchResponse> future = client.multiQuery(multiQueryRequest);
            String responseBody = future.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));
        }
    }
}

Batch query

Use BatchRequest to send multiple independent queries — each targeting potentially different tables and indexes — in a single HTTP request. This reduces network round trips and lets the query planner optimize queries that share the same filter.

Java

import com.aliyun.ha3engine.vector.Client;
import com.aliyun.ha3engine.vector.models.BatchRequest;
import com.aliyun.ha3engine.vector.models.Config;
import com.aliyun.ha3engine.vector.models.QueryRequest;
import com.aliyun.ha3engine.vector.models.SearchResponse;
import com.aliyun.tea.TeaException;
import org.junit.Before;
import org.junit.Test;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Map;

public class BatchQuery {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        config.setInstanceId("ha-cn-i7*****605");
        config.setAccessUserName("username");
        config.setAccessPassWord("password");
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");
        client = new Client(config);
    }

    @Test
    public void batch() throws Exception {
        try {
            BatchRequest request = new BatchRequest();

            QueryRequest queryRequest1 = new QueryRequest();
            queryRequest1.setTableName("test");
            queryRequest1.setIndexName("vector");
            queryRequest1.setOutputFields(Arrays.asList("id", "name"));
            queryRequest1.setVector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F));

            QueryRequest queryRequest2 = new QueryRequest();
            queryRequest2.setTableName("test1");
            queryRequest2.setIndexName("vector");
            queryRequest2.setOutputFields(Arrays.asList("id", "title"));
            queryRequest2.setVector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F));

            List<QueryRequest> queries = new ArrayList<>();
            queries.add(queryRequest1);
            queries.add(queryRequest2);
            request.setQueries(queries);

            SearchResponse searchResponse = client.batch(request);
            System.out.println("Result:\n" + searchResponse.getBody());
        } 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, QueryRequest, BatchRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

def batch_query():
    query_request1 = QueryRequest(
        table_name="test",
        index_name="vector",
        vector=[0.524355, 0.940892, 0.002874, 0.551031],
        include_vector=True,
        search_params="{\\\"qc.searcher.scan_ratio\\\":0.01}",
        top_k=10)
    query_request2 = QueryRequest(
        table_name="test1",
        index_name="vector",
        vector=[0.524355, 0.940892, 0.002874, 0.551031],
        include_vector=True,
        search_params="{\\\"qc.searcher.scan_ratio\\\":0.01}",
        top_k=10)
    request = BatchRequest(queries=[query_request1, query_request2])
    result = client.batch_query(request)
    print(result.headers)
    print(result.body)

if __name__ == "__main__":
    batch_query()

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }
    batch(client)
}

func batch(client *ha3engine.Client) {
    queryRequest1 := &ha3engine.QueryRequest{}
    queryRequest1.SetTableName("test")
    ids1 := make([]*float32, 4)
    ids1[0] = tea.Float32(0.1)
    ids1[1] = tea.Float32(0.2)
    ids1[2] = tea.Float32(0.3)
    ids1[3] = tea.Float32(0.4)
    queryRequest1.SetVector(ids1)

    queryRequest2 := &ha3engine.QueryRequest{}
    queryRequest2.SetTableName("test1")
    ids2 := make([]*float32, 4)
    ids2[0] = tea.Float32(0.1)
    ids2[1] = tea.Float32(0.2)
    ids2[2] = tea.Float32(0.3)
    ids2[3] = tea.Float32(0.4)
    queryRequest2.SetVector(ids2)

    batchRequest := &ha3engine.BatchRequest{}
    batchRequest.SetQueries([]*ha3engine.QueryRequest{queryRequest1, queryRequest2})

    response, err := client.BatchQuery(batchRequest)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.BatchRequest;
import com.aliyun.ha3engine.async.models.QueryRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
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.Arrays;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class BatchQuery {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 batch() {
        try {
            QueryRequest queryRequest1 = QueryRequest.builder()
                    .tableName("test")
                    .indexName("vector")
                    .vector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F))
                    .outputFields(Arrays.asList("id", "name"))
                    .build();
            QueryRequest queryRequest2 = QueryRequest.builder()
                    .tableName("test1")
                    .indexName("vector")
                    .vector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F))
                    .outputFields(Arrays.asList("id", "title"))
                    .build();
            List<QueryRequest> queries = new ArrayList<>();
            queries.add(queryRequest1);
            queries.add(queryRequest2);
            BatchRequest request = BatchRequest.builder()
                    .queries(queries)
                    .build();

            CompletableFuture<SearchResponse> future = client.batchQuery(request);
            String responseBody = future.get().getBody();
            System.out.println("batch 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));
        }
    }
}

Hybrid query by using a single vector

Combine a dense vector and a sparse vector in a single QueryRequest to leverage both scoring signals simultaneously.

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.Arrays;
import java.util.Map;

public class Demo {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        config.setInstanceId("ha-cn-i7*****605");
        config.setAccessUserName("username");
        config.setAccessPassWord("password");
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");
        client = new Client(config);
    }

    @Test
    public void query() throws Exception {
        try {
            QueryRequest queryRequest = new QueryRequest();
            queryRequest.setIndexName("index");
            queryRequest.setNamespace("cate1");
            queryRequest.setVector(Arrays.asList(0.0001575F, 0.00682848F));

            SparseData sparseData = new SparseData();
            sparseData.setCount(Arrays.asList(2));                              // Number of elements per sparse vector.
            sparseData.setIndices(Arrays.asList(983589459L, 1261855554L));      // Element indexes in ascending order.
            sparseData.setValues(Arrays.asList(0.0001575F, 0.00682848F));       // Element values matching the index order.
            queryRequest.setSparseData(sparseData);

            SearchResponse searchResponse = client.query(queryRequest);
            System.out.println(searchResponse.getBody());
        } 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, SparseData, QueryRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

def mix_query():
    sparse_data = SparseData(indices=[101, 203], values=[0.1, 0.5])
    request = QueryRequest(
        table_name="test",
        index_name="embedding",
        vector=[0.1, 0.2, 0.3, 0.4],
        sparse_data=sparse_data,
        include_vector=True,
        top_k=10)
    result = client.query(request)
    print(result.body)

if __name__ == "__main__":
    mix_query()

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }
    mixQuery(client)
}

func mixQuery(client *ha3engine.Client) {
    request := &ha3engine.QueryRequest{}
    request.SetTableName("test1")

    ids := make([]*float32, 4)
    ids[0] = tea.Float32(0.1)
    ids[1] = tea.Float32(0.2)
    ids[2] = tea.Float32(0.3)
    ids[3] = tea.Float32(0.4)
    request.SetVector(ids)

    count := make([]*int, 1)
    count[0] = tea.Int(2)
    indices := make([]*int64, 2)
    indices[0] = tea.Int64(1)
    indices[1] = tea.Int64(2)
    values := make([]*float32, 2)
    values[0] = tea.Float32(0.1)
    values[1] = tea.Float32(0.2)

    request.SetSparseData(&ha3engine.SparseData{
        Count:   count,
        Indices: indices,
        Values:  values,
    })

    response, err := client.Query(request)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.QueryRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
import com.aliyun.ha3engine.async.models.SparseData;
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.Arrays;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class MixQuery {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 mixQuery() {
        try {
            QueryRequest queryRequest = QueryRequest.builder()
                    .tableName("test1")
                    .indexName("vector")
                    .vector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F))
                    .sparseData(SparseData.builder()
                            .count(Arrays.asList(2))
                            .indices(Arrays.asList(1L, 2L))
                            .values(Arrays.asList(0.1F, 0.2F))
                            .build())
                    .topK(10)
                    .includeVector(false)
                    .build();

            CompletableFuture<SearchResponse> future = client.query(queryRequest);
            String responseBody = future.get().getBody();
            System.out.println("query 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));
        }
    }
}

Hybrid query by using multiple vectors

Use MultiQueryRequest to combine dense and sparse vectors across multiple sub-queries in a single request. Each sub-query can carry its own sparse data, enabling simultaneous multi-vector hybrid scoring.

Important

When performing hybrid queries based on multiple vectors, all vectors in a single query must be of the same type — for example, multiple dense vectors or dense-sparse vector pairs.

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.Arrays;
import java.util.Map;

public class Demo {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        config.setInstanceId("ha-cn-i7*****605");
        config.setAccessUserName("username");
        config.setAccessPassWord("password");
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");
        client = new Client(config);
    }

    @Test
    public void query() throws Exception {
        try {
            MultiQueryRequest multiQueryRequest = new MultiQueryRequest();
            multiQueryRequest.setTableName("main");
            multiQueryRequest.setTopK(50);
            multiQueryRequest.setOutputFields(Arrays.asList("content", "source", "instance_id"));
            multiQueryRequest.setFilter("type='TEXT'");
            multiQueryRequest.setOrder("DESC");

            QueryRequest queryRequest = new QueryRequest();
            queryRequest.setIndexName("index");
            queryRequest.setNamespace("cate1");
            queryRequest.setVector(Arrays.asList(0.0001575F, 0.00682848F));

            SparseData sparseData = new SparseData();
            sparseData.setCount(Arrays.asList(2));
            sparseData.setIndices(Arrays.asList(983589459L, 1261855554L));
            sparseData.setValues(Arrays.asList(0.0001575F, 0.00682848F));
            queryRequest.setSparseData(sparseData);

            multiQueryRequest.setQueries(Arrays.asList(queryRequest));

            SearchResponse searchResponse = client.multiQuery(multiQueryRequest);
            System.out.println(searchResponse.getBody());
        } 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, SparseData, MultiQueryRequest
from alibabacloud_ha3engine_vector.models import QueryRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

def mix_multi_query():
    sd1 = SparseData(indices=[101, 203], values=[0.1, 0.5])
    sd2 = SparseData(indices=[200, 405, 502], values=[0.9, 0.5, 0.75])
    q1 = QueryRequest(vector=[0.1, 0.2, 0.3, 0.4], sparse_data=sd1)
    q2 = QueryRequest(vector=[0.4, 0.5, 0.6, 0.7], sparse_data=sd2)
    request = MultiQueryRequest(
        table_name="test",
        queries=[q1, q2],
        top_k=3,
        include_vector=True)
    result = client.multi_query(request)
    print(result.body)

if __name__ == "__main__":
    mix_multi_query()

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }
    mixMultiVectorQuery(client)
}

func mixMultiVectorQuery(client *ha3engine.Client) {
    array := make([]*float32, 4)
    value1 := float32(1.23)
    value2 := float32(4.56)
    value3 := float32(7.89)
    value4 := float32(7.89)
    array[0] = &value1
    array[1] = &value2
    array[2] = &value3
    array[3] = &value4

    count := make([]*int, 1)
    count[0] = tea.Int(2)
    indices := make([]*int64, 2)
    indices[0] = tea.Int64(1)
    indices[1] = tea.Int64(2)
    values := make([]*float32, 2)
    values[0] = tea.Float32(0.1)
    values[1] = tea.Float32(0.2)
    sparseData := &ha3engine.SparseData{
        Count:   count,
        Indices: indices,
        Values:  values,
    }

    query1 := &ha3engine.QueryRequest{}
    query1.SetSparseData(sparseData)
    query1.SetVector(array)

    query2 := &ha3engine.QueryRequest{}
    query2.SetVector(array)

    request := &ha3engine.MultiQueryRequest{}
    request.SetTableName("test1")

    querys := make([]*ha3engine.QueryRequest, 2)
    querys[0] = query1
    querys[1] = query2
    request.SetQueries(querys)
    request.SetTopK(10)
    request.SetIncludeVector(false)
    request.SetOrder("DESC")

    response, err := client.MultiQuery(request)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.MultiQueryRequest;
import com.aliyun.ha3engine.async.models.QueryRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
import com.aliyun.ha3engine.async.models.SparseData;
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.Arrays;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class MixMultiVectorQuery {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 mixMultiVectorQuery() {
        try {
            QueryRequest query1 = QueryRequest.builder()
                    .vector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F))
                    .sparseData(SparseData.builder()
                            .count(Arrays.asList(2))
                            .indices(Arrays.asList(1L, 2L))
                            .values(Arrays.asList(0.1F, 0.2F))
                            .build())
                    .namespace("space_a")
                    .build();
            QueryRequest query2 = QueryRequest.builder()
                    .vector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F))
                    .sparseData(SparseData.builder()
                            .count(Arrays.asList(2))
                            .indices(Arrays.asList(1L, 2L))
                            .values(Arrays.asList(0.1F, 0.2F))
                            .build())
                    .namespace("space_b")
                    .build();
            MultiQueryRequest request = MultiQueryRequest.builder()
                    .tableName("test2")
                    .topK(3)
                    .includeVector(false)
                    .queries(Arrays.asList(query1, query2))
                    .build();

            CompletableFuture<SearchResponse> future = client.multiQuery(request);
            String responseBody = future.get().getBody();
            System.out.println("query 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));
        }
    }
}

Hybrid query based on vectors and text

Combine k-nearest neighbor (k-NN) vector search with full-text search in a single SearchRequest. The knn field takes a QueryRequest with vector parameters; the text field takes a TextQuery with a query string.

Java

import java.util.Arrays;
import java.util.Map;

import com.alibaba.fastjson.JSONObject;
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;

public class VectorSearchService {

    private Client client;

    @Before
    public void clientInit() throws Exception {
        Config config = new Config();
        config.setInstanceId("ha-cn-i7*****605");
        config.setAccessUserName("username");
        config.setAccessPassWord("password");
        config.setEndpoint("ha-cn-i7*****605.public.ha.aliyuncs.com");
        client = new Client(config);
    }

    @Test
    public void search() throws Exception {
        try {
            // Vector (k-NN) parameters.
            QueryRequest queryRequest = new QueryRequest();
            queryRequest.setIndexName("vector");
            queryRequest.setTopK(10);
            queryRequest.setVector(Arrays.asList(0.62498F, 0.886408F, 0.586114F, 0.043189F));
            SparseData sparseData = new SparseData();
            sparseData.setIndices(Arrays.asList(1L, 2L, 3L, 4L));
            sparseData.setValues(Arrays.asList(0.0001575F, 0.00682848F, 0.008745F, 0.4583474F));
            queryRequest.setSparseData(sparseData);

            // Text query parameters.
            TextQuery textQuery = new TextQuery();
            textQuery.setQueryString("content:'Publish'");

            SearchRequest request = new SearchRequest();
            request.setTableName("test1");
            request.setKnn(queryRequest);
            request.setText(textQuery);
            request.setSize(10);
            request.setOutputFields(Arrays.asList("id", "content", "name"));

            SearchResponse searchResponse = client.search(request);
            System.out.println("Result:\n" + searchResponse.getBody());
        } 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, SearchRequest, TextQuery, QueryRequest

config = Config(
    endpoint="http://ha-cn-i7*****605.public.ha.aliyuncs.com",
    access_user_name="username",
    access_pass_word="password")
client = Client(config)

def search():
    knn = QueryRequest(
        index_name="vector",
        vector=[0.62498, 0.886408, 0.586114, 0.043189],
        include_vector=True,
        top_k=10)
    text = TextQuery(query_string="content:'Publish'")
    request = SearchRequest(
        table_name="test1",
        size=10,
        output_fields=["id", "content", "name"],
        knn=knn,
        text=text)
    result = client.search(request)
    print(result.body)

if __name__ == "__main__":
    search()

Go

package main

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

func main() {
    config := &ha3engine.Config{
        Endpoint:       tea.String("ha-cn-i7*****605.public.ha.aliyuncs.com"),
        AccessUserName: tea.String("username"),
        AccessPassWord: tea.String("password"),
        RuntimeOptions: &service.RuntimeOptions{
            KeepAlive:    tea.Bool(true),
            MaxIdleConns: tea.Int(1000),
            ReadTimeout:  tea.Int(1000),
        },
    }

    client, err := ha3engine.NewClient(config)
    if err != nil {
        fmt.Println(err)
        return
    }
    search(client)
}

func search(client *ha3engine.Client) {
    searchRequest := &ha3engine.SearchRequest{}
    searchRequest.SetTableName("test1")

    knn := &ha3engine.QueryRequest{}
    ids := make([]*float32, 4)
    ids[0] = tea.Float32(0.1)
    ids[1] = tea.Float32(0.2)
    ids[2] = tea.Float32(0.3)
    ids[3] = tea.Float32(0.4)
    knn.SetVector(ids)

    text := &ha3engine.TextQuery{}
    text.SetQueryString("content:'Publish'")

    searchRequest.SetText(text)
    searchRequest.SetKnn(knn)

    response, err := client.Search(searchRequest)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(response)
}

Java (asynchronous)

import com.aliyun.ha3engine.async.AsyncClient;
import com.aliyun.ha3engine.async.models.QueryRequest;
import com.aliyun.ha3engine.async.models.SearchRequest;
import com.aliyun.ha3engine.async.models.SearchResponse;
import com.aliyun.ha3engine.async.models.TextQuery;
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.Arrays;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class VectorTextMixSearch {

    private AsyncClient client;

    @Before
    public void clientInit() {
        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 search() {
        try {
            SearchRequest request = SearchRequest.builder()
                    .tableName("test1")
                    .size(10)
                    .knn(QueryRequest.builder()
                            .vector(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f))
                            .namespace("space_a")
                            .build())
                    .text(TextQuery.builder()
                            .queryString("content:'Content'")
                            .build())
                    .outputFields(Arrays.asList("name", "age", "content"))
                    .build();

            CompletableFuture<SearchResponse> future = client.search(request);
            String responseBody = future.get().getBody();
            System.out.println("search 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));
        }
    }
}

Usage notes

When performing hybrid queries based on multiple vectors, all vectors in a single query must be of the same type (for example, multiple dense vectors, or dense-sparse vector pairs).
For Go dependencies, always specify the edition-specific tag (@v1.1.17-vector) when running go get. Do not use the untagged command go get github.com/aliyun/alibabacloud-ha3-go-sdk, as it may resolve to a different edition's SDK.
For response parameter details, see Response parameters.

What's next

Filter expression — full filter syntax reference
QcSearcher configuration — tune quantitative clustering search parameters
HNSW configuration — tune Hierarchical Navigable Small World index parameters