com.google.visualization.datasource.query
Class Query

java.lang.Object
  com.google.visualization.datasource.query.Query

public class Query
extends java.lang.Object

Holds the query data and clauses. This class is the result of parsing the query string that comes from the user. The clauses that can be included in a query are: select, filter, sort, group by, pivot, options, labels, format, limit, and offset. For more details see the query language reference . A Query can be executed by the query engine (see: DataSourceHelper.applyQuery(com.google.visualization.datasource.query.Query, com.google.visualization.datasource.datatable.DataTable, com.ibm.icu.util.ULocale)). It can be split in 2 Query objects based on the Capabilities value (see: DataSourceHelper.splitQuery(com.google.visualization.datasource.query.Query, com.google.visualization.datasource.Capabilities)). Note on errors: Since this class handles a user generated query, all errors (of type INVALID_QUERY) should provide a descriptive error message for both the user.

Author:

Itai R., Yonatan B.Y.

Field Summary

protected QuerySelection

selection The required selection.

Constructor Summary

Query()
Constructs a new, empty, query.

Method Summary

void	copyFrom(Query query) Copies all information from the given query to this query.
void	copyRowLimit(Query originalQuery) Sets the max number of rows to return to the caller, based on another query.
void	copyRowOffset(Query originalQuery) Sets the number of rows to skip, based on another query.
boolean	equals(java.lang.Object obj)
java.util.Set<AggregationColumn>	getAllAggregations() Returns all aggregation columns used in all parts of this query.
java.util.Set<java.lang.String>	getAllColumnIds() Returns all simple column IDs in use in all parts of the query.
java.util.Set<ScalarFunctionColumn>	getAllScalarFunctionsColumns() Returns all scalar function columns in this query.
QueryFilter	getFilter() Returns the required filter of this query.
QueryGroup	getGroup() Returns the required group of the query result.
QueryLabels	getLabels() Returns the query labels.
QueryOptions	getOptions() Returns the options for this query.
QueryPivot	getPivot() Returns the required pivot of the query result.
int	getRowLimit() Returns the maximum number of rows to return to the caller.
int	getRowOffset() Returns the number of rows that should be removed from the beginning of the data table.
QuerySelection	getSelection() Returns the required selection of the query result.
QuerySort	getSort() Returns the required sort of the query result.
QueryFormat	getUserFormatOptions() Returns the query formatting options.
boolean	hasFilter() Returns whether or not this query has a filter defined.
boolean	hasGroup() Returns true if the query has a group-by section.
int	hashCode()
boolean	hasLabels() Returns true if this query has labels defined.
boolean	hasOptions() Returns true if this query has any nondefault options set.
boolean	hasPivot() Returns true if the query has a pivot-by section.
boolean	hasRowLimit() Returns true if this query has a row limit set.
boolean	hasRowOffset() Returns true if this query has a row offset set.
boolean	hasSelection() Returns true if there is a non-trivial selection, i.e.
boolean	hasSort() Returns true if the query has a non empty sort-by section.
boolean	hasUserFormatOptions() Returns true if this query has user format options defined.
boolean	isEmpty() Returns true if the query is empty, i.e.
void	setFilter(QueryFilter filter) Set the required filter of this query.
void	setGroup(QueryGroup group) Sets the required group of the query result.
void	setLabels(QueryLabels labels) Sets the query labels.
void	setOptions(QueryOptions options) Sets the required options for this query.
void	setPivot(QueryPivot pivot) Sets the required pivot of the query result.
void	setRowLimit(int rowLimit) Sets the max number of rows to return to the caller.
void	setRowOffset(int rowOffset) Sets the number of rows that should be removed from the beginning of the data table.
void	setSelection(QuerySelection selection) Set the required selection of the query result.
void	setSort(QuerySort sort) Set the required sort of the query result.
void	setUserFormatOptions(QueryFormat userFormatOptions) Sets the user formatting options map.
java.lang.String	toQueryString() Returns a string that when fed to the query parser will yield an identical Query.
void	validate() Validates the query.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

