Escape functions
Escape functions make values safe to embed in specific formats, such as queries, URLs, markup documents, and CSV rows.
ESCAPE THE VALUE, NOT THE WHOLE STRING
Escape each value before you insert it. Don't escape the completed string. Escaping the completed string can alter valid syntax, while skipping escaping can allow injection.
f"SELECT Id FROM Account WHERE Name = '{escape_for_soql(_.name)}'"The quotes form part of the query syntax. Escape only the value between them.
Query languages
Inbound data inserted directly into a query can introduce unintended syntax. The following functions escape values so the query engine treats them as data instead of code.
escape_for_soql
Escapes a value for a SOQL string literal in Salesforce. Escapes ' and \. Doesn't escape % and _ wildcards.
escape_for_soql(value)| Parameter | Description |
|---|---|
| value | The value to escape. Raises E100 for a List, Map, or Binary value. |
Escape an apostrophe for SOQL
The following example escapes an apostrophe for a SOQL string literal:
Formula
escape_for_soql("O'Brien")Output
O\'Brienescape_for_odata
Escapes a value for an OData filter string literal by doubling each single quote. OData expects a doubled quote instead of a backslash escape.
escape_for_odata(value)| Parameter | Description |
|---|---|
| value | The value to escape. |
Escape an apostrophe for OData
The following example escapes an apostrophe for an OData filter string literal:
Formula
escape_for_odata("O'Brien")Output
O''Brienescape_for_regex
Escapes regular-expression metacharacters so the pattern matches the string literally. Syntax characters get a preceding backslash, and punctuation becomes a \xHH escape.
escape_for_regex(value)| Parameter | Description |
|---|---|
| value | The value to escape. Raises E100 for a List, Map, or Binary value. |
Escape regex metacharacters
The following example escapes the regex metacharacters in a string:
Formula
escape_for_regex('a.b*c')Output
a\.b\*cMarkup
The following functions escape a value for HTML or XML markup:
escape_for_html
Escapes a value for HTML text or a quoted attribute value. Escapes &, <, >, ", ', and /.
The result isn't safe inside a <script> or <style> element, or inside an unquoted attribute. Use escape_for_javascript first, then escape_for_html for JavaScript in an event-handler attribute.
escape_for_html(value)| Parameter | Description |
|---|---|
| value | The value to escape. Raises E100 for a List, Map, or Binary value. |
Escape HTML markup characters
The following example escapes the markup characters in an HTML string:
Formula
escape_for_html('<b>Tom & Jerry</b>')Output
<b>Tom & Jerry</b>escape_for_xml
Escapes a value for XML text or an attribute, and strips code points that are illegal in XML 1.0.
Removing these code points prevents source-system control characters from producing XML that a parser can't process.
escape_for_xml(value)| Parameter | Description |
|---|---|
| value | The value to escape. |
Escape XML markup characters
The following example escapes the markup characters in an XML string:
Formula
escape_for_xml('<tag> & more')Output
<tag> & moreData formats
The following functions escape a value for a specific data or code format:
escape_for_csv
Escapes a value for a CSV field, following RFC 4180 by quoting the field and doubling internal quotes when needed.
Pass 'safe_formulas' to prevent CSV formula injection. Spreadsheet applications otherwise treat a field beginning with a tab, a carriage return, a line feed, a negative number, =, +, -, @, or a full-width equivalent as a formula, so a value from an untrusted source can run when someone opens the file. 'safe_formulas' prefixes potentially dangerous fields with an apostrophe (').
escape_for_csv(value, 'safe_formulas')| Parameter | Description |
|---|---|
| value | The value to escape. Raises E100 for a List, Map, or Binary value. |
| 'safe_formulas' | Optional. Pass this parameter to also neutralize leading formula characters. Raises E225 for an unrecognized mode. |
Quote a field containing a comma
The following example quotes a CSV field containing a comma:
Formula
escape_for_csv('Smith, Josh')Output
"Smith, Josh"Neutralize a leading formula character
The following example neutralizes a leading formula character with 'safe_formulas':
Formula
escape_for_csv('=1+1', 'safe_formulas')Output
"'=1+1"USE SAFE_FORMULAS FOR ANYTHING A PERSON OPENS
Pass 'safe_formulas' when a person opens the CSV in a spreadsheet application. This option isn't necessary for machine-to-machine processing that doesn't evaluate spreadsheet formulas.
escape_for_json_string
Escapes a value to embed inside a JSON string, without adding the surrounding quotes. It escapes only ", \, and control characters, leaving / and non-ASCII characters unchanged.
Use this when assembling JSON text by hand. Use to_json, which handles escaping throughout, to serialize a whole value instead.
escape_for_json_string(value)| Parameter | Description |
|---|---|
| value | The value to escape. Raises E100 for a List, Map, or Binary value. |
Escape a quote for a JSON string
The following example escapes a double quote for embedding inside a JSON string:
Formula
escape_for_json_string('He said "hi"')Output
He said \"hi\"escape_for_javascript
Escapes a value for use inside a single or double-quoted JavaScript string literal, without adding the quotes.
| Character | Result |
|---|---|
', ", \, / | Gains a preceding backslash |
<, > | \x3C, \x3E |
| Newline, CR, tab, backspace, form feed | Becomes \n, \r, \t, \b, \f |
U+2028, U+2029 | Becomes \u2028, \u2029 |
| Other control characters | Becomes \uXXXX |
Escaping < and > means the result can't close a <script> element. Backticks and ${ aren't escaped, so don't put the result in a template literal.
escape_for_javascript(value)| Parameter | Description |
|---|---|
| value | Any scalar value. A number, Boolean, temporal value, or null is first converted to text by the String rules, and null becomes 'null'. Raises E100 for a List, Map, or Binary value. |
Escape an apostrophe for JavaScript
The following example escapes an apostrophe for a JavaScript string literal:
Formula
escape_for_javascript("O'Brien")Output
O\'BrienURLs and query strings
These three related functions handle spaces differently. Choose the function that matches the required URL format:
| Function | Space becomes | Use for |
|---|---|---|
escape_for_url | %20 | A whole string, as defined in RFC 3986 |
uri_encode_www_form_component | %20 | One component of a URL |
uri_encode_www_form | + | A whole form-encoded query string |
escape_for_url
Percent-encodes a string as defined in RFC 3986.
escape_for_url(value)| Parameter | Description |
|---|---|
| value | The value to encode. |
Percent-encode a whole string
The following example percent-encodes a whole string as defined in RFC 3986:
Formula
escape_for_url('name=Kalani Park&x=1')Output
name%3DKalani%20Park%26x%3D1uri_encode_www_form_component
Percent-encodes a single URI component. Unreserved characters pass through unchanged.
uri_encode_www_form_component(value)| Parameter | Description |
|---|---|
| value | The component to encode. |
Percent-encode a single component
The following example percent-encodes a single URI component:
Formula
uri_encode_www_form_component('Kalani Park')Output
Kalani%20Parkuri_decode_www_form_component
Decodes a percent-encoded URI component. A + passes through unchanged rather than becoming a space.
uri_decode_www_form_component(value)| Parameter | Description |
|---|---|
| value | The component to decode. Malformed percent-encoding raises E226. |
Decode a percent-encoded component
The following example decodes a percent-encoded URI component:
Formula
uri_decode_www_form_component('Kalani%20Park')Output
Kalani Parkuri_encode_www_form
Encodes a Map as an application/x-www-form-urlencoded query string, with pairs joined by & in the map's order.
Keys and values use the WHATWG form rules: A space becomes +, ASCII letters, digits, and *, -, ., _ pass through unchanged, and every other byte becomes %XX. A String value is written as is. Any other scalar value is written in its canonical text form, so true becomes true, null becomes null, and a date becomes its ISO form.
uri_encode_www_form(map, options)| Parameter | Description |
|---|---|
| map | The map of parameters. A List value writes one pair for each item. An empty List raises E218. A Map, Binary, or nested List value raises E100. |
| options | Optional map specifying the dialect. 'whatwg' (default) repeats the key for each List item. 'rack' writes key[] for each item, and raises E218 for a key containing [ or ]. An unrecognized option key raises E225. An unrecognized dialect value raises E225. |
Encode a map as a query string
The following example encodes a map as a form-urlencoded query string:
Formula
uri_encode_www_form({status: 'open', q: 'blue widget'})Output
status=open&q=blue+widgeturi_decode_www_form
Decodes a query string into a Map. The function decodes + to a space, skips empty pairs, decodes a pair with no = sign to an empty value, and keeps a leading ? literally as part of the first key.
uri_decode_www_form(text, options)| Parameter | Description |
|---|---|
| text | The query string to decode. Malformed percent-encoding raises E226. |
| options | Optional map to control decoding.
E225. |
Decode a query string into a map
The following example decodes a form-urlencoded query string into a map:
Formula
uri_decode_www_form('status=open&q=blue+widget')Output
{status: "open", q: "blue widget"}Use case: Build a filtered API request
Search terms from inbound data can contain spaces and punctuation. Encode the parameters as a map instead of concatenating strings to escape each value and preserve the separators:
Input
{
"status": "open",
"search": "blue widget & more"
}Formula
f"/api/v2/orders?{uri_encode_www_form({status: _.status, q: _.search})}"Output
"/api/v2/orders?status=open&q=blue+widget+%26+more"uri_encode_www_form encodes the & inside the search term as %26 so it isn't mistaken for a parameter separator, and leaves the & that genuinely separates the two parameters untouched.
Related
- JSON functions: Use
to_jsonto serialize a whole value. - String functions: Regular-expression matching and replacement.
- Encoding functions: Character encodings, not escaping.
- Strings and formatting: More information about f-strings.
Last updated: