ioLoop Docs

Appearance

$io.db ​

Client API reference.

Functions ​

$io.db.addFiles ​

Upload files and attach successful uploads to a Files field on an existing database record

Usage ​

js
$io.db.addFiles(tableName, dsName, fieldName, recordId, files, options)

Description ​

Uploads caller-supplied browser File objects and saves metadata for successful uploads in the specified Files field. This is a headless operation: it does not display a file picker, form, or upload widget. The record must already exist; when creating a record, await creation and pass the returned record ID.

Successful uploads are added to the field's stored file list, preserving existing entries. Stored filenames use the same generated timestamp prefix and filename sanitization as the form upload control.

If some files fail to upload, metadata for the successful uploads is still saved. The result then has status: false and data.saved: true if that save succeeded. If metadata persistence fails, uploaded bytes are not rolled back; data.uploadedFiles retains the metadata for the successful uploads.

Await this Promise before starting another file operation on the same record. For example, when deleting files and then adding files, await deleteFiles before calling addFiles. Overlapping metadata operations can overwrite changes.

Usage Scenarios ​

  • Attach files supplied by a file input or drag-and-drop handler to a record
  • Add files to an existing record without displaying a form or upload widget

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table.

dsName ​

Type: String

Required: Yes

A nonempty dataset name identifying the operation. Use $io.db.uniqueDsName to generate a name if needed.

fieldName ​

Type: String

Required: Yes

The name of a field with type Text and sub-type Files.

recordId ​

Type: String

Required: Yes

The identifier of the existing record to receive the files.

files ​

Type: File or FileList or Array

Required: Yes

A browser File object, a FileList such as input.files, or a nonempty array of File objects. File names, URLs, plain metadata objects, and empty lists are not accepted. This is different from deleteFiles, which accepts stored filenames or objects identifying stored files.

options ​

Type: Object

Required: Yes

Optional settings:

  • refresh: Boolean, defaults to false. If true, starts a dataset refresh after metadata is saved, including partial upload success. The Promise does not wait for the refreshed read to finish. If false, cached dataset data is cleared when any upload succeeded.

Output ​

Type: Promise

Resolves to an object with these properties:

  • status: true only when all files uploaded and their metadata was saved.
  • err: null on success, otherwise an error description.
  • data: null for invalid parameters; otherwise an object containing:
    • saved: Whether metadata for successful uploads was saved on the row.
    • uploadAttemptCnt: Number of supplied files, including unattempted files.
    • uploadCnt: Number of successful uploads identified in the results.
    • uploadErrCnt: Number of supplied files that did not succeed.
    • uploadedFiles: Metadata for successful uploads, each containing fileName, url, prefix, type (MIME type), and size (bytes).
    • failedFiles: Entries containing name (original filename) and err for failed or unattempted files.
    • files: The complete stored file list returned after a successful metadata save, including existing entries; otherwise null.

Counts and file arrays remain at their initial values if the operation fails before upload results can be collected. Check status and err for setup failures. A partial upload failure can have saved: true; inspect failedFiles to see which files were not uploaded.

$io.db.clearDataset ​

Clear the records in a dataset and free up resources and associated memory.

Usage ​

js
$io.db.clearDataset(tableName, dsName)

Description ​

Use this function to clear the records in a dataset and free up resources and the associated memory.

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This should be the same as the name used in the previous successful calls to the $io.db.readPrev, $io.db.readNext, $io.db.read $io.db.readQuery functions

Output ​

Type: null

This function does not return a value.

$io.db.create ​

Initiates the Creation or addition of a new record into the database table.

Usage ​

js
$io.db.create(tableName, dsName, recordInfo, options)

Description ​

Initiates the addition of a new record into the database table. Returns a Promise that allows you to wait for the completion of the operation.

Usage Scenarios ​

  • Add a new databse record
  • Create a new databse record

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $io.db.uniqueDsName function.

recordInfo ​

