ioLoop Docs

Appearance

$io.db ​

Server API reference.

Functions ​

$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.compressAndCreateTableFileFromUrl ​

Download, compress an image file from a URL and attach it to a database table record.

Usage ​

js
$io.db.compressAndCreateTableFileFromUrl(tableName, dsName, fieldName, recordId, fileName, url, tinyfyApiKey, tinyfyOptions)

Description ​

This function downloads an image file from a given URL and attaches it to a database record. The size and the contentType are determined automatically and are saved as meta data for the file.

Usage Scenarios ​

  • Reduce file sizes of images before storing in a database record
  • Automatically download, optimize images and attach files received from external services to database entries
  • Store files received from external services in a database record

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table where the file will be created. 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 database table where the file will be attached. You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record to which the file is being attached.

fileName ​

Type: String

Required: Yes

The name of the file being created.

url ​

Type: String

Required: Yes

The url to read/download the file from

tinyfyApiKey ​

Type: String

Required: Yes

The API key for the Tinyfy service, required for accessing the compression API.

tinyfyOptions ​

Type: Object

Required: Yes

Optional parameters for configuring the compression process (e.g., resize options, conversion options, etc.).

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 file's information in the database. The following properties are provided:
    • fileName: The name of the file stored in the database record.
    • size: The size of the file in bytes.
    • contentType: The MIME content type for the file.
  • err: If successful, set to null, otherwise contains information about the error (usually as a string).

$io.db.compressTableFile ​

Compress an image file attached to a database record

Usage ​

js
$io.db.compressTableFile(tableName, dsName, fieldName, recordId, fileName, newFileName, tinyfyApiKey, tinyfyOptions)

Description ​

This function compresses a image file attached to a database record. The compressed file is attached to the same database record after completion.

Usage Scenarios ​

  • Optimize large images files attached to a database record
  • Automate file compression for media files

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table where the file will be created. 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 database table where the file will be attached. You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record to which the file is being attached.

fileName ​

Type: String

Required: Yes

The name of the file being created.

newFileName ​

Type: String

Required: Yes

The name of the compressed file to be created.

tinyfyApiKey ​

Type: String

Required: Yes

The API key for the Tinyfy service, required for accessing the compression API.

tinyfyOptions ​

Type: Object

Required: Yes

Optional parameters for configuring the compression process (e.g., resize options, conversion options, etc.).

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 file's information in the database. The following properties are provided:
    • fileName: The name of the file stored in the database record.
    • size: The size of the file in bytes.
    • contentType: The MIME content type for the file.
  • err: If successful, set to null, otherwise contains information about the error (usually as a string).

$io.db.copyFsFileToTable ​

Copy a file from regular cloud storage to a database table record.

Usage ​

js
$io.db.copyFsFileToTable(tableName, dsName, fieldName, recordId, dstFileName, srcPath, srcIsPublic)

Description ​

This function copies a file from a specified path in regular cloud storage to a database table record. The file is duplicated into the database's managed storage context, allowing it to be associated with a specific database record.

Usage Scenarios ​

  • Attach files from cloud storage to a database record for management and reference
  • Automatically link uploaded files to specific database entries
  • Copy user-generated content from cloud storage to the database for tracking

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table where the file will be copied. 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 database table where the file will be copied. You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record to which the file is being attached.

dstFileName ​

Type: String

Required: Yes

The destination file name in the database record after the file is copied.

srcPath ​

Type: String

Required: Yes

The path in cloud storage where the file is currently stored, including directory and file name (e.g., '/storage/files/file.jpg').

srcIsPublic ​

Type: Boolean

Required: Yes

Specifies whether the source file is publicly accessible (true) or private (false) in the cloud storage.

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 file's information in the database. The following properties are provided:
    • fileName: The name of the file stored in the database record.
    • size: The size of the file in bytes.
    • contentType: The MIME content type for the file.
  • err: If successful, set to null, otherwise contains information about the error (usually as a string).

$io.db.copyTableFileToFs ​

Copy a file associated with a database table record to a path in the regular cloud storage.

Usage ​

