Skip to content

Expression Reference#

These are some commonly used expressions. A more exhaustive list appears below.

Category Expression Description
Access current input item data $json JSON data of the current item
$json.fieldName Field of the current item
$binary Binary data of current item
Access previous node data $("NodeName").first() First item in a node
$("NodeName").item Linked item of a node. See Item linking for more information.
$("NodeName").all() All items of a node
$("NodeName").last() Last item of a node
Date/Time $now Current date and time
$today Today's date
$now.toFormat("yyyy-MM-dd") Format current date as a string
Conditionals $if(condition, "true", "false") Helper function that returns a value when a condition is true or false
condition ? true : false Ternary operator: returns one value if a condition is true, another if false
$ifEmpty(value, defaultValue) Helper function takes two parameters and tests the first to check if it's empty, then returns either the parameter (if not empty) or the second parameter (if the first is empty). The first parameter is empty if it's undefined, null, an empty string '', an array where value.length returns false , or an object where Object.keys(value).length returns false
String Methods text.toUpperCase() Convert to uppercase
text.toLowerCase() Convert to lowercase
text.includes("foo") Check if text contains search term
text.extractEmail() Extract email from text
Array Methods array.length Get array length
array.join(", ") Join array elements using a comma a separator
array.filter(x => x <= 20) Filter items of array based on the filtering condition
array.map(x => x.id) Transform items of an array

Browse the tables below to find methods by the data type on which they act. Click a method name to read detailed documentation for it.

Array#

If you need all matching elements, use filter().

The opposite of split().

See also slice() and append().

  • Array.toString()

    Converts the array to a string, with values separated by commas. To use a different separator, use join() instead.

  • Array.union(otherArray)

    Concatenates two arrays and then removes any duplicates

  • Array.unique()

    Removes any duplicate elements from the array

BinaryFile#

  • binaryFile.directory

    The path to the directory that the file is stored in. Useful for distinguishing between files with the same name in different directories. Not set if n8n is configured to store files in its database.

  • binaryFile.fileExtension

    The suffix attached to the filename (e.g. txt)

  • binaryFile.fileName

    The name of the file, including extension

  • binaryFile.fileSize

    A string representing the size of the file

  • binaryFile.fileType

    A string representing the type of the file, e.g. image. Corresponds to the first part of the MIME type.

  • binaryFile.id

    The unique ID of the file. Used to identify the file when it is stored on disk or in a storage service such as S3.

  • binaryFile.mimeType

    A string representing the format of the file’s contents, e.g. image/jpeg

Boolean#

CustomData#

Date#

  • Date.toDateTime()

    Converts a JavaScript Date to a Luxon DateTime. The DateTime contains the same information, but is easier to manipulate.