Type: Object

Required: Yes

Object with properties corresponding to the database table's fields. You may use the App Assets side-bar (on the left) to copy the fields template and fill in the values.

options ​

Type: Object

Required: Yes

Optional. Options for the create operation.

  • noWait: If true, returns immediately without waiting for completion. In this case, you must call $io.db.waitForCompletion with the appropriate operation type, tableName, and dsName to get the result.
  • refresh: If true, performs a read again after the create operation.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If options.noWait is true, null. Otherwise, if successful, an object representing the newly inserted record with the _id property containg the record's identifier. - err: If successful set to null, otherwise the information about the error (usually as a string). If options.noWait is true, the Promise resolves immediately with { status: true, data: null, err: null }. In this case, data is null and does not contain the newly inserted record, and you must call $io.db.waitForCompletion to obtain the final result.

$io.db.deleteById ​

Initiates a database delete operation for a record with the given identifier

Usage ​

js
$io.db.deleteById(tableName, dsName, recordId, options)

Description ​

Initiates a database delete operation for a record with the given identifier. Returns a Promise that allows you to wait for the completion of the operation.

Usage Scenarios ​

  • Remove a database record
  • Delete a database record

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $io.db.uniqueDsName function.

recordId ​

Type: String

Required: Yes

The record identifier.

options ​

Type: Object

Required: Yes

Optional. Options for the delete operation.

  • noWait: If true, returns immediately without waiting for completion. In this case, you must call $io.db.waitForCompletion with the appropriate operation type, tableName, and dsName to get the result.
  • refresh: If true, performs a read again after the delete operation.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If options.noWait is true, null. Otherwise, not set. - err: If successful set to null, otherwise the information about the error (usually as a string). If options.noWait is true, the Promise resolves immediately with { status: true, data: null, err: null }. In this case, data is null, and you must call $io.db.waitForCompletion to obtain the final result.

$io.db.deleteFiles ​

Delete/Remove files attached to a field on a database table record

Usage ​

js
$io.db.deleteFiles(tableName, dsName, fieldName, recordId, filesInfo, options)

Description ​

Removes the specified files attached to the given Files field of a record and updates the field's stored file list after successful deletions. This function reads the record using recordId before matching the requested file names against its stored file list. You do not need to read the record first if you already know the stored file names to delete. Returns a Promise that allows you to wait for the completion of the operation.

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $io.db.uniqueDsName function.

fieldName ​

Type: String

Required: Yes

The name of the field in the table. You may use the App Assets side-bar (on the left) to copy the desired field name.

recordId ​

Type: String

Required: Yes

The record identifier.

filesInfo ​

Type: Array or String or Object

Required: Yes

Identifies the attached files to delete. Accepted formats are:

  • A string containing one stored fileName, such as "report.pdf".
  • An object containing fileName, such as {fileName: "report.pdf"}.
  • An array of file name strings, objects containing fileName, or a mixture of both, such as ["report.pdf", {fileName: "photo.png"}]. A single string or object is treated as a one-element array.

You may pass the array returned by $io.db.getFileList(fieldValue), a subset of that array, or one of its objects. For example, after reading record, pass $io.db.getFileList(record.attachments) to delete all files listed in that field.

Matching uses the exact stored fileName, including any generated filename prefix. Only fileName is used from an object; its path, prefix, url, type, and size are not used to select files. A string must contain the fileName, not a full storage path, URL, or the JSON-encoded field value. All stored entries with a matching fileName are selected. If no files match, including when an empty array is supplied, the operation returns status: false.

options ​

Type: Object

Required: No

Optional settings:

  • refresh: Boolean, defaults to false. If true, starts a dataset refresh after the updated file list is saved to the record. The Promise does not wait for the refreshed read to finish. If false, cached dataset data is cleared when the operation completes.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: not set - err: If successful set to null, otherwise the information about the error (usually as a string).

$io.db.forEachPageRecord ​

