自訂分析器

自訂分析器可讓您控制 Azure DocumentDB 如何為全文搜尋處理文字。 定義權杖化與權杖篩選流程,以支援不區分大小寫的比對、前綴搜尋、階層式識別碼,以及語言專屬分析。

您可以在搜尋索引定義中宣告自訂分析器,並在可搜尋的字串欄位中依名稱參考這些分析器。 單一索引可以涵蓋多個欄位,每個欄位可以使用不同的分析器。

Note

全文搜尋目前處於預覽階段。 在使用這些範例之前,請先為您的叢集啟用全文搜尋。

自訂分析器的運作方式

分析器會將輸入字串轉換為可搜尋的權杖。 它有兩個元件:

  • 分詞器。 將輸入分割成權杖。 每個分析器恰好有一個分詞器。
  • 詞元篩選器。 將標記標準化或轉換。 分析器可以有零個或多個令牌篩選器,並依您指定的順序套用。

分析會在文件被索引且查詢文字處理時執行:

Setting Purpose
analyzer 在索引時間處理欄位值。
searchAnalyzer 在查詢時處理查詢文字。 若省略,查詢也會使用索引分析器。
multi 為同一字串欄位定義替代分析分析器的映射。

在索引定義層級設定 searchAnalyzer 和 analyzer 以提供預設值,或在字串欄位上設定它們以覆寫預設值。 當兩條管線產生相同的正規化形式時,查詢標記會匹配已索引的標記。

這些流程不必總是完全相同。 例如,前綴搜尋可以在索引時產生前綴,並在查詢時保留完整的查詢字串。

何時使用自訂分析器

當內建分析器無法滿足您的索引或查詢需求時,請使用自訂分析器。 選擇一個支援的權杖化工具,並依照您的工作負載需求組合支援的令牌篩選器。

需求 分析儀配置
不區分大小寫的比對 新增 lowerCase 令牌篩選器。
不區分重音的比對 新增 asciiFolding 令牌篩選器。
零件編號或 SKU 上的前綴匹配 使用 edgeGram 分詞器或令牌篩選器。
階層式識別碼搜尋 使用 pathHierarchy 分詞工具。
匹配詞形 新增語言專屬的 stemmer token 篩選器。
移除常用詞彙 新增 stopWords 令牌篩選器。
在所選分隔符上分割識別碼 使用 charGroup 或 pattern 分詞器。
對同一欄位進行的替代分析 定義具名 multi 對應。

支援的權杖產生器

在自訂分析器中使用下列分詞器類型之一。

Tokenizer 選項 Purpose
whitespace None. 按空白字元分割文字。
keyword None. 將完整輸入保留為單一標記。
pattern 必須 pattern;可選 group,預設 0。 使用正則表達式分割或擷取 token。
charGroup 必須的 tokenizeOnChars 陣列。 依空白字元或指定的常值字元進行分割。
pathHierarchy 可選 delimiter,預設為 /;replacement,預設分隔符;skip,預設為 0;及 reverse,預設為 false。 為階層式路徑的連續層級產生權杖。 分隔符號和取代字元皆為單一字元。
edgeGram 必須有 minGram 和 maxGram。 產生錨定在輸入內容開頭的前綴。
nGram 必須有 minGram 和 maxGram。 在整個輸入內容中產生滑動字元序列。
simple None. 將文字轉為小寫,並依非字母字元分割。
chinese、japanese、korean、thai None. 套用語言特定的斷詞處理。

對於 edgeGram 和 nGram,兩個 gram 長度都必須是至少 1 的整數,且 minGram 不得超過 maxGram。

對於 pattern,請指定內嵌正則表達式旗標,例如 (?i)。 不支援獨立 tokenizer.flags 選項。 預設擷取群組為 0,用來識別整個匹配。

支援的代幣過濾器

依照您想要套用的順序新增權杖篩選器。

令牌過濾器 選項 Purpose
lowerCase None. 將權杖轉換為小寫。
asciiFolding None. 在可用的情況下,將非 ASCII 字元轉換為最接近的 ASCII 對應字元。
removeLong None. 移除超過分析器支援的標記長度的標記。
length 可選 min,預設 0;可選 max,預設 255。 將權杖保持在指定長度範圍內。
stemmer 必要的 language。 將屈折變化詞還原為語言特定的詞根。
stopWords tokens 或 language。 移除明確的標記清單或語言特定的停字。
edgeGram 必須有 minGram 和 maxGram,且兩者皆至少為 1。 從分詞器產生的每個標記產生前綴。
patternCapture 必須的 patterns 陣列;可選 preserveOriginal,預設 false。 使用正則表達式模式擷取權杖內容。
patternReplace 必填 pattern 和 replacement;選填 replaceAll,預設為 true。 取代 token 中相符的內容。

