{"title":"Display dynamic content using Liquid queries","slug":"liquid-queries","url":"https://support.storeconnect.com/articles/liquid-queries","url_markdown":"https://support.storeconnect.com/articles/liquid-queries.md","subtitle":null,"summary":"A use-case introduction to fetching Salesforce records inside Liquid templates with the query tag: filtering, comparison operators, LIKE patterns, IN arrays, custom data fields, and ordering.","type":"Developer_Documentation","video_url":"","keywords":"liquid queries, query tag, liquid, dynamic content, salesforce records, filtering, comparison operators, like wildcard, in array, custom data fields, ordering, storeconnect liquid","last_modified":"2026-08-21T07:12:35+0000","body_markdown":"The Liquid `query` tag fetches records from a Salesforce object directly inside a Liquid template, so you can present dynamic content powered by real-time data without custom code.\n\nThis article covers the patterns you reach for most often. For the full technical reference — every operator, ordering, distance calculations, error messages, and limitations — see [Liquid query (full reference)](liquid-query).\n\n:::tip\nReach for the standard global drops first (`current_store`, `current_account`, `current_cart`, `product`, `current_account.orders` …). They are pre-computed, scoped to the current store, and far cheaper than running a `query`. Use `query` when no global already exposes what you need.\n:::\n\n## Common use cases\n\n- **Render a custom landing page from a slug** by querying `Product2` with `s_c__slug__c`.\n- **Personalize content for an account or store** by querying account/store-related records via `sfid` or `s_c__store__c`.\n- **Display only currently active records** by filtering on date, time, or numeric ranges (e.g. promotion windows, availability periods).\n- **Build curated or related-item lists** by querying multiple records at once with an `IN` (array) condition.\n- **Sort by distance from a point** (e.g. nearest collection points) using a distance struct — see [Liquid query (full reference)](liquid-query).\n\n## How Liquid queries work\n\n- Query a Salesforce object using its **API name** (e.g. `Product2`, `Account`, `s_c__Promotion__c`).\n- Filter records using one or more conditions — all conditions are joined with **AND**.\n- Conditions support strings, numbers, dates, times, datetimes, and booleans.\n- The result is a list of records you can iterate with a Liquid `for` loop.\n- Field names are the **column names on the experience-site database**, including the `s_c__` prefix and `__c` suffix on StoreConnect-managed fields.\n\n## Basic query syntax\n\n\n```liquid\n\n{%- query 'ObjectName' as variable_name, field1: 'value1', field2: 'value2' -%}\n```\n\n\n| Component        | Description                                                                |\n|------------------|----------------------------------------------------------------------------|\n| `ObjectName`     | Salesforce object API name (e.g. `Product2`, `Account`, `s_c__Tag__c`).    |\n| `as variable_name` | Name of the Liquid variable that will hold the result set.               |\n| Conditions       | Field/value pairs used to filter records — field names are API/column names. |\n\n## Examples\n\n### Fetch every record (no conditions)\n\n\n```liquid\n\n{%- query 'Product2' as records -%}\n```\n\n\n### Filter by a field value\n\n\n```liquid\n\n{%- query 'Account' as records, s_c__sc_id__c: '9876' -%}\n```\n\n\n### Multiple conditions (AND)\n\n\n```liquid\n\n{%- query 'Contact' as records, firstname: 'John', lastname: 'Doe' -%}\n```\n\n\n## Filtering patterns\n\n### String equality is case-insensitive\n\nString equality is **case-insensitive automatically** — both sides are lowercased before comparison. You don't need any prefix or special syntax.\n\n\n```liquid\n\n{%- query 'Product2' as records, s_c__slug__c: 'PRODUCT-SLUG' -%}\n{# matches 'product-slug', 'Product-Slug', etc. #}\n```\n\n\n### LIKE / wildcard matches\n\nUse `%` as a wildcard. LIKE patterns are also case-insensitive.\n\n\n```liquid\n\n{%- query 'Product2' as records, name: 'My%' -%}    {# starts with \"My\"        #}\n{%- query 'Product2' as records, name: '%Product' -%} {# ends with \"Product\"    #}\n{%- query 'Product2' as records, name: '%My%' -%}   {# contains \"My\"           #}\n```\n\n\n### IN queries (match any of a list)\n\n\n```liquid\n\n{%- query 'Product2' as records, s_c__slug__c: ['product-1', 'product-2'] -%}\n```\n\n\nBuild the list dynamically:\n\n\n```liquid\n\n{%- new List slugs = ['product-1', 'product-2'] -%}\n{%- query 'Product2' as records, s_c__slug__c: slugs -%}\n```\n\n\n\n```liquid\n\n{%- assign slug2 = 'product-2' -%}\n{%- query 'Product2' as records, s_c__slug__c: ['product-1', slug2] -%}\n```\n\n\n### Comparison queries (numbers, dates, times, datetimes)\n\nUse `\u003e`, `\u003e=`, `\u003c`, `\u003c=` inside a string for ranges:\n\n\n```liquid\n\n{%- query 's_c__Promotion__c' as records, s_c__usage_limit__c: '\u003e10' -%}\n{%- query 's_c__Availability__c' as records, s_c__start_date__c: '\u003c2026-01-01' -%}\n{%- query 's_c__Availability__c' as records, s_c__start_time__c: '\u003e=14:30' -%}\n{%- query 'Order' as records, s_c__submitted_date__c: '\u003e=2026-01-01T00:00:00Z' -%}\n```\n\n\n:::warning\nAn invalid date or time value (e.g. `'\u003e2023-21-02'`) returns zero results silently — it does not raise. Validate user-supplied dates before using them in a query.\n:::\n\n### Custom data fields\n\nSalesforce custom fields surfaced through Custom Data Mappings are stored in a `custom_data` jsonb column. Filter them with the `data.` prefix:\n\n\n```liquid\n\n{%- query 'Product2' as records, data.color__c: 'blue', data.material__c: 'suede' -%}\n```\n\n\nA Custom Data Mapping must exist for each field you reference. Without one, the tag raises `Invalid liquid query field`.\n\n### Ordering\n\nAdd an `order by` clause **at the end of the tag** — the clause must be quoted:\n\n\n```liquid\n\n{%- query 'Product2' as records order by 'createddate desc' -%}\n{%- query 's_c__Availability__c' as records order by 's_c__end_date__c, name desc' -%}\n```\n\n\n### Limiting results\n\nThere is no native `limit` keyword. Use the standard Liquid `for ... limit:` modifier on the loop, or wrap the loop in `paginate` for full pagination — see [Paginate tag reference](paginate-tag-reference):\n\n\n```liquid\n\n{%- query 'Product2' as records order by 'createddate desc' -%}\n{%- for record in records limit: 10 -%}\n  {{ record.name }}\n{%- endfor -%}\n```\n\n\n## Access query results\n\nIterate the result with a `for` loop:\n\n\n```liquid\n\n{%- query 'Product2' as records -%}\n\n{%- for record in records -%}\n  {{ record.name }}\n  {{ record.sfid }}\n  {{ record['s_c__slug__c'] }}\n{%- endfor -%}\n\n{# total count #}\n{{ records.size }}\n```\n\n\n### Helpful record filters\n\n\n```liquid\n\n{# all attribute names available on the record #}\n{{ record | record_fields | join: ', ' }}\n\n{# the record's table name #}\n{{ record | record_name }}\n\n{# cast the generic record into its full StoreConnect drop #}\n{%- assign product = record | cast: 'Product' -%}\n{{ product.images.first.url }}\n\n{# inverse: drop -\u003e generic record #}\n{%- assign record = product | recordize -%}\n```\n\n\n## Things to keep in mind\n\n- **Queries are not store-scoped.** Records from every store in the org are returned. If you only want the current store, filter explicitly (e.g. `s_c__store__c: current_store.sfid`).\n- **All conditions are joined with AND**, never OR. To union results, run two queries and merge them with `| concat | uniq`.\n- **No joins, no aggregation, no SELECT projection.** Each query loads every column on a single object.\n- **Each `query` tag is a database call.** Don't run a query inside a hot loop — fetch once into a variable and iterate that.\n- **Object and field names are the API/column names.** Standard Salesforce columns use their plain names (`name`, `sfid`, `firstname`); StoreConnect-managed fields use `s_c__…__c`.\n\nFor the full operator matrix, ordering rules, distance calculations, error messages, and the complete limitations list, see [Liquid query (full reference)](liquid-query)."}