Pinned results in the C# SDK

Pinned results let you promote specific content items to the top of search results when a query matches a configured phrase. Use this feature to highlight important pages for common or high-value searches.

Configure pinned items in Optimizely Graph using the Graph management API. The C# SDK does not create pinned items. Instead, use .WithPinned() in a query to include them in the results.

Add pinned results to a query

Call .WithPinned() in a query that uses .SearchFor(). The phrase passed to .SearchFor() retrieves matching pinned items.

var result = await client
    .QueryContent<BlogPostPage>()
    .SearchFor("GRAPH API")
    .UsingFullText()
    .WithPinned()
    .GetAsContentAsync();

Pinned items appear at the top of the results list. Other results follow based on their relevance score.

Override the pinned phrase

Use the phrase: parameter when the display query differs from the phrase used to configure pinned items.

var result = await client
    .QueryContent<BlogPostPage>()
    .SearchFor("graph api tutorial")
    .UsingFullText()
    .WithPinned(phrase: "graph api")
    .GetAsContentAsync();

In this example, the user typed graph api tutorial, but the query matches pinned items configured for graph api.

Limit pinned results to a collection

Restrict pinned items to a specific collection. Only pinned items that belong to the specified collection appear at the top of the results.

var collectionId = Guid.Parse("YOUR_COLLECTION_ID");

var result = await client
    .QueryContent<BlogPostPage>()
    .SearchFor("graph api")
    .UsingFullText()
    .WithPinned(collectionId: collectionId)
    .GetAsContentAsync();

Combine pinned results with other query methods

Pinned results work with other query operations such as filters, pagination, and total counts.

var result = await client
    .QueryContent<BlogPostPage>()
    .SearchFor("graph api")
    .UsingFullText()
    .Where(x => x.BlogCategory == "Tutorials")
    .WithPinned()
    .Skip(0)
    .Limit(10)
    .IncludeTotal()
    .GetAsContentAsync();

Pinned items always appear first in the result set. Non-pinned items follow according to their calculated relevance.

.WithPinned() requires a search query. If the query does not include .SearchFor(), pinned results are not applied.