Merge pull request #28992 from awanlin/docs/catalog-collator-filter-example

Added Catalog Collator filter example
2025-02-27 13:41:34 -06:00
parent 26550b1097 f571d10497
commit 40d2fa1e02
2 changed files with 40 additions and 34 deletions
@@ -35,6 +35,10 @@ backend.start();

 ### Configuring the Catalog Collator

+The following sections outlines the available configurations for this collator.
+
+#### Scheduling
+
 The default schedule for the Catalog Collator is to run every 10 minutes, you can provide your own schedule by adding it to your config:

 ```yaml title="app-config.yaml
@@ -50,6 +54,42 @@ search:
        timeout: { minutes: 3 }
 ```

+#### Filtering
+
+You may wish to collate specific subsets of entities in your Catalog, this can be accomplished using the `filter` configuration option. Here's a basic example:
+
+```yaml title"app-config.yaml"
+search:
+  collators:
+    catalog:
+      filter:
+        kind: ['component', 'api']
+        spec.lifecycle: production
+```
+
+The above example will only collate entities that are `kind` equal to `component` or `api` AND have a `spec.lifecycle` set to `production`
+
+You can also apply a more advanced filter like this:
+
+```yaml title"app-config.yaml"
+search:
+  collators:
+    catalog:
+      filter:
+        - kind: ['API']
+          spec.type: openapi
+        - kind: ['Component']
+          spec.lifecycle: experimental
+```
+
+Now with this example it will collate all entities that are `kind` equal to `api` with a `spec.type` equal to `openapi` OR all entities that are `kind` equal to `component` AND have a `spec.lifecycle` set to `experimental`
+
+:::tip
+
+The filter configuration is implemented using the `EntityFilterQuery` syntax. The [reference documentation on `EntityFilterQuery`](https://backstage.io/docs/reference/catalog-client.entityfilterquery/) provides more details.
+
+:::
+
 ## TechDocs

 The TechDocs collator will index all the TechDocs in your Catalog. It is installed by default but if you need to add it manually here's how.
@@ -111,40 +111,6 @@ indexBuilder.addCollator({
 });
 ```

-## How to limit what can be searched in the Software Catalog
-
-The Software Catalog includes a wealth of information about the components,
-systems, groups, users, and other aspects of your software ecosystem. However,
-you may not always want _every_ aspect to appear when a user searches the
-catalog. Examples include:
-
- Entities of kind `Location`, which are often not useful to Backstage users.
- Entities of kind `User` or `Group`, if you'd prefer that users and groups be
-  exposed to search in a different way (or not at all).
-
-It's possible to write your own [Collator](./concepts.md#collators) to control
-exactly what's available to search, (or a [Decorator](./concepts.md#decorators)
-to filter things out here and there), but the `DefaultCatalogCollator` that's
-provided by `@backstage/plugin-catalog-backend` offers some configuration too!
-
-```ts title="packages/backend/src/plugins/search.ts"
-indexBuilder.addCollator({
-  defaultRefreshIntervalSeconds: 600,
-  collator: DefaultCatalogCollator.fromConfig(env.config, {
-    discovery: env.discovery,
-    tokenManager: env.tokenManager,
-    /* highlight-add-start */
-    filter: {
-      kind: ['API', 'Component', 'Domain', 'Group', 'System', 'User'],
-    },
-    /* highlight-add-end */
-  }),
-});
-```
-
-As shown above, you can add a catalog entity filter to narrow down what catalog
-entities are indexed by the search engine.
-
 ## How to customize search results highlighting styling

 The default highlighting styling for matched terms in search results is your