js
$io.db.copyTableFileToFs(tableName, dsName, fieldName, recordId, fileInfo, dstPath, dstIsPublic)

Description ​

This function copies a file that is stored in the cloud and associated with a database table record to a specified path in regular cloud storage. The operation duplicates the file outside the database's managed context for further processing, backups, or access from standard storage locations.

Usage Scenarios ​

  • Copy files from a database record to standard cloud storage for processing or backup
  • Extract files linked to a database record for direct access via a cloud storage path

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table containing the file. 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 database table that holds the file (field type "Files"). You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record from which the file is being copied.

fileInfo ​

Type: String | Object

Required: Yes

Information about the file to be copied. This can either be:

  • A string containing the name of the file.
  • An object with a string property "fileName" containing the name of the file.

dstPath ​

Type: String

Required: Yes

The path in cloud storage where the file will be copied to, including directory and file name (e.g., '/storage/files/file.jpg').

dstIsPublic ​

Type: Boolean

Required: Yes

Specifies whether the copied file should be publicly accessible (true) or private (false) in the cloud storage destination.

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 information about the file. The following properties are provided:
    • Location: The path of the file
    • size: The size of the file in bytes
    • contentType: The MIME content type for the file
  • err: If successful set to null, otherwise the information about the error (usually as a string).

$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.createTableFileFromBuffer ​

Create a file using a buffer and attach it to a database table record.

Usage ​

js
$io.db.createTableFileFromBuffer(tableName, dsName, fieldName, recordId, fileName, buffer, contentType)

Description ​

This function creates a file using the provided buffer and attaches it to a database table record.

Usage Scenarios ​

  • Generate and store binary files in a database record
  • Programmatically create binary files and attach them to database entries
  • Save non-text data like PDFs, ZIP files, or executables in a database's file field

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table where the file will be created. 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 database table where the file will be attached. You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record to which the file is being attached.

fileName ​

Type: String

Required: Yes

The name of the file being created.

buffer ​

Type: Object

Required: Yes

A Buffer object containing the contents to be written to the file

contentType ​

Type: String

Required: Yes

The MIME content type. text/plain will be used if an empty content type is provided.

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 file's information in the database. The following properties are provided:
    • fileName: The name of the file stored in the database record.
    • size: The size of the file in bytes.
    • contentType: The MIME content type for the file.
  • err: If successful, set to null, otherwise contains information about the error (usually as a string).

$io.db.createTableFileFromStream ​

Create a file using a Readable stream and attach it to a database table record.

Usage ​

js
$io.db.createTableFileFromStream(tableName, dsName, fieldName, recordId, fileName, stream, contentType)

Description ​

Creates a file attached to a database record with the contents of the specified Readable stream. This function is commonly used for handling large files by streaming data in chunks.

Usage Scenarios ​

  • Read binary data from a stream and store in a database record
  • Attach files received from external services to database entries
  • Save non-text data like PDFs, ZIP files, or executables in a database record

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table where the file will be created. 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 database table where the file will be attached. You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record to which the file is being attached.

fileName ​

Type: String

Required: Yes

The name of the file being created.

stream ​

Type: Object

Required: Yes

A stream.Readable object containing the contents to be written to the file

contentType ​

Type: String

Required: Yes

The MIME content type. text/plain will be used if an empty content type is provided.

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 file's information in the database. The following properties are provided:
    • fileName: The name of the file stored in the database record.
    • size: The size of the file in bytes.
    • contentType: The MIME content type for the file.
  • err: If successful, set to null, otherwise contains information about the error (usually as a string).

$io.db.createTableFileFromText ​

Create a file from a text string and attach it to a database table record.

Usage ​

js
$io.db.createTableFileFromText(tableName, dsName, fieldName, recordId, fileName, text, contentType)

Description ​

This function creates a file from the provided text string and attaches it to a database table record.

Usage Scenarios ​

  • Generate and store text-based files (e.g., JSON, HTML, logs) in a database record
  • Programmatically create text files and attach them to database entries
  • Store dynamic content, such as reports or configuration files, in a database's file field

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table where the file will be created. 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 database table where the file will be attached. You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record to which the file is being attached.

