Create a custom person query

Tip

You can find a demo video, download sample results, and go through a Show me how explanation while you’re building your query. Select these options just above Query setup.

Overview

Each of these steps takes place within one section of the advanced insights app's Custom queries > Person query page.

Note

If you're an existing Viva Insights customer, refer to the note in the Introduction for more information about using the new platform.

To run a person query, you'll follow five basic steps:

1. Set up your query.
2. Add metrics.
3. Add conditions and condition groups.
4. Add employee attributes.
5. Run your query.

In this article, we talk about how to complete each of these steps, and also give some important background information about how metrics, conditions, and attributes work.

Set up your query

Section: Query setup

The following steps are optional. We describe default values below.

Under Query setup:

1. Name your query. Queries are assigned a default name, which follows this format: Query type, user ID, date, and time. Make sure the name is unique.

2. Select a Time period. This field defaults to Last 3 months, but you can select another time period you want your query to analyze. Pick from Last 1 year, Last 6 months, Last 1 month, or a Custom date range. If you choose a Custom date range, use the date picker to select the range.

3. Set the query to automatically update by selecting the Auto-Refresh box. When you select the auto-refresh option, your query automatically runs and computes a new result every time Viva Insights gets updated collaboration data for licensed people. This option is deselected by default, but you can select it on any query where the Time period isn’t customized.

   Note

   If the organizational data used in an auto-refreshing query changes (for example, an attribute name is altered or an attribute is removed), you might see an error when you run the query.

4. Type a Description.

5. Set how the query is grouped. By default, custom person queries are grouped by Month. To change this setting to Week or Day, select More Settings beneath the Description box.

   Selecting More Settings brings you to the More Settings pane. Along with Group by, this pane shows the metric rules that apply to your query. To find out more about metric rules that apply to your query, select See metric rule details.

   Note

   Metrics are criteria used to measure the productivity and wellbeing of employees, and metric rules are rules Viva Insights uses to improve the accuracy of your query results.

To learn more about metrics used in Viva Insights, refer to Metric definitions. To learn more about metric rules, refer to Metric rules.

Add metrics

Section: Select metrics for what you want to know about your employees

1. Under Select metrics for what you want to know about your employees, select the Add metrics button.

2. The Add metrics button brings you to the Select metrics pane. Using the check marks and the tools described later in this section (filter, search, and groupings) select the metrics you want to use in the query, then select Add to query. Learn more about advanced insights metrics.

   The Add to query button adds these metrics into your query and takes you back to the setup screen. The metrics you selected appear as tags in the box beneath the section description.

   

3. You can also add Microsoft 365 Copilot metrics to your custom person query. These metrics provide insights around how employees are using Microsoft 365 Copilot with Microsoft 365 apps, and they’re part of your .csv output file.

   Learn more about the Microsoft 365 Copilot metrics that you can use for your query.

About metrics

Metrics are criteria used to measure the productivity and wellbeing of employees. For example, if you’re wondering how much time employees spend collaborating after their working hours, you could use the After-hours scheduled call hours and After-hours chat hours metrics in your query.

Select metrics pane

Metric categories

In the Select metrics pane, metrics are grouped by metric category. Expand the categories to see which metrics they contain. Let’s say you were looking for the After-hours scheduled call hours and After-hours chat hours metrics in our earlier example. You’d find them in the After-hours collaboration metric category.

Filters, keyword search, and more information

There are a few other ways you can find metrics to include in your query. You can filter by type (for example, Activity count metrics or Meeting metrics) on the left side of the pane, or use the search bar to find metrics by keyword. If you're working with Power BI templates, use Filter by Power BI templates to pick metrics used in particular reports.

To find out more about a metric, hover over its information icon.

Add conditions and condition groups

Section: Select which employees you want to include in the query

1. Underneath the predefined "Is Active" filter, select the Add condition button, then select Organizational data.

   

2. Using conditions and condition groups, add one or multiple filters to narrow your analysis of employees.

   Note

   The default conjunction for conditions and condition groups is “and.” To select “or” instead, use the dropdown menu.

About conditions and condition groups

A condition is a statement about one attribute you want to analyze in your query. A condition only extracts rows from your organizational data that meet certain criteria, which you specify in the condition statement. For example, if your condition statement read, “Organization = Contoso.com,” the query would only extract rows that equal Contoso.com” under the Organization column. A condition group is a combination of conditions connected with a conjunction ("and" or "or"). In the following image, the condition group is in the block to the right of the conjunction "or."

To learn more about filters and conditions, refer to our Filters article.

Is Active

