Move away from LINQ

This is for:

In this article

Why Coveo for Sitecore no longer supports LINQ queries
Coveo Hive explained
Using Coveo Hive for listing pages
Calling the Coveo Search API using server-side code

Support for LINQ queries was dropped in Coveo for Sitecore 5 (see Release Notes for November 2018: 5.0.74.10). This article explains the reasons for this decision and provides guidance on how to move from LINQ to Coveo queries.

Why Coveo for Sitecore no longer supports LINQ queries

Coveo’s decision to discontinue support for LINQ is simply one of business focus. One needs only to compare the characteristics of LINQ and real Coveo queries to realize the extent to which LINQ was out-of-line with what Coveo stands for.

	LINQ queries	Coveo Hive queries
Data Retrieval Method	The Coveo index is queried through the Coveo Search API using the Sitecore Content Search API.	The Coveo Hive framework queries the Coveo Search API which retrieves the data from the index.
Query Creation	Hard-coded server-side.	Queries are generated by the Coveo Hive Search Interface, but can be customized using several business tools or client-side using the Coveo JavaScript Framework.
Identity Management	Hard-coded with a custom user authentication logic.	The Coveo Hive Search Interface automatically identifies the user and sends the proper role to the Coveo index for security trimming.
Analytics Tracking	The connection with the Coveo Analytics API needs to be built manually.	Every Coveo Hive component sends usage analytics data to Coveo.
Machine Learning	Only active if the entire analytics tracking loop is completed.	Activated by default based on data sent by the components.
Focus of the solution	Data retrieval.	Relevance at every interaction.

LINQ queries

Coveo Hive queries

Data Retrieval Method

The Coveo index is queried through the Coveo Search API using the Sitecore Content Search API.

The Coveo Hive framework queries the Coveo Search API which retrieves the data from the index.

Query Creation

Hard-coded server-side.

Queries are generated by the Coveo Hive Search Interface, but can be customized using several business tools or client-side using the Coveo JavaScript Framework.

Identity Management

Hard-coded with a custom user authentication logic.

The Coveo Hive Search Interface automatically identifies the user and sends the proper role to the Coveo index for security trimming.

Analytics Tracking

The connection with the Coveo Analytics API needs to be built manually.

Every Coveo Hive component sends usage analytics data to Coveo.

Machine Learning

Only active if the entire analytics tracking loop is completed.

Activated by default based on data sent by the components.

Focus of the solution

Data retrieval.

Relevance at every interaction.

In a nutshell, using LINQ queries is a completely valid way to retrieve index content. However, Coveo aims to provide users with tailored results, based on analytics and artificial intelligence models. Coveo is a relevance engine.

Other Sitecore search providers can be used to surface index data just fine, in parallel with Coveo. Using LINQ queries on a Coveo index amounts to missing out entirely on the whole value of Coveo.

Coveo Hive explained

At the core of Coveo is the JavaScript Search UI Framework, a set of components typically associated with search interfaces (for example, search box components, facet components, result list components). The component underlying logic ensures all components inserted in a web page work together. Only a few components are required to form a fully functional (and relevance-ready) search interface, right out-of-the-box.

Coveo packages the Coveo JavaScript Search UI Framework as Sitecore items and associated files under the Coveo Hive framework designation. Therefore, you can seamlessly leverage the Coveo JavaScript Search UI Framework in Sitecore by inserting Coveo Hive renderings in your web pages, the same way you would with other renderings in Sitecore (see Coveo Hive framework).

Using Coveo Hive for listing pages

You get the most out of Coveo when you draw from usage analytics, and much of that data comes from user actions. Hence, using a complete search interface, including a search box and facets will generate more analytics and better relevance than simply having Coveo for Sitecore display a result list on web page loads. But even for that specific use case, Coveo Hive is more flexible and powerful than using LINQ.

You can add a simple Coveo for Sitecore results list in your Sitecore web page(s) to surface related items. The required Coveo results list components automatically generate and send a query to the Coveo Platform Search API when the page finishes loading. This query contains user/visitor and context information which is leveraged by Coveo before it sends a response (search results) back to the page. These results are now rendered.

Result list example

The Create a Simple Result List page contains step-by-step instructions on adding a simple Coveo for Sitecore result list and setting up result filtering and boosting using both recommended methods.

Calling the Coveo Search API using server-side code

Although the Coveo Hive framework is highly flexible, you might need to retrieve server-side data for precise use cases.

