EMIT
EMIT is the primary output verb in OQL. It sets the query result and, in most contexts, terminates the current chain. Understanding exactly when it terminates and when it combines is essential.
Basic usage
EMIT returns any value as the query result. It accepts variables, literals, expressions, and object field access.
EMIT terminates the chain
In a sequential chain, only the last EMIT in the chain is returned. Earlier EMIT calls are evaluated (and their side effects run) but their values are replaced by later ones.
Result: "third". The last EMIT wins.
EMIT with AND — parallel output
When EMIT appears alongside AND EMIT, all values are collected into an array. The left-hand EMIT value is prepended to the parallel results.
Result: ["alpha", "beta", "gamma"]
Variables resolved before the parallel split are preserved:
Result: ["<uuid>", "done"]
EMIT inside HTML blocks
Inside an HTML block, EMIT does not return a query result — it appends to the HTML buffer of that block. The block itself returns the assembled HTML string when it closes.
EMIT inside EMAIL blocks
Inside an EMAIL block, EMIT appends to the email body buffer. It does not produce a query result. The EMAIL verb sends on CLOSE NEST.
EMIT inside IF / FOREACH / WHILE
EMIT inside a control flow block returns its value to the block's result, which then propagates as the block's output. The block result then participates in the outer chain normally.
EMIT on a multivariable
Emitting a multivariable (AND branches sharing the same name) returns one value at random from the active branches. Use COLLAPSE first if you want all values as an array.
Result: one of "ALPHA", "BETA", or "GAMMA" — chosen at random.
EMIT GEOIP — client location
EMIT has a special form for returning geolocation data about the client IP.
| Verb | Returns |
|---|---|
EMIT GEOIP ADDRESS | Client IP address string |
EMIT GEOIP CITY | City name string |
EMIT GEOIP COUNTRY | Country name string |
EMIT GEOIP REGION | State/province name string |
EMIT GEOIP LAT | Latitude number |
EMIT GEOIP LON | Longitude number |
EMIT GEOIP ALL | {ip, city, country, region, lat, lon} object for client IP |
EMIT GEOIP "1.2.3.4" | {ip, city, country, region, lat, lon} object for a specific IP |
When EMIT does NOT work as expected
| Situation | Behaviour | Fix |
|---|---|---|
| Multiple sequential EMITs | Only the last EMIT value is returned | Build an array and EMIT it once, or use AND EMIT for parallel collection |
| EMIT inside HTML block | Appends to HTML buffer, not query result | Capture the block result with SET and EMIT it after CLOSE NEST |
| EMIT inside EMAIL block | Appends to email body buffer only | EMIT after CLOSE NEST if you need a result |
| EMIT ?multivariable | Returns one random branch value | COLLAPSE ?multivariable SET ?arr AFTER EMIT ?arr if you need all values |
| EMIT ?undefined | Returns null | Ensure the variable is SET before EMIT |
| EMIT before AFTER chain | Value discarded by next AFTER step result | EMIT only at the end of the chain, or use AND EMIT to merge with parallel values |
EMIT vs RETURN
RETURN exits the entire query immediately with the given value — including breaking out of nested blocks and loops. EMIT does the same in a flat chain but participates in parallel collection with AND. Use RETURN when you need to exit from inside a FOREACH or WHILE; use EMIT for normal output.
Quick reference
| Pattern | Result |
|---|---|
EMIT "x" | String "x" |
EMIT ?var | Value of ?var (null if unset) |
EMIT ?obj(key) | Field key from object ?obj |
EMIT "x" AND EMIT "y" | Array ["x","y"] |
EMIT ?v AND EMIT "y" | Array [value_of_v, "y"] |
EMIT "x" AFTER EMIT "y" | String "y" — last wins |
EMIT GEOIP CITY | Client city string |