FacetSpec

執行多面向搜尋的 facet 規格。

JSON 表示法 
{
  "facetKey": {
    object (FacetKey)
  },
  "limit": integer,
  "excludedFilterKeys": [
    string
  ],
  "enableDynamicPosition": boolean
}
欄位
facetKey

object (FacetKey)

這是必要旗標，構面鍵規格。
limit

integer

這個 Facet 傳回的 Facet 值數量上限。如未指定，則預設值為 20。允許的最大值為 300。如果值超過 300，系統會強制設為 300。在醫療照護搜尋中進行匯總時，如果 [FacetKey.key] 是「healthcare_aggregation_key」，系統會將限制內部覆寫為 10,000，無論您在此設定的值為何。

如果這個欄位為負數，系統會傳回 INVALID_ARGUMENT。
excludedFilterKeys[]

string

分層檢索時要排除的金鑰清單。

根據預設，除非 FacetKey.key 列在這個欄位中，否則不會從篩選器中排除。

在這個欄位中列出 Facet 鍵，即使 Facet 值已從搜尋結果中篩除，仍會顯示為 Facet 結果。使用這個欄位不會影響傳回的搜尋結果。

舉例來說，假設有 100 份文件的顏色 Facet 為「紅色」，200 份文件的顏色 Facet 為「藍色」。如果查詢包含「color:ANY("Red")」篩選器，且「color」為 FacetKey.key，則預設只會在搜尋結果中傳回「Red」文件，並只傳回「Red」和計數 100 做為顏色 Facet。雖然也有藍色文件，但「藍色」不會顯示為可用的 Facet 值。

如果「color」列在「excludedFilterKeys」中，查詢會傳回 Facet 值「Red」(計數為 100) 和「Blue」(計數為 200)，因為「color」鍵現在已從篩選器中排除。由於這個欄位不會影響搜尋結果，因此搜尋結果仍會正確篩選，只傳回「紅色」文件。

最多可輸入 100 個值。否則，系統會傳回 INVALID_ARGUMENT 錯誤。
enableDynamicPosition

boolean

啟用這個 facet 的動態位置。如設為 true，系統會自動決定這個側面的位置，以及回應中的所有側面。如果啟用動態 facet，系統會一併排序。如果設為 false，回應中這個 facet 的位置會與要求中的位置相同，且會排在啟用動態位置的 facet 和所有動態 facet 之前。

舉例來說，您可能希望一律在回應中傳回評分層面，但不一定會一律在頂端顯示評分層面。在這種情況下，您可以將 enableDynamicPosition 設為 true，讓系統自動決定回應中評分構面的位置。

再舉一例，假設要求中包含下列構面：

  • "rating", enableDynamicPosition = true

  • "price"，enableDynamicPosition = false

  • 「brands」，enableDynamicPosition = false

此外，您也啟用了動態 facet，這會產生 facet gender。然後，回應中構面最終順序可以是 ("price", "brands", "rating", "gender") 或 ("price", "brands", "gender", "rating")，取決於 API 如何排序「gender」和「rating」構面。不過請注意，「price」和「brands」一律會排在第一和第二位，因為它們的 enableDynamicPosition 為 false。

FacetKey

指定如何計算側邊。

JSON 表示法 
{
  "key": string,
  "intervals": [
    {
      object (Interval)
    }
  ],
  "restrictedValues": [
    string
  ],
  "prefixes": [
    string
  ],
  "contains": [
    string
  ],
  "caseInsensitive": boolean,
  "orderBy": string
}
欄位
key

string

這是必要旗標，Document 物件中支援的文字和數值層面鍵，系統會根據這些鍵計算層面值。分頁鍵須區分大小寫。
intervals[]

object (Interval)

只有在值應分組到間隔時才設定。必須為具有數值的 facet 設定。不得為含有文字值的 facet 設定。間隔數上限為 30。
restrictedValues[]

string

只取得指定受限值的 facet。僅支援文字欄位。舉例來說，假設「類別」有三個值：「動作 > 2022」、「動作 > 2021」和「科幻 > 2022」。如果將「restrictedValues」設為「Action > 2022」，則「category」層面只會包含「Action > 2022」。僅支援文字欄位。最多 10 個。
prefixes[]

string

只取得以指定字串前置字元開頭的側欄值。舉例來說，假設「類別」有三個值：「動作 > 2022」、「動作 > 2021」和「科幻 > 2022」。如果將「前置字元」設為「動作」，則「類別」層面只會包含「動作 > 2022」和「動作 > 2021」。僅支援文字欄位。最多 10 個。
contains[]

string

只取得包含指定字串的側滑選單值。舉例來說，假設「類別」有三個值：「動作 > 2022」、「動作 > 2021」和「科幻 > 2022」。如果將「包含」設為「2022」，則「類別」層面只會包含「動作 > 2022」和「科幻 > 2022」。僅支援文字欄位。最多 10 個。
caseInsensitive

boolean

如果使用前置字元或包含字元取得分面值時，分面鍵不區分大小寫，則為 True；否則為 False。
orderBy

string

傳回文件的順序。

允許的值包括：

如未設定，文字值會以自然順序排序；數值間隔則會以 FacetSpec.FacetKey.intervals 指定的順序排序。