DateTime#

  • DateTime.day

    The day of the month (1-31)

  • DateTime.diffTo(otherDateTime, unit)

    Returns the difference between two DateTimes, in the given unit(s)

  • DateTime.diffToNow(unit)

    Returns the difference between the current moment and the DateTime, in the given unit(s). For a textual representation, use toRelative() instead.

  • DateTime.endOf(unit, opts)

    Rounds the DateTime up to the end of one of its units, e.g. the end of the month

  • DateTime.equals(other)

    Returns true if the two DateTimes represent exactly the same moment and are in the same time zone. For a less strict comparison, use hasSame().

  • DateTime.extract(unit?)

    Extracts a part of the date or time, e.g. the month, as a number. To extract textual names instead, see format().

  • DateTime.format(fmt)

    Converts the DateTime to a string, using the format specified. Formatting guide. For common formats, toLocaleString() may be easier.

  • DateTime.hasSame(otherDateTime, unit)

    Returns true if the two DateTimes are the same, down to the unit specified. Time zones are ignored (only local times are compared), so use toUTC() first if needed.

  • DateTime.hour

    The hour of the day (0-23)

  • DateTime.isBetween(date1, date2)

    Returns true if the DateTime lies between the two moments specified

  • DateTime.isInDST

    Whether the DateTime is in daylight saving time

  • DateTime.locale

    The locale of a DateTime, such 'en-GB'. The locale is used when formatting the DateTime.

  • DateTime.millisecond

    The millisecond of the second (0-999)

  • DateTime.minus(n, unit?)

    Subtracts a given period of time from the DateTime

  • DateTime.minute

    The minute of the hour (0-59)

  • DateTime.month

    The month (1-12)

  • DateTime.monthLong

    The textual long month name, e.g. 'October'. Defaults to the system's locale if no locale has been specified.

  • DateTime.monthShort

    The textual abbreviated month name, e.g. 'Oct'. Defaults to the system's locale if no locale has been specified.

  • DateTime.plus(n, unit?)

    Adds a given period of time to the DateTime

  • DateTime.quarter

    The quarter of the year (1-4)

  • DateTime.second

    The second of the minute (0-59)

  • DateTime.set(values)

    Assigns new values to specified units of the DateTime. To round a DateTime, see also startOf() and endOf().

  • DateTime.setLocale(locale)

    Sets the locale, which determines the language and formatting for the DateTime. Useful when generating a textual representation of the DateTime, e.g. with format() or toLocaleString().

  • DateTime.setZone(zone, opts)

    Converts the DateTime to the given time zone. The DateTime still represents the same moment unless specified in the options. See also toLocal() and toUTC().

  • DateTime.startOf(unit, opts)

    Rounds the DateTime down to the beginning of one of its units, e.g. the start of the month

  • DateTime.toISO(opts)

    Returns an ISO 8601-compliant string representation of the DateTime

  • DateTime.toLocal()

    Converts a DateTime to the workflow’s local time zone. The DateTime still represents the same moment unless specified in the parameters. The workflow’s time zone can be set in the workflow settings.

  • DateTime.toLocaleString(formatOpts)

    Returns a localised string representing the DateTime, i.e. in the language and format corresponding to its locale. Defaults to the system's locale if none specified.

  • DateTime.toMillis()

    Returns a Unix timestamp in milliseconds (the number elapsed since 1st Jan 1970)

  • DateTime.toRelative(options)

    Returns a textual representation of the time relative to now, e.g. ‘in two days’. Rounds down by default.

  • DateTime.toSeconds()

    Returns a Unix timestamp in seconds (the number elapsed since 1st Jan 1970)

  • DateTime.toString()

    Returns a string representation of the DateTime. Similar to toISO(). For more formatting options, see format() or toLocaleString().

  • DateTime.toUTC(offset, opts)

    Converts a DateTime to the UTC time zone. The DateTime still represents the same moment unless specified in the parameters. Use setZone() to convert to other zones.

  • DateTime.weekday

    The day of the week. 1 is Monday and 7 is Sunday.

  • DateTime.weekdayLong

    The textual long weekday name, e.g. 'Wednesday'. Defaults to the system's locale if no locale has been specified.

  • DateTime.weekdayShort

    The textual abbreviated weekday name, e.g. 'Wed'. Defaults to the system's locale if no locale has been specified.

  • DateTime.weekNumber

    The week number of the year (1-52ish)

  • DateTime.year

    The year

  • DateTime.zone

    The time zone associated with the DateTime

ExecData#

  • $exec.customData

    Set and get custom execution data (e.g. to filter executions by). You can also do this with the ‘Execution Data’ node. More info

  • $exec.id

    The ID of the current workflow execution

  • $exec.mode

    Can be one of 3 values: either test (meaning the execution was triggered by clicking a button in n8n) or production (meaning the execution was triggered automatically). When running workflow tests, evaluation is used.

  • $exec.resumeFormUrl

    The URL to access a form generated by the ’Wait’ node.

  • $exec.resumeUrl

    The webhook URL to call to resume a workflow waiting at a ’Wait’ node.

HTTPResponse#

  • $response.body

    The body of the response object from the last HTTP call. Only available in the ‘HTTP Request’ node

  • $response.headers

    The headers returned by the last HTTP call. Only available in the ‘HTTP Request’ node.

  • $response.statusCode

    The HTTP status code returned by the last HTTP call. Only available in the ‘HTTP Request’ node.

  • $response.statusMessage

    An optional message regarding the request status. Only available in the ‘HTTP Request’ node.

Item#

NodeInputData#

NodeOutputData#

