Querying

Queries inspect a successfully solved result. A membership query asks whether one exact fact is present. The result includes policy facts, the runtime input snapshot and the conclusions derived by rules.

For programming details, see C Stable querying, Python querying and TypeScript querying.

Why querying exists

Solving computes the consequences of a policy; querying extracts the answer the application needs.

An absent fact is an ordinary negative answer. An invalid predicate, an incorrect arity or a forbidden observation is an API error, not “absent”.

Where querying fits

The query does not solve the policy again or add facts. The result remains unchanged and can be queried repeatedly until it is released.

Ground-only queries

Ground means every term is a concrete value: for example, the user "alice" and the document "roadmap.pdf". A variable such as User does not name one exact fact.

% Fully ground: one exact fact
allow("alice", "roadmap.pdf")
% A variable is not accepted by the ground-query API
allow(User, "roadmap.pdf")

Membership can inspect query-enabled facts from all three origins: EDB, POLICY_FACT and IDB. Native result enumeration has a different scope: it lists derived IDB facts, subject to the same observation checks. Enumeration is not a wildcard membership query or a listing of all base facts.

Public Query Whitelist

The domain must grant a predicate the QUERY permission. For manifest-loaded policies, the manifest's queries field adds a second restriction: only listed predicates may be publicly inspected.

{
  "queries": [
    { "name": "allow", "arity": 2 }
  ]
}

An empty or omitted queries list exposes no predicates through this gate. The whitelist restricts observation, not computation: other predicates may still be evaluated and used to derive allow/2.

Inline loading — no whitelist

Inline loading has no manifest whitelist. All predicates granted QUERY by the selected domain can be inspected. This is also the typed WASM wrapper's loading model; see its query reference.

Why-true and Why-false

First obtain a successful membership answer, then choose the corresponding explanation.

A present base fact need not have a derivation witness: Why-true can return not-derived. Asking Why-false about a present fact returns not-applicable. Membership remains the source of the decision.

Both documents use the MAELYS-DATALOG-v2 envelope, with document=why-true or document=why-false. Both can be truncated when their explanation limits are reached. Why-false is a bounded exploration, not an exhaustive proof of every possible failed derivation. Neither document's truncation changes the solved answer.

An aggregate premise records the observed group and aggregate value; it does not expand into a derivation for every member of the counted relation. For concrete output and its fields, see the language guide.

Explanation memory and explanation limits

Automatic session workspace and caller-provided storage are two ways to manage memory for the same explanation machinery. They do not increase the number of explanation steps or candidate branches the engine can explore.

An undersized workspace is a storage error; an undersized output text buffer is a separate payload error. A returned document marked truncated is different from both: the engine successfully produced a bounded explanation. For ownership, caching and buffer sizes, see prepared explanations.

What you have learned