Recode Syntax: Write Recode Rules as Text

Clicking through Rule Builder is great for a handful of rules. When you’ve got twenty bands to set up, or you want to copy a Recode from one data store to another, typing is faster. The Syntax tab shows your whole Recode as a few lines of text that you can read, edit, copy and paste.

It’s the same Recode either way. Whatever you write in Syntax shows up in Rule Builder, and the other way around.

When to use this

Use Syntax for long lists of rules, for copying a Recode into another data store, or for the few options that only Syntax offers, like copying the source value in Else. For your first few Recodes, start in Rule Builder and peek at Syntax to see how it’s written.

Permission Requirements

You need to be the data store’s Owner or have Can Edit access. See Recode variables.

---

Open the Syntax tab

1. Start or reopen a Recode - See Start a Recode. Choose the source on Source & output, then click NEXT.

2. Click Syntax - It’s next to Rule Builder on the Build rules step. Your Recode is already written out, including any rules you’ve added.

3. Edit the text - When the text is valid, Rule Builder and the preview panels update to match. If something’s wrong, you’ll see a list under “Fix Syntax errors before finishing:”. Each error starts with where it is, for example: “Line 4, column 1: Expected “WHEN”, “ELSE”, or “END”.”

4. Click DONE - Or RUN AGAIN if you’re reopening a Recode. You can’t finish while Syntax has errors.

Leaving with errors discards your edits

If you switch back to Rule Builder while Syntax has errors, you’ll see “Syntax has errors. Leaving will discard the unparseable edits.” Click Keep editing to fix them, or Discard edits to go back to the last version that worked.

---

Understanding the format

Here’s an NPS Recode written out:

RECODE VERSION 1
SOURCE @nps
OUTPUT CATEGORICAL @nps_group LABEL "NPS group" MEASURE NOMINAL
WHEN BETWEEN 0 AND 6 THEN CODE 1 LABEL "Detractor"
WHEN BETWEEN 7 AND 8 THEN CODE 2 LABEL "Passive"
WHEN BETWEEN 9 AND 10 THEN CODE 3 LABEL "Promoter"
ELSE SYSTEM_MISSING
END

Every Recode has the same lines, in the same order:

Line	What it says
RECODE VERSION 1	Always the first line, exactly as shown
SOURCE @name	The source variable. It must be the one you chose on Source & output.
OUTPUT … @name LABEL "…" MEASURE …	The output’s type, New Variable Name, Variable Label and measure. See The OUTPUT line.
WHEN … THEN …	One line per rule, top to bottom. The first rule a record matches wins.
ELSE …	Exactly one, after all the rules. See ELSE.
END	Always the last line, with nothing after it

Writing rules for the format

The format is strict, so a few habits keep it happy:

• Write keywords in capitals: WHEN, THEN, BETWEEN and so on.
• Put one space between each part, and start every line at the left edge, with no indent.
• Don’t leave blank lines, and don’t add anything after END.
• Put text in double quotes, like "Detractor". For a double quote inside the text, use \".
• Variable names start with @. Type @ and the editor suggests the variables you can use.
• The editor also suggests keywords as you type. If a suggestion is showing when you press Enter, Enter accepts it instead of starting a new line, so check the line before you move on.

---

The OUTPUT line

OUTPUT CATEGORICAL @nps_group LABEL "NPS group" MEASURE NOMINAL

Part	Options
Type	CATEGORICAL, NUMERIC or TEXT, matching Variable Type
Name	@ and the New Variable Name
LABEL	The Variable Label, in quotes
MEASURE	SCALE for NUMERIC. NOMINAL for CATEGORICAL and TEXT.

Changing the type here is the same as changing Variable Type: your rules have to match the new type. When you reopen a Recode, the type and name are locked, but you can still change the label.

---

Conditions

The part between WHEN and THEN is the condition.

Syntax	Matches	Same as in Rule Builder
EQUAL 5	Exactly 5	Equal
NOT_EQUAL 5	Anything except 5 (blanks don’t match)	Not Equal
IN (1, 2, 3)	Any of the listed values	In
IN (7, 8, SYSTEM_MISSING)	7, 8 or blank	In with Include system-missing in this bucket ticked
IS_MISSING	Blank values	Is Missing
IS_NOT_MISSING	Anything that isn’t blank	Is Not Missing
LESS_THAN 5, LESS_THAN_OR_EQUAL 5	Below 5, or 5 and below	Less Than, Less Than or Equal
GREATER_THAN 5, GREATER_THAN_OR_EQUAL 5	Above 5, or 5 and above	Greater Than, Greater Than or Equal
BETWEEN 0 AND 6	0 to 6, including both	Between

Values can be:

• numbers, like 5 or 2.5
• text in quotes, like "Yes"
• TRUE or FALSE, for Boolean sources
• SYSTEM_MISSING, for blank

The comparison operators and BETWEEN only work on Integer and Number sources, the same as in Rule Builder.

