Create a query

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.

RequestResponse

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.

RequestResponse

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:

RequestResponse

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:

RequestResponse

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:

RequestResponse

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:

RequestResponse

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:

RequestResponse

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:

RequestResponse

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:

RequestResponse

  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
  }