Merge pull request #73 from getsentry/shana/fix-optional-filters

Fix SDK optional filters
getsentry · Oct 31, 2023 · 853b33c · 853b33c · vercel · Oct 31, 2023
2 parents 97077d6 + 446bbaf
commit 853b33c
Show file tree

Hide file tree

Showing 8 changed files with 122 additions and 83 deletions.
diff --git a/README.md b/README.md
@@ -194,25 +194,34 @@ When doing a search while on the page `/foo/`, we tell Algolia to put all record
 
 #### Sorting by Platform
 
-In most cases, searches are done in the context of a specific platform. We float the results from a given platform to the top of the list by indexing a record’s applicable platforms and then using Algolias `optionalFilters` to request the appropriate platform results. Additionally, we want a platform’s family results to also be promoted, for example, we should show JavaScript results under React results if the priority is React.
+In most cases, searches are done in the context of a specific platform. We float the results from a given platform to the top of the list by indexing a record’s SDK and framework  and then using Algolia's `optionalFilters` to request the appropriate platform results. Additionally, we want a platform’s family results to also be promoted, for example, we should show JavaScript results under React results if the priority is React.
 
-Records include a `platforms` array which includes applicable [SDK slugs][sdk-slug-format]. The format is `entity.ecosystem[.flavor]`, and the platforms list includes slugs for the parents of a SDK in addition to the SDK itself. That is, a React record looks like:
+Records include a `sdk` property and a `framework` property. `sdk` is the appropriate [SDK slug][sdk-slug-format] and `framework` is the appropriate framework slug, if applicable, or the SDK slug. The format is `entity.sdk[.framework]`.
+
+Example record:
 
 ```JavaScript
-platforms: [
-  'sentry',
-  'sentry.javascript',
-  'sentry.javascript.react',
-]
+sdk: 'sentry.javascript',
+framework: 'sentry.javascript.react',
 ```
 
-Using this list, we can prioritize our results as such:
+Using Algolia's `optionalFilters`, each record scores a "point" each for an SDK match and a framework match.
+
+This means, if the user is in the React SDK docs, we can prioritize our results as such:
 
 - Put all records matching `sentry.javascript.react` first.
 - Show results which contain `sentry.javascript` next.
 - Show everything else last.
 
