mondrian.olap
Class Query

java.lang.Object
  mondrian.olap.QueryPart
      mondrian.olap.Query

All Implemented Interfaces:

Walkable

public class Query
extends QueryPart

Query is an MDX query.

It is created by calling Connection.parseQuery(java.lang.String), and executed by calling Connection.execute(mondrian.olap.Query), to return a Result.

Query control

Most queries are model citizens, executing quickly (often using cached results from previous queries), but some queries take more time, or more database resources, or more results, than is reasonable. Mondrian offers three ways to control rogue queries:

• You can set a query timeout by setting the MondrianProperties.QueryTimeout parameter. If the query takes longer to execute than the value of this parameter, the system will kill it.
• The MondrianProperties.QueryLimit parameter limits the number of cells returned by a query.
• At any time while a query is executing, another thread can call the cancel() method. The call to Connection.execute(Query) will throw an exception.

Author:

jhyde

Field Summary

(package private) Set<FunDef>	alertedNonNativeFunDefs Set of FunDefs for which alerts about non-native evaluation have already been posted.
QueryAxis[]	axes public-private: This must be public because it is still accessed in rolap.RolapConnection
Calc[]	axisCalcs
Formula[]	formulas public-private: This must be public because it is still accessed in rolap.RolapCube
QueryAxis	slicerAxis public-private: This must be public because it is still accessed in rolap.RolapResult
Calc	slicerCalc

Constructor Summary

Query(Connection connection, Cube mdxCube, Formula[] formulas, QueryAxis[] axes, QueryAxis slicerAxis, QueryPart[] cellProps, Parameter[] parameters, boolean load, boolean strictValidation)
Creates a Query.

Query(Connection connection, Formula[] formulas, QueryAxis[] axes, String cube, QueryAxis slicerAxis, QueryPart[] cellProps, boolean load, boolean strictValidation)
Creates a Query.

Method Summary

Object	accept(MdxVisitor visitor)
void	addFormula(Id id, Exp exp) Adds a new formula specifying a set to an existing query.
void	addFormula(Id id, Exp exp, MemberProperty[] memberProperties) Adds a new formula specifying a member to an existing query.
void	addLevelToAxis(AxisOrdinal axis, Level level) Adds a level to an axis expression.
void	addMeasuresMembers(OlapElement olapElement) Keeps track of references to members of the measures dimension
void	cancel() Issues a cancel request on this Query object.
boolean	canRemoveFormula(String uniqueName) Returns whether a formula can safely be removed from the query.
void	checkCancelOrTimeout() Checks if either a cancel request has been issued on the query or the execution time has exceeded the timeout value (if one has been set).
void	clearEvalCache() Remove all entries in the evaluation cache
Object	clone()
Calc	compileExpression(Exp exp, boolean scalar, ResultStyle resultStyle) Compiles an expression, using a cached compiled expression if available.
ExpCompiler	createCompiler()
Validator	createValidator()
Validator	createValidator(FunTable functionTable)
Formula	findFormula(String uniqueName) Looks up a calculated member or set defined in this Query.
QueryAxis[]	getAxes() Returns an array of this query's axes.
List<RolapCube>	getBaseCubes() return the set of base cubes associated with the virtual cube referenced in this query
Object[]	getChildren() Returns an array of the object's children.
Connection	getConnection()
Cube	getCube()
(package private) List<Member>	getDefinedMembers()
Object	getEvalCache(String key) Gets the Object associated with the value.
Formula[]	getFormulas() Returns an array of the formulas used in this query.
Hierarchy[]	getMdxHierarchiesOnAxis(AxisOrdinal axis) Returns Hierarchy[] used on axis.
Set<Member>	getMeasuresMembers()
Parameter[]	getParameters() Returns the parameters defined in this query.
long	getQueryStartTime() Gets the query start time
ResultStyle	getResultStyle()
SchemaReader	getSchemaReader(boolean accessControlled) Returns a schema reader.
QueryAxis	getSlicerAxis()
boolean	hasCellProperty(String propertyName) Checks whether the property name is present in the query.
boolean	ignoreInvalidMembers()
boolean	isCellPropertyEmpty() Checks whether any cell property present in the query
Member	lookupMemberFromCache(String memberUniqueName) Looks up a member whose unique name is memberUniqueName from cache.
boolean	nativeCrossJoinVirtualCube()
void	putEvalCache(String key, Object value) Put an Object value into the evaluation cache with given key.
void	removeFormula(String uniqueName, boolean failIfUsedInQuery) Remove a formula from the query.
void	renameFormula(String uniqueName, String newName) Finds formula by name and renames it to new name.
void	resolve() Performs type-checking and validates internal consistency of a query, using the default resolver.
void	resolve(Validator validator) Performs type-checking and validates internal consistency of a query.
Query	safeClone()
void	setAxisShowEmptyCells(int axis, boolean showEmpty) Finds axis by index and sets flag to show empty cells on that axis.
void	setBaseCubes(List<RolapCube> baseCubes) Saves away the base cubes related to the virtual cube referenced in this query
(package private) void	setOutOfMemory(String msg)
void	setParameter(String parameterName, String value) Assigns a value to the parameter with a given name.
void	setQueryEndExecution() Called when query execution has completed.
void	setQueryStartTime() Sets the start time of query execution.
void	setQueryTimeoutMillis(long queryTimeoutMillis) Sets the timeout in milliseconds of this Query.
void	setResultStyle(ResultStyle resultStyle) A Query's ResultStyle can only be one of the following: ResultStyle.ITERABLE ResultStyle.LIST ResultStyle.MUTABLE_LIST
void	setSlicerAxis(QueryAxis axis)
void	setVirtualCubeNonNativeCrossJoin() Indicates that the query cannot use native cross joins to process this virtual cube
boolean	shouldAlertForNonNative(FunDef funDef) Determines whether an alert for non-native evaluation needs to be posted.
void	swapAxes() Swaps the x- and y- axes.
String	toString() Returns the MDX query string.
void	unparse(PrintWriter pw) Writes a string representation of this parse tree node to the given writer.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