fileName ​

Type: String

Required: Yes

The name of the file being created.

text ​

Type: String

Required: Yes

The text content that will be written to the file.

contentType ​

Type: String

Required: Yes

The MIME content type. text/plain will be used if an empty content type is provided.

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 file's information in the database. The following properties are provided:
    • fileName: The name of the file stored in the database record.
    • size: The size of the file in bytes.
    • contentType: The MIME content type for the file.
  • err: If successful, set to null, otherwise contains information about the error (usually as a string).

$io.db.createTableFileFromUrl ​

Copy a file from a specified URL and attach it to a database table record.

Usage ​

js
$io.db.createTableFileFromUrl(tableName, dsName, fieldName, recordId, fileName, url)

Description ​

This function downloads a file from a given URL and attaches it to a database record. The size and the contentType are determined automatically and are saved as meta data for the file.

Usage Scenarios ​

  • Download files from a remote server and store in a database record
  • Attach files received from external services to database entries
  • Store files received from external services in a database record

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table where the file will be created. 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 database table where the file will be attached. You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record to which the file is being attached.

fileName ​

Type: String

Required: Yes

The name of the file being created.

url ​

Type: String

Required: Yes

The url to read/download the file from

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 file's information in the database. The following properties are provided:
    • fileName: The name of the file stored in the database record.
    • size: The size of the file in bytes.
    • contentType: The MIME content type for the file.
  • err: If successful, set to null, otherwise contains information about the error (usually as a string).

$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.deleteByMatch ​

Initiates a database delete operation for records that match the given criteria

Usage ​

js
$io.db.deleteByMatch(tableName, dsName, match, options)

Description ​

Initiates a database delete operation for records that match the given criteria. Returns a Promise that allows you to wait for the completion of the operation. Use the options parameter to control dataset refresh and clearing behavior.

Usage Scenarios ​

  • Remove outdated or irrelevant data from a database table, such as deleting records older than a certain date
  • Clean up test data or temporary records based on specific conditions, like a certain status or flag
  • Delete multiple entries matching certain criteria to free up storage or maintain data integrity
  • Perform bulk deletions to clear data that meets specific conditions

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.

match ​

Type: Object

Required: Yes

Object representing the match criteria. This function supports MongoDB v4.0 based oprators like $eq, $and, $or, and others.

options ​

Type: Object

Required: Yes

Optional parameters that control the operation.

  • refresh: Boolean (default false). When true, refresh the dataset after completion.
  • noClear: Boolean (default false). When true, do not clear the dataset after completion (by default the dataset is cleared when refresh is false).

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.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.getTriggerHookInfo ​

Get a property from the trigger hook info object.

Usage ​

js
$io.db.getTriggerHookInfo(tvwaCrudHookInfo, prop)

Description ​

This function extracts a property from the trigger hook info object that is passed to the callback function of $io.db.setTriggerHook. Use it inside that callback to read table, id, data, or orig values.

Usage Scenarios ​

  • Read the table name or record ID inside a trigger hook
  • Access the new or original data from a trigger hook callback

Parameters ​

tvwaCrudHookInfo ​

Type: Object

Required: Yes

The info object received by the callback function of $io.db.setTriggerHook.

prop ​

Type: String

Required: Yes

The property to retrieve. Use one of the following values:

  • table: The name of the table
  • id: The record ID
  • data: The new or current data for create/update
  • orig: The original data for update

Output ​

Type: Object

Returns the requested property value. For table and id this is a String. For data and orig this is an Object. Returns null when unavailable.

$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.lookupTableFile ​

Retrieve information about a file attached to a database record

Usage ​

js
$io.db.lookupTableFile(tableName, fieldName, recordId, fileName)

Description ​

Retrieves information about a file attached to a database record. Information includes the name, size, MIME content type, etc.'

Usage Scenarios ​

  • Get information about a file attached to a database record
  • Find out the size of a file attached to a database record
  • Find out the MIME content-type of a file attached to a database record

Parameters ​

tableName ​

Type: String

Required: Yes

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

fieldName ​

