milvus-logo
LFAI
< Docs
  • Java
    • v1

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.
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\ 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\ 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\

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.

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.*;
import io.milvus.response.QueryResultsWrapper;
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);
}