Adjustments based on feedback

Signed-off-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com>

docs/features/search/search-engines.md

@@ -59,10 +59,38 @@ configured and make the following changes to your backend:
 
 // Initialize a connection to a search engine.
 const searchEngine = (await PgSearchEngine.supported(env.database))
-  ? await PgSearchEngine.from({ database: env.database })
+  ? await PgSearchEngine.fromConfig(env.config, { database: env.database })
   : new LunrSearchEngine({ logger: env.logger });
 ```
 
+## Optional Configuration
+
+The following is an example of the optional configuration that can be applied when using Postgres as the search backend. Currently this is mostly for just the highlight feature:
+
+```yaml
+search:
+  pg:
+    highlightOptions:
+      useHighlight: true # Used to enable to disable the highlight feature. The default value is true
+      maxWord: 35 # Used to set the longest headlines to output. The default value is 35.
+      minWord: 15 # Used to set the shortest headlines to output. The default value is 15.
+      shortWord: 3 # Words of this length or less will be dropped at the start and end of a headline, unless they are query terms. The default value of three (3) eliminates common English articles.
+      highlightAll: false # If true the whole document will be used as the headline, ignoring the preceding three parameters. The default is false.
+      maxFragments: 0 # Maximum number of text fragments to display. The default value of zero selects a non-fragment-based headline generation method. A value greater than zero selects fragment-based headline generation (see the linked documentation above for more details).
+      fragmentDelimiter: ' ... ' # Delimiter string used to concatenate fragments. Defaults to " ... ".
+```
+
+**Note:** the highlight search term feature uses `ts_headline` which has been known to potentially impact performance. You only need this minimal config to disable it should you have issues:
+
+```yaml
+search:
+  pg:
+    highlightOptions:
+      useHighlight: false
+```
+
+The Postgres documentation on [Highlighting Results](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-HEADLINE) has more details.
+
 ## ElasticSearch
 
 Backstage supports ElasticSearch search engine connections, indexing and

packages/backend/src/plugins/search.ts

@@ -39,9 +39,8 @@ async function createSearchEngine(
   }
 
   if (await PgSearchEngine.supported(env.database)) {
-    return await PgSearchEngine.fromConfig({
+    return await PgSearchEngine.fromConfig(env.config, {
       database: env.database,
-      config: env.config,
     });
   }
 

plugins/search-backend-module-pg/api-report.md

@@ -79,6 +79,7 @@ export interface DatabaseStore {
 //
 // @public (undocumented)
 export class PgSearchEngine implements SearchEngine {
+  // @deprecated
   constructor(databaseStore: DatabaseStore, config: Config);
   // @deprecated (undocumented)
   static from(options: {
@@ -86,10 +87,10 @@ export class PgSearchEngine implements SearchEngine {
     config: Config;
   }): Promise<PgSearchEngine>;
   // (undocumented)
-  static fromConfig({
-    config,
-    database,
-  }: PgSearchOptions): Promise<PgSearchEngine>;
+  static fromConfig(
+    config: Config,
+    options: PgSearchOptions,
+  ): Promise<PgSearchEngine>;
   // (undocumented)
   getIndexer(type: string): Promise<PgSearchEngineIndexer>;
   // (undocumented)
@@ -142,7 +143,6 @@ export type PgSearchHighlightOptions = {
 
 // @public
 export type PgSearchOptions = {
-  config: Config;
   database: PluginDatabaseManager;
 };
 

plugins/search-backend-module-pg/src/PgSearchEngine/PgSearchEngine.ts

@@ -60,7 +60,6 @@ export type PgSearchQueryTranslator = (
  * @public
  */
 export type PgSearchOptions = {
-  config: Config;
   database: PluginDatabaseManager;
 };
 
@@ -82,6 +81,10 @@ export type PgSearchHighlightOptions = {
 
 export class PgSearchEngine implements SearchEngine {
   private readonly highlightOptions: PgSearchHighlightOptions;
+
+  /**
+   * @deprecated This will be marked as private in a future release, please us fromConfig instead
+   */
   constructor(private readonly databaseStore: DatabaseStore, config: Config) {
     const uuidTag = uuid();
     const highlightConfig = config.getOptionalConfig(
@@ -117,9 +120,9 @@ export class PgSearchEngine implements SearchEngine {
     );
   }
 
-  static async fromConfig({ config, database }: PgSearchOptions) {
+  static async fromConfig(config: Config, options: PgSearchOptions) {
     return new PgSearchEngine(
-      await DatabaseDocumentStore.create(await database.getClient()),
+      await DatabaseDocumentStore.create(await options.database.getClient()),
       config,
     );
   }

plugins/search-backend-module-pg/src/database/DatabaseDocumentStore.ts

@@ -135,6 +135,7 @@ export class DatabaseDocumentStore implements DatabaseStore {
     searchQuery: PgSearchQuery,
   ): Promise<DocumentResultRow[]> {
     const { types, pgTerm, fields, offset, limit, options } = searchQuery;
+    // TODO(awanlin): We should make the language a parameter so that we can support more then just english
     // Builds a query like:
     // SELECT ts_rank_cd(body, query) AS rank, type, document,
     // ts_headline('english', document, query) AS highlight