milvus-logo

query()

A MilvusClient interface. This method queries entity(s) based on scalar field(s) filtered by boolean expression.

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.QueryParam;
QueryParam.Builder builder = QueryParam.newBuilder();

Methods of QueryParam.Builder:

MethodDescriptionParameters
withCollectionName(collectionName)Sets the collection name. The collection name cannot be empty or null.collectionName: The name of the collection to query.
withConsistencyLevel(ConsistencyLevelEnum consistencyLevel)Sets the consistency level used in the query. If the consistency level is not specified, the default level is ConsistencyLevelEnum.BOUNDED.consistencyLevel: The consistency level used in the query.
withPartitionNames(List<String> partitionNames)Sets a partition name list to specify query scope (Optional).partitionNames: The name list of the partitions to query.
addPartitionName(String partitionName)Adds a partition to specify query scope (Optional).partitionName: The name of the partition to query.
withTravelTimestamp(Long ts)Specifies an absolute timestamp in a query to get results based on a data view at a specified point in time (Optional). The default value is 0, with which the server executes the query on a full data view. For more information please refer to Search with Time Travel.ts: An absolute timestamp value.
withOutFields(List<String> outFields)Specifies the output scalar fields (Optional). If the output fields are specified, the QueryResults returned by query() will contains the values of these fields.outFields: The name list of output fields.
addOutField(String fieldName)Specifies an output scalar field (Optional).fieldName: The name of an output field .
withExpr(String expr)Sets the expression to query entities. For more information please refer to Boolean Expression Rules.expr: The boolean expression used in the query.
withOffset(Long offset)Sets a position, the returned entities before which will be ignored. This parameter works only when the limit value is specified. The default value is 0, starting from beginning of the returned set of entities.offset: A value that defines the position.
withLimit(Long limit)Sets a value to limit the returned number of entities. It must be a positive integer. The default value is 0, indicating that all entities are returned without a limit.limit: A value that defines the limit of returned entities.
build()Constructs 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.Unknow 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:

MethodDescriptionParametersReturns
getFieldWrapper(String fieldName)Returns a FieldDataWrapper object by a field name. ParamException is thrown if the field does not exist.fieldName: a field name which is specified by the withOutFields() of QueryParam.FieldDataWrapper

FieldDataWrapper

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

Methods of FieldDataWrapper:

MethodDescriptionReturns
isVectorField()Indicated whether this field is a vector field or a scalar field.Boolean
getDim()Gets the dimension value if the field is a vector field. IllegalResponseException is thrown if the field is not a vector field.int
getRowCount()Gets the row count of a field. IllegalResponseException is thrown if the field data is illegal.long
getFieldData()Returns the field data according to field type.
  • Returns List<List<Float>> for float vector field.
  • Returns List<ByteBuffer> for binary vector field.
  • Returns List<Long> for int64 field.
  • Returns List<Integer> for int32/int16/int8 field.
  • Returns List<Boolean> for boolean field.
  • Returns List<Float> for float field.
  • Returns List<Double> for double field.
  • Returns List<String> for VARCHAR field.
  • Example

    import io.milvus.param.*;
    import io.milvus.response.QueryResultsWrapper;
    import io.milvus.response.FieldDataWrapper;
    import io.milvus.grpc.QueryResults;
    
    QueryParam param = QueryParam.newBuilder()
            .withCollectionName("collection1")
            .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());
    FieldDataWrapper fieldData = queryResultsWrapper.getFieldWrapper("field1");
    System.out.println("Field " + fieldName + " row count: " + fieldData.getRowCount());
    System.out.println(fieldData.getFieldData());