CopilotRetrieval
Retrieves relevant text extracts from SharePoint, OneDrive, and Microsoft 365 Copilot connectors content using the Microsoft 365 Copilot Retrieval API. Returns one row per text extract, with parent document metadata repeated on each row.
Stored Procedure Specific Information
Select
In order to execute this stored procedure, you must create a custom OAuth app with the permissions Files.Read.All and Sites.Read.All at minimum, and optionally also ExternalItem.Read.All. These must be delegated permissions on a work or school account. Additionally, your account must have the Microsoft 365 Copilot license.
Sample statements:
EXEC CopilotRetrieval QueryString = 'How do you set up a corporate VPN?', DataSource = 'sharePoint' EXEC CopilotRetrieval QueryString = 'How do you set up a corporate VPN?', DataSource = 'oneDriveBusiness', ResourceMetadata = 'title', MaximumNumberOfResults = '10'
Input
| Name | Type | Required | Description |
| QueryString | String | True | Natural language query string used to retrieve relevant text extracts. Limited to 1,500 characters. Should be a single sentence without spelling errors in context-rich keywords. |
| DataSource | String | True | Indicates whether extracts should be retrieved from SharePoint (sharePoint), OneDrive (oneDriveBusiness), or Copilot connectors (externalItem).
The allowed values are sharePoint, oneDriveBusiness, externalItem. |
| FilterExpression | String | False | Keyword Query Language (KQL) expression with queryable SharePoint, OneDrive, or Copilot connectors properties to scope the retrieval before the query runs. Supported SharePoint and OneDrive properties include: Author, FileExtension, Filename, FileType, InformationProtectionLabelId, LastModifiedTime, ModifiedBy, Path, SiteID, and Title. For Copilot connectors content, any property marked as queryable in the connector schema may be used. By default, no scoping is applied. |
| ResourceMetadata | String | False | Comma-separated list of metadata field names to return for each item in the response. Only retrievable metadata properties can be included. Common values include title and author. By default, no metadata is returned. |
| MaximumNumberOfResults | String | False | The maximum number of documents whose extracts are returned in the response. Must be between 1 and 25. Defaults to 25. Note that each document can have multiple extracts, so the number of rows in the output may be more than this value.
The default value is 25. |
| ConnectionIds | String | False | Comma-separated list of Copilot connector connection IDs to restrict retrieval to specific connections. Only applicable when DataSource is externalItem. |
Result Set Columns
| Name | Type | Description |
| Text | String | The text extract retrieved from the document. |
| RelevanceScore | Double | The cosine similarity between the text extract and the QueryString, normalized to the 0-1 range. May be empty if the API does not return a score for this extract. |
| WebUrl | String | The URL of the document from which the extract was retrieved. |
| ResourceType | String | The resource type of the source document. Possible values include site, list, listItem, externalItem, drive, and driveItem. |
| ResourceMetadata | String | JSON object containing the requested metadata fields for the source document, such as title and author. Empty if no metadata was requested or none was applicable. |
| SensitivityLabel_SensitivityLabelId | String | The unique identifier of the sensitivity label applied to the source document. |
| SensitivityLabel_DisplayName | String | The display name of the sensitivity label applied to the source document. |
| SensitivityLabel_Tooltip | String | The tooltip text describing the sensitivity label applied to the source document. |
| SensitivityLabel_Priority | Int | The priority of the sensitivity label applied to the source document. |
| SensitivityLabel_Color | String | The color associated with the sensitivity label applied to the source document. |