SharePoint Online - Query a list

Use the SharePoint Online - Query a list action A tool for building the processes, logic, and direction within workflows. to query a list of items within a specified SharePoint Online site. You can add conditions to limit the returned query results.

For example, you can use this action to automate a reimbursement process. The accounts team may look for employees who have raised reimbursement requests. You can also set conditions to query employees from a location or team.

Before you start 

Configure the SharePoint Online - Query a list action

The steps required to configure the action are given below. The SharePoint Online - Query a list action fields and settings table describes all the required and optional configuration fields.

  1. Select a Connection.
  2. Note: Only the connections created with the List and libraries authentication method are available in the drop-down. For more information about authentication methods for SharePoint Online connections, see Connectors.

  3. Type a SharePoint site URL and click Retrieve lists.

    Example:https://domain.sharepoint.com/sites/hr

  4. Select the List name that you want to query.
  5. Caution: Querying and retrieving items from lists that contain 12 or more columns of the People, Lookup, or Managed Metadata type can cause a list view threshold error.

  1. Type a value for Item limit.

Retrieve the first item from the query results

The following example shows how the first item that is returned from the query can be retrieved. The following actions are used in this example:

In the Designer page:

Retrieve items from the query results

The Loop for each action can be used to retrieve items from a SharePoint Online list as described in the steps below. The following actions are used in this example:

In the Designer page:

SharePoint Online - Query a list action fields and settings

Important: Before inserting variables in the action configuration, you must manually type or select the values and populate other dependent fields in order to retrieve the output data. Once configured, you can insert variables to the required fields.

Section Field Description Variable types
(unlabeled)

Connection Credentials and other settings required to pass data between the workflow and the indicated service, which could be a cloud service, business application, or content store.

SharePoint Online connection for the list you want to query.

To refresh the available connections , click .

(n/a)
Source list

SharePoint site URL

The URL of the SharePoint Online site containing the list you want to use.

To retrieve the lists from the SharePoint site, type the SharePoint site URL and click Retrieve lists.

Example:https://domain.sharepoint.com/sites/hr

Boolean, Collection, DateTime, Decimal, Integer, Text

 

List name

The name of the list you want to query. The drop-down list is limited to lists and document libraries within the site specified in SharePoint Online site URL.

Boolean, Collection, DateTime, Decimal, Integer, Text

 

Item limit

Highest number of rows to return in the query. Accepts either typed text or an inserted variable.

Integer

Conditions Add conditions/Edit conditions

Conditional statements to use for the query. For example, to query for stale items, you might configure a condition "Modified is before <yourDateVariable>."

Note: For conditions involving columns with multiple values, you need to create conditions for each available value and select And or Or options accordingly.

Displays the condition builder to define new conditions or edit existing conditions.

  • Add conditions - Displayed when there are no existing conditions specified for the action.

  • Edit conditions - Displayed when there are existing conditions set for the action. You can edit the conditions.

The Condition builder supports nested conditions, enabling you to create conditions within another condition.

(n/a)
Condition builder When

Displays the items from the Column field of the selected SharePoint list.

Note: 

The following columns are not supported in the Condition builder:

  • Calculated

  • Hyperlink

  • Managed Metadata

  • Multiple lines of text

Note: If the list contains more than 5000 items, an index must be created for the column. For more information, see Add an index to a SharePoint column.

Text, Decimal, Integer, Boolean, DateTime, Collection
  Operator

How the item from the When drop-down and Value are compared. Select from the drop-down.

The operators available in the drop-down depend on the data type of the item selected from the When drop-down.

(n/a)
  Value

The value you are expecting in the column (field) specified for When.

The data type of Value must match the data type of the item selected in the When drop-down.

(varies)
  Add

Adds a new condition. When adding a new condition you have to select the level of the condition.

Select Nested condition to nest the new condition within the condition above it.

(n/a)
  And/Or

The connecting operator to use for the conditions. If you select:

And: The workflow starts when the item that is added matches all the conditions.

Or: The workflow starts when the item that is added matches any one of the conditions.

(n/a)
  Edit

Displays the following options menu for a condition. The following options are available:

  • Promote: Promotes the condition to a higher level. Promote option is shown if the condition is nested within another condition and allows you to move it to a higher level.

  • Demote: Demotes the condition to a lower level. If you demote a condition it is moved to a lower level making it nested within the condition immediately above it.

  • Delete: Deletes the selected condition.

(n/a)
Sorting

Sort by

Allows you to select the column by which you want to sort a query result.

The columns displayed in the drop-down list are associated with the SharePoint Online list you specify in the List name field. You can also insert a variable, which you can use to specify either the display name or internal name of the column.

You can sort a column in ascending or descending order:

  • Ascending: Sort the list items of a column in ascending order.

  • Descending: Sort the list items of a column in descending order.

The sort order you select is applicable to the Item ID(s), Items, and First item output variables.

Note: Sorting the Managed Metadata column is not supported.

(n/a)

Output

Result

Stores the result of the action as an object with the following variables:

  • Number of items returned: Integer variable to store the total number of items retrieved from this query.
  • Item ID(s): Collection variable to store the ID(s) of all the returned items.
  • Items: Collection of objects with all columns from that list.
  • First item: Object variable that contains the properties of the first item in a query.

Note: Item ID(s), Items, and First item can be arranged, depending on the sort order selected in the Sorting section.

Object A variable that groups several related variables of any type into a hierarchical structure. Objects can contain other Objects.