An Embeddable NoSQL Database Engine

Jx9 Built-in Function - Database Storage & Retrieval Functions.

Syntax

bool db_exists(string $collection_name);

Alias

collection_exists

Description

db_exists() return True if the given collection exists in the underlying database. If the collection does not exists, you can create a new one via db_create().

Parameters

$collection_name

Name of the target collection.

Return Values

TRUE if the collection exists. FALSE otherwise.

Example

$zCol
= 'users'; /* Target collection name */
/* Check if the
collection 'users' exists */
 if(
db_exists($zCol) ){
       print "Collection users already created\n";
}else{
     /* Try to
create it */
     $rc =
db_create($zCol);
     if ( !$rc ){
          //Handle
error db_errlog()
          return;
     }
     print "Collection users successfully created\n";
}
//Store some JSON
now db_store() ...

Syntax

bool db_create(string $collection_name);

Alias

collection_create

Description

db_create() tries to create the given collection in the underlying database.

Parameters

$collection_name

Name of the collection to be created.

Return Values

TRUE if the collection was successfully created and stored in the underlying database. FALSE otherwise.

Example

$zCol
= 'users'; /* Target collection name */
/* Check if the
collection 'users' exists */
 if(
db_exists($zCol) ){
       print "Collection users already created\n";
}else{
     /* Try to
create it */
     $rc =
db_create($zCol);
     if ( !$rc ){
          //Handle
error db_errlog()
          return;
     }
     print "Collection users successfully created\n";
}
//Store some JSON
now db_store() ...

Syntax

int64 db_last_record_id(string $collection_name);

Description

db_last_record_id() return the unique ID (64-bit integer) of the last inserted record in the collection. You can extract the unique ID of a stored JSON object via the special __id field which is appended automatically to each object after successful return from db_store().

Parameters

$collection_name

Name of the target collection.

Return Values

Record ID (64-bit integer) is returned on success. FALSE otherwise.

Syntax

int64 db_current_record_id(string $collection_name);

Description

db_current_record_id() return the unique ID (64-bit integer) of the record pointed by the internal cursor. You can also extract the unique ID of a stored JSON object via the special __id field which is appended automatically to each object after successful return from db_store().

Parameters

$collection_name

Name of the target collection.

Return Values

Record ID (64-bit integer) is returned on success. FALSE otherwise.

Syntax

bool db_reset_record_cursor(string $collection_name);

Description

db_reset_record_cursor() reset the internal record cursor so that a call to db_fetch() can re-start from the beginning.

Parameters

$collection_name

Name of the target collection.

Return Values

TRUE on success. FALSE otherwise.

Syntax

int64 db_total_records(string $collection_name);

Description

db_total_records() return the total number of inserted records in the given collection.

Parameters

$collection_name

Name of the target collection.

Return Values

Total number of records (64-bit integer) on success. FALSE otherwise.

Syntax

string db_creation_date(string $collection_name);

Description

db_creation_date() return the creation date of the given collection.

Parameters

$collection_name

Name of the target collection.

Return Values

String holding the creation date of the collection on success. FALSE otherwise.

Syntax

bool db_begin(void);

Description

db_begin()manually start a write-transaction on the specified database handle. If a write-transaction has already been opened, this function is a no-op.
Tip: For maximum concurrency, it is preferable to let UnQLite start the transaction for you automatically.

Return Values

TRUE on success. FALSE otherwise.

Syntax

bool db_commit(void);

Description

db_commit() Commit all changes to the database and release the exclusive lock. In other words, make sure that all changes reaches the disk surface.
Tip: For maximum concurrency, it is recommended that you commit your transaction manually as soon as you have no more insertions.

Return Values

TRUE on success. FALSE otherwise.

Syntax

bool db_rollback(void);

Description

If a write transaction is open, then all changes made within the transaction are reverted and the current write-transaction is closed (Dropping all exclusive locks on the target database, deletion of the journal file, etc.). Otherwise this routine is a no-op.

Return Values

TRUE on success. FALSE otherwise.

Syntax

bool db_drop_collection(string $collection_name);

Alias

collection_delete

Description