Number#

  • Number.abs()

    Returns the number’s absolute value, i.e. removes any minus sign

  • Number.ceil()

    Rounds the number up to the next whole number

  • Number.floor()

    Rounds the number down to the nearest whole number

  • Number.format(locale?, options?)

    Returns a formatted string representing the number. Useful for formatting for a specific language or currency. The same as Intl.NumberFormat().

  • Number.isEmpty()

    Returns false for all numbers. Returns true for null.

  • Number.isEven()

    Returns true if the number is even. Throws an error if the number isn’t a whole number.

  • Number.isInteger()

    Returns true if the number is a whole number

  • Number.isOdd()

    Returns true if the number is odd. Throws an error if the number isn’t a whole number.

  • Number.round(decimalPlaces?)

    Returns the number rounded to the nearest whole number (or specified number of decimal places)

  • Number.toBoolean()

    Converts the number to a boolean value. 0 becomes false; everything else becomes true.

  • Number.toDateTime(format?)

    Converts a numerical timestamp into a DateTime. The format of the timestamp must be specified if it’s not in milliseconds. Uses the time zone in n8n (or in the workflow’s settings).

  • Number.toLocaleString(locales?, options?)

    Returns a localised string representing the number, i.e. in the language and format corresponding to its locale. Defaults to the system's locale if none specified.

  • Number.toString(radix?)

    Converts the number to a simple textual representation. For more formatting options, see toLocaleString().

Object#

  • Object.compact()

    Removes all fields that have empty values, i.e. are null or ""

  • Object.hasField(name)

    Returns true if there is a field called name. Only checks top-level keys. Comparison is case-sensitive.

  • Object.isEmpty()

    Returns true if the Object has no keys (fields) set or is null

  • Object.isNotEmpty()

    Returns true if the Object has at least one key (field) set

  • Object.keepFieldsContaining(value)

    Removes any fields whose values don’t at least partly match the given value. Comparison is case-sensitive. Fields that aren’t strings will always be removed.

  • Object.keys()

    Returns an array with all the field names (keys) the object contains. The same as JavaScript’s Object.keys(obj).

  • Object.merge(otherObject)

    Merges the two Objects into a single one. If a key (field name) exists in both Objects, the value from the first (base) Object is used.

  • Object.removeField(key)

    Removes a field from the Object. The same as JavaScript’s delete.

  • Object.removeFieldsContaining(value)

    Removes keys (fields) whose values at least partly match the given value. Comparison is case-sensitive. Fields that aren’t strings are always kept.

  • Object.toJsonString()

    Converts the Object to a JSON string. Similar to JavaScript’s JSON.stringify().

  • Object.urlEncode()

    Generates a URL parameter string from the Object’s keys and values. Only top-level keys are supported.

  • Object.values()

    Returns an array with all the values of the fields the Object contains. The same as JavaScript’s Object.values(obj).

PrevNodeData#

  • name

    The name of the node that the current input came from.

Always uses the current node’s first input connector if there is more than one (e.g. in the ‘Merge’ node).

  • outputIndex

    The index of the output connector that the current input came from. Use this when the previous node had multiple outputs (such as an ‘If’ or ‘Switch’ node).

Always uses the current node’s first input connector if there is more than one (e.g. in the ‘Merge’ node).

  • runIndex

    The run of the previous node that generated the current input.

Always uses the current node’s first input connector if there is more than one (e.g. in the ‘Merge’ node).

Root#

  • $(nodeName)

    Returns the data of the specified node

  • $binary

    Returns any binary input data to the current node, for the current item. Shorthand for $input.item.binary.

  • $execution

    Retrieve or set metadata for the current execution

  • $fromAI(key, description?, type?, defaultValue?)

    Use when a large language model should provide the value of a node parameter. Consider providing a description for better results.

  • $if(condition, valueIfTrue, valueIfFalse)

    Returns one of two values depending on the condition. Similar to the ? operator in JavaScript.

  • $ifEmpty(value, valueIfEmpty)

    Returns the first parameter if it isn’t empty, otherwise returns the second parameter. The following count as empty: ””, [], {}, null, undefined

  • $input

    The input data of the current node

  • $itemIndex

    The position of the item currently being processed in the list of input items

  • $jmespath(obj, expression)

    Extracts data from an object (or array of objects) using a JMESPath expression. Useful for querying complex, nested objects. Returns undefined if the expression is invalid.

  • $json

    Returns the JSON input data to the current node, for the current item. Shorthand for $input.item.json. More info

  • $max(num1, num2, …, numN)

    Returns the highest of the given numbers

  • $min(num1, num2, …, numN)

    Returns the lowest of the given numbers

  • $nodeVersion

    The version of the current node (as displayed at the bottom of the nodes’s settings pane)

  • $now

    A DateTime representing the current moment.

