Package com.apple.foundationdb.record.query.expressions

Interface QueryComponent

All Superinterfaces:

PlanHashable, QueryHashable

All Known Subinterfaces:

ComponentWithChildren, ComponentWithComparison, ComponentWithNoChildren, ComponentWithSingleChild

All Known Implementing Classes:

AndComponent, AndOrComponent, BaseField, BaseNestedField, EmptyComparison, FieldWithComparison, NestedField, NotComponent, OneOfThemWithComparison, OneOfThemWithComponent, OrComponent, QueryKeyExpressionWithComparison, QueryRecordFunctionWithComparison, RecordTypeKeyComparison

@API(STABLE)
public interface QueryComponent
extends PlanHashable, QueryHashable

Base component interface for checking whether a given record matches a query. Although you can provide your own implementations, let it be said that the planner does a lot of instanceof checks to determine which indexes to use, and thus will end up falling back to getting all records and then evaluating the component on the returned records. validate(Descriptors.Descriptor) must be called before calling eval(FDBRecordStoreBase, EvaluationContext, FDBRecord), or bad things may happen.

Nested Class Summary

Nested classes/interfaces inherited from interface com.apple.foundationdb.record.PlanHashable

PlanHashable.PlanHashKind

Nested classes/interfaces inherited from interface com.apple.foundationdb.record.QueryHashable

QueryHashable.QueryHashKind

Method Summary

Modifier and Type	Method	Description
default <M extends Message> Boolean	eval(FDBRecordStoreBase<M> store, EvaluationContext context, FDBRecord<M> record)	Return whether or not the given record matches this component.
default <M extends Message> CompletableFuture<Boolean>	evalAsync(FDBRecordStoreBase<M> store, EvaluationContext context, FDBRecord<M> record)	Asynchronous version of eval.
<M extends Message> Boolean	evalMessage(FDBRecordStoreBase<M> store, EvaluationContext context, FDBRecord<M> record, Message message)	Return whether or not the given record matches this component.
default <M extends Message> CompletableFuture<Boolean>	evalMessageAsync(FDBRecordStoreBase<M> store, EvaluationContext context, FDBRecord<M> record, Message message)	Asynchronous version of evalMessage.
default GraphExpansion	expand(CorrelationIdentifier baseAlias)	Expand this query component into a data flow graph.
GraphExpansion	expand(CorrelationIdentifier baseAlias, List<String> fieldNamePrefix)	Expand this query component into a data flow graph.
default boolean	isAsync()	Get whether this component is asynchronous.
void	validate(Descriptors.Descriptor descriptor)	Validate that the given descriptor is consistent with this component.

Methods inherited from interface com.apple.foundationdb.record.PlanHashable

planHash, planHash

Methods inherited from interface com.apple.foundationdb.record.QueryHashable

queryHash

Method Detail

eval

@Nullable
default <M extends Message> Boolean eval(@Nonnull
                                         FDBRecordStoreBase<M> store,
                                         @Nonnull
                                         EvaluationContext context,
                                         @Nullable
                                         FDBRecord<M> record)

Return whether or not the given record matches this component. This may return true or false, but it may also return null. Generally a component should return null if some data in the record is missing. e.g. if record does not have a value for field f, and this component is checking whether the value f is greater than 3, it will probably want to return null. Other types of component will naturally handle a value of null, such as isNull. Excepting for some outer wrapping components (e.g. isNull), a null return value should not be included in results. Implementations should override evalMessage(com.apple.foundationdb.record.provider.foundationdb.FDBRecordStoreBase<M>, com.apple.foundationdb.record.EvaluationContext, com.apple.foundationdb.record.provider.foundationdb.FDBRecord<M>, com.google.protobuf.Message) instead of this one, even if they do not deal with Protobuf messages, so that they interact properly with expressions that do.

Type Parameters:

M - the type of records

Parameters:

store - the record store from which the record came

context - context against which evaluation takes place

record - a record of the appropriate record type for this component

Returns:

true/false/null, true if the given record should be included in results, false if it should not, and null if this component cannot determine whether it should be included or not

evalMessage

@Nullable
<M extends Message> Boolean evalMessage(@Nonnull
                                        FDBRecordStoreBase<M> store,
                                        @Nonnull
                                        EvaluationContext context,
                                        @Nullable
                                        FDBRecord<M> record,
                                        @Nullable
                                        Message message)