-By including the `entity` portion of the SDK slug, we also give ourselves the ability to filter 1st party SDKs higher than 3rd party SDKs.
+And if a user is in the JavaScript SDK docs, we can prioritize our results as such:
+
+- Put all records matching `sentry.javascript` first.
+- Show results which contain `sentry.javascript.<framework>` next.
+- Show everything else last.
+
+~~By including the `entity` portion of the SDK slug, we also give ourselves the ability to filter 1st party SDKs higher than 3rd party SDKs.~~
+
+We no longer index and use the `entity` portion of the SDK slug, as we only index docs for 1st party SDKs.
 
 #### Sorting By legacy
 

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@sentry-internal/global-search",
   "description": "JavaScript library and helper utilities for searching Sentry sites via Algolia.",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "author": "Sentry",
   "dependencies": {
     "@types/react": ">=16",

diff --git a/src/html-to-algolia-record/lib/types.ts b/src/html-to-algolia-record/lib/types.ts
@@ -19,6 +19,9 @@ export type Node = Element | Text;
 export type Meta = {
   title: string;
   url: string;
+  sdk?: string;
+  framework?: string;
+  // deprecated in 0.5.9
   platforms?: string[];
   pathSegments?: string[];
   keywords?: string[];

diff --git a/src/sentry-algolia-index-settings.ts b/src/sentry-algolia-index-settings.ts
@@ -14,22 +14,24 @@ export const settings: Settings = {
   attributesToHighlight: ['section'],
   attributesForFaceting: [
     'filterOnly(pathSegments)',
-    'filterOnly(platforms)',
+    'filterOnly(sdk)',
+    'filterOnly(framework)',
     'filterOnly(legacy)',
   ],
   distinct: 1,
   attributeForDistinct: 'section',
-  attributesToRetrieve: [
-    'text',
-    'title',
-    'section',
-    'url',
-    'anchor',
-    'context',
-  ],
+  attributesToRetrieve: ['*'],
   searchableAttributes: ['unordered(section)', 'unordered(keywords)', 'text'],
-  customRanking: ['asc(sectionRank)', 'desc(position)'],
   disableTypoToleranceOnWords: ['react', 'cli'],
   advancedSyntax: true,
+  ranking: [
+    'desc(sectionRank)',
+    'filters',
+    'asc(position)',
+    'attribute',
+    'exact',
+    'proximity',
+    'words',
+    'typo',
+  ],
 };
-
diff --git a/src/sentry-global-search/__snapshots__/sentry-global-search.test.js.snap b/src/sentry-global-search/__snapshots__/sentry-global-search.test.js.snap
@@ -11,9 +11,8 @@ Array [
           "highlightPostTag": "</mark>",
           "highlightPreTag": "<mark>",
           "optionalFilters": Array [
-            Array [
-              "platforms:sentry.javascript.react",
-            ],
+            "sdk:sentry.javascript",
+            "framework:sentry.javascript.react",
             "legacy:0",
           ],
           "snippetEllipsisText": "…",
@@ -175,14 +174,13 @@ Array [
   Array [
     Array [
       Object {
-        "indexName": "sentry-docs",
+        "indexName": "sentry-docs-v2",
         "params": Object {
           "highlightPostTag": "</mark>",
           "highlightPreTag": "<mark>",
           "optionalFilters": Array [
-            Array [
-              "platforms:sentry.javascript.react",
-            ],
+            "sdk:sentry.javascript",
+            "framework:sentry.javascript.react",
             "legacy:0",
           ],
           "snippetEllipsisText": "…",
@@ -199,7 +197,7 @@ Array [
   Array [
     Array [
       Object {
-        "indexName": "sentry-docs",
+        "indexName": "sentry-docs-v2",
         "params": Object {
           "highlightPostTag": "</mark>",
           "highlightPreTag": "<mark>",
@@ -220,14 +218,13 @@ Array [
   Array [
     Array [
       Object {
-        "indexName": "sentry-docs",
+        "indexName": "sentry-docs-v2",
         "params": Object {
           "highlightPostTag": "</mark>",
           "highlightPreTag": "<mark>",
           "optionalFilters": Array [
-            Array [
-              "platforms:sentry.javascript.react",
-            ],
+            "sdk:sentry.javascript",
+            "framework:sentry.javascript.react",
             "legacy:0",
           ],
           "snippetEllipsisText": "…",
@@ -248,7 +245,7 @@ Array [
           "context1": "Platforms > JavaScript > React",
         },
         "id": "cd5528ad-935b-5a33-b25e-4f945638551b",
-        "index": "sentry-docs",
+        "index": "sentry-docs-v2",
         "site": "docs",
         "text": "Mocked text",
         "title": "Mocked section",
@@ -259,7 +256,7 @@ Array [
           "context1": "Platforms > JavaScript > React",
         },
         "id": "cd5528ad-935b-5a33-b25e-4f945638551b",
-        "index": "sentry-docs",
+        "index": "sentry-docs-v2",
         "site": "docs",
         "text": "Mocked text",
         "title": "Mocked section",
@@ -281,7 +278,7 @@ Array [
           "context1": "Platforms > JavaScript > React",
         },
         "id": "cd5528ad-935b-5a33-b25e-4f945638551b",
-        "index": "sentry-docs",
+        "index": "sentry-docs-v2",
         "site": "docs",
         "text": "Mocked text",
         "title": "Mocked section",
@@ -292,7 +289,7 @@ Array [
           "context1": "Platforms > JavaScript > React",
         },
         "id": "cd5528ad-935b-5a33-b25e-4f945638551b",
-        "index": "sentry-docs",
+        "index": "sentry-docs-v2",
         "site": "docs",
         "text": "Mocked text",
         "title": "Mocked section",
@@ -390,7 +387,7 @@ Array [
   Array [
     Array [
       Object {
-        "indexName": "sentry-docs",
+        "indexName": "sentry-docs-v2",
         "params": Object {
           "highlightPostTag": "</mark>",
           "highlightPreTag": "<mark>",
@@ -411,14 +408,13 @@ Array [
   Array [
     Array [
       Object {
-        "indexName": "sentry-docs",
+        "indexName": "sentry-docs-v2",
         "params": Object {
           "highlightPostTag": "</mark>",
           "highlightPreTag": "<mark>",
           "optionalFilters": Array [
-            Array [
-              "platforms:sentry.javascript.react",
-            ],
+            "sdk:sentry.javascript",
+            "framework:sentry.javascript.react",
             "legacy:0",
           ],
           "snippetEllipsisText": "…",

diff --git a/src/sentry-global-search/lib/config.ts b/src/sentry-global-search/lib/config.ts
@@ -26,7 +26,7 @@ export const sites = [
     name: 'Documentation',
     indexes: [
       {
-        indexName: 'sentry-docs',
+        indexName: 'sentry-docs-v2',
         transformer: Transformers.transformDocsGatsbyHit,
       },
     ],

diff --git a/src/sentry-global-search/sentry-global-search.test.js b/src/sentry-global-search/sentry-global-search.test.js
@@ -56,7 +56,7 @@ describe('Search', () => {
   test('queries with platform priority', async () => {
     const search = new SentryGlobalSearch(config);
     const results = await search.query('react', {
-      platforms: ['sentry.javascript.react'],
+      platforms: ['sentry.javascript', 'sentry.javascript.react'],
     });
     expect(client.search.mock.calls).toMatchSnapshot();
   });
@@ -81,7 +81,7 @@ describe('Search', () => {
     const search = new SentryGlobalSearch(config);
     const results = await search.query('react', {
       path: ['/foo/bar/'],
-      platforms: ['sentry.javascript.react'],
+      platforms: ['sentry.javascript', 'sentry.javascript.react'],
     });
     expect(client.search.mock.calls).toMatchSnapshot();
   });
@@ -97,44 +97,54 @@ describe('Search', () => {
     const search = new SentryGlobalSearch(biasedConfig);
     const results = await search.query('react', {
       path: ['/foo/bar/'],
-      platforms: ['sentry.javascript.react'],
+      platforms: ['sentry.javascript', 'sentry.javascript.react'],
       legacy: true,
     });
     expect(client.search.mock.calls).toMatchSnapshot();
   });
 
   test('calls search with clickAnalytics', async () => {
-    const search = new SentryGlobalSearch([{
-      site: "blog",
-      indexes: [{
-        indexName: "blog",
-        clickAnalytics: true,
-      }]
-    }]);
+    const search = new SentryGlobalSearch([
+      {
+        site: 'blog',
+        indexes: [
+          {
+            indexName: 'blog',
+            clickAnalytics: true,
+          },
+        ],
+      },
+    ]);
 
     const results = await search.query('react', {
       path: ['/foo/bar/'],
-      platforms: ['sentry.javascript.react'],
+      platforms: ['sentry.javascript', 'sentry.javascript.react'],
       legacy: true,
     });
     expect(client.search.mock.calls).toMatchSnapshot();
   });
 
   test('calls transformer with response', async () => {
-    const config = [{
-      site: "blog",
-      indexes: [{
-        indexName: "sentry-blog-posts",
-        clickAnalytics: true,
-        transformer: jest.fn()
-      }]
-    }]
+    const config = [
+      {
+        site: 'blog',
+        indexes: [
+          {
+            indexName: 'sentry-blog-posts',
+            clickAnalytics: true,
+            transformer: jest.fn(),
+          },
+        ],
+      },
+    ];
 
     const search = new SentryGlobalSearch(config);
-    await search.query('react')
+    await search.query('react');
 
     expect(config[0].indexes[0].transformer).toHaveBeenCalledTimes(2);
     expect(config[0].indexes[0].transformer.mock.calls[0][1]).toMatchSnapshot();
-    expect(config[0].indexes[0].transformer.mock.calls[0][1].hitsPerPage).toBe(20)
+    expect(config[0].indexes[0].transformer.mock.calls[0][1].hitsPerPage).toBe(
+      20
+    );
   });
 });