org.apache.lens.cube.parse

Interface Candidate

All Known Implementing Classes:

JoinCandidate, SegmentationCandidate, StorageCandidate, UnionCandidate

public interface Candidate

This interface represents candidates that are involved in different phases of query rewriting. At the lowest level, Candidate is represented by a StorageCandidate that has a fact on a storage and other joined dimensions (if any) that are required to answer the query or part of the query. At a higher level Candidate can also be a Join or a Union Candidate representing join or union between other candidates Different Re-writers will work on applicable candidates to produce a final candidate which will be used for generating the re-written query.

Method Summary

Modifier and Type	Method and Description
void	addAnswerableMeasurePhraseIndices(int index) Add `index` as answerable index in a pre-decided list of queried phrases.
boolean	contains(Candidate candidate) Returns true if this candidate contains the given candidate
default Candidate	copy() Clones this candidate
default Set<org.apache.lens.cube.parse.QueriedPhraseContext>	coveredPhrases(Set<org.apache.lens.cube.parse.QueriedPhraseContext> phrases) Filters phrases that are covered by this candidate
default Set<Integer>	decideMeasurePhrasesToAnswer(Set<Integer> measurePhraseIndices)
boolean	evaluateCompleteness(TimeRange timeRange, TimeRange queriedTimeRange, boolean failOnPartialData) Calculates if this candidate can answer the query for given time range based on actual data registered with the underlying candidate storages.
Candidate	explode() Explode this candidate into another candidate.
Set<Integer>	getAnswerableMeasurePhraseIndices() Gets the index positions of answerable measure phrases in CubeQueryContext#selectPhrases
Collection<? extends Candidate>	getChildren() Returns child candidates of this candidate if any.
default int	getChildrenCount() Count of children
Optional<Date>	getColumnEndTime(String column) This method should give end time of a column, if there's any.
Collection<String>	getColumns() Returns all the fact columns
Optional<Date>	getColumnStartTime(String column) This method should give start time of a column, if there's any.
default org.apache.hadoop.conf.Configuration	getConf() Utility method to return the configuration of its cube query context.
OptionalDouble	getCost()
default <T extends CubeInterface> T	getCube() Utility method to return cube of its cube query context
default CubeMetastoreClient	getCubeMetastoreClient() Utility method to return the metastore client of its cube query context
CubeQueryContext	getCubeQueryContext() A candidate always works along with its cube query context.
Date	getEndTime() End Time for this candidate (calculated based on schema)
Set<FactPartition>	getParticipatingPartitions() Returns the set of fact partitions that will participate in this candidate.
Date	getStartTime() Start Time for this candidate (calculated based on schema)
default boolean	hasColumn(String column) Returns whether this candidate has the asked column or not
default boolean	isColumnPresentAndValidForRange(String column) Utility method for clubbing column contains check and column range validity check.
default boolean	isColumnValidForRange(String column) Utility method for checking column time range validity.
default boolean	isCompletelyValidForTimeRanges(List<TimeRange> timeRanges) Returns true if the Candidate is valid for all the timeranges based on its start and end times.
boolean	isDimAttributeEvaluable(String dim) Checks whether a dim attribute is evaluable by this candidate
boolean	isExpressionEvaluable(org.apache.lens.cube.parse.ExpressionResolver.ExpressionContext expressionContext) Checks whether an expression is evaluable by this candidate 1.
boolean	isExpressionEvaluable(String expr) Checks whether an expression is evaluable by this candidate 1.
default boolean	isPartiallyValidForTimeRange(TimeRange timeRange) Utility method for checking whether this candidate is partially valid for the given time range
default boolean	isPartiallyValidForTimeRanges(List<TimeRange> timeRanges) Utility method to check whether this candidate is partially valid for any of the given time ranges
boolean	isPhraseAnswerable(org.apache.lens.cube.parse.QueriedPhraseContext phrase) Checks whether the given queries phrase is evaluable by this candidate
boolean	isTimeRangeCoverable(TimeRange timeRange) Is time range coverable based on start and end times configured in schema for the composing storage candidates and valid update periods.
default QueryWriterContext	toQueryWriterContext(Map<Dimension,CandidateDim> dimsToQuery, CubeQueryContext rootCubeQueryContext) Get query writer context from the candidate.
default void	updateStorageCandidateQueriablePhraseIndices(List<org.apache.lens.cube.parse.QueriedPhraseContext> qpcList) Default method to update querieble phrase indices in candidate

Method Detail

getColumns

Collection<String> getColumns()

