Package com.commercetools.docs.meta

Class Querying

java.lang.Object
com.commercetools.docs.meta.Querying
public class Querying extends Object
Table of content

Querying the API

Predicates

The system allows the use of predicates when querying the API. Predicates are added as query parameter string to the request itself. The following example shows the usage of input variables

ProjectApiRoot apiRoot = createProjectClient();
apiRoot.customers()
        .get()
        .withWhere("firstName = :firstName and lastName = :lastName",
            Arrays.asList(Pair.of("firstName", "John"), Pair.of("lastName", "Doe")));

apiRoot.customers()
        .get()
        .withWhere("firstName = :firstName", "firstName", "John")
        .addWhere("lastName = :lastName", "lastName", "John");

apiRoot.customers()
        .get()
        .withWhere("firstName = :firstName")
        .addWhere("lastName = :lastName")
        .withPredicateVar("firstName", "John")
        .withPredicateVar("lastName", "Doe");

See the test code.
It's also possible to use array values in predicates in case of a varying number of parameters 
ProjectApiRoot apiRoot = createProjectClient();
apiRoot.productProjections()
        .get()
        .withWhere("masterVariant(sku in :skus)",
            Collections.singletonMap("skus", Arrays.asList("abc", "def")));

apiRoot.productProjections()
        .get()
        .withWhere("masterVariant(sku in :skus)",
            Arrays.asList(Pair.of("skus", "abc"), Pair.of("skus", "def")));

apiRoot.productProjections()
        .get()
        .withWhere("masterVariant(sku in :skus)")
        .withPredicateVar("skus", Arrays.asList("abc", "def"));

apiRoot.productProjections()
        .get()
        .withWhere("masterVariant(sku in :skus)")
        .withPredicateVar("skus", "abc")
        .addPredicateVar("skus", "def");

See the test code.

Query Predicate Builder

The Query Predicate Builder offers a fluent, type-safe interface for building Query Predicates.

Basic Usage


 import static com.commercetools.api.predicates.query.CustomerQueryBuilderDsl.*;

 String predicate = CustomerQueryBuilderDsl.of()
       .firstName().is("John")
       .and()
       .lastName().is("Doe")
       .build();

Examples of Query Predicates

The following examples demonstrate how to use the Query Predicate builder for different scenarios. More examples can be found here.

Equality Comparisons

 CartQueryBuilderDsl.of().id().is("abc");
 CustomerQueryBuilderDsl.of().dateOfBirth().is(LocalDate.parse("2018-10-12"));
 TaxRateQueryBuilderDsl.of().amount().is(0.19);
Logical Operators

 CartQueryBuilderDsl.of().id().is("abc").not();
 CartQueryBuilderDsl.of().id().is("abc").and(p -> p.customerId().is("def"));
 CartQueryBuilderDsl.of().id().is("abc").or(p -> p.customerId().is("def"));
Range Comparisons

 CartQueryBuilderDsl.of().version().isLessThan(10L);
 CartQueryBuilderDsl.of().version().isGreaterThan(10L);
 TaxRateQueryBuilderDsl.of().amount().isLessThan(0.19);
 CustomerQueryBuilderDsl.of().dateOfBirth().isGreaterThan(LocalDate.parse("2018-10-12"));
Collection Queries

 CartQueryBuilderDsl.of().key().isIn(Arrays.asList("foo", "bar"));
 TaxRateQueryBuilderDsl.of().amount().isIn(Arrays.asList(0.19, 0.20));
Nested Queries

 ProductQueryBuilderDsl.of()
   .masterData(m -> m.current(c -> c.slug(l -> l.with(Locale.ENGLISH).is("super-product"))
     .and(t -> t.name(l -> l.with(Locale.ENGLISH).is("Super Product")))));
Special Cases

 CartQueryBuilderDsl.of().key().isDefined();
 CartQueryBuilderDsl.of().key().isNotDefined();
 CartQueryBuilderDsl.of().lineItems().isEmpty();
 TypeQueryBuilderDsl.of().resourceTypeIds().containsAnyVar("approval-flow");

Get by id/key

ProjectApiRoot apiRoot = createProjectClient();
apiRoot.productProjections().withKey("product-key").get();

apiRoot.productProjections().withId("product-key").get();

See the test code.

Query all

ProjectApiRoot apiRoot = createProjectClient();
List<String> ids = QueryUtils.queryAll(apiRoot.productProjections().get(), (productProjections) -> {
    return productProjections.stream().map(ProductProjection::getId).collect(Collectors.toList());
}, 100)
        .thenApply(lists -> lists.stream().flatMap(List::stream).collect(Collectors.toList()))
        .toCompletableFuture()
        .join();

See the test code.

Sorting

Please see Sort for details

Sorting using one parameter:

ProjectApiRoot apiRoot = createProjectClient();
apiRoot.products().get().withSort("masterData.current.name.en asc");

See the test code.

Sorting using multiple parameters:

ProjectApiRoot apiRoot = createProjectClient();
apiRoot.products().get().withSort("masterData.current.name.en asc").addSort("id asc");

See the test code.

Pagination

Limiting the number of the returned documents or page size:

ProjectApiRoot apiRoot = createProjectClient();
apiRoot.products().get().withLimit(4);

apiRoot.products().get().withLimit(4).withOffset(4);

See the test code.

To retrieve the next results use the offset parameter. The example shows how to retrieve page 2:

ProjectApiRoot apiRoot = createProjectClient();

apiRoot.products().get().withLimit(4).withOffset(4);

See the test code.

Test cases

The repository has test cases for each endpoint and query parameter. Please see in the following folder: Resource test cases

For more real world test cases you may also look into the integration test suite: Integration test cases

  • Constructor Details

    • Querying

      public Querying()