Skip to main content
Version: Next

Collators

Backstage includes 2 collators out of the box for the Catalog and TechDocs. There's also some from the Backstage Community too!

Catalog​

The Catalog collator will index all the Entities in your Catalog. It is installed by default but if you need to add it manually here's how.

First we add the plugin into your backend app:

From your Backstage root directory
yarn --cwd packages/backend add @backstage/plugin-search-backend-module-catalog

Then add the following line:

packages/backend/src/index.ts
const backend = createBackend();

// Other plugins...

// search plugin
backend.add(import('@backstage/plugin-search-backend'));

backend.add(import('@backstage/plugin-search-backend-module-catalog'));

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:

search:
  collators:
    catalog:
      schedule: # same options as in SchedulerServiceTaskScheduleDefinition
        # supports cron, ISO duration, "human duration" as used in code
        initialDelay: { seconds: 90 }
        # supports cron, ISO duration, "human duration" as used in code
        frequency: { hours: 6 }
        # supports ISO duration, "human duration" as used in code
        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:

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:

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 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.

First we add the plugin into your backend app:

From your Backstage root directory
yarn --cwd packages/backend add @backstage/plugin-search-backend-module-techdocs

Then add the following line:

packages/backend/src/index.ts
const backend = createBackend();

// Other plugins...

// search plugin
backend.add(import('@backstage/plugin-search-backend'));

backend.add(import('@backstage/plugin-search-backend-module-techdocs'));

backend.start();

Configuring the TechDocs Collator​

The default schedule for the TechDocs Collator is to run every 10 minutes, you can provide your own schedule by adding it to your config:

search:
  collators:
    techdocs:
      schedule: # same options as in SchedulerServiceTaskScheduleDefinition
        # supports cron, ISO duration, "human duration" as used in code
        initialDelay: { seconds: 90 }
        # supports cron, ISO duration, "human duration" as used in code
        frequency: { hours: 6 }
        # supports ISO duration, "human duration" as used in code
        timeout: { minutes: 3 }

Filtering through the catalog collator​

The TechDocs collator by default filters through catalog entities where the annotation metadata.annotations.backstage.io/techdocs-ref exists. If you wish to further filter out entities, there are two ways to do so through the techDocsCollatorEntityFilterExtensionPoint.

export const exampleCustomCatalogFiltering = createBackendModule({
  pluginId: 'search',
  moduleId: 'search-techdocs-collator-entity-filter',
  register(reg) {
    reg.registerInit({
      deps: {
        customCollatorFilter: techDocsCollatorEntityFilterExtensionPoint,
      },
      async init({ customCollatorFilter }) {
        /* filtering by catalog params */
        customCollatorFilter.setCustomCatalogApiFilters([
          { kind: ['API', 'Component', ...] },
          { metadata: ['...more filters'] },
        ]);

        /* filtering by a custom function */
        customCollatorFilter.setEntityFilterFunction((entities: Entity[]) =>
          entities.filter(
            entity => entity.metadata?.annotations?.abc === 'xyz',
          ),
        );
      },
    });
  },
});

Community Collators​

Here are some of the known search collators available from the Backstage Community:

Custom collators​

To learn how to create your own collator, see the Writing Custom Collators guide.