BangDB API for C#

    Database

  1. To create database
  2. Database(string dbName, string configpath, TransactionType transaction_type=TransactionType.DBTransactionNone, string dbpath = null)

    TransactionType has following options

    • DBTransactionNone
    • DBOptimisticTransaction
    • DBPessimisticTransaction
  3. To get a table
  4. Table GetTable(string tableName, DBOpenType flag = DBOpenType.Opencreate, TableEnv tblEnv = null)

    WideTable GetWideTable(string tableName, DBOpenType flag = DBOpenType.Opencreate, TableEnv tblEnv = null)

    Table GetPrimitiveTable(string tableName, BangDBPrimitiveDataType dataType = BangDBPrimitiveDataType.PrimitiveLong, DBOpenType flag = DBOpenType.Opencreate, TableEnv tblEnv = null)

    DBOpenType has following options

    • Opencreate
    • Truncopen
    • Justopen

    The TableEnv is a type which can be created, set with proper values and passed to the gettable. This allows user to override a set of config values as defined in the bangdb.config file. Note that if null is passed for TableEnv then db config (defined in bangdb.config) values will apply to the table as well, but user can override some of the values by creating TableEnv for each table. This allows us to treat each table differently.

    Following parameters can be set or overridden for the table;

    • PersistType
      • InmemOnly, //only RAM based, cache enabled (no overflow to disk, ideally overflow to other RAM)
      • InmemPersist, //disked backed, cache enabled (over flow to disk)
      • PersistOnly, //many procs one db file, cache disabled
      • DefaultConfig,
    • IndexType
      • Hash, - deprecated
      • Exthash,
      • Btree,
      • Heap, - not supported
      • DefaultConfig,
    • key type (BangDBKeyType)
      • NormalKey,
      • CompositeKey,
      • NormalKeyLong
    • TableSizeHint
      • TinyTableSize
      • SmallTableSize
      • NormalTableSize
      • BigTableSize
    • WALSate
      • Disabled
      • Enabled
      • DefaultConfig
    • allowDuplicates
      • true
      • false
    • BangDBLogType
      • SharedLog
      • PrivateLog
    • BangDBTableType
    • Note that user should never set table type, it's totally for BangDB to set based on API called (GetTable, GetPrimitiveTable and GetWideTable)

      • NormalTable
      • WideTable
      • IndexTable
      • PrimitiveTableInt
      • PrimitiveTableLong
      • PrimitiveTableString
    • BangDBPrimitiveDataType
      • PrimitiveInt
      • PrimitiveLong
      • PrimitiveString
    • BangDBKeySortMethod
      • Lexicograph,
      • QuasiLexicograph,
    • BangDBKeySortDirection
      • SortAscending,
      • SortDescending,
    • AutoCommitState
      • Disabled
      • Enabled
      • DefaultConfig
    • keySize
    • LogSizeMB

    Hence table_env gives us the capability to create multiple tables within a db with different set of config values. For example, we can create table1 with {inmem_only, hash, log-on..}, table2 with {inmem_persist, Btree, log-off, autocommit-on...} and so on

    When successful, this returns a Table object else null with error message

  5. Closing a Table
  6. int CloseTable(Table tbl, DBCloseType flag = DBCloseType.Default)

    int CloseTable(string tableName, DBCloseType flag = DBCloseType.Default)

    int CloseTable(WideTable wtbl, DBCloseType flag = DBCloseType.Default)

    DBCloseType has following options;

    • Default
    • Conservative
    • Optimistic
    • CleanClose

    returns 0 for success or -1 for error

  7. Closing database
  8. void CloseDatabase(DBCloseType flag = DBCloseType.Default)

    Note that closedatabase is enough to close the database and user need not close each table or connection separately. Closing database closes everything and cleans up all resources

  9. Beginning a transaction
  10. Transaction txn = new Transaction();

    db.BeginTransaction(txn)

    returns a Transaction object which should be used in all participating operations

  11. Committing a transaction
  12. long CommitTransaction(Transaction txn)

    returns a unique identifier for the committed transaction else -1 on error

  13. Aborting a transaction
  14. void AbortTransaction(Transaction txn)

    Table

  1. Getting a connection
  2. Connection GetConnection()

    PrimConnection GetPrimConnection()

    returns a connection object using which all operations for the table can be done

    Note that for NormalTable user should call GetConnection() and for PrimitiveTable (all types of primitive tables) user should call GetPrimConnection. If there is mismatch in calling either of the APIs then it returns NULL with proper error message.

  3. Closing a table
  4. int CloseTable(DBCloseType flag = DBCloseType.Default)

    Returns 0 for success, -1 for error

  5. Dumping data
  6. int DumpData()

    This is helpful in explicitly dumping the data to disk at any time during the operation. But mostly used when we run the table in inmemory only mode but later during close or any other time we wish to save the data on disk

    Returns 0 for success, -1 for error

  7. Closing connection
  8. int CloseConnection(Connection conn)

    Returns 0 for success, -1 for error

    WideTable

  1. Getting a connection
  2. WideConnection GetConnection()

    returns a connection object using which all operations for the table can be done

  3. Closing a table
  4. int CloseTable(DBCloseType flag = DBCloseType.Default)

    Returns 0 for success, -1 for error

  5. adding index
  6. int AddIndex_Str(string idxName, int idxSizeByte, bool allowDuplicates)

    int AddIndex_Num(string idxName, bool allowDuplicates)

    int AddIndex(string idxName, TableEnv tenv)

    int DropIndex(string idxName)

  7. Dumping data
  8. int DumpData()

    This is helpful in explicitly dumping the data to disk at any time during the operation. But mostly used when we run the table in inmemory only mode but later during close or any other time we wish to save the data on disk

    Returns 0 for success, -1 for error

  9. Closing all connections
  10. int CloseAllConnection()

    Returns 0 for success, -1 for error

    Connection (for Normal table)

  1. Putting key value without transaction
  2. long Put(long key, string val, InsertOptions flag)

    long Put(long key, byte[] val, InsertOptions flag)

    long Put(string key, ref DataVar dv, InsertOptions flag)

    long Put(byte[] key, ref DataVar dv, InsertOptions flag)

    long Put(byte[] key, byte[] val, InsertOptions flag)

    long Put(string key, string val, InsertOptions flag)

    long Put(string key, byte[] val, InsertOptions flag)

    long Put(byte[] key, string val, InsertOptions flag)

    Variety of options for keys and values are provided for user's convenience, user should ensure calling the appropriate apis which ever suitable

    The InsertOptions has following options;

    • InsertUnique, //if non-existing then insert else return
    • UpdateExisting, //if existing then update else return
    • InsertUpdate, //insert if non-existing else update
    • DeleteExisting, //delete if existing(for future usage)

    Return 0 for success else -1 with error message

  3. DataVar is used with pre-allocated buffers
    • create DataVar
    • DataVar(int sizeInBytes)

    • copy buffers
    • void Copy(string _buf, int len)

      void Copy(byte[] _buf, int len)

    • Reading the buffer
    • string Read()

      string Read(int len)

    • Compare or Equal
    • bool Equals(string _buf, int len)

      bool Equals(byte[] _buf, int len)

      bool Equals(byte[] buffer1, int offset1, byte[] buffer2, int offset2, int count)

  4. Putting key value with transaction
  5. public long Put(long key, string val, InsertOptions flag, Transaction txn)

    public long Put(long key, byte[] val, InsertOptions flag, Transaction txn)

    long Put(string key, ref DataVar dv, InsertOptions flag, Transaction txn)

    long Put(byte[] key, ref DataVar dv, InsertOptions flag, Transaction txn)

    long Put(byte[] key, byte[] val, InsertOptions flag, Transaction txn)

    long Put(string key, string val, InsertOptions flag, Transaction txn)

    long Put(string key, byte[] val, InsertOptions flag, Transaction txn)

    long Put(byte[] key, string val, InsertOptions flag, Transaction txn)

    These are similar to above APIs except that they take transaction handle

    Return 0 for success else -1 with error message

  6. Getting value for a key without transaction
  7. bool Get(long key, byte[] val)

    bool Get(long key, out string vout)

    bool Get(string key, out byte[] val)

    bool Get(byte[] key, out string val)

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

    bool Get(string key, out string val)

    bool Get(string key, ref DataVar dv)

    bool Get(byte[] key, ref DataVar dv)

    First three APIs returns true for success and false for failure to retrieve, whereas the last two apis returns the value or null for success and failure respectively. Failure to retrieve means data may not be there in the db, for other reasons like errors, an error message is also sent

  8. Getting value for a key with transaction
  9. bool Get(long key, byte[] val, Transaction txn)

    bool Get(long key, out string vout, Transaction txn)

    bool Get(string key, out byte[] val, Transaction txn)

    bool Get(byte[] key, out string val, Transaction txn)

    bool Get(byte[] key, out byte[] val, Transaction txn)

    bool Get(string key, out string val, Transaction txn)

    These are similar to above APIs except that they take transaction handle. Failure to retrieve means data may not be there in the db, for other reasons like errors, an error message is also sent

  10. Deleting a key value without transaction
  11. long Del(byte[] key)

    long Del(string key)

    long Del(long key)

    Return 0 for success else -1 with error message

  12. Deleting a key value without transaction
  13. long Del(byte[] key, Transaction txn)

    long Del(string key, Transaction txn)

    Return 0 for success else -1 with error message

  14. Range query or scan without transaction
  15. ResultSet Scan(long skey, long ekey, ScanFilter sf = null)

    ResultSet Scan(byte[] skey, byte[] ekey, ScanFilter sf = null)

    ResultSet Scan(string skey, string ekey, ScanFilter sf = null)

    Here skey and ekey are start and end keys for range query. Either of these two keys can be null, partial, full or some random value keys. When null is provided for skey and/or ekey then it means full scan in that direction. For example to get all values for keys greater than equal to key=”mykey” we can use scan(key, null) or to get get all values (select * from table) we can use scan((byte[])null, (byte[])null)

    ScanFilter is provided to further add operators while doing the query and provide some limits on the returned resultset. The values for ScanFilter is as follows;

    • ScanOperator skeyOp; //default GTE
    • ScanOperator ekeyOp; //default LTE
    • ScanLimitBy limitBy; //default LIMIT_RESULT_SIZE
    • int limit; //default 2MB (MAX_RESULTSET_SIZE)

    The ScanOperator has following values;

    • GT, //greater than
    • GTE, //greater than equal to - default
    • LT, //less than
    • LTE, //less than equal to – default

    And ScanLimitBy has following values;

    • LimitResultSizeByte, //defines the bytes of data that should be returned (max)
    • LimitResultRow, //number of rows (max) that should be returned

    The resultset is scrollable cursor with methods to iterate over the returned keys and values based in the given parameters by scan.

    Returns resultset on success else null for error

  16. Range query or scan with transaction
  17. ResultSet Scan(byte[] skey, byte[] ekey, Transaction txn, ScanFilter sf = null)

    ResultSet Scan(string skey, string ekey, Transaction txn, ScanFilter sf = null)

    These are similar to above APIs except that they take transaction handle

    Returns appropriate values or null with error message

  18. Counting the number of items
  19. long Count(byte[] skey, byte[] ekey, ScanFilter sf = null)

    long Count(string skey, string ekey, ScanFilter sf = null)

    long Count()

    long Count(long sk, long ek, ScanFilter sf = null)

    long Count(int sk, int ek, ScanFilter sf = null)

    This is very similar to scan except that this returns the count instead of resultset. The skey and ekey behaviour is similar

    Third one is convenient method for counting all elements in the table

    Returns count on success else -1 on error

  20. Setting auto commit
  21. void SetAutoCommit(bool flag);

    When transaction is OFF, then autocommit by default is ON and all individual operations guarantees ACID. We use non transactional APIs for get, put, del, scan. But when transaction is on and if autocommit is off then we can only use transactional APIs for get, put, del, scan and all non-transactional ones will fail. But to override the scenario, one can call this method and perform transactional or non transaction ops as required.

    For example, if db is opened in transactional mode with autocommit = OFF then following is not allowed;

    	bool b = conn.Get(k, out v);	//Not OK
    	
    	//we will have to either use the transactional API,
    	Transaction txn = db.BeginTransaction();
    	bool b = conn.Get(k, out v, txn);
    	
    	//Or, set the autocommit ON,
    	conn.SetAutocommit(true);
    	bool b = conn.Get(k, out v);		//OK
    	
    	//if you don't wish to bother about all these then simply
    	//set the auto commit in bangdb.config as 1 and then you
    	//will not have to set or unset autocommit using the API
    	
  22. Close this connection
  23. int CloseConnection();

    Returns 0 for success else -1 with error message

    primConnection (for primitive table)

  1. put
  2. The supported get and put are given below. The scan, count, del etc... APIs remain same as of normal connection

    public long Put(long key, long val, InsertOptions flag);

    public long Put(int key, int val, InsertOptions flag);

    public long Put(string key, long val, InsertOptions flag);

    public long Put(byte[] key, long val, InsertOptions flag);

  3. get
  4. public bool Get(long key, ref long val);

    public bool Get(int key, ref int val);

    public bool Get(string key, ref long val);

    public bool Get(byte[] key, ref long val);

    wideConnection (for wide table)

    Most of the APIs are similar to that of connection, except that it has few more APIs for put and scan and they are;

  1. more put APIs
  2. public long Put(byte[] key, string val, string idxName, string idxVal);

    public long Put(string key, byte[] val, string idxName, string idxVal);

    public long Put(string key, string val, string idxName, string idxVal);

    public long Put(long key, string val, string idxName, string idxVal);

    public long Put(long key, byte[] val, string idxName, string idxVal);

    public long PutDoc(string key, string jsonStr, InsertOptions flag);

    public long PutDoc(long key, string jsonStr, InsertOptions flag);

    public long PutDoc(string jsonStr);

  3. more scan APIs
  4. public ResultSet ScanDoc(string idxName, string skey, string ekey, ScanFilter sf = null);

    public ResultSet ScanDoc(string idxName, long skey, long ekey, ScanFilter sf = null);

    public ResultSet Scan(string idxName, string skey, string ekey, ScanFilter sf = null);

    public ResultSet Scan(string idxName, byte[] skey, byte[] ekey, ScanFilter sf = null);

    Resultset

  1. Checking if the result has next key, val pair
  2. bool HasNext();

    returns true if yes and false otherwise

  3. Moving to the next key and val pair
  4. void MoveNext();

  5. Beginning the iteration
  6. void Begin();

    When resultset is returned, it is set at begining, but if we want to go back to beginning then we call this api

  7. Getting the next key
  8. bool GetNextKey(out byte[] key)

    bool GetNextKey(out string key)

    long GetNextKeyLong()

    string GetNextKeyStr()

    Returns true for success and false otherwise

  9. Getting the next val
  10. bool GetNextVal(out byte[] val)

    bool GetNextVal(out string val)

    long GetNextValLong()

    string GetNextValStr()

    Returns true for success and false otherwise

  11. Last Evaluated Key
  12. bool LastEvaluatedKey(out byte[] key)

    bool LastEvaluatedKey(out string key)

    long LastEvaluatedKeyLong()

    Returns true for success and false otherwise. Please see the documentation for use of this method

  13. Check if more data is to come
  14. bool MoreDataToCome()

    returns true if more data is expected to come for the query else false

  15. Counting the num of items in the resultset
  16. int Count();

    returns the number of items in the resultset

  17. Searching a key in the resultset
  18. bool SearchValue(byte[] key, out byte[] val)

    bool SearchValue(string key, out string val)

    Returns true for success and false otherwise

  19. Operations on ResultSet
  20. void AddDoc(ResultSet rs, string orderBy = null)

    void Add(ResultSet rs)

    void Append(ResultSet rs)

    void Intersect(ResultSet rs)

  21. Freeing the resultset resource
  22. void Clear();

    Sliding Table

  1. Create
  2. SWTable(Database db, string tableName, TableEnv tenv, int ttlSec)

  3. Initialize
  4. int Initialize()

  5. Adding index
  6. void AddIndex(string idxName, TableEnv tenv)

  7. Getting Connection
  8. IntPtr GetConnection()

  9. put
  10. int Put(string str, InsertOptions flag)

    int Put(string str, string idxName, string idxKey)

  11. scan
  12. ResultSet Scan(int period)

    ResultSet Scan(int period, int lag)

    ResultSet ScanFull()

    ResultSet ScanRemaining(long fromTime, int lag)

  13. close
  14. void Close()

    Counting

  1. Create wrapper
  2. swEntityCount(char *countName, int swTime, int swExpiry, int nEntity = 32)

  3. Create Entity
  4. void CreateEntity(string name, BangDBWindowType swType, BangDBCountType countType)

    BangDBWindowType

      NonSlidingWindow,

      SlidingWindowSpan,

      SlidingWindowUnit,

  5. Add
  6. int Add(string entityName, string s)

    void AddCreate(string entityName, string s, BangDBWindowType swType, BangDBCountType countType)

  7. Remove Entity
  8. void RemoveEntity(string name)

  9. List
  10. string ListCount_Json()

    string ListCount_Str()

  11. Count
  12. int count(char *entityName)

    int count(char *entityName, int span)

  13. shutdown
  14. void ShutDown()

    TopK

  1. Create
  2. TopK(string name, int swSizeSec, int k, bool desc, string uniqueBy)

  3. Put
  4. void Put(long score, string data, string uniqueParam)

  5. Get TopK
  6. ResultSet GetTopK(int k = 0)

    string GetTopKJson(int k = 0)

  7. Close
  8. void Close()