@wedgekit/mql

MQL (Metadata Query Language)

Encoding

The encode method accepts a pseudo abstract syntax tree that is represented as follows using disjunctive normal form:

    [ // conditions combined with ||
        conditionA,
        conditionB,
        [ // conditions combined with &&
    	    conditionC,
    	    [ // conditions combined with ||
    		    conditionD,
    		    [ // conditions combined with &&
    			    ... and so on, alternating || and && by layer
    		    ]
    	    ]
        ],
        conditionE
    ]

...where a given condition is represented as and object with a field, operator, and list of values:

    {
        field: some field,
        operator: an operator from the metadata spec,
        value: [list of reqired values needed for chosen operator]
    }

The field and values cannot contain parentheses or gate symbols, so the following symbols are reserved: (, ), ||, and &&.

Refer to the metadata spec for required values.

NOTE - SET_VALUE expressions are not currently supported by the encoder.

For example, the following condition:

    [
        {
            field: 'exampleA',
            operator: 'EQUALS',
            value: ['A']
        },
        [
            {
                field: 'exampleB',
                operator: 'TRUTHY',
                value: []
            },
    	    [
                {
                    field: 'exampleC',
                    operator: 'STARTS_WITH',
                    value: ['example']
                },
                {
                    field: 'exampleC',
                    operator: 'ENDS_WITH',
                    value: ['C']
                }
    	    ]
        ],
        {
            field: 'exampleD',
            operator: 'BETWEEN',
            value: [1, 5]
        }
    ]

is encoded as "exampleA EQUALS A || (exampleB TRUTHY && (exampleC STARTS_WITH example || exampleC ENDS_WITH C)) || exampleD BETWEEN 1 5".

Parsing

The parse method accepts MQL query string written and returns a pseudo abstract syntax tree. It does the inverse of the example above.

A compound condition MUST be comprised of conditions or compound conditions seperated by a logic operator i.e. && and ||. More information on valid conditions can be found in the metadata spec

Combining two conditions into a compound condition:
"fieldA TRUTHY && fieldB FALSY"
Combining a compound condition and a condition into a compound condition:
"(fieldA TRUTHY && fieldB TRUTHY) || fieldC TRUTHY"
Combining two compound conditions into a compound condition:
"(fieldA TRUTHY && fieldB TRUTHY) || (fieldC TRUTHY && fieldD TRUTHY)"

The MQL parser makes no assumptions in regards to order of operations, so a compound condition MUST NOT have different operators in the same logic level. Consider the following example:

"coditionA || conditionB && conditionC"

This MQL query is INVALID. The query can result in two different results based on which operation is validated first. MQL requires that one of these operations be grouped into a logic level that will be evaluated first.

"conditionA || (conditionB && conditionC)"

The MQL query does NOT need to be simplified. Redundant parentheses are allowed and will be cleaned up before parsing.