Skip to main content

Vault queries

JavaScript query reference

Use Vault helpers to check collected records and, when necessary, retrieve matching data from another NIM system table.

Vault query functions are available in custom JavaScript columns. They work with data NIM has already collected into the Vault; they do not query a connected source system live.

Choose the right functionDirect link to Choose the right function

FunctionUse it whenReturns
vaultObjectExistsYou know the table’s primary-key value and only need to know whether the record exists.true or false
vaultObjectExistsByRefYou need to check a value in a configured reference column.true or false
vaultObjectFindYou need values from a matching record rather than a simple existence check.An array of matching records, or an empty array
Prefer existence checksUse an existence function when a Boolean answer is sufficient. It makes the intent clear and avoids the broader record lookup performed by vaultObjectFind.

Check a primary key with vaultObjectExistsDirect link to check-a-primary-key-with-vaultobjectexists

Use this function when the lookup value is the table’s configured primary key.

return vaultObjectExists('hr500', 'employees', '10023963');
ArgumentRequiredDescription
System nameYesThe NIM system that contains the collected table.
Table nameYesThe table to check.
Lookup valueYesThe primary-key value to find.

The example returns true when hr500 contains an employees record whose primary key is 10023963; otherwise, it returns false.

Check a reference key with vaultObjectExistsByRefDirect link to check-a-reference-key-with-vaultobjectexistsbyref

Use this function when the value is stored in a column configured as a reference key.

return vaultObjectExistsByRef('hr500', 'employees', 'ssn', '999-888-7777');
ArgumentRequiredDescription
System nameYesThe NIM system that contains the collected table.
Table nameYesThe table to check.
Reference columnYesA column marked as a Reference in the table properties.
Lookup valueYesThe value to find in that reference column.

This returns a Boolean. It does not return the matching employee record.

Retrieve matching records with vaultObjectFindDirect link to retrieve-matching-records-with-vaultobjectfind

Use vaultObjectFind only when the script genuinely needs a value from the matching record. It returns an array, so handle the no-match case before accessing an item.

const records = vaultObjectFind('hr500', 'employees', 'ssn', '999-888-7777');
return records.length > 0 ? records[0]['FirstName'] : '';
ArgumentRequiredDescription
System nameYesThe NIM system that contains the collected table.
Table nameYesThe table to search.
Reference columnYesThe column to search.
Lookup valueYesThe value to match.
Case-sensitive flagNoWhether the comparison must respect letter case.
warning

vaultObjectFind can be computationally expensive. Avoid using it in calculations that run across a large number of records unless there is no simpler model or relation that meets the need. Test with representative data before placing it in a production workflow.

Before using a Vault queryDirect link to Before using a Vault query

  1. Confirm the target system has been collected and its data is current.
  2. Verify the exact system name, table name, and column name in NIM.
  3. For vaultObjectExistsByRef and vaultObjectFind, make sure the lookup column is configured as a reference column.
  4. Return a safe fallback value when no record is found.
  5. Consider an intra-system relation, inter-system relation, or filter lookup when the requirement is a repeatable data relationship rather than a one-off calculation.

For calculation patterns and guidance on safe handling of blank values, return to Custom JavaScript columns.

Last updated on