Advanced Datastore Queries

Marketpath templates have the ability to query datastores in unique and powerful ways. Dive into the advanced topic of liquid datastore queries.

The simplest way to query datastores - similar to other content - is to use the "filter" argument. This will return all datastore items containing the matching text in any searchable field. Eg:

{% var filterTerm = request.query_params['filter'] %}
{% datastore_items items = datastore:entity filter:filterTerm %}

Unlike other content types, however, datastore items can also be queried using a more advanced syntax to return a more specific set of results. Eg:

{% var filterTerm = request.query_params['filter'] | urldecode %}
{% var escapedTerm = filterTerm | replace: '"', '""' %}
{% capture var filterQuery %}description CONTAINS "{{escapedTerm}}" OR requirements CONTAINS "{{escapedTerm}}"{% endcapture %}
{% datastore_items items = datastore:entity query:filterQuery %}

Syntax

Leading and extra whitespace is ignored. Quoted whitespace is not ignored. Capitalization does not matter.

[phrase]

[simplephrase] or ( [phrase] ) or NOT [phrase] or [phrase] AND [phrase] or [phrase] OR [phrase]

[simplephrase]

[field] or [field] [condition] [value]

[field]

[quotedstring] or [unquotedstring]

[condition]

=, ==, !=, <>, ><, <, >, <=, >=, CONTAINS, or LIKE

[value]

[numericvalue], [quotedstring], or [unquotedstring]

[numericvalue]

positive or negative integer

[quotedstring]

"..." or '...'. To escape quotes inside a quoted string, duplicate the quote character (eg: "...""..." or '...''...').

[unquotedstring]

single word containing only letters, numbers, dashes, and underscores

Grouping Phrases

Multiple phrases may be grouped into a larger phrase and combined using the AND or OR keywords. It is possible to group more than 2 phrases together in this way, but if both AND and OR keywords are used then AND takes precencence (ie: "a and b or c and d" is equivalent to "(a and b) or (c and d)"). When using both AND and OR phrases together, you can - and should - explicitly identify the proper grouping using parenthesis (ie: " a and (b or c) and d"). Explicitly identifying the proper grouping makes your code more consistent and readable even if the default behavior is the desired behavior.

NOT

Phrases may be inverted to return results that do NOT match the conditions using the NOT keyword. Eg: "a" and "NOT a" will return opposite result sets.

Conditions

If no condition is specified, the phrase will match all datastore items with any value for the specified field.

= or ==

Matches datastore items where the specified field exactly matches the specified value.

!=, <>, or ><

Matches datastore items where the specified field does not exactly match the specified value.

<

Matches datastore items where the specified field is less than the specified value.

>

Matches datastore items where the specified field is greater than the specified value.

<=

Matches datastore items where the specified field is less than or equal to the specified value.

>=

Matches datastore items where the specified field is greater than or equal to the specified value.

CONTAINS or LIKE

Matches datastore items where the specified field contains the specified text value.

Synonyms

The following are synonyms which developers may use at their discretion. Each of the following is synonymous in queries:

AND: and, +, &, && (eg: "a and b" is the same as "a && b")

OR: or, |, || (eg: "a or b" is the same as "a || b")

NOT: not, ! (eg: "not b" is the same as "!b")

AND NOT: - (eg: "a and not b" is the same as "a - b")

Examples

Related