Dynamic Linq Query Language

Dynamic Linq

Dynamic Linq is a data query language used for complex query building in multiple SystemLink APIs. Clients may use the Dynamic Linq query language to build filter expressions, which specify data queries in several SystemLink services.

Dynamic Linq is open-source, and its core documentation is available here.

Supported Versions

As of SystemLink 19.5, the following SystemLink services leverage Dynamic Linq:

• Asset Performance Management
• Notebook Execution
• Systems Management
• Test Monitor

Query Language

This section provides a brief overview of the supported features in the Dynamic Linq query language. For a more in-depth description of the language itself, refer to the open-source documentation here.

Types

Dynamic Linq is a strongly typed expression language. Every identifier is associated with a type, and may only be operated on according to the properties of that type. The base set of supported types include:

• Boolean - Either true or false.
• String - Represents a sequence of characters.
• Int32 - Represents a signed integer.
• UInt32 - Represents an unsigned integer.
• Int64 - Represents a signed long integer.
• UInt64 - Represents an unsigned long integer.
• Double - Represents a 64-bit floating-point value.
• Object - Represents a JSON object.
• DateTime - Represents a date and time.
• TimeSpan - Represents an interval or length of time.
• List<T> - Represents a homogeneous ordered sequence of values.
• Dictionary<TKey, TValue> - Represents a set of key-value pairs.
• Variant - Represents any type above. This type is implicitly convertible to any other type.

These types are common to all SystemLink APIs. Note that specific APIs may define custom types in addition to the types listed above.

In general, conversions between all numeric types (Int32, UInt32, Int64, UInt64, Double) are implicitly performed by the query language.

DateTimes

DateTimes are represented as ISO-8601 formatted timestamps within a string. Although they appear like strings, they support all DateTime comparison operators.

Example:

startedAt < "2019-08-13T20:50:46Z"

TimeSpans

TimeSpans are represented as strings using Microsoft's TimeSpan format. In general, a TimeSpan string is represented as {days.hours:minutes:seconds.milliseconds}.

Example:

myTimeSpan < "6.12:30:45.5"

The above query will match objects whose myTimeSpan value is less than 6 days, 12 hours, 30 minutes, and 45.5 seconds.

Keywords

The following keywords are supported in filter expressions.

• it - Represents the current instance, depending on the scope of the expression. This is commonly used in Any() expressions, for example:

keywords.Any(it.Contains("abc"))

• null - A literal representing the absence of a value. null may be implicitly converted to any other type.
• true - A constant literal which represents the true Boolean value.
• false - A constant literal which represents the false Boolean value.

Operators

The following operators are supported in filter expressions.

Name	Example	Description
Logical AND	x and y, x && y	Logical AND between two expressions. The expressions must be of type Boolean.
Logical OR	x or y, x || y	Logical OR between two expressions. The expressions must be of type Boolean.
Logical Negation	!x	Negates a logical expression. The expression must be of type Boolean.
Equals	x = y, x == y	Compares two expressions for equality.
Not Equals	x != y	Compares two expressions for inequality.
Greater Than	x > y	Compares two expressions of a numeric type.
Greater Than Or Equals	x >= y	Compares two expressions of a numeric type.
Less Than	x < y	Compares two expressions of a numeric type.
Less Than Or Equals	x <= y	Compares two expressions of a numeric type.
Member Access	x.y	Accesses a sub-member of an object.
List Bracket Access	x[y]	Accesses a member of a list by index. x must be of type List and y must be an integer literal type.
Dictionary Bracket Access	x[y]	Accesses a member of a dictionary by key. x must be of type Dictionary and y must be a literal whose type is convertible to the key type of the dictionary.
Method Invocation	x.y(...)	Invokes a method on a type.
Parentheses	(x and y) or z	Specifies the order of operations in a complex query.

Methods

The following methods are supported on certain types.

Base Type	Example	Description
String	x.Contains("y")	Checks whether a string contains another string.
List	x.Contains(y)	Checks whether a List contains a specified member.
List	x.Any(expr)	Checks whether a list contains any elements that match a specified condition. The condition is given as a Boolean filter expression, expr.
List	x.All(expr)	Checks whether all elements in a list match a specified condition. The condition is given as a Boolean filter expression, expr.

