Typed Queries¶
A JevQuery declares questions as properties. Each property name becomes the question id, and each property
is a typed handle (QuestionRef<A>) that reads its answer back from a result.
object Triage : JevQuery() {
val urgent by noul("Does this message convey urgency or time-sensitivity?") {
whenTrue("Explicitly time-sensitive, or the customer is blocked right now")
whenFalse("No urgency expressed")
}
val team by choice<Team>("Which team should handle this message?")
val frustration by score("How frustrated does the customer appear?") {
level("Calm, just stating facts")
level("Frustrated but civil")
level("Very angry, strong language or threatening to leave")
}
}
Team is an ordinary enum; see Enum Choices.
Asking and reading¶
jev.ask(query, state) sends every question in the query as one request. result[handle] returns the answer,
already typed:
val result = jev.ask(Triage, state = ticket)
val urgent: NoulAnswer = result[Triage.urgent]
val team: ChoiceAnswer<Team> = result[Triage.team] // team.choice is a Team
val frustration: ScoreAnswer = result[Triage.frustration]
println("${team.choice} urgent=${urgent.noul} frustration=${frustration.normalized}")
A handle only works on results of requests that included it. Reading one from an unrelated result throws
IllegalArgumentException.
The builder functions¶
A JevQuery has the same builders as the inline DSL, but the id comes from the property name, so
instructions are the first argument:
| Function | Returns a handle to |
|---|---|
noul(instructions) { ... } |
NoulAnswer |
choice(instructions) { ... } |
ChoiceAnswer<String> |
choice<E>(instructions) |
ChoiceAnswer<E> |
score(instructions) { ... } |
ScoreAnswer |
box(instructions) |
BoxAnswer (experimental) |
attach(image) |
the JevImage itself (experimental) |
box and attach, which attaches an image to every request that asks the query, are experimental; see
Images & Box.
Custom ids¶
id = sends a different id than the property name:
object Sentiment : JevQuery() {
// The property name is the default id; `id =` sends something else.
val tone by choice("What is the customer's tone?", id = "customer_tone") {
options("calm", "frustrated", "angry")
}
}
Always pass id by name
The inline builders take the id first, noul("urgent", "Is this urgent?"), while a JevQuery's take the
instructions first and the id second. Both are strings, so a question moved from an inline query into a
JevQuery with its arguments unchanged still compiles, and Jev is asked "urgent" as its question. Writing
id = "urgent" makes the call read the same either way.
Inheritance¶
Queries can extend other queries. The base class's questions come first, then the subclass's, each in declaration order:
open class BaseChecks : JevQuery() {
val spam by noul("Is this message unsolicited advertising or spam?")
val abusive by noul("Does this message contain abusive or threatening language?")
}
// Subclass questions come after the base class's, in declaration order.
object ForumPostChecks : BaseChecks() {
val offTopic by noul("Is the post unrelated to software development?")
}
Parameterized queries¶
A query can be a class, so its questions can depend on runtime values. Here there's one query per policy, each with
ids of its own, so include can put all of them in one request:
// A query can be a class, so its questions can depend on runtime values. Each instance gets ids of its own, so
// several can share one request.
class PolicyCheck(
slug: String,
policy: String,
) : JevQuery() {
val violates by noul("Does the message violate this policy: $policy", id = "violates_$slug")
}
val policyChecks =
listOf("personal_data" to "No personal data", "medical_advice" to "No medical advice")
.map { (slug, policy) -> PolicyCheck(slug, policy) }
// Every policy in one request, so the message is sent and read once.
suspend fun policyViolations(
jev: JevApi,
message: String,
): List<Double> {
val result = jev.query(state = message) { policyChecks.forEach { include(it) } }
return policyChecks.map { result[it.violates].noul }
}
Combining with ad-hoc questions¶
include() inside an inline query asks a typed query's questions alongside one-off questions, in one request:
// Mix a typed query with ad-hoc questions in one request; the typed handles still work.
val result =
jev.query(state = ticket) {
include(Triage)
noul("mentions_competitor", "Does the message mention a competing product?")
}
val team = result[Triage.team].choice
val competitor = result.noul("mentions_competitor").noul
Many states¶
The same query works for any number of states. Here they run concurrently:
// The same query works for any number of states. Run them concurrently, a few at a time.
suspend fun triageAll(
jev: JevApi,
tickets: List<String>,
parallelism: Int = 4,
): Map<String, Team> {
val permits = Semaphore(parallelism)
return coroutineScope {
tickets
.map { ticket -> async { ticket to permits.withPermit { jev.ask(Triage, state = ticket) } } }
.awaitAll()
.associate { (ticket, result) -> ticket to result[Triage.team].choice }
}
}
Keep concurrency modest on a shared key; see Making Calls.
When definitions are checked¶
A query's questions are validated the first time they're used, typically on the first ask, not when the
object is created. Invalid definitions, such as blank instructions or duplicate ids, surface as a
JevValidationException listing every problem.