PicoBot/skills/lark-base/references/formula-field-guide.md

Base Formula Writing Guide

Mandatory Read Acknowledgement

When creating or updating a formula field with lark-cli base +field-create/+field-update --json ... and type is formula, you should read this guide first and only then add --i-have-read-guide to the command.

Do not proactively add --i-have-read-guide before reading this guide. Without it, the CLI will fail fast and direct you back to this guide.

When using +field-update, also pass --yes: field update is a high-risk PUT operation because changing a field definition can affect the whole column.

Default strategy

All cross-table references, aggregations, and computed fields should use Formula fields by default. Do NOT use Lookup fields unless the user explicitly requests it. Formula is a strict superset of Lookup — anything Lookup can do, Formula can do with a single expression.

Usage

When creating a formula field, the Agent should:

1. Get all table names: lark-cli base +table-list --base-token <base> — returns items[].table_name
2. Get table structure: lark-cli base +table-get --base-token <base> --table-id <table> — returns fields[]
3. If the formula references other tables, also get those tables' structures
4. Write the formula expression following this guide
5. Construct the Formula field JSON and submit it to create or update the field

Key constraints:

• The JSON must include "type": "formula" — this field is required
• Table names and field names in the formula must exactly match those returned by +table-list / +table-get
• The expression value is a string containing the formula expression; double quotes inside the expression must be properly escaped in JSON (e.g. \"text\")

---

Section 1: Core Concepts — Scalar vs List

This is the foundation of formula logic. You must determine this before writing any formula.

Syntax	Meaning	Return type	Example
[Field]	Value of this field in the current row	Scalar (single value)	[Name] → "Alice"
[TableName].[Field]	All values of this field in the target table	List (multiple values)	[Employees].[Name] → ["Alice","Bob",...]
[TableName]	The target table (entire table)	Table reference	Used as data range for FILTER/COUNTIF etc.

Rules:

• Scalars can be used directly in operations: [Price] * [Quantity]

• Lists cannot be used as scalars — they must be processed first: use SUM() for sum, ARRAYJOIN(",") for joining, FIRST()/LAST()/NTH() for single value extraction

• Link field access [LinkField].[TargetField] returns a list (values of the target field for all linked records)

• LISTCOMBINE flattening rule: When a FILTER's result column is itself a multi-value field (select with multiple=true, link, etc.), it produces a 2D array and must be flattened with .LISTCOMBINE(); for single-value fields (number, text, etc.) it can be omitted, but adding it is never wrong:

  [Table].FILTER(CurrentValue.[Field] = [Value]).[Tags].LISTCOMBINE() ← required for multi-value columns
  [Table].FILTER(CurrentValue.[Field] = [Value]).[NumberCol].LISTCOMBINE() ← optional for single-value columns
  

---

Section 2: Data Types and Type Conversion

Field storage types

Type	Description	Supported operations
number	Stored as numeric value	Math operations, comparisons, auto-converts to string for concatenation
text	Stored as string	String operations; can participate in math if content is numeric, otherwise errors
datetime	Date object	Date functions, add/subtract with numbers; auto-converts to default format string when using & — use TEXT to format first for controlled output
select (multiple=true)	Data list	List functions, CONTAIN checks
link	Links to other table records	Chained access [LinkField].[Field], result is a list
checkbox	TRUE/FALSE	Logical operations; auto-converts to number when compared with numbers

Implicit type conversion

Scenario	Conversion rule
Number + Float	→ Float
Date + Number	→ Date (adds/subtracts days). Use +/- for whole days, use DURATION() for hour/minute/second precision
Date - Date	→ Duration
Boolean compared with Number	Boolean auto-converts to number (TRUE=1, FALSE=0)
& concatenation	Both sides auto-convert to string

Type consistency in comparisons

When using comparison operators (>, >=, <, <=, =, !=), both sides should be the same type to avoid semantic errors or unexpected results.

Principle: When types differ, explicitly convert one side rather than relying on implicit conversion:

• number vs text → use VALUE() to convert text to number
• datetime vs text → use TEXT() to convert date to text
• datetime vs datetime equality → dates include time components, so direct = comparison may fail due to different hours/minutes/seconds. For day-level equality, convert to text first: TEXT([DateA], "YYYY/MM/DD") = TEXT([DateB], "YYYY/MM/DD")
• select and user fields can be compared with both same-type values and text
• text fields in numeric aggregation (SUM/AVERAGE/MIN/MAX etc.) → convert to number with VALUE() first. For FILTER results, use .MAP(VALUE(CurrentValue)).SUM()

---

Section 3: CurrentValue

CurrentValue is the iteration variable in FILTER/MAP/COUNTIF/SUMIF functions, representing the "current item" being processed in the data range.

CurrentValue meaning in different contexts

Data range type	CurrentValue represents	Access pattern	Example
Entire table [TableName]	A row in the table	CurrentValue.[FieldName]	[Orders].FILTER(CurrentValue.[Amount] > 100).[Customer]
Column [TableName].[Field]	A single field value	Use CurrentValue directly	[Orders].[Amount].FILTER(CurrentValue > 100)
select (multiple=true) field [Tags]	One option	Use CurrentValue directly	[Tags].FILTER(CurrentValue = "Important")
LIST-generated list	One element	Use CurrentValue directly	LIST(1,2,3).MAP(CurrentValue * 2)

Key rules

1. When data range is a table, use CurrentValue.[FieldName] to access row fields
2. When data range is a column/list, use CurrentValue directly for the element value — cannot use CurrentValue.[FieldName]
3. CurrentValue can only appear inside the condition/mapping parameters of FILTER/MAP/COUNTIF/SUMIF functions
4. To reference the current table's field value in a condition, write [FieldName] directly — it refers to the formula row's value, not a property of CurrentValue

Anti-patterns

Wrong	Reason	Correct
[Table].[Col].FILTER(CurrentValue.[Col] > 0)	Data range is a column; CurrentValue is a scalar, cannot use . to access fields	[Table].[Col].FILTER(CurrentValue > 0)
[Table].FILTER(CurrentValue > 100)	Data range is a table; CurrentValue is a row, cannot compare directly	[Table].FILTER(CurrentValue.[Amount] > 100).[Amount]
CurrentValue + 1 (at top level)	CurrentValue can only be used inside iteration functions	Use inside MAP/FILTER etc.

---

Section 4: Operators

Base formulas only allow the following operators. like, in, <>, **, ^ etc. are prohibited.

Category	Operators	Description
Arithmetic	+ - * / %	Add, subtract, multiply, divide, modulo (% is equivalent to MOD())
Comparison	> >= < <= = !=	Greater than, greater or equal, less than, less or equal, equal, not equal
Logical	&& ||	AND, OR
Concatenation	&	Text concatenation; non-text values auto-convert to string

Important:

• Equality uses = (single equals), not ==
• Not-equal uses !=, not <>
• String concatenation uses &, not +
• Both &&/|| and AND()/OR() functions are supported

---

Section 5: Link Fields and Cross-Table References

Link field description

When a field type is described as FieldName: Link [target table: X, foreign key: Y], it links to target table X using field Y as the join key.

Chained cross-table access

[LinkField].[TargetField]

Retrieves the target field values for all linked records as a list. Supports continued chaining: [LinkA].[LinkB].[Field].

Equivalent expanded form

• Multi-value link: [TargetTableX].FILTER([LinkField].CONTAIN(CurrentValue.[Y])).[TargetField].LISTCOMBINE()
• Single-value link: [TargetTableX].FILTER(CurrentValue.[Y] = [LinkField]).[TargetField].LISTCOMBINE()

(.LISTCOMBINE() is required when [TargetField] is a multi-value field; optional for single-value fields)

Notes

• Link fields typically return lists (possibly empty)
• To output a single value, use aggregation (SUM/MAX), joining (ARRAYJOIN), or extraction (FIRST/LAST/NTH)
• Do not nest FILTER inside FILTER for cross-table queries — prefer link field chained access

---

Section 6: Function Call Conventions

Two calling styles

Style	Format	Description
Functional	FUNC(arg1, arg2)	Works for all functions
Chained	arg1.FUNC(arg2)	Moves the first argument before .

Rules:

• Zero-argument functions cannot be chained: NOW(), TODAY(), PI(), TRUE(), FALSE()
• SORTBY can only be chained: [Table].SORTBY([Table].[SortCol]).[OutputCol]. The sort column always uses the original table's column name ([TableName].[Field] format); the engine aligns rows internally, even when the data range is a FILTER result
• FILTER is recommended to be chained: [Table].FILTER(condition).[OutputCol]

FILTER / SORTBY result column rules

• When data range is a table [TableName], FILTER / SORTBY returns a table reference. The chain must end with .[Field] to specify the result column, otherwise the formula fails:

  Correct: [Sales].FILTER(CurrentValue.[Amount] > 100).[Customer]
  Correct: [Sales].FILTER(condition).SORTBY([Sales].[SortCol]).[Customer]  ← result column at end of chain
  Wrong: [Sales].FILTER(CurrentValue.[Amount] > 100) ← missing result column
  

• When data range is a column [TableName].[Field] or a list, FILTER returns the filtered list directly — no result column needed:

  Correct: [Sales].[Amount].FILTER(CurrentValue > 100)
  

After the result column, it's recommended to flatten with .LISTCOMBINE() first (especially when the result column is a multi-value field), then chain aggregation functions:

[Sales].FILTER(CurrentValue.[Amount] > 100).[Amount].LISTCOMBINE().SUM()

---

Section 7: Hard Constraints

1. Nesting prohibition: FILTER / SUMIF / COUNTIF / MAP must not be nested inside each other's condition/mapping expressions. None of these functions can appear inside the condition or mapping parameter of another.

   • Prohibited: [Table1].FILTER(CurrentValue.[Col] = [Table2].FILTER(...).[Col]) ← FILTER inside FILTER condition
   • Prohibited: [Table].MAP([Table2].MAP(...)) ← MAP inside MAP mapping
   • Allowed: [Table].FILTER(cond1).[Col].FILTER(cond2) ← chained call; the first FILTER's output is the second's data range, not nesting

2. Function whitelist: Only use functions listed in Section 8. No unlisted functions.

3. Exact name matching: Table names and field names in formulas must exactly match those returned by +table-get — no renaming or adding spaces.

4. Operator whitelist: Only use operators listed in Section 4.

5. Strings use double quotes: Strings must be wrapped in double quotes ", single quotes are not supported.

6. Do not use LOOKUP: FILTER is a superset of LOOKUP. All LOOKUP formulas can be rewritten with FILTER. Use FILTER exclusively to reduce complexity.

---

Section 8: Complete Function Reference

8.1 Logic functions

Function	Signature	Return type	Description
IF	IF(condition, true_val, [false_val])	Matches branch type	Returns true_val when TRUE, false_val otherwise; omitting false_val returns false (not null)
IFS	IFS(cond1, val1, cond2, val2, ...)	Matches branch type	Multi-condition branching; returns value for the first TRUE condition
SWITCH	SWITCH(expr, match1, result1, [match2, result2, ...], [default])	Matches branch type	Matches expression value and returns corresponding result
IFERROR	IFERROR(expr, fallback)	Matches branch type	Returns fallback when expression errors
IFBLANK	IFBLANK(expr, fallback)	Matches branch type	Returns fallback when expression is blank (blank = NULL/empty string/empty list)
AND	AND(cond1, cond2, ...)	Boolean	TRUE when all conditions are TRUE
OR	OR(cond1, cond2, ...)	Boolean	TRUE when any condition is TRUE
NOT	NOT(condition)	Boolean	Logical negation
ISBLANK	ISBLANK(value)	Boolean	Tests if blank (NULL/empty string/empty list are blank; 0 and FALSE are not)
ISNULL	ISNULL(value)	Boolean	Tests if NULL (only NULL is true; empty string is not)
ISERROR	ISERROR(expr)	Boolean	Tests if expression errors
ISNUMBER	ISNUMBER(value)	Boolean	Tests if value is a number
CONTAIN	CONTAIN(search_range, value, ...)	Boolean	Tests if a list or select (multiple=true) contains the value; does NOT do text substring matching
CONTAINSALL	CONTAINSALL(search_range, value, ...)	Boolean	Tests if a list or select (multiple=true) contains all specified values
CONTAINSONLY	CONTAINSONLY(search_range, value, ...)	Boolean	Tests if a list or select (multiple=true) contains only the specified values
TRUE	TRUE()	Boolean	Returns TRUE
FALSE	FALSE()	Boolean	Returns FALSE
RECORD_ID	RECORD_ID()	Text	Returns the current row's record ID
RANDOMBETWEEN	RANDOMBETWEEN(min_int, max_int, [keep_updating])	Number	Random integer in the specified range
RANDOMITEM	RANDOMITEM(list, [keep_updating])	Matches element type	Randomly picks one element from a list

8.2 Numeric functions

Function	Signature	Return type	Description
SUM	SUM(val1, val2, ...)	Number	Sum; accepts multiple values or a list
AVERAGE	AVERAGE(val1, val2, ...)	Number	Average
MAX	MAX(val1, val2, ...)	Number	Maximum
MIN	MIN(val1, val2, ...)	Number	Minimum
MEDIAN	MEDIAN(val1, val2, ...)	Number	Median
COUNTA	COUNTA(val1, val2, ...)	Number	Count of non-blank values
COUNTIF	COUNTIF(data_range, condition)	Number	Count matching items. Data range can be a table (CurrentValue is a row, use CurrentValue.[Field]) or a column (CurrentValue is a scalar value)
SUMIF	SUMIF(data_range, condition)	Number	Sum matching values. Data range must be a numeric column (e.g. [Table].[NumField]); CurrentValue is each value in that column (scalar), cannot use CurrentValue.[Field] to access other fields. For cross-field conditions, use FILTER+SUM instead
ROUND	ROUND(number, digits)	Number	Round. digits: 1=one decimal, 0=integer, -1=tens place
ROUNDUP	ROUNDUP(number, digits)	Number	Round away from zero. Same digits semantics as ROUND
ROUNDDOWN	ROUNDDOWN(number, digits)	Number	Round toward zero. Same digits semantics as ROUND
FLOOR	FLOOR(number, [base])	Number	Round down to nearest multiple of base (default 1)
CEILING	CEILING(number, [base])	Number	Round up to nearest multiple of base (default 1)
ABS	ABS(number)	Number	Absolute value
INT	INT(number)	Integer	Truncate to integer
MOD	MOD(dividend, divisor)	Number	Modulo
POWER	POWER(base, exponent)	Number	Exponentiation
QUOTIENT	QUOTIENT(dividend, divisor)	Number	Integer division
VALUE	VALUE(text)	Number	Convert text to number
ISODD	ISODD(number)	Boolean	Tests if number is odd
RANK	RANK(value, search_range, [ascending])	Number	Rank of value in range; default descending
SEQUENCE	SEQUENCE(start, end, [step])	List	Generate number sequence
PI	PI()	Number	Pi constant
SIN/COS/TAN/ASIN/ACOS/ATAN/ATAN2/SINH/COSH/TANH/ASINH/ACOSH/ATANH	func(radians_or_value)	Number	Trigonometric and hyperbolic functions; arguments in radians

8.3 Text functions

Function	Signature	Return type	Description
CONCATENATE	CONCATENATE(text1, text2, ...)	Text	Concatenate multiple texts; supports lists as input
LEN	LEN(text)	Number	Character count
LEFT	LEFT(text, [count])	Text	Extract from left; default 1
RIGHT	RIGHT(text, [count])	Text	Extract from right; default 1
MID	MID(text, start, count)	Text	Extract from middle
FIND	FIND(search_val, search_range, [start])	Number	Find substring position (case-sensitive); returns -1 if not found
REPLACE	REPLACE(text, start, count, new_text)	Text	Replace by position
SUBSTITUTE	SUBSTITUTE(text, old_text, new_text, [occurrence])	Text	Replace by content; can specify which occurrence
UPPER	UPPER(text)	Text	Convert to uppercase
LOWER	LOWER(text)	Text	Convert to lowercase
TRIM	TRIM(text)	Text	Remove leading/trailing spaces
TEXT	TEXT(value, format)	Text	Format output. Date formats: "YYYY-MM-DD", "YYYY/MM/DD hh:mm:ss"; number formats: "00", "000.00"
CONTAINTEXT	CONTAINTEXT(text, search_text)	Boolean	Tests if text contains substring (text substring matching)
SPLIT	SPLIT(text, delimiter)	List	Split text by delimiter
TODATE	TODATE(value)	Date	Convert date string to date type
CHAR	CHAR(number)	Text	ASCII code to character
FORMAT	FORMAT(template, [val1, val2, ...])	Text	Template string formatting; use {1}, {2} as placeholders
HYPERLINK	HYPERLINK(url, [display_text])	Hyperlink	Create a hyperlink
ENCODEURL	ENCODEURL(text)	Text	URL encode
REGEXMATCH	REGEXMATCH(text, regex)	Boolean	Regex match test
REGEXEXTRACT	REGEXEXTRACT(text, regex)	List	Extract first match's capture groups
REGEXEXTRACTALL	REGEXEXTRACTALL(text, regex)	2D List	Extract all matches
REGEXREPLACE	REGEXREPLACE(text, regex, replacement)	Text	Regex replace

8.4 Date functions

Function	Signature	Return type	Description
NOW	NOW()	Date	Current date and time
TODAY	TODAY()	Date	Current date (midnight)
DATE	DATE(year, month, day)	Date	Construct a date
YEAR	YEAR(date)	Number	Extract year
MONTH	MONTH(date)	Number	Extract month
DAY	DAY(date)	Number	Extract day
HOUR	HOUR(date)	Number	Extract hour
MINUTE	MINUTE(date)	Number	Extract minute
SECOND	SECOND(date)	Number	Extract second
WEEKDAY	WEEKDAY(date, [type])	Number	Day of week
WEEKNUM	WEEKNUM(date, [type])	Number	Week number
DAYS	DAYS(end_date, start_date)	Number	Days between two dates (end - start), includes decimals. Note parameter order: end date comes first
DATEDIF	DATEDIF(start_date, end_date, [unit])	Number	Whole days/months/years between dates. Unit: "D"(default)/"M"/"Y". Start must be before end
DURATION	DURATION(days, [hours], [minutes], [seconds])	Duration	Create a duration for date arithmetic
EDATE	EDATE(date, months)	Date	Date N months later
EOMONTH	EOMONTH(date, [months])	Date	End of month N months later; months default 0
WORKDAY	WORKDAY(start_date, days, [holidays])	Date	Date N workdays later (skips weekends and holidays)
NETWORKDAYS	NETWORKDAYS(start_date, end_date, [holidays])	Number	Workdays between dates (inclusive)

8.5 List functions

Function	Signature	Return type	Description
LIST	LIST(val1, val2, ...)	List	Create a list
FIRST	FIRST(list)	Scalar	First element
LAST	LAST(list)	Scalar	Last element
NTH	NTH(list, index)	Scalar	Nth element (1-based)
FILTER	[Table].FILTER(condition).[ResultCol] or [Table].[Col].FILTER(condition)	List	Filter by condition. When data range is a table, result column is required; when it's a column/list, it's not needed. Use CurrentValue in conditions. Add .LISTCOMBINE() when result column is multi-value
MAP	data_range.MAP(mapping_expr)	List	Apply mapping to each element. Use CurrentValue in mapping
SORT	SORT(list, [ascending])	List	Sort; default ascending (TRUE)
SORTBY	[Table].SORTBY([Table].[SortCol], [ascending]).[OutputCol]	List	Sort by column then extract output column. Chain-only, must include output column
UNIQUE	UNIQUE(list)	List	Deduplicate
ARRAYJOIN	ARRAYJOIN(list, [delimiter])	Text	Join list elements as text; default comma-separated
LISTCOMBINE	LISTCOMBINE(val1, [val2, ...]) or list.LISTCOMBINE()	List	Two uses: (1) merge values/lists into one list; (2) chained call to flatten 2D array (commonly used when FILTER result column is a multi-value field)
DISTANCE	DISTANCE(location1, location2)	Number	Distance between two geographic locations (km)

---

Section 9: Commonly Confused Functions

CONTAIN vs CONTAINTEXT

	CONTAIN	CONTAINTEXT
Purpose	Tests if a list / select (multiple=true) contains a value	Tests if text contains a substring
Example	[Tags].CONTAIN("Urgent")	[Notes].CONTAINTEXT("completed")
Wrong usage	CONTAIN([Notes], "completed") — cannot do substring matching	CONTAINTEXT([Tags], "Urgent") — Tags is a list, not text

ISBLANK vs ISNULL

	ISBLANK	ISNULL
NULL	TRUE	TRUE
"" empty string	TRUE	FALSE
Empty list []	TRUE	FALSE
0	FALSE	FALSE
FALSE	FALSE	FALSE

DAYS vs DATEDIF

	DAYS	DATEDIF
Parameter order	DAYS(end, start) — end first	DATEDIF(start, end, unit) — start first
Precision	Includes decimals (hours/minutes/seconds as fractional days)	Integer only (whole days/months/years)
Negative values	Returns negative when start is after end	Errors when start is after end

SUM vs SUMIF

	SUM	SUMIF
Purpose	Sum all values	Sum values matching a condition
Arguments	SUM(val1, val2, ...) or SUM([Table].[Col])	SUMIF(data_range, condition) with CurrentValue in condition
Example	SUM([Orders].[Amount]) — sum all	SUMIF([Orders].[Amount], CurrentValue > 100) — sum only >100

FILTER+aggregation vs COUNTIF/SUMIF

	FILTER+aggregation	COUNTIF/SUMIF
Nature	Filter then aggregate (two steps)	One-step (syntactic sugar)
Equivalence	[Table].FILTER(cond).[Col].LISTCOMBINE().SUM()	SUMIF([Table].[Col], cond) (only when condition involves only column values)
When to use	Conditions span multiple fields, or multi-step needed	Conditions only involve column values (e.g. CurrentValue > 100)

---

Section 10: Decision Trees

Cross-table queries: which approach?

Need data from another table?
├─ Current table has a link field to the target table?
│   ├─ Yes → Use chained access: [LinkField].[TargetField]
│   │         Need aggregation? → .SUM() / .ARRAYJOIN(",") / .FIRST()
│   └─ No → Need to match by field value?
│       ├─ Field matching or complex filtering → [TargetTable].FILTER(CurrentValue.[MatchField] = [Value]).[OutputCol]
│       └─ Only counting or summing → COUNTIF([TargetTable], condition) / FILTER+SUM

Conditional logic: IF vs IFS vs SWITCH?

Need conditional logic?
├─ Single condition → IF(condition, true_val, false_val)
├─ Multiple mutually exclusive conditions (if-elseif-else) → IFS(cond1, val1, cond2, val2, ...)
├─ Matching a value against fixed options → SWITCH(expr, option1, result1, option2, result2, ..., default)
└─ Need error handling?
    ├─ Catch errors → IFERROR(expr, fallback)
    └─ Catch blanks → IFBLANK(expr, fallback)

Aggregation: which function?

Need to aggregate data?
├─ Sum/average/max/min for entire column → SUM/AVERAGE/MAX/MIN([Table].[Col])
├─ Count non-blank → COUNTA([Table].[Col])
├─ Conditional count → COUNTIF([Table], CurrentValue.[Field] = [Value])
├─ Conditional sum (column-only condition) → SUMIF([Table].[Col], CurrentValue > threshold)
├─ Conditional sum (cross-field condition) → [Table].FILTER(CurrentValue.[Field]=value).[NumCol].LISTCOMBINE().SUM()
├─ Count unique → [Table].[Col].UNIQUE().COUNTA()
└─ Ranking → RANK([Value], [Table].[Col])

---

Section 11: Common Formula Patterns

Pattern 1: Cross-table conditional count

Count rows in target table matching a condition:

[TargetTable].COUNTIF(CurrentValue.[MatchField] = [CurrentTableField])

Pattern 2: Cross-table conditional sum

Filter target table by current row's value, then sum:

[TargetTable].FILTER(CurrentValue.[MatchField] = [CurrentTableField]).[NumCol].LISTCOMBINE().SUM()

SUMIF works when data range is a column and conditions only involve column values:

SUMIF([TargetTable].[NumCol], CurrentValue > 100)

Note: COUNTIF can use a table as data range (only counting, no specific column needed), but SUMIF's data range must be a numeric column (needs values to sum), so CurrentValue is each value in that column (scalar) — cannot use CurrentValue.[OtherField] to access other fields. For cross-field conditions, use FILTER with a table as data range.

Pattern 3: Cross-table lookup

[TargetTable].FILTER(CurrentValue.[MatchCol] = [CurrentTableField]).[ReturnCol]

Pattern 4: Link field values + aggregation

SUM([LinkField].[NumField])
[LinkField].[TextField].UNIQUE().ARRAYJOIN(",")

Pattern 5: Conditional text concatenation

IF([Condition], "prefix" & [Field] & "suffix", "default text")

Pattern 6: Date difference

DATEDIF([StartDate], [EndDate], "D") & " days"
DAYS([EndDate], [StartDate])

Pattern 7: List element mapping

[SelectField(which multiple=true)].MAP(CurrentValue & " tag")
SPLIT([TextField], ",").MAP(TRIM(CurrentValue))

Pattern 8: Cross-table with sorting

[TargetTable].SORTBY([TargetTable].[SortCol], FALSE).[OutputCol]
[TargetTable].FILTER(CurrentValue.[Field] = [Value]).SORTBY([TargetTable].[SortCol]).[OutputCol]

---

Section 12: Anti-Pattern Collection

Mistake 1: Extra argument in MAP

Wrong:   [Table].[Col].MAP([Table2].[Col], CurrentValue + 1)
Correct: [Table].[Col].MAP(CurrentValue + 1)

Reason: MAP takes only two arguments (data range + mapping expression), no "lookup range".

Mistake 2: Inverted FILTER syntax

Wrong:   condition.[Table].FILTER()
Correct: [Table].FILTER(condition).[ResultCol]    (result column required when data range is a table)

Reason: FILTER's data range comes first, condition is passed as the argument.

Mistake 3: Using CurrentValue.[Field] on a column range

Wrong:   SUMIF([Sales].[Revenue], CurrentValue.[Salesperson] = [Name])
Correct: [Sales].FILTER(CurrentValue.[Salesperson] = [Name]).[Revenue].LISTCOMBINE().SUM()

Reason: SUMIF([Sales].[Revenue], ...) uses "Revenue" column as data range. CurrentValue is each revenue value (scalar), not a row — cannot use . to access other fields. Use FILTER with the table as data range for cross-field conditions.

Mistake 4: Missing result column after FILTER

Wrong:   [Sales].FILTER(CurrentValue.[Amount] > 100)
Correct: [Sales].FILTER(CurrentValue.[Amount] > 100).[Customer]

Reason: FILTER on a table returns a table reference; must specify result column with .[Field] at the end.

Mistake 5: Nested FILTER

Wrong:   [Table1].FILTER(CurrentValue.[ID] = [Table2].FILTER(CurrentValue.[Status]="Done").[ID])
Correct: [Table1].FILTER(CurrentValue.[ID] = [CurrentRowField]).[OutputCol]

Reason: FILTER/MAP/SUMIF/COUNTIF cannot be nested inside each other's conditions. Split into multiple steps or use link fields.

Mistake 6: SORTBY without output column

Wrong:   [Table].SORTBY([Table].[Col])
Correct: [Table].SORTBY([Table].[Col]).[OutputCol]

Reason: SORTBY must have an output column at the end; otherwise the result cannot be represented as an array.

Mistake 7: SORTBY sort column without table name

Wrong:   [Table].SORTBY([Col]).[OutputCol]
Correct: [Table].SORTBY([Table].[Col]).[OutputCol]

Reason: SORTBY's sort column must use [TableName].[FieldName] format.

Mistake 8: Using CONTAIN for text substring matching

Wrong:   CONTAIN([Notes], "urgent")
Correct: CONTAINTEXT([Notes], "urgent")

Reason: CONTAIN checks if a list or select (multiple=true) contains a whole value, not substring matching. Use CONTAINTEXT for text substrings.

Mistake 9: Date concatenation without formatting

Not recommended: "Deadline: " & [DateField] ← output format is uncontrolled
Recommended: "Deadline: " & TEXT([DateField], "YYYY-MM-DD")

Reason: Concatenating a date with & won't error, but uses the default format. Use TEXT to specify the format explicitly.

Mistake 10: Reversed DAYS parameter order

Wrong:   DAYS([StartDate], [EndDate])  → returns negative
Correct: DAYS([EndDate], [StartDate])  → returns positive

Reason: DAYS parameter order is end date first, start date second.

Mistake 11: Chaining zero-argument functions

Wrong:   TODAY.DAYS([Date])
Correct: TODAY().DAYS([Date])

Reason: NOW, TODAY, PI and other zero-argument functions must include parentheses.

---

Section 13: Complete Examples

Example 1: Employee sales summary

Table structure (from +table-get):

• Employees: EmployeeID (Text), Name (Text), Department (Text)
• Sales: ContractID (Number), SalespersonID (Text), Quantity (Number), Total (Number)

Current table: Employees

Requirement: For each employee, output "Sold XX orders" if they have sales records, otherwise "No sales records".

Formula:

IF(
  [Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) >= 1,
  "Sold " & [Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) & " orders",
  "No sales records"
)

Field JSON:

{
  "type": "formula",
  "name": "Sales Summary",
  "expression": "IF([Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) >= 1, \"Sold \" & [Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) & \" orders\", \"No sales records\")"
}

Explanation: [Sales].COUNTIF(...) uses the entire Sales table as data range. CurrentValue represents each row in Sales, accessing CurrentValue.[SalespersonID] for that row's salesperson. [EmployeeID] refers to the current row in the Employees table (where the formula lives).

Example 2: Chained cross-table access via link fields

Table structure:

• Orders: ID (auto_number), OrderItems (link [target: OrderItems, foreign key: ID])
• OrderItems: ID (auto_number), Product (link [target: Products, foreign key: ID])
• Products: ID (auto_number), ProductName (text)

Current table: Orders

Requirement: Deduplicate and comma-join all product names from linked order items.

Formula:

[OrderItems].[Product].[ProductName].UNIQUE().ARRAYJOIN(",")

Field JSON:

{
  "type": "formula",
  "name": "Product List",
  "expression": "[OrderItems].[Product].[ProductName].UNIQUE().ARRAYJOIN(\",\")"
}

Explanation: [OrderItems] gets linked order item records, .[Product] expands to each item's linked product, .[ProductName] gets all product names, .UNIQUE() deduplicates, .ARRAYJOIN(",") joins with commas.

Example 3: Cross-table filter + sort

Table structure:

• Projects: ProjectName (Text), Status (Text), Owner (Text)
• Tasks: TaskName (Text), Project (Text), Priority (Number), DueDate (Date)

Current table: Projects

Requirement: Find the highest-priority (lowest number) task name for the current project.

Formula:

FIRST(
  [Tasks].FILTER(CurrentValue.[Project] = [ProjectName]).SORTBY([Tasks].[Priority], TRUE).[TaskName]
)

Field JSON:

{
  "type": "formula",
  "name": "Top Priority Task",
  "expression": "FIRST([Tasks].FILTER(CurrentValue.[Project] = [ProjectName]).SORTBY([Tasks].[Priority], TRUE).[TaskName])"
}

Explanation: [Tasks].FILTER(CurrentValue.[Project] = [ProjectName]) filters tasks belonging to the current project. .SORTBY([Tasks].[Priority], TRUE) sorts by priority ascending. .[TaskName] extracts task names. FIRST(...) gets the first one (highest priority).

---

Section 14: Translating User Requirements to Formulas

When the user describes their formula need in natural language, follow these rules to convert it into a precise expression:

1. Numbers must use precise values: "less than 80%" → field value less than 0.8. "above 1000" → >= 1000.
2. Interval boundaries: "above/below/within" = closed (inclusive); "less than/more than/outside" = open (exclusive).
3. Branching logic must be organized as an ordered list with a fallback branch. Each branch has a condition and output.
   • Example: "return risk level for 1-3" → IFS([Value] = 1, "low", [Value] = 2, "medium", [Value] = 3, "high") with an IFERROR or trailing empty-string fallback.
4. Multi-level branches must be flattened to a single level. Nested if-else chains → flat IFS.
5. Branch conditions must be mutually exclusive. If the user's conditions overlap, rewrite to eliminate ambiguity.
6. Reorder branches by logical priority if the user's order is illogical (e.g., check specific conditions before catch-all).

---

Section 15: Constraint Summary

• Request body must include "type": "formula" — this field is required
• Only use functions and operators listed in this document
• FILTER/SUMIF/COUNTIF/MAP must not be nested inside each other's conditions (chained calls are not nesting)
• Do not use LOOKUP — use FILTER exclusively
• Table and field names must exactly match +table-get output
• Strings must use double quotes "
• Format dates with TEXT before concatenating, to control output format
• SORTBY can only be chained and must include an output column
• Link fields return lists — aggregate or extract single values before output