ibis::table Class Reference
[FastBit IBIS main interface objects.]

The abstract table class. More...

#include <table.h>

Inheritance diagram for ibis::table:

List of all members.

Public Types
typedef std::map< const char *, ibis::TYPE_T, ibis::lessi >	namesTypes
	An associate array of names and types.
typedef std::vector< const char * >	stringList
	A list of strings.
typedef std::vector< ibis::TYPE_T >	typeList
	A list of data types.
Public Member Functions
virtual int	addPartition (const char *dir)
	Add data partition defined in the named directory.
virtual stringList	columnNames () const =0
	Return column names.
virtual typeList	columnTypes () const =0
	Return data types.
virtual cursor *	createCursor () const =0
	Create a cursor object to perform row-wise data access.
virtual void	describe (std::ostream &) const =0
	Print a description of the table to the specified output stream.
virtual const char *	description () const
	Free text description.
virtual int	dump (std::ostream &out, uint64_t nr) const =0
	Print the first nr rows.
virtual int	dump (std::ostream &out, const char *del=", ") const =0
	Print the values in ASCII form to the specified output stream.
virtual void	estimate (const char *cond, uint64_t &nmin, uint64_t &nmax) const =0
	Estimate the number of rows satisfying the selection conditions.
virtual table *	groupby (const char *) const
	Perform group-by operation.
virtual table *	groupby (const stringList &) const =0
	Perform aggregate functions on the current table.
virtual const char *	name () const
	Name of the table object.
virtual size_t	nColumns () const =0
virtual uint64_t	nRows () const =0
virtual void	orderby (const char *)
	Reorder the rows. The column names are separated by comma.
virtual void	orderby (const stringList &)=0
	Reorder the rows.
virtual void	reverseRows ()=0
	Reverse the order of the rows.
virtual table *	select (const char *sel, const char *cond) const =0
	Given a set of column names and a set of selection conditions, compute another table that represents the selected values.
virtual	~table ()
	Destructor.
virtual int	buildIndex (const char *colname, const char *option=0)=0
	Create the index for the named column.
virtual int	buildIndexes (const char *options=0)=0
	Create indexes for every column of the table.
virtual void	indexSpec (const char *opt, const char *colname=0)=0
	Replace the current indexing option.
virtual const char *	indexSpec (const char *colname=0) const =0
	Retrieve the current indexing option.
virtual int64_t	getColumnAsBytes (const char *cname, char *vals) const =0
	Retrieve all values of the named column.
virtual int64_t	getColumnAsDoubles (const char *cname, double *vals) const =0
	Retrieve all values of the named column.
virtual int64_t	getColumnAsFloats (const char *cname, float *vals) const =0
	Retrieve all values of the named column.
virtual int64_t	getColumnAsInts (const char *cname, int32_t *vals) const =0
	Retrieve all values of the named column.
virtual int64_t	getColumnAsLongs (const char *cname, int64_t *vals) const =0
	Retrieve all values of the named column.
virtual int64_t	getColumnAsShorts (const char *cname, int16_t *vals) const =0
	Retrieve all values of the named column.
virtual int64_t	getColumnAsStrings (const char *cname, std::vector< std::string > &vals) const =0
	Retrieve the null-terminated strings as a vector of std::string objects.
virtual int64_t	getColumnAsUBytes (const char *cname, unsigned char *vals) const =0
	Retrieve all values of the named column.
virtual int64_t	getColumnAsUInts (const char *cname, uint32_t *vals) const =0
	Retrieve all values of the named column.
virtual int64_t	getColumnAsULongs (const char *cname, uint64_t *vals) const =0
	Retrieve all values of the named column.
virtual int64_t	getColumnAsUShorts (const char *cname, uint16_t *vals) const =0
	Retrieve all values of the named column.
