The row predicate to constrain the number of rows to return. More...

#include <QCassandraRowPredicate.h>

Inheritance diagram for QtCassandra::QCassandraRowPredicate:

Collaboration diagram for QtCassandra::QCassandraRowPredicate:

Public Member Functions
	QCassandraRowPredicate ()
	Initializes a row range predicate.
QSharedPointer < QCassandraColumnPredicate >	columnPredicate () const
	Retrieve a pointer to the column predicate.
int32_t	count () const
	Return the maximum number of rows that will be returned.
const QByteArray &	endRowKey () const
	Retrieve a copy of the end row key.
QString	endRowName () const
	Retrieve the end row name.
void	setColumnPredicate (QSharedPointer< QCassandraColumnPredicate > column_predicate)
	Set a new column predicate.
void	setCount (int32_t count=100)
	Change the number of rows to return.
void	setEndRowKey (const QByteArray &row_key)
	Define the last row key.
void	setEndRowName (const QString &row_name)
	Set the end row name.
void	setStartRowKey (const QByteArray &row_key)
	Set the start row key.
void	setStartRowName (const QString &row_name)
	Set the name of the start row.
void	setWrap (bool wrap=true)
	Define whether the specified keys wrap.
const QByteArray &	startRowKey () const
	Retrieve a copy of the start row key.
QString	startRowName () const
	Retrieve a copy of the start row name.
bool	wrap () const
	Return whether the row predicate is wrapped or not.
Private Member Functions
virtual void	toPredicate (void *data) const
	Transform to a Thrift predicate.
Private Attributes
QSharedPointer < QCassandraColumnPredicate >	f_column_predicate
	A copy of the column predicate.
cassandra_count_t	f_count
	The number of rows you want to find.
QByteArray	f_end_row
	The key of the last row to read from the Cassandra server.
QByteArray	f_start_row
	The key of the start row to read from the Cassandra server.
controlled_vars::zbool_t	f_wrap
	Whether the row search should wrap.
Friends
class	QCassandraPrivate

Detailed Description

This function defines a row constrain with lower and upper bounds. The QCassandraRowPredicate also includes a QCassandraColumnPredicate to constrain the columns returned by the QCassandraTable::readRows() function.

The row predicate uses a start and end row key to constrain the search. It also includes a limit to the number of rows that can be returned at once.

In order to read all the rows of a table one wants:

Set the start row to the null value (see QCassandraValue::setNullValue().)

Set the end row to the null value. The end row does not change until the entire set was read.

Set the wrap mode to true so the start row is exclusive and the end row is inclusive. The wrapping in itself is not used in this case but the exclusive behavior of the first row is important.

Set the limit parameter to the number of rows you can read at once (i.e. limit it to whatever makes sense in your application.)

After the first read returned and if the number of rows returned was equal to the limit, then put the key of the last returned row in the start parameter and call the readRows() function again.

Note that the last readRows() may return 0 as the number of rows read.

 QCassandraRowPredicate rowp;
 rowp.setStartRowName("");
 rowp.setEndRowName("");
 rowp.setLimit(100); // 100 is the default
 rowp.setWrap(); // change to wrapping mode
 for(;;) {
   // we need to clear the cache or we cannot distinguish between
   // existing and new rows... (we may want to return a list of the
   // matching rows in the readRows() function.)
   table.clearCache();
   int c = table.readRows(rowp);
   if(c == 0) {
     break;
   }
   // handle the result
   const QCassandraRows& r(table.rows());
   ...
   if(c < 100) { // your setLimit() parameter
     break;
   }
   rowp.setStartRowName(last_row.rowName());
 }

Definition at line 51 of file QCassandraRowPredicate.h.

Constructor & Destructor Documentation

QtCassandra::QCassandraRowPredicate::QCassandraRowPredicate ( )

This function initializes a row range predicate.

By default, all the rows of a table are returned (limited to the count parameter.) If you add a start row name and a end row name, then only the rows defined between those (boundaries included unless you set wrap to true) will be returned.

Warning:: The default is to read ALL the rows and ALL the columns of a table. This may mean a lot of data. 100 rows x 100 columns with each column using an average of 1,000 bytes is 10Mb to transmit over the wire. Think about it twice because if you make use of a single column and that were to be an integer (i.e. 4 bytes) you'd instead read 400 bytes.

The constructor sets the number of rows to return to 100 by default.

Definition at line 170 of file QCassandraRowPredicate.cpp.

Member Function Documentation

