You can pass in one or more filter sets that get matched against each entity. Each filter set is a number of conditions that all have to match for the condition to be true (conditions effectively have an AND between them). At least one filter set has to be true for the entity to be part of the result set (filter sets effectively have an OR between them).

Example:

/entities/by-query?filter=kind=user,metadata.namespace=default&filter=kind=group,spec.type

  Return entities that match

    Filter set 1:
      Condition 1: kind = user
                  AND
      Condition 2: metadata.namespace = default

    OR

    Filter set 2:
      Condition 1: kind = group
                  AND
      Condition 2: spec.type exists

Each condition is either on the form <key>, or on the form <key>=<value>. The first form asserts on the existence of a certain key (with any value), and the second asserts that the key exists and has a certain value. All checks are always case insensitive.

In all cases, the key is a simplified JSON path in a given piece of entity data. Each part of the path is a key of an object, and the traversal also descends through arrays. There are two special forms:

• Array items that are simple value types (such as strings) match on a key-value pair where the key is the item as a string, and the value is the string true
• Relations can be matched on a relations.<type>=<targetRef> form

Let's look at a simplified example to illustrate the concept:

{
  "a": {
    "b": ["c", { "d": 1 }],
    "e": 7
  }
}

This would match any one of the following conditions:

• a
• a.b
• a.b.c
• a.b.c=true
• a.b.d
• a.b.d=1
• a.e
• a.e=7

Some more real world usable examples:

• Return all orphaned entities:

  /entities/by-query?filter=metadata.annotations.backstage.io/orphan=true

• Return all users and groups:

  /entities/by-query?filter=kind=user&filter=kind=group

• Return all service components:

  /entities/by-query?filter=kind=component,spec.type=service

• Return all entities with the java tag:

  /entities/by-query?filter=metadata.tags.java

• Return all users who are members of the ops group (note that the full reference of the group is used):

  /entities/by-query?filter=kind=user,relations.memberof=group:default/ops