ibis::whereClause Class Reference

A representation of the where clause. More...

#include <whereClause.h>

Public Member Functions
void	addConditions (const char *)
	Append a set of conditions to the existing where clause. More...
void	addExpr (const ibis::qExpr *)
	Append a set of conditions to the existing where clause. More...
void	clear () throw ()
	Clear the existing content.
bool	empty () const
	The where clause is considered empty if the expr_ is a nil pointer.
const ibis::qExpr *	getExpr (void) const
	Return a pointer to the root of the expression tree for the where clause. More...
ibis::qExpr *	getExpr (void)
	Return a pointer to the root of the expression tree for the where clause. More...
void	getNullMask (const ibis::part &, ibis::bitvector &) const
const char *	getString (void) const
	Return a pointer to the string form of the where clause.
ibis::qExpr *	operator-> ()
	Member access operator redefined to point to ibis::qExpr.
const ibis::qExpr *	operator-> () const
	Member access operator redefined to point to const ibis::qExpr.
whereClause &	operator= (const whereClause &)
	Assignment operator.
int	parse (const char *cl)
	Parse a new string.
void	resetString ()
	Regenerate the string version of the query conditions.
void	setExpr (const ibis::qExpr *ex)
	Assign a new set of conditions directly. More...
void	simplify ()
	Simplify the query expression.
void	swap (whereClause &rhs) throw ()
	Swap the contents of two where clauses.
int	verify (const ibis::part &p0, const ibis::selectClause *sel=0) const
	Verify that the names exist in the data partition. More...
	whereClause (const char *cl=0)
	Construct a where clause from a string.
	whereClause (const whereClause &)
	Construct a where clause from another where clause.
	~whereClause ()
	Destructor.

Static Public Member Functions
static int	removeAlias (ibis::qContinuousRange *&, const ibis::column *)
	Create a simple range expression as the replacement of the incoming oldr. More...
static int	verifyExpr (const ibis::qExpr *, const ibis::part &, const ibis::selectClause *)
static int	verifyExpr (ibis::qExpr *&, const ibis::part &, const ibis::selectClause *)
	A function to verify an single query expression. More...

Protected Member Functions
void	amplify (const ibis::part &)
	!< The expression tree. More...

Protected Attributes
std::string	clause_
ibis::qExpr *	expr_
	!< String version of the where clause.

Friends
class	ibis::whereParser

Detailed Description

A representation of the where clause.

It parses a string into an ibis::qExpr object. One may access the functions defined for ibis::qExpr through the operator->.

A where clause is a set of range conditions joined together with logical operators. The supported logical operators are

NOT, AND, OR, XOR, &&, ||.

The supported range conditions are equality conditions, discrete ranges, one-sided range conditions and two-sided range conditions.

• An equality condition is defined by the equal operator and its two operands can be arithematic expressions, column names, numbers or string literals. On string valued columns, FastBit currently only supports equality comparisons. In such a case, the comparison is of the form "column_name = column_value". Internally, when FastBit detect that the type of the column named "column_name" is ibis::CATEGORY or ibis::TEXT, it will interpret the other side as literal string value to be compared. Note that if the left operand of the equality operator is not a known column name, the evaluation function will examine the right operand to see if it is a column name. If the right operand is the name of string-valued column, the left operand will be used as string literal.
• A discrete range is defined by the operator "IN", e.g.,

  column_name IN ( list_of_strings_or_numbers )

  Note unquoted string values must start with an alphabet or a underscore. Strings starting with anything else must be quoted.
• A one-side range condtion can be defined with any of the following operators, <, <=, >, and >=. The two operands of the operator can be any arithmetic expressions, column names or numbers.
• A two-sided range condtion can be defined with two operators selected from <, <=, >, and >=, if their directions much agree. Alternatively, they can be defined with operators "... between ... and ...", where

  A between B and C

  is equivalent to

  B <= A <= C

  In this example, A, B, and C can be arithematic expressions, column names, and numbers.