The app predefines one condition for you: “Is Active.” If you leave this condition set to “true,” the query only analyzes active employees. Active employees send at least one email or Teams chat during the unit of time—day, week, or month—defined by the query’s Group by setting.

When you open your query results file, you'll see a Boolean value of "TRUE" or "FALSE" in the IsActive column for each row.

Total and measured employees

Beneath the Add condition and Add condition group buttons, you’ll see a number for Total employees and Measured employees. These numbers represent how many employees could be measured and how many employees the query is actually measuring, respectively. Checking these numbers before running your query can help you determine whether you’ve selected the right conditions and condition groups.

To move and delete conditions and condition groups

To move a condition or condition group, take the following actions:

1. Select the six-dot icon to the right.

2. Drag the six-dot icon above or below other conditions or groups.

   To delete a condition or condition group, select the trashcan icon to the right.

   

Add employee attributes

Section: Select which employee attributes you want to include in the query

1. Select the Select attributes button, then on the right pane, use the checklist to make selections.

2. When you're done picking attributes, select the Add to query button.

   Attributes appear as tags in the box above the Select attributes button.

   Note

   If an attribute appears as a red tag, that attribute might have been removed or renamed. You might see red tags if you’re cloning or editing a query and the attributes have changed since the query was last run. You can remove these marked attributes to get the query to run properly.

About employee attributes

Employee attributes are the data fields—or columns—that you’ve uploaded in your employee data. In Select which employee attributes you want to include in the query, you narrow down which data fields your query includes—for example, Job level or Hire date—to prevent your output (.csv) file from being larger than necessary. Making selections here:

• Improves data analysis with fewer columns in a smaller file.
• Further protects private data by excluding columns from the file.
• Enables you to select Clear all to clear the selected columns.

Run the query

Select the Run button in the screen’s upper right to run the query.

To access your query results

After your query runs, access its results on the Query results page, where you can also edit and clone your query. For further information, refer to Access query results and modify existing queries.

Example person query for after-hours communication

Let’s say you wanted to run a custom person query to find out how often managers are emailing and sending Teams chats after their working hours. You want to:

• Analyze your company’s “West” organization only, which is provided in your employee data.
• See data for the last six months, grouped by month.
• Exclude Senior managers from the query.

Here’s how you might do that:

1. Set up your query.

   1. Query name: Give your query a custom name by typing in something like “AfterHoursWest.”
   2. Time period: Select Last 6 months.
   3. Auto-Refresh: You just want to have this run once, so leave the Auto-Refresh box deselected.
   4. Description: Other analysts in your organization might want to know more about this query, so give it a brief description.
   5. More settings: You want this query to be grouped by month, not week. Select More settings, then change Group by to Month.

2. Add metrics.

   1. Under Select metrics for what you want to know about your employees, select the Add metrics button.
   2. Because you want to add metrics about collaboration after hours, expand the After hours collaboration metric category.
   3. Select the After hours email hours and After hours instant messages metrics.
   4. Select the Add to query button.

3. Specify the employees you want to analyze.

   1. Under Select which employees you want to include in the query, leave the "Is Active" filter set to “true.“
   2. Select Add condition.
   3. Select Organizational data.
   4. Select Organization, leave the Operator at “=,” and select an employee organization of your company from the dropdown list. As we identified earlier, you’d select “West” from this list.
   5. Select Add condition group. You don’t want to include Senior managers in this query, so:
      1. Select Level designation from the Organizational data dropdown.
      2. Leave the Operator at “=.”
      3. If you want, you can use the search bar to help find titles with “Manager.” Select Manager, Sales manager, and Design manager from the dropdown list.
   6. Check the Total employees against the Measured employees. If this number seems off, adjust your conditions above.

4. Choose the employee attributes you want to include in your output file.

   1. Under Select which employee attributes you want to include in the query, select the Select attributes button.
   2. From the right pane, select PopulationType.
   3. Select the Add to query button.

5. Run the query. On the upper right of the screen, select the Run button.

6. After the query successfully runs, find its results in the Query results page. To:

   1. Download the .csv output file: Select the CSV icon from the Downloads column. If you want to connect the query to another file, like a Power BI visualization, you can select the copy link icon.
   2. Edit, Edit query name, Clone, Favorite, or Delete the query: Select the ellipses to the right of the Downloads column, then select the appropriate choice.

   Caution

   Editing queries overwrites existing results. If you want to keep your query’s results, use the Clone feature—which creates an identical copy of the query—instead.

   Note

   Only the analyst who originally ran the query can Edit query name, Edit, or Delete the query. Other analysts in the organization can View, Clone, and Favorite the query.

Related topics

Metric descriptions

Access query results and modify existing queries