Uses the workflow’s time zone (which can be changed in the workflow settings).

  • $pageCount

    The number of results pages the node has fetched. Only available in the ‘HTTP Request’ node.

  • $parameter

    The configuration settings of the current node. These are the parameters you fill out within the node’s UI (e.g. its operation).

  • $prevNode

    Information about the node that the current input came from.

When in a ‘Merge’ node, always uses the first input connector.

  • $request

    The request object sent during the last run of the node. Only available in the ‘HTTP Request’ node.

  • $response

    The response returned by the last HTTP call. Only available in the ‘HTTP Request’ node.

  • $runIndex

    The index of the current run of the current node execution. Starts at 0.

  • $secrets

    The secrets from an external secrets vault, if configured. Secret values are never displayed to the user. Only available in credential fields.

  • $today

    A DateTime representing midnight at the start of the current day.

Uses the instance’s time zone (unless overridden in the workflow’s settings).

String#

If the string also contains other content, try using extractEmail() or extractUrl() first.

  • String.extractEmail()

    Extracts the first email found in the string. Returns undefined if none is found.

  • String.extractUrl()

    Extracts the first URL found in the string. Returns undefined if none is found. Only recognizes full URLs, e.g. those starting with http.

  • String.extractUrlPath()

    Returns the part of a URL after the domain, or undefined if no URL found.

If the string also contains other content, try using extractUrl() first.

For checking whether text is present, consider includes() instead.

  • String.parseJson()

    Returns the JavaScript Object or value represented by the string, or undefined if the string isn’t valid JSON. Single-quoted JSON is not supported.

  • String.quote(mark?)

    Wraps a string in quotation marks, and escapes any quotation marks already in the string. Useful when constructing JSON, SQL, etc.

  • String.removeMarkdown()

    Removes any Markdown formatting from the string. Also removes HTML tags.

  • String.removeTags()

    Removes tags, such as HTML or XML, from the string

  • String.replace(pattern, replacement)

    Returns a string with the first occurrence of pattern replaced by replacement.

To replace all occurrences, use replaceAll() instead.

The opposite of using join() on an array.

  • String.startsWith(searchString, start?)

    Returns true if the string starts with searchString. Case-sensitive.

  • String.substring(start, end?)

    Extracts a fragment of the string at the given position. For more advanced extraction, see match().

  • String.toBoolean()

    Converts the string to a boolean value. 0, false and no resolve to false, everything else to true. Case-insensitive.

  • String.toDateTime()

    Converts the string to a DateTime. Useful for further transformation. Supported formats for the string are ISO 8601, HTTP, RFC2822, SQL and Unix timestamp in milliseconds.

To parse other formats, use DateTime.fromFormat().

  • String.toJsonString()

    Prepares the string to be inserted into a JSON object. Escapes any quotes and special characters (e.g. new lines), and wraps the string in quotes.

The same as JavaScript’s JSON.stringify().

  • String.toLowerCase()

    Converts all letters in the string to lower case

  • String.toNumber()

    Converts a string representing a number to a number. Throws an error if the string doesn’t start with a valid number.

  • String.toSentenceCase()

    Changes the capitalization of the string to sentence case. The first letter of each sentence is capitalized and all others are lowercased.

  • String.toSnakeCase()

    Changes the format of the string to snake case. Spaces and dashes are replaced by _, symbols are removed and all letters are lowercased.

  • String.toTitleCase()

    Changes the capitalization of the string to title case. The first letter of each word is capitalized and the others left unchanged. Short prepositions and conjunctions aren’t capitalized (e.g. ‘a’, ‘the’).

  • String.toUpperCase()

    Converts all letters in the string to upper case (capitals)

  • String.trim()

    Removes whitespace from both ends of the string. Whitespace includes new lines, tabs, spaces, etc.

  • String.urlDecode(allChars?)

    Decodes a URL-encoded string. Replaces any character codes in the form of %XX with their corresponding characters.

  • String.urlEncode(allChars?)

    Encodes the string so that it can be used in a URL. Spaces and special characters are replaced with codes of the form %XX.

WorkflowData#

This page was