Whether or not the user has visited this URL previously in their current session. Note that this will always be false if the user has not allowed session permission (see the Permissions and Personalization documentation). Using this property prevents the page from being fast-cached
The default output that the datastore_item produces when output directly to the template. The default output may change at any time. Template developers should avoid using this and should handle the output of datastore items themselves
The default output that the datastore_items will produce when it is output directly to the template - using the "output_in_list" property of each datastore_item in the items list
List containing all of the combined datastore_items from the prepended, fetched, and appended lists. If unique is true, this list will not contain any duplicates. If max_size is set, this list will not contain more than the number of datastore_items specified.
The total number of datastore_items in the items list, including prepended, fetched, and appended lists, and respecting the unique and max_size properties.
If set, this is the maximum number of items that will be returned in the items list and the maximum number of items that will be included when this datastore_items object is enumerated as a list. When not set, this value will be 0.
The maximum number of items that were allowed to be in the list of fetched datastore_items. May be 0 in some cases (such as when when there are no fetched datastore_items.
The 1-based index of the paginated results returned in the list of fetched datastore_items, which is calculated from the start and limit parameters. Useful for paginated results.
If any items were fetched from the database, total_pages will contain the number of paginated result pages in the database for the provided arguments. This may also be calculated using the total_count and limit properties.
ExampleSample datastore item queriesThree query patterns for datastore_items: a simple numeric range/comparison, a complex nested query with NOT and optional conditions, and a dynamically built query across configurable fields.
Filters the Hotels datastore to items with more than 100 rooms and an average room price of 100 or less, combining two numeric comparisons with AND.
Complex nested query with NOT and an optional condition
Liquid
{%- capture query -%}
is_vegan
OR
(
number_of_ingredients < 6
AND (
NOT ingredients contains chicken
-ingredients contains pork
- ingredients LIKE 'beef'
{%- if other_meat_to_avoid is_valid -%}
AND !(ingredients CONTAINS "{{other_meat_to_avoid | replace: '"', '""' }}")
{%- endif -%}
)
AND NOT (
'contains_dairy'
OR ingredients contains egg
)
)
{%- endcapture -%}
{%- datastore_items items = datastore:'Recipes' query:query -%}
Matches vegan recipes, or recipes with fewer than 6 ingredients that avoid chicken, pork, and beef (using NOT and the bare - shorthand for AND NOT), plus an optional other_meat_to_avoid the caller may supply, and excludes anything marked contains_dairy or containing egg.
Query multiple configurable fields dynamically
Liquid
{%- set query = "" -%}
{%- set fieldvalue = request.query_params['fieldvalue'] | urldecode -%}
{%- if request.query_params['fieldnames'] is_valid and fieldvalue is_valid -%}
{%- var fieldnames = request.query_params['fieldnames'] | urldecode | split: ',' -%}
{%- var queryparts = '' | compact -%}
{%- for field in fieldnames -%}
{%- capture querypart %}{{field}} = "{{fieldvalue | replace: '"', '""'}}"{% endcapture -%}
{%- set queryparts = queryparts | concat: querypart -%}
{%- endfor -%}
{%- set query = queryparts | join: ' OR ' -%}
{%- endif -%}
{%- datastore_items items = datastore:entity query:query -%}
Builds an OR query across a caller-supplied, comma-separated list of field names (fieldnames), matching each one against the same escaped value (fieldvalue) from the request's query string.
ExampleGetting and manipulating entity listsUse the list methods and filters to create and manage lists of data in your templates
Liquid
{%- datastore_items var featured_houses = datastore:"houses" query:"is_featured = true" -%}
{%- datastore_items var houses_by_folder = datastore:"houses" folder:entity.folder -%}
Concatenate and uniq the easy way
Liquid
{% datastore_items var houses = featured_houses houses_by_folder unique %}
Concatenate manually
Liquid
{% var houses = featured_houses | concat: houses_by_folder %}
Unique manually
Liquid
{% var houses = houses | uniq %}
Get one random item from the list
Liquid
{% var random_house = houses | rand %}
Get a random item from the list. Prevents the page from being fast-cached, and every time the page is loaded a new random item will be chosen.
Get one random item from the list and allow fast-caching
Liquid
{% var random_house = houses | rand:1, false, false %}
Get a random item from the list and allow the page to be fast-cached, resulting in much faster pageload speeds but the same random item will be used until the fast cache expires.
Sort the full list randomly
Liquid
{% set houses = houses | shuffle %}
Sort the full list randomly. The page will not be able to be fast-cached, and every time the page is loaded a new random order will be chosen. To allow the page to be fast-cached, pass false to the shuffle command.
Various ways to filter and slice
Liquid
{%- var one_rooms = houses | where: "rooms", "1" | sort: "price" -%}
{%- var cheapest = one_rooms | first -%}
{%- var mid_houses = one_rooms | slice: 1, 6 -%}
{%- var expensive_houses = one_rooms | slice: 7 -%}
{%- var num_expensive_houses = expensive_houses | size -%}
{%- var grouped_by_rooms = houses | group_by: "rooms" | sort: "Key" -%}
{%- for list in grouped_by_rooms -%}
<p>{{list.Key | default: "Unknown"}} Rooms ({{list.Value | size }} houses)</p>
{%- endfor -%}
Mapping and Compact
Liquid
{%- var mapped_by_rooms = grouped_by_rooms | map: "Value" -%}
{%- for list in mapped_by_rooms -%}
<h4>{{list[0].rooms | default: "Unknown"}} Rooms</h4>
<ul>
<li>{{list | map: "description" | compact | join: "</li><li>" }}</li>
</ul>
{%- endfor -%}
ExampleGet datastore items using an advanced queryBuild a query string from request params and pass it to datastore_items to filter by custom fields (e.g. beds, baths).
Liquid
{%- var query = "movein_ready = true" -%}
{%- if request.query_params.beds is_int -%}
{%- set query = query | append: " and beds = " | append: request.query_params.beds -%}
{%- endif -%}
{%- if request.query_params.baths is_int -%}
{%- set query = query | append: " and baths = " | append: request.query_params.baths -%}
{%- endif -%}
{%- datastore_items collection = datastore:entity query:query -%}
{% datastore_item %}
{% datastore_item output_to_template? [[var, set, or assign]? variable]? output_to_template? = value %}Parameters
Optional. Specify either "var", "set" or "assign" to change which scope this {% datastore_items %} is stored on. "var" is the default behavior.
variableoptionalvariable
argumentsrequiredcollection
Key:value pairs. May use the variable arguments syntax.
Options
prependoptionallist
May be a single datastore_item, a list of datastore_items, or the name or guid of one datastore_item, to be included at the beginning of the datastore_items list.
appendoptionallist
May be a single datastore_item, a list of datastore_items, or the name or guid of one datastore_item, to be included at the end of the datastore_items list.
excludeoptionallist
May be a single datastore_item, a list of datastore_items, or the name or guid of one datastore_item that should NOT be included in the fetched results. Has no effect on prepended or appended datastore_items.
exclude_prependedoptionalboolean
True to specifically exclude all prepended datastore_items from the fetched results. If "unique:true" is specified this is the default behavior, although you may also specify "exclude_prepended:false" to allow any prepended items to be fetched along with other results anyway.
exclude_appendedoptionalboolean
True to specifically exclude all appended datastore_items from the fetched results. This is false by default - even if "unique:true" is specified - so that results are returned in the proper order.
uniqueoptionalboolean
True to remove duplicates from each of the resulting lists (prepended, fetched, appended, and items), although there may be duplicates between the prepended, fetched, and appended lists. The "items" list will include objects in the order in which they appear - with prepended items first, then fetched items, then appended items.
max_sizeoptionalinteger
The maximum number of items to be included in the "items" list. If there are any prepended or appended items, this will automatically lower the "limit" to only fetch as many datastore_items as needed. Note that this may also impact both the "page" and "total_pages" values in the resulting datastore_items. In order to use pagination with a list loaded using "max_size" use "start" instead of "page" and "limit".
filteroptionalvalue
Only include datastore items that match the given string filter
datastoreoptionalvalue
May include multiple datastores. Only include datastore items with one of the given datastores
queryoptionalvalue
Only include datastore items which match the given query. Queries can only filter on the item's custom fields (by FieldID); built-in/reserved properties such as the item's Name are not queryable this way. Datastore item queries have their own advanced syntax, which may be reviewed at https://help.marketpath.com/liquid/advanced-datastore-queries
tagoptionalvalue
May include multiple tags. Only include datastore items with one of the given tags
authoroptionalvalue
May include multiple authors. Only include datastore items with one of the given authors
folderoptionalvalue
May include multiple folders. Only include datastore items with one of the given folders
date_created_startoptionalvalue
Only include datastore items with date_created greater than or equal to date_created_start. Remember that date_created will typically be the date that the datastore item was first published.
date_created_endoptionalvalue
Only include datastore items with date_created less than or equal to date_created_end. Remember that date_created will typically be the date that the datastore item was first published.
has_urloptionalboolean
If true, only return datastore_items that have a URL. If false, only return datastore_items that do NOT have a URL.
templateoptionalobject
Only return datastore_items with one of these templates. May be a single template, a list of templates, or the name or guid of a template to filter the results by.
include_in_searchoptionalboolean
True or false to only return datastore_items whose include_in_search property matches the provided value.
domain_nameoptionalobject
Only return datastore_items from the given domain.
startoptionalinteger
Set the 1-based index of the first datastore_item to fetch.
pageoptionalinteger
Used to automatically calculate the first datastore_item to fetch based on both the "limit" and the 1-based "page" value. Defaults to 1, but is ignored if "start" is set.
limitoptionalinteger
The maximum number of datastore_items to fetch. Defaults to 10. Note that if "max_size" is defined, then "limit" may be automatically lowered even if specified separately.
sort_byoptionalstring
Specify which property to sort the results by. Has no effect on prepended or appended datastore_items. By default, results will be sorted by relevance if there is a filter string and date_created desc (newest first) if not. Options include:
relevance: only applies when there is a filter string. When sorting by relevance sort_direction is ignored.
date_created: the date each datastore_item was first published. Unpublishing and republishing one resets date_created to the current date.
random: results will be returned in a random order, which prevents the page from being fast-cached. Setting cache_random:true overrides this behavior and allows the page to be fast-cached anyway.
name
title
url
browser_title
sort_directionoptionalstring
asc or desc.
cache_randomoptionalboolean
True to allow the results to be cached when sort_by is "random".
ExampleSample datastore item queriesThree query patterns for datastore_items: a simple numeric range/comparison, a complex nested query with NOT and optional conditions, and a dynamically built query across configurable fields.
Filters the Hotels datastore to items with more than 100 rooms and an average room price of 100 or less, combining two numeric comparisons with AND.
Complex nested query with NOT and an optional condition
Liquid
{%- capture query -%}
is_vegan
OR
(
number_of_ingredients < 6
AND (
NOT ingredients contains chicken
-ingredients contains pork
- ingredients LIKE 'beef'
{%- if other_meat_to_avoid is_valid -%}
AND !(ingredients CONTAINS "{{other_meat_to_avoid | replace: '"', '""' }}")
{%- endif -%}
)
AND NOT (
'contains_dairy'
OR ingredients contains egg
)
)
{%- endcapture -%}
{%- datastore_items items = datastore:'Recipes' query:query -%}
Matches vegan recipes, or recipes with fewer than 6 ingredients that avoid chicken, pork, and beef (using NOT and the bare - shorthand for AND NOT), plus an optional other_meat_to_avoid the caller may supply, and excludes anything marked contains_dairy or containing egg.
Query multiple configurable fields dynamically
Liquid
{%- set query = "" -%}
{%- set fieldvalue = request.query_params['fieldvalue'] | urldecode -%}
{%- if request.query_params['fieldnames'] is_valid and fieldvalue is_valid -%}
{%- var fieldnames = request.query_params['fieldnames'] | urldecode | split: ',' -%}
{%- var queryparts = '' | compact -%}
{%- for field in fieldnames -%}
{%- capture querypart %}{{field}} = "{{fieldvalue | replace: '"', '""'}}"{% endcapture -%}
{%- set queryparts = queryparts | concat: querypart -%}
{%- endfor -%}
{%- set query = queryparts | join: ' OR ' -%}
{%- endif -%}
{%- datastore_items items = datastore:entity query:query -%}
Builds an OR query across a caller-supplied, comma-separated list of field names (fieldnames), matching each one against the same escaped value (fieldvalue) from the request's query string.
ExampleGetting and manipulating entity listsUse the list methods and filters to create and manage lists of data in your templates
Liquid
{%- datastore_items var featured_houses = datastore:"houses" query:"is_featured = true" -%}
{%- datastore_items var houses_by_folder = datastore:"houses" folder:entity.folder -%}
Concatenate and uniq the easy way
Liquid
{% datastore_items var houses = featured_houses houses_by_folder unique %}
Concatenate manually
Liquid
{% var houses = featured_houses | concat: houses_by_folder %}
Unique manually
Liquid
{% var houses = houses | uniq %}
Get one random item from the list
Liquid
{% var random_house = houses | rand %}
Get a random item from the list. Prevents the page from being fast-cached, and every time the page is loaded a new random item will be chosen.
Get one random item from the list and allow fast-caching
Liquid
{% var random_house = houses | rand:1, false, false %}
Get a random item from the list and allow the page to be fast-cached, resulting in much faster pageload speeds but the same random item will be used until the fast cache expires.
Sort the full list randomly
Liquid
{% set houses = houses | shuffle %}
Sort the full list randomly. The page will not be able to be fast-cached, and every time the page is loaded a new random order will be chosen. To allow the page to be fast-cached, pass false to the shuffle command.
Various ways to filter and slice
Liquid
{%- var one_rooms = houses | where: "rooms", "1" | sort: "price" -%}
{%- var cheapest = one_rooms | first -%}
{%- var mid_houses = one_rooms | slice: 1, 6 -%}
{%- var expensive_houses = one_rooms | slice: 7 -%}
{%- var num_expensive_houses = expensive_houses | size -%}
{%- var grouped_by_rooms = houses | group_by: "rooms" | sort: "Key" -%}
{%- for list in grouped_by_rooms -%}
<p>{{list.Key | default: "Unknown"}} Rooms ({{list.Value | size }} houses)</p>
{%- endfor -%}
Mapping and Compact
Liquid
{%- var mapped_by_rooms = grouped_by_rooms | map: "Value" -%}
{%- for list in mapped_by_rooms -%}
<h4>{{list[0].rooms | default: "Unknown"}} Rooms</h4>
<ul>
<li>{{list | map: "description" | compact | join: "</li><li>" }}</li>
</ul>
{%- endfor -%}
ExampleGet datastore items using an advanced queryBuild a query string from request params and pass it to datastore_items to filter by custom fields (e.g. beds, baths).
Liquid
{%- var query = "movein_ready = true" -%}
{%- if request.query_params.beds is_int -%}
{%- set query = query | append: " and beds = " | append: request.query_params.beds -%}
{%- endif -%}
{%- if request.query_params.baths is_int -%}
{%- set query = query | append: " and baths = " | append: request.query_params.baths -%}
{%- endif -%}
{%- datastore_items collection = datastore:entity query:query -%}