Skip to content

Dash Component created from ukrbublik/react-awesome-query-builder

License

Notifications You must be signed in to change notification settings

TillerBurr/dash-query-builder

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Dash Query Builder

Component for Dash based on react-awesome-query-builder. The component is a way to graphically generate WHERE clauses for SQL queries.

Install

pip install dash_query_builder

Usage

To use Dash Query Builder (DQB), you need to have a Dash app and a dictionary of fields. The fields property is a dictionary of fields and their properties, following the config.fields docs. The only caveat is that JavaScript cannot be used as in the example.

For instance the following dictionary is valid:

fields = {
    "qty": {
        "label": "Qty",
        "type": "number",
        "fieldSettings": {"min": 0},
        "valueSources": ["value"],
        "preferWidgets": ["number"],
    },
    "price": {
        "label": "Price",
        "type": "number",
        "valueSources": ["value"],
        "fieldSettings": {"min": 10, "max": 100},
        "preferWidgets": ["slider", "rangeslider"],
        "operators": ["equal", "between"],
    },
    "color": {
        "label": "Color",
        "type": "select",
        "valueSources": ["value"],
        "fieldSettings": {
            "listValues": [
                {"value": "yellow", "title": "Yellow"},
                {"value": "green", "title": "Green"},
                {"value": "orange", "title": "Orange"},
            ]
        },
    },
    "is_promotion": {
        "label": "Promo?",
        "type": "boolean",
        "operators": ["equal", "is_empty"],
        "valueSources": ["value"],
    },
}

The basic component can be created via:

from dash import Dash, html
import dash_query_builder as dqb
fields =...
app=Dash(__name__)
app.layout=html.Div([dqb.DashQueryBuilder(fields=fields)])
app.run_server()

This will run the app similar to this:

Basic.Usage.mp4

There are other properties available as well, with defaults in parentheses.

  • config({}): see CONFIG.adoc for full options
  • theme("basic"): one of "antd", "mui", "fluent", "bootstrap", "basic"
  • loadFormat("tree"): one of "tree", "spelFormat", "jsonLogicFormat"
  • alwaysShowActionButtons(True): A boolean whether to always show action buttons, e.g. "Add Rule", "Add Group", etc.

With the above parameters, a query builder will be created with an empty tree. To pre-populate the query builder, there are several ways to do so:

  1. loadFormat=="tree": Set tree to a valid tree object.
  2. loadFormat=="spelFormat": Set spelFormat to a valid SpEL string.
  3. loadFormat=="jsonLogicFormat": Set jsonLogicFormat to a valid jsonLogic object.

Once loadFormat is set, the tree/query builder will update when the query is changed or when the corresponding property is changed. The loadFormat can be changed via a callback, while keeping the same tree.

Here's an example using usage.py:

LoadFormat.mp4

Where Parser

DQB has a built-in parser for SQL queries. The parser is relatively simple as far as parsers go, but it does what I need it to. It will parse the query and return a template string and a parameter dictionary. The template string will be in pyformat style, as specified in PEP 249.

Example

from dash_query_builder.where_parser import WhereParser
where_parser = WhereParser()
template, params = where_parser.get_template("qty > 15 and price between 10 and 20")
print(template) # (qty > %(YSaAddDFs27s)s AND price BETWEEN %(W5PRwTGpFqqF)s AND %(N2nGExcGaUSt)s)
print(params) # {'YSaAddDFs27s': 15, 'W5PRwTGpFqqF': 10, 'N2nGExcGaUSt': 20}

Currently, only pyformat is supported. PRs are welcome!

Tools Used

  • uv for Python virtual environment and dependencies.
  • just for common commands
  • mise-en-place to manage the toolchain.

Development

Getting Started

  1. Create a Python environment from previous step 1 and install:
    just sync
  2. Update the requirements and dev requirements
    just compile
  3. Build
    just build
  4. Publish
    just publish
  5. See all commands with just -l