Iterate through records in the current page of results

Usage ​

js
$io.db.forEachPageRecord(tableName, dsName, cbFn)

Description ​

Use this function to iterate over each record in the most recent page of records read for the dataset. This is primarily useful when the read operation was initiated with options.noWait set to true. In that case, call $io.db.waitForCompletion first, then use this function before clearing the dataset. If options.noWait is not true, the read functions copy the records into their Promise result and clear the dataset before resolving, so this function should not be expected to return those records afterward.

Usage Scenarios ​

  • Process each record in the current page

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This should be the same as the name used in the previous successful calls to the $io.db.readPrev, $io.db.readNext, $io.db.read $io.db.readQuery functions

cbFn ​

Type: Function

Required: Yes

Callback invoked for each record. The function is passed two parameters:

  • record: The record object for the current row.
  • index: The zero-based index of the record in the current page.

Output ​

Type: null

This function does not return a value.

$io.db.getFileList ​

Returns an array of objects containing file information for the given field value

Usage ​

js
$io.db.getFileList(fieldValue)

Description ​

Returns an array of objects containing file information parsed from the given field value. Use this function for fields with type Text and sub-type of Files. First read the database record using a read or lookup function, then pass the value of its Files field to this function. For example, if record is the record already read and attachments is its Files field, use $io.db.getFileList(record.attachments). This function parses the supplied value locally; it does not read the record or fetch file information from the database.

Usage Scenarios ​

  • Get uploaded files for a database record
  • Get file attachments for a database record

Parameters ​

fieldValue ​

Type: String

Required: Yes

The stored JSON string value of a Files field from a record that has already been read. Pass the field value, such as record.attachments, not the field name, record ID, or entire record.

Output ​

Type: Array

Returns an array containing objects representing the files uploaded and associated with the provided field. Each object contains the following properties:

  • url: The url of the file.
  • path: The full path for the file
  • prefix: The storage path prefix; prefix + fileName forms the full path.
  • fileName: The file name
  • type: The file's MIME type
  • size: The size of the file

$io.db.getRecordByIndex ​

Get a record by index from the last read page

Usage ​

js
$io.db.getRecordByIndex(tableName, dsName, index)

Description ​

Use this function to retrieve a single record by index from the most recent page of records read for the dataset. This is primarily useful when the read operation was initiated with options.noWait set to true. In that case, call $io.db.waitForCompletion first, then use this function before clearing the dataset. If options.noWait is not true, the read functions copy the records into their Promise result and clear the dataset before resolving, so this function should not be expected to return those records afterward.

Usage Scenarios ​

  • Get a record by its position in the current page of results

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This should be the same as the name used in the previous successful calls to the $io.db.readPrev, $io.db.readNext, $io.db.read $io.db.readQuery functions

index ​

Type: Number

Required: Yes

The zero-based index of the record in the current page.

Output ​

Type: Object

The record object at the specified index, or null if out of range.

$io.db.getRecordCount ​

Get the count of records previously read from a database table

Usage ​

js
$io.db.getRecordCount(tableName, dsName)

Description ​

Use this function to get the count of records read using the $io.db.read, $io.db.readQuery, $io.db.readNext or $io.db.readPrev functions. This returns the count of records in the current dataset page only. The maximum value returned by this function is limited to the perPage value used in the $io.db.read or $io.db.readQuery operation that loaded the dataset. To get the full count of records in a table, use $io.db.readCount. To get the full count of records matching a query, use $io.db.readCountQuery. This is primarily useful when the read operation was initiated with options.noWait set to true. In that case, call $io.db.waitForCompletion first, then use this function before clearing the dataset. If options.noWait is not true, the read functions copy the records into their Promise result and clear the dataset before resolving, so this function should not be expected to return those records afterward.

Usage Scenarios ​

  • Get count of records that were previously read from a database table

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This should be the same as the name used in the previous successful calls to the $io.db.readPrev, $io.db.readNext, $io.db.read $io.db.readQuery functions

