LINQ to Sitecore

Abstract

LINQ to Sitecore provides access to search the indexes, using standard LINQ queries.

LINQ to Sitecore provides access to search the indexes, using standard LINQ queries in the same way that other LINQ providers, such as LINQ to SQL and LINQ to Objects, work. It uses the standard IQueryable<T> interface and supports most of the available operations. For a general introduction to LINQ, see http://msdn.microsoft.com/en-us/library/vstudio/bb397926.aspx.

Sitecore supports two search providers: Lucene and Solr. The LINQ layer is an abstract layer that converts common queries to something that these search providers understand.

For example, the LINQ layer resolves a query like this:

var query = context.GetQueryable<Product>.Where(item => item.Name == “Sample Item”)

to something that Solr or Lucene understands. If you implement a new search provider, this provider can also understand the query.

The LINQ layer is used internally by Sitecore but developers can also use it. You can use this layer in sublayouts.

To start a search, you set up a search context:

using (var context = ContentSearchManager.GetIndex(item).CreateSearchContext())
{
    IQueryable<SearchResultItem> searchQuery = context.GetQueryable<SearchResultItem>().Where(item => item.Name == “Sitecore”)
}

The LINQ layer converts the query to something your provider understands. For example, for Lucene it is converted to:

_name:sitecore

This returns the results of a query on your search index and returns it as a SearchResultItem type. You can also use the indexer to run queries:

using (var context = ContentSearchManager.GetIndex(item).CreateSearchContext())
{
    IQueryable<SearchResultItem> searchQuery = context.GetQueryable<SearchResultItem>().Where(item => item[“_name”] == “Sitecore”)
}

This topic describes:

Supported IQueryable methods

The LINQ layer does not implement all IQueryable methods. The following methods have been implemented:

Sort by standard string, integer, float, or any type that implements IComparable
All
Any
Between (with an extra overload for including or excluding the start and end ranges)
Boost (makes this part of the query more important than the other parts)
Cast (you can use this instead of Select)
Contains
Count
ElementAt
EndsWith
Equal
Facets (an extension that fetches the facets of predicates)
First
FirstOrDefault
Join
Last
LastOrDefault
Min
Max
Match (an extension for running regular expression queries)
OrderBy
OrderByDescending
Select
Single
SingleOrDefault
Skip
Take
ToList()
ToLookUp()
ToDictionary()
Page (an extension that does Skip and Take automatically for you)
StartsWith

Not supported IQueryable methods

These methods are not supported:

GroupBy
GroupByJoin
Intersect
Sum
Average
Concat
TakeWhile
SkipWhile
Reverse
Union

If these methods are called, a NotSupportedException or InvalidOperationException exception is thrown at runtime.

LINQ to Sitecore syntax

This table shows how the LINQ layer and Lucene correspond:

	Lucene syntax	LINQ to Sitecore
