diff --git a/docs/features/search/collators.md b/docs/features/search/collators.md index 0282bc845e..834a14437a 100644 --- a/docs/features/search/collators.md +++ b/docs/features/search/collators.md @@ -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. diff --git a/docs/features/search/how-to-guides.md b/docs/features/search/how-to-guides.md index 007b108df5..0476ef6c24 100644 --- a/docs/features/search/how-to-guides.md +++ b/docs/features/search/how-to-guides.md @@ -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