結構化與文字搜尋

結構化與文字搜尋將相關性排序的文字匹配與精確值、數字與日期範圍及其他條件結合在同一 $search 階段進行。 將文字與結構化欄位對應到相同的搜尋索引,然後使用 compound 來合併這些條件。

在僅僅匹配文字不足的商品型錄、知識庫及其他集合中,請使用此方法。 例如,搜尋商品描述時,卻要求商品在特定價格範圍內有現貨。

Note

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

支援的欄位對應

在 mappings.fields 下宣告可搜尋欄位。 選擇與儲存值及查詢相符的類型。

欄位類型 Purpose 支援查詢與排序
string 分析過的文字。 text、模糊 text、且 phrase。
document 巢狀欄位的容器。 查詢會針對其明確對應的葉欄位。
token 精確字串詞彙,例如識別碼與類別。 , equals、range、exists、in,和內嵌排序。
number 數值。 equals、range、exists、in,以及內嵌排序。
date 日期值。 equals、range、exists、in、內嵌排序。
boolean 布林值。 equals、、 exists、 in以及內嵌排序。

使用 string 處理經分析的語言文字,並使用 token 進行精確的字串比較。 對於數字欄位,請依您的資料設定 representation 為 double 或 int64 。

巢狀欄位使用 document.fields 遞迴映射。 使用點號路徑來定址映射的葉節點欄位,例如 details.region。

陣列不需要獨立的映射類型。 映射其元素的類型。 當陣列值的型別與欄位對應相符時,會被索引;具有其他類型的元素不會為該欄位建立索引。

建立文字與結構化欄位的搜尋索引

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

新增範例文件

建立集合並新增包含文字、識別碼、價格、可用性及日期的文件。

db.createCollection("products");

db.products.insertMany([
  {
    _id: 1,
    title: "Bracket controller",
    description: "Steel mounting bracket for a controller",
    partNumber: "SKU-BRACKET-001",
    category: "hardware",
    price: 49.0,
    inStock: true,
    publishedAt: ISODate("2026-09-01T00:00:00Z"),
    details: { region: "west" }
  },
  {
    _id: 2,
    title: "Bracket assembly",
    description: "Heavy-duty bracket for an industrial controller",
    partNumber: "SKU-BRACKET-002",
    category: "hardware",
    price: 129.0,
    inStock: true,
    publishedAt: ISODate("2026-10-01T00:00:00Z"),
    details: { region: "east" }
  },
  {
    _id: 3,
    title: "Lightweight bracket",
    description: "Compact bracket for a controller",
    partNumber: "SKU-BRACKET-003",
    category: "accessories",
    price: 29.0,
    inStock: false,
    publishedAt: ISODate("2026-10-15T00:00:00Z"),
    details: { region: "west" }
  }
]);

對應可搜尋欄位

建立一個索引,涵蓋查詢所用的所有欄位。

db.runCommand({
  createSearchIndexes: "products",
  indexes: [
    {
      name: "idx_products_filters",
      definition: {
        mappings: {
          dynamic: false,
          fields: {
            title: { type: "string" },
            description: { type: "string" },
            partNumber: { type: "token" },
            category: { type: "token" },
            price: { type: "number", representation: "double" },
            inStock: { type: "boolean" },
            publishedAt: { type: "date" },
            details: {
              type: "document",
              fields: {
                region: { type: "token" }
              }
            }
          }
        }
      }
    }
  ]
});

確認索引已準備好

指令返回後,索引建立仍可繼續。 等待,直到索引顯示 status: "READY" 和 queryable: true。

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

結合文字與結構化條件

使用 compound 來合併操作員文件。 每個子句包含一個條件陣列。

條款 Behavior
must 每一項條件都必須符合並有助於相關性。
should 匹配條件能提升相關性。 在有必要條件的查詢中,它們不必匹配。
mustNot 相符的文件會被排除。
filter 每個條件都必須相符。 目前條件會影響相關性。

以下查詢會搜尋兩個文字欄位,要求商品有現貨,且價格介於 20 到 100,並優先比對標題中的完全相符詞組:

db.products.aggregate([
  {
    $search: {
      index: "idx_products_filters",
      compound: {
        must: [
          {
            text: {
              query: "bracket controller",
              path: ["title", "description"],
              matchCriteria: "all"
            }
          }
        ],
        should: [
          {
            phrase: {
              query: "bracket controller",
              path: "title",
              slop: 0
            }
          }
        ],
        filter: [
          { equals: { path: "inStock", value: true } },
          { range: { path: "price", gte: 20, lte: 100 } },
          { in: { path: "category", value: ["hardware", "accessories"] } },
          { exists: { path: "publishedAt" } }
        ],
        mustNot: [
          { equals: { path: "details.region", value: "retired" } }
        ]
      }
    }
  },
  { $limit: 10 },
  {
    $project: {
      _id: 0,
      title: 1,
      partNumber: 1,
      price: 1,
      inStock: 1,
      score: { $meta: "searchScore" }
    }
  }
]);