Return whether or not the given record matches this component. The message might be the Protobuf form of a record or a piece of that record. If the key expression is meaningful against a subrecord, it should evaluate against the message. Otherwise, it should evaluate against the record and ignore what part of that record is being considered. There should not be any reason to call this method outside of the implementation of another evalMessage. Under ordinary circumstances, if record is null, then message will be null. Otherwise, message will be record.getRecord() or some submessage of that, possibly null if the corresponding field is missing.

Type Parameters:

M - the type of record

Parameters:

store - the record store from which the record came

context - context for bound expressions

record - the record

message - the Protobuf message to evaluate against

Returns:

true/false/null, true if the given record should be included in results, false if it should not, and null if this component cannot determine whether it should be included or not

See Also:

eval(com.apple.foundationdb.record.provider.foundationdb.FDBRecordStoreBase<M>, com.apple.foundationdb.record.EvaluationContext, com.apple.foundationdb.record.provider.foundationdb.FDBRecord<M>)

evalAsync

@Nonnull
default <M extends Message> CompletableFuture<Boolean> evalAsync(@Nonnull
                                                                 FDBRecordStoreBase<M> store,
                                                                 @Nonnull
                                                                 EvaluationContext context,
                                                                 @Nullable
                                                                 FDBRecord<M> record)

Asynchronous version of eval.

Type Parameters:

M - the type of records

Parameters:

store - the record store from which the record came

context - context against which evaluation takes place

record - a record of the appropriate record type for this component

Returns:

a future that completes with whether the record should be included in the query result

See Also:

eval(com.apple.foundationdb.record.provider.foundationdb.FDBRecordStoreBase<M>, com.apple.foundationdb.record.EvaluationContext, com.apple.foundationdb.record.provider.foundationdb.FDBRecord<M>)

evalMessageAsync

@Nonnull
default <M extends Message> CompletableFuture<Boolean> evalMessageAsync(@Nonnull
                                                                        FDBRecordStoreBase<M> store,
                                                                        @Nonnull
                                                                        EvaluationContext context,
                                                                        @Nullable
                                                                        FDBRecord<M> record,
                                                                        @Nullable
                                                                        Message message)

Asynchronous version of evalMessage.

Type Parameters:

M - the type of record

Parameters:

store - the record store from which the record came

context - context for bound expressions

record - the record

message - the Protobuf message to evaluate against

Returns:

a future that completes with whether the record should be included in the query result

See Also:

eval(com.apple.foundationdb.record.provider.foundationdb.FDBRecordStoreBase<M>, com.apple.foundationdb.record.EvaluationContext, com.apple.foundationdb.record.provider.foundationdb.FDBRecord<M>)

isAsync

default boolean isAsync()

Get whether this component is asynchronous.

Returns:

true if this component is better executed asynchronously

validate

void validate(@Nonnull
              Descriptors.Descriptor descriptor)

Validate that the given descriptor is consistent with this component. e.g. it has all the fields defined that this component wants to inspect.

Parameters:

descriptor - a record type descriptor, or a submessage descriptor

Throws:

Query.InvalidExpressionException - if the descriptor is not consistent with this component

expand

@API(EXPERIMENTAL)
default GraphExpansion expand(@Nonnull
                              CorrelationIdentifier baseAlias)

Expand this query component into a data flow graph. The returned graph represents an adequate representation of the component as composition of relational expressions and operators.

Parameters:

baseAlias - a an alias that refers to the data flow equivalent of an input to this component

Returns:

a new GraphExpansion representing the query graph equivalent of this query component

See Also:

KeyExpression.expand(com.apple.foundationdb.record.query.plan.temp.ExpansionVisitor<S>)

expand

@API(EXPERIMENTAL)
GraphExpansion expand(@Nonnull
                      CorrelationIdentifier baseAlias,
                      @Nonnull
                      List<String> fieldNamePrefix)

Expand this query component into a data flow graph. The returned graph represents an adequate representation of the component as composition of relational expressions and operators.

Parameters:

baseAlias - a an alias that refers to the data flow equivalent of an input to this component

fieldNamePrefix - a list of field names that accumulate a field nesting chain for non-repeated fields

Returns:

a new GraphExpansion representing the query graph equivalent of this query component

See Also:

TODO make this method private in Java 11