BFL Syntax Reference

Basenine Filter Language (BFL) is the language implemented inside Basenine database server that enables the user to query the traffic logs efficiently and precisely.

http and request.method == "GET" and request.path != "/example" and (request.query.a > 42 or request.headers["x"] == "y")

The syntax as a whole evaluates into a boolean outcome, always. Such that the record which makes the boolean true is a record that matches the filter.

There are certain helper methods that can do more than reducing into a boolean value.

Literals

The language supports the following literals:

• Nil nil
• Boolean true or false
• Number 42, 3.14 etc.
• String "hello world"
• Regex r"prefix.*"

Operators

Operations can be grouped (precedence) using parentheses (...)

Note: Operators are evaluated from left to right, excluding parentheses (...)

The language supports the following operators:

Logical

and, or

Note: false and, true or are evaluated fast

Equality

==, !=

Comparison

>=, >, <=, <

Unary

!, -

Helpers

Helpers in BFL are method invocations that enables filtering capability which cannot be provided through the syntax. These are the available helpers in BFL:

startsWith(string)

Returns true if the given selector's value starts with the string. e.g. brand.name.startsWith("Chev")

endsWith(string)

Returns true if the given selector's value ends with the string. e.g. brand.name.endsWith("let")

contains(string)

Returns true if the given selector's value contains the string. e.g. brand.name.contains("ro")

datetime(string) integer

Returns the UNIX timestamp integer which is the equivalent of the time that's provided by the string. If the given date-time string is not in a recognized format then it evaluates to false. The format must be same as "1/2/2006, 3:04:05 PM" (en-US) e.g. timestamp > datetime("10/19/2021, 6:29:02 PM")

It's equal to the time.Now().UnixNano() / int64(time.Millisecond) in Go. e.g. 1635190131000

limit(integer)

Limits the number of records that are streamed back as a result of a query. Always evaluates to true.

rlimit(integer)

Limits the number of records that are streamed back as a result of a query but in reverse. Always evaluates to true.

leftOff(integer)

Forces the querying to start from the given offset. e.g. leftOff(100) skips the first 100 records and starts the querying from 101th record according to the internally tracked offsets in the server. This internally tracked offset is exposed through leftOff field of Metadata. Calling leffOff with a negative value like leftOff(-1) makes the query start from the latest record in the database.

Note: Calling an undefined helper makes the whole expression collapse and evaluate to false.

Selectors

Selectors in BFL are JSONPath(s) that refers to the path in a JSON document. In Basenine, every record is a JSON document. Any selector that does not match a path is evaluated to false.

Following are some selector examples:

• brand.name basic selector
• request.path[1] index selector
• request.headers["a"] == "b" key selector

Selectors can be combined with a subset of helpers such that they evaluate into a boolean without any operator. e.g. brand.name.startsWith("Chev") These are the list of helpers that can be used with selectors:

• startsWith(string)
• endsWith(string)
• contains(string)

Such that instead of writing a boolean expression like brand.name == "Chevrolet", one of the following can be written:

brand.name.startsWith("Chev")
brand.name.endsWith("let")
brand.name.contains("ro")

A selector can be compared to another selector as well. Such that for these given JSON document, filters like those can be written:

JSON: {"id":114905,"model":"Camaro","brand":{"name":"Chevrolet"},"year":2021,"salesYear":2021} Filter: year == salesYear

JSON: {"id":114905,"model":"Camaro","brand":{"name":"Chevrolet"},"year":2021,"salesYear":2020} Filter: year != salesYear

Note: A selector (JSONPath) that couldn't be found in the JSON document makes the whole expression collapse and evaluate to false.