對於範例資料,查詢會回傳 Bracket controller。 較昂貴的組件和缺貨的支架無法符合所需條件。

Important

compound.minimumShouldMatch 目前不支援。 compound.filter 中的條件會影響相關性評分,也會限制符合項目。 不要以為某個篩選條件會讓分數保持不變。

使用結構化運算子

結構化運算符號會比對索引值,而非經分析的文字。 查詢值類型必須與其欄位對應相符。

Operator Purpose 必要選項
equals 與精確值相符。 path 以及 value。
range 匹配 number、date 或 token 欄位上的有界值。 path以及至少下列其中一項:gt、gte、lt或lte。
exists 將路徑上有索引值的文件匹配。 path。
in 匹配集合中的某個值。 path 還有一個 value 陣列。

例如,使用 equals 搜尋精確的零件編號:

db.products.aggregate([
  {
    $search: {
      index: "idx_products_filters",
      equals: {
        path: "partNumber",
        value: "SKU-BRACKET-001"
      }
    }
  },
  { $limit: 10 },
  { $project: { _id: 0, title: 1, partNumber: 1 } }
]);

對於日期範圍,請使用日期值而非字串:

db.products.aggregate([
  {
    $search: {
      index: "idx_products_filters",
      range: {
        path: "publishedAt",
        gte: ISODate("2026-10-01T00:00:00Z"),
        lt: ISODate("2026-11-01T00:00:00Z")
      }
    }
  },
  { $limit: 10 },
  { $project: { _id: 0, title: 1, publishedAt: 1 } }
]);

搜尋多個文字欄位

傳入一個明確的映射路徑陣列,以 text 搜尋多個欄位。 用於 matchCriteria: "any" 匹配任何已分析的查詢詞,或 "all" 要求所有已分析的查詢詞彙。

db.products.aggregate([
  {
    $search: {
      index: "idx_products_filters",
      text: {
        query: "bracket controller",
        path: ["title", "description"],
        matchCriteria: "all"
      }
    }
  },
  { $limit: 20 },
  {
    $project: {
      _id: 0,
      title: 1,
      description: 1,
      score: { $meta: "searchScore" }
    }
  }
]);

您必須包含所選搜尋索引中的每一條路徑。 查詢 text 只接受一個非空的查詢字串,而非一組查詢字串。 若要搜尋具有不同分析需求的多個識別欄位,請參閱 自訂分析器。

不支援萬用字元查詢路徑。 請明確指定每條映射路徑。

排序與限制搜尋結果

搜尋結果預設依相關性遞減排序。 在 $search 內設定 sort,以依索引的標量欄位排序結果。

db.products.aggregate([
  {
    $search: {
      index: "idx_products_filters",
      text: {
        query: "bracket",
        path: "description"
      },
      sort: {
        inStock: -1,
        price: 1,
        score: { $meta: "searchScore" }
      }
    }
  },
  { $limit: 20 },
  {
    $project: {
      _id: 0,
      title: 1,
      price: 1,
      inStock: 1,
      score: { $meta: "searchScore" }
    }
  }
]);

內嵌欄位排序接受1表示升序,或token表示降序,用於已對應的number、date、boolean和-1欄位。 分數排序僅為降序。 當你需要與下游 $sort相同的陣列排序語意時,避免在陣列值欄位上進行內嵌排序。

若可能,請將 $search 緊接在 $limit 之後。 搜尋執行時會將限制下推至搜尋執行流程中,讓引擎在收集到指定的頂尖結果後即可停止。

如果某個條件無法用支援的搜尋運算子來表達,請在最後的 $match 之前使用下游 $limit。 在套用商業篩選條件前限制候選項目可能會遺漏符合資格的結果。

目前限制

以下限制適用於結構化搜尋與複合搜尋:

  • 映射是靜態的。 您必須宣告所選搜尋索引中的每個查詢及內嵌排序路徑。
  • 不支援 objectId、uuid 和 embeddedDocument 欄位類型。
  • 不支援 near 運算子。
  • wildcard裡面的regex和$search運算子不被支援。
  • $searchMeta 階段、$$SEARCH_META 變數、計數、Facet、醒目提示和自訂分數加成都不支援。
  • 使用該 dropIndexes 指令來刪除搜尋索引。 專用的搜尋索引更新 API 並不包含在目前支援的管理介面中。