Syntax and usage for GetFirstValueFromQuery, GetValuesFromQuery, and QueryList functions
In the Lightning Forms Expression Builder, Context placeholder functions allow querying lists so that values from any list can be used in expressions. The functions make use of CAML queries against the SharePoint API, which you can learn more about in this Microsoft documentation.
You can find these functions on the Context tab to the right of the Expression Builder code area. Simply double-click on one of the functions to use it.
The available functions in general are:
GetFirstValueForQuery allows you to retrieve the first value of the specified field in the specified SharePoint list based on the CAML query. Syntax: [[@Site.GetFirstValueForQuery('ListName or relative Url', 'Caml query', 'FieldName')]]
GetValuesForQuery allows you to retrieve multiple values of the specified field in the specified SharePoint list based on the CAML query. Syntax: [[@Site.GetValuesForQuery('ListName or relative Url', 'Caml query', 'FieldName')]]
QueryList allows you to retrieve SharePoint list items with query parameters such as maximum number of rows. Syntax: [[@Site.QueryList('ListName or relative Url', 'Caml query', MaxRowNumber, 'View Fields', 'Viewattributes')]]
Each function is available at either the Site (site collection) or Web (site or subsite) level.
Query Function parameters
1. The first parameter in each function is the name of the list you wish to query. You can use either the user-friendly name of a list in the current site (enclosed in single quotes, e.g. 'Contacts') or the relative URL of a list in the current site collection (e.g. '/sites/Contoso/Clients/Lists/Contacts').
2. The 'Caml query' parameter needs to be a valid CAML query (enclosed in single quotes) against the specified list.
You can read about CAML queries in the reference link at the end of this article. But here is a typical example for Lightning Forms:
<Where><Eq><FieldRef Name="Title"/><Value Type="Text">SomeValue</Value></Eq></Where>
The above query finds an item where the Title equals (Eq) SomeValue. Note that SomeValue can be literal text or (perhaps more likely) a dynamic placeholder from the current form, written as [[SomeField]].
3. The 'FieldName' parameter is the display name of the field that you wish to retrieve from the query.
In the example below, we wish to retrieve the Phone Number of an organization where the Org field of the current form equals the Title of an item in the Organizations list on the current site (assuming the Organization names are unique):
[[@Web.GetFirstValueForQuery('Organizations', '<Where><Eq><FieldRef Name="Title"/><Value Type="Text">[[Org]]</Value></Eq></Where>', 'Phone Number')]]
Coming soon to Lightning Forms will be the ability to use the CAML Query Builder to construct the queries within the Expression Builder Query Functions.
Microsoft CAML query reference
Published April 19, 2024