An arithematic expression may contain operators +, -, *, /, %, ^, and **, as well as common one-argument and two-argument functions defined in the header file math.h. Both operators ^ and ** denote the exponential operation.

Note

Operators & and | are reserved for bitwise logical operations within an arithmetic expression, while && and || are for logical operations between query conditions.

The following operations on text fields are also supported. For the purpose of query composition, they can be tought of as alternative form of discrete ranges.

• Operator LIKE, e.g.,

  column_name LIKE regular_expression

  Note that the regular expression can only contain wild characters % and _ per SQL standard. Internally, this is referred to as pattern matching and treats a string as a single atomic unit of data.

  See also

  ibis::category

• Operator CONTAINS, e.g.,

  column_name CONTAINS literal_word
  column_name CONTAINS ( list_of_literal_words )

  When multiple keywords are given, this operator is meant to look for rows containing all of the given keywords. Internally, this is referred to as keyword matching and treats a string field as a list of words. Typically, the column is of type TEXT and a KEYWORD index has been built on the column. Note that the KEYWORD index could take a user provided parser to extract the keywords.

  See also

  ibis::keywords

  This operator can work with set-valued data, in which case, each row of this column is a set but expressed as a string. The user provides a parser during the construction of the KEYWORD index to make sure the string is parsd into the correct elements of the sets. This expression is used to identify sets with the speicified list of elements.

• Operator NOT NULL The only way to mention NULL values in a query expression is through this operator.

  column_name NOT NULL

  Note that there is no support for NULL as an operator. The way to select only NULL values is through (NOT column_name NOT NULL).

• Time handling functions An integer valued column could be used to store Unix time stamps (i.e., seconds since beginning of 1970), in which case, it might be useful to perform comparison on day of the week or hours of a day in a where clause. To support such operations, four functions are provided.

  – from_unixtime_local(timestamp, "format"): extract a number from the time stamp. The timestamp should be the name of column to be interpreted as Unix time stamps. The format string follows the convention of function strftime from libc. Note that this function actuall uses strftime to extract the information in string form first and then interpret the leading portion of the string as a floating-point number. The tailing portion of the string that could not be interpreted as part of a floating-point number is ignored. If this process results no number at all, for example, strftime prints the first date and time with an alphabet as the first character, then this function returns a NaN (Not-a-number).

  This function assumes the time stamps are in the local time zone.

  Note that the format string must be quoted.

  – from_unixtime_gmt(timestamp, "format"): same functionality as from_unixtime_local, but assumes the time stamps are in time zone GMT/UTC.

  Note that the format string must be quoted.

  – to_unixtime_local("date-time-string", "format"): This function attempts to be the inverse of from_unixtime_local. It is a constant function at this time and only transform one specific time value to unix time stamp. Therefore this is only useful for generating a constant for bounding a unix time stamp.

  – to_unixtime_gmt("date-time-string", "format"): the inverse of from_unixtime_gmt, but only works with a simple time constant.

Member Function Documentation

void ibis::whereClause::addConditions

(

const char *

cl

)

Append a set of conditions to the existing where clause.

The new conditions are joined together with the existing ones with the AND operator.

Referenced by ibis::query::addConditions().

void ibis::whereClause::addExpr

(

const ibis::qExpr *

ex

)

Append a set of conditions to the existing where clause.

The new conditions are joined together with the existing ones with the AND operator.

Note

This object will have a copy of the incomping object.

References ibis::qExpr::dup().

Referenced by ibis::query::addConditions().

void ibis::whereClause::amplify ( const ibis::part &  part0 )

protected

!< The expression tree.

Add conditions implied by self-join conditions.

Note

This name is intentionally vague to discourage its use. It might be completely removed in a later release.

References ibis::math::term::eval(), ibis::qExpr::findRange(), ibis::column::getActualMax(), ibis::column::getActualMin(), ibis::part::getColumn(), ibis::qExpr::getLeft(), ibis::qExpr::getRight(), ibis::qRange::leftBound(), ibis::qRange::restrictRange(), ibis::qRange::rightBound(), and ibis::qExpr::simplify().

