Pinned results in C# SDK

Pinned results let you promote specific content items to the top of search results when a query matches a configured phrase. This feature is useful for highlighting 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 the .WithPinned() method in a query to include them in the results.

Add pinned results to a query

Call .WithPinned() in a query that uses .SearchFor(). The search phrase passed to SearchFor() is used to retrieve 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 phrase: 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 query searches for graph api but the user typed graph api tutorial

Limit pinned results to a collection

You can 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 filtering, 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.

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