Queries

A query is simply a request for data from an index – e.g. ‘Return all active products with a price below 100’ or ‘Return all users who live in Denmark’.

Queries are created by stringing together a set of expressions – as in Figure 1.1 where we’re asking for all products which are Active and in SHOP2.

Figure 1.1 An expression

You can think of each expression as being a kind of filter which limits what the query returns by only returning products which match the expression criteria, typically by checking if a field in the index has a specific value.

The anatomy of an expression is this:

• On the left side you have an index field – this can be a standard field or a generated field
• In the middle you have an operator – it defines how you’re comparing the left and right-side values, e.g. GreaterThan, LessThan, Equal, or IsEmpty.
• On the right side you have a test value – this is the value you’re comparing with the value(s) in the index field

Expressions may be combined in AND-groups (all expressions inside the group must be true for a product/user/page to be included in the result) and OR-groups (one of the expressions in this group must be true for a product/user/page to be included in the result). You can also check Negate for a group to return all elements not matching the expressions. All in all, this makes it possible to create pretty powerful and complex queries – although in most cases it’s not necessary to complicate things!

To create a query:

1. Go to Settings > Repositories and open a repository
2. Click Add Query in the toolbar
3. Provide a name and select an index as a data source
4. Under the Expressions section:
   • Click Add group or Add expression
   • Select an index field using the dropdown
   • Select an operator
   • Use the term selector/pencil icon to set a test value
   • Click OK

When creating expressions, you must select an operator.

The available operators depend on the type of field selected - for a Boolean field you only have access to true/false, for a string array you have Contains, MatchAll, MatchAny and In, and so on.

This makes it easier to select an appropriate operator for an expression (Figure 2.1).

Figure 2.1 Modifying expressions using operators

Some of the operators are a little hard to differentiate at a glance - here's a short explanation:

The right side of an expression contains the test value. Test values can be either static or dynamic depending on the type of test value you use.

The following test value types are available:

• Constant – a static value of a particular data type – string, double, datetime, etc.
• Parameter – a dynamic value passed to the query from frontend, e.g. through a search field
• Macro – a dynamic value retrieved from the context, e.g. PageID, WebsiteID, UserID, CartID, etc.
• Term – a static value present in the field being queried
• Code – lets you select a provider which provides a graphical interface to manipulating e.g. a DateTime C# object (CurrentDate – 1 month)

To define a test value:

• Click the pencil icon on the right side of the expression
• Select a test value type
• Configure the type selected:
  • Constant: Select a data type and enter a value
  • Parameter: Select a parameter - see later section
  • Macro: Select one of the context-specific values available
  • Term: Use the dropdown to select one or more of the terms that exist in the field (Figure 3.1)
  • Code: Select a provider and configure the associated settings

Figure 3.1 Selecting terms when defining a test value

The following macros are currently available as test values:

A parameter is a variable which can be used as a test value in an expression to make the query dynamic – so you could create a parameter called Search, use it as a test value in an expression, and then pass dynamic values to it from frontend through a search filter.

It is also used by facets, with each facet passing values to a specific parameter - e.g. Color or Size.

To create a parameter:

• Click Add Parameter on the query page
• Name the parameter
• Select an appropriate data type for the parameter – this should match the data type of the field your will be testing against
• (Optional) Specify a default value
• Click OK

Once created, a parameter will be listed in the parameters table (Figure 4.1) – and will be available as a test value when creating expressions.

Figure 4.1 Creating parameters

The data returned by a query can be sorted in a number of ways. Most of the time, you will want to control sorting at the app-level, on either the Product Catalog app instance or the Query publisher app instance used to publish the data.

Should you want to not do that, or should those settings fail for some reason, you can create default sorting criteria on the query level:

• Click Add sorting on the query page
• Select a field and a direction
• Click OK

Figure 5.1 Add sorting

Please note that this is a default sorting and that any sorting applied at the app-level will override it.