Output ​

Type: Number

The count of records currently loaded in the dataset page for the given dataset and table. This is not the full count of records matching the read or query unless all matching records fit within the perPage value used for the read operation.

$io.db.getRecordId ​

Returns the record identifier for a valid record information object

Usage ​

js
$io.db.getRecordId(recordInfo)

Description ​

This is a utility function that returns the record identifier for a valid record information object. Essentially it returns the _id property of the provided record information object or an empty string.

Parameters ​

recordInfo ​

Type: Object

Required: Yes

A valid record information object.

Output ​

Type: String

String representing the record identifier or an empty string if recordInfo is not a valid record information object.

$io.db.getRecordList ​

Get the array of records read from a database table

Usage ​

js
$io.db.getRecordList(tableName, dsName)

Description ​

Use this function to get the array of records read using the $io.db.read, $io.db.readQuery, $io.db.readNext or $io.db.readPrev functions. This is primarily useful when the read operation was initiated with options.noWait set to true. In that case, call $io.db.waitForCompletion first, then use this function before clearing the dataset. If options.noWait is not true, the read functions copy the records into their Promise result and clear the dataset before resolving, so this function should not be expected to return those records afterward.

Usage Scenarios ​

  • Get list of records that were read from a database table
  • Get array of records that were read from a database table

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This should be the same as the name used in the previous successful calls to the $io.db.readPrev, $io.db.readNext, $io.db.read $io.db.readQuery functions

Output ​

Type: Array

Array of objects representing the database table records. The _id property of each represents the record's identifier.

$io.db.lookup ​

Lookup database table record with provided criteria

Usage ​

js
$io.db.lookup(tableName, dsName, matchCriteria, options)

Description ​

Lookup a database table record using the provided matching criteria for the table. Returns a Promise that allows you to wait for the completion of the operation.

Usage Scenarios ​

  • Lookup a database entry using unique fields
  • Lookup a database entry using primary key
  • Verify if a record exists

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table to be read. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $io.db.uniqueDsName function.

matchCriteria ​

Type: Array

Required: Yes

Contains elements corresponding to the unique or primary key fields that allow looking up a record from the table. The array elements are arranged in the order of the primary key fields in the table's definition. If the table does not have any unique fields, this function may not return desired results and we recommend using the $io.db.lookupById function instead for such cases.

options ​

Type: Object

Required: Yes

Optional. Options for the lookup operation.

  • noWait: If true, returns immediately without waiting for completion. In this case, you must call $io.db.waitForCompletion with the appropriate operation type, tableName, and dsName to get the result.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If options.noWait is true, null. Otherwise, if successful, an object representing the first record that was read. The _id property represents the record's identifier. - err: If successful set to null, otherwise the information about the error (usually as a string). If options.noWait is true, the Promise resolves immediately with { status: true, data: null, err: null }. In this case, data is null and does not contain the lookup result, and you must call $io.db.waitForCompletion to obtain the final result.

$io.db.lookupById ​

Lookup database table record using a record identifier.

Usage ​

js
$io.db.lookupById(tableName, dsName, recordId)

Description ​

Initiates a database lookup operation using the provided record identifier. Returns a Promise that allows you to wait for the completion of the operation.

Usage Scenarios ​

  • Verify if a record exists

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table to be read. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $io.db.uniqueDsName function.

recordId ​

Type: String

Required: Yes

The record identifier.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If successful, an object representing the first record that was read. The _id property represents the record's identifier. - err: If successful set to null, otherwise the information about the error (usually as a string).

$io.db.read ​

Initiates a simple database table read without criteria

Usage ​

js
$io.db.read(tableName, dsName, perPage, options)

Description ​

Initiates a simple database read operation without any match, sort or field selection criteria. Hence this will read the first page of records without criteria and use the default sorting order. Returns a Promise that allows you to wait for the completion of the operation.

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table to be read. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $io.db.uniqueDsName function.

