Menu
hqRuleUnderstanding hqRule

hqRule Documentation

hqRule is the business rules engine for Data Management teams who would rather focus on the features that make their business unique.

Here’s how to use it.

Welcome to hqRule!

Yell for help!

hqRule evaluates a set of Inputs against a Ruleset in order to match each Input to one or more Results. Depending on evaluation configuration, some subset of these matched Results will be returned as Output.

Results may be unrelated to one another, or may share a hierarchical relationship. Rules are evaluated in priority order, so ambiguous or even contradictory Rules can still match Inputs to Results so long as at least one Rule evaluates TRUE against a given Input.

A Result may be of one of two types:

  • Constant Result always returns the same, hard-coded value.
  • A Term Result returns the value of a designated Term from the Input row under evaluation.

An Example Ruleset

The following image illustrates a Ruleset designed to classify private capital assets.

hqRule Example Ruleset

Note that the Results have a hierarchical relationship. This is optional: Results could also be represented as a flat list, which is accomplished by setting each Result’s ParentResultId to NULL. Deleting one Result—say, Equity—will cause the deletion of all descendant Results (Venture Capital, Early Stage, Expansion Capital, etc.) as well as all associated Rules, RuleTerms, and RuleTermValues.

Three Config options can be set when evaluating Inputs against a Ruleset:

  • EvaluateAllRules (EAR) indicates whether Rule evaluation for a given Input should stop after the first Rule in priority order evaluates TRUE.
  • ProgressiveEvaluation (PE) indicates whether Results should be evaluated progressively, meaning that a Result in a hierarchy can only evaluate TRUE if its parent Result evaluates TRUE..
  • ReturnAllResults (RAR) indicates whether a single, lowest-level Result should be returned from a hierarchy, or whether all of its parent Results should be returned as well.

Used in combination, these options have the following effects:

EAR PE RAR Comments
F F Highest-performance mode of operation. RAR value not relevant because EAR = FALSE guarantees one or zero Outputs returned. Rules evaluated non-progressively, so Output may come from any Result in the hierarchy.
F T RAR value not relevant because EAR = FALSE guarantees one or zero Outputs returned. Rules evaluated progressively, so Output may only come from a Result at the top level of the hierarchy.
T F F All Rules evaluated non-progressively, so Outputs may come from any Result in the hierarchy. When parent Results also evaluate TRUE, only lowest-level Outputs returned.
T F T All Rules evaluated non-progressively, so Outputs may come from any Result in the hierarchy. When parent Results also evaluate TRUE, all levels returned.
T T F Lowest-performance mode of operation. All Rules evaluated progressively, so Outputs only returned if all parent levels evaluate TRUE. Only lowest-level Outputs returned.
T T T All Rules evaluated progressively, so Outputs only returned if all parent levels evaluate TRUE. All Output levels returned.

Evaluating Data

Let’s assume that we are evaluating the following Input against the example Ruleset above:

  • Activity = Development
  • ControlChange = True
  • Focus = Asset
  • InvestmentType = Structure
  • isDistressed = TRUE
  • LifecycleStage = Startup
  • Location = Core
  • MarketSize = Medium
  • ProfitMargin = (2%)
  • ServiceType = Non-essential
  • Tangible = TRUE

The sections below illustrate expected results with different combinations of Config options. Highlighted Rules evaluate TRUE, and highlighted Results are returned as Outputs.

Config Options: EAR = FALSE, PE = FALSE

This is the highest-performance mode of operation. RAR value is not relevant because EAR = FALSE guarantees one or zero Outputs returned. Rules are evaluated non-progressively, so Output may come from any Result in the hierarchy.

hqRule Example Ruleset: FFX

Config Options: EAR = FALSE, PE = TRUE

RAR is value not relevant because EAR = FALSE guarantees one or zero Outputs returned. Rules are evaluated progressively, so Output may only come from a Result at the top level of the hierarchy.

hqRule Example Ruleset: FTX

Config Options: EAR = TRUE, PE = FALSE, RAR = FALSE

All Rules are evaluated non-progressively, so Outputs may come from any Result in the hierarchy. When parent Results also evaluate TRUE, only lowest-level Outputs are returned.

hqRule Example Ruleset: TFF

Config Options: EAR = TRUE, PE = FALSE, RAR = TRUE

All Rules are evaluated non-progressively, so Outputs may come from any Result in the hierarchy. When parent Results also evaluate TRUE, all levels are returned.

hqRule Example Ruleset: TFT

Config Options: EAR = TRUE, PE = TRUE, RAR = FALSE

This is the lowest-performance mode of operation. All Rules are evaluated progressively, so Outputs are only returned if all parent levels evaluate TRUE. Only lowest-level Outputs are returned.

hqRule Example Ruleset: TTF

Config Options: EAR = TRUE, PE = TRUE, RAR = TRUE

All Rules are evaluated progressively, so Outputs are only returned if all parent levels evaluate TRUE. All Output levels are returned.

hqRule Example Ruleset: TTT

Rule Structure

In the above examples, only one Rule is associated with most Results. This need not be the case: any number of Rules may be associated with a given Result (e.g. Late Stage and Early Stage). There is an implicit OR relationship between Rules on a given Result: if any one evaluates TRUE, then the Result is returned (assuming the Config options permit it).

Note that many of the Rules articulated in our example have multiple RuleTerms, meaning several Terms must be evaluated successfully against the Input for the Rule to evaluate TRUE. There is an implicit AND relationship between RuleTerms on a given Rule, so all of them must evaluate TRUE for the Rule to evaluate TRUE.

Also, a few of the RuleTerms in our example have multiple RuleTermValues (e.g. InvestmentType in the Rule with Priority = 9). There is an implicit OR relationship between RuleTermValues.

A RuleTerm brings together a Term, an Operator, and one or more RuleTermValues. So for the one RuleTerm on the Rule with Priority = 9…

  • The Term is InvestmentType.
  • The Operator is Equality.
  • The RuleTermValues are Loan, Bond, and CreditDeriv. Any one of these values on the Input for Term InvestmentType will cause this RuleTerm to evaluate TRUE.