Type: String

Required: Yes

The name of the field in the database table where the file is attached. You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record to which the file is attached.

fileName ​

Type: String

Required: Yes

The name of the database attached file for which information is being looked up.

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 information about the file. The following properties are provided:
    • name: The name of the file
    • size: The size of the file in bytes
    • contentType: The MIME content type for the file
  • 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.readAggregate ​

Read database table records using aggregation stages

Usage ​

js
$io.db.readAggregate(tableName, aggrStages)

Description ​

Reads from the specified database table using the supplied aggregation stages. The aggrStages parameter works in the same way as MongoDB v4.0 aggregation stages. It must be supplied as an Array of objects. Each stage must contain exactly one stage operator. This function is intended for read-only aggregation. The following top-level stages are not allowed: $out, $merge, $currentOp, $indexStats, $collStats, and $planCacheStats.

Usage Scenarios ​

  • Calculate grouped totals or summaries from table records
  • Read transformed records using aggregation stages
  • Compute values such as the sum of quantity multiplied by price across matching records

Parameters ​

tableName ​

Type: String

Required: Yes

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

aggrStages ​

Type: Array

Required: Yes

Array of aggregation stage objects. The supported syntax follows MongoDB v4.0 aggregation stages. Each stage must be an object with exactly one stage operator. For example: [ {$match: {status: "paid"}}, {$group: {_id: null, total: {$sum: {$multiply: ["$quantity", "$price"]}}}} ]

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 array containing the aggregation results. - err: If successful set to null, otherwise the information about the error (usually as a string).

$io.db.readByMatch ​

Initiates a database table read using MongoDB match criteria

Usage ​

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

Description ​

Initiates a database read operation for records that match the criteria provided using the match parameter. This follows the same dataset and pagination behavior as $io.db.read. Returns a Promise that allows you to wait for the completion of the operation.

Usage Scenarios ​

  • Read records from a database table that match specific field values
  • Read a page of records using MongoDB query criteria instead of a saved table query
  • Find records by status, owner, date range, or other table fields

Parameters ​

tableName ​

Type: String

Required: Yes

The name of the database table to read from. 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.

match ​

Type: Object

Required: Yes

Object representing the match criteria. This function supports MongoDB v4.0 based oprators like $eq, $and, $or, and others.

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 array can be empty if no records were found. - err: If successful set to null, otherwise the information about the error (usually as a string).

$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.readCountByMatch ​

Read the count of records matching MongoDB match criteria

Usage ​

js
$io.db.readCountByMatch(tableName, match)

Description ​

Reads the total number of records that match the criteria provided using the match parameter. This function does not create or use a dataset and returns the normal database operation response object directly.

Usage Scenarios ​

  • Get the total number of records matching a MongoDB query object
  • Check whether records exist before calling $io.db.readByMatch
  • Display a total count for records filtered by status, owner, date range, or other table fields

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.

match ​

Type: Object

Required: Yes

Object representing the match criteria. This function supports MongoDB v4.0 based oprators like $eq, $and, $or, and others.

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 matching the criteria. - 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.readTableFileAsBuffer ​

Read the contents of a file attached to a database record and return it as a Buffer object.

Usage ​

js
$io.db.readTableFileAsBuffer(tableName, fieldName, recordId, fileName)

Description ​

This function reads the contents of a file attached to a database record and returns the file content as a Buffer object.

Usage Scenarios ​

  • Retrieve binary files that are attached to database records such as images, PDFs, or media files for further processing
  • Read files attached to database records that are not text-based, such as executables or archives

Parameters ​

tableName ​

Type: String

Required: Yes

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

fieldName ​

Type: String

Required: Yes

The name of the field in the database table where the file will be attached. You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record to which the file is being attached.

fileName ​

Type: String

Required: Yes

The name of the file to be read.

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.
  • contentType: The MIME content type of the file.
  • data: If successful, a Buffer object containing the file's data
  • err: If successful set to null, otherwise the information about the error (usually as a string).

$io.db.readTableFileAsStream ​

Read the contents of a file attached to a database record and return it as a Node.js readable stream.

