FQL language reference — write a herd query

Farm Query Language (FQL) gives Herd Queries a repeatable question to run against the selected farm. Start with a page example or the visual Builder, inspect the generated command, and run it. Keywords and item names are case-insensitive. The page’s Suggestions catalogue is the live source for fields, measures, group dimensions and entitlement-dependent options; a valid spelling can still be unavailable for a farm type or plan.

Choose a command

Form	Result and example
LIST item item …	One row per matching animal, with the chosen columns. LIST TAG PEN DIM MILK FOR SCC > 200 AND DIM < 100 BY PEN
COUNT	Number of matching animals. COUNT FOR RPRO = LATE
SUM numeric-item	Sum of a numeric animal item, optionally grouped. SUM MILK BY PEN
AVG numeric-item	Average of a numeric animal item, optionally grouped. AVG MILK BY PEN FOR DIM < 150
TREND measure	Historical measure in time buckets. TREND MILK BY WEEK LAST 12 WEEKS
BREAKDOWN metric	Historical event metric grouped by a compatible dimension. BREAKDOWN CONCEPTION_RATE BY SIRE LAST 12 MONTHS

COUNT takes no item name; it counts animals. LIST needs at least one item. SUM and AVG need exactly one numeric animal item. A TREND name is a period measure, not an animal column: for example, TREND MILK totals milk recorded in each period, while LIST TAG MILK displays each cow’s latest yield. BREAKDOWN metrics come from event datasets; its BY dimension must belong to the metric’s dataset. A BREAKDOWN needs both a dimension and an explicit date range. The Builder and Suggestions panel show the choices currently available to this farm.

Add clauses

Each clause may appear at most once. Clauses can follow the verb in different orders; AVG MILK BY PEN FOR DIM < 150 and AVG MILK FOR DIM < 150 BY PEN have the same shape.

Clause	Where it applies	Example or meaning
FOR condition	All forms	Filter the matching animal cohort. FOR SEX = Female AND AGE > 365
BY item	LIST, COUNT, SUM, AVG	Group by a groupable animal item, such as PEN, BREED or LACT.
SORT item ASC or SORT item DESC	LIST only	Order rows by a sortable item, such as SORT SCC DESC.
LIMIT positive-whole-number	LIST only	Keep at most that many rows after sorting. The server still caps a result at 10,000 rows.
BY DAY, BY WEEK, BY MONTH	TREND only	Set the time bucket; week is the default.
SPLIT BY item	TREND only	Draw separate series for a supported groupable fact. Fixed facts such as BREED and SEX use their current value; history-backed facts such as STAGE, PEN, GROUP and LACT use the value in effect when each measurement was recorded. Some measures expose a native split, such as PEN for FEEDCOST and IOFC.
LAST n DAYS, LAST n WEEKS, LAST n MONTHS	TREND, BREAKDOWN	Relative farm-calendar window; LAST 7 DAYS includes today.
FROM date TO date	TREND, BREAKDOWN	Explicit inclusive dates, for example FROM 2026-01-01 TO 2026-03-31. Either endpoint may use TODAY with an offset.

Use one range form, LAST or FROM … TO …, never both. TREND without a range defaults to 12 weekly buckets and reports that default. BREAKDOWN refuses a missing range and each current event dataset permits at most 36 months. Trend bucket and lookback limits depend on the bucket: at most 92 daily, 104 weekly or 60 monthly buckets. Shorten an excessive window rather than relying on silent truncation. SORT and LIMIT do not apply to a trend or breakdown; LIMIT does not rank aggregate groups.

Write a FOR condition

Syntax	Example
Comparison =, != (or <>), <, <=, >, >=	DIM < 100, STATUS != Sold
Several choices with IN (…)	PEN IN ("High group", "Fresh pen")
Text search with CONTAINS	NAME CONTAINS "bella"
Missing or present value	DUE IS BLANK, DUE IS NOT BLANK
Boolean combinations	MILK < 15 AND (DOPN > 150 OR LACT >= 6), NOT (PEN = "Dry pen")

AND binds more tightly than OR; use parentheses whenever the intended grouping could be unclear. Put multiword names inside double quotes. To include a double quote inside a quoted value, write it twice. Numeric values can have decimals or a leading minus sign. Dates use yyyy-MM-dd; TODAY, TODAY-30 and TODAY+14 use the farm’s local day, not the viewer’s browser day. The binder checks operators against each item’s type, so CONTAINS is for text rather than a number or date. An IN list can contain up to 50 values.

Understand the rows before comparing figures

For ordinary LIST, COUNT, SUM and AVG, the default scope is living/active animals. Mentioning a status/exit item such as STATUS, EXITDAT or EXITREASON can lift that default even in displayed columns or BY, so COUNT BY STATUS may include exited animals. A TREND or BREAKDOWN is historical and does not apply today’s active-only default: excluding an animal sold since the period would rewrite the past. A FOR filter on those historical forms uses supported stable animal facts; volatile facts are refused because today’s pen or state would mislabel an earlier event.

BY GROUP is different from BY PEN: one animal can belong to several management groups and appears in each group. Adding group totals can therefore double-count animals or their measures. Some fields are blank when no source record exists. For example, DIM is blank for a dry cow, heifer or male, and DUE is blank without a derivable date. Read the result’s blank/exclusion notes rather than assuming missing values are zero. WACTIVE asks whether any withdrawal is active at the query instant; WDRAW, WMILK and WMEAT show dates that can be projections while a course-completion hold is still open. Use the treatment record for milk or meat release decisions.