對於 stopWords,請指定一個 tokens 陣列或一個 language,而非兩者皆有。 對於篩選器 edgeGram , minGram 不得超過 maxGram。

使用自訂分析器建立搜尋索引

以下範例使用 MongoDB Shell 語法及已啟用全文搜尋的 Azure DocumentDB 叢集。 使用名為 products的新集合。

新增範例文件

建立集合並新增虛構產品資料,用於前綴、階層及文字查詢。

db.createCollection("products");

db.products.insertMany([
  {
    _id: 1,
    partNumber: "SKU-SHOE-001",
    alternatePartNumber: "ALT-SHOE-001",
    basicNumber: "catalog/outdoor/running",
    title: "Running shoes",
    description: "Lightweight shoes for everyday running"
  },
  {
    _id: 2,
    partNumber: "SKU-BOOT-002",
    alternatePartNumber: "SKU-SHOE-002",
    basicNumber: "catalog/outdoor/hiking",
    title: "Trail shoes",
    description: "Durable shoes for outdoor trails"
  },
  {
    _id: 3,
    partNumber: "SKU-SANDAL-003",
    alternatePartNumber: "ALT-SANDAL-003",
    basicNumber: "catalog/indoor/casual",
    title: "Walking shoes",
    description: "Comfortable shoes for everyday walking"
  }
]);

定義分析器與欄位映射

使用 createSearchIndexes 建立具名搜尋索引。 明確設定 dynamic: false 並宣告每個可搜尋欄位。

db.runCommand({
  createSearchIndexes: "products",
  indexes: [
    {
      name: "idx_products_analyzers",
      definition: {
        mappings: {
          dynamic: false,
          fields: {
            partNumber: {
              type: "string",
              analyzer: "part_prefix",
              searchAnalyzer: "identifier_query"
            },
            alternatePartNumber: {
              type: "string",
              analyzer: "part_prefix",
              searchAnalyzer: "identifier_query"
            },
            basicNumber: {
              type: "string",
              analyzer: "basic_hierarchy",
              searchAnalyzer: "identifier_query"
            },
            title: {
              type: "string",
              analyzer: "normalized_text",
              multi: {
                stems: {
                  type: "string",
                  analyzer: "english_stems"
                }
              }
            },
            description: {
              type: "string",
              analyzer: "normalized_text"
            }
          }
        },
        analyzers: [
          {
            name: "part_prefix",
            tokenizer: {
              type: "edgeGram",
              minGram: 2,
              maxGram: 20
            },
            tokenFilters: [
              { type: "lowerCase" }
            ]
          },
          {
            name: "identifier_query",
            tokenizer: { type: "keyword" },
            tokenFilters: [
              { type: "lowerCase" }
            ]
          },
          {
            name: "basic_hierarchy",
            tokenizer: {
              type: "pathHierarchy",
              delimiter: "/"
            },
            tokenFilters: [
              { type: "lowerCase" }
            ]
          },
          {
            name: "normalized_text",
            tokenizer: { type: "whitespace" },
            tokenFilters: [
              { type: "lowerCase" },
              { type: "asciiFolding" }
            ]
          },
          {
            name: "english_stems",
            tokenizer: { type: "whitespace" },
            tokenFilters: [
              { type: "lowerCase" },
              { type: "stemmer", language: "english" }
            ]
          }
        ]
      }
    }
  ]
});

確認索引已準備好

指令返回後,索引建立仍可繼續。 檢查指定索引,並等待它回報 status: "READY" 和 queryable: true 後再執行查詢。

db.products.aggregate([
  { $listSearchIndexes: { name: "idx_products_analyzers" } }
]);

執行前綴查詢

前綴搜尋會匹配欄位值的開頭。 它對於零件編號、SKU 以及使用者逐步輸入的其他識別碼非常有用。

分析器會在 part_prefix 索引時間產生前綴。 identifier_query 分析器會將查詢保留為一個小寫標記。

db.products.aggregate([
  {
    $search: {
      index: "idx_products_analyzers",
      text: {
        query: "sku-shoe",
        path: "partNumber"
      }
    }
  },
  { $limit: 20 },
  {
    $project: {
      _id: 0,
      partNumber: 1,
      score: { $meta: "searchScore" }
    }
  }
]);

此查詢會比對到 SKU-SHOE-001。 選擇 minGram 和 maxGram,作為您的應用程式所需的前綴長度。 超出該範圍的前綴不會由此分析器產生。 產生更多前綴會增加索引大小。

edgeGram分詞器會從輸入產生前綴。 edgeGram權杖篩選器會從分詞器產生的每個權杖產生前綴。 當你需要先將文字分詞成詞彙再產生前綴時,請使用這個篩選器。

前綴匹配edgeGram不需要autocomplete運算子。 該運算子目前尚未支援。