Usage ​

js
$io.db.readTableFileAsStream(tableName, fieldName, recordId, fileName)

Description ​

This function reads the contents of a file attached to a database record and returns the file content as a Node.js readable stream.

Usage Scenarios ​

  • Retrieve binary files that are attached to database records such as images, PDFs, or media files for further processing
  • Read files attached to database records that are not text-based, such as executables or archives

Parameters ​

tableName ​

Type: String

Required: Yes

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

fieldName ​

Type: String

Required: Yes

The name of the field in the database table where the file is attached. You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record to which the file is attached.

fileName ​

Type: String

Required: Yes

The stored file name to be read, including any generated filename prefix.

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.
  • contentType: The MIME content type of the file.
  • data: If successful, a Node.js readable stream containing the file's data
  • err: If successful set to null, otherwise the information about the error (usually as a string).

$io.db.readTableFileAsText ​

Read the contents of a file attached to a database record and return it as a text string.

Usage ​

js
$io.db.readTableFileAsText(tableName, fieldName, recordId, fileName)

Description ​

This function reads the contents of a file attached to a database record and returns the file content as a text string.

Usage Scenarios ​

  • Retrieve and display the content of text-based files attached to a database record (e.g., .txt, .json, .html)
  • Read text files or logs attached to a database record

Parameters ​

tableName ​

Type: String

Required: Yes

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

fieldName ​

Type: String

Required: Yes

The name of the field in the database table where the file will be attached. You may use the App Assets side-bar (on the left) to copy the field's name.

recordId ​

Type: String

Required: Yes

The ID of the database record to which the file is being attached.

fileName ​

Type: String

Required: Yes

The name of the file to be read.

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.
  • contentType: The MIME content type of the file.
  • data: If successful, a String containing the file's data
  • err: If successful set to null, otherwise the information about the error (usually as a string).

$io.db.setTriggerHook ​

Set a trigger hook for create, update, or delete operations on database records.

Usage ​

js
$io.db.setTriggerHook(type, cbFn)

Description ​

This function allows you to set a trigger hook on database operations (create, update, or delete). When the specified operation is performed on any database record, the provided callback function is executed. The callback receives information about the affected record, such as the table name, record ID, and the data before and after the operation. Triggers are useful for automating processes, updating related records, or performing audits based on database changes.

Usage Scenarios ​

  • Automatically execute custom logic when a new record is created in a table
  • Trigger actions or notifications when a record is updated
  • Log or track data when records are deleted from the database

Parameters ​

type ​

Type: String

Required: Yes

The operation to set the trigger hook on. Use the following values:

  • io-create: When new records are added to any database table
  • io-update: When any database record is updated
  • io-delete: When any database record is deleted

cbFn ​

Type: Function

Required: Yes

The callback function that will be called as a trigger when the specified operation occurs. The function is passed an object with the following properties: - table: The name of the table - id: The record ID of the record that was operated on - data: For create and update operations, the data for the modified or the created record - orig: For update operation, the original data for the modified record

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.updateByMatch ​

Initiates a database update operation for records that match the given criteria

Usage ​

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

Description ​

Initiates a database update operation for all records that match the criteria provided using the match parameter. Returns a Promise that allows you to wait for the completion of the operation. Use the options parameter to control dataset refresh and clearing behavior.

Usage Scenarios ​

  • Update multiple records in a database table that meet specific conditions, such as changing the status of all orders placed on a certain date
  • Modify data for a subset of users based on criteria like age, location, or subscription level
  • Perform batch updates to correct or enhance information across records matching certain conditions, such as adjusting prices for products in a specific category
  • Use conditional updates to change fields in all matching records, such as updating flags or settings for a group of related data entries

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.

match ​

Type: Object

Required: Yes

Object representing the match criteria. This function supports MongoDB v4.0 based oprators like $eq, $and, $or, and others.

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 parameters that control the operation.

  • refresh: Boolean (default false). When true, refresh the dataset after completion.
  • noClear: Boolean (default false). When true, do not clear the dataset after completion (by default the dataset is cleared when refresh is false).

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.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).