selection

protected QuerySelection selection

The required selection. If the selection is null, or is empty, the original selection that was defined in the report is used.

Constructor Detail

Query

public Query()

Constructs a new, empty, query.

Method Detail

setSort

public void setSort(QuerySort sort)

Set the required sort of the query result.

Parameters:

sort - The required sort of the query result.

getSort

public QuerySort getSort()

Returns the required sort of the query result.

Returns:

The required sort of the query result.

hasSort

public boolean hasSort()

Returns true if the query has a non empty sort-by section.

Returns:

True if the query has a non empty sort-by section.

setSelection

public void setSelection(QuerySelection selection)

Set the required selection of the query result.

Parameters:

selection - The required selection of the query result.

getSelection

public QuerySelection getSelection()

Returns the required selection of the query result.

Returns:

The required selection of the query result.

hasSelection

public boolean hasSelection()

Returns true if there is a non-trivial selection, i.e. if not all columns should be selected.

Returns:

True if there is a non-trivial selection.

setFilter

public void setFilter(QueryFilter filter)

Set the required filter of this query.

Parameters:

filter - The required filter of this query.

getFilter

public QueryFilter getFilter()

Returns the required filter of this query.

Returns:

The required filter of this query.

hasFilter

public boolean hasFilter()

Returns whether or not this query has a filter defined.

Returns:

true if this query has a filter defined.

setGroup

public void setGroup(QueryGroup group)

Sets the required group of the query result.

Parameters:

group - The required group of the query result.

setPivot

public void setPivot(QueryPivot pivot)

Sets the required pivot of the query result.

Parameters:

pivot - The required pivot of the query result.

getGroup

public QueryGroup getGroup()

Returns the required group of the query result.

Returns:

The required group of the query result.

hasGroup

public boolean hasGroup()

Returns true if the query has a group-by section.

Returns:

True if the query has a group-by section.

getPivot

public QueryPivot getPivot()

Returns the required pivot of the query result.

Returns:

The required pivot of the query result.

hasPivot

public boolean hasPivot()

Returns true if the query has a pivot-by section.

Returns:

True if the query has a pivot-by section.

getRowLimit

public int getRowLimit()

Returns the maximum number of rows to return to the caller. If the caller specified this parameter, and the data table returned from the data source contains more than this number of rows, then the result is truncated, and the query result contains a warning with this reason. If this value is set to -1 it is just ignored, but this can only be done internally.

Returns:

The maximum number of rows to return to the caller.

setRowLimit

public void setRowLimit(int rowLimit)
                 throws InvalidQueryException

Sets the max number of rows to return to the caller. If the caller specified this parameter, and the data table returned from the data source contains more than this number of rows, then the result is truncated, and the query result contains a warning with this reason. By default, this is set to -1, which means that no limit is requested. If there is is an attempt to set the limit value to any negative number smaller than -1 (which means no limit), then an InvalidQueryException is thrown.

Parameters:

rowLimit - The max number of rows to return.

Throws:

InvalidQueryException - Thrown if an invalid value is specified.

copyRowLimit

public void copyRowLimit(Query originalQuery)

Sets the max number of rows to return to the caller, based on another query.

Parameters:

originalQuery - The query from which the row limit should be taken.

hasRowLimit

public boolean hasRowLimit()

Returns true if this query has a row limit set. A value of -1 means no limit so in case of -1 this function returns true.

Returns:

True if this query has a row limit set.

getRowOffset

public int getRowOffset()

Returns the number of rows that should be removed from the beginning of the data table. Together with the row limit parameter, this enables pagination. The default value is 0, (skip 0 rows) - which means to start from the first row.

Returns:

The number of rows to skip from the beginning of the table.

setRowOffset

public void setRowOffset(int rowOffset)
                  throws InvalidQueryException