virtual long	getHistogram (const char *constraints, const char *cname, double begin, double end, double stride, std::vector< size_t > &counts) const =0
virtual long	getHistogram2D (const char *constraints, const char *cname1, double begin1, double end1, double stride1, const char *cname2, double begin2, double end2, double stride2, std::vector< size_t > &counts) const =0
	Compute a two-dimension histogram on columns cname1 and cname2.
virtual long	getHistogram3D (const char *constraints, const char *cname1, double begin1, double end1, double stride1, const char *cname2, double begin2, double end2, double stride2, const char *cname3, double begin3, double end3, double stride3, std::vector< size_t > &counts) const =0
	Compute a three-dimensional histogram on the named columns.
Static Public Member Functions
static ibis::table *	create (const char *dir1, const char *dir2)
	Create a table object from a pair of data directories.
static ibis::table *	create (const char *dir)
	Create a table object from the specified data directory.
Protected Member Functions
void	parseNames (char *in, stringList &out) const
	Parse a string into a set of names.
	table (const char *na, const char *de)
	Copy constructor.
	table ()
	The default constructor.
Protected Attributes
std::string	desc_
	Description of the table.
std::string	name_
	Name of the table.
Classes
class	cursor
	Cursor class for row-wise data accesses. More...
struct	row
	A simple struct for storing a row of a table. More...

---

Detailed Description

The abstract table class.

This is an abstract base class that defines the common operations on a data table. Conceptually, data records in a table is organized into rows and columns. A query on a table produces a filtered version of the table. In many database systems this is known as a view on a table. All data tables and views are logically treated as specialization of this ibis::table class.

---

Member Function Documentation

virtual int ibis::table::addPartition

(

const char *

dir

)

[inline, virtual]

Add data partition defined in the named directory.

It returns 0 to indicate success, a negative number to indicate failure, and a positive number to indicate some adversary conditions.

Note:

On systems that supports readdir and friend (all unix-type of systems do), it also recursively traverses all subdirectories.

Reimplemented in ibis::mensa.

virtual int ibis::table::buildIndex	(	const char *	colname,
		const char *	option = 0
	)			[pure virtual]

Create the index for the named column.

The existing index will be replaced. If an indexing option is not specified, it will use the internally recorded option for the named column or the table containing the column.

Note:

Unless any there is a specific instruction to not index a column, the querying functions will automatically build indices as necessary. However, as building an index is relatively expensive process, building an index on a column is on average about four or five times as expensive as reading the column from disk, this function is provided so that it is possible to build indexes beforehand.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int ibis::table::buildIndexes

(

const char *

options = 0

)

[pure virtual]

Create indexes for every column of the table.

Existing indexes will be replaced. If an indexing option is not specified, the internally recorded options will be used.

See also:

buildIndex

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

ibis::table * ibis::table::create	(	const char *	dir1,
		const char *	dir2
	)			[static]

Create a table object from a pair of data directories.

The intention of maintaining two sets of data files is to continue processing queries using one set while accepting new data records with the other. However, such functionality is not currently implemented!

ibis::table * ibis::table::create

(

const char *

dir

)

[static]

Create a table object from the specified data directory.

Note:

If the incoming directory name is nil or an empty string, it attempts to use the directories specified in the configuration files.

virtual int ibis::table::dump	(	std::ostream &	out,
		const char *	del = ", "
	)			const [pure virtual]

Print the values in ASCII form to the specified output stream.

The default delimiter is coma (","), which produces Comma-Separated-Values (CSV).

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual void ibis::table::estimate	(	const char *	cond,
		uint64_t &	nmin,
		uint64_t &	nmax
	)			const [pure virtual]

Estimate the number of rows satisfying the selection conditions.

The number of rows is between [nmin, nmax].

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int64_t ibis::table::getColumnAsBytes	(	const char *	cname,
		char *	vals
	)			const [pure virtual]

Retrieve all values of the named column.

The member functions of this class only support access to whole column at a time. Use table::cursor class for row-wise accesses. For fixed-width data types, the raw pointers are used to point to the values to be returned. In these cases, the caller is responsible for allocating enough storage for the values to be returned.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int64_t ibis::table::getColumnAsDoubles	(	const char *	cname,
		double *	vals
	)			const [pure virtual]

Retrieve all values of the named column.

The member functions of this class only support access to whole column at a time. Use table::cursor class for row-wise accesses. For fixed-width data types, the raw pointers are used to point to the values to be returned. In these cases, the caller is responsible for allocating enough storage for the values to be returned.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int64_t ibis::table::getColumnAsFloats	(	const char *	cname,
		float *	vals
	)			const [pure virtual]

Retrieve all values of the named column.

The member functions of this class only support access to whole column at a time. Use table::cursor class for row-wise accesses. For fixed-width data types, the raw pointers are used to point to the values to be returned. In these cases, the caller is responsible for allocating enough storage for the values to be returned.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int64_t ibis::table::getColumnAsInts	(	const char *	cname,
		int32_t *	vals
	)			const [pure virtual]

Retrieve all values of the named column.

The member functions of this class only support access to whole column at a time. Use table::cursor class for row-wise accesses. For fixed-width data types, the raw pointers are used to point to the values to be returned. In these cases, the caller is responsible for allocating enough storage for the values to be returned.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int64_t ibis::table::getColumnAsLongs	(	const char *	cname,
		int64_t *	vals
	)			const [pure virtual]

Retrieve all values of the named column.

The member functions of this class only support access to whole column at a time. Use table::cursor class for row-wise accesses. For fixed-width data types, the raw pointers are used to point to the values to be returned. In these cases, the caller is responsible for allocating enough storage for the values to be returned.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int64_t ibis::table::getColumnAsShorts	(	const char *	cname,
		int16_t *	vals
	)			const [pure virtual]

Retrieve all values of the named column.

The member functions of this class only support access to whole column at a time. Use table::cursor class for row-wise accesses. For fixed-width data types, the raw pointers are used to point to the values to be returned. In these cases, the caller is responsible for allocating enough storage for the values to be returned.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int64_t ibis::table::getColumnAsStrings	(	const char *	cname,
		std::vector< std::string > &	vals
	)			const [pure virtual]

Retrieve the null-terminated strings as a vector of std::string objects.

Both ibis::CATEGORY and ibis::TEXT types can be retrieved using this function.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int64_t ibis::table::getColumnAsUBytes	(	const char *	cname,
		unsigned char *	vals
	)			const [pure virtual]

Retrieve all values of the named column.

The member functions of this class only support access to whole column at a time. Use table::cursor class for row-wise accesses. For fixed-width data types, the raw pointers are used to point to the values to be returned. In these cases, the caller is responsible for allocating enough storage for the values to be returned.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int64_t ibis::table::getColumnAsUInts	(	const char *	cname,
		uint32_t *	vals
	)			const [pure virtual]

Retrieve all values of the named column.

The member functions of this class only support access to whole column at a time. Use table::cursor class for row-wise accesses. For fixed-width data types, the raw pointers are used to point to the values to be returned. In these cases, the caller is responsible for allocating enough storage for the values to be returned.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int64_t ibis::table::getColumnAsULongs	(	const char *	cname,
		uint64_t *	vals
	)			const [pure virtual]

Retrieve all values of the named column.

The member functions of this class only support access to whole column at a time. Use table::cursor class for row-wise accesses. For fixed-width data types, the raw pointers are used to point to the values to be returned. In these cases, the caller is responsible for allocating enough storage for the values to be returned.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual int64_t ibis::table::getColumnAsUShorts	(	const char *	cname,
		uint16_t *	vals
	)			const [pure virtual]

Retrieve all values of the named column.

The member functions of this class only support access to whole column at a time. Use table::cursor class for row-wise accesses. For fixed-width data types, the raw pointers are used to point to the values to be returned. In these cases, the caller is responsible for allocating enough storage for the values to be returned.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual long ibis::table::getHistogram	(	const char *	constraints,
		const char *	cname,
		double	begin,
		double	end,
		double	stride,
		std::vector< size_t > &	counts
	)			const [pure virtual]

