Mechanic filters
Last updated
Was this helpful?
Last updated
Was this helpful?
This page defines all of the that are available in Mechanic Liquid. Mechanic supports many of our own filters, as well as an array of filters drawn from Shopify Liquid.
Liquid filters should not be confused with , which are used to conditionally ignore incoming events.
This filter converts a browser user agent string into an object that represents the browser itself. Data from is used to match user agents.
Supports converting a two-dimensional array to a CSV string, and back again.
delimiter
(optional): A single character that separates the fields in the CSV. Defaults to a comma.
include_bom
(optional): A boolean value that, when set to true, includes a Byte Order Mark (BOM) at the beginning of the CSV string to enhance compatibility with Microsoft Excel. Defaults to false.
Unlike Shopify Liquid, Mechanic's date filter does not require a format argument. If one is not given, Mechanic defaults to formatting the date per ISO8601.
This filter accepts the special value "now"
. This may optionally be combined with a single date calculation, as in "now + 5 days"
or "now - 5 weeks"
. For specifics on date calculation, see notes below for the advance
option.
The date filter also accepts these following options, evaluated in the following order:
If given, the resulting time string will be in the specified timezone.
If this option is not provided, the time is assumed to be in the store's local timezone, as configured at the Shopify level.
All date calculations are performed with respect to the current timezone, with consideration for DST and other calendar variances.
beginning_of_year: true
or end_of_year: true
beginning_of_quarter: true
or end_of_quarter: true
beginning_of_month: true
or end_of_month: true
beginning_of_week: weekday
or end_of_month: weekday
weekday
must be a string naming the first day of the week for the intended usage, e.g. "sunday"
or "monday"
beginning_of_day: true
or middle_of_day: true
or end_of_day: true
advance: "1 year 6 months"
Supports any combination of years, months, weeks, days, hours, minutes, seconds
Supports positive and negative values
Durations are calculated in the order given, left to right
Seconds, minutes, and hours are all implemented as constant intervals
Days, weeks, months, and years are all variable-length, appropriate for the current time in the current timezone (see tz
). For example, {{ "2023-01-31" | date: "%F", advance: "1 year 1 month" }}
returns 2024-02-29
.
Commas and signs may be used for clarity. Pluralization is optional. All of the examples below are equivalent:
{{ "now" | date: advance: "-3 hours, +2 minutes, -1 second" }}
{{ "now" | date: advance: "-3 hours, 2 minutes, -1 second" }}
{{ "now" | date: advance: "-3 hour 2 minute -1 second" }}
{{ "now" | date: advance: "-3 hours 2 minutes -1 seconds" }}
Use parse_date to parse a date string, when its exact format is known. This filter is useful for strings that contain an ambiguous date value, like "01/01/01"
.
This filter returns an ISO8601 string, representing the parsed date value in the store's local timezone. If the supplied date string cannot be parsed successfully, the filter will return nil.
These filters allow you to compress and decompress strings, using gzip compression.
In general, all strings passing through Mechanic must be UTF-8, and must ultimately be valid when represented as JSON. However, because gzip'd content may not be UTF-8, and because it may be important to preserve the original encoding, the gunzip filter supports a force_utf8: false
option. Use this when you're certain the original encoding must be preserved, if you ultimately intend to pass along the string in a JSON-friendly representation. (For example, you might gunzip a value, and then use the base64 filter to represent it safely within JSON.)
Useful for preparing key-value pairs of GraphQL query or mutation arguments.
Allows converting objects to their JSON representations, and parsing that JSON into hashes.
The parse_json filter raises an error when invalid JSON. To ignore parse errors, and to return null when an error is encountered, add silent: true
to the filter's options:
Allows for rendering an iterable object (i.e. an array) as a series of JSON lines, separated by simple newlines.
The parse_jsonl filter raises an error when invalid JSONL is received.
This filter accepts a GraphQL query string, sends it to Shopify, and returns the full response â including "data"
and "errors"
.
This filter also supports GraphQL variables, via an optional named argument called variables
.
In addition to our own filters, Mechanic supports the following data filter from Shopify Liquid:
Accepts string input, given an RSA PEM key string as a filter option.
Use this filter on strings to remove indentation from strings.
In addition to our own filters, Mechanic supports the following string filters from Shopify Liquid:
Note that this filter does not automatically append the currency ISO code (e.g. it will not generate output resembling "âŦ100,000.00 EUR"). To add the ISO code manually, use one of these examples:
In addition to our own filters, Mechanic supports the following math filters from Shopify Liquid:
This filter is particularly useful when performing work in batches, by making it easy to split an array of potentially large size into smaller pieces of controlled size.
This filter accepts the name of an object property or attribute, and returns a hash that whose values are every element in the array, keyed by every element's corresponding property or attribute.
This filter appends any number of arguments onto the provided array, returning a new array, leaving the original unmodified.
This filter can be used on any array. Used without any arguments, it returns a single random element from the array. Provide an integer argument to return another array of that size, containing a random subset of the input array.
When applied to an array, this filter accepts an integer offset, and an optional integer length (defaulting to 1). If the length is 1, it returns the single element found at that index of the input array. Otherwise, it returns a slice of the array, beginning at the provided index, having the provided length.
Negative offsets begin counting from the end of the array.
This filter prepends any number of arguments onto the provided array, returning a new array, leaving the original unmodified.
In addition to our own filters, Mechanic supports the following array filters from Shopify Liquid:
When applied to a hash, this filter returns a new hash which omits all keys having nil values.
This filter accepts one or more string arguments, corresponding to keys that should be left out of the output. The filter returns a new hash, containing all the key/value pairs of the original hash except those keys named as arguments.
Returns an array of keys found in the supplied hash.
When applied to a hash, the slice filter accepts one or more string arguments, corresponding to keys that the hash may contain. This filter will then return a new hash, containing only matching key/value pairs from the original hash.
Returns an array of values found in the supplied hash.
Mechanic's date filter is based on , and has several important extensions.
Date formats may be given per. For an interactive format-building tool, see .
tz
â
Under the hood, parse_date uses , and inherits its behavior with regard to missing upper components.
Across the documentation and , you'll frequently see json
used for serializing argument values. Users have reported some rare cases where this filter is insufficient, and where graphql_arguments
does the trick instead.
To try this using a Shopify action, use the syntax.
To try this using the shopify filter, use the argument.
This results in a containing the following GraphQL:
For a more complex example, see from the task library.
The parse_jsonl filter can be used to parse a series of JSON strings, each on their own line, into an array of hashes. Useful when preparing for .
Use this filter to parse an XML string. (Under the hood, this filter calls .) Useful for processing output from third-party APIs, either by "http" actions, or by parsing content from .
Use to quickly and precisely assemble your queries.
Variables can be a useful part of making queries reusable within a task, or for working around .
This filter accepts a phone number â country code is required! â and outputs it in . If the number does not appear valid, the filter returns nil
.
Use this filter to match a string with a Ruby-compatible regular expression pattern (see ).
This filter returns the entire matched string (i.e. ). Use the "captures" or "named_captures" lookups to receive an array or hash of captures, respectively (i.e. , ).
This filter only returns the first match found. To find all available matches in a string, use .
Works like , but uses SHA-512 instead.
This filter is useful for generating !
Use this filter to find all available matches in a string, using a Ruby-compatible regular expression pattern (see ).
This filter returns an array of matches, consisting of each matched string (i.e. ). Use the "captures" or "named_captures" lookups on individual matches to receive an array or hash of captures, respectively (i.e. , ).
This filter returns an array of matches. To only find the first match, use .
Works like , but uses SHA-512 instead.
Formats a number (given as an , , or ) as currency. Called with no arguments, this filter uses the store's primary currency and default locale.
A three-character ISO currency code may be specified as the first argument; currency support is drawn from the project. The locale may be overridden as a named option; locale support is drawn from .
This filter is an implementation of . It accepts an array, and an integer count, and â optionally â a "fill_with" option.
This filter is an implementation of . It accepts an array, and an integer count, and â optionally â a "fill_with" option.
Sorts an array uses the human-friendly sort order defined by . Accepts a single optional parameter, specifying an attribute to sort.
This filter complements Shopify Liquid's and filters. Choose your sort filter intentionally: machine audiences are typically happier with "sort", and human audiences are typically happier with "sort_naturally".