Understanding Variables with Liquid

Prompt bodies can use Liquid, an open-source template engine created by Shopify that allows for dynamic content generation. This guide helps show you how to use Liquid syntax to create dynamic prompts with variables, tags, and filters.

Variables


The most basic kind of expression is just the name of a variable. Liquid variables  should consist of alphanumeric characters and underscores, should always start with a letter, and do not have any kind of leading sigil (that is, they look like var_name, not $var_name). Variables in Liquid are used to store and display data. They are defined by placing them between double curly braces {{ }}. For example, {{ product_title }} would display the title of a product.

Array or hash access. If you have a variable whose value is an array or hash, you can use a single value from that array/hash as follows:
  • my_variable[<KEY EXPRESSION>] — The name of the variable, followed immediately by square brackets containing a key expression.
    • For arrays, the key must be a literal integer or an expression that resolves to an integer.
    • For hashes, the key must be a literal quoted string or an expression that resolves to a string.
  • my_hash.key — Hashes also allow a shorter "dot" notation, where the name of the variable is followed by a period and the name of a key. This only works with keys that don't contain spaces, and (unlike the square bracket notation) does not allow the use of a key name stored in a variable.
  • Note: if the value of an access expression is also an array or hash, you can access values from it in the same way, and can even combine the two methods. (For example, site.posts[34].title.)

Variables in Prompts

A prompt which uses variables to pass data might look like this:
# Prompt
Prompt.create(
  name: "Welcome letter standard",
  body: "Write a new hire welcome letter to new employee whose first name is " \
        "{{ first_name }}. {{ first_name }} has been hired as a {{ job_title }}. " \
        "The {{ job_title }} role is within the {{ department.name }} department". \
        "Let them know that their new company email will be {{ email }}."
)
To create a hash for the Liquid template in the prompt body, you need to provide values for each of the variables used within the template. In this case, the variables are first_name, job_title, and email.

  • first_name is a string.
  • job_title is a string.
  • email is a string.
  • department is a hash containing a key name which contains a string.
# Variable values
{
  "first_name" => "James",
  "job_title" => "Prompt Engineer",
  "email" => "james@fakeexample.com",
  "department" => {"name" => "Content"}
}
When rendering the Liquid template with this hash, it will replace {{ first_name }}, {{ job_title }}, and {{ email }} with "James", "Prompt Engineer", and "james@fakeexample.com", respectively. It will also replace {{ department.name }} with "Content".
# Constructed prompt text
Write a new hire welcome letter to new employee whose first name is James. James was hired
as a Prompt Engineer. The Prompt Engineer role is within the Content department. Let them
know that their new company email will be james@fakeexample.com. Also let them their company
laptop will be arriving by mail shortly.

Tags


Tags in Liquid are used to control the flow of the template. They are defined by placing them between curly braces {% %}. For example, {% if product_available %} would only display the code between the if statement if the product is available. See a full list of tags.

Using Tags in Prompts

Using Tags for control structures, like if statements, can add complexity to your prompts.
# Prompt
Prompt.create(
  name: "Welcome letter standard",
  body: "Write a new hire welcome letter to new employee whose first name is " \
        "{{ first_name }}. {{ first_name }} has been hired as a {{ job_title }}. " \
        "Let them know that their new company email will be {{ email }}. " \
        "The {{ job_title }} role is within the {{ department.name }} department". \
        "{% if department.code == 'IT' %}" \
          "Also let them know that since they are in the {{ department.name }} department" \
          "their company laptop will be arriving by mail shortly.
        "{% endif %}"
)
In this case, the variables are first_name, job_title, and email. Additionally, job_title is an object with a property department_code.

  • first_name is a string.
  • job_title is a string.
  • email is a string.
  • department is a hash containing a key name which contains a string and a key department_code which also contains a string.
# Variable values
{
  "first_name" => "Alice",
  "job_title" => "Software Developer",
  "email" => "alice@fakeexample.com",
  "department" => {"name" => "Information Technology", "department_code" => "IT"}
}
When rendering the Liquid template with this hash, it will replace {{ first_name }}, {{ job_title }}, and {{ email }} with "Alice", "Software Developer", and "alice@example.com", respectively. It will also replace {{ department.name }} with "Information Technology". The {% if %} condition will evaluate based on the code within the department hash. Since this condition evaluates to true it will print the additional sentence and also will replace {{ department.name }} with "Information Technology" in the additional sentence.
# Constructed prompt text
Write a new hire welcome letter to new employee whose first name is Alice. Alice was hired
as a Software Developer. The Software Developer role is within the Content department. Let them
know that their new company email will be james@fakeexample.com. Also let them their company
laptop will be arriving by mail shortly. Also let them know that that since they are in the  
Information Technology department their company laptop will be arriving by mail shortly.

Filters


Filters are used to modify the output of a variable. They are defined by placing them after the variable and separating them with a pipe symbol |. For example, {{ product_price | money }} would display the price of a product formatted as currency. See a full list of filters.

Additional Resources

There is much more functionality that can be achieved so please review the Liquid Documentation for more resources.

Subscribe to our newsletter

The latest prompt engineering best practices and resources, sent to your inbox weekly.