Compute the histogram of the named column. This version uses the user specified bins:

 [begin, begin+stride) [begin+stride, begin+2*stride) ....

A record is placed in bin

 (x - begin) / stride, 

where the first bin is bin 0. The total number of bins is

 (end - begin) / stride. 

Note:

Records (rows) outside of the range [begin, end] are not counted.

Non-positive stride is considered as an error.

If end is less than begin, an empty array counts is returned along with return value 0.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual long ibis::table::getHistogram2D	(	const char *	constraints,
		const char *	cname1,
		double	begin1,
		double	end1,
		double	stride1,
		const char *	cname2,
		double	begin2,
		double	end2,
		double	stride2,
		std::vector< size_t > &	counts
	)			const [pure virtual]

Compute a two-dimension histogram on columns cname1 and cname2.

The bins along each dimension are defined the same way as in function getHistogram. The array counts stores the two-dimensional bins with the first dimension as the slow varying dimension following C convention for ordering multi-dimensional arrays.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual long ibis::table::getHistogram3D	(	const char *	constraints,
		const char *	cname1,
		double	begin1,
		double	end1,
		double	stride1,
		const char *	cname2,
		double	begin2,
		double	end2,
		double	stride2,
		const char *	cname3,
		double	begin3,
		double	end3,
		double	stride3,
		std::vector< size_t > &	counts
	)			const [pure virtual]

Compute a three-dimensional histogram on the named columns.

The triplets <begin, end, stride> are used the same ways in getHistogram and getHistogram2D. The three dimensional bins are linearized in counts with the first being the slowest varying dimension and the third being the fastest varying dimension following the C convention for ordering multi-dimensional arrays.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

ibis::table * ibis::table::groupby

(

const char *

str

)

const [inline, virtual]

Perform group-by operation.

The column names and operations are separated by comma.

Reimplemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

References groupby(), and parseNames().

virtual table* ibis::table::groupby

(

const stringList &

)

const [pure virtual]

Perform aggregate functions on the current table.

It produces a new table. The list of strings passed to this function are interpreted as a set of names followed by a set of functions. Currently, only functions COUNT, AVG, MIN, MAX, and SUM are supported, and the functions can only accept a column name as arguments.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

Referenced by groupby(), and ibis::bord::groupby().

virtual void ibis::table::indexSpec	(	const char *	opt,
		const char *	colname = 0
	)			[pure virtual]

Replace the current indexing option.

If no column name is specified, it resets the indexing option for the table.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual const char* ibis::table::indexSpec

(

const char *

colname = 0

)

const [pure virtual]

Retrieve the current indexing option.

If no column name is specified, it retrieve the indexing option for the table.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

virtual void ibis::table::orderby

(

const stringList &

)

[pure virtual]

Reorder the rows.

Sort the rows in ascending order of the columns specified in the list of column names. This function is not designated const because though it does not change the content in SQL logic, but it may change internal representations.

Note:

If an empty list is passed to this function, it will reorder rows using all columns with the column having the smallest number of distinct values first.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

Referenced by orderby(), ibis::mensa::orderby(), and ibis::bord::orderby().

void ibis::table::parseNames	(	char *	in,
		stringList &	out
	)			const [protected]

Parse a string into a set of names.

Some bytes may be turned into 0 to mark the end of names or functions.

References ibis::gVerbose.

Referenced by groupby(), and orderby().

virtual table* ibis::table::select	(	const char *	sel,
		const char *	cond
	)			const [pure virtual]

Given a set of column names and a set of selection conditions, compute another table that represents the selected values.

Implemented in ibis::bord, ibis::mensa, ibis::tabula, and ibis::tabele.

---

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

• table.h
• mensa.cpp