Fields	`text:”go”`	`c.Text == "go"` or `c.Text.Equals(“go”)`
WildCard	`text:amber`	`c.Text.Contains ("amber")`
Prefix	`text: *amber`	`c.ContactName.StartsWith("amber")`
Fuzzy	`text:roam~` `text:roam~0.8`	`c.Text.Like("roam")` `c.Text.Like("roam", 0.8)`
Proximity	`text:"jakarta apache"~10`	`c.Text.Like("jakarta apache", 10)`
Inclusive Range	`__smallupdateddate:[20140101 TO 20150101]`	`.Where(c => c.Updated.Between(new DateTime(2014, 1, 1), new DateTime(2015, 1, 1), Inclusion.Both)`
Exclusive Range	`title:{Aida TO Carmen}`	`c.Title.Between("Aida", "Carmen", Inclusion.None)`
Boosting	`name:jakarta^4 apache`	`.Where(c => c.Name.Equals("jakarta").Boost(4) \|\| c.Name.Equals("apache"))`
Boolean Or	`name:"jakarta apache" OR jakarta`	`where c.Name.Equals("jakarta apache") \|\| c.Equals("jakarta")`
Boolean And	`"jakarta apache" AND "Apache Lucene"`	`where c.Equals("jakarta apache") && c.Equals("Apache Lucene")`
Boolean Not	`"jakarta apache" NOT "Apache Lucene"`	`where c.Equals("jakarta apache") && !c.Equals("Apache Lucene")`
Grouping	(`jakarta OR apache) AND website`	`where (c.Title == "jakarta" \|\| c.Title == "apache") && (c.Title == "website")`

IQueryable extensions

The LINQ layer provides extra methods that extend the standard IQueryable interface. You must declare the Sitecore.ContentSearch.Linq namespace to use them.

Filtering

Filtering is similar to using Where to restrict the result list. When you use Filter, the scoring/ranking of the search hits is not influenced by the filters, and filters can be cached to optimize search performance.

For example:

results = queryable.Filter(d => d.Id > 4 && d.Id < 8);

Note

To avoid influencing the ranking of the search results, use Filter when applying restrictions to search queries in the GetGlobalFilters pipeline.

Facets

Simple faceting

var results = queryable.FacetOn(d => d.Name); 
var facets = results.GetFacets(); 
foreach (var category in facets.Categories) { 
    Console.WriteLine(category.Name); 
    foreach (var facetValue in category.Values) { 
        Console.WriteLine("{0}: {1}", facetValue.Name, facetValue.Aggregate); 
    } 
}

Pivot faceting

var results = queryable.FacetPivotOn(p => p.FacetOn(d => d.Name).FacetOn(d => d.Year)); 
var facets = results.GetFacets(); 
foreach (var category in facets.Categories) { 
    Console.WriteLine(category.Name); 
    foreach (var facetValue in category.Values) { 
        Console.WriteLine("{0}: {1}", facetValue.Name, facetValue.Aggregate); 
    } 
}

Boosting

queryable.Where(it => (it.TemplateName == "Sample Item").Boost(50) || it.TemplateName=="Folder");
queryable.Where(it => (it.Paths.Contains(new ID("{0DE95AE4-41AB-4D01-9EB0-67441B7C2450}")).Boost(3) || it.TemplateName=="Folder") );

Other

Between

results = queryable.Where(item => item.Price.Between(50.0f, 400.0f, Inclusion.Both));
results = queryable.Where(item => item.Price.Between(2.0f, 12.0f, Inclusion.Both) || item.Price.Between(80.0f, 400.0f, Inclusion.Both)); 
results = queryable.Where(d => d.Date.Between(new DateTime(2004, 12, 31), DateTime.Now, Inclusion.Both)); 
results = queryable.Where(d => d.Id.Between(1, 4, Inclusion.Both)); 
results = queryable.Where(d => d.Id.Between(1, 4, Inclusion.Lower)); 
results = queryable.Where(d => d.Id.Between(1, 4, Inclusion.Upper)); 
results = queryable.Where(d => d.Id.Between(1, 4, Inclusion.None));

string.Contains

results = queryable.Where(d => !d.Template.Contains("Hello:));

string.CompareTo

results = queryable.Where(d => !d.Name.CompareTo("Hello") == 1);

Equal

results = queryable.Where(d => d.Id.Equal(4));

Matches

results = queryable.Where(i => i.Template.Matches("^.*$"));

MatchWildcard

results = queryable.Where(i => i.Template.Where(i => i.Template.MatchWildcard("H?li*m")));

Like

results = queryable.Where(i => i.Template.Like("Citecoar"));

string.StartsWith

results = queryable.Where(d => !d.Name.StartsWith("Hello"));

string.EndsWith

results = queryable.Where(d => !d.Name.EndsWith("Hello"));

GetResults

results = queryable.GetResults().Hits.Where(i => i.Document.Name.Contains("o")).Where(hit => hit.Score > 0.6);

GetFacets

results = queryable.Where(d => d.Id > 0).FacetOn(d => d.Template, 0).GetFacets();

Custom search type/object mapping

Because the LINQ layer uses the generic IQueryable<T> interface to expose the search indexes, you can use custom classes or POCO classes to describe the information in the indexes.

To implement custom search types, such a class must:

Have an empty constructor.
Expose public properties with getters and setters and/or a public indexer to hold the search result data.

The LINQ provider automatically maps document fields in the index to properties on the custom search type by the names of the properties. Properties or fields from the index that have not been matched together by name are skipped during the object creation/mapping.

It is also possible to map properties that do not match to fields in the index by decorating the properties with the IndexField attribute. You can use this, for example, to expose special Sitecore fields such as _name as a property called Name. A different use case is field names with spaces, because they cannot be mapped directly to a property by name.

Furthermore, you can implement an indexer that is populated with the field name as key and the value for each field in the index document. There is also an ObjectIndexerKey that you can use to wrap indexers as different types. This is useful if you only have the string version of a property name but need to use it as an indexer for a property type, where you most often need an int.

The process of supplying a custom type and let Sitecore map from index fields to the properties of the item is also known as "hydration".

Depending on the search provider being used, the indexed and stored data in the index might not be the native types for the value. For Lucene, everything is stored and indexed as strings.

Supported types

The following types are supported for automatic type conversion when mapping index document fields to properties:

.NET built-in integral types
.NET built-in floating-point types
Boolean
String
DateTime
GUID
Sitecore ID
Sitecore ShortID
Sitecore ItemUri
IEnumerable<T>
DateTimeOffset
Language
Version
Database
CultureInfo
TimeSpan

Custom search type example

The following is a short example of how you implement a custom search type:

public class MySearchResultItem 
{
    // Fields 
    private readonly Dictionary<string, stringfields = new Dictionary<string, string>(); 
    // Properties 
    // Will match the _name field in the index 
    [IndexField("_name")] 
    public string Name { get; set; } 
    // Will match the myid field in the index 
    public Guid MyId { get; set; } 
    public int MyNumber { get; set; } 
    public float MyFloatingPointNumber { get; set; } 
    public double MyOtherFloatingPointNumber { get; set;} 
    public DateTime MyDate { get; set; } 
    public ShortID MyShortID { get; set; } 
    public ID SitecoreID { get; set; } 
    // Will be set with key and value for each field in the index document 
    public string this[string key]
    { 
        get 
        { 
            return this.fields[key.ToLowerInvariant()]; 
        } 
        set 
        { 
            this.fields[key.ToLowerInvariant()] = value; 
        } 
    } 
}

LINQ to Sitecore

Supported IQueryable methods

Not supported IQueryable methods

LINQ to Sitecore syntax

Lucene syntax

LINQ to Sitecore

IQueryable extensions

Filtering

Note

Facets

Simple faceting

Pivot faceting

Boosting

Other

Between

string.Contains

string.CompareTo

Equal

Matches

MatchWildcard

Like

string.StartsWith

string.EndsWith

GetResults

GetFacets

Custom search type/object mapping

Supported types

Custom search type example