@findlane/server 0.12.0 → 0.13.0

package/README.md

@@ -47,7 +47,7 @@ const results = await products.search({ q }, { visitor: { ip: req.ip, userAgent:
 
 | Method | What it does |
 | --- | --- |
-| `search(request, options?)` | Search with a query, filters, facets, a sort, paging, and highlighting. `options` takes `signal` and `visitor` (below). |
+| `search(request, options?)` | Search with a query, filters, facets, a sort, paging, and highlighting. `explain: true` says why each hit matched and what ordered it, and `appliedRules` lists the index's query rules the query fired. `options` takes `signal` and `visitor` (below). |
 | `upsert(records)` | Add or update up to 1,000 records by `objectID`. |
 | `replaceAll(records)` | Replace the whole catalog in one request (up to 100,000 records). |
 | `replaceAllStaged(records, options)` | Replace a larger catalog in batches under one stage ID, switched in one commit. Retrying with the same `stageId` resumes. `abortReplacement(stageId)` drops a stage. |

package/dist/index.d.cts

@@ -12,20 +12,46 @@ export type SortOption = SortRule & {
     thenBy: SortRule[];
 };
 export type IndexSettings = {
-    /** One to five fields, matched with their weight. */
+    /** One to five fields, matched with their weight. `typos: false` matches a field's words exactly or as
+     * prefixes, never with typos, for codes, SKUs, and brands. */
     searchableAttributes: {
         field: string;
         weight: number;
+        typos?: false;
     }[];
     facetFields: string[];
     filterFields?: string[];
     typoTolerance: boolean;
+    /** Words of at least `oneTypo` letters match with one typo, and of at least `twoTypos` with two.
+     * `{ oneTypo: 4, twoTypos: 7 }` by default; oneTypo is 3 to 20, twoTypos from oneTypo to 50. */
+    typoWordLengths?: {
+        oneTypo: number;
+        twoTypos: number;
+    };
+    /** Up to 1,000 single words that never match with typos, though prefixes still do, such as brand names. */
+    exactWords?: string[];
     sorts: SortOption[];
     defaultSort: string;
-    /** Orders equally relevant results (within 10% of the best score) by up to three sort fields. */
+    /** Orders every result by up to two sort fields before relevance, in relevance and named sorts (not
+     * distance), such as `[{ field: "soldOut", direction: "asc" }]` for in stock first. Relevance and
+     * custom ranking order each group. Records without the field come last. */
+    rankFirst?: SortRule[];
+    /** Orders equally relevant results (within `relevanceTolerance` of the best score) by up to three sort fields. */
     customRanking?: SortRule[];
+    /** How close to the best match's score, in percent (1 to 50), results count as equally relevant for
+     * custom ranking, and for distance in searches with a query and `near`. 10 by default. */
+    relevanceTolerance?: number;
     /** Groups of interchangeable words or phrases (up to four words each). */
     synonyms?: string[][];
+    /** A query for an input also matches its 1 to 20 synonyms, but not the other way round. Up to 1,000,
+     * each term up to four words. */
+    oneWaySynonyms?: {
+        input: string;
+        synonyms: string[];
+    }[];
+    /** Up to 1,000 query rules, applied at query time, so a change takes effect at once. Up to 10 fire per
+     * search, in this order, and an earlier rule's filter on a field wins over a later one's. */
+    rules?: QueryRule[];
     /** Languages whose common words queries drop, and whose plurals and alternative spellings match. */
     languages?: Array<"da" | "de" | "en" | "is" | "no" | "sv">;
     /** Searches say which words typo tolerance corrected, and `suggest()` offers a corrected query for a
@@ -39,6 +65,40 @@ export type IndexSettings = {
     fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
     [key: string]: unknown;
 };
+/** When a query is, starts with, or contains one of a rule's phrases, the rule's `then` applies to that
+ * search. Phrases are compared as synonyms are: without case, accents, or the index languages' stop words,
+ * and with their plurals and other spellings, so a rule for "balloon" also fires for "balloons". */
+export type QueryRule = {
+    /** 1 to 64 letters, digits, `_`, `.`, `:`, or `-`, unique in the index. */
+    id: string;
+    /** Up to 200 characters, for the people reading the settings. */
+    description?: string;
+    /** false keeps the rule without applying it. Reading settings always returns it; true when left out. */
+    enabled?: boolean;
+    if: {
+        /** 1 to 20 phrases of one to four words. */
+        phrases: string[];
+        /** The query is one of the phrases, starts with one, or contains one; "contains" when left out. */
+        match?: "is" | "startsWith" | "contains";
+    };
+    /** One or more of these. `filters`, `boost` and `bury` take a search's filters, on 1 to 10 fields. */
+    then: {
+        /** Added to the search's filters, except on fields the search (or an earlier rule) already filters.
+         * Records without the field drop out, so `boost` is usually the better choice. */
+        filters?: SearchRequest["filters"];
+        /** Records matching these come before the others, after `rankFirst`'s groups, in searches with a query
+         * sorted by relevance. Several rules' boosts add up. */
+        boost?: SearchRequest["filters"];
+        /** Records matching these come after the others, in the same searches as `boost`. */
+        bury?: SearchRequest["filters"];
+        /** Up to 100 objectIDs left out of the results. */
+        hide?: string[];
+        /** Words searched instead of the matched phrase, up to 64 characters; "" removes the phrase. */
+        replace?: string;
+        /** JSON up to 4 KB returned with the results in `appliedRules`, such as a banner or a redirect. */
+        userData?: unknown;
+    };
+};
 /** A settings change running in the background (with the settings it applies), or the last one's
  * failure. `kind` is "searchable" (new searchable fields filled in) or "rebuild" (a full copy). */
 export type SettingsRebuild = {
@@ -100,7 +160,13 @@ export type SearchRequest = {
     q?: string;
     /** A sort ID from the index settings, "relevance", or "distance" (with `near`). */
     sort?: string;
-    /** Field values to keep: a value, `{ in: [...] }`, or a range `{ gte, lte }` for numbers and dates. */
+    /** Field values to keep. Each field takes a value (a list field contains it), or an object of
+     * conditions that all apply: `in` (any of up to 100 values), `all` (a list field has every one),
+     * `not` and `notIn` (records without the field stay in), and `gte`/`lte` for numbers and dates, such
+     * as `{ tags: { in: ["kids", "adult"], notIn: ["party"] }, price: { lte: 50 } }`. `"$or"` takes one to
+     * four groups of field filters and keeps records that match any group:
+     * `{ inStock: true, $or: [{ brand: "Acme" }, { price: { lte: 20 } }] }`. Up to 20 field filters,
+     * counting those in groups. */
     filters?: Record<string, unknown>;
     facets?: string[];
     /** Facets (also in `facets`) counted without the filter on their own field, so a list of choices
@@ -122,6 +188,13 @@ export type SearchRequest = {
         preTag?: string;
         postTag?: string;
     };
+    /** Say why each hit matched and what ordered it, in each hit's `explain`: each query word's best match in
+     * each searchable field, the relevance band, and the ranking fields' values. For understanding and tuning
+     * ranking; browser search doesn't explain results. */
+    explain?: boolean;
+    /** false searches without the index's query rules, such as to compare results with and without them. On by
+     * default; browser search doesn't take it. */
+    enableRules?: boolean;
     /** Nearest first from a point, with each hit's `distance` in meters; `radius` (meters) keeps only what's
      * within it. With a query, the best matches come first and distance orders them. Needs the index's
      * location field. Records without a location are left out. */
@@ -144,6 +217,60 @@ export type GeoBox = {
     east: number;
     west: number;
 };
+/** How a query word matched: as itself, as the start of a longer word, within its typos, through a synonym, or
+ * as another form of the word in the index's languages (a plural or another spelling). */
+export type MatchKind = "exact" | "prefix" | "typo" | "synonym" | "form";
+/** A query word's best match in one searchable field. `word` is the matched word (or a synonym's phrase) as
+ * the record writes it. `weight` is what that kind of match weighs in the search: the field's weight times 1
+ * for exact, 0.8 for a synonym or word form, 0.2 for a prefix, and 0.1 for a typo. A typo has `edits`, or
+ * `firstLetter` when the first letter differs (tried only when nothing matched without); a synonym has the
+ * `synonym` that matched. */
+export type FieldMatch = {
+    field: string;
+    word: string;
+    how: MatchKind;
+    weight: number;
+    edits?: number;
+    firstLetter?: true;
+    synonym?: string;
+};
+/** A ranking field and the hit's value for it; null when the record has none (it comes last). */
+export type RankingValue = SortRule & {
+    value: unknown;
+};
+/** Why a hit matched and what ordered it, with `explain`. Scores are for the whole record, so matches carry
+ * weights rather than points that add up to `score`. */
+export type HitExplanation = {
+    /** Each query word (after the languages' stop words, up to eight) with its best match in each searchable
+     * field, strongest first. Every word matches somewhere. Empty without a query. */
+    words: {
+        query: string;
+        matches: FieldMatch[];
+    }[];
+    /** With custom ranking (or `near`) and a query: 0 for results within `relevanceTolerance` of `bestScore`,
+     * 1 for the next band down, and so on. Distance (with `near`), then custom ranking, orders the results
+     * within a band. */
+    band?: number | null;
+    /** The best score in the hit's rank first group, among results as boosted by the search's rules (the whole
+     * search without either). */
+    bestScore?: number | null;
+    /** The index's rank first fields. */
+    rankFirst?: RankingValue[];
+    /** The index's custom ranking fields, when sorting by relevance. */
+    customRanking?: RankingValue[];
+    /** The named sort's fields, when sorting by one. */
+    sort?: RankingValue[];
+    /** When the query's rules boosted or buried results: those whose filters the hit matched, if any. */
+    rules?: {
+        id: string;
+        effect: "boost" | "bury";
+    }[];
+};
+/** A query rule the search fired, with its `userData`, if it has any. */
+export type AppliedRule = {
+    id: string;
+    userData?: unknown;
+};
 export type SearchResponse<T> = {
     hits: {
         id: string;
@@ -153,6 +280,8 @@ export type SearchResponse<T> = {
         distance?: number;
         /** With `highlight`: matched searchable fields by path; list fields give one string per value. */
         highlights?: Record<string, string | string[]>;
+        /** With `explain`: why the hit matched and what ordered it. */
+        explain?: HitExplanation;
     }[];
     total: number;
     /** "gte" when `total` is a lower bound (page count mode). */
@@ -172,12 +301,17 @@ export type SearchResponse<T> = {
     /** With the index's `didYouMean` setting: the query with the words typo tolerance corrected, when the
      * results matched some words only by typo ("Showing results for …"), else null. */
     didYouMean?: DidYouMean | null;
+    /** The index's query rules the query fired, in the index's order. Left out when none fired. */
+    appliedRules?: AppliedRule[];
+    /** When a rule replaced words: the query that was searched. */
+    rewrittenQuery?: string;
 };
 /** How a product's recommendations are served (the recommendations add-on). */
 export type RecommendationsRequest = {
     /** Up to this many products in each list, 1 to 20; 8 by default. */
     limit?: number;
-    /** Only picks matching these filters, as in a search (fields configured as filters), such as `{ inStock: true }`. */
+    /** Only picks matching these filters, as in a search (fields configured as filters), such as `{ inStock: true }`.
+     * Each field's filter takes the same shapes; `$or` is for searches only. */
     filters?: SearchRequest["filters"];
     /** The record fields to return; all of them by default. */
     attributesToRetrieve?: string[];

package/dist/index.d.ts

@@ -12,20 +12,46 @@ export type SortOption = SortRule & {
     thenBy: SortRule[];
 };
 export type IndexSettings = {
-    /** One to five fields, matched with their weight. */
+    /** One to five fields, matched with their weight. `typos: false` matches a field's words exactly or as
+     * prefixes, never with typos, for codes, SKUs, and brands. */
     searchableAttributes: {
         field: string;
         weight: number;
+        typos?: false;
     }[];
     facetFields: string[];
     filterFields?: string[];
     typoTolerance: boolean;
+    /** Words of at least `oneTypo` letters match with one typo, and of at least `twoTypos` with two.
+     * `{ oneTypo: 4, twoTypos: 7 }` by default; oneTypo is 3 to 20, twoTypos from oneTypo to 50. */
+    typoWordLengths?: {
+        oneTypo: number;
+        twoTypos: number;
+    };
+    /** Up to 1,000 single words that never match with typos, though prefixes still do, such as brand names. */
+    exactWords?: string[];
     sorts: SortOption[];
     defaultSort: string;
-    /** Orders equally relevant results (within 10% of the best score) by up to three sort fields. */
+    /** Orders every result by up to two sort fields before relevance, in relevance and named sorts (not
+     * distance), such as `[{ field: "soldOut", direction: "asc" }]` for in stock first. Relevance and
+     * custom ranking order each group. Records without the field come last. */
+    rankFirst?: SortRule[];
+    /** Orders equally relevant results (within `relevanceTolerance` of the best score) by up to three sort fields. */
     customRanking?: SortRule[];
+    /** How close to the best match's score, in percent (1 to 50), results count as equally relevant for
+     * custom ranking, and for distance in searches with a query and `near`. 10 by default. */
+    relevanceTolerance?: number;
     /** Groups of interchangeable words or phrases (up to four words each). */
     synonyms?: string[][];
+    /** A query for an input also matches its 1 to 20 synonyms, but not the other way round. Up to 1,000,
+     * each term up to four words. */
+    oneWaySynonyms?: {
+        input: string;
+        synonyms: string[];
+    }[];
+    /** Up to 1,000 query rules, applied at query time, so a change takes effect at once. Up to 10 fire per
+     * search, in this order, and an earlier rule's filter on a field wins over a later one's. */
+    rules?: QueryRule[];
     /** Languages whose common words queries drop, and whose plurals and alternative spellings match. */
     languages?: Array<"da" | "de" | "en" | "is" | "no" | "sv">;
     /** Searches say which words typo tolerance corrected, and `suggest()` offers a corrected query for a
@@ -39,6 +65,40 @@ export type IndexSettings = {
     fieldTypes?: Record<string, "text" | "number" | "boolean" | "text[]" | "number[]" | "boolean[]" | "location">;
     [key: string]: unknown;
 };
+/** When a query is, starts with, or contains one of a rule's phrases, the rule's `then` applies to that
+ * search. Phrases are compared as synonyms are: without case, accents, or the index languages' stop words,
+ * and with their plurals and other spellings, so a rule for "balloon" also fires for "balloons". */
+export type QueryRule = {
+    /** 1 to 64 letters, digits, `_`, `.`, `:`, or `-`, unique in the index. */
+    id: string;
+    /** Up to 200 characters, for the people reading the settings. */
+    description?: string;
+    /** false keeps the rule without applying it. Reading settings always returns it; true when left out. */
+    enabled?: boolean;
+    if: {
+        /** 1 to 20 phrases of one to four words. */
+        phrases: string[];
+        /** The query is one of the phrases, starts with one, or contains one; "contains" when left out. */
+        match?: "is" | "startsWith" | "contains";
+    };
+    /** One or more of these. `filters`, `boost` and `bury` take a search's filters, on 1 to 10 fields. */
+    then: {
+        /** Added to the search's filters, except on fields the search (or an earlier rule) already filters.
+         * Records without the field drop out, so `boost` is usually the better choice. */
+        filters?: SearchRequest["filters"];
+        /** Records matching these come before the others, after `rankFirst`'s groups, in searches with a query
+         * sorted by relevance. Several rules' boosts add up. */
+        boost?: SearchRequest["filters"];
+        /** Records matching these come after the others, in the same searches as `boost`. */
+        bury?: SearchRequest["filters"];
+        /** Up to 100 objectIDs left out of the results. */
+        hide?: string[];
+        /** Words searched instead of the matched phrase, up to 64 characters; "" removes the phrase. */
+        replace?: string;
+        /** JSON up to 4 KB returned with the results in `appliedRules`, such as a banner or a redirect. */
+        userData?: unknown;
+    };
+};
 /** A settings change running in the background (with the settings it applies), or the last one's
  * failure. `kind` is "searchable" (new searchable fields filled in) or "rebuild" (a full copy). */
 export type SettingsRebuild = {
@@ -100,7 +160,13 @@ export type SearchRequest = {
     q?: string;
     /** A sort ID from the index settings, "relevance", or "distance" (with `near`). */
     sort?: string;
-    /** Field values to keep: a value, `{ in: [...] }`, or a range `{ gte, lte }` for numbers and dates. */
+    /** Field values to keep. Each field takes a value (a list field contains it), or an object of
+     * conditions that all apply: `in` (any of up to 100 values), `all` (a list field has every one),
+     * `not` and `notIn` (records without the field stay in), and `gte`/`lte` for numbers and dates, such
+     * as `{ tags: { in: ["kids", "adult"], notIn: ["party"] }, price: { lte: 50 } }`. `"$or"` takes one to
+     * four groups of field filters and keeps records that match any group:
+     * `{ inStock: true, $or: [{ brand: "Acme" }, { price: { lte: 20 } }] }`. Up to 20 field filters,
+     * counting those in groups. */
     filters?: Record<string, unknown>;
     facets?: string[];
     /** Facets (also in `facets`) counted without the filter on their own field, so a list of choices
@@ -122,6 +188,13 @@ export type SearchRequest = {
         preTag?: string;
         postTag?: string;
     };
+    /** Say why each hit matched and what ordered it, in each hit's `explain`: each query word's best match in
+     * each searchable field, the relevance band, and the ranking fields' values. For understanding and tuning
+     * ranking; browser search doesn't explain results. */
+    explain?: boolean;
+    /** false searches without the index's query rules, such as to compare results with and without them. On by
+     * default; browser search doesn't take it. */
+    enableRules?: boolean;
     /** Nearest first from a point, with each hit's `distance` in meters; `radius` (meters) keeps only what's
      * within it. With a query, the best matches come first and distance orders them. Needs the index's
      * location field. Records without a location are left out. */
@@ -144,6 +217,60 @@ export type GeoBox = {
     east: number;
     west: number;
 };
+/** How a query word matched: as itself, as the start of a longer word, within its typos, through a synonym, or
+ * as another form of the word in the index's languages (a plural or another spelling). */
+export type MatchKind = "exact" | "prefix" | "typo" | "synonym" | "form";
+/** A query word's best match in one searchable field. `word` is the matched word (or a synonym's phrase) as
+ * the record writes it. `weight` is what that kind of match weighs in the search: the field's weight times 1
+ * for exact, 0.8 for a synonym or word form, 0.2 for a prefix, and 0.1 for a typo. A typo has `edits`, or
+ * `firstLetter` when the first letter differs (tried only when nothing matched without); a synonym has the
+ * `synonym` that matched. */
+export type FieldMatch = {
+    field: string;
+    word: string;
+    how: MatchKind;
+    weight: number;
+    edits?: number;
+    firstLetter?: true;
+    synonym?: string;
+};
+/** A ranking field and the hit's value for it; null when the record has none (it comes last). */
+export type RankingValue = SortRule & {
+    value: unknown;
+};
+/** Why a hit matched and what ordered it, with `explain`. Scores are for the whole record, so matches carry
+ * weights rather than points that add up to `score`. */
+export type HitExplanation = {
+    /** Each query word (after the languages' stop words, up to eight) with its best match in each searchable
+     * field, strongest first. Every word matches somewhere. Empty without a query. */
+    words: {
+        query: string;
+        matches: FieldMatch[];
+    }[];
+    /** With custom ranking (or `near`) and a query: 0 for results within `relevanceTolerance` of `bestScore`,
+     * 1 for the next band down, and so on. Distance (with `near`), then custom ranking, orders the results
+     * within a band. */
+    band?: number | null;
+    /** The best score in the hit's rank first group, among results as boosted by the search's rules (the whole
+     * search without either). */
+    bestScore?: number | null;
+    /** The index's rank first fields. */
+    rankFirst?: RankingValue[];
+    /** The index's custom ranking fields, when sorting by relevance. */
+    customRanking?: RankingValue[];
+    /** The named sort's fields, when sorting by one. */
+    sort?: RankingValue[];
+    /** When the query's rules boosted or buried results: those whose filters the hit matched, if any. */
+    rules?: {
+        id: string;
+        effect: "boost" | "bury";
+    }[];
+};
+/** A query rule the search fired, with its `userData`, if it has any. */
+export type AppliedRule = {
+    id: string;
+    userData?: unknown;
+};
 export type SearchResponse<T> = {
     hits: {
         id: string;
@@ -153,6 +280,8 @@ export type SearchResponse<T> = {
         distance?: number;
         /** With `highlight`: matched searchable fields by path; list fields give one string per value. */
         highlights?: Record<string, string | string[]>;
+        /** With `explain`: why the hit matched and what ordered it. */
+        explain?: HitExplanation;
     }[];
     total: number;
     /** "gte" when `total` is a lower bound (page count mode). */
@@ -172,12 +301,17 @@ export type SearchResponse<T> = {
     /** With the index's `didYouMean` setting: the query with the words typo tolerance corrected, when the
      * results matched some words only by typo ("Showing results for …"), else null. */
     didYouMean?: DidYouMean | null;
+    /** The index's query rules the query fired, in the index's order. Left out when none fired. */
+    appliedRules?: AppliedRule[];
+    /** When a rule replaced words: the query that was searched. */
+    rewrittenQuery?: string;
 };
 /** How a product's recommendations are served (the recommendations add-on). */
 export type RecommendationsRequest = {
     /** Up to this many products in each list, 1 to 20; 8 by default. */
     limit?: number;
-    /** Only picks matching these filters, as in a search (fields configured as filters), such as `{ inStock: true }`. */
+    /** Only picks matching these filters, as in a search (fields configured as filters), such as `{ inStock: true }`.
+     * Each field's filter takes the same shapes; `$or` is for searches only. */
     filters?: SearchRequest["filters"];
     /** The record fields to return; all of them by default. */
     attributesToRetrieve?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@findlane/server",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Findlane server SDK: upload catalogs, manage index settings, and search with a secret workspace API key.",
   "keywords": ["findlane", "search", "full-text search", "typo tolerance", "ecommerce search", "search api", "sdk"],
   "license": "MIT",