Microsoft Graph advanced queries for directory objects are now generally available

Office Add-ins team

We’re excited to announce that all the advanced queries for Azure AD we released in public preview in May are now generally available. This means that these new Microsoft Graph functionalities are fully supported in your production apps and you can access them through the v1.0 endpoint.

To recap, we enhanced the query operators for the following objects and links.

Object Links
Users Member Of, Transitive Member Of, Owned Objects, Registered Devices, Owned Devices, Direct Reports
Groups Members, Transitive Members, Owners
Applications Owners
Service Principals Member Of, Transitive Member Of
Devices Member Of, Transitive Member Of, Registered Users, Registered Owners
Org Contacts Member Of, Transitive Member Of
Administrative Units Members

This enables you to:

  • Count objects, complex properties, and related links.
  • Search on displayName and description fields using tokenization.
  • Filter on new properties with new operators (such as endsWith, in, ne, ge, le).
  • OrderBy on new properties and filtering at the same time.

To use the advanced queries capabilities, you must add the following to your queries:

  • Query String $count = true
  • Header ConsistencyLevel = eventual

Graph Explorer screenshot highlighting count=true Query String parameter and Consistency Level eventual header.

What’s new since May?

Other than stability, availability, and performance improvements, we added new $filter operators:

  • NotEqual (on all properties)
  • endsWith (on mail and userPrincipalName)

Here a couple of examples:

GET ../users?$count=true&$filter=officeLocation ne null
GET ../users?$count=true&$filter=endsWith(mail, '')

We also indexed new properties, enabling sorting and filtering.

Property Filter Order by Example
Soft-Deleted DateTime Supported Supported GET
Group’s expiration DateTime Supported GET
Device’s approximate Last Sign in DateTime Supported Supported GET

Finally, we added the support for extension properties and on-premises extensions:

../users?$count=true&$filter=extension_<AppId>_<PropName> eq '<value>'
../users?$count=true&$filter=onPremisesExtensionAttributes/extensionAttribute1 eq '<value>'

You’ll see the implementation of these new capabilities in the Azure Portal soon.

Access with PowerShell

You can also access many of these functionalities with the IT admin’s favorite scripting language: PowerShell.

The Microsoft Graph PowerShell SDK is a collection of PowerShell modules that contain cmdlets for calling Microsoft Graph.

PowerShell screenshot showing the Microsoft Graph SDK in action, getting the list of users in the tenant

To get started:

  1. Install Windows Terminal (optional).
  2. Install PowerShell Core.
  3. Open PowerShell Core in Windows terminal.
  4. Install-Module Microsoft.Graph -Repository PSGallery
  5. List the available commands (optional): Get-Command -Module Microsoft.Graph*
  6. Import-Module Microsoft.Graph.Authentication
  7. Connect-Graph -Scopes "User.Read.All"
  8. Import-Module Microsoft.Graph.Users
  9. Get-MgUser

If you’d like to use the advanced query capabilities, you need to add the ConsistencyLevel eventual and count parameter to your queries:

get-mguser -consistencyLevel eventual -count userCount -search '"displayName:room"'

PowerShell screenshot showing the user search command and result set

Note: if you need to use search, remember to escape it with the single quote character like in the example above. $userCount variable will contain the result-set count.

Access with .NET

As a .NET developer, there is nothing better than to have a simple SDK to access the power of our queries. We created a sample .NET Core app that mimics Graph Explorer, where you can use the advanced filter, search, and orderBy clauses.

The following screenshot shows the Not Equal filtering in action.

Screenshot of the sample app using the Microsoft Graph .NET SDK

Are you an OData Wizard?

We created a challenging quiz to test your knowledge of Microsoft Graph and directory objects. This will help you learn about the nuances of Microsoft Graph, OData, and Azure AD.

If you think you got all the answers right, and you want to be contacted by engineers working on the Microsoft Graph Identity workload, leave your mail in the last question. We would like to hear from you!

Current limitations and next steps

The new advanced query capabilities are not yet available in B2C tenants. We are working to implement the support for it, but we don’t have any date to communicate yet. Please follow this blog or read What’s new in AAD for updates.

As usual, we’re eager to know what you think about the new capabilities to help us shape the future direction of our APIs. The Microsoft Graph UserVoice is always open, and we also created this specific survey to share your feedback. We’re listening!

Feedback usabilla icon