Type Conversion

The .NET Convert API is supported for explicit conversion between data types. These methods will throw if the input data is not convertible, so they're not suitable for many use cases. Some SystemLink Enterprise back-ends provide a SafeConvert.ToDecimal implementation, which will return null on non-convertible inputs.

Support for SafeConvert.ToDecimal:

Service	Version	Comments
TestMonitor	SystemLink Enterprise 2023-10	query-results version 4

Constants

Constant values are supported within queries. The following constants are supported in filter expressions.

Constant	Type	Description
Math.PI	Double	Represents the mathematical constant pi.
Math.E	`Double	Represents the mathematical constant e.

Best Practices

When using the Dynamic Linq query language, keep the following best practices in mind.

Use it-expressions instead of lambda expressions.

This helps prevent identifier scoping issues.

Bad:

keywords.Any(k => k.Contains("y"))

Good:

keywords.Any(it.Contains("y"))

Represent Enum literals in PascalCase.

This provides consistency when dealing with enum values which contain multiple words in the name, such as TimedOut.

Bad:

status.statusType == "PASSED"

Good:

status.statusType == "Passed"

Use List.Contains() instead of List.Any() when comparing single values for equality in lists.

Contains() is slightly more performant than Any(), so prefer it whenever possible.

Bad:

keywords.Any(it == "123")

Good:

keywords.Contains("123")

Comparing keys and values in nested collections

Nested collections like data.parameters in the TestMonitor steps API do not support the full set of Dynamic Linq expressions.

In many cases, !string.IsNullOrEmpty(it[<key>]) can be used instead of ContainsKey. Note that string.IsNullOrEmpty will match: missing keys, null values, and empty string values. !string.IsNullOrEmpty will match everything else.

Contains and !Contains can be used to compare against values in the data.parameters dictionaries. Neither Contains nor !Contains will match missing keys.

Not supported:

data.parameters(it.ContainsKey("measurement"))
data.parameters(p => string.IsNullOrEmpty(p["measurement"])
data.parameters(p => p["measurement"].Contains("substring"))

Good:

data.parameters(string.IsNullOrEmpty(it["measurement"])
data.parameters(!string.IsNullOrEmpty(it["measurement"])
data.parameters(it["measurement"].Contains("substring"))
data.parameters(!it["measurement"].Contains("substring"))

Asset Performance Management

The Asset Performance Management services use Dynamic Linq to filter asset data.

Assets

The following properties are valid in filter expressions passed to Asset Performance Management:

Property	Type	Description
assetIdentifier	String	String representing the unique identifier of an asset.
assetClass	Enum	String enumeration representing the class of an asset. Possible values are: UNDEFINED, DISCOVERED, ASSET, DUT, FIXTURE.
serialNumber	String	String representing the serial number of an asset.
modelName	String	String representing the model name of an asset.
modelNumber	UInt32	Unsigned integer representing the model number of an asset.
vendorName	String	String representing the vendor name of an asset.
vendorNumber	UInt32	Unsigned integer representing the vendor number of an asset.
assetName	String	String representing the asset name.
firmwareVersion	String	String representing the firmware version of an asset.
hardwareVersion	String	String representing the hardware version of an asset.
busType	Enum	String enumeration representing the bus type of an asset. Possible values are: BUILT_IN_SYSTEM, PCI_PXI, USB, GPIB, VXI, SERIAL, TCP_IP, CRIO, SCXI, CDAQ, SWITCH_BLOCK, SCC, FIRE_WIRE, ACCESSORY, CAN, SWITCH_BLOCK_DEVICE.
isNIAsset	Boolean	Boolean flag specifying whether the asset is an NI asset or a third-party asset.
keywords	List<String>	Collection of string values representing asset metadata keywords. Example: 'Keywords=["keyword1", "keyword2"]'.
properties	Dictionary<String, String>	Collection of key-value pairs, each key-value pair representing an asset metadata property. Example: 'Properties=["key1":"value1", "key2":"value2"]'.
location.minionId	String	String representing the identifier of the minion in which the asset is located in.
location.systemName	String	String representing the name of the system that the asset is located in.
location.slotNumber	UInt32	Unsigned integer representing the slot number the asset is located in.
location.assetState.systemConnection	Enum	String enumeration representing the connection state of the system the asset is currently located in. Possible values are: APPROVED, DISCONNECTED, CONNECTED_UPDATE_PENDING, CONNECTED_UPDATE_SUCCESSFUL, CONNECTED_UPDATE_FAILED, UNSUPPORTED, ACTIVATED.
location.assetState.assetPresence	Enum	String enumeration representing the present status of an asset in a system. Possible values are: INITIALIZING, UNKNOWN, NOT_PRESENT, PRESENT.
supportsSelfCalibration	Boolean	Boolean flag specifying whether the asset supports self-calibration.
selfCalibration.calibrationDate	DateTime	ISO-8601 formatted timestamp string specifying the last date the asset was self-calibrated. Example: "2018-05-20T00:00:00Z"
supportsExternalCalibration	Boolean	Boolean flag specifying whether the asset supports external calibration.
externalCalibration.calibrationDate	DateTime	ISO-8601 formatted timestamp string specifying the last date the asset was externally-calibrated. Example: "2018-05-20T00:00:00Z"
externalCalibration.nextRecommendedDate	DateTime	ISO-8601 formatted timestamp string specifying the recommended date for the next external calibration. Example: "2018-05-20T00:00:00Z"
externalCalibration.recommendedInterval	Int32	Integer representing the manufacturer-recommended calibration interval, in months.
externalCalibration.comments	String	String representing any external calibration comments.
externalCalibration.isLimited	Boolean	Boolean flag specifying whether the last external calibration was a limited calibration.
externalCalibration.operator.displayName	String	String representing the name of the operator which performed an external calibration on a third-party asset.

Notebook Execution

The Notebook Execution service uses Dynamic Linq to filter notebooks and executions.

Notebooks

The following properties are valid in notebook filter expressions passed to Notebook Execution:

Property	Type	Description
path	String	String representing the path of the notebook.
createdAt	DateTime	ISO-8601 formatted timestamp specifying when the notebook was created.
updatedAt	DateTime	ISO-8601 formatted timestamp specifying when the notebook was last modified.
parameters	Object	Input parameters of the notebook and their default values. The values may be of any valid JSON type.
metadata	Object	Metadata associated with the notebook. Metadata values may be of any valid JSON type.

Executions

The following properties are valid in execution filter expressions passed to Notebook Execution:

Property	Type	Description
id	String	String representing the ID of the execution.
notebookPath	String	The path of the notebook associated with this execution.
parameters	Object	Input parameters of the notebook. The values may be of any valid JSON type.
executionHash	String	String representing the hash of this execution.
timeout	Int32	The number of seconds the execution runs before it aborts if uncompleted.
status	Enum	String enum representing the status of the execution. Possible values are QUEUED, IN_PROGRESS, FAILED, SUCCEEDED, CANCELED, and TIMED_OUT.
queuedAt	DateTime	ISO-8601 formatted timestamp specifying when the notebook execution was queued.
startedAt	DateTime	ISO-8601 formatted timestamp specifying when the notebook execution was started.
completedAt	DateTime	ISO-8601 formatted timestamp specifying when the notebook execution was completed.
exception	String	String containing exception information.
result	Object	Object containing the result of the executed notebook. The values may be of any valid JSON type.

Systems Management

The Systems Management services use Dynamic Linq to filter jobs and systems.

Jobs

The following properties are valid in job filter expressions passed to Systems Management:

Property	Type	Description
jid	String	String representing the ID of the job.
id	String	String representing the ID of the system.
createdTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the date when the job was created.
lastUpdatedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the last date the job was updated.
dispatchedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the date when the job was actually sent to the system.
state	String	String representing the state of the job.
metadata	Object	Object containg the metadata of the job. Example: metadata.queued
config.user	String	String representing the user who created the job.
config.tgt	List<String>	List of strings representing the targeted systems. Example: config.tgt.Contains("id")
config.fun	List<String>	List of strings representing the functions to be executed within the job. Example: config.fun.Contains("nisysmgmt.set_blackout")
config.arg	List<List<Variant>>	An array of arrays of variable type elements that are arguments to the function specified by the "fun" property. Example: config.arg[0].Contains("test")
result.return	List<Object>	An array of objects representing return values for each executed function. Example: result.return[0].Contains("Success")
result.retcode	List<Int32>	An array of integers representing code values for each executed function. Example: result.retcode
result.success	List<Boolean>	An array of Booleans representing success values for each executed function. Example: result.success.Contains(false)

Systems

The following properties are valid in system filter expressions passed to Systems Management:

Property	Type	Description
id	String	String representing the ID of the system.
createdTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the date when the system was registered.
lastUpdatedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the last date the system was updated.
alias	String	String representing the alias of the system.
activation.lastUpdatedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the last date the system activation was updated.
activation.data.activated	Boolean	Boolean representing whether the system is activated or not.
activation.data.licenseName	String	String representing the name of the license.
activation.data.licenseVersion	String	String representing the license version.
connected.lastUpdatedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the last date the system connection was updated.
connected.data.state	String	String representing the state of the system.
grains.lastUpdatedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the last date the system grains were updated.
grains.data	Dictionary<String, Object>	Dictionary of string to object representing general information about the system. Example: grains.data.os == "Windows"
packages.lastUpdatedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the last date the system installed packages were updated.
packages.data	Dictionary<String, Variant>	Dictionary representing software packages installed on the system. Example: packages.data["ni-package-manager-upgrader"].version: String representing the installed version of ni-package-manager-upgrader package.
feeds.lastUpdatedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the last date the system configured feeds were updated.
feeds.data	Dictionary<String, String>	Dictionary representing the feeds configured on the system.
sysapi.lastUpdatedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the last date the system sysapi data was updated.
sysapi.data	Dictionary<String, Variant>	Dictionary representing system API information of a system.
groups.lastUpdatedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the last date the system groups data was updated.
groups.data	List<String>	Array of strings representing the IDs of the groups the system is assigned to. Example: groups.data.Contains("id")
keywords.lastUpdatedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the last date the system keywords were updated.
keywords.data	List<String>	Array of strings representing the keywords of the system. Example: keywords.data.Contains("test")
properties.lastUpdatedTimestamp	DateTime	ISO-8601 formatted timestamp string specifying the last date the system properties were updated.
properties.data	Dictionary<String, String>	Dictionary of string to string representing metadata information about a system. Example: properties.data.owner == "admin"

Test Monitor

The Test Monitor service uses Dynamic Linq to filter products, results, and steps.

Products

The following properties are valid in product filter expressions passed to Test Monitor:

Property	Type	Description
id	String	String representing the ID of the product.
partNumber	String	String representing the part number of the product.
name	String	String representing the name of the product.
family	String	String representing the product family of the product.
updatedAt	DateTime	ISO-8601 formatted timestamp specifying when the product was last updated.
keywords	String[]	Array of user-defined metadata strings associated with the product.
properties	Dictionary<String, String>	Dictionary of string key-value pairs of user-defined metadata associated with the product.
fileIds	String[]	An array of string which represent files attached to this product.
updatedWithin	TimeSpan	A span of time indicating the difference between when this product was last updated (updatedAt) and the current server time.
workspace	String	(SystemLink Enterprise Only) The ID of the workspace to which the product belongs to.
workspaceName	String	(SystemLink Enterprise Only) The name of the workspace to which the product belongs to. This property only supports comparison operators, such as ==, !=, and >. Methods such as Contains() or Any() are not supported.

Results

The following properties are valid in result filter expressions passed to Test Monitor:

Property	Type	Description
id	String	String representing the ID of the result.
status.statusType	Enum	String enumeration representing the current state of the test result. Possible values are Looping, Skipped, Custom, Done, Passed, Failed, Running, Waiting, Terminated, Errored, and TimedOut.
status.statusName	String	A custom display name string describing the status of the test result.
startedAt	DateTime	ISO-8601 formatted timestamp specifying when the test started.
updatedAt	DateTime	ISO-8601 formatted timestamp specifying when the result was last updated.
programName	String	String representing the name of the test program which was executed to produce this result.
systemId	String	String representing the ID of the system on which this test was executed.
systemAlias	String	(Not available in SystemLink Enterprise) The Systems Management alias of the system referred to by systemId. This property only supports comparison operators, such as ==, !=, and >. Methods such as Contains() or Any() are not supported.
hostName	String	String representing the host name of the system on which this test was executed.
operator	String	String representing the operator of the test result.
serialNumber	String	String representing the serial number of the UUT.
product	String	String representing the product type of the test. Deprecated and replaced by partNumber.
partNumber	String	String representing the part number of the device under test.
productName	String	The name of the product associated with the test. This property only supports comparison operators, such as ==, !=, and >. Methods such as Contains() or Any() are not supported.
totalTimeInSeconds	Double	The total time, in seconds, that the test took to execute.
keywords	String[]	Array of user-defined metadata strings associated with the result.
properties	Dictionary<String, String>	Dictionary of string key-value pairs of user-defined metadata associated with the result.
fileIds	String[]	An array of string which represent files attached to this test result.
dataTableIds	String[]	(SystemLink Enterprise Only) An array of string which represent data tables attached to this test result.
startedWithin	TimeSpan	A span of time indicating the difference between when this test started (startedAt) and the current server time.
updatedWithin	TimeSpan	A span of time indicating the difference between when this test was last updated (updatedAt) and the current server time.
workspace	String	The ID of the workspace to which the result belongs to.
workspaceName	String	The name of the workspace to which the result belongs to. This property only supports comparison operators, such as ==, !=, and >. Methods such as Contains() or Any() are not supported.

Steps

The following properties are valid in step filter expressions passed to Test Monitor:

Property	Type	Description
stepId	String	A string which uniquely identifies this step within its corresponding test result.
name	String	String representing the name of this test step.
stepType	String	String representing the type of this test step.
parentId	String	The stepId of this step's parent.
resultId	String	The id of this step's associated result.
path	String	String containing the name fields for all ancestor steps, separated by dots.
pathIds	String[]	Array of stepId fields for all ancestor steps.
status.statusType	Enum	String enumeration representing the current state of the test step. Possible values are Looping, Skipped, Custom, Done, Passed, Failed, Running, Waiting, Terminated, Errored, and TimedOut.
status.statusName	String	A custom display name string describing the status of the test step.
totalTimeInSeconds	Double	The total time, in seconds, that the step took to execute.
startedAt	DateTime	ISO-8601 formatted timestamp specifying when the step started.
updatedAt	DateTime	ISO-8601 formatted timestamp specifying when the step was last updated.
inputs	NamedValue[]	Array of objects, each with a String name and a variant value, representing the parameters of the test step.
outputs	NamedValue[]	Array of objects, each with a String name and a variant value, representing the outputs of the test step.
dataModel	String	String representing the structure of the associated data object.
data.text	String	String containing custom text associated with this step.
data.parameters	List<Dictionary<String, String>>	A list of sets of string key-value pairs containing custom metadata such as limits and measurements.
startedWithin	TimeSpan	A span of time indicating the difference between when this step started (startedAt) and the current server time.
updatedWithin	TimeSpan	A span of time indicating the difference between when this step was last updated (updatedAt) and the current server time.
hasChildren	Boolean	Boolean indicating whether the step has child steps.
keywords	String[]	(SystemLink Enterprise Only) Array of user-defined metadata strings associated with the step.
properties	Dictionary<String, String>	(SystemLink Enterprise Only) Dictionary of string key-value pairs of user-defined metadata associated with the step.
workspace	String	(SystemLink Enterprise Only) The ID of the workspace to which the result belongs to.
workspaceName	String	(SystemLink Enterprise Only) The name of the workspace to which the result belongs to. This property only supports comparison operators, such as ==, !=, and >. Methods such as Contains() or Any() are not supported.

Paths

The following properties are valid in path filter expressions passed to Test Monitor:

Property	Type	Description
id	String	String representing the ID of the path.
programName	String	String representing the name of the test program which was executed to produce this path.
partNumber	String	String representing the part number of the device under test.
path	String	String representing the path of the test program.

Constants

The following constants are valid in any filter expression passed to Test Monitor:

Constant	Type	Description
Constants.CurrentDay	TimeSpan	The elapsed time between now and the start of the current day, in the server's timezone.
Constants.CurrentWeek	TimeSpan	The elapsed time between now and the start of the current week, in the server's timezone.
Constants.CurrentMonth	TimeSpan	The elapsed time between now and the start of the current month, in the server's timezone.
Constants.CurrentYear	TimeSpan	The elapsed time between now and the start of the current year, in the server's timezone.