Returns all the fact columns

Returns:

collection of column names

hasColumn

default boolean hasColumn(String column)

Returns whether this candidate has the asked column or not

Parameters:

column - column to check

Returns:

whether this candidate contains the column

getStartTime

Date getStartTime()

Start Time for this candidate (calculated based on schema)

Returns:

start time of this candidate

getEndTime

Date getEndTime()

End Time for this candidate (calculated based on schema)

Returns:

end time of this candidate

isCompletelyValidForTimeRanges

default boolean isCompletelyValidForTimeRanges(List<TimeRange> timeRanges)

Returns true if the Candidate is valid for all the timeranges based on its start and end times.

Parameters:

timeRanges - time ranges to check

Returns:

whether this candidate is completely valid for all the time ranges

isPartiallyValidForTimeRanges

default boolean isPartiallyValidForTimeRanges(List<TimeRange> timeRanges)

Utility method to check whether this candidate is partially valid for any of the given time ranges

Parameters:

timeRanges - time ranges to check

Returns:

whether this candidate is partially valid for any of the ranges

isPartiallyValidForTimeRange

default boolean isPartiallyValidForTimeRange(TimeRange timeRange)

Utility method for checking whether this candidate is partially valid for the given time range

Parameters:

timeRange - time range to check

Returns:

whether this candidate is partially valid

getCost

OptionalDouble getCost()

Returns:

the cost of this candidate

contains

boolean contains(Candidate candidate)

Returns true if this candidate contains the given candidate

Parameters:

candidate - candidate to check

Returns:

whether this contains the candidate in question

getChildren

Collection<? extends Candidate> getChildren()

Returns child candidates of this candidate if any. Note: StorageCandidate will return null

Returns:

child candidates if this is a complex candidate, else null

getChildrenCount

default int getChildrenCount()

Count of children

Returns:

number of children it has. 0 if null.

isTimeRangeCoverable

boolean isTimeRangeCoverable(TimeRange timeRange)
                      throws LensException

Is time range coverable based on start and end times configured in schema for the composing storage candidates and valid update periods. Note: This method is different from evaluateCompleteness(TimeRange, TimeRange, boolean) . isTimeRangeCoverable checks the the possibility of covering time range from schema perspective by using valid storages/update periods while evaluateCompleteness checks if a time range can be covered based on registered partitions. So isTimeRangeCoverable = false implies evaluateCompleteness = false but vice versa is not true.

Parameters:

timeRange - The time range to check

Returns:

whether this time range is coverable by this candidate

Throws:

LensException - propagated exceptions

evaluateCompleteness

boolean evaluateCompleteness(TimeRange timeRange,
                             TimeRange queriedTimeRange,
                             boolean failOnPartialData)
                      throws LensException

Calculates if this candidate can answer the query for given time range based on actual data registered with the underlying candidate storages. This method will also update any internal candidate data structures that are required for writing the re-written query and to answer getParticipatingPartitions().

Parameters:

timeRange - : TimeRange to check completeness for. TimeRange consists of start time, end time and the partition column

queriedTimeRange - : User quried timerange

failOnPartialData - : fail fast if the candidate can answer the query only partially

Returns:

true if this Candidate can answer query for the given time range.

Throws:

LensException

getParticipatingPartitions

Set<FactPartition> getParticipatingPartitions()

Returns the set of fact partitions that will participate in this candidate. Note: This method can be called only after call to evaluateCompleteness(TimeRange, TimeRange, boolean)

Returns:

a set of participating partitions

isExpressionEvaluable

boolean isExpressionEvaluable(org.apache.lens.cube.parse.ExpressionResolver.ExpressionContext expressionContext)

Checks whether an expression is evaluable by this candidate 1. For a JoinCandidate, atleast one of the child candidates should be able to answer the expression 2. For a UnionCandidate, all child candidates should answer the expression

Parameters:

expressionContext - Expression to be evaluated for Candidate

Returns:

Whether the given expression is evaluable or not

isExpressionEvaluable

boolean isExpressionEvaluable(String expr)

Checks whether an expression is evaluable by this candidate 1. For a JoinCandidate, atleast one of the child candidates should be able to answer the expression 2. For a UnionCandidate, all child candidates should answer the expression

Parameters:

expr - Expression to be evaluated for Candidate

Returns:

Whether the given expression is evaluable or not

isDimAttributeEvaluable

boolean isDimAttributeEvaluable(String dim)
                         throws LensException

Checks whether a dim attribute is evaluable by this candidate

Parameters:

