Querying client

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 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, you can use the singleAsync method.

var entity: IEntity = await client.querying.singleAsync(query);

Warning

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, it is convenient to use the singleIdAsync method.

var entityId: number = await client.querying.singleIdAsync(query);

Warning

When multiple items match the query, an InvalidOperationException is thrown.

Query for one or multiple entities

To query for one or more entities:

import { IEntityQueryResult } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/entity-query-result";

var queryResult: IEntityQueryResult = await client.querying.queryAsync(query);

The IEntityQueryResult.Items contains the returned entities.

Query for one or multiple entity ids

To query for one or more entities:

import { IIdQueryResult } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/id-query-result";

var queryResult: IIdQueryResult = await client.querying.queryIdsAsync(query);

The IIdQueryResult.Items contains the returned entities.

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:

import { EntityIterator } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/entity-iterator";

var iterator = new EntityIterator(client, query, EntityLoadConfiguration.Full);

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

while (await iterator.moveNextAsync()) {
  var entities: IEntity[] = iterator.current.items;
  // Do something with the entities
}

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

Warning

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:

import { EntityIdIterator } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/id-iterator";

var iterator = new EntityIdIterator(client, query);

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

while (await iterator.moveNextAsync()) {
  var ids: number[] = iterator.current.items;
  // Do something with the ids
}

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

Warning

When the iterator goes beyond the configured maximum number of results, the server throws an exception. To solve this issue, you can use another query with a scroll. The scroll will be used to skip the first few elements.

The following example shows how to skip the first 200 elements using the scroll:

  var definitionQueryFilter = new DefinitionQueryFilter({ 
    names: ["M.Asset", "M.Fragment"],
    operator: ComparisonOperator.Equals 
  });

  // scroll by skipping 200
  var query = new Query({
    filter: definitionQueryFilter,
    skip: 200
  });

  var iterator = new EntityIdIterator(client, query);
  iterator

  while (await iterator.moveNextAsync()) {
    var ids: number[] = iterator.current.items;
    // Do something with the ids
  }

If you have suggestions for improving this article, let us know!