Perform similarity search in DashVector using the SDK for Java - DashVector

Search a DashVector collection for documents that match a given vector, a primary key, or a metadata filter. The examples on this page use the Java SDK.

Search modes

The query method supports the following search modes depending on which parameters you provide:

Mode	Parameters	Use case
Vector search	`vector`	Find documents closest to a dense vector
Primary key search	`id`	Find documents similar to a stored vector without re-supplying the vector values
Filtered search	`vector` or `id` + `filter`	Narrow similarity results by metadata conditions
Hybrid dense + sparse search	`vector` + `sparseVector`	Combine semantic similarity with keyword relevance
Filter-only query	`filter` only (no `vector` or `id`)	Retrieve documents that match metadata conditions without ranking by similarity

Prerequisites

Before you begin, make sure you have:

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

API signatures

DashVectorCollection provides two query methods -- one synchronous, one asynchronous:

Java

// Synchronous
public Response<List<Doc>> query(QueryDocRequest queryDocRequest);

// Asynchronous
public ListenableFuture<Response<List<Doc>>> queryAsync(QueryDocRequest queryDocRequest);

Both methods accept a QueryDocRequest object built with QueryDocRequestBuilder. The synchronous method blocks until results are returned. The asynchronous method returns a ListenableFuture that resolves when the search completes.

Examples

All examples below query a collection named quickstart. Before running any example:

Note

Replace YOUR_API_KEY with your API key and YOUR_CLUSTER_ENDPOINT with the endpoint of your cluster.
Create the quickstart collection. See the "Example" section of Create a collection.
Insert documents into the collection. See Insert documents.

Search by vector

Pass a dense vector to find the most similar documents.

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 4-dimensional query vector
        Vector vector = Vector.builder().value(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f)).build();

        // Return the top 100 most similar documents, including vector values
        QueryDocRequest request = QueryDocRequest.builder()
            .vector(vector)
            .topk(100)
            .includeVector(true)
            .build();

        Response<List<Doc>> response = collection.query(request);
        assert response.isSuccess();

        System.out.println(response);
        // Sample output:
        // {
        //   "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
        //     }
        //   ]
        // }
    }
}

Note

Note: Setting includeVector(true) returns vector data in each result. For better performance with large topk values, leave this parameter at its default (false) unless you need the raw vectors.

Search by primary key

Search using a stored document's vector without re-supplying the vector values. Specify the document ID and optionally select which fields to return.

Java

QueryDocRequest request = QueryDocRequest.builder()
    .id("1")
    .topk(100)
    .outputFields(Arrays.asList("name", "age"))  // Return only the name and age fields
    .includeVector(true)
    .build();

Response<List<Doc>> response = collection.query(request);
assert response.isSuccess();

Search with a metadata filter

Combine a vector or primary key search with a metadata filter to narrow results. Filters use SQL WHERE clause syntax.

Java

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

QueryDocRequest request = QueryDocRequest.builder()
    .vector(vector)                                // Or use .id("1") for primary key search
    .topk(100)
    .filter("age > 18")                            // SQL WHERE syntax
    .outputFields(Arrays.asList("name", "age"))
    .includeVector(true)
    .build();

Response<List<Doc>> response = collection.query(request);
assert response.isSuccess();

The filter parameter supports standard SQL comparison and logical operators:

Filter expression	Meaning
`"age > 18"`	Documents where `age` is greater than 18
`"age >= 18 AND name = 'zhangsan'"`	`age` at least 18 and `name` equals `zhangsan`
`"weight < 80 OR age > 30"`	`weight` under 80 or `age` over 30

For the complete filter syntax, see Conditional filtering.

Hybrid search with dense and sparse vectors

Combine a dense vector with a sparse vector to blend semantic similarity and keyword relevance. Sparse vectors represent keyword weights for keyword-aware semantic search.

Java

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

QueryDocRequest request = QueryDocRequest.builder()
    .vector(vector)
    .sparseVector(
        new HashMap<Integer, Float>() {{
            put(1, 0.4f);
            put(10000, 0.6f);
            put(222222, 0.8f);
        }})  // Sparse vector: dimension index -> weight
    .build();

Response<List<Doc>> response = collection.query(request);
assert response.isSuccess();

Filter-only query

Retrieve documents that match metadata conditions without similarity ranking. Omit both vector and id to use this mode.

Java

QueryDocRequest request = QueryDocRequest.builder()
    .topk(100)
    .filter("age > 18")
    .outputFields(Arrays.asList("name", "age"))
    .includeVector(true)
    .build();

// No vector or ID -- results are filtered by metadata only
Response<List<Doc>> response = collection.query(request);
assert response.isSuccess();

Request parameters

Build a QueryDocRequest with QueryDocRequestBuilder.

Note

Note: To perform a similarity search, specify either vector or id. If you specify neither, the query returns only the documents that match the filter condition, without similarity ranking.

Method	Required	Default	Description
`vector(Vector vector)`	No	-	Dense vector to search against
`sparseVector(Map<Integer, Float>)`	No	-	Sparse vector for hybrid search
`id(String id)`	No	-	Primary key of a stored document whose vector to use as the query
`topk(int topk)`	No	10	Maximum number of results to return, ranked by similarity
`filter(String filter)`	No	-	Metadata filter in SQL WHERE clause syntax. See Conditional filtering
`includeVector(bool includeVector)`	No	false	Whether to include vector values in the response. Set to `false` for better performance when you do not need the raw vectors
`partition(String partition)`	No	default	Partition to search within
`outputFields(List<String> outputFields)`	No	All fields	Metadata fields to include in the response
`outputField(String field)`	No	-	Add a single metadata field to the response. Call multiple times to add more fields
`build()`	-	-	Build the `QueryDocRequest` object

Response parameters

Note

The query method returns a Response<List<Doc>> object with the following accessors:

Method	Type	Description	Example
`getCode()`	int	Status code. See Status codes	0
`getMessage()`	String	Status message	success
`getRequestId()`	String	Unique request ID for troubleshooting	19215409-ea66-4db9-8764-26ce2eb5bb99
`getOutput()`	List<Doc>	Matching documents ranked by similarity score. See Doc	`[{"id":"9","vector":{"value":[0.9,0.9,0.9,0.9]},"fields":{"name":"java_9","age":9},"score":90}]`
`isSuccess()`	Boolean	Whether the operation succeeded	true

DashVector:Query for documents

Search modes

Prerequisites

API signatures

Examples

Search by vector

Search by primary key

Search with a metadata filter

Hybrid search with dense and sparse vectors

Filter-only query

Request parameters

Response parameters

Related topics