Using server-side code to fetch Coveo index data isn’t impossible. Coveo provides information on how to do this outside of Sitecore (see Search API). However, Coveo for Sitecore assemblies contain a client that simplifies the process of connecting to the Search API. This client lets you generate and send a query to the Search API and then bind the query results to a model.

Server-side queries have a significant impact on queries per month (QPM) and can represent extra costs for the customer. Set meaningful search hub values in your server-side query code to ease their identification in the Consumption dashboard. If need be, you’ll be able to locate server-side queries in your solution using the search hub value and make any adjustments you consider necessary.
Be aware that, just like LINQ, using the Coveo Search API directly won’t log any analytics event used to feed the Coveo Machine Learning models.

Example

You work for the Regional Corn Growers Association and you’ve been tasked to add a side widget on the association web site pages displaying the upcoming corn roast events. You have set up event items in Sitecore with a field called EventType.

The following code sample generates a Search API query that contains an advanced query (aq) (see Query parameters and Query syntax). This advanced query specifies that only items whose EventType value is set to Corn Roast must be returned.

Notes

The code samples contain fictitious values for field and security provider names. The associated comments provide instructions on how to set the appropriate variable values for your implementation.
The SearchHub property of the QueryParams class used in the code sample below was added in the June 2020 release of Coveo for Sitecore 5. Setting the value of this property with an instruction such as qParams.SearchHub = "ServerSideQueries"; will yield a 'QueryParams' does not contain a definition for 'SearchHub' error in pre-June 2020 releases.

using Coveo.Framework.SearchService;
using Coveo.SearchServiceProvider.Rest;
using Coveo.Framework.Configuration;
using Coveo.Framework.Connection;
using Coveo.SearchProvider.ContentSearch;
using Sitecore.ContentSearch;
using System.Collections.Generic;

namespace ...

private QueryResults ExecuteQuery()
{

   IClientSessionWrapperFactory factory = new ClientSessionWrapperFactory();
   ICoveoIndexFetcher coveoFetcher = new CoveoIndexFetcher();
   ISearchIndex coveoIndex = coveoFetcher.GetCoveoSearchIndex("Coveo_web_index");
   CoveoIndexConfiguration configuration = coveoIndex.Configuration as CoveoIndexConfiguration;

   /*
    * See the
    * https://platform.cloud.coveo.com/admin/#/orgid/content/security-identities page of the Coveo Administration Console for the securityProviderName value
    * to use for your instance of Coveo for Sitecore.
    */

    String securityProviderName = "Expanded Sitecore Security Provider for WKS-000236";

   // This example assumes that non-authenticated users have read access to the fetched items.
   String currentUserName = @"extranet\Anonymous";

   QueryParams qParams = new QueryParams();
   qParams.SortByCriteria = new []
   {
      /*
       * Use the Translated Name value of the Sitecore fields as the first parameter of the FieldSortBy constructor.
       * The Translated Name value may be found in the Indexing Manager at
       * http://<INSTANCE_HOSTNAME>/coveo/command-center/index.html#fields/.
       * Ensure that the field to sort by is marked as "Sortable".
       */
       new FieldSortBy("feventdate2181", true)
   };

   /*
    * Use an advanced query (`aq`) to filter your items according to the Sitecore field of your choice. Once again,
    * use the Translated Name of the Sitecore field in your query.
    */
   qParams.AdvancedExpression = "@feventtype2181=\"Corn Roast\"";

   /*
    * NOTE: Always set a SearchHub value on your search queries (see
    * https://docs.coveo.com/en/3302/).
    *
    * The SearchHub property was added to the QueryParams class in the June 2020 release of
    * Coveo for Sitecore 5.
    */

   qParams.SearchHub = "ServerSideQueries";

   /* In the June 2020 release, the QueryParams class was updated to inherit from the AbstractCloudObject class
    * which is a Dictionary<string, object>. This allows you to set any QueryParams object property using the
    * following syntax:  qParams["foo"] = "bar";
    */

   IClientSessionWrapper client = factory.GetClientSessionWrapper(configuration, securityProviderName, currentUserName);
   return client.ExecuteQuery(qParams);
}

You can subsequently retrieve the field values you need to display from the returned QueryResults type object using a syntax like the following:

var allEventNamesForResults = ExecuteQuery().Results.Select(result => result.Fields["feventname2181"];

See the Indexing Manager for the translated names of your Sitecore fields. The Indexing Manager is located at http://<INSTANCE_HOSTNAME>/coveo/command-center/index.html#fields/.