db_drop_collection() remove a collection with all its records from the underlying database.

Parameters

$collection_name

Name of the target collection.

Return Values

TRUE when the given collection was succesfully removed from the database. FALSE otherwise.

Syntax

bool db_drop_record(string $collection_name, int64 $record_id);

Description

db_drop_record() remove a stored record from the collection via its unique ID. You can extract the unique ID of a stored JSON object via the special __id field which is appended automatically to each object after successful return from db_store().

Parameters

$collection_name	Name of the target collection.
$record_id	Unique ID of the record to be deleted.

Return Values

TRUE is returned on success. FALSE otherwise.

Syntax

bool db_set_schema(string $collection_name, string $json_object_schema);

Description

db_set_schema() set a database schema for the given collection. A collection schema must a valid JSON object, otherwise this function return FALSE.

Parameters

$collection_name	Name of the target collection.
$json_object_schema	Collection schema which must be a JSON object (See exmaple below).

Return Values

TRUE is returned on success. FALSE otherwise (i.e. Not a JSON object).

Example

$zCol
= 'users'; /* Target collection name */
/* Check if the
collection 'users' exists */
 if(
db_exists($zCol) ){
       print "Collection users already created\n";
}else{
     /* Try to
create it */
     $rc =
db_create($zCol);
     if ( !$rc ){
          //Handle
error db_errlog()
          return;
     }
     print "Collection users successfully created\n";
}
//Set a schema for our collection
$zSchema =  {
    name : 'string',
    age  : 'integer',
    addr : 'string'
};
db_set_schema('users',$zSchema);

//Store some JSON
now db_store() ...

Syntax

object db_get_schema(string $collection_name);

Description

db_get_schema() return the schema (JSON object) associated with the given collection. If no schema were associated within this collection, then NULL is returned instead.

Parameters

$collection_name

Name of the target collection.

Return Values

Collection schema (JSON object) is returned on success. NULL otherwise.

Syntax

string db_version(void);

Description

db_version() return the current version of the UnQLite database engine.

Return Values

UnQLite database engine version.

Syntax

string db_sig(void);

Description

db_sig() return the unique signature of the UnQLite database engine.

Return Values

UnQLite database engine unique signature.

Syntax

string db_copyright(void);

Alias

db_credits

Description

db_copyright() return the UnQLite copyright notice.

Return Values

UnQLite copyright notice.

Syntax

string db_errlog(void);

Description

db_errlog() return the database error log. The database error log is stored in an internal buffer. When something goes wrong during a db_store(), db_create(), db_fetch(), etc., a human-readable error message is generated to help clients diagnostic the problem.

Return Values

Database error log or the empty string.

Syntax

value db_fetch_by_id(string $collection_name,int64 $record_id);

Alias

db_get_by_id

Description

Fetch a record via its unique ID from the given collection. Note that you can extract the unique ID of a stored JSON object via the special __id field which is appended automatically to each object after successful return from db_store().

Parameters

$collection_name	Name of the target collection.
$record_id	Unique record ID

Return Values

Record value is returned on success. NULL otherwise.

Example

/* Create
the collection 'users'  */
 if(
!db_exists('users') ){
     /* Try to
create it */
   $rc =
db_create('users');
     if ( !$rc ){
          //Handle
error
      print db_errlog();

   return;
     }
}
//Our simple JSON object to be stored shortly.
$doc = {

   name : 'james',

   age  : 28,

   mail : 'dude@example.com',

 };

//Perform the store operation in the collection users

$rc = db_store('users',$doc);

if( !$rc ){

  //Handle
error    print db_errlog();

  return;


}
/* Extract our record using its unique ID which is appended automatically by the engine.

*/

print db_fetch_by_id('users',$doc.__id);



//Remove our object via its unique ID 
db_drop_record('users',$doc.__id);

Syntax

value db_fetch(string $collection_name);

Alias

db_get

Description

Fetch the current record from the target collection and automatically advance the cursor to the next record in the collection.

Note that you can manually reset the internal record cursor using db_reset_record_cursor().

Parameters

$collection_name

Name of the target collection.

Return Values