QSharedPointer< QCassandraColumnPredicate > QtCassandra::QCassandraRowPredicate::columnPredicate ( ) const

This function returns a shared pointer to the column predicate of the row predicate. This pointer can be used to modify the existing predicate.

The best is for you to allocate your own predicate and set it using the setColumnPredicate() function.

This function is also used to retrieve the column predicate and transform it in a SlicePredicate.

Returns:: A shared pointer to the column predicate attached to this row predicate.

See also:: setColumnPredicate()

Definition at line 381 of file QCassandraRowPredicate.cpp.

References f_column_predicate.

Referenced by QtCassandra::QCassandraPrivate::getRowSlices().

int32_t QtCassandra::QCassandraRowPredicate::count ( ) const

This function retrieves the maximum number of rows that a row slice request will return. By default it is set to 100.

Returns:: The maximum number of rows to be returned by requests.

See also:: setCount()

Definition at line 306 of file QCassandraRowPredicate.cpp.

References f_count.

Referenced by setCount().

const QByteArray & QtCassandra::QCassandraRowPredicate::endRowKey ( ) const

This function returns a constant reference to the current end row key.

Returns:: A constant reference key to the end row key.

Definition at line 275 of file QCassandraRowPredicate.cpp.

References f_end_row.

QString QtCassandra::QCassandraRowPredicate::endRowName ( ) const

This function retrieves the row key in the form of a row name. The name is the UTF-8 string that you set using setRowName().

If you used the setRowKey() and the name was not valid UTF-8, then this function will throw an eror.

Returns:: The row string.

Definition at line 248 of file QCassandraRowPredicate.cpp.

References f_end_row.

void QtCassandra::QCassandraRowPredicate::setColumnPredicate ( QSharedPointer< QCassandraColumnPredicate > column_predicate )

As the rows are being read, the Cassandra server also reads the columns. Which columns should be read can be determined by the column predicate. By default, the column predicate is set to "read all the columns."

