Package com.mongodb.client.model.mql

Interface MqlValue

All Known Subinterfaces:
MqlArray<T>, MqlBoolean, MqlDate, MqlDocument, MqlEntry<T>, MqlInteger, MqlMap<T>, MqlNumber, MqlString
@Sealed @Beta(CLIENT) public interface MqlValue
A value in the context of the MongoDB Query Language (MQL).

The API provided by this base type and its subtypes is the Java-native variant of MQL. It is used to query the MongoDB server, to perform remote computations, to store and retrieve data, or to otherwise work with data on a MongoDB server or compatible execution context. Though the methods exposed through this API generally correspond to MQL operations, this correspondence is not exact.

The following is an example of usage within an aggregation pipeline. Here, the current document value is obtained and its "numberArray" field is filtered and summed, in a style similar to that of the Java Stream API: 


 import static com.mongodb.client.model.mql.MqlValues.current;
 MongoCollection<Document> col = ...;
 AggregateIterable<Document> result = col.aggregate(Arrays.asList(
     addFields(new Field<>("result", current()
         .<MqlNumber>getArray("numberArray")
         .filter(v -> v.gt(of(0)))
         .sum(v -> v)))));

Values are typically initially obtained via the current document and its fields, or specified via statically-imported methods on the MqlValues class.

As with the Java Stream API's terminal operations, corresponding Java values are not directly available, but must be obtained indirectly via MongoCollection.aggregate or MongoCollection.find. Certain methods may cause an error, which will be produced through these "terminal operations".

The null value is not part of, and cannot be used as if it were part of, any explicit type (except the root type MqlValue itself). See MqlValues.ofNull() for more details.

This API specifies no "missing" or "undefined" value. Users may use MqlMap.has(com.mongodb.client.model.mql.MqlString) to check whether a value is present.

This type hierarchy differs from the org.bson types in that they provide computational operations, the numeric types are less granular, and it offers multiple abstractions of certain types (document, map, entry). It differs from the corresponding Java types (such as int, String, Map) in that the operations available differ, and in that an implementation of this API may be used to produce MQL in the form of BSON. (This API makes no guarantee regarding the BSON output produced by its implementation, which in any case may vary due to optimization or other factors.)

Some methods within the API constitute an assertion by the user that the data is of a certain type. For example, MqlDocument.getArray(java.lang.String)} requires that the underlying field is both an array, and an array of some certain type. If the field is not an array in the underlying data, behaviour is undefined by this API (though behaviours may be defined by the execution context, users are strongly discouraged from relying on behaviour that is not part of this API).

This API should be treated as sealed: it must not be extended or implemented (unless explicitly allowed).

Since:
4.9.0
See Also: