Search for documents - DashVector - Alibaba Cloud Documentation Center

This topic describes how to perform similarity searches in a collection by using the SDK for Java.

Prerequisites

A cluster is created. For more information, see Create a cluster.
An API key is obtained. For more information, see Manage API keys.
The SDK of the latest version is installed. For more information, see Install DashVector SDK.

API definition

Java

// The DashVectorCollection class.

// The method working in synchronous mode.
public Response<List<Doc>> query(QueryDocRequest queryDocRequest);

// The method working in asynchronous mode.
public ListenableFuture<Response<List<Doc>>> queryAsync(QueryDocRequest queryDocRequest);

Example

Note

You need to replace YOUR_API_KEY with your API key and YOUR_CLUSTER_ENDPOINT with the endpoint of your cluster in the sample code for the code to run properly.
You need to create a collection named quickstart in advance. For more information, see the "Example" section of the Create a collection topic. You also need to insert some documents in advance. For more information, see Insert documents.

Perform a similarity search by using a vector

Java

import com.aliyun.dashvector.DashVectorClient;
import com.aliyun.dashvector.DashVectorCollection;
import com.aliyun.dashvector.common.DashVectorException;
import com.aliyun.dashvector.models.Doc;
import com.aliyun.dashvector.models.Vector;
import com.aliyun.dashvector.models.requests.QueryDocRequest;
import com.aliyun.dashvector.models.responses.Response;

import java.util.Arrays;
import java.util.List;

public class Main {
    public static void main(String[] args) throws DashVectorException {
        DashVectorClient client = new DashVectorClient("YOUR_API_KEY", "YOUR_CLUSTER_ENDPOINT");
        DashVectorCollection collection = client.get("quickstart");
        
        // Build a vector.
        Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();
      	
      	// Build a QueryDocRequest object. 
      	QueryDocRequest request = QueryDocRequest.builder()
          .vector(vector)
          .topk(100)
          .includeVector(true)
          .build();
        
        // Search for documents.
        Response<List<Doc>> response = collection.query(request);
      
      	// Check whether the operation is successful.
      	assert response.isSuccess() 

        System.out.println(response);
        // Output example:
        // {
        //   "code":0,
        //   "message":"Success",
        //   "requestId":"b26ce0b8-0caf-4836-8136-df889d79ae91",
        //   "output":[
        //     {
        //       "id":"1",
        //       "vector":{
        //         "value":[
        //           0.10000000149011612,
        //           0.20000000298023224,
        //           0.30000001192092896,
        //           0.4000000059604645
        //         ]
        //       },
        //       "fields":{
        //         "name":"zhangsan",
        //         "age":20,
        //         "weight":100.0,
        //         "anykey1":"String",
        //         "anykey2":1,
        //         "anykey3":true,
        //         "anykey4":3.1415926
        //       },
        //       "score":1.1920929E-7
        //     }
        //   ]
        // }
    }
}

Perform a similarity search by using the vector associated with the primary key

Java

// Build a QueryDocRequest object. 
QueryDocRequest request = QueryDocRequest.builder()
  .id("1")
  .topk(100)
  .outputFields(Arrays.asList("name", "age")) // Only the name and age fields need to be returned.
  .includeVector(true)
  .build();

// Perform a similarity search based on the vector associated with the primary key.
Response<List<Doc>> response = collection.query(request);

// Check whether the search is successful.
assert response.isSuccess()

Perform a similarity search by using the vector or primary key and a conditional filter

Java

Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();

// Build a QueryDocRequest object. 
QueryDocRequest request = QueryDocRequest.builder()
  .vector(vector) // Specify a vector for search. Alternatively, you can specify a primary key for search.
  .topk(100)
  .filter("age > 18") // Specify a conditional filter to perform a match query on documents whose value of the age field is greater than 18.
  .outputFields(Arrays.asList("name", "age")) // Only the name and age fields need to be returned.
  .includeVector(true)
  .build();

// Perform a similarity search by using the conditional filter and the specified vector or primary key.
Response<List<Doc>> response = collection.query(request);

// Check whether the search is successful.
assert response.isSuccess()

Perform a similarity search by using both dense and sparse vectors

Note

You can use a sparse vector to represent the keyword weight to implement a keyword-aware semantic vector search.

Java

Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();

// Build a QueryDocRequest object containing a sparse vector.
QueryDocRequest request = QueryDocRequest.builder()
  .vector(vector) // Specify a vector for search.
  .sparseVector(
  	new Map<Integer, Float>() {
      {
        put(1, 0.4f);
        put(10000, 0.6f);
        put(222222, 0.8f);
      }
  	}) // Specify a sparse vector.
  .build();

// Perform a similarity search by using both dense and sparse vectors.
Response<List<Doc>> response = collection.query(request);

// Check whether the search is successful.
assert response.isSuccess()

Perform a match query by using a conditional filter

Java

// Build a QueryDocRequest object that contains a conditional filter but not a primary key or a vector.
QueryDocRequest request = QueryDocRequest.builder()
  .topk(100)
  .filter("age > 18") // Specify a conditional filter to perform a match query on documents whose value of the age field is greater than 18.
  .outputFields(Arrays.asList("name", "age")) // Only the name and age fields need to be returned.
  .includeVector(true)
  .build();

// Perform a search based on the conditional filter only as neither a vector nor a primary key is specified.
Response<List<Doc>> response = collection.query(request);

// Check whether the search is successful.
assert response.isSuccess()

Request parameters

You can use a QueryDocRequestBuilder instance to build a QueryDocRequest object. The following table describes the methods that can be called by the instance.

Note

To perform a similarity search, you need to specify either the vector or id field. If neither is specified, the system performs a match query only by using a conditional filter.

Method	Required	Default value	Description
vector(Vector vector)	No	-	Sets the vector.
sparseVector(Map(Integer, Float))	No	-	Sets the sparse vector.
id(String id)	No	-	Sets the primary key. The similarity search is performed based on the vector associated with the primary key.
topk(int topk)	No	10	Returns top k results by similarity.
filter(String filter)	No	-	Sets the conditional filter, which must comply with the syntax of the SQL WHERE clause. For more information, see Conditional filtering.
includeVector(bool includeVector)	No	false	Specifies whether to return vector data.
partition(String partition)	No	default	Sets the name of the partition.
outputFields(List<String> outputFields)	No	-	Sets a list of document fields to be returned. By default, all fields are returned.
outputField(String field)	No	-
build()	-	-	Builds a `QueryDocRequest` object.

Response parameters

Note

A Response<List<Doc>> object is returned, which contains the operation result, as described in the following table.

Method	Type	Description	Example
getCode()	int	The returned status code. For more information, see Status codes.	0
getMessage()	String	The returned message.	success
getRequestId()	String	The unique ID of the request.	19215409-ea66-4db9-8764-26ce2eb5bb99
getOutput()	List<Doc>	Similarity search result. For more information, see Doc.	`[ { "id":"9", "vector":{"value":[0.9,0.9,0.9,0.9]}, "fields":{"name":"java_9","age":9}, "score":90 } ]`
isSuccess()	Boolean	Specifies whether the operation is successful.	true