Skip to main content

query()

The MilvusClient interface. This method queries entity(s) based on scalar field(s) filtered by boolean expression. Note that the order of the returned entities cannot be guaranteed.

R<QueryResults> query(QueryParam requestParam);

QueryParam

Use the QueryParam.Builder to construct a QueryParam object.

import io.milvus.param.dml.QueryParam;
QueryParam.Builder builder = QueryParam.newBuilder();

Methods of QueryParam.Builder:

Method

Description

Parameters

withCollectionName(collectionName)

Set the collection name. Collection name cannot be empty or null.

collectionName: The target collection name.

withDatabaseName(String databaseName)

Sets the database name. database name can be null for default database.

databaseName: The database name.

withConsistencyLevel(ConsistencyLevelEnum consistencyLevel)

Sets the search consistency level(Optional).
If the level is not set, will use the default consistency level of the collection.

consistencyLevel: The consistency level used in the query.

withPartitionNames(List<String> partitionNames)

Sets partition names list to specify query scope (Optional).

partitionNames: The name list of partitions to be queried.

addPartitionName(String partitionName)

Adds a partition to specify query scope (Optional).

partitionName: A partition name to be queried.

withOutFields(List<String> outFields)

Specifies output scalar fields (Optional).
If output fields are specified, the QueryResults returned by query() will contains the values of these fields.


outFields: The name list of fields to be outputed.

addOutField(String fieldName)

Specifies an output scalar field (Optional).

fieldName: An output field name.

withExpr(String expr)

Set the expression to query entities. For more information please refer to this doc.

expr: The expression to query

withOffset(Long offset)

Specify a position, the returned entities before this position will be ignored. Only take effect when the 'limit' value is specified. Default value is 0, start from begin.

offset: A value to define the position.

withLimit(Long limit)

Specify a value to control the returned number of entities. Must be a positive value. Default value is -1, will return without limit.

limit: A value to define the limit of returned entities.

withIgnoreGrowing(Boolean ignoreGrowing)

Ignore the growing segments to get best query performance. For the user case that don't require data visibility. Default value is False.

ignoreGrowing: Ignore growing segments or not.

build()

Construct a QueryParam object.

N/A

The QueryParam.Builder.build() can throw the following exceptions:

  • ParamException: error if the parameter is invalid.

Returns

This method catches all the exceptions and returns an R<QueryResults> object.

  • If the API fails on the server side, it returns the error code and message from the server.

  • If the API fails by RPC exception, it returns R.Status.Unknown and the error message of the exception.

  • If the API succeeds, it returns valid QueryResults held by the R template. You can use QueryResultsWrapper to get the query results.

QueryResultsWrapper

A tool class to encapsulate the QueryResults.

import io.milvus.response.QueryResultsWrapper;
QueryResultsWrapper wrapper = new QueryResultsWrapper(queryResults);

Methods of QueryResultsWrapper:

Method

Description

Parameters

Returns

getFieldWrapper(String fieldName)

Return a FieldDataWrapper object by a field name. Throws ParamException if the field doesn't exist.

fieldName: A field name which is specified by the withOutFields() of QueryParam.

FieldDataWrapper

getRowCount()

Gets the row count of a query result.

N/A

long

getRowRecords()

Gets row records list from the query result.

N/A

List<QueryResultsWrapper.RowRecord>

FieldDataWrapper

A tool class to encapsulate column data returned by query() API.

Methods of FieldDataWrapper:

Method

Description

Returns

isVectorField()

Tell the user if this field is a vector field or a scalar field.

boolean

isJsonField()

Tell the user if this field is a JSON field.

boolean

isDynamicField()

Tell the user if this field is a the dynamic field.

boolean

getDim()

Gets the dimension value if the field is a vector field. Throw IllegalResponseException if the field is not a vector field.

int

getRowCount()

Gets the row count of a field. Throws IllegalResponseException if the field data is illegal.

long

getFieldData()

Returns the field data according to field type.

  • Return List<List<Float>gt; for FloatVector field.

  • Return List<ByteBuffer> for BinaryVector/Float16Vector/BFloatVector field.

  • Return List<SortedMap<Long, Float>gt; for SparseFloatVector field.

  • Return List<Long> for Int64 field.

  • Return List<Integer> for Int32/Int16/Int8 field.

  • Return List<Boolean> for Bool field.

  • Return List<Float> for Float field.

  • Return List<Double> for Double field.

  • Return List<String> for Varchar field.

  • Return List<ByteString> for JSON field.

QueryResultsWrapper.RowRecord

A tool class to hold the data of a single row in key-value format.

Methods of RowRecord:

Method

Description

Returns

put(String keyName, Object obj)

For internal use. Set a key-value pair for the row.

boolean

get(String keyName)

Get a value by a key name. If the key name is a field name, return the value of this field.If the key name is in the dynamic field, return the value from the dynamic field.Throws ParamException if the key name doesn't exist.

Object

Example

import io.milvus.param.dml.*;
import io.milvus.response.QueryResultsWrapper;
import io.milvus.response.FieldDataWrapper;
import io.milvus.grpc.QueryResults;

QueryParam param = QueryParam.newBuilder()
.withCollectionName(COLLECTION_NAME)
.withExpr("id in [100, 101]")
.addOutFields("field1")
.withConsistencyLevel(ConsistencyLevelEnum.EVENTUALLY)
.build();
R<QueryResults> response = client.query(param)
if (response.getStatus() != R.Status.Success.getCode()) {
System.out.println(response.getMessage());
}

QueryResultsWrapper wrapper = new QueryResultsWrapper(response.getData());
List<QueryResultsWrapper.RowRecord> records = wrapper.getRowRecords();
for (QueryResultsWrapper.RowRecord record:records) {
System.out.println(record);
}