Create a query
You can use the Querying client to create queries and then run any of the following queries or iterate on results.
View query results
After running a query, an IQueryResult is returned. This result has the following properties:
-
Items- the entities/IDs that matched the query, which 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 inItems). -
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, you can use the SingleAsync method.
IEntity entity = await MClient.Querying.SingleAsync(query);
When multiple items match the query, an InvalidOperationException is thrown.
Query for a single entity ID
When it is certain that a query only matches a single entity, you can use the SingleIdAsync method.
long? entityId = await MClient.Querying.SingleIdAsync(query);
When multiple items match the query, an InvalidOperationException is thrown.
Query for one or multiple entities
To query for one or more entities:
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:
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 size of results (the default configuration is 10.000 results maximum), it is easy to batch process the entities using an iterator.
In the following code snippet, an iterator is created:
IEntityIterator iterator = MClient.Querying.CreateEntityIterator(query);
In the following code snippet, the iterator is used to batch process entities:
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.
When the iterator goes beyond the configured maximum number of results, the server throws an exception. In this case, a scroll is necessary.
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 code snippet, an iterator is created:
IIdIterator iterator = MClient.Querying.CreateIdIterator(query);
In the following code snippet, the iterator is used to batch process entity IDs:
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.
When the iterator goes beyond the configured maximum number of results, the server throws an exception. In that case, a scroll is necessary.
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. We recommend that you do not use these properties, but pass the load configuration as an extra parameter when passing the query object, when applicable.