Sets the number of rows that should be removed from the beginning of the data table. Together with the row limit parameter, this enables pagination. The default value is 0, (skip 0 rows) - which means to start from the first row. If there is is an attempt to set the offset value to any negative number, then an InvalidQueryException is thrown.

Parameters:

rowOffset - The number of rows to skip from the beginning of the table.

Throws:

InvalidQueryException - Thrown if an invalid value is specified.

copyRowOffset

public void copyRowOffset(Query originalQuery)

Sets the number of rows to skip, based on another query.

Parameters:

originalQuery - The query from which the row offset should be taken.

hasRowOffset

public boolean hasRowOffset()

Returns true if this query has a row offset set. A value of 0 means no offset so in case of 0 this function returns true.

Returns:

True if this query has a row offset set.

getUserFormatOptions

public QueryFormat getUserFormatOptions()

Returns the query formatting options.

Returns:

The query formatting options.

setUserFormatOptions

public void setUserFormatOptions(QueryFormat userFormatOptions)

Sets the user formatting options map.

Parameters:

userFormatOptions - A map of patterns to column IDs.

hasUserFormatOptions

public boolean hasUserFormatOptions()

Returns true if this query has user format options defined.

Returns:

True if this query has user format options defined.

getLabels

public QueryLabels getLabels()

Returns the query labels.

Returns:

The query labels.

setLabels

public void setLabels(QueryLabels labels)

Sets the query labels.

Parameters:

labels - A map of labels to column IDs.

hasLabels

public boolean hasLabels()

Returns true if this query has labels defined.

Returns:

True if this query has labels defined.

getOptions

public QueryOptions getOptions()

Returns the options for this query.

Returns:

The options for this query.

setOptions

public void setOptions(QueryOptions options)

Sets the required options for this query.

Parameters:

options - The required options.

hasOptions

public boolean hasOptions()

Returns true if this query has any nondefault options set.

Returns:

True if this query has any nondefault options set.

isEmpty

public boolean isEmpty()

Returns true if the query is empty, i.e. has no clauses or all the clauses are empty.

Returns:

true if the query is empty.

copyFrom

public void copyFrom(Query query)

Copies all information from the given query to this query.

Parameters:

query - The query to copy from.

validate

public void validate()
              throws InvalidQueryException

Validates the query. Runs a sanity check on the query, verifies that there are no duplicates, and that the query follows a basic set of rules required for its execution. Specifically, verifies the following: - There are no duplicate columns in the clauses. - No column appears both as a selection and as an aggregation. - When aggregation is used, checks that all selected columns are valid (a column is valid if it is either grouped-by, or is a scalar function column the arguments of which are all valid columns). - No column is both grouped-by, and aggregated in, the select clause. - No column both appears as pivot, and aggregated in, the select clause. - No grouping/pivoting is used when there is no aggregation in the select clause. - If aggregation is used in the select clause, no column is ordered-by that is not in the select clause. - No column appears both as a group-by and a pivot. - If pivoting is used, the order by clause does not contain aggregation columns. - The order-by clause does not contain aggregation columns that were not defined in the select clause.

Throws:

InvalidQueryException

getAllColumnIds

public java.util.Set<java.lang.String> getAllColumnIds()

Returns all simple column IDs in use in all parts of the query.

Returns:

All simple column IDs in use in all parts of the query.

getAllAggregations

public java.util.Set<AggregationColumn> getAllAggregations()

Returns all aggregation columns used in all parts of this query.

Returns:

All aggregation columns used in all parts of this query.

getAllScalarFunctionsColumns

public java.util.Set<ScalarFunctionColumn> getAllScalarFunctionsColumns()

Returns all scalar function columns in this query.

Returns:

All scalar function columns in this query.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

toQueryString

public java.lang.String toQueryString()

Returns a string that when fed to the query parser will yield an identical Query. Used mainly for debugging purposes.

Returns:

The query string.