Parsing queries

Kaquel provides various utilities to parse queries into Query objects that can be rendered. In this section, we will use these utilities in example programs.

Parsing KQL queries

In order to parse a KQL query, you must use the parse_kql() function.

For example, say you need to make a program that converts a KQL query provided in the standard input into an ElasticSearch query. You can do the following:

from __future__ import annotations

from json import dumps
from sys import stdin

from kaquel.kql import parse_kql


# Read the raw KQL query from standard input.
raw_query = stdin.read()

# Parse the raw KQL query into a kaquel.query.Query object.
query = parse_kql(raw_query)

# Render the Query object into a Python dictionary.
rendered_query = query.render()

# Dump the Python dictionary as a JSON document on standard output.
print(dumps(rendered_query))

For example, when executing the program with the following input:

NOT http.request.method: GET

The output will be the following:

{"bool": {"must_not": {"match": {"http.request.method": "GET"}}}}

Parsing Lucene queries

In order to parse a Lucene query, as for KQL queries, you must use the parse_lucene() function.

For example, say you need to make a program that converts a Lucene query provided in the standard input into an ElasticSearch query. You can do the following:

from __future__ import annotations

from json import dumps
from sys import stdin

from kaquel.lucene import parse_lucene


# Read the raw Lucene query from standard input.
raw_query = stdin.read()

# Parse the raw Lucene query into a kaquel.query.Query object.
query = parse_lucene(raw_query)

# Render the Query object into a Python dictionary.
rendered_query = query.render()

# Dump the Python dictionary as a JSON document on standard output.
print(dumps(rendered_query))

For example, when executing the program with the following input:

a:b AND c:d

The output will be the following:

{"query_string": {"query": "a:b AND c:d"}}

Detecting invalid input

In case of an invalid input, parsing functions will raise a DecodeError, that holds the location of the error within the source string. You can thus catch it and display the error to the end user.

An example program doing exactly that is the following:

from __future__ import annotations

from kaquel.errors import DecodeError
from kaquel.kql import parse_kql


raw_string = "double_it:: and_give_it_to_the_next_person"

try:
    parse_kql(raw_string)
except DecodeError as exc:
    print(f"At line {exc.line}, column {exc.column}:")
    print("Syntax error starting at:")
    print(" ", raw_string[exc.offset :])

The output of the above program will be the following:

At line 1, column 11:
Syntax error starting at:
  : and_give_it_to_the_next_person