Overview

Regle Query Language (ReQL) is Regle's Domain Specific language (DSL) for writing rules to react events.

Becoming proficient in ReQL only requires understanding a few core concepts, which we cover below.

Concept

Feature

A variable inside ReQL is called a feature. Feature values can be a constant or a computed value.

main.tw

##
# Feature Example
##

# a constant
LET One = 1;
# data extracted from incoming JSON event 
LET EventIp: String = jsonExtract(EventData, "$.event.ip");
# data returned from functions
LET EventCountry = ip2Country(EventIp);

What is EventData

EventData is a builtin variable that contains the JSON event we are currently processing.

See Built-Ins for the list of built in variables.

The :String on EventIp is a type annotation that tells the ReQL's compiler and runtime that the extracted JSON field is of type "String". We will cover this syntax and the type system in Type System.

Rule and Label

ReQL Rule is similar to a filter in an email services. A rule applies a label if a given set of conditions is true.

The simplest way to understand rule is through an example

main.tw

##
# Rule Example
##

LET EventIp: string = jsonExtract(EventData, "$.event.ip");

# number of new user created on a 
# particular IP over the last day
LET NumberOfUserCreatedOnIpLastDay = ...;

RULE "high_prob_bot_ip"
LABEL EventIp AS "bot_ip"
WHERE NumberOfUserCreatedOnIpLastDay > 10;

Here, we have a rule "high_prob_bot_ip" that applies the label "bot_ip" to EventIp when feature NumberOfUserCreatedOnIpLastDay exceed 10.

Package

ReQL is organized into files that end with .tw extension.

A package is a collection of such files in a directory.

Here is an example package with 2 files, main.tw and constant.tw

directory

pkg
├── constant.tw
└── main.tw

constant.tw

LET A = 1;
LET B = 1;

main.tw

IMPORT "constant";

# `constant` namespace is now available etc.
LET X = constant.A;
LET Y = constant.B;

A package can be published to Github for others to download via regle's command line tool. See creating-packages to learn more.

Like a npm package

If you are familiar with nodejs and the npm's ecosystem, a ReQL package is similar to a npm module.

ReQL packages encapsulates a set of functionalities that can be easily shared with other people.

Summary

Rules applies labels to features by evaluating features.

A package is made of up of multiple tw files and a package is a unified set of functionalities that we can share with others.