# Dash Query Builder
Component for Dash based on [react-awesome-query-builder](https://github.com/ukrbublik/react-awesome-query-builder).
The component is a way to graphically generate WHERE clauses for SQL queries.
## Install
```shell
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](https://github.com/ukrbublik/react-awesome-query-builder/blob/master/CONFIG.adoc#configfields).
The only caveat is that JavaScript cannot be used as in the example.
For instance the following dictionary is valid:
```python
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:
```python
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:
https://github.com/TillerBurr/dash-query-builder/assets/49296311/1fdc9663-fde7-4c26-a706-00b5edc9f902
There are other properties available as well, with defaults in parentheses.
- config({}): see [CONFIG.adoc](https://github.com/ukrbublik/react-awesome-query-builder/blob/master/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.
1. `loadFormat=="spelFormat"`: Set `spelFormat` to a valid SpEL string.
1. `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`:
https://github.com/TillerBurr/dash-query-builder/assets/49296311/1191a643-27c0-4a4f-8032-2eb5d4b1d88e
## 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](https://peps.python.org/pep-0249/#paramstyle).
### Example
```python
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](https://github.com/astral-sh/uv) for Python virtual environment and dependencies.
- [just](https://github.com/casey/just) for common commands
- [mise-en-place](https://mise.jdx.dev) to manage the toolchain.
## Development
### Getting Started
1. Create a Python environment from previous step 1 and install:
```shell
just sync
```
1. Update the requirements and dev requirements
```shell
just compile
```
1. Build
```shell
just build
```
1. Publish
```shell
just publish
```
1. See all commands with `just -l`
Raw data
{
"_id": null,
"home_page": null,
"name": "dash-query-builder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "dash, dash-query-builder",
"author": null,
"author_email": "Tyler Baur <baur.tyler@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/96/4f/b2f17667d64a2bf36d4d9ad00edfd41edd42e0436798be8f26334fecdf94/dash_query_builder-1.0.1.tar.gz",
"platform": null,
"description": "# Dash Query Builder\n\nComponent for Dash based on [react-awesome-query-builder](https://github.com/ukrbublik/react-awesome-query-builder).\nThe component is a way to graphically generate WHERE clauses for SQL queries.\n\n## Install\n\n```shell\npip install dash_query_builder\n```\n\n## Usage\n\nTo use Dash Query Builder (DQB), you need to have a Dash app and a dictionary of fields.\nThe fields property is a dictionary of fields and their properties, following the\n[config.fields docs](https://github.com/ukrbublik/react-awesome-query-builder/blob/master/CONFIG.adoc#configfields).\nThe only caveat is that JavaScript cannot be used as in the example.\n\nFor instance the following dictionary is valid:\n\n```python\nfields = {\n \"qty\": {\n \"label\": \"Qty\",\n \"type\": \"number\",\n \"fieldSettings\": {\"min\": 0},\n \"valueSources\": [\"value\"],\n \"preferWidgets\": [\"number\"],\n },\n \"price\": {\n \"label\": \"Price\",\n \"type\": \"number\",\n \"valueSources\": [\"value\"],\n \"fieldSettings\": {\"min\": 10, \"max\": 100},\n \"preferWidgets\": [\"slider\", \"rangeslider\"],\n \"operators\": [\"equal\", \"between\"],\n },\n \"color\": {\n \"label\": \"Color\",\n \"type\": \"select\",\n \"valueSources\": [\"value\"],\n \"fieldSettings\": {\n \"listValues\": [\n {\"value\": \"yellow\", \"title\": \"Yellow\"},\n {\"value\": \"green\", \"title\": \"Green\"},\n {\"value\": \"orange\", \"title\": \"Orange\"},\n ]\n },\n },\n \"is_promotion\": {\n \"label\": \"Promo?\",\n \"type\": \"boolean\",\n \"operators\": [\"equal\", \"is_empty\"],\n \"valueSources\": [\"value\"],\n },\n}\n```\n\nThe basic component can be created via:\n\n```python\nfrom dash import Dash, html\nimport dash_query_builder as dqb\nfields =...\napp=Dash(__name__)\napp.layout=html.Div([dqb.DashQueryBuilder(fields=fields)])\napp.run_server()\n```\n\nThis will run the app similar to this:\n\nhttps://github.com/TillerBurr/dash-query-builder/assets/49296311/1fdc9663-fde7-4c26-a706-00b5edc9f902\n\nThere are other properties available as well, with defaults in parentheses.\n\n- config({}): see [CONFIG.adoc](https://github.com/ukrbublik/react-awesome-query-builder/blob/master/CONFIG.adoc) for full options\n- theme(\"basic\"): one of \"antd\", \"mui\", \"fluent\", \"bootstrap\", \"basic\"\n- loadFormat(\"tree\"): one of \"tree\", \"spelFormat\", \"jsonLogicFormat\"\n- alwaysShowActionButtons(True): A boolean whether to always show action buttons, e.g. \"Add Rule\", \"Add Group\", etc.\n\nWith the above parameters, a query builder will be created with an empty tree. To pre-populate the query builder,\nthere are several ways to do so:\n\n1. `loadFormat==\"tree\"`: Set `tree` to a valid tree object.\n1. `loadFormat==\"spelFormat\"`: Set `spelFormat` to a valid SpEL string.\n1. `loadFormat==\"jsonLogicFormat\"`: Set `jsonLogicFormat` to a valid jsonLogic object.\n\nOnce `loadFormat` is set, the tree/query builder will update when the query is changed or when the corresponding property is changed.\nThe `loadFormat` can be changed via a callback, while keeping the same tree.\n\nHere's an example using `usage.py`:\n\nhttps://github.com/TillerBurr/dash-query-builder/assets/49296311/1191a643-27c0-4a4f-8032-2eb5d4b1d88e\n\n## Where Parser\n\nDQB 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.\nIt will parse the query and return a template string and a parameter dictionary. The template string will be in `pyformat` style, as\nspecified in [PEP 249](https://peps.python.org/pep-0249/#paramstyle).\n\n### Example\n\n```python\nfrom dash_query_builder.where_parser import WhereParser\nwhere_parser = WhereParser()\ntemplate, params = where_parser.get_template(\"qty > 15 and price between 10 and 20\")\nprint(template) # (qty > %(YSaAddDFs27s)s AND price BETWEEN %(W5PRwTGpFqqF)s AND %(N2nGExcGaUSt)s)\nprint(params) # {'YSaAddDFs27s': 15, 'W5PRwTGpFqqF': 10, 'N2nGExcGaUSt': 20}\n```\n\nCurrently, only `pyformat` is supported. PRs are welcome!\n\n## Tools Used\n\n- [uv](https://github.com/astral-sh/uv) for Python virtual environment and dependencies.\n- [just](https://github.com/casey/just) for common commands\n- [mise-en-place](https://mise.jdx.dev) to manage the toolchain.\n\n## Development\n\n### Getting Started\n\n1. Create a Python environment from previous step 1 and install:\n ```shell\n just sync\n ```\n1. Update the requirements and dev requirements\n ```shell\n just compile\n ```\n1. Build\n ```shell\n just build\n ```\n1. Publish\n ```shell\n just publish\n ```\n1. See all commands with `just -l`\n",
"bugtrack_url": null,
"license": null,
"summary": "Component for Dash based on react-awesome-query-builder",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/tillerburr/dash-query-builder",
"Issues": "https://github.com/tillerburr/dash-query-builder/issues",
"Repository": "https://github.com/tillerburr/dash-query-builder"
},
"split_keywords": [
"dash",
" dash-query-builder"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b712110a661d3e7e0087491bddf84dd6743b8609ca8fd10c4da3eb920321f901",
"md5": "a169eda85289728e1f609862e8ccbb9b",
"sha256": "3b7a4a38acd10c7acb9231cf52e44fdfdf241ee7daa74d5cb5d81328dd930c35"
},
"downloads": -1,
"filename": "dash_query_builder-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a169eda85289728e1f609862e8ccbb9b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 878257,
"upload_time": "2025-07-18T02:19:00",
"upload_time_iso_8601": "2025-07-18T02:19:00.328377Z",
"url": "https://files.pythonhosted.org/packages/b7/12/110a661d3e7e0087491bddf84dd6743b8609ca8fd10c4da3eb920321f901/dash_query_builder-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "964fb2f17667d64a2bf36d4d9ad00edfd41edd42e0436798be8f26334fecdf94",
"md5": "b9bf605a49fb40abd4e72b20907005dd",
"sha256": "6a0596c0c5a0557f28c314a56afd18b17d6985f12a377ce98cf210bf990afdaa"
},
"downloads": -1,
"filename": "dash_query_builder-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "b9bf605a49fb40abd4e72b20907005dd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 852482,
"upload_time": "2025-07-18T02:19:01",
"upload_time_iso_8601": "2025-07-18T02:19:01.747109Z",
"url": "https://files.pythonhosted.org/packages/96/4f/b2f17667d64a2bf36d4d9ad00edfd41edd42e0436798be8f26334fecdf94/dash_query_builder-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 02:19:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tillerburr",
"github_project": "dash-query-builder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "blinker",
"specs": [
[
"==",
"1.7.0"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2024.2.2"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.3.2"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.7"
]
]
},
{
"name": "dash",
"specs": [
[
"==",
"2.16.1"
]
]
},
{
"name": "dash-core-components",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "dash-html-components",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "dash-table",
"specs": [
[
"==",
"5.0.0"
]
]
},
{
"name": "flask",
"specs": [
[
"==",
"3.0.3"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.7"
]
]
},
{
"name": "importlib-metadata",
"specs": [
[
"==",
"7.1.0"
]
]
},
{
"name": "itsdangerous",
"specs": [
[
"==",
"2.2.0"
]
]
},
{
"name": "jinja2",
"specs": [
[
"==",
"3.1.3"
]
]
},
{
"name": "markupsafe",
"specs": [
[
"==",
"2.1.5"
]
]
},
{
"name": "nest-asyncio",
"specs": [
[
"==",
"1.6.0"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.0"
]
]
},
{
"name": "plotly",
"specs": [
[
"==",
"5.21.0"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.31.0"
]
]
},
{
"name": "retrying",
"specs": [
[
"==",
"1.3.4"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"69.5.1"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "tenacity",
"specs": [
[
"==",
"8.2.3"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
"==",
"4.11.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.2.1"
]
]
},
{
"name": "werkzeug",
"specs": [
[
"==",
"3.0.2"
]
]
},
{
"name": "zipp",
"specs": [
[
"==",
"3.18.1"
]
]
}
],
"lcname": "dash-query-builder"
}
JSON
