ResultSet

In the previous section we reviewed the BnagDB objects and dealing with them. Now using the objects we will perform some operations. This section will review the *resultset* and operations supported by it

resultset - scrollable, searchable, iterable cursor returned by Scan operation

API set for resultset is as follows;

void begin();

void begin_reverse();

bool hasNext();

void moveNext();

FDT *getNextKey();

long getNextKeyInt();

long getNextKeyLong();

char * getNextKeyStr();

FDT *getNextVal();

long getNextValLong();

long getNextValInt();

char * getNextValStr();

FDT *lastEvaluatedKey();

long lastEvaluatedKeyLong();

bool moreDataToCome();

int count();

FDT *searchVal(FDT *key);

void clear();

void add_doc(resultset *rs, char *orderBy=NULL);

void add(resultset *rs);

void append(resultset *rs);

void intersect(resultset *rs);

Description of the above APIs is given in the resultset API section. However, there are certain points which are worth mentioning and they are listed below;

  • When scan returns resultset then we don't need to call begin() as it's already at this position. Hoever, if we want to come back to begining from some point then we should call this function
  • If reverse travel is required then call begin_reverse() instead, everything else remains same
  • hasNext doesn't move the pointer, it just tells if we have next data in the resultset
  • movenext actually moves the pointer to the next key value pair
  • getNextKey and getNextVal returns the pointer to the key and value at the current location. It's important to note that these function doesn't return the copy of the key and value but the pointer to the actual key and value. Hence one should never delete the returned key a nd value for clean up, but should call clear() method always in the end when we are done with the resultset
  • The getNextKeyLong() retruns long key, this should be called when log key is expected. Similarly getNextValLong() return long value and this should be called when long value is expected
  • The getNextKeyStr() returns the string, hence it is easier to call this when null terminated string is expected, same for getNextValStr()
  • moreDataToCome indicates if we there are more data that can come from db matching our range query, which could not be earlier returned due to the limit on the size or rows of resultset. Hence if we do a query betwen k1 and k2, and there are 90000 keys and values to be returned but limit on number of rows returned in single call to scan is 10000 then we would need to call the scan 9 times. The moreDataToCome tells us should we call scan again or not. Please see the usage of scan for more information
  • lastEvaluatedKey returns the last key that was there in the resultset. Note that it returns copy of the key hence once done we should delete the returned key as this won't be cleared by clear() call. The reason of returning copy of data here is to help doing the while loop until we have seen all the data. Here we might do scan in multiple steps
  • searchVal is a helper function to look for a particular key in the returned resultset. It returns the pointer to the val hence don't delete the returned val
  • clear should always be called to free the memory consumed by the resultset once done with it
  • There are four APIs provided for various operations on resultsets. The add simply adds two resultsets (it doesn't duplicate items). Note that for add, the sorting happens on the key and hence user need to ensure that the resultsets are for the same table.
  • The add_doc is for json data and here we can specify any field to order by. If we don't provide the orderby field then addition happens on the key else on the provided field in the json data
  • append simply adds result set to the end of the first one, no duplication is checked
  • intersect keeps the items present in both the list
  • Note that the result sets are modified if any of the above(add, add_doc, append, intersect) four APIs are called

API set for resultset is as follows;

void Begin();

void BeginReverse();

bool HasNext();

void MoveNext();

bool GetNextKey(out byte[] key);

bool GetNextKey(out string key);

long GetNextKeyLong();

string GetNextKeyStr();

bool GetNextVal(out byte[] val)

bool GetNextVal(out string val)

long GetNextValLong();

string GetNextValStr();

bool LastEvaluatedKey(out byte[] key);

bool LastEvaluatedKey(out string key);

ong LastEvaluatedKeyLong();

bool MoreDataToCome();

int Count();

bool SearchValue(byte[] key, out byte[] val)

bool SearchValue(string key, out string val)

void Clear();

void AddDoc(ResultSet rs, string orderBy = null);

void Add(ResultSet rs);

void Append(ResultSet rs);

void Intersect(ResultSet rs);

Description of the above APIs is given in the resultset API section. However, there are certain points which are worth mentioning and they are listed below;

  • When scan returns resultset then we don't need to call Begin() as it's already at this position. Hoever, if we want to come back to Begining from some point then we should call this function
  • If reverse travel is required then call BeginReverse() instead, everything else remains same
  • HasNext doesn't move the pointer, it just tells if we have next data in the resultset
  • MoveNext actually moves the pointer to the next key value pair
  • GetNextKey and GetNextVal returns the pointer to the key and value at the current location. It's important to note that these function doesn't return the copy of the key and value but the pointer to the actual key and value. Hence one should never delete the returned key and value for clean up, but should call clear() method always in the end when we are done with the resultset
  • The GetNextKeyLong() retruns long key, this should be called when log key is expected. Similarly GetNextValLong() return long value and this should be called when long value is expected
  • The GetNextKeyStr() returns the string, hence it is easier to call this when null terminated string is expected, same for GetNextValStr()
  • moreDataToCome indicates if we there are more data that can come from db matching our range query, which could not be earlier returned due to the limit on the size or rows of resultset. Hence if we do a query betwen k1 and k2, and there are 90000 keys and values to be returned but limit on number of rows returned in single call to scan is 10000 then we would need to call the scan 9 times. The moreDataToCome tells us should we call scan again or not. Please see the usage of scan for more information
  • LastEvaluatedKey returns the Last key that was there in the resultset. Note that it returns copy of the key hence once done we should delete the returned key as this won't be cleared by clear() call. The reason of returning copy of data here is to help doing the while loop until we have seen all the data. Here we might do scan in multiple steps
  • When MoreDataToCome returns true, then we get the Last seen key from LastEvaluatedKey() and start the scan again from this key. Note that since we have already seen the LastEvaluatedKey in the current scan resultset hence next time we should Add GT(greater than) constraint for the this key. For ex; if we wish to get all key value pairs for k1 to k5, and first scan returns k1 to k2, then next scan will happen from k2-k3 and k2 should not be included hence put a skey_op constriant of GT
  • searchVal is a helper function to look for a particular key in the returned resultset. It returns the pointer to the val hence don't delete the returned val
  • clear should always be called to free the memory consumed by the resultset once done with it
  • There are four APIs provided for various operations on resultsets. The Add simply Adds two resultsets (it doesn't duplicate items). Note that for Add, the sorting happens on the key and hence user need to ensure that the resultsets are for the same table.
  • The AddDoc is for json data and here we can specify any field to order by. If we don't provide the orderby field then addition happens on the key else on the provided field in the json data
  • Append simply adds result set to the end of the first one, no duplication is checked
  • Intersect keeps the items present in both the list
  • Note that the result sets are modified if any of these four APIs are called

API set for resultset is as follows;

void begin();

void beginReverse();

long getNextKeyLong()

String getNextKeyStr();

bool hasNext();

void moveNext();

byte[] getNextKey();

long getNextValLong();

String getNextValStr();

byte[] getNextVal()

byte[] lastEvaluatedKey();

long lastEvaluatedKeyLong();

bool moreDataToCome();

int count();

byte[] searchValue(byte[] key);

byte[] searchValue(string key);

void clear();

void addDoc(ResultSetImpl rs, String orderBy);

void add(ResultSetImpl rs);

void append(ResultSetImpl rs);

void intersect(ResultSetImpl rs);

Description of the above APIs is given in the resultset API section. However, there are certain points which are worth mentioning and they are listed below;

  • When scan returns resultset then we don't need to call begin() as it's already at this position. Hoever, if we want to come back to begining from some point then we should call this function
  • If reverse travel is required then call begin_reverse() instead, everything else remains same
  • hasNext doesn't move the pointer, it just tells if we have next data in the resultset
  • movenext actually moves the pointer to the next key value pair
  • getNextKey and getNextVal returns the pointer to the key and value at the current location.
  • The getNextKeyLong() retruns long key, this should be called when log key is expected. Similarly getNextValLong() return long value and this should be called when long value is expected
  • The getNextKeyStr() returns the string, hence it is easier to call this when string is expected, same for getNextValStr()
  • moreDataToCome indicates if we there are more data that can come from db matching our range query, which could not be earlier returned due to the limit on the size or rows of resultset. Hence if we do a query betwen k1 and k2, and there are 90000 keys and values to be returned but limit on number of rows returned in single call to scan is 10000 then we would need to call the scan 9 times. The moreDataToCome tells us should we call scan again or not. Please see the usage of scan for more information
  • lastEvaluatedKey returns the last key that was there in the resultset
  • searchVal is a helper function to look for a particular key in the returned resultset
  • clear should always be called to free the memory consumed by the resultset once done with it
  • There are four APIs provided for various operations on resultsets. The add simply adds two resultsets (it doesn't duplicate items). Note that for add, the sorting happens on the key and hence user need to ensure that the resultsets are for the same table.
  • The add_doc is for json data and here we can specify any field to order by. If we don't provide the orderby field then addition happens on the key else on the provided field in the json data
  • append simply adds result set to the end of the first one, no duplication is checked
  • intersect keeps the items present in both the list
  • Note that the result sets are modified if any of the above(add, add_doc, append, intersect) four APIs are called