Note that we save a shared pointer to your column predicate. This means you need to allocate it. You may also want to retrieve a copy of the object internal column predicate with the columnPredicate() function and directly modify that copy (assuming you don't want to use the Name or Range specilized column predicate.)

Parameters:

[in] column_predicate A column predicate instance.

See also:: columnPredicate()

Definition at line 402 of file QCassandraRowPredicate.cpp.

References f_column_predicate.

Referenced by QtCassandra::QCassandraTable::exists().

void QtCassandra::QCassandraRowPredicate::setCount ( int32_t count = 100 )

This function defines the number of rows a table request will return when querying for a slice.

The default is 100.

Keep in mind that the entire set of rows will be returned in a single message, thus returning a very large number can fill up your memory quickly.

Parameters:

[in] count The new number of rows to return when querying for a slice.

See also:: count()

Definition at line 326 of file QCassandraRowPredicate.cpp.

References count(), and f_count.

void QtCassandra::QCassandraRowPredicate::setEndRowKey ( const QByteArray & row_key )

This function sets the last key you're interested in. It can safely be set to an empty key to not bound the last key.

Parameters:

[in] row_key The binary row key we stop searching.

See also:: endRowKey()

Definition at line 289 of file QCassandraRowPredicate.cpp.

References f_end_row.

Referenced by QtCassandra::QCassandraTable::exists(), and setEndRowName().

void QtCassandra::QCassandraRowPredicate::setEndRowName ( const QString & row_name )

This function defines the end row key using the UTF-8 string of the specified row name.

Note that the row that matches this key is returned (i.e. the boundary is inclusive.)

Parameters:

[in] row_name The name of the end row.

Definition at line 263 of file QCassandraRowPredicate.cpp.

References setEndRowKey().

void QtCassandra::QCassandraRowPredicate::setStartRowKey ( const QByteArray & row_key )

This function sets the start row key of this row predicate.

Parameters:

[in] row_key The new start row key.

See also:: setStartRowName()

Definition at line 230 of file QCassandraRowPredicate.cpp.

References f_start_row.

Referenced by QtCassandra::QCassandraTable::exists(), and setStartRowName().

void QtCassandra::QCassandraRowPredicate::setStartRowName ( const QString & row_name )

This function defines the name of the start row to retrieve. All the rows defined between the start and end row names/keys will be returned by this predicate.

An empty row name can be used to request the very first row to be returned first. The start row is included in the result except if the wrap parameter is set to true.

Parameters:

[in] row_name The name of the row to start with.

See also:: setStartRowKey()

Definition at line 206 of file QCassandraRowPredicate.cpp.

References setStartRowKey().

void QtCassandra::QCassandraRowPredicate::setWrap ( bool wrap = true )

By default, the specified keys are inclusive and do not wrap. This means a key range from J to L will return all the rows that are defined between J and L inclusive. On the other hand, the range L to J will return an empty set.

When you set the wrap flag to true, then the range J to L will return all the keys except the one that match J. And the range L to J will return the set of keys after L and before J, J included.

Parameters:

[in] wrap true to get the keys to wrap.

Definition at line 360 of file QCassandraRowPredicate.cpp.

References f_wrap, and wrap().

const QByteArray & QtCassandra::QCassandraRowPredicate::startRowKey ( ) const

This function returns a constant reference to the start row key.

Returns:: A constant reference to the start row key.

Definition at line 217 of file QCassandraRowPredicate.cpp.

References f_start_row.

QString QtCassandra::QCassandraRowPredicate::startRowName ( ) const

This function returns a copy of the start row name. If the start row key was defined with binary that is not UTF-8 compatible, this function will raise an exception while converting the buffer to UTF-8.

Returns:: The start row name.

Definition at line 187 of file QCassandraRowPredicate.cpp.

References f_start_row.

void QtCassandra::QCassandraRowPredicate::toPredicate ( void * data ) const [private, virtual]

This function is used to transform a QCassandraColumnRangePredicate object to a Cassandra SlicePredicate structure.

The input parameter is set to void * because the function is defined in the public header file and thus cannot directly make use of the Thrift type definitions.

Parameters:

[in] data The pointer to the SlicePredicate to setup.

Definition at line 418 of file QCassandraRowPredicate.cpp.

References f_count, f_end_row, f_start_row, and f_wrap.

Referenced by QtCassandra::QCassandraPrivate::getRowSlices().

bool QtCassandra::QCassandraRowPredicate::wrap ( ) const

This function returns the current status of the wrap flag. If true then it wraps which means it has slightly different semantics and it gives you a way to navigate through all the rows. See the setWrap() function for more info.

Returns:: The current status of the wrap flag.

See also:: setWrap()

Definition at line 342 of file QCassandraRowPredicate.cpp.

References f_wrap.

Referenced by setWrap().

Friends And Related Function Documentation

friend class QCassandraPrivate [friend]

Definition at line 78 of file QCassandraRowPredicate.h.

Member Data Documentation

QtCassandra::QCassandraRowPredicate::f_column_predicate [private]

This is a column predicate to define the list of columns that you want to retrieve from a readRows() call.

See also:: setColumnPredicate()

Definition at line 84 of file QCassandraRowPredicate.h.

Referenced by columnPredicate(), and setColumnPredicate().

QtCassandra::QCassandraRowPredicate::f_count [private]

The search of rows can be limited by this count value. If you want to search all the rows with multiple searches, make sure to set f_wrap to true (setWrap()) and copy the row key of the last row found to the start bound.

Definition at line 82 of file QCassandraRowPredicate.h.

Referenced by count(), setCount(), and toPredicate().

QtCassandra::QCassandraRowPredicate::f_end_row [private]

This value defines the end row that will be returned. The search is always inclusive of the end_row parameter.

Definition at line 81 of file QCassandraRowPredicate.h.

Referenced by endRowKey(), endRowName(), setEndRowKey(), and toPredicate().

QtCassandra::QCassandraRowPredicate::f_start_row [private]

This value defines the first row that will be returned. The search is inclusive if the wrap parameter is false. It is exclusive when wrap is true.

The first search can start with an empty key.

Definition at line 80 of file QCassandraRowPredicate.h.

Referenced by setStartRowKey(), startRowKey(), startRowName(), and toPredicate().

QtCassandra::QCassandraRowPredicate::f_wrap [private]

Whether the row search should wrap.

When the wrap flag is true, the start bound is exclusive. In all other cases the bounds are inclusive. Also, if the end bound is larger than the start bound, the predicate returns nothing unless the wrap flag is set to true.

Definition at line 83 of file QCassandraRowPredicate.h.

Referenced by setWrap(), toPredicate(), and wrap().

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

/home/alexis/m2osw/sources/freeware/snapwebsites/libQtCassandra/include/QtCassandra/QCassandraRowPredicate.h
/home/alexis/m2osw/sources/freeware/snapwebsites/libQtCassandra/src/QCassandraRowPredicate.cpp

QtCassandra::QCassandraRowPredicate Class Reference

Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation