Introduction to midPoint Query Language

Last modified 10 Jun 2025 10:32 +02:00
Table of Contents

This page introduces the structure of the midPoint Query Language (MQL) and describes available filters.

Language Description

MQL is designed to construct complex queries.

A query is a combination of a filter and additional parts, such as paging and sorting.

Simple filters usually take the form of triplets consisting of:

  • Item path: Specifies the searchable item to which the filter is applied.

  • Filter name: Defines the name of the filter.

  • Value: Defines a value literal or item path that should be matched according to the filter specification. Note that strings need to be enclosed in quotes (') or double-quotes (").

Some examples of valid filters are:

  • fullName = "John Doe"

  • givenName startsWith "J"

  • activation/effectiveStatus = "enabled"

Item Path

Item path specifies the item by which data are filtered. In its simplest form, it is a name of an object property, or names of items and containers separated by slashes, such as:

  • fullName

  • activation/administrativeStatus

  • attributes/uid

For details, refer to Item path.

Filter Name

The filter name, or its alias, specifies a filtering condition that should be used.

Value

Values are usually string literals enclosed in double quotes. However, values can take various forms. For example, a value may be a path to another item, e.g. when the query compares two items.

In some cases, values may be complex. The exact form of the value part of the filter depends on the operator and the type of the value.

Querying Values of Different Types

The exact syntax of queries for values of different types is described in the following table:

Type Query Note

boolean

extension/coreMember = true

Boolean values do not require quotes. Valid values are true and false.

string

emailAddress endsWith "testorg.com"

String values are enclosed in quotes (') or double quotes (").

PolystringType

givenName = 'Adam'

Values of the polystring type are enclosed in quotes (') or double quotes (").

int

extension/height > 170

Number values do not require quotes. Only common property filters (=,>, ..) are defined for number types.

float

extension/perfScore > 1.05

Number values do not require quotes. Only common property filters (=,>, ..) are defined for number types.

dateTime

metadata/createTimestamp >= "2024-03-01"

DateTime values are enclosed in quotes (') or double quotes ("). They can be compared as dates, or as date and time (following the ISO-8601 format).

metadata/createTimestamp >= "2024-03-01T15:30:00"

While comparing time values, datetime values entered without a timezone are considered to be in the same timezone as the running midPoint.

extension/empStartDate >= "2019-10-01" and extension/empStartDate < "2019-10-02"

As datetime values contain the exact time value (down to milliseconds), you need to compare dates as intervals.

ObjectReferenceType

assignment/targetRef/@/name = "End user"

Object references are queried using the matches filter, or the dereferencing operator @. See Advanced filters.

QName

assignment/targetRef matches (relation=owner)

QName values (a relation in this example) are entered into queries without quotation marks.

assignment/targetRef matches (relation=org:owner)

QNames may use namespaces. Unless values conflict, namespaces are not necessary in queries. In this case, both relation=owner and relation=org:owner return the same results.

Simple Filters

Comparison Filters

The following table summarizes common comparison filters:

Name Alias Description

equal

=

Matches items equal to a value.

not equal
notEqual

!=

Matches items different from a value.

less

<

Matches items smaller than a value.

lessOrEqual

<=

Matches items smaller or equal to a value.

greater

>

Matches items greater than a value.

greaterOrEqual

>=

Matches items greater or equal to a value.
Examples of using comparison filters on users:
familyName = "Doe"

Equals filter, searches for all users with the familyName of "Doe".

familyName = ("Doe", "Smith")

Equals multi-value filter, searches for all users with the familyName of "Doe" or "Smith".

name != "Administrator"

Not equals filter, searches for everyone except for "Administrator".

name != ("Administrator", "Leonardo")

Not equals multi-value filter, searches for everyone except for "Administrator" and "Leonardo".

activation/validTo < "2022-01-01"

Less filter, searches for all users that will not be valid after 2021.

In Equal (=) and notEqual (!=) filters, you can enclose values within brackets on the right side of the query. The query name = ("adam","john") provides the same results as name = "adam" or name = "john" .
In these filters, only values are allowed within the set.

Comparison filters also support item path on the right side of filters. For example, activation/validFrom > activation/validTo should return all objects with incorrectly set activations, i.e. objects for which the activation starts after it ends.

Matching Rules

Comparison filters can be further enhanced with matching rules. The syntax of a matching rule in a query is: filter[matchingRuleName]

Example usage
givenName =[origIgnoreCase] "Adam"

Query matches all cases of "Adam" in givenName with various casings, such as 'Adam', 'adam', or 'ADAM'.

emailAddress endsWith[stringIgnoreCase] "@test.com"

Query matches users with email addresses that end with the "test.com" domain.

For a list of all matching rules, refer to the Matching Rules page.

String Filters

The following table summarizes additional filters that can be applied to string and polystring values.

Name Description

startsWith

Matches items starting with a specified string.

contains

Matches string properties that contain a specified substring.

endsWith

Matches string properties that end in a specified substring.

fullText

Performs a full text search. The item path must be a dot (.)

Logical Filters

Logical filters are used to combine several subfilters into one filter, or to negate a filter, for example:

givenName = "John" and familyName = "Doe"

You can use the following logic operators:

Table 1. Logical Operators
Operator Example Description

and

givenName = "John" and familyName = "Doe"

All subfilters must be true`.

or

givenName = "Bill" or nickName = "Bill"

Any of the subfilters has to be true`.

not

givenName not startsWith "J"
givenName != "John"

Logical negation where not prefixes the filter name.

You can use brackets to group logical statements for better readability, for example:

familyName = "Doe" and (givenName = "John" or givenName ="Bill")

Object Selection

Midpoint performs queries over a defined set of objects. In GUI, this set is defined by the currently opened view.

In configuration, the object type must be explicitly specified for a query. However, not within the query itself. See the configuration snippet below in which the query selects User with the name "XYZ".

    <activity>
        <work>
            <recomputation>
                <objects>
                    <type>UserType</type>
                    <query>
                        <q:filter>
                            <q:text>name = "XYZ"</q:text>
                        </q:filter>
                    </query>
                </objects>
            </recomputation>
        </work>
    </activity>

Advanced Filters

Matches Filter

The Matches filter operates on a container or a structured value, and specifies conditions that must be met by a single container value. It is in the form of itemPath matches (subfilter), where subfilter (and item paths) are relative to the container, for example assignment/validTo < "2022-01-01" is the same as assignment matches (validTo < "2022-01-01").

The subfilter is any of the supported filters in which paths are relative to the container. It enables you to specify multiple conditions (joined using Logical Filters) that must be met by container values.

An example of the matches filter:

activation matches (
  validFrom > "2022-01-01"
   and validTo <"2023-01-01"
)

For filters that match multiple properties of multi-value containers (such as assignment), it is important to consider if you want to match a container where one container value meets all criteria, or if these criteria could be met by multiple different container values.

If these multiple criteria are to be met by a single container value, you must use the Matches filter.

The filter assignment/validFrom > "2022-01-01" and assignment/validTo <"2023-01-01" is different from assignment matches (validFrom > "2022-01-01" and validTo <"2023-01-01"). The first filter will match users who have one assignment starting after 2022, and potentially, another assignment ending by 2023. The second filter with match users who have an assignment which starts in 2022 and expires before 2023.

inOid Filter

You can query objects by their object identifiers (OID) in inOid filters.

An inOid query is a triplet consisting of an object representation, an inOid filter, and a list of OID values enclosed in brackets. The midPoint object is represented by the dot (.) character.

An example of querying one specific object by its OID:

. inOid ("00000000-0000-0000-0000-000000000702")

An example of querying 2 specific objects by their OIDs:

. inOid ("eb21455d-17cc-4390-a736-f1d6afa82057", "87e048ae-6fcf-47bb-a55e-60acb8604ead")

Reference Filters

Reference filters match references utilizing Matches filters on properties of referenced objects, using the dereferencing operator (@).

You can also perform inverse queries using a referencedBy filter to search for an object by properties of its referencer. For example, you can search for roles by properties of their members.

Matches Filter in References

A reference is a structured value which contains the target OID, type, and relationship.

You can use Matches filters with nested subfilters to target these properties of an object reference:

  • oid matches the target OID exactly (UUID as a string). Example: assignment/targetRef matches (oid = efaf89f4-77e9-460b-abc2-0fbfd60d9167)

  • relation matches any reference with a specified relation (QName). Example: roleMembershipRef matches (relation = manager)

  • targetType matches any reference with a specified target type (QName). Example: roleMembershipRef matches (targetType = OrgType)

It is possible to match any combination of these three properties of a reference, however, only equals and and filters are supported.

roleMembershipRef matches (
  oid = "bc3f7659-e8d8-4f56-a647-2a352eead720"
  and relation = manager
  and targetType = OrgType
)
If you need to query referenced objects of a specified type you must use the targetType keyword. See the example above.

Dereferencing

With dereferencing, you can write filter conditions which are executed on referenced objects. Dereferencing is done using the @ special character in the item path after the reference. For example, the assignment/targetRef/@ item path points to an object referenced by targetRef instead of targetRef itself. This enables you to enhance paths with properties of referenced objects, such as assignment/targetRef/@/name which means the name of the assigned object.

For example, dereferencing enables you to search for users with a specific assigned role by the role name instead of its OID, even if the execution time will be slightly longer since we need to dereference objects. assignment/targetRef/@/name = "Superuser" matches any user who is directly assigned the superuser role.

  • Dereferencing is not supported in authorizations, in-memory, and in resource searches.

  • To also match users who are assigned a role indirectly, you should use roleMembershipRef instead of assignment/targetRef.

  • If you need to match a referenced object on multiple properties, you should use the Matches filter.

  • Dereferencing is not supported for object references defined via schema extensions.

Dereferencing Inside Reference Matches Filter

This feature is currently supported only in the midPoint native repository. It is not supported in authorizations, in-memory and in resource searches.

You can use dereferencing inside a Reference Matches filter to match properties of a reference, and also properties of its target.

In order to match a target, you can use dereferencing and matching: @ matches (…​).

Find all users who are managers for roles with the Business Role archetype
assignment/targetRef matches ( (1)
  targetType = RoleType (2)
  and relation = manager (3)
  and @ matches ( (4)
     archetypeRef/@/name = "Business Role" (5)
  )
)
1 We are matching references in assignment/targetRef.
2 The type of the referenced target should be RoleType.
3 The relation of users to the assigned role is manager.
4 We dereference the target and match its properties.
5 Name of the role archetype should be Business Role. This is done by dereferencing archetypeRef, using @ in the item path.

referencedBy Filter

With referencedBy filters, you can find objects based on properties of objects that reference them since the object as a whole is referenced in the item path.

In order to use a referencedBy filter, you must also specify the type of objects which it references, and the path of the object reference which is used for the reference (e.g. assignment/targetRef or inducement/targetRef).

This looks for all roles assigned to Administrator:
. referencedBy ( (1)
  @type = UserType (2)
  and @path = assignment/targetRef (3)
  and name = "Administrator" (4)
)
1 . referencedBy is the filter name.
2 @type (required) is a special filter property which specifies the type of objects that should be considered when evaluating the filter. In this case, we are interested in users.
3 @path (required) is a special filter property which specifies which object reference should be used in the filter. In this case, we are interested in directly assigned roles (assignment/targetRef).
4 The filter which the referencing object must match. In this case, the name of the referencing object must be Administrator.
referencedBy filters are not supported for object references defined via schema extensions.

ownedBy Filter

ownedBy filters are currently only supported in the midPoint native repository. They are not supported in authorizations, in-memory, and in resource searches.

With ownedBy filters, you can match indexed containers based on the properties of their parent, i.e. the owning object or container.

The syntax of this filter is similar to that of the referencedBy filter. You can only apply ownedBy filters to the current object path (.). The properties of ownedBy filter are:

  • type: (Required) Defines the type of the parent/owner.

  • path: Defines the name/location of the container inside the parent.

  • filter: Specifies a filter to which the parent needs to conform. The filter is an explicit element in XML/YAML/JSON. In midPoint queries, any filter that is not a special property of ownedBy is automatically treated as a nested filter.

The following example looks for all inducements:
. ownedBy ( @type = AbstractRoleType and @path = inducement)

Organization Filters

Organization filters are used to filter objects based on their organization membership. These filters operate on an object as a whole and so the item path must be . (the dot).

Name Value Description

inOrg

OID (UUID)

Matches an object if it is a part of an organization unit or its subunits.

isRoot

N/A

Matches an object if it is the organization root. This filter does not have any values.
. inOrg "f9444d2d-b625-4d5c-befd-36c9b5861ac4"

Matches all objects that are members of the specified organization and all its subunits (whole SUBTREE).

. inOrg[ONE_LEVEL] "f9444d2d-b625-4d5c-befd-36c9b5861ac4"

If you only need to match users in a specified organization, use the ONE_LEVEL matching rule.

. isRoot

Matches all roles and organization units that are organization tree roots.

Similarity Filters

Similarity filters are only supported in the midPoint native repository.

To perform fuzzy (not exact) matching, midPoint query language provides 2 filters: levenshtein and similarity.

Contrary to other filters, the right side of the query consists of a triplet of parameters enclosed in brackets. Their meaning is explained in following table:

Name Value Description Parameters

Levenshtein

(value, threshold, inclusive)

Matches objects for which the queried attribute has the Levenshtein distance lower than (or equal to, depending on the inclusive parameter value) the specified threshold.

  • Value (string): A string value that is compared with the queried attribute.

  • Threshold (integer): The compared distance value. The result must be less than (or equal to) the threshold.

  • Inclusive (boolean): Defines if objects with the threshold value should be included in the result (true) or not (false).

Similarity

(value, threshold, inclusive)

Matches objects for which the queried attribute has similarity greater than (or equal to, depending on the inclusive parameter value) the specified threshold.
Similarity of 1 means an exact match, while 0 means no similarity.

  • Value (string): A string value that is compared with the queried attribute.

  • Threshold (float): The compared distance value. The result must be greater than (or equal to) the threshold.

  • Inclusive (boolean): Defines if objects with the threshold value should be included in the result (true) or not (false).

As similarity filters are implemented using levenshtein PostgreSQL function and similarity PostgreSQL function, they only work with the native repository.

name levenshtein ("ang",2,true)

Matches all users whose name attribute has Levenshtein distance 2 or lower from the string "ang".

name levenshtein ("ang",2,false)

Matches all users whose name has Levenshtein distance lower than 2 from the string "ang".

name similarity ('gren', 0.5, true)

Matches all users whose name has similarity of 0.5 or lower from the string 'gren'.

The Levenshtein distance between two strings is the number of modifications required to transform one string (s1) into the other string (s2). It allows for single-character edits such as deletion, insertion, and substitution. For example, for s1=“helloIndia” and s2=“halloindia,” the Levenshtein distance is 2.

Other Filters

Name Value Description

exists

N/A

Matches an item if it exists, i.e. if it has a value. This filter does not have a value.

type

object type

Matches an object if it is of the specified type. This is usually used in combination with the and filter for dereferenced objects, or when you need to match a property defined in a more specific type.

Filtering All Objects of Specified Type

Sometimes, in configuration files, you need to select all objects of a specific object type. An example of such a case would be selecting all users in midPoint through an object collection.

To select all objects, just omit the <filter> element in the query, or the entire query.

The object collection below lists all roles (all objects of RoleType) in midPoint.

<objectCollection oid="72b1f98e-f587-4b9f-b92b-72e251dbb255">
    <name>All roles</name>
    <type>RoleType</type>
</objectCollection>

Basic Query Examples

This section provides examples of MQL role queries that can be utilized when configuring midPoint.

For additional examples, refer to Query Examples.

Search by Archetype Name

You can search for reports with an archetype using the archetype name:

midPoint query
archetypeRef/@/name = "Report export task"

Where archetypeRef/@ specifies that we are not matching a reference value but its target. In this case, it is an archetype.

Search by Assigned Role Name

midPoint query
assignment/targetRef/@/name = "Role Name"

Where assignment/targetRef/@ specifies that we are not matching a reference value but its target. In this case, it is an assigned role.

Users with Account on Specific Resource

You can search for users who have an account specified resource by using the default intent.

midPoint query
linkRef/@ matches (
  . type ShadowType
  and resourceRef matches (oid = "ff735c0a-21e3-11e8-a91a-df0065248d2d")
  and intent = "default"
)

Where:

  • linkRef/@ specifies the dereference target of linkRef. This behaves similarly to SQL JOIN and enables you to filter properties of the target.

  • matches specifies a subfilter for the dereferenced target, i.e. the filter that linkRef must match.

    • . type ShadowType searches for shadows on the resource. This is necessary to be able to use shadow properties for the filter.

    • resourceRef matches (oid = "…​" ) matches a specific resource to which the shadow belongs.

    • intent = "default" matches the shadow with the default intent.

All Roles which Are Assigned to System Users

midPoint query using UserType in a referencedBy filter
. referencedBy (
  @type = UserType
  and @path = assignment/targetRef
  and archetypeRef/@/name = "System user"
)
midPoint query using AssignmentType in a referencedBy filter
. referencedBy (
   @type = AssignmentType
   and @path = targetRef
   and . ownedBy (
      @type = UserType
      and @path = assignment
      and archetypeRef/@/name = "System user"
   )
)

All Roles Assigned Using Inducement

The following filter is only supported in the midPoint native repository.

midPoint query
. referencedBy (
  @type = AbstractRoleType
  and @path = inducement/targetRef
)

All Roles Assigned to Administrator Using Full Text Search

midPoint query
. referencedBy (
   @type = UserType
   and @path = roleMembershipRef
   and . fullText "administrator"
)

Search Assigned Role Using Full Text Search

midPoint query
assignment/targetRef/@ matches (
   . fullText "secret"
)
Was this page helpful?
YES NO
Thanks for your feedback