perPage ​

Type: Number

Required: Yes

The maximum records to be read in a page. This value must be greater than 0 and cannot exceed 100.

options ​

Type: Object

Required: Yes

Optional. Options for the read operation.

  • noWait: If true, returns immediately without waiting for completion. In this case, you must call $io.db.waitForCompletion with the appropriate operation type, tableName, and dsName to get the result.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If options.noWait is true, null. Otherwise, if successful, an array of objects representing the database table records. The _id property of each element contains the record's identifier. The array can be empty if no records were found as this still indicates the read was succesful. - err: If successful set to null, otherwise the information about the error (usually as a string). If options.noWait is true, the Promise resolves immediately with { status: true, data: null, err: null }. In this case, data is null and does not contain the read records. You must call $io.db.waitForCompletion to wait for the operation to complete, then call $io.db.getRecordList to obtain the records.

$io.db.readCount ​

Read the total number of records in a database table

Usage ​

js
$io.db.readCount(tableName)

Description ​

Reads the total number of records in a database table without creating or using a dataset. This function returns the normal database operation response object directly and does not use $io.db.waitForCompletion.

Usage Scenarios ​

  • Get the total record count for a database table
  • Check whether a table has any records before starting a paged read
  • Display a total table record count in a dashboard or report

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table whose records should be counted. You may use the App Assets side-bar (on the left) to copy the desired table's name.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If successful, the number of records in the table. - err: If successful set to null, otherwise the information about the error (usually as a string).

$io.db.readCountQuery ​

Read the total number of records returned by a defined database query

Usage ​

js
$io.db.readCountQuery(tableName, queryId, queryInput)

Description ​

Reads the total number of records returned by an already defined query for the table. This function does not create or use a dataset, does not apply pagination, and returns the normal database operation response object directly.

Usage Scenarios ​

  • Get the total count for a parameterized database query
  • Display the total number of records matching a saved query before reading pages
  • Check whether a saved query has any matching records

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table to count records from. You may use the App Assets side-bar (on the left) to copy the desired table's name.

queryId ​

Type: String

Required: Yes

The query identifier to use for the count operation. You may use the App Assets side-bar (on the left) to copy the query identifier.

queryInput ​

Type: Array

Required: Yes

Array containing values for the criteria inputs/parameters used by the query. The order of the criteria inputs/parameters is based on the definition of the query. Use an empty array when the query does not require input parameters. You may use the App Assets side-bar (on the left) to copy the query input parameter template and fill in the values.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If successful, the number of records returned by the query. - err: If successful set to null, otherwise the information about the error (usually as a string).

$io.db.readNext ​

Initiates the read for the next page of records

Usage ​

js
$io.db.readNext(tableName, dsName, options)

Description ​

Initiates the read for the next page of records after an existing call to $io.db.readPrev, $io.db.readNext, $io.db.read or $io.db.readQuery completes successfuly for the same dataset and table. The query input parameters (in case of $io.db.readQuery) and the perPage value is retained from the previous initiation. Returns a Promise that allows you to wait for the completion of the operation.

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table to be read. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This should be the same as the name used in the previous successful calls to the $io.db.readPrev, $io.db.readNext, $io.db.read $io.db.readQuery functions

options ​

Type: Object

Required: Yes

Optional. Options for the read operation.

  • noWait: If true, returns immediately without waiting for completion. In this case, you must call $io.db.waitForCompletion with the appropriate operation type, tableName, and dsName to get the result.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If options.noWait is true, null. Otherwise, if successful, an array of objects representing the database table records. The _id property of each element contains the record's identifier. The array can be empty if no records were found as this still indicates the read was succesful. - err: If successful set to null, otherwise the information about the error (usually as a string). If options.noWait is true, the Promise resolves immediately with { status: true, data: null, err: null }. In this case, data is null and does not contain the read records. You must call $io.db.waitForCompletion to wait for the operation to complete, then call $io.db.getRecordList to obtain the records.