Read a split trend correctly

A split trend can show at most 12 series. When more exist, Farmlync keeps the largest series and adds a notice. Fixed facts such as Breed and Sex classify an animal using its current stored fact. History-backed Stage, Pen, Group and Lactation splits attribute each measurement to the value in force at the time, so later moves do not rewrite the earlier period.

SPLIT BY GROUP is non-partitioning because an animal can belong to several groups at once. Its series can overlap and must not be added to obtain a herd total. SPLIT BY PEN is partitioning where a single pen interval applies, and feed-cost/IOFC pen splits use the pen carried or resolved by the underlying event. Read the split notice above the chart because it states the attribution basis actually used.

Animal item names

The current animal-item catalogue contains the following names. The live Suggestions panel supplies their full descriptions, supported operators and availability. This table groups them by purpose; it does not mean every item is valid for SUM, BY or SORT.

Purpose	Items and meaning
Identity and location	TAG management tag; NAME; NATID national identifier; RFID current electronic tag; TAGHIST identifier history; BREED; SEX; PEN physical location; GROUP management groups; DAM and SIRE.
Current and exit state	STATUS; STAGE; AGE in days; BDAT birth date; ENTDAT herd-entry date; EXITDAT exit date; EXITREASON; WATCH open watch-list flag; FAVORITE starred animal.
Lactation and milk	LACT parity; DIM days in milk; MILK latest yield; MILK7 seven-day daily average; PEAK current-lactation peak; PROJ305 projected 305-day yield; SCC latest somatic cell count in thousands of cells/mL; LGSCC linear SCC score; FAT and PROT latest percentages.
Breeding	RPRO reproductive state; CDAT last calving; LSDAT last service; TBRD services in cycle; DUE expected calving; DOPN days open; DCC days carried calf; DDRY expected dry-off; DNB do-not-breed; HOLD active breeding hold; INPROGRAM breeding-program roster; LHDAT last heat; LPDAT last pregnancy check; PDRES its result; PDDUE the date recorded on the latest scan.
Health and weight	WDRAW overall withdrawal end; WACTIVE active withdrawal now; WHOLD open course-completion hold; WMILK and WMEAT withdrawal ends by leg; TRT active treatment count; LTDAT last treatment; TRTLACT current-lactation treatment count; VDAT last vaccination; VNEXT next due on the latest vaccination; BCS latest condition score; WT latest weight; ADG30 weight-gain rate over spaced weigh-ins; TCOST rolling 365-day treatment cost.

For period trends, the current measure catalogue includes MILK, MILKCOWS, MILKAVG, SCC, FAT, PROT, FEEDCOST, IOFC, CALVINGS, DRYOFFS, EXITS and TREATMENTS. Similar names can have different grains: LIST TAG MILK is a latest animal value; TREND MILK is recorded production by period. Check the unit and any feature restriction in Suggestions before sharing a result.

Event breakdown metrics and dimensions

BREAKDOWN uses a metric and a dimension from the same event dataset, with a mandatory range. These are the current dataset families; the Suggestions panel reflects the farm’s actual access. A familiar animal item such as PEN is not automatically an event-time dimension: for breeding services, use PEN_AT_SERVICE if offered, because the cow may have moved since service.

Event family	Metric names	Compatible BY dimensions
Breeding services	SERVICE_COUNT, CONCEPTION_COUNT, CONCEPTION_RATE, EARLY_LOSS_RATE	SIRE, SIRE_BREED, SERVICE_TYPE, SERVICE_NUMBER, PEN_AT_SERVICE, LACTATION_GROUP, SERVICE_MONTH
Health treatments	TREATMENT_COUNT, ANTIBIOTIC_TREATMENT_COUNT, TREATMENT_COURSE_RECOVERY_RATE, TREATED_ANIMALS, TREATMENT_COST	DISEASE_CODE, TREATMENT_TYPE, IS_ANTIBIOTIC, OUTCOME, TREATMENT_MONTH, TREATMENT_WEEK, TREATMENT_DAY_OF_WEEK
Treatment medicine lines	MEDICINE_LINE_COUNT, ANTIBIOTIC_LINE_COUNT, MEDICATED_ANIMALS, MEDICATED_TREATMENTS, CASCADE_LINE_SHARE	DRUG, STOCK_ITEM, IS_ANTIBIOTIC, ROUTE, USE_BASIS, DOSE_UNIT, DISEASE_CODE, TREATMENT_MONTH
Health cases	CASE_COUNT, OPEN_CASE_COUNT, CASE_RECOVERY_RATE, CASE_DURATION_DAYS	CASE_OUTCOME, CASE_STATUS, OPENED_MONTH, OPENED_WEEK

For example, BREAKDOWN TREATMENT_COUNT BY DISEASE_CODE LAST 3 MONTHS asks how many treatment events were recorded per disease code in that period, whereas COUNT FOR TRT > 0 counts animals meeting a current treatment predicate. The two answer different questions. Percentage/rate metrics also have their own denominator rules: read the metric description and result notes rather than adding displayed percentages.