Add copilot retrieval filterExpression sample

docs/embedded/build/agent-experiences.md

@@ -98,6 +98,54 @@ The shape of `webUrl` depends on the container type's `urlTemplate` setting, so
 
 To return extra fields such as `title` or `author` with each hit, add a `resourceMetadata` collection to the request. Request only the fields your app uses, because each field adds to the response payload.
 
+### Filter retrieval by custom metadata
+
+Use `filterExpression` to limit retrieval to files with specific custom metadata. First, create an indexed custom column, set the file values, and wait for search indexing to finish. For instructions, see [Store and query container metadata](container-metadata.md).
+
+SharePoint Embedded stores a file's custom column values on its associated `listItem/fields` resource. Retrieval filters on the column's indexed SharePoint managed property, not the stored field name.
+
+For example, a single-line text column named `ClientMatterCode` typically has this managed property:
+
+```text
+ClientMatterCodeOWSTEXT
+```
+
+Automatically created managed properties are text properties, even when their source columns use another data type. The suffix and indexed value format depend on the column type. Confirm the generated property name and value format in the target tenant. For naming details, see [Automatically created managed properties in SharePoint Server](/sharepoint/technical-reference/automatically-created-managed-properties-in-sharepoint).
+
+This request limits candidates to files with an exact indexed metadata value. It also returns the value with each matching hit:
+
+```http
+POST https://graph.microsoft.com/v1.0/copilot/retrieval
+Content-Type: application/json
+
+{
+  "queryString": "What obligations are described in the client agreement?",
+  "dataSource": "sharePointEmbedded",
+  "dataSourceConfiguration": {
+    "sharePointEmbedded": {
+      "containerTypeId": "{containerTypeId}"
+    }
+  },
+  "filterExpression": "ClientMatterCodeOWSTEXT=\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"",
+  "resourceMetadata": [
+    "title",
+    "containerTypeId",
+    "ClientMatterCodeOWSTEXT"
+  ],
+  "maximumNumberOfResults": 10
+}
+```
+
+Use `=` when the complete indexed value must match:
+
+```text
+ClientMatterCodeOWSTEXT="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+```
+
+Don't use the `:` operator for an exact boundary. The colon operator performs term matching and can match related values or prefixes. For more information, see [Keyword Query Language syntax reference](/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference).
+
+The filter limits the candidate files before `queryString` ranks semantically relevant extracts. A file with matching metadata might not appear when its content doesn't relate to `queryString`.
+
 Pass the extracts to your own model or answer-generation step as grounding data. This snippet sends the query and reads the top extract from each hit:
 
 ```javascript

docs/embedded/build/container-metadata.md

@@ -124,7 +124,9 @@ GET https://graph.microsoft.com/beta/drives/{drive-id}/items?$orderby=listitem/f
 
 Use `$expand=listitem($expand=fields)` when the result needs field values in the response. Create indexed columns for high-cardinality filters that your app runs frequently.
 
-For full-text search across containers and custom metadata (using the `OWSTEXT` property suffix), see [Search containers and files](search-containers-files.md). Use OData `$filter` for structured queries inside a single container drive; use search for free-text queries across many containers.
+For full-text search across containers and custom metadata, see [Search containers and files](search-containers-files.md). To filter semantic retrieval by indexed custom metadata, see [Filter retrieval by custom metadata](agent-experiences.md#filter-retrieval-by-custom-metadata). Both experiences use SharePoint managed properties, such as the `OWSTEXT` property generated for a text column.
+
+Use OData `$filter` for structured queries inside one container drive. Use search for free-text queries across many containers, or use the Retrieval API to return extracts for AI grounding.
 
 ## Keep schema consistent