formulas

public Formula[] formulas

public-private: This must be public because it is still accessed in rolap.RolapCube

axes

public QueryAxis[] axes

public-private: This must be public because it is still accessed in rolap.RolapConnection

slicerAxis

public QueryAxis slicerAxis

public-private: This must be public because it is still accessed in rolap.RolapResult

axisCalcs

public Calc[] axisCalcs

slicerCalc

public Calc slicerCalc

alertedNonNativeFunDefs

Set<FunDef> alertedNonNativeFunDefs

Set of FunDefs for which alerts about non-native evaluation have already been posted.

Constructor Detail

Query

public Query(Connection connection,
             Formula[] formulas,
             QueryAxis[] axes,
             String cube,
             QueryAxis slicerAxis,
             QueryPart[] cellProps,
             boolean load,
             boolean strictValidation)

Creates a Query.

Query

public Query(Connection connection,
             Cube mdxCube,
             Formula[] formulas,
             QueryAxis[] axes,
             QueryAxis slicerAxis,
             QueryPart[] cellProps,
             Parameter[] parameters,
             boolean load,
             boolean strictValidation)

Creates a Query.

Method Detail

setQueryTimeoutMillis

public void setQueryTimeoutMillis(long queryTimeoutMillis)

Sets the timeout in milliseconds of this Query.

Zero means no timeout.

Parameters:

queryTimeoutMillis - Timeout in milliseconds

hasCellProperty

public boolean hasCellProperty(String propertyName)

Checks whether the property name is present in the query.

isCellPropertyEmpty

public boolean isCellPropertyEmpty()

Checks whether any cell property present in the query

addFormula

public void addFormula(Id id,
                       Exp exp)

Adds a new formula specifying a set to an existing query.

addFormula

public void addFormula(Id id,
                       Exp exp,
                       MemberProperty[] memberProperties)

Adds a new formula specifying a member to an existing query.

Parameters:

id - Name of member

exp - Expression for member

memberProperties - Properties of member

createValidator

public Validator createValidator()

createValidator

public Validator createValidator(FunTable functionTable)

clone

public Object clone()

Overrides:

clone in class Object

safeClone

public Query safeClone()

getConnection

public Connection getConnection()

cancel

public void cancel()

Issues a cancel request on this Query object. Once the thread running the query detects the cancel request, the query execution will throw an exception. See BasicQueryTest.testCancel for an example of usage of this method.

setOutOfMemory

void setOutOfMemory(String msg)

checkCancelOrTimeout

public void checkCancelOrTimeout()

Checks if either a cancel request has been issued on the query or the execution time has exceeded the timeout value (if one has been set). Exceptions are raised if either of these two conditions are met. This method should be called periodically during query execution to ensure timely detection of these events, particularly before/after any potentially long running operations.

setQueryStartTime

public void setQueryStartTime()

Sets the start time of query execution. Used to detect timeout for queries.

getQueryStartTime

public long getQueryStartTime()

Gets the query start time

Returns:

start time

setQueryEndExecution

public void setQueryEndExecution()

Called when query execution has completed. Once query execution has ended, it is not possible to cancel or timeout the query until it starts executing again.

shouldAlertForNonNative

public boolean shouldAlertForNonNative(FunDef funDef)

Determines whether an alert for non-native evaluation needs to be posted.

Parameters:

funDef - function type to alert for

Returns:

true if alert should be raised

resolve

public void resolve()

Performs type-checking and validates internal consistency of a query, using the default resolver.

This method is called automatically when a query is created; you need to call this method manually if you have modified the query's expression tree in any way.

ignoreInvalidMembers

public boolean ignoreInvalidMembers()

Returns:

true if the relevant property for ignoring invalid members is set to true for this query's environment (a different property is checked depending on whether environment is schema load vs query validation)

setResultStyle

public void setResultStyle(ResultStyle resultStyle)

A Query's ResultStyle can only be one of the following: ResultStyle.ITERABLE ResultStyle.LIST ResultStyle.MUTABLE_LIST

Parameters:

resultStyle -

getResultStyle

public ResultStyle getResultStyle()