---

Results

The part after THEN depends on the output type.

Output type	Syntax	Example
CATEGORICAL	CODE (a whole number) and LABEL	THEN CODE 1 LABEL "Detractor"
NUMERIC	VALUE, with an optional DESCRIPTION	THEN VALUE -100 DESCRIPTION "Detractor"
TEXT	TEXT, with an optional DESCRIPTION	THEN TEXT "Unhappy customer in @region"

In a TEXT result, @name inside the quotes is replaced by that variable’s value for each record. Blank values become empty text. You can’t use variables whose personal information is set to Mask, Mask + retention or Wipe.

DESCRIPTION on a TEXT result can only be set in Syntax. There’s no field for it in Rule Builder.

---

ELSE

The ELSE line sets the result for records that match no rule. The options depend on the output type:

Output type	Options
CATEGORICAL	SYSTEM_MISSING (blank), or CODE 9 LABEL "Other"
NUMERIC	SYSTEM_MISSING (blank), VALUE 0, or COPY_SOURCE
TEXT	EMPTY_STRING (empty text), SYSTEM_MISSING (blank), or TEXT "Other"

COPY_SOURCE keeps each unmatched record’s original value. It needs an Integer or Number source, and it’s only available in Syntax.

---

Examples

Score answers for averaging

Turn a 1–5 agreement scale into points, keeping anything else as it was:

RECODE VERSION 1
SOURCE @q7
OUTPUT NUMERIC @q7_score LABEL "Q7 score" MEASURE SCALE
WHEN IN (1, 2) THEN VALUE -1 DESCRIPTION "Disagree"
WHEN EQUAL 3 THEN VALUE 0 DESCRIPTION "Neutral"
WHEN IN (4, 5) THEN VALUE 1 DESCRIPTION "Agree"
ELSE COPY_SOURCE
END

Turn text answers into codes

Group a free-text Yes/No field into codes, catching blanks separately:

RECODE VERSION 1
SOURCE @consent
OUTPUT CATEGORICAL @consent_code LABEL "Consent" MEASURE NOMINAL
WHEN IN ("Yes", "Y") THEN CODE 1 LABEL "Yes"
WHEN IN ("No", "N") THEN CODE 2 LABEL "No"
WHEN IS_MISSING THEN CODE 99 LABEL "Not answered"
ELSE CODE 9 LABEL "Other"
END

---

Frequently Asked Questions

Is this the same as Survey Shaper syntax?

No. Recode syntax is its own format, used only for Recode in Data Wrangler.

Can I copy a Recode to another data store?

Yes. Copy the text from Syntax, start a Recode on the other data store with a source of the same name, and paste it into Syntax. If the source has a different name, change the SOURCE line to match.

Can I write a rule with two conditions?

No. Each WHEN line takes one condition. To catch several values in one rule, use IN.

Can I add comments or blank lines?

No. Every line has to be one of the lines in Understanding the format, so comments and blank lines show as errors.

Do keywords have to be in capitals?

Yes. WHEN works, when doesn’t. Variable names after @ aren’t case sensitive in SOURCE, though.

Why did my changes disappear when I switched tabs?

Syntax had errors, and you chose Discard edits. Only text without errors carries over to Rule Builder.

What’s COPY_SOURCE for?

It keeps the original value for records that match no rule, so you can change a few values and leave the rest alone. It only works for NUMERIC output from an Integer or Number source.

Can I change the source in Syntax?

No. The SOURCE line has to match the variable you chose on Source & output. To use a different source, click BACK and change it there.

---

Common Issues and Solutions

”Line …, column …: Expected “WHEN”, “ELSE”, or “END”.”

A line between OUTPUT and END doesn’t start with WHEN or ELSE.

1. Go to the line in the message - Look for a blank line, an indent, a lowercase keyword, or a typo there.
2. Fix or remove it - Every rule starts with WHEN, at the left edge.

”Line 2, column 8: Syntax must use the selected source @….”

The SOURCE line names a different variable from the one you chose.

1. Fix the SOURCE line - Line 2 must name the variable shown in the message.
2. Or change the source - Click BACK and choose a different source on Source & output.

”Line …, column …: Categorical rules require CODE <integer> LABEL “text”.”

A rule’s result doesn’t match the output type. Each type has its own message, for example “Numeric rules require VALUE <number> and an optional DESCRIPTION “text”.”

1. Check the OUTPUT line - Line 3 sets the type. Make sure it’s the one you want.
2. Fix the result - Go to the line in the message, and write the part after THEN the way Results shows for that type.

”Line …, column …: Expected a number, quoted string, TRUE, FALSE, or SYSTEM_MISSING.”

A value in a condition isn’t written in a way the format understands.

1. Go to the value in the message - The column number points to it.
2. Quote text values - Write "Yes", not Yes.
3. Check numbers - Use a dot for decimals, like 2.5, with no thousands separators.