使用聚合和预览 (优化) Refine search results using aggregations (preview)

优化搜索结果,在索引中显示其分布。Refine search results and show their distribution in the index.

示例 1:按字符串字段请求聚合Example 1: Request aggregations by string fields

以下示例搜索 listItem 资源,并按其文件类型和内容类聚合结果,两者都是字符串值。The following example searches listItem resources and aggregates results by their file type and content class, both of which are string values.

该响应包括两个聚合的 searchBucket 对象:The response includes two searchBucket objects for the two aggregations:

  • 属性 指定实际值 (聚合) 同一存储桶中的 FileType contentclass 那些匹配的 listItem 对象的值。The key property specifies the actual value (by FileType or contentclass) for those matching listItem objects that are aggregated in the same bucket by that value.
  • count 属性指定聚合在同一存储桶中的此类对象的数量。The count property specifies the number of such objects aggregated in the same bucket. 请注意,此数字是匹配数的近似值,不会提供确切的匹配数。Note that this number is an approximation of the number of matches and will not provide an exact number of matches.
  • 按文件类型聚合的结果存储桶按计数降序排序。Buckets of results aggregated by file type are sorted by count in descending order. 本示例中,有 3 个存储桶用于 3 种文件类型:、 docx xlsxpptxIn this example, there are 3 buckets for 3 file types: docx, xlsx, and pptx.
  • 由内容类聚合的结果存储桶按内容类的字符串值按降序排序。Buckets of results aggregated by content class are sorted by the string value of the content class in descending order. 本示例中,只有一个存储桶,其中所有匹配的对象共享同一个内容类 STS_ListItem_DocumentLibraryIn this example, there is only one bucket with all the matching objects sharing the same content class, STS_ListItem_DocumentLibrary.

请求Request

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
          "listItem"
      ],
      "query": {
          "queryString": "test"
      },
      "from": 0,
      "size": 25,
      "aggregations": [
          {
              "field": "FileType",
              "size": 20,
              "bucketDefinition": {
                  "sortBy": "count",
                  "isDescending": "true",
                  "minimumCount": 0
              }
          },
          {
              "field": "contentclass",
              "size": 15,
              "bucketDefinition": {
                  "sortBy": "keyAsString",
                  "isDescending": "true",
                  "minimumCount": 0
              }
          }
      ]
    }
  ]
}

响应Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.searchResponse",
    "hitsContainers": [
        {
            "@odata.type": "#microsoft.graph.searchHitsContainer",
            "hits": [
                "..."
            ],
            "total": 9,
            "moreResultsAvailable": false,
            "aggregations": [
                {
                    "@odata.type": "#microsoft.substrateSearch.searchAggregation",
                    "field": "FileType",
                    "buckets": [
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "docx",
                            "count": 5,
                            "aggregationFilterToken": "\"ǂǂ646f6378\""
                        },
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "xlsx",
                            "count": 3,
                            "aggregationFilterToken": "\"ǂǂ786c7378\""
                        },
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "pptx",
                            "count": 1,
                            "aggregationFilterToken": "\"ǂǂ70707478\""
                        }
                    ]
                },
                {
                    "@odata.type": "#microsoft.substrateSearch.searchAggregation",
                    "field": "contentclass",
                    "buckets": [
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "STS_ListItem_DocumentLibrary",
                            "count": 9,
                            "aggregationFilterToken": "\"ǂǂ5354535f4c6973744974656d5f446f63756d656e744c696272617279\""
                        }
                    ]
                }
            ]
        }
    ]
}

示例 2:基于上一个请求应用聚合筛选器Example 2: Apply an aggregation filter based on a previous request

本示例中,我们应用聚合筛选器,该筛选器基于作为示例 1 中的字段返回的 aggregationFilterToken。 docx FileTypeIn this example, we apply an aggregation filter that is based on the aggregationFilterToken returned for docx as the FileType field in example 1.