$io.db.readPrev ​

Initiates the read for the previous page of records

Usage ​

js
$io.db.readPrev(tableName, dsName, options)

Description ​

Initiates the read for the previous page of records after an existing call to $io.db.readPrev, $io.db.readNext, $io.db.read or $io.db.readQuery completes successfuly for the same dataset and table. The query input parameters (in case of $io.db.readQuery) and the perPage value is retained from the previous initiation. Returns a Promise that allows you to wait for the completion of the operation.

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table to be read. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This should be the same as the name used in the previous successful calls to the $io.db.readPrev, $io.db.readNext, $io.db.read $io.db.readQuery functions

options ​

Type: Object

Required: Yes

Optional. Options for the read operation.

  • noWait: If true, returns immediately without waiting for completion. In this case, you must call $io.db.waitForCompletion with the appropriate operation type, tableName, and dsName to get the result.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If options.noWait is true, null. Otherwise, if successful, an array of objects representing the database table records. The _id property of each element contains the record's identifier. The array can be empty if no records were found as this still indicates the read was succesful. - err: If successful set to null, otherwise the information about the error (usually as a string). If options.noWait is true, the Promise resolves immediately with { status: true, data: null, err: null }. In this case, data is null and does not contain the read records. You must call $io.db.waitForCompletion to wait for the operation to complete, then call $io.db.getRecordList to obtain the records.

$io.db.readQuery ​

Initiates a database table read using a defined query and match criteria

Usage ​

js
$io.db.readQuery(tableName, dsName, perPage, queryId, queryInput, options)

Description ​

Initiates a database read operation using an already defined query for the table. Returns a Promise that allows you to wait for the completion of the operation.

Usage Scenarios ​

  • Read database using a query with parameters

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table to be read. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $io.db.uniqueDsName function.

perPage ​

Type: Number

Required: Yes

The maximum records to be read in a page. This value must be greater than 0 and cannot exceed 100.

queryId ​

Type: String

Required: Yes

The query identifier to use for the read operation. You may use the App Assets side-bar (on the left) to copy the query identifier.

queryInput ​

Type: Array

Required: Yes

Array containing values for the criteria inputs/parameters used by the query. The order of the criteria inputs/parameters is based on the definition of the query. You may use the App Assets side-bar (on the left) to copy the query input parameter template and fill in the values.

options ​

Type: Object

Required: Yes

Optional. Options for the read operation.

  • noWait: If true, returns immediately without waiting for completion. In this case, you must call $io.db.waitForCompletion with the appropriate operation type, tableName, and dsName to get the result.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If options.noWait is true, null. Otherwise, if successful, an array of objects representing the database table records. The _id property of each element contains the record's identifier. The array can be empty if no records were found as this still indicates the read was succesful. - err: If successful set to null, otherwise the information about the error (usually as a string). If options.noWait is true, the Promise resolves immediately with { status: true, data: null, err: null }. In this case, data is null and does not contain the read records. You must call $io.db.waitForCompletion to wait for the operation to complete, then call $io.db.getRecordList to obtain the records.

$io.db.showInputModal ​

Display a dialog/popup to accept user input for a database table

Usage ​

js
$io.db.showInputModal(title, tableName, editData, cbFnSuccess, options)

Description ​

Use this function to display a generic form as a modal dialog/popup that accepts input from the user based on the table's field information schema. Unlike $io.ui.showFormModal which is used to show custom designed form, this function generates the form dynamically but in a generic way.

Usage Scenarios ​

  • Display a dialog for user input and save to database

Parameters ​

title ​

Type: String

Required: Yes

The title for the modal. If null or blank, a default value gets used.

tableName ​

Type: String

Required: Yes

The name of the database table. You may use the App Assets side-bar (on the left) to copy the desired table's name.

editData ​

Type: Object

Required: Yes