const ibis::qExpr* ibis::whereClause::getExpr ( void  ) const

inline

Return a pointer to the root of the expression tree for the where clause.

Note

Functions that modify this object may invalidate the pointer returned by this function.

References expr_.

Referenced by ibis::query::addConditions(), ibis::query::contractQuery(), ibis::query::countHits(), ibis::quaere::create(), ibis::query::estimate(), ibis::query::evaluate(), ibis::query::expandQuery(), ibis::query::getNumHits(), ibis::query::query(), ibis::query::setPartition(), ibis::query::setSelectClause(), ibis::countQuery::setWhereClause(), ibis::query::setWhereClause(), ibis::filter::sift(), ibis::filter::sift1(), ibis::filter::sift1S(), ibis::filter::sift2(), and ibis::filter::sift2S().

ibis::qExpr* ibis::whereClause::getExpr ( void  )

inline

Return a pointer to the root of the expression tree for the where clause.

Note

Functions that modify this object may invalidate the pointer returned by this function.

References expr_.

int ibis::whereClause::removeAlias ( ibis::qContinuousRange *&  oldr, const ibis::column *  col  )

static

Create a simple range expression as the replacement of the incoming oldr.

It replaces the name of the column if the incoming expression uses an alias. It replaces the negative query boundaries with 0 for unsigned integer columns.

References ibis::column::isUnsignedInteger(), ibis::qContinuousRange::leftBound(), ibis::column::name(), and ibis::qContinuousRange::rightBound().

void ibis::whereClause::setExpr ( const ibis::qExpr *  ex )

inline

Assign a new set of conditions directly.

The new set of conditions is copied here.

References ibis::qExpr::dup(), and expr_.

Referenced by ibis::table::select(), ibis::countQuery::setWhereClause(), and ibis::query::setWhereClause().

int ibis::whereClause::verify	(	const ibis::part &	part0,
		const ibis::selectClause *	sel = 0
	)		const

Verify that the names exist in the data partition.

This function also simplifies the arithmetic expression if ibis::term::preserveInputExpression is not set and augment the expressions with implied conditions.

Note

The select clause is provided to make the aliases defined there available to the where clause.

Simplifying the arithmetic expressions typically reduces the time needed for evaluations, but may introduces a different set of round-off erros in the evaluation process than the original expression.

Referenced by ibis::query::addConditions(), ibis::countQuery::setPartition(), ibis::query::setPartition(), ibis::countQuery::setWhereClause(), and ibis::query::setWhereClause().

int ibis::whereClause::verifyExpr ( ibis::qExpr *&  xp0, const ibis::part &  part0, const ibis::selectClause *  sel  )

static

A function to verify an single query expression.

This function checks each variable name specified in the query expression to make sure they all appear as column names of the given data partition. It returns the number of names NOT in the data partition.

It also removes the aliases and simplifies certain query expressions. For example, it converts expressions of the form "string1 = string2" to string lookups when one of the strings is a name of a string-valued column.

References ibis::selectClause::aggExpr(), ibis::selectClause::aggSize(), ibis::CATEGORY, ibis::qContinuousRange::colName(), ibis::qDiscreteRange::colName(), ibis::qAnyString::colName(), ibis::qLike::colName(), ibis::math::term::dup(), ibis::math::variable::dup(), ibis::selectClause::find(), ibis::FLOAT, ibis::selectClause::getAggregator(), ibis::part::getColumn(), ibis::column::getDictionary(), ibis::qExpr::getLeft(), ibis::qExpr::getRight(), ibis::qExpr::getType(), ibis::qDiscreteRange::getValues(), ibis::column::isFloat(), ibis::column::isInteger(), ibis::qContinuousRange::leftBound(), ibis::part::name(), ibis::column::name(), ibis::util::readDouble(), ibis::util::readInt(), ibis::qContinuousRange::rightBound(), ibis::TEXT, ibis::column::type(), ibis::TYPESTRING, ibis::UBYTE, and ibis::UINT.

---

The documentation for this class was generated from the following files:

• whereClause.h
• whereClause.cpp