dim - dim attribute

Returns:

whether the dim attribute is evaluable by this candidate

Throws:

LensException - propageted exception

getAnswerableMeasurePhraseIndices

Set<Integer> getAnswerableMeasurePhraseIndices()

Gets the index positions of answerable measure phrases in CubeQueryContext#selectPhrases

Returns:

set of indices of answerable phrases

copy

default Candidate copy()
                throws LensException

Clones this candidate

Returns:

the clone

Throws:

LensException - propagated exception

isPhraseAnswerable

boolean isPhraseAnswerable(org.apache.lens.cube.parse.QueriedPhraseContext phrase)
                    throws LensException

Checks whether the given queries phrase is evaluable by this candidate

Parameters:

phrase - Phrase to check

Returns:

whether the phrase is evaluable by this candidate

Throws:

LensException - propagated exception

addAnswerableMeasurePhraseIndices

void addAnswerableMeasurePhraseIndices(int index)

Add `index` as answerable index in a pre-decided list of queried phrases.

Parameters:

index - index to mark as answerable

updateStorageCandidateQueriablePhraseIndices

default void updateStorageCandidateQueriablePhraseIndices(List<org.apache.lens.cube.parse.QueriedPhraseContext> qpcList)
                                                   throws LensException

Default method to update querieble phrase indices in candidate

Parameters:

qpcList - List of queries phrases

Throws:

LensException - propagated exception

isColumnPresentAndValidForRange

default boolean isColumnPresentAndValidForRange(String column)

Utility method for clubbing column contains check and column range validity check.

Parameters:

column - column name to check

Returns:

true if this candidate can answer this column looking at existence and time validity.

isColumnValidForRange

default boolean isColumnValidForRange(String column)

Utility method for checking column time range validity.

Parameters:

column - column to check

Returns:

true if this column is valid for all ranges queried

getColumnStartTime

Optional<Date> getColumnStartTime(String column)

This method should give start time of a column, if there's any. Else, this should return Optional.absent

Parameters:

column - column name

Returns:

optional start time of this column

getColumnEndTime

Optional<Date> getColumnEndTime(String column)

This method should give end time of a column, if there's any. Else, this should return Optional.absent

Parameters:

column - column name

Returns:

optional end time of this column

getCubeQueryContext

CubeQueryContext getCubeQueryContext()

A candidate always works along with its cube query context. So a top level method to retrieve that.

Returns:

cube query context for this candidate.

getConf

default org.apache.hadoop.conf.Configuration getConf()

Utility method to return the configuration of its cube query context.

Returns:

getCubeQueryContext().getConf()

getCubeMetastoreClient

default CubeMetastoreClient getCubeMetastoreClient()

Utility method to return the metastore client of its cube query context

Returns:

getCubeQueryContext().getMetastoreClient()

getCube

default <T extends CubeInterface> T getCube()

Utility method to return cube of its cube query context

Type Parameters:

T - a subclass of CubeInterface

Returns:

getCubeQueryContext().getCube()

coveredPhrases

default Set<org.apache.lens.cube.parse.QueriedPhraseContext> coveredPhrases(Set<org.apache.lens.cube.parse.QueriedPhraseContext> phrases)
                                                                     throws LensException

Filters phrases that are covered by this candidate

Parameters:

phrases - queried phrases to check

Returns:

a set of queried phrases belonging to the list `phrases` that are answerable by this candidate

Throws:

LensException - propagated exception

explode

Candidate explode()
           throws LensException

Explode this candidate into another candidate. Generally candidates can return `this` in this method Special case is storage candidate that returns UnionCandidate if there are multiple update periods covered and update periods have different tables.

Returns:

converted candidate

Throws:

LensException

toQueryWriterContext

default QueryWriterContext toQueryWriterContext(Map<Dimension,CandidateDim> dimsToQuery,
                                                CubeQueryContext rootCubeQueryContext)
                                         throws LensException

Get query writer context from the candidate. Default implementation is for Union, Join and Segmentation candidates. In the default implementation, a MultiCandidateQueryWriterContext is returned, whose children are obtained by getting the query writer contexts from the children of this candidate.

Parameters:

dimsToQuery - Dimensions and corresponding picked CandidateDim for query

rootCubeQueryContext - Root query context.

Returns:

A Query Writer Context

Throws:

LensException - exception to be propagated

decideMeasurePhrasesToAnswer

default Set<Integer> decideMeasurePhrasesToAnswer(Set<Integer> measurePhraseIndices)
                                           throws LensException

Throws:

LensException