執行階層式查詢

pathHierarchy分詞器會為識別碼的連續層級產生標記。 以 / 為分隔符,catalog/outdoor/running 會產生:

catalog
catalog/outdoor
catalog/outdoor/running

使用查詢時 keyword 分詞器搜尋特定階層層級,且不將查詢擴展至其父層級。

db.products.aggregate([
  {
    $search: {
      index: "idx_products_analyzers",
      text: {
        query: "catalog/outdoor",
        path: "basicNumber"
      }
    }
  },
  { $limit: 20 },
  {
    $project: {
      _id: 0,
      basicNumber: 1,
      score: { $meta: "searchScore" }
    }
  }
]);

此查詢匹配 catalog/outdoor/running 與 catalog/outdoor/hiking。 使用選用 replacement的 、 skip和 reverse 設定來自訂階層式標記的產生方式。

搜尋多個識別欄位

一個搜尋索引可以涵蓋多個識別欄位。 傳入明確的映射路徑陣列至 text,以便一併搜尋。

db.products.aggregate([
  {
    $search: {
      index: "idx_products_analyzers",
      text: {
        query: "sku-shoe",
        path: ["partNumber", "alternatePartNumber"],
        matchCriteria: "any"
      }
    }
  },
  { $limit: 20 },
  {
    $project: {
      _id: 0,
      partNumber: 1,
      alternatePartNumber: 1,
      score: { $meta: "searchScore" }
    }
  }
]);

此查詢透過 partNumber 匹配第一份文件,並透過 alternatePartNumber 匹配第二份文件。 每條路徑都必須在所選索引中映射。 如果沒有任何單一索引能涵蓋所有請求的路徑,查詢會回傳錯誤。

在同一欄位使用多個分析器

一個 multi 映射會用替代分析器索引相同的字串欄位。 此功能支援不同的匹配行為,且不會儲存重複的文件欄位。

範例索引在 title 上定義了 stems 映射。 使用 path: { value, multi } 選取該對應:

db.products.aggregate([
  {
    $search: {
      index: "idx_products_analyzers",
      text: {
        query: "running",
        path: {
          value: "title",
          multi: "stems"
        }
      }
    }
  },
  { $limit: 20 },
  {
    $project: {
      _id: 0,
      title: 1,
      score: { $meta: "searchScore" }
    }
  }
]);

替代分析器將英文詞幹分析套用於索引文本與查詢文本。 multi映射與多欄位索引不同:multi提供同一欄位的多種分析變體,而多欄位索引則涵蓋多個文件欄位。

使用語言專屬分析工具

Azure DocumentDB 提供中文、日文、韓文與泰文的內建分析工具。 請以 documentdb. 前綴引用這些分析器。 在自訂管線內,請使用未前綴的分詞器名稱。

語言 內建分析器 自訂分詞器類型
Chinese documentdb.chinese chinese
日本 documentdb.japanese japanese
韓語 documentdb.korean korean
Thai documentdb.thai thai

設定預設分析器

在索引定義中設定 analyzer,以為對應的字串欄位提供預設值。 欄位層級 analyzer 會覆寫該預設值。 如果您未設定 searchAnalyzer,查詢將使用該欄位的有效索引時間分析器。

以下索引將其設 documentdb.chinese 為預設分析器。 欄位 titleZh 繼承該預設值,而 descriptionZh 欄位則以自訂語言 tokenizer 流程覆寫該預設值:

db.runCommand({
  createSearchIndexes: "products",
  indexes: [
    {
      name: "idx_products_languages",
      definition: {
        analyzer: "documentdb.chinese",
        mappings: {
          dynamic: false,
          fields: {
            titleZh: {
              type: "string"
            },
            descriptionZh: {
              type: "string",
              analyzer: "chinese_normalized"
            }
          }
        },
        analyzers: [
          {
            name: "chinese_normalized",
            tokenizer: { type: "chinese" },
            tokenFilters: [
              { type: "lowerCase" }
            ]
          }
        ]
      }
    }
  ]
});

目前限制

以下限制適用於自訂分析器及其欄位映射:

  • 設定 dynamic: false 或省略 dynamic 會使用靜態映射。 您必須在 mappings.fields 之下明確宣告所有可搜尋欄位。 設定dynamic: true會導致索引建立失敗,並顯示 mappings.dynamic is not supported in search indexes yet.。如果缺少 mappings.fields 或其為空,索引建立也會失敗。
  • 自訂分析器名稱必須在索引定義中唯一且不超過32個字元。
  • 欄位的分析器設定必須參考支援的內建分析器或索引定義中宣告的自訂分析器。
  • 不支援字元篩選器(charFilters)及同義詞定義。
  • 不支援 autocomplete 和 queryString 運算子。
  • wildcard裡面的regex和$search運算子不被支援。