FIQLEx v0.1.0 FIQLEx.QueryBuilder behaviour View Source

QueryBuilder module has to be used to build queries from FIQL.

You have at least to use this module and define the functions init and build.

Here is the minimal code:

defmodule MyQueryBuilder do
  use FIQLEx.QueryBuilder

  @impl true
  def init(ast, _opts) do
    %{}
  end

  @impl true
  def build(_ast, state) do
    {:ok, state}
  end
end

The you'll want to override functions like handle_and_expression/4, etc, ... to build your final query. See SQLQueryBuilder module for an implementation example.

To build a new query using your module you have to parse a FIQL query and call FIQLEx.build_query/3

query = "author.age=ge=25;author.name==*Doe"
{:ok, ast} = FIQLEx.parse(query)
{:ok, query} = FIQLEx.build_query(ast, MyQueryBuilder)

Link to this section Summary

Callbacks

This callback is invoked at the end of the call to the function FIQLEx.build_query/3.

This callback is invoked when an AND expression is found in the query.

This callback is invoked when an expression is found in the query. An expression is a selector compared to a value, or just a selector.

This callback is invoked when an OR expression is found in the query.

This callback is invoked when a selector without a value to be compared to is found.

This callback is invoked when a selector is found with a value it is compared to.

This callback is invoked when a selector is found with a value it is compared to. Same as handle_selector_and_value/5 but with a custom comparison operator

This callback is invoked as soon as you call the function FIQLEx.build_query/3.

Link to this section Callbacks

Link to this callback

build(ast, state)

View Source (optional)
build(ast :: FIQLEx.ast(), state :: any()) :: {:ok, state} | {:error, any()}
when state: any()

This callback is invoked at the end of the call to the function FIQLEx.build_query/3.

Parameters are:

  • ast: The AST returned by FIQLEx.parse/1
  • state: The current (and final) state of your query builder

This function returns {:ok, final_state} if everything is ok, or {:error, reason} if there is something wrong

Link to this callback

handle_and_expression(exp1, exp2, ast, state)

View Source (optional)
handle_and_expression(
  exp1 :: FIQLEx.ast(),
  exp2 :: FIQLEx.ast(),
  ast :: FIQLEx.ast(),
  state
) :: {:ok, state} | {:error, any()}
when state: any()

This callback is invoked when an AND expression is found in the query.

Parameters are:

  • exp1: left side of the AND expression
  • exp2: right side of the AND expression
  • ast: The AST returned by FIQLEx.parse/1
  • state: The current state of your query builder

This function returns {:ok, new_state} if everything is ok, or {:error, reason} if there is something wrong

Example

author.age!=25;author.name==*Doe

The exp1 is author.age!=25 The exp2 is author.name==*Doe

Call handle_ast(exp, ast, state) to go deeper in the expressions

Link to this callback

handle_expression(exp, ast, state)

View Source (optional)
handle_expression(exp :: FIQLEx.ast(), ast :: FIQLEx.ast(), state) ::
  {:ok, state} | {:error, any()}
when state: any()

This callback is invoked when an expression is found in the query. An expression is a selector compared to a value, or just a selector.

Parameters are:

  • exp: the expression
  • ast: The AST returned by FIQLEx.parse/1
  • state: The current state of your query builder

This function returns {:ok, new_state} if everything is ok, or {:error, reason} if there is something wrong

Example

author.age!=25

This is an expression. Call handle_ast(exp, ast, state) to go deeper in the expression

Link to this callback

handle_or_expression(exp1, exp2, ast, state)

View Source (optional)
handle_or_expression(
  exp1 :: FIQLEx.ast(),
  exp2 :: FIQLEx.ast(),
  ast :: FIQLEx.ast(),
  state
) :: {:ok, state} | {:error, any()}
when state: any()

This callback is invoked when an OR expression is found in the query.

Parameters are:

  • exp1: left side of the OR expression
  • exp2: right side of the OR expression
  • ast: The AST returned by FIQLEx.parse/1
  • state: The current state of your query builder

This function returns {:ok, new_state} if everything is ok, or {:error, reason} if there is something wrong

Example

author.age!=25,author.name==*Doe

The exp1 is author.age!=25 The exp2 is author.name==*Doe

Call handle_ast(exp, ast, state) to go deeper in the expressions

Link to this callback

handle_selector(selector_name, ast, state)

View Source (optional)
handle_selector(selector_name :: binary(), ast :: FIQLEx.ast(), state) ::
  {:ok, state} | {:error, any()}
when state: any()

This callback is invoked when a selector without a value to be compared to is found.

Parameters are:

  • selector_name: the name of the selector
  • ast: The AST returned by FIQLEx.parse/1
  • state: The current state of your query builder

This function returns {:ok, new_state} if everything is ok, or {:error, reason} if there is something wrong

Example

author.age

The selector_name is author.age

Link to this callback

handle_selector_and_value(selector_name, op, value, ast, state)

View Source (optional)
handle_selector_and_value(
  selector_name :: binary(),
  op :: :equal | :not_equal,
  value :: any(),
  ast :: FIQLEx.ast(),
  state
) :: {:ok, state} | {:error, any()}
when state: any()

This callback is invoked when a selector is found with a value it is compared to.

Parameters are:

  • selector_name: the name of the selector
  • op: the comparison operator. Either :equal or :not_equal
  • value: The value to compare the selector to
  • ast: The AST returned by FIQLEx.parse/1
  • state: The current state of your query builder

This function returns {:ok, new_state} if everything is ok, or {:error, reason} if there is something wrong

Example

author.age==25

The selector_name is author.age The op is :equal The value is 25

Link to this callback

handle_selector_and_value_with_comparison(selector_name, op, value, ast, state)

View Source (optional)
handle_selector_and_value_with_comparison(
  selector_name :: binary(),
  op :: binary(),
  value :: any(),
  ast :: FIQLEx.ast(),
  state
) :: {:ok, state} | {:error, any()}
when state: any()

This callback is invoked when a selector is found with a value it is compared to. Same as handle_selector_and_value/5 but with a custom comparison operator

Parameters are:

  • selector_name: the name of the selector
  • op: the comparison operator as a string
  • value: The value to compare the selector to
  • ast: The AST returned by FIQLEx.parse/1
  • state: The current state of your query builder

This function returns {:ok, new_state} if everything is ok, or {:error, reason} if there is something wrong

Example

author.age=ge=25

The selector_name is author.age The op is ge The value is 25

Link to this callback

init(ast, options)

View Source (optional)
init(ast :: FIQLEx.ast(), options :: Keyword.t()) :: state when state: any()

This callback is invoked as soon as you call the function FIQLEx.build_query/3.

Parameters are:

This function must return the initial state of your query builder