Interface MqlValue
- All Known Subinterfaces:
MqlArray<T>
,MqlBoolean
,MqlDate
,MqlDocument
,MqlEntry<T>
,MqlInteger
,MqlMap<T>
,MqlNumber
,MqlString
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:
-
Method Summary
Modifier and TypeMethodDescriptionasString()
The string representation ofthis
value.Whetherthis
value is equal to theother
value.boolean
The methodeq(com.mongodb.client.model.mql.MqlValue)
should be used to compare values for equality.Whetherthis
value is greater than theother
value.Whetherthis
value is greater than or equal to theother
value.<T extends MqlValue>
MqlArray<@MqlUnchecked(TYPE_ARGUMENT) T>this
value as a array ifthis
is an array, or theother
array value ifthis
is null, or is missing, or is of any other non-array type.isBooleanOr
(MqlBoolean other) this
value as a boolean ifthis
is a boolean, or theother
boolean value ifthis
is null, or is missing, or is of any other non-boolean type.this
value as a boolean ifthis
is a date, or theother
date value ifthis
is null, or is missing, or is of any other non-date type.<T extends MqlDocument>
TisDocumentOr
(T other) isIntegerOr
(MqlInteger other) this
value as an integer ifthis
is an integer, or theother
integer value ifthis
is null, or is missing, or is of any other non-integer type.<T extends MqlValue>
MqlMap<@MqlUnchecked(TYPE_ARGUMENT) T>this
value as a map ifthis
is a map (or map-like value, seeMqlDocument
andMqlEntry
) or theother
map value ifthis
is null, or is missing, or is of any other non-map type.isNumberOr
(MqlNumber other) this
value as a number ifthis
is a number, or theother
number value ifthis
is null, or is missing, or is of any other non-number type.isStringOr
(MqlString other) this
value as a string ifthis
is a string, or theother
string value ifthis
is null, or is missing, or is of any other non-string type.Whetherthis
value is less than theother
value.Whetherthis
value is less than or equal to theother
value.Whetherthis
value is not equal to theother
value.<R extends MqlValue>
RThe result of passingthis
value to the provided function.<R extends MqlValue>
RThe result of applying the provided switch mapping tothis
value.
-
Method Details
-
equals
The methodeq(com.mongodb.client.model.mql.MqlValue)
should be used to compare values for equality. This method checks reference equality. -
eq
- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
ne
Whetherthis
value is not equal to theother
value.The result does not correlate with
equals(Object)
.- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
gt
Whetherthis
value is greater than theother
value.- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
gte
Whetherthis
value is greater than or equal to theother
value.- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
lt
Whetherthis
value is less than theother
value.- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
lte
Whetherthis
value is less than or equal to theother
value.- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
isBooleanOr
this
value as a boolean ifthis
is a boolean, or theother
boolean value ifthis
is null, or is missing, or is of any other non-boolean type.- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
isNumberOr
this
value as a number ifthis
is a number, or theother
number value ifthis
is null, or is missing, or is of any other non-number type.- Parameters:
other
- the other value.- Returns:
- the resulting value.
- Since server release
- 4.4
-
isIntegerOr
this
value as an integer ifthis
is an integer, or theother
integer value ifthis
is null, or is missing, or is of any other non-integer type.- Parameters:
other
- the other value.- Returns:
- the resulting value.
- Since server release
- 5.2
-
isStringOr
this
value as a string ifthis
is a string, or theother
string value ifthis
is null, or is missing, or is of any other non-string type.- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
isDateOr
this
value as a boolean ifthis
is a date, or theother
date value ifthis
is null, or is missing, or is of any other non-date type.- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
isArrayOr
<T extends MqlValue> MqlArray<@MqlUnchecked(TYPE_ARGUMENT) T> isArrayOr(MqlArray<? extends T> other) this
value as a array ifthis
is an array, or theother
array value ifthis
is null, or is missing, or is of any other non-array type.Warning: The type of the elements of the resulting array are not enforced by the API. The specification of a type by the user is an unchecked assertion that all elements are of that type. If the array contains multiple types (such as both nulls and integers) then a super-type encompassing all types must be chosen, and if necessary the elements should be individually type-checked when used.
- Type Parameters:
T
- the type of the elements of the resulting array.- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
isDocumentOr
this
value as a document ifthis
is a document (or document-like value, seeMqlMap
andMqlEntry
) or theother
document value ifthis
is null, or is missing, or is of any other non-document type.- Type Parameters:
T
- the type.- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
isMapOr
this
value as a map ifthis
is a map (or map-like value, seeMqlDocument
andMqlEntry
) or theother
map value ifthis
is null, or is missing, or is of any other non-map type.Warning: The type of the values of the resulting map are not enforced by the API. The specification of a type by the user is an unchecked assertion that all map values are of that type. If the map contains multiple types (such as both nulls and integers) then a super-type encompassing all types must be chosen, and if necessary the elements should be individually type-checked when used.
- Type Parameters:
T
- the type of the values of the resulting map.- Parameters:
other
- the other value.- Returns:
- the resulting value.
-
asString
MqlString asString()The string representation ofthis
value.This will cause an error if the type cannot be converted to a string, as is the case with arrays, documents, maps, entries, and the null value.
- Returns:
- the resulting value.
- See Also:
- Since server release
- 4.0
-
passTo
The result of passingthis
value to the provided function. Equivalent tof.apply(this)
, and allows lambdas and static, user-defined functions to use the chaining syntax.The appropriate type-based variant should be used when the type of
this
is known.- Type Parameters:
R
- the type of the resulting value.- Parameters:
f
- the function to apply.- Returns:
- the resulting value.
- See Also:
-
MqlBoolean.passBooleanTo(java.util.function.Function<? super com.mongodb.client.model.mql.MqlBoolean, ? extends R>)
MqlInteger.passIntegerTo(java.util.function.Function<? super com.mongodb.client.model.mql.MqlInteger, ? extends R>)
MqlNumber.passNumberTo(java.util.function.Function<? super com.mongodb.client.model.mql.MqlNumber, ? extends R>)
MqlString.passStringTo(java.util.function.Function<? super com.mongodb.client.model.mql.MqlString, ? extends R>)
MqlDate.passDateTo(java.util.function.Function<? super com.mongodb.client.model.mql.MqlDate, ? extends R>)
MqlArray.passArrayTo(java.util.function.Function<? super com.mongodb.client.model.mql.MqlArray<T>, ? extends R>)
MqlMap.passMapTo(java.util.function.Function<? super com.mongodb.client.model.mql.MqlMap<T>, ? extends R>)
MqlDocument.passDocumentTo(java.util.function.Function<? super com.mongodb.client.model.mql.MqlDocument, ? extends R>)
-
switchOn
<R extends MqlValue> R switchOn(Function<Branches<MqlValue>, ? extends BranchesTerminal<MqlValue, ? extends R>> mapping) The result of applying the provided switch mapping tothis
value.Can be used to perform pattern matching on the type of
this
value, or to perform comparisons, or to perform any arbitrary check onthis
value.The suggested convention is to use "
on
" as the name of themapping
parameter, for example:myValue.switchOn(on -> on .isInteger(...) ... .defaults(...))
The appropriate type-based variant should be used when the type of
this
is known.- Type Parameters:
R
- the type of the resulting value.- Parameters:
mapping
- the switch mapping.- Returns:
- the resulting value.
- See Also:
-
MqlBoolean.switchBooleanOn(java.util.function.Function<com.mongodb.client.model.mql.Branches<com.mongodb.client.model.mql.MqlBoolean>, ? extends com.mongodb.client.model.mql.BranchesTerminal<com.mongodb.client.model.mql.MqlBoolean, ? extends R>>)
MqlInteger.switchIntegerOn(java.util.function.Function<com.mongodb.client.model.mql.Branches<com.mongodb.client.model.mql.MqlInteger>, ? extends com.mongodb.client.model.mql.BranchesTerminal<com.mongodb.client.model.mql.MqlInteger, ? extends R>>)
MqlNumber.switchNumberOn(java.util.function.Function<com.mongodb.client.model.mql.Branches<com.mongodb.client.model.mql.MqlNumber>, ? extends com.mongodb.client.model.mql.BranchesTerminal<com.mongodb.client.model.mql.MqlNumber, ? extends R>>)
MqlString.switchStringOn(java.util.function.Function<com.mongodb.client.model.mql.Branches<com.mongodb.client.model.mql.MqlString>, ? extends com.mongodb.client.model.mql.BranchesTerminal<com.mongodb.client.model.mql.MqlString, ? extends R>>)
MqlDate.switchDateOn(java.util.function.Function<com.mongodb.client.model.mql.Branches<com.mongodb.client.model.mql.MqlDate>, ? extends com.mongodb.client.model.mql.BranchesTerminal<com.mongodb.client.model.mql.MqlDate, ? extends R>>)
MqlArray.switchArrayOn(java.util.function.Function<com.mongodb.client.model.mql.Branches<com.mongodb.client.model.mql.MqlArray<T>>, ? extends com.mongodb.client.model.mql.BranchesTerminal<com.mongodb.client.model.mql.MqlArray<T>, ? extends R>>)
MqlMap.switchMapOn(java.util.function.Function<com.mongodb.client.model.mql.Branches<com.mongodb.client.model.mql.MqlMap<T>>, ? extends com.mongodb.client.model.mql.BranchesTerminal<com.mongodb.client.model.mql.MqlMap<T>, ? extends R>>)
MqlDocument.switchDocumentOn(java.util.function.Function<com.mongodb.client.model.mql.Branches<com.mongodb.client.model.mql.MqlDocument>, ? extends com.mongodb.client.model.mql.BranchesTerminal<com.mongodb.client.model.mql.MqlDocument, ? extends R>>)
-