Record value is returned on success. NULL otherwise (i.e. No more records to retrieve).

Example

/* Create
the collection 'users'  */
 if(
!db_exists('users') ){
     /* Try to
create it */
   $rc =
db_create('users');
     if ( !$rc ){
          //Handle
error
      print db_errlog();

   return;
     }
}
//Store some JSON objects in our collection

db_store('users',{ name : 'james',   age : 27, mail : 'dude@example.com'  } );

db_store('users',{ name : 'robert',  age : 35, mail : 'rob@example.com'   } );

db_store('users',{ name : 'monji',   age : 47, mail : 'monji@example.com' } );

db_store('users',{ name : 'barzini', age : 52, mail : 'barz@mobster.com'  } );

//Fetch our records one after one from the collection


//db_reset_record_cursor();



while( ($rec = db_fetch('users')) != NULL ){

   print $rec;

}

Syntax

array db_fetch_all(string $collection_name,callback $filter_callback);

Alias

db_get_all

Description

Retrieve all records from a given collection and apply the filter callback if available.

Parameters

$collection_name

Name of the target collection.

$filter_callback

Optional: Filter callback to apply to the retrieved records. The callback must accept one argument which is the current retrieved record passed verbatim by the engine to the callback.

The callback must return a boolean result. TRUE when the record correspond to the callback criteria. FALSE otherwise (See example below).

Return Values

JSON array holding the filtered records if any. NULL is returned on failure.

Example

/* Create
the collection 'users'  */
 if(
!db_exists('users') ){
     /* Try to
create it */
   $rc =
db_create('users');
     if ( !$rc ){
          //Handle
error
      print db_errlog();

   return;
     }
}
//The following is the records to be stored shortly in our collection
$zRec = [
{
   name : 'james',
   age  : 27,
   mail : 'dude@example.com'
},
{
   name : 'robert',
   age  : 35,
   mail : 'rob@example.com'
},
{
   name : 'monji',
   age  : 47,
   mail : 'monji@example.com'


},

{
 name : 'barzini',  age  : 52,
  mail : 'barz@mobster.com'
}
];

//Store our records

$rc = db_store('users',$zRec);

if( !$rc ){

 //Handle
error    print db_errlog();

  return;
}

//Create our filter callback

$zCallback = function($rec){

    //Allow only users >= 30 years old.

    if( $rec.age < 30 ){

        // Discard this record

        return FALSE;

    }

    //Record correspond to our criteria

    return TRUE;

 }; //Don't forget the semi-colon here

//Retrieve collection records and apply our filter callback

$data = db_fetch_all('users',$zCallback); 



print $data; //JSON array holding the filtered records

Syntax

bool db_store(string $collection_name,$record,...);

Alias

db_put

Description

Store one or more JSON values (i.e. Objects, Arrays, Strings, etc.) in the given collection. The stored value is called collection record.

Parameters

$collection_name

Name of the target collection.

$record

One or more JSON values to be stored in the target collection (See example below).

Return Values

TRUE is returned on successful insertion. FALSE otherwise.

Example

/* Create
the collection 'users'  */
 if(
!db_exists('users') ){
     /* Try to
create it */
   $rc =
db_create('users');
     if ( !$rc ){
          //Handle
error
      print db_errlog();

   return;
     }
}
//The following is the records to be stored shortly in our collection
$zRec = [
{
   name : 'james',
   age  : 27,
   mail : 'dude@example.com'
},
{
   name : 'robert',
   age  : 35,
   mail : 'rob@example.com'
},
{
   name : 'monji',
   age  : 47,
   mail : 'monji@example.com'


},

{
 name : 'barzini',  age  : 52,
  mail : 'barz@mobster.com'
}
];

//Store our records

$rc = db_store('users',$zRec);

if( !$rc ){

 //Handle
error    print db_errlog();

  return;
}

//One more record
$rc = db_store('users',{ name : 'alex', age : 19, mail : 'alex@example.com'  });
if( !$rc ){

 //Handle
error    print db_errlog();

  return;
}

print "Total number of stored records: ",db_total_records('users');



//Fetch data using db_fetch_all(), db_fetch_by_id() and db_fetch().