Groups concepts (preview)

A group in Azure Device Registry (ADR) is a query-defined set of homogeneous resources that you use to target fleet-scale operations, such as software updates. In the current preview, a group targets IoT Hub-connected devices. Instead of managing individual resources, you define a filter once and reuse the resulting group wherever you need to act on that set of resources.

Service applicability

In this preview, groups support IoT Hub-connected devices in an Azure Device Registry namespace.

Query-defined membership

You create a group by defining a filter against supported resource properties, such as manufacturer or software revision. In the preview, the only supported Azure resource type is RegistryDevice. Azure Device Registry evaluates the filter within the namespace and populates the group with every matching resource.

A group filter can contain up to 255 characters. Use * to include all devices in the ADR namespace, or a WHERE clause to select matching devices. Don't include SELECT or FROM.

For RegistryDevice groups, use query-language property names in the filter. For example:

WHERE manufacturer = 'Fabrikam' AND model = 'VX900'

For properties that support IN or NIN, provide values in an array. For example:

WHERE name IN ['sensor-01', 'sensor-02']

A device can belong to more than one group at the same time. For example, a device might match both a "firmware version 2.1" group and a "building 12" group. Membership isn't exclusive, so you can compose groups around different operational needs without duplicating devices.

RegistryDevice supported properties and operators

The following table shows the supported properties and operators for RegistryDevice filter queries:

RegistryDevice supported update properties and operators

The following table shows the supported properties and operators for RegistryDevice filter queries within the attributes.update scope:

You can combine conditions with AND, OR, NOT, parentheses, and comparisons to null. Scalar functions such as STARTSWITH, CONTAINS, IS_NULL, and IS_DEFINED, field-to-field comparisons, and arbitrary properties.* or attributes.* paths aren't supported.

Cached membership and refresh

Group membership is calculated and cached at refresh time—it isn't evaluated in real time. When you create a group, or when you refresh an existing one, Azure Device Registry re-evaluates the filter and updates the cached member list.

You trigger a group refresh through the RefreshMembers operation. Refresh is asynchronous, and the group's membershipState can be Creating, RefreshingMembers, Ready, or FailedToResolveMembers. Wait for Ready before using the newly resolved membership.

Because membership is cached, a group's member list can be stale between refreshes. If a resource's properties change, or a new resource starts matching the filter, that change isn't reflected in a manual-refresh group's member list until the next refresh completes. The service enforces a minimum one-hour interval between manual refreshes.

Immutable filters and lifecycle

You can edit a group's display name and description. The resource name and query filter are fixed at creation. To target a different set of devices, create or clone a group with a new filter.

Deleting a group removes only the group; its member devices remain. You can't delete a group while it has active or scheduled job runs. Wait for those runs to finish or remove them before deleting the group.

Manage groups through the REST API

Manage groups programmatically with the Groups REST API, using api-version=2026-11-02-preview.

ListMembers returns each member's ARM resource ID in members[].id. Use CountMembers to get the group's member count. For paging, see Limits and preview restrictions.

Manage groups in the Azure portal (preview)

In the ADR namespace navigation, under Fleet, select Groups (preview). The list shows each group's name, member count, description, provisioning state, and last-updated time.

Select a group to open its Overview page. Expand Essentials to see its display name, description, member count, and last-updated time. Select Definition to open the Group definition pane and view the read-only query filter. Use this filter to confirm which devices the group targets.

The member list previews up to 10 devices and shows the total member count. For example, a group with 50 members shows "Previewing 10 of 50 members." The preview includes device status, manufacturer, model, provisioning state, and last-updated time. Treat it as a spot check, not a complete listing of a large group.

From the groups list or the group detail view, you can take the following actions:

• Create a group from the list view by providing a required name, an optional description, and a query filter.
• Clone an existing group from the list or detail view. Cloning is the practical way to start from a group's definition when you need adjusted membership criteria, because you can't edit the original filter.
• Edit a group's display name and description from the detail view. The resource name and query filter don't change.
• Refresh a group's cached membership from the detail view, subject to the refresh limits described in Cached membership and refresh. Refresh on the groups list reloads the list; it doesn't recalculate membership.
• Delete a group from the list or detail view. You confirm the deletion by entering the group name.

When you create a group, enter its membership criteria on the Query filter step.

Relationship to jobs and software updates

Groups define which devices to target; jobs define the operation to run. In this preview, a group can be the target of one software update job. To create a different software update job for the same group, delete the existing job first.

Onboarding update jobs target an ADR namespace directly, not a group. For more information, see Jobs concepts (preview).

Group-targeted reports

The preview REST API also uses groups as targets for software update reports:

• GroupBestUpdatesComplianceReport describes the best available updates and update compliance for devices in the group.
• GroupInstallableUpdatesReport lists installable updates and the devices they target.

Request a report with the namespace's generateReport operation, specifying the report type and target group. Retrieve the result with getLatestReport.

Limits and preview restrictions

The following limits currently apply to groups:

• Up to 100 groups per ADR namespace.
• A minimum one-hour interval between manual refreshes.
• ListMembers returns up to 1,000 members per page, with no filtering or sorting in this preview. Set pageSize to request a smaller page and pass the returned skipToken in the next request to continue listing members.

Related content

• Jobs concepts (preview)
• Software updates concepts (preview)
• Groups REST API reference