Set-PnPSearchResultType
SYNOPSIS
Required Permissions
- Graph Connector Service (GCS) API
- Site scope: Site Administrator
- Organization scope: Search Administrator or Global Administrator
Updates a Microsoft Search result type on the currently connected site or at the organization level.
SYNTAX
Properties (Default)
Set-PnPSearchResultType -Identity <String> [-Scope <SearchVerticalScope>] [-Name <String>] [-Priority <Int32>] [-Validate] [-Verbose] [-Connection <PnPConnection>]
Payload
Set-PnPSearchResultType -Identity <String> [-Scope <SearchVerticalScope>] -Payload <SearchResultTypePayload> [-Validate] [-Verbose] [-Connection <PnPConnection>]
DESCRIPTION
This cmdlet updates a Microsoft Search result type on the site you are currently connected to, or at the organization (tenant) level when using -Scope Organization. When using individual parameters (Properties parameter set), the cmdlet retrieves the current configuration, merges in your changes, and performs a full update. For complete control over rules, content source, and display template, use the -Payload parameter. It uses the Graph Connector Service (GCS) API at gcs.office.com.
Warning
This cmdlet uses the Graph Connector Service (GCS) API, which is an internal Microsoft API that is not publicly documented or officially supported. It may change without notice.
Prerequisites
Your Entra app registration must have the ExternalConnection.ReadWrite.All delegated permission from the Graph Connector Service (GCS) API. To add this permission using Azure CLI:
az ad app permission add --id <your-app-id> --api 56c1da01-2129-48f7-9355-af6d59d42766 --api-permissions d44774bd-e26c-43b1-996d-51bb90a9078e=Scope
az ad app permission admin-consent --id <your-app-id>
Note
This cmdlet requires a delegated (interactive) connection. App-only (certificate-based) connections are not supported by the GCS API and will result in a 403 Forbidden error.
EXAMPLES
EXAMPLE 1
Set-PnPSearchResultType -Identity "1770839639348_FYXB8XQI5" -Name "Updated Name"
Updates the name of the specified result type.
EXAMPLE 2
# Get the result type and modify its payload
$rt = Get-PnPSearchResultType -Identity "1770839639348_FYXB8XQI5"
$payload = $rt.Payload
# Change the content source to an external connector
$connection = Get-PnPSearchSiteConnection -Identity "techcrunch"
$payload.ContentSourceId = [PnP.PowerShell.Commands.Model.Graph.MicrosoftSearch.SearchResultTypeContentSource]@{
ContentSourceApplication = "Connectors"
Identity = $connection.Id
SystemId = $connection.SystemId
}
$payload.ContentSourceName = $connection.Name
# Update the rules using New-PnPSearchResultTypeRule
$payload.Rules = @(
New-PnPSearchResultTypeRule -PropertyName "IconUrl" -Operator StartsWith -Values "https://"
)
$payload.RuleProperties = @("IconUrl")
Set-PnPSearchResultType -Identity "1770839639348_FYXB8XQI5" -Payload $payload
Changes a result type's content source from SharePoint to an external connector with new rules.
EXAMPLE 3
$rt = Get-PnPSearchResultType -Identity "1770839639348_FYXB8XQI5"
$rt.Payload.Rules = @(
New-PnPSearchResultTypeRule -PropertyName "FileType" -Operator Equals -Values "docx","xlsx","pptx"
New-PnPSearchResultTypeRule -PropertyName "IsListItem" -Operator Equals -Values "false"
)
$rt.Payload.RuleProperties = @("FileType", "IsListItem")
Set-PnPSearchResultType -Identity "1770839639348_FYXB8XQI5" -Payload $rt.Payload
Updates the rules on an existing result type to match Office documents that are not list items.
EXAMPLE 4
$template = @'
{
"type": "AdaptiveCard",
"version": "1.3",
"body": [
{
"type": "TextBlock",
"text": "[${title}](${titleUrl})",
"weight": "Bolder",
"size": "Medium",
"color": "Accent"
},
{
"type": "TextBlock",
"text": "${description}",
"wrap": true,
"maxLines": 3
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
}
'@
$rt = Get-PnPSearchResultType -Identity "1770839639348_FYXB8XQI5"
$rt.Payload.DisplayTemplate = $template
Set-PnPSearchResultType -Identity "1770839639348_FYXB8XQI5" -Payload $rt.Payload
Updates the display template of an existing result type with a custom Adaptive Card layout. Use a here-string (@'...'@) for readability.
EXAMPLE 5
Set-PnPSearchResultType -Identity "1770839639348_FYXB8XQI5" -Priority 1
Sets the result type to be first in display order.
EXAMPLE 6
Set-PnPSearchResultType -Identity "1770839639348_FYXB8XQI5" -Name "Updated Name" -Scope Organization
Updates the name of an organization-level result type.
EXAMPLE 7
$rt = Get-PnPSearchResultType -Identity "1770839639348_FYXB8XQI5"
$rt.Payload.Rules = @(
New-PnPSearchResultTypeRule -PropertyName "IconUrl" -Operator StartsWith -Values "https://"
)
$rt.Payload.RuleProperties = @("IconUrl")
Set-PnPSearchResultType -Identity "1770839639348_FYXB8XQI5" -Payload $rt.Payload -Validate
Updates the rules on a connector-based result type with property validation. The -Validate switch checks that IconUrl exists in the connector's schema. If a rule property does not exist, the cmdlet throws an error. Invalid display properties produce a warning.
EXAMPLE 8
Get-PnPSearchResultType -Identity "My Result Type" | Set-PnPSearchResultType -Name "Updated Name"
Pipes a result type object directly into Set-PnPSearchResultType. The LogicalId property binds automatically to -Identity.
PARAMETERS
-Connection
Optional connection to be used by the cmdlet. Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection.
Type: PnPConnection
Parameter Sets: (All)
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Identity
The logical ID or name of the search result type to update.
Type: String
Parameter Sets: (All)
Required: True
Position: 0
Default value: None
Accept pipeline input: True (ByValue, ByPropertyName)
Accept wildcard characters: False
Aliases: LogicalId
-Scope
Specifies whether to update a site-level or organization-level result type. Defaults to Site.
Type: SearchVerticalScope
Parameter Sets: (All)
Accepted values: Site, Organization
Required: False
Position: Named
Default value: Site
Accept pipeline input: False
Accept wildcard characters: False
-Name
The new name for the result type.
Type: String
Parameter Sets: Properties
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Priority
The priority (display order) for the result type. Priorities must be unique — when you set a result type to a priority that is already in use, the existing result type at that position shifts accordingly.
Type: Int32
Parameter Sets: Properties
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Payload
A full SearchResultTypePayload object to replace the entire result type configuration. The payload is sent directly via PUT without merging with the existing configuration.
Type: SearchResultTypePayload
Parameter Sets: Payload
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Validate
Validates rule and display property names before updating the result type. For external connector content sources, the connector's schema is fetched from the API: invalid rule properties cause an error (they would never match), invalid display properties produce a warning. For SharePoint content sources, property names are checked against the list of known default managed properties: unrecognized properties produce a warning (not an error) because customers may have custom managed properties, aliases, or autogenerated properties not in the default set. Standard search display properties (title, titleUrl, modifiedBy, modifiedTime, description) are always considered valid. Additionally, the display template is validated to be valid JSON with Adaptive Card version 1.3, which is the version supported by Microsoft Search.
Type: SwitchParameter
Parameter Sets: (All)
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Verbose
When provided, additional debug statements will be shown while executing the cmdlet.
Type: SwitchParameter
Parameter Sets: (All)
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False