If a valid object is provided, the Form will be initialized in editing the existing record. Note that this should not be used as means to pre-populate the form's input fields as for saving the user's input a database update call is used instead of a database create when this parameter is null.

cbFnSuccess ​

Type: Function

Required: Yes

The callback function that will be called when the operation completes successfuly. Signature: cbFnSuccess(dataObj, refreshReq). The first argument is the data object entered by the user. The second argument is a Boolean indicating whether the modal requested a dataset refresh after save.

options ​

Type: Object

Required: Yes

Optional settings for the modal:

  • dsName: Dataset name used for refresh (default is empty string).
  • refresh: Set to true to refresh the dataset after save.

Output ​

Type: null

This function does not return a value.

$io.db.uniqueDsName ​

Generates a unique dataset name for use with database operations.

Usage ​

js
$io.db.uniqueDsName()

Description ​

Generates a unique dataset name for use with database operations.

Parameters ​

This function does not require parameters.

Output ​

Type: String

Returns a string containing a unique dataset name.

$io.db.updateById ​

Initiates a database update operation for a record with the given identifier and data

Usage ​

js
$io.db.updateById(tableName, dsName, recordId, recordInfo, options)

Description ​

Initiates a database update operation for a record with the given identifier and data. Returns a Promise that allows you to wait for the completion of the operation.

Usage Scenarios ​

  • Update a database record
  • Modify a database record

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name. This can be any string used to identify the initiatiation of the operation. To use a system generated name, use the $io.db.uniqueDsName function.

recordId ​

Type: String

Required: Yes

The record identifier.

recordInfo ​

Type: Object

Required: Yes

Object with properties corresponding to the database table's fields that need to be updated. You may use the App Assets side-bar (on the left) to copy the fields template and fill in the values for fields that need to be updated, removing the others.

options ​

Type: Object

Required: Yes

Optional. Options for the update operation.

  • noWait: If true, returns immediately without waiting for completion. In this case, you must call $io.db.waitForCompletion with the appropriate operation type, tableName, and dsName to get the result.
  • refresh: If true, performs a read again after the update operation.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If options.noWait is true, null. Otherwise, not set. - err: If successful set to null, otherwise the information about the error (usually as a string). If options.noWait is true, the Promise resolves immediately with { status: true, data: null, err: null }. In this case, data is null, and you must call $io.db.waitForCompletion to obtain the final result.

$io.db.waitForCompletion ​

Waits for the completion of the specified database operation

Usage ​

js
$io.db.waitForCompletion(opType, tableName, dsName)

Description ​

Returns a Promise that allows you to wait for the completion of the specified database operation for the given table and dataset name.

Parameters ​

opType ​

Type: String

Required: Yes

The operation to wait on. Use the following values:

  • zn-read: For a $io.db.readQuery, $io.db.read or $io.db.readCriteria operation
  • zn-lookup: For a lookup operation ($io.db.lookupById, $io.db.lookup)
  • zn-create: For a create operation using $io.db.create
  • zn-update: For an update operation using $io.db.updateById
  • zn-delete: For a delete operation using $io.db.deleteById or deleting files associated with a record using $io.db.deleteFiles

tableName ​

Type: String

Required: Yes

The name of the database table. You may use the App Assets side-bar (on the left) to copy the desired table's name.

dsName ​

Type: String

Required: Yes

The dataset name that was used to initiate the operation.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - data: If successful, an object as follows: - For readQuery, read, readNext and readPrev (zn-read) operations, this is operation completion data from the underlying read. To get the full page of records, call $io.db.getRecordList after this Promise resolves. - For lookup (zn-lookup) operations, this is an object representing the first record that was read. The _id property represents the record's identifier. - For a create operation (zn-create), this is an object representing the newly inserted record with the _id property containg the record's identifier. - For update (zn-update) and delete (zn-delete) operations, this is not set. - err: If successful set to null, otherwise the information about the error (usually as a string).