🔍 Code Extractor

class RefinementResults

Maturity: 49

A data class representing refinement results from a SharePoint search query, containing layout templates, refiners, and result metadata.

File:
/tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/search/refinement_results.py
Lines:
6 - 41
Complexity:
moderate

Purpose

RefinementResults encapsulates the refinement data returned from SharePoint search operations. It stores information about how search results should be displayed (via templates), the available refiners for filtering results, and metadata like result titles and URLs. This class is used to structure and transport search refinement data between SharePoint REST API and client applications, inheriting from ClientValue to enable serialization/deserialization for API communication.

Source Code

class RefinementResults(ClientValue):
    """
    The RefinementResults table contains refinement results that apply to the search query.
    """

    def __init__(
        self,
        group_template_id=None,
        item_template_id=None,
        refiners=None,
        properties=None,
        result_title=None,
        result_title_url=None,
    ):
        """
        :param str group_template_id:  Specifies the identifier of the layout template that specifies how the results
            returned will be arranged.
        :param str item_template_id: Specifies the identifier of the layout template that specifies how the result
            item will be displayed
        :param list[Refiner] refiners: Contains the list of refiners
        :param dict properties: Specifies a property bag of key value pairs.
        :param str result_title: Specifies the title associated with results for the transformed query by query
             rule action. MUST NOT be more than 64 characters in length.
        :param str result_title_url: pecifies the URL to be linked to the ResultTitle. MUST NOT be more than
             2048 characters in length.
        """
        self.GroupTemplateId = group_template_id
        self.ItemTemplateId = item_template_id
        self.Refiners = ClientValueCollection(Refiner, refiners)
        self.Properties = properties
        self.ResultTitle = result_title
        self.ResultTitleUrl = result_title_url

    @property
    def entity_type_name(self):
        return "Microsoft.Office.Server.Search.REST.RefinementResults"

Parameters

Name Type Default Kind
bases ClientValue -

Parameter Details

group_template_id: Optional string identifier specifying the layout template that determines how the collection of search results will be arranged and displayed. Used for customizing the visual presentation of result groups.

item_template_id: Optional string identifier specifying the layout template that determines how individual result items will be rendered. Controls the display format for each search result.

refiners: Optional list of Refiner objects that provide filtering capabilities for the search results. Each refiner represents a facet or dimension by which results can be filtered (e.g., file type, author, date range).

properties: Optional dictionary containing key-value pairs for additional metadata or custom properties associated with the refinement results. Provides extensibility for storing arbitrary data.

result_title: Optional string specifying the title to display for results transformed by query rule actions. Must not exceed 64 characters in length. Used when query rules modify the search results.

result_title_url: Optional string specifying the URL to be linked to the ResultTitle. Must not exceed 2048 characters in length. Provides a clickable link associated with the result title.

Return Value

Instantiation returns a RefinementResults object with all specified attributes initialized. The object represents a complete set of refinement data for a search query, ready for serialization to/from SharePoint REST API format.

Class Interface

Methods

__init__(self, group_template_id=None, item_template_id=None, refiners=None, properties=None, result_title=None, result_title_url=None)

Purpose: Initializes a new RefinementResults instance with search refinement data including templates, refiners, and result metadata

Parameters:

  • group_template_id: Optional string identifier for the layout template controlling result group arrangement
  • item_template_id: Optional string identifier for the layout template controlling individual result item display
  • refiners: Optional list of Refiner objects providing filtering capabilities
  • properties: Optional dictionary of key-value pairs for additional metadata
  • result_title: Optional string title for results (max 64 characters)
  • result_title_url: Optional string URL linked to the result title (max 2048 characters)

Returns: None (constructor)

@property entity_type_name(self) -> str property

Purpose: Returns the SharePoint entity type name for this class, used for proper serialization and type identification in REST API communication

Returns: String 'Microsoft.Office.Server.Search.REST.RefinementResults' representing the SharePoint entity type

Attributes

Name Type Description Scope
GroupTemplateId str or None Identifier of the layout template specifying how result groups are arranged instance
ItemTemplateId str or None Identifier of the layout template specifying how individual result items are displayed instance
Refiners ClientValueCollection[Refiner] Collection of Refiner objects providing filtering and faceting capabilities for search results instance
Properties dict or None Property bag containing key-value pairs for additional metadata instance
ResultTitle str or None Title associated with results transformed by query rule actions (max 64 characters) instance
ResultTitleUrl str or None URL to be linked to the ResultTitle (max 2048 characters) instance

Dependencies

  • office365

Required Imports

from office365.runtime.client_value import ClientValue
from office365.runtime.client_value_collection import ClientValueCollection
from office365.sharepoint.search.refiner.refiner import Refiner

Usage Example

from office365.sharepoint.search.refinement_results import RefinementResults
from office365.sharepoint.search.refiner.refiner import Refiner

# Create refiners for filtering
refiners = [
    Refiner(name='FileType', entries=[]),
    Refiner(name='Author', entries=[])
]

# Instantiate RefinementResults
refinement_results = RefinementResults(
    group_template_id='~sitecollection/_catalogs/masterpage/Display Templates/Search/Group_Default.js',
    item_template_id='~sitecollection/_catalogs/masterpage/Display Templates/Search/Item_Default.js',
    refiners=refiners,
    properties={'CustomProperty': 'CustomValue'},
    result_title='Search Results',
    result_title_url='https://example.sharepoint.com/search'
)

# Access attributes
print(refinement_results.GroupTemplateId)
print(refinement_results.ResultTitle)
print(refinement_results.entity_type_name)

# Iterate through refiners
for refiner in refinement_results.Refiners:
    print(refiner.name)

Best Practices

  • Ensure result_title does not exceed 64 characters to comply with SharePoint limitations
  • Ensure result_title_url does not exceed 2048 characters to comply with SharePoint limitations
  • Use valid template identifiers that exist in the SharePoint site's master page catalog
  • Initialize refiners as a list of Refiner objects rather than raw dictionaries to ensure proper type handling
  • The properties dictionary should contain serializable values compatible with SharePoint REST API
  • This class is typically instantiated by the Office365 library when deserializing search responses, not manually created by users
  • Access the entity_type_name property when serializing to ensure correct type identification in SharePoint REST API calls
  • The Refiners attribute is a ClientValueCollection, which provides collection-specific functionality for managing Refiner objects

Tags

sharepoint search refinement filtering facets rest-api data-model client-value search-results templates

Similar Components

AI-powered semantic similarity - components with related functionality:

  • class Refiner 77.9% similar

    A Refiner class that represents a SharePoint search refiner containing a list of RefinerEntry objects, inheriting from ClientValue for Office 365 REST API integration.

    From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/search/refiner/refiner.py

  • class RefinerEntry 74.2% similar

    RefinerEntry is a data class representing a single refinement entry in Microsoft Office Server Search REST API, containing a refinement name and its associated count.

    From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/search/refiner/entry.py

  • class CustomResult 71.5% similar

    A data class representing custom search query results with layout templates and properties for Microsoft Office Server Search REST API.

    From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/search/custom_result.py

  • class PersonalResultSuggestion 66.9% similar

    A data class representing a personal search result suggestion from SharePoint Search, containing metadata about suggested results including title, URL, and best bet status.

    From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/search/query/personal_result_suggestion.py

  • class PromotedResultsOperationsResult 66.6% similar

    A data class representing the result of a REST API call to retrieve promoted search results from SharePoint/Office 365.

    From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/search/promoted_results_operations_result.py
← Back to Browse