FacetSpec

用于执行分面搜索的分面规范。

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

object (FacetKey)

必需。分面键规范。
limit

integer

针对相应分面返回的分面值数量上限。如果未指定，则默认为 20。允许的最大值为 300。大于 300 的值会强制转换为 300。对于医疗保健搜索中的聚合，当 [FacetKey.key] 为“healthcare_aggregation_key”时，无论此处设置的值是多少，系统都会在内部将限制替换为 10,000。

如果此字段为负数，则返回 INVALID_ARGUMENT。
excludedFilterKeys[]

string

分面时要排除的键的列表。

默认情况下，除非 FacetKey.key 列在此字段中，否则不会从过滤条件中排除。

在此字段中列出构面键后，即使构面值被过滤出搜索结果，仍可显示为构面结果。使用此字段不会影响返回的搜索结果。

例如，假设有 100 个文档的颜色构面为“红色”，200 个文档的颜色构面为“蓝色”。包含过滤条件“color:ANY("Red")”且将“color”设为 FacetKey.key 的查询默认只会返回搜索结果中的“红色”文档，并且还会返回“红色”以及数量 100，作为唯一的颜色构面。虽然也有蓝色文档，但“蓝色”不会显示为可用的构面值。

如果“color”列在“excludedFilterKeys”中，则查询会返回构面值“Red”（数量为 100）和“Blue”（数量为 200），因为“color”键现在已从过滤条件中排除。由于此字段不会影响搜索结果，因此搜索结果仍会正确过滤，仅返回“红色”文档。

最多允许 100 个值。否则，系统将返回 INVALID_ARGUMENT 错误。
enableDynamicPosition

boolean

为此分面启用动态位置。如果设置为 true，则系统会自动确定此分面在响应中所有分面中的位置。如果启用了动态分面，则会一起排序。如果设置为 false，则相应分面在响应中的位置与在请求中的位置相同，并且其排名高于启用动态位置的分面和所有动态分面。

例如，您可能希望始终在响应中返回评分分面，但不一定始终将评分分面显示在顶部。在这种情况下，您可以将 enableDynamicPosition 设置为 true，以便自动确定响应中评分分面的位置。

再举一个例子，假设请求中包含以下方面：

  • “rating”，enableDynamicPosition = true

  • “price”，enableDynamicPosition = false

  • “brands”，enableDynamicPosition = false

此外，您还启用了动态分面，这会生成分面 gender。然后，响应中各构面的最终顺序可以是（“价格”“品牌”“评分”“性别”），也可以是（“价格”“品牌”“性别”“评分”），具体取决于 API 如何对“性别”和“评分”构面进行排序。不过，请注意，“价格”和“品牌”始终排在第一位和第二位，因为它们的 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 设置。间隔数上限为 30。
restrictedValues[]

string

仅获取指定受限值的分面。仅支持文本字段。例如，假设“category”有三个值：“Action > 2022”“Action > 2021”和“Sci-Fi > 2022”。如果将“restrictedValues”设置为“Action > 2022”，则“category”分面仅包含“Action > 2022”。仅支持文本字段。最多 10 个。
prefixes[]

string

仅获取以指定字符串前缀开头的分面值。例如，假设“category”有三个值：“Action > 2022”“Action > 2021”和“Sci-Fi > 2022”。如果将“prefixes”设置为“Action”，则“category”分面仅包含“Action > 2022”和“Action > 2021”。仅支持文本字段。最多 10 个。
contains[]

string

仅获取包含指定字符串的分面值。例如，假设“category”有三个值：“Action > 2022”“Action > 2021”和“Sci-Fi > 2022”。如果将“contains”设置为“2022”，则“category”分面仅包含“Action > 2022”和“Sci-Fi > 2022”。仅支持文本字段。最多 10 个。
caseInsensitive

boolean

如果为 true，则在获取带有前缀或包含的分面值时，分面键不区分大小写；否则为 false。
orderBy

string

返回文档的顺序。

允许的值为：

如果未设置，则文本值按自然顺序排序；数值区间按 FacetSpec.FacetKey.intervals 给定的顺序排序。