Page 18 out of 26 total pages


QbKeyDatabaseClass


QbKeyDatabaseClass is derived from the QbDatabaseClass and returns the results of queries and specifies a restriction list of keys. A restriction list is a list of keys used to restrict a query. For example, in a query such as "Find images by artist Picasso with this shade of red" with a text query on "Picasso" returns a set of keys of images associated with Picasso. These keys are then passed to the query engine as a restriction list together with the content-based query specification for "red" to obtain the final, ordered query results.

QbKeyDatabaseClass is a database of keys with distance values. Iterations on this database are required to return items in increasing distance order. Key order is used in the event of a tie.

The IsRanked and SetRanked methods allow you to find or set the ranked state of this database. Even though the database is always sorted by distance, this sort may not be valid.

The GetDistance and SetDistance methods return or set the distance of a value datum. When you use a QbKeyDatabaseClass instance to define a restriction list, use the same distance for all elements or call SetDistance with no distance argument (it defaults to use the distance of -1.0).

The GetNumberOfKeys method returns the number of keys (records) in the database. The return results of a query are always ranked.

The RetrieveMax method retrieves the element with the largest distance in the list. An efficient implementation of this method could greatly enhance query performance.

To pass restriction lists to a query, use the ToQueryString method. This process can be reversed using the FromQueryString method. In the current implementation, the ToQueryString method creates a blank terminated list of key distance pairs, and FromQueryString reinserts these into a QbKeyDatabaseClass object.

This chapter describes the following methods:

QbKeyDatabaseClass method

This is the constructor for the class.

Syntax

QbKeyDatabaseClass( void )

Parameters

None

~QbKeyDatabaseClass method

This is the destructor for the class.

Syntax

virtual ~QbKeyDatabaseClass( void )

Parameters

None

FromKeyString method

This method decodes the string inside a QbDatumClass object to initialize the object. Distance values for all keys are set to zero.

Syntax

virtual int FromKeyString( const QbDatumClass &datum )

Parameters

Input

datum-A reference to a QbDatumClass object whose byte string holds names of keys separated by spaces

Output

An integer value: 0 indicates success; -1 indicates failure

FromQueryString method

This method decodes the byte string in the input QbDatumClass object and initializes the QbKeyDatabaseClass object.

Syntax

virtual int FromQueryString( const QbDatumClass &datum )

Parameters

Input

datum-A reference to a QbDatumClass object that holds the encoded key-distance pairs

Output

An integer value: 0 indicates success; -1 indicates failure

GetDistance method

This method retrieves the distance value from the input QbDatumClass object.

Syntax

virtual float GetDistance( const QbDatumClass &data )

Parameters

Input

data-A reference to a QbDatumClass object whose byte string holds the distance value

Output

A float value that represents the distance

GetNumberOfKeys method

This method returns the number of elements in the object.

Syntax

unsigned long GetNumberOfKeys( void )

Parameters

Input

None

Output

An unsigned long integer that represents the number of elements

IsRanked method

This method returns True if the database is set to order the keys based on the distance value, False if not.

Syntax

Boolean IsRanked( void )

Parameters

Input

None

Output

A Boolean value; True if the database is set to order the keys based on the distance value, False if it is not.

RetrieveMax method

This method retrieves the key-value pair that contains the maximum distance in the object.

Syntax

virtual int RetrieveMax( QbDatumClass &key, QbDatumClass &value )

Parameters

Input

Output

An integer value: 0 indicates success; 1 indicates nonfatal error (for example, no keys in object); -1 indicates fatal error

SetDistance method

This method assigns the distance value into the byte string in the input data object.

Syntax

virtual int SetDistance( QbDatumClass &data, const float distance = -1 
)

Parameters

Input

Output

An integer value: 0 indicates success; -1 indicates failure

SetRanked method

This method makes the object order keys based on the distance value if rank=True.

Syntax

void SetRanked( const Boolean rank )

Parameters

Input

rank-A Boolean value; True means rank on distance, False means do not.

Output

None

ToKeyString method

This method encodes keys inside an object to an ASCII string and assigns it to the byte string of the given QbDatumClass object. The distance records are not encoded.

Syntax

virtual int ToKeyString( QbDatumClass &datum )

Parameters

Input

datum-A reference to a QbDatumClass object whose byte string will hold the encoded keys

Output

An integer value: 0 indicates success; -1 indicates failure

ToQueryString method

This method encodes both key and distance values in the object to an ASCII string and assigns it to the a byte string in the input QbDatumClass object.

Syntax

virtual int ToQueryString( QbDatumClass &datum )

Parameters

Input

datum-A reference to a QbDatumClass object whose byte string will hold encoded key-distance pairs

Output

An integer value: 0 indicates success; -1 indicates failure





Page 18 out of 26 total pages


xzhu@almaden.ibm.com or tedl@almaden.ibm.com
Copyright © 1998, IBM Corporation. All rights reserved.