@platt/plugin-search-backend-module-cognitive-search

search-backend-module-cognitive-search

This is an extension to module to search-backend-node plugin. This module provides functionality to index and implement querying using Azure Cognitive Search.

Getting Started

• provision cognitive search
• assign roles to user or service principal
• implements search plugns

Provision a Azure Cognitive Search service

Following the Azure Cognitive Search document, you can create an Azure Cognitive Search service using azure portal(or bicep or any other tools).

Assign roles to user or service principal

This plugin is uses DefaultAzureCredential of @azure/identity for authorizing access to Azure Cognitive Search service. So you can use user identity or service principal.

It is needed to assigned roles below to user or principal.

• Search Service Contributor for creating the indexes.
• Search Index Data Contributor for read/write the index contents.

Install & configure earch plugin

Install plugin

Install the plugin to backstage backend.

yarn add --cwd packages/backend @platt/plugin-search-backend-module-cognitive-search

Configure setting

To enable this plugin, at least you should configure search.cognitiveSearch.endpoint.

Other optional configuration can be found in the config.d.ts.

search:
  cognitiveSearch:
    endpoint: https://<your service name>.search.windows.net

New backend system

Update packages/backend/index.ts

import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

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

// ... 

backend.add(import('@platt/plugin-search-backend-module-cognitive-search'));  // add this line

backend.start();

If you want to configure default analyzer type for cognitive search, you can describe the type like this.

search:
  cognitiveSearch:
    endpoint: https://<your service name>.search.windows.net
    defaultAnalyzerName: 'ja.microsoft'   # add this line

defaultAnalyzerName can be specifies the supported language analyzers of cognitive search.

Old backend system

Here is the sample code for using Cognitive Search plugin.

import { CognitiveSearchSearchEngine } from '@platt/plugin-search-backend-module-cognitive-search';

export default async function createPlugin(
  env: PluginEnvironment,
): Promise<Router> {
  const searchEngine = (CognitiveSearchSearchEngine.supported(env.config))
  ? CognitiveSearchSearchEngine.fromConfig(env.config, {
      logger: env.logger,
      defaultAnalyzerName: 'ja.microsoft',
    })
  : new LunrSearchEngine({ logger: env.logger });
  
  const indexBuilder = new IndexBuilder({
    logger: env.logger,
    searchEngine,
  });

...
};

You can define defaultAnalyzerName for cognitive search indexes. For example, our catalog or techdocs is written by Japanese, so we'd like to use 'ja.microsoft' analyzer.

defaultAnalyzerName can be specifies the supported language analyzers of cognitive search.

Indexable document

Supported document by default

This plugin supports basic backstage document below

• Catalog entity document
• TechDocs document

Additonal document type (Optional)

If you want to use other document, you should define the schema of document and adding document type.

You shoud map the json types of document to the index schemas.

Here is the sample schema definition. (for of the catalog entity).

export const catalogEntityIndexFields = (_analyzerName: string): CognitiveSearchIndexFields => ([
  {
    type: 'Edm.String',
    name: 'componentType',
    searchable: true,
    facetable: true,
    filterable: true,
    sortable: false,
  },
  {
    type: 'Edm.String',
    name: 'type',
    searchable: true,
    facetable: true,
    filterable: true,
    sortable: false,
  },
  {
    type: 'Edm.String',
    name: 'namespace',
    searchable: true,
    facetable: true,
    filterable: true,
    sortable: false,
  },
  {
    type: 'Edm.String',
    name: 'kind',
    searchable: true,
    facetable: true,
    filterable: true,
    sortable: false,
  },
  {
    type: 'Edm.String',
    name: 'lifecycle',
    searchable: true,
    facetable: true,
    filterable: true,
    sortable: false,
  },
  {
    type: 'Edm.String',
    name: 'owner',
    searchable: true,
    facetable: true,
    filterable: true,
    sortable: false,
  },
]);

You can find the full definitions here for default document types.

And here is the sample code for supporting additional type.

// add 2 types of additional documents
const ExtendedDocumentType = SomeDocument1 | SomeDocument2 | DefaultBackstageSearchDocuments;

const extraSchema1: CognitiveSearchIndexFields = [
  ...
];
const extranSchema1Transformer: CognitiveSearchIndexTransformer<SomeDocument1> = (data) => {
  return {
    ...
  };
};

const extraSchema2: CognitiveSearchIndexFields = [
  ...
];
const extranSchema1Transformer: CognitiveSearchIndexTransformer<SomeDocument2> = (data) => {
  return {
    ...
  };
};


CognitiveSearchSearchEngine.fromConfig<ExtendedDocumentType>(env.config, {
      logger: env.logger,
      defaultAnalyzerName: 'ja.microsoft',
      searchIndexDefinitions: [
        {
          type: 'docType1',
          transformer: extranSchema1Transformer,
          fields: extraSchema1
        },
        {
          type: 'docType2',
          transformer: extranSchema2Transformer,
          fields: extraSchema2
        }
      ]
    })

Extra schemas will be merged to default schemas applied automatically.

I'm sorry to say but we did not provide this feature for the new backend system. If you want to use this feature, you should create your own module description.

License

Copyright 2023 AP Communications Co.,Ltd. Licenced under the Apache Licence, Version 2.0.