DB objects (RFC-062)
A period when the community can review the RFC (comment Docs)
Document Maintainers: Andi Gabriel Tan 2024. List of other contributors in Annex. 1.
Copyright: MIT license
Copyright © 2018-2024 Axiologic Research and Contributors.
This document is licensed under MIT license.
- Abstract
- 1. DB Types summary
- 1.1 BasicDB
- Function addIndex(tableName, fieldname, forceReindex, callback)
- Function getIndexedFields(tableName, callback)
- Function beginBatch()
- Function cancelBatch(callback)
- Function commitBatch(callback)
- Function deleteRecord(tableName, key, callback)
- Function filter(tableName, query, sort, limit, callback)
- Function getHistory(tableName, key, callback)
- Function getRecord(tableName, key, callback)
- Function insertRecord(tableName, key, record, callback)
- Function updateRecord(tableName, key, record, callback)
- Function writeKey(tableName, key, value, callback)
- Function readKey(tableName, key, callback)
- 1.1 BasicDB
- Annex 1. Contributors
Abstract
Operations available on the different types of databases provided by the Database API are all available in this RFC. The BasicDB is created using a storage strategy. Several storage strategies are available, but if a person wants to create a custom strategy, all the following functions must be present in his storage strategy.
Warning: the OpenDSU DBs are NOT key/value databases, but databases containing records organized as tables! These records have a primary key, but they can also be indexed on any of their fields. Additionally, we should note that no schema definition is required, and heterogeneous objects could be freely inserted (but some standard fields would make it more valuable).
1. DB Types summary
Type | Description |
---|---|
BasicDB | Initialize a basic noSQL database . |
1.1 BasicDB
Function addIndex(tableName, fieldname, forceReindex, callback)
Description: Add an index to all the values from a specific field in your table. It can be used to locate the data in your database faster.
Name | Type | Value | Description |
---|---|---|---|
tableName | string | *required | Name of the table inside your database. |
fieldname | string | *required | Name of the field in your table that you want to index. |
forceReindex (optional) | Controls whether to create a new index for an already indexed field. If true, a new index for the specified fieldName will be created, regardless of whether an index for the fieldName already exists. If false, the field fieldName will be indexed only if there are no indexes for the specified field. By default, forceReindex is set to false. | ||
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object |
Description: An error object containing a message.
Function getIndexedFields(tableName, callback)
Description: Returns the list of the indexed fields in the specified table.
Name | Type | Value | Description |
---|---|---|---|
tableName | string | *required | Name of the table inside your database field name, forceReindex. |
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object | |
indexedFields | Array of strings |
Description: An error object containing a message. / The list of indexed fields in the specified table.
Function beginBatch()
Description: Start a batch of operations on your DSU without anchoring changes.
Returns
Name | Description |
---|---|
callback function | Prevent anchoring after each operation. |
Function cancelBatch(callback)
Description: Cancel the batch of operations in progress.
Name | Type | Value | Description |
---|---|---|---|
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object |
Description: An error object containing a message.
Function commitBatch(callback)
Description: Anchor the changes from the batch of operations on your DSU.
Name | Type | Value | Description |
---|---|---|---|
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object |
Description: An error object containing a message.
Function deleteRecord(tableName, key, callback)
Description: Delete a record by incrementing the record’s version number and setting the new record “delete property” to true. The old version of the record is saved.
Name | Type | Value | Description |
---|---|---|---|
tableName | string | *required | Name of the table inside your database. |
key | string | *required | Delete the existing record for this key. |
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object | |
record | Object |
Description: An error object containing a message./The updated record.
Function filter(tableName, query, sort, limit, callback)
Description: Returns the list of records satisfying the conditions in the specified query.
Name | Type | Value | Description |
---|---|---|---|
tableName | string | *required | Name of the table inside your database. |
query (optional) | string or array of strings | The conditions applied on the table tableName.A query can contain a condition (as a string) or an array of conditions. A condition has the format “field operator value”, where field is the field on which the condition is applied, the operator is one of <,<=,>,>=,==, like, and the value is the value to which the field values are compared. In the case of the like operator, the value is a string representing a regular expression. If the query is not provided, the function will return all the records in table tableName. | |
sort (optional) | string | Indicates if the returned array of records is sorted ascending or descending. The sort argument can have one of the values “asc” or “dsc”. By default, it has the value “asc”. | |
limit (optional) | number | The maximum number of records returned by the filter function. By default limit is Infinity, so all the records that satisfy the query are returned. | |
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object | |
record | Array of Object |
Description: An error object containing a message./ An array containing all the records satisfying the filter function’s condition.
Function getHistory(tableName, key, callback)
Description: Get the history of a record, including the deleted versions in a callback.
Name | Type | Value | Description |
---|---|---|---|
tableName | string | *required | Name of the table inside your database. |
Key | string | *required | The key you want to get history from. |
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object | |
record | Array of Object |
Description: An error object containing a message./An array of all the different versions.
Function getRecord(tableName, key, callback)
Description: Get a single row from a table.
Name | Type | Value | Description |
---|---|---|---|
tableName | string | *required | Name of the table inside your database. |
Key | string | *required | The key you want to get history from. |
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object | |
record | Array of Object |
Description: An error object containing a message./The record present for the selected key in the selected table.
Function insertRecord(tableName, key, record, callback)
Description: Insert a record, and return an error if it already exists.
Name | Type | Value | Description |
---|---|---|---|
tableName | string | *required | Name of the table inside your database. |
Key | string | *required | The value of the primary key for that record. Usually, a record has a field with the name “pk”. |
record | object | The record content. | |
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object | |
record | Array of Object |
Description: An error object containing a message./ The new record.
Function updateRecord(tableName, key, record, callback)
Description: Update a record, and return an error if it does not exist.
Name | Type | Value | Description |
---|---|---|---|
tableName | string | *required | Name of the table inside your database. |
Key | string | *required | The key you want to update. |
record | object | The record content. | |
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object | |
record | Array of Object |
Description: An error object containing a message./ The updated record.
Function writeKey(tableName, key, value, callback)
Description: Allows the insertion of a value of any type associated with the specified key, like in a key/value database.
Name | Type | Value | Description |
---|---|---|---|
tableName | string | *required | Name of the table inside your database. |
Key | string | *required | An unique identifier for the added value. |
value | any | The record content. | |
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object |
Description: An error object containing a message.
Function readKey(tableName, key, callback)
Description: Reads the value associated with the provided key.
Name | Type | Value | Description |
---|---|---|---|
tableName | string | *required | Name of the table inside your database. |
Key | string | *required | The identifier of the content read. |
callback | function | *required |
Callback parameters
Name | Type | Response example |
---|---|---|
err | Error object | |
value | any |
Description: An error object containing a message./The value associated with the provided key.
Contributors
-
Axiologic Research: New content and improvements. Original texts under PharmaLedger Association and Novartis funding. MIT licensed content accordingly with the contracts. Publish and maintain the www.opendsu.org site.
-
PharmaLedger Project: Review, feedback, observations, new content, and corrections MIT licensed accordingly with the consortium agreements.
- PrivateSky Research Project: MIT licensed content accordingly with the contracts. https://profs.info.uaic.ro/~ads/PrivateSky/
Annex 1. Contributors
Current Editors | |
---|---|
Sînică Alboaie | sinica.alboaie@axiologic.net |
Cosmin Ursache | cosmin@axiologic.net |
Teodor Lupu | teodor@axiologic.net |
Andi-Gabriel Țan | andi@axiologic.net |
Contributors Axiologic Research | |
Adrian Ganga | adrian@axiologic.net |
Andi-Gabriel Țan | andi@axiologic.net |
Cosmin Ursache | cosmin@axiologic.net |
Daniel Sava | daniel@axiologic.net |
Nicoleta Mihalache | nicoleta@axiologic.net |
Valentin Gérard | valentin@axiologic.net |
PrivateSky Contributors | |
Alex Sofronie | alsofronie@gmail.com (DPO) |
Cosmin Ursache | cos.ursache@gmail.com (UAIC) |
Daniel Sava | sava.dumitru.daniel@gmail.com (HVS, AQS) |
Daniel Visoiu | visoiu.daniel.g@gmail.com (SGiant) |
Lenuța Alboaie | lalboaie@gmail.com (UAIC) |
Rafael Mastaleru | rafael@rms.ro (RMS) |
Sînică Alboaie | salboaie@gmail.com (UAIC) |
Vlad Balmos | vlad.balmos@gmail.com (Code932) |
PharmaLedger Contributors | |
Ana Balan | bam@rms.ro (RMS) |
Bogdan Mastahac | mab@rms.ro (RMS) |
Cosmin Ursache | cos@rms.ro (RMS) |
Rafael Mastaleru | raf@rms.ro (RMS) |