By default the full entities are returned, but you can pass in a fields query parameter which selects what parts of the entity data to retain. This makes the response smaller and faster to transfer, and may allow the catalog to perform more efficient queries.

The query parameter value is a comma separated list of simplified JSON paths like above. Each path corresponds to the key of either a value, or of a subtree root that you want to keep in the output. The rest is pruned away. For example, specifying ?fields=metadata.name,metadata.annotations,spec retains only the name and annotations fields of the metadata of each entity (it'll be an object with at most two keys), keeps the entire spec unchanged, and cuts out all other roots such as relations.

Some more real world usable examples:

• Return only enough data to form the full ref of each entity:

  /entities/by-query?fields=kind,metadata.namespace,metadata.name

Number of records to return in the response.

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

Number of records to skip in the query page.

Pointer to the previous page of results.