Querying client

The SDK provides a Querying client for executing queries.

Warning

When multiple items match a query, an InvalidOperationException is thrown. And, when the iterator goes beyond the configured maximum number of results, the server throws an exception. In this case, a scroll is necessary.

Create a query

For more information about creating queries, please refer to the creating a query with LINQ section.

Handle query results

After executing a query, an IQueryResult is returned. This result has the following properties:

  • Items: The entities/ids that matched the query (can be a subset of the total results)

  • TotalNumberOfResults: The number of items that matched the query in Sitecore Content Hub (even if not all of them are in Items)

  • Offset: The number of items that were skipped.

Query for a single entity

When it is certain that a query only matches a single entity, it is convenient to use the SingleAsync method.

RequestResponse

IEntity entity = await MClient.Querying.SingleAsync(query);

Query for a single entity ID

When it is certain that a query only matches a single entity, it is convenient to use the SingleIdAsync method.

RequestResponse

long? entityId = await MClient.Querying.SingleIdAsync(query);

Query for one or multiple entities

To query for one or more entities:

RequestResponse

IEntityQueryResult queryResult = await MClient.Querying.QueryAsync(query);

The IEntityQueryResult.Items contains the returned entities.

Query for one or multiple entity IDs

To query for one or more entity ids:

RequestResponse

IIdQueryResult queryResult = await MClient.Querying.QueryIdsAsync(query);

The IIdQueryResult.Items contains the returned IDs (in long format).

Iterate query result entities

When the query returns a small to medium number of results (the default configuration is 10,000 results maximum), it is easy to batch process the entities using an iterator.

In the following snippet, an iterator is created:

RequestResponse

IEntityIterator iterator = MClient.Querying.CreateEntityIterator(query);

In the following snippet, the iterator is used to batch process entities:

RequestResponse

while (await iterator.MoveNextAsync())
{
  var entities = iterator.Current.Items;
  // Do something with the entities
}

The while loop automatically ends when the iterator has finished processing all the batches of entities.

Iterate query result entity IDs

When the query returns a small to medium size of results (the default configuration is 10.000 results maximum), it is easy to batch process the entity ids using an iterator.

In the following snippet, an iterator is created:

RequestResponse

IIdIterator iterator = MClient.Querying.CreateIdIterator(query);

In the following snippet, the iterator is used to batch process entity IDs:

RequestResponse

while (await iterator.MoveNextAsync())
{
  var ids = iterator.Current.Items;
  // Do something with the ids
}

The while loop automatically ends when the iterator has finished processing all the batches of entities.

Deprecation notes

On the Query class it is possible to set the EntityLoadOptions property and the LoadConfiguration property. The first property was used by the old WebApiClient SDK and was deprecated in 3.0. In 3.1 the Query class and the load configurations were separated. It is recommended to no longer use these properties, but pass the load configuration as an extra parameter when passing the query object, when applicable.

Do you have some feedback for us?

If you have suggestions for improving this article,