Querying client

The SDK provides a Querying client for executing queries.

Note

The client variable in the following code examples refers to the ContentHubClient instance. When using the JavaScript SDK, the variable name can be chosen freely, but is also called client at instantiation in the documentation.

Create a query

For more information about creating queries, please refer to the Creating a query with filters.

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, 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 you know that a query only matches a single entity, it is convenient to 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 entity IDs:

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 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

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

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

In the following 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 that 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 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 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.

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

In the example below, we 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
  }

Do you have some feedback for us?

If you have suggestions for improving this article,