`out` — writing results

out is the result. What it holds when the execution finishes is the answer — there is no separate return step, and no rule needs to assemble a final envelope.

It is also readable, so a later rule can branch on what an earlier one produced. That makes out the way rules communicate, and it is why the scratch-memory family on in is no longer the answer.

rule ClassifyClosingDisclosure "identify the form" salience 100 {
    when
        bbox.Doc().Top(10).Has("Closing Disclosure")
    then
        out.Set("docType", "closing_disclosure");
        Retract("ClassifyClosingDisclosure");
}

You never call Changed

Writing to out invalidates the engine’s expression cache by itself. Rules written for older engines called Changed("out") after a write; that is no longer needed, and no longer part of the rule surface.

Writing

out.Set(path, v)

Writes a value at path.

Parameter	Type	Meaning
path	string	Where to write. Dotted paths nest, where path keys are enabled
v	any	The value — text, a number, a map, a list, or a document read

v may be a plain value or a document read. When it is a read that carries metadata — a confidence, the text that actually matched — those attributes travel with it, so you do not have to unpack the value to keep its provenance.

rule CaptureLoanAmount "read the loan amount and keep its confidence" {
    when
        bbox.Doc().Right("Loan Amount").Found()
    then
        out.Set("loanAmount", bbox.Doc().Right("Loan Amount").Currency());
}

out.SetValue(path, v)

out.Set for a value that is already typed.

Parameter	Type	Meaning
path	string	Where to write
v	Value	An already-typed value

out.Delete(path)

Removes the value at path.

Parameter	Type	Meaning
path	string	What to remove

Useful where a later rule supersedes an earlier classification and the earlier key would otherwise remain alongside the correction.

out.Attr(path, name, v)

Attaches one attribute to an already-written path.

Parameter	Type	Meaning
path	string	The path that already holds a value
name	string	The attribute name
v	any	The attribute value

This is the escape hatch for metadata the producing value could not supply. It should stay rare — validation reports its use — because a value that carries its own provenance is better than one annotated afterwards by a rule that happened to know something.

rule MarkManualReview "this amount came from a low-confidence read" {
    when
        out.Has("loanAmount") && out.AttrNum("loanAmount", "confidence", 1.0) < 0.7
    then
        out.Attr("loanAmount", "needsReview", true);
}

Reading back

Every read takes the same shape as the in equivalents and never raises.

out.Has(path) → bool

Reports whether anything is present at path.

Parameter	Type	Meaning
path	string	The path to test

rule ClassifyFallback "only classify if nothing else did" salience 1 {
    when
        !out.Has("docType")
    then
        out.Set("docType", "unknown");
}

The low salience plus the Has guard is the standard “nobody claimed this” idiom — it runs last, and only when it is still needed.

out.IsEmpty(path) → bool

Reports whether path is absent or holds an empty value.

Parameter	Type	Meaning
path	string	The path to test

The first-class form of “has anything classified this page yet?”, which older rulesets express as a chain of map reads. Prefer it: Has is true for a key written as an empty string, and usually that is not what the rule meant.

out.Get(path) → any

Returns the raw value at path, or nil.

Parameter	Type	Meaning
path	string	The path to read

out.Value(path) → Value

Returns the typed value at path, or Null.

Parameter	Type	Meaning
path	string	The path to read

out.Str(path, def) → string

Parameter	Type	Meaning
path	string	The path to read
def	string	Returned when absent

out.Int(path, def) → int64

Parameter	Type	Meaning
path	string	The path to read
def	int64	Returned when absent

out.Double(path, def) → float64

Parameter	Type	Meaning
path	string	The path to read
def	float64	Returned when absent

Write the default with a decimal point — 0.0, not 0 — for the same type-dispatch reason as in.EqNum.

out.Bool(path, def) → bool

Parameter	Type	Meaning
path	string	The path to read
def	bool	Returned when absent

out.Date(path) → Date

Returns the date at path, or the zero date.

Parameter	Type	Meaning
path	string	The path to read

out.Map(path) → map

Returns the map at path, or nil.

Parameter	Type	Meaning
path	string	The path to read

Attributes

Attributes are opaque producer metadata recorded alongside a value — a confidence score, the text that matched, the page it came from. They ride along with out.Set and are readable afterwards.

out.Attributes(path) → map

Returns everything recorded for path, or nil.

Parameter	Type	Meaning
path	string	The path to inspect

out.HasAttr(path, name) → bool

Reports whether path carries the named attribute.

Parameter	Type	Meaning
path	string	The path to inspect
name	string	The attribute name

out.AttrNum(path, name, def) → float64

Returns the named numeric attribute, or def.

Parameter	Type	Meaning
path	string	The path to inspect
name	string	The attribute name
def	float64	Returned when the attribute is absent

The confidence gate is the usual use, and the default is load-bearing: pass 1.0 so a value carrying no confidence is treated as certain rather than as zero-confidence.

rule LowConfidenceExtraction "flag anything read below the threshold" {
    when
        out.Has("borrowerName") && out.AttrNum("borrowerName", "confidence", 1.0) < 0.85
    then
        findings.Warn("LowConfidenceExtraction", "extraction",
            strings.Sprintf("Borrower name read at %s confidence",
                to.Fixed(out.AttrNum("borrowerName", "confidence", 1.0), 2)));
}

out.AttrStr(path, name, def) → string

Returns the named string attribute, or def.

Parameter	Type	Meaning
path	string	The path to inspect
name	string	The attribute name
def	string	Returned when the attribute is absent

Inspecting the whole result

out.All() → map

Returns everything collected so far.

out.AllAttributes() → map of map

Returns every path’s attributes, keyed by path.

out.JSON() → bytes

Serialises the collected results.

out.History() → list

Returns every write in order, with the rule that made it.

out.HistoryFor(path) → list

Returns the writes to one path.

History is the debugging tool for the question that otherwise takes a bisect: which rule set this, and did anything overwrite it? On a ruleset where several rules can claim the same key, that is the first thing to look at.

rule TraceDocType "record how many times the classification changed" salience 1 {
    when
        out.Has("docType")
    then
        log.Debug("classification history",
            "writes", array.Len(to.List(out.HistoryFor("docType"))));
}

Older forms

Still working, listed so you recognise them.

Older form	Write instead	Why
out.GetStr(key)	out.Str(path, def)	Takes a default
out.GetInt(key)	out.Int(path, def)	Takes a default
out.GetFloat(key)	out.Double(path, def)	Takes a default
out.GetBool(key)	out.Bool(path, def)	Takes a default
out.GetMap(key)	out.Map(path)	Same shape, current name
out.Append(key, val)	Attributes	It predates attributes; it was used to accumulate provenance by string concatenation
out.UnwrapColumn(...)	delivery.ExplodeColumn(...)	Moved to the delivery plugin
out.UnwrapColumnWithTemplate(...)	delivery.ExplodeColumn(...)	Moved to the delivery plugin

Not callable from a rule

Three methods exist on the type and are the engine’s, not yours: BindInvalidator, SetCurrentRule and EnablePathKeys. The engine calls them once per execution — to wire cache invalidation, to attribute history, and to apply the deployment’s path-key setting. A rule has no reason to call any of them.

See also

• Writing output — the same surface as a guide
• in — reading facts — the other half of the pair
• Findings — for validation results rather than extracted values