分配给 aggregationFilters 属性的字符串值采用格式 "{field}:" \ "{aggregationFilterToken} \ ""The string value assigned to the aggregationFilters property follows the format "{field}:\"{aggregationFilterToken}\"". 如果同一筛选器需要多个值,则分配给 aggregationFilters 属性的字符串值应遵循以下格式 :"{field}:或 (\ "{aggregationFilterToken1} \ ", \ "{aggregationFilterToken2} \ ") "。If multiple values for the same filter are required, the string value assigned to the aggregationFilters property should follow this format : "{field}:or(\"{aggregationFilterToken1}\",\"{aggregationFilterToken2}\")".

请求Request

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
          "driveItem"
      ],
      "query": {
          "queryString": "test"
      },
      "from": 0,
      "size": 20,
      "aggregations": [
          {
              "field": "FileType",
              "size": 10,
              "bucketDefinition": {
                  "sortBy": "count",
                  "isDescending": "true",
                  "minimumCount": 0
              }
          }
      ],
      "aggregationFilters": [
        "FileType:\"ǂǂ68746d6c\""
      ]
    }
  ]
}

响应Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.searchResponse",
    "hitsContainers": [
        {
            "@odata.type": "#microsoft.graph.searchHitsContainer",
            "hits": [
                "..."
            ],
            "total": 69960,
            "moreResultsAvailable": true,
            "aggregations": [
            {
                "@odata.type": "#microsoft.substrateSearch.searchAggregation",
                "field": "FileType",
                "buckets": [
                    {
                        "@odata.type": "#microsoft.substrateSearch.searchBucket",
                        "key": "html",
                        "count": 69960,
                        "aggregationFilterToken": "\"ǂǂ68746d6c\""
                    }
                ]
            }
        ]
        }
    ]
}

示例 3:通过数值字段请求聚合Example 3: Request aggregation by a numeric field

以下示例搜索 driveItem 资源,并按其大小(即数值)聚合结果。The following example searches driveItem resources and aggregates results by their size which is a numeric value. 该请求指定 3 个大小范围的聚合:The request specifies aggregation by 3 size ranges:

  • 小于 100 的大小Size less than 100
  • 大小介于 100 和 1000 之间Size between 100 and 1000
  • 大小 1000 及更高版本Size 1000 and higher

该响应包括 3 个 searchBucket 对象,每个大小范围聚合一个:The response includes 3 searchBucket objects, one for each size range aggregation:

  • 小尺寸范围的 2 个存储桶不包含任何搜索匹配项。The 2 buckets of the lower size ranges don't include any search matches.
  • 所有 9 个搜索匹配项的大小都为 1000 或更大。All 9 search matches have sizes 1000 or higher.

请求Request

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
    "requests": [
        {
            "entityTypes": [
                "driveItem"
            ],
            "query": {
                "queryString": "test"
            },
            "from": 0,
            "size": 10,
            "aggregations": [
                {
                    "field": "Size",
                    "size": 5,
                    "bucketDefinition": {
                        "sortBy": "keyAsNumber",
                        "isDescending": "true",
                        "minimumCount": 0,
                        "ranges": [
                            {
                                "to": "100"
                            },
                            {
                                "from": "100",
                                "to": "1000"
                            },
                            {
                                "from": "1000"
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

响应Response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.searchResponse",
    "hitsContainers": [
        {
            "@odata.type": "#microsoft.graph.searchHitsContainer",
            "hits": [
                "..."
                    ],
            "total": 9,
            "moreResultsAvailable": false,
            "aggregations": [
                {
                    "@odata.type": "#microsoft.substrateSearch.searchAggregation",
                    "field": "Size",
                    "buckets": [
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "Less than 100",
                            "count": 0,
                            "aggregationFilterToken": "range(min, 100)"
                        },
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "100 up to 1000",
                            "count": 0,
                            "aggregationFilterToken": "range(100, 1000)"
                        },
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "1000 and up",
                            "count": 9,
                            "aggregationFilterToken": "range(1000, max, to=\"le\")"
                        }
                    ]
                }
            ]
        }
    ]
}

已知限制Known limitations

聚合仅受 SharePoint 或 OneDrive 项支持。Aggregations are supported only for SharePoint or OneDrive items. 消息或事件 不支持****它们They are not supported for message or event.

后续步骤Next steps