Tutorial

Range Lookups

upscaledb offers a functionality called “Approximate Matching”. It allows you to look up values even if you do not know their exact key!

Imagine an embedded system with a sensor attached. At irregular intervals, the sensor returns a value which will then be stored in the database. Sometimes it returns a value every second, at other times it returns just one value per minute.

Your application stores these values and uses the current timestamp as a key.

Further imagine that the application now wants to check the sensor value at about 12:00 o’clock. Note the “about” - chances are low that there’s a key with an exact 12:00 o’clock timestamp. The application needs to retrieve a value which was stored at 12:00 o’clock or very close to it!

Approximate Matching gives that functionality. You can ask upscaledb to retrieve values which match a key exactly or which are lower or greater than this key, but still very close to it.

You can do this by specifying a combination of the following flags to ups_find or ups_cursor_find:

• UPS_FIND_EQ_MATCH: This is the default setting. If exactly this key exists then the record of this key will be returned.
• UPS_FIND_LT_MATCH ‘find’ flag ‘Less Than’: retrieves the last record with a key which is less than the specified key.
• UPS_FIND_GT_MATCH ‘find’ flag ‘Greater Than’: retrieves the first record with a key which is greater than the specified key.
• UPS_FIND_LEQ_MATCH ‘find’ flag ‘Less or EQual’: retrieves the last record with a key which is less or equal than the specified key.
• UPS_FIND_GEQ_MATCH ‘find’ flag ‘Greater or Equal’: retrieves the first record with a key which is greater or equal than the specified key.

Here’s a short example snippet to search for a key or the next greater key:

memset (&record, 0, sizeof (record));
memset (&key, 0, sizeof (key));
/* fill key */

if ((st = ups_db_find (db, NULL, &key, &record, UPS_FIND_GEQ_MATCH))
    != UPS_SUCCESS) {
    // ...