resolve

public void resolve(Validator validator)

Performs type-checking and validates internal consistency of a query.

Parameters:

validator - Validator

unparse

public void unparse(PrintWriter pw)

Description copied from class: QueryPart

Writes a string representation of this parse tree node to the given writer.

Overrides:

unparse in class QueryPart

Parameters:

pw - writer

toString

public String toString()

Returns the MDX query string.

Overrides:

toString in class Object

getChildren

public Object[] getChildren()

Description copied from interface: Walkable

Returns an array of the object's children. Those which are not Walkable are ignored.

Specified by:

getChildren in interface Walkable

Overrides:

getChildren in class QueryPart

getSlicerAxis

public QueryAxis getSlicerAxis()

setSlicerAxis

public void setSlicerAxis(QueryAxis axis)

addLevelToAxis

public void addLevelToAxis(AxisOrdinal axis,
                           Level level)

Adds a level to an axis expression.

setParameter

public void setParameter(String parameterName,
                         String value)

Assigns a value to the parameter with a given name.

Throws:

RuntimeException - if there is not parameter with the given name

swapAxes

public void swapAxes()

Swaps the x- and y- axes. Does nothing if the number of axes != 2.

getParameters

public Parameter[] getParameters()

Returns the parameters defined in this query.

getCube

public Cube getCube()

getSchemaReader

public SchemaReader getSchemaReader(boolean accessControlled)

Returns a schema reader.

Parameters:

accessControlled - If true, schema reader returns only elements which are accessible to the connection's current role

Returns:

schema reader

lookupMemberFromCache

public Member lookupMemberFromCache(String memberUniqueName)

Looks up a member whose unique name is memberUniqueName from cache. If the member is not in cache, returns null.

getFormulas

public Formula[] getFormulas()

Returns an array of the formulas used in this query.

getAxes

public QueryAxis[] getAxes()

Returns an array of this query's axes.

removeFormula

public void removeFormula(String uniqueName,
                          boolean failIfUsedInQuery)

Remove a formula from the query. If failIfUsedInQuery is true, checks and throws an error if formula is used somewhere in the query.

canRemoveFormula

public boolean canRemoveFormula(String uniqueName)

Returns whether a formula can safely be removed from the query. It can be removed if the member or set it defines it not used anywhere else in the query, including in another formula.

Parameters:

uniqueName - Unique name of the member or set defined by the formula

Returns:

whether the formula can safely be removed

findFormula

public Formula findFormula(String uniqueName)

Looks up a calculated member or set defined in this Query.

Parameters:

uniqueName - Unique name of calculated member or set

Returns:

formula defining calculated member, or null if not found

renameFormula

public void renameFormula(String uniqueName,
                          String newName)

Finds formula by name and renames it to new name.

getDefinedMembers

List<Member> getDefinedMembers()

setAxisShowEmptyCells

public void setAxisShowEmptyCells(int axis,
                                  boolean showEmpty)

Finds axis by index and sets flag to show empty cells on that axis.

getMdxHierarchiesOnAxis

public Hierarchy[] getMdxHierarchiesOnAxis(AxisOrdinal axis)

Returns Hierarchy[] used on axis. It calls collectHierarchies(mondrian.olap.Exp).

compileExpression

public Calc compileExpression(Exp exp,
                              boolean scalar,
                              ResultStyle resultStyle)

Compiles an expression, using a cached compiled expression if available.

Parameters:

exp - Expression

scalar - Whether expression is scalar

resultStyle - Preferred result style; if null, use query's default result style; ignored if expression is scalar

Returns:

compiled expression

createCompiler

public ExpCompiler createCompiler()

addMeasuresMembers

public void addMeasuresMembers(OlapElement olapElement)

Keeps track of references to members of the measures dimension

Parameters:

olapElement - potential measure member

getMeasuresMembers

public Set<Member> getMeasuresMembers()

Returns:

set of members from the measures dimension referenced within this query

setVirtualCubeNonNativeCrossJoin

public void setVirtualCubeNonNativeCrossJoin()

Indicates that the query cannot use native cross joins to process this virtual cube

nativeCrossJoinVirtualCube

public boolean nativeCrossJoinVirtualCube()

Returns:

true if the query can use native cross joins on a virtual cube

setBaseCubes

public void setBaseCubes(List<RolapCube> baseCubes)

Saves away the base cubes related to the virtual cube referenced in this query

Parameters:

baseCubes - set of base cubes

getBaseCubes

public List<RolapCube> getBaseCubes()

return the set of base cubes associated with the virtual cube referenced in this query

Returns:

set of base cubes

accept

public Object accept(MdxVisitor visitor)

putEvalCache

public void putEvalCache(String key,
                         Object value)

Put an Object value into the evaluation cache with given key. This is used by Calc's to store information between iterations (rather than re-generate each time).

Parameters:

key - the cache key

value - the cache value

getEvalCache

public Object getEvalCache(String key)

Gets the Object associated with the value.

Parameters:

key - the cache key

Returns:

the cached value or null.

clearEvalCache

public void clearEvalCache()

Remove all entries in the evaluation cache