Skip to content

Commit 9673a3d

Browse files
author
bosd
committed
[ADD] base_sparse_field_jsonb_search
1 parent 1718574 commit 9673a3d

File tree

16 files changed

+1226
-0
lines changed

16 files changed

+1226
-0
lines changed

‎base_sparse_field_jsonb_search/README.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
## Introduction
2+
3+
This module enables native PostgreSQL JSONB search operators for sparse fields stored in
4+
Serialized containers.
5+
6+
When combined with `base_sparse_field_jsonb`, which upgrades Serialized fields from TEXT
7+
to JSONB storage, this module translates Odoo search domains into native PostgreSQL
8+
JSONB operators for significantly improved query performance.
9+
10+
## Performance Improvement
11+
12+
Without this module, searching on sparse fields requires:
13+
14+
1. Loading all records from the database
15+
2. Deserializing JSON data in Python
16+
3. Filtering records in Python memory
17+
18+
With this module, the same search uses native PostgreSQL:
19+
20+
```sql
21+
-- Native JSONB query (fast, uses GIN index)
22+
SELECT * FROM product_template
23+
WHERE x_custom_json->>'x_color' = 'red'
24+
```
25+
26+
## Supported Operators
27+
28+
| Odoo Operator | JSONB Translation |
29+
| -------------------- | ------------------------------- |
30+
| `=` | `jsonb->>'key' = 'value'` |
31+
| `!=` | `jsonb->>'key' != 'value'` |
32+
| `in` | `jsonb->>'key' IN (...)` |
33+
| `not in` | `jsonb->>'key' NOT IN (...)` |
34+
| `like` | `jsonb->>'key' LIKE '%value%'` |
35+
| `ilike` | `jsonb->>'key' ILIKE '%value%'` |
36+
| `>`, `>=`, `<`, `<=` | Numeric cast + comparison |
37+
38+
## Boolean Fields
39+
40+
Boolean sparse fields are handled specially:
41+
42+
```sql
43+
-- Check if boolean field is True
44+
WHERE (jsonb->'field')::boolean = TRUE
45+
46+
-- Check if boolean field is False or not set
47+
WHERE (jsonb->'field' IS NULL OR (jsonb->'field')::boolean = FALSE)
48+
```
49+
50+
## Usage
51+
52+
## Automatic Activation
53+
54+
This module auto-installs when `base_sparse_field_jsonb` is installed. No additional
55+
configuration is required.
56+
57+
## How It Works
58+
59+
When you search on a model with sparse fields:
60+
61+
```python
62+
# Standard Odoo search on a sparse field
63+
products = self.env['product.template'].search([
64+
('x_color', '=', 'red'),
65+
('x_manufacturing_year', 'in', ['2022', '2023', '2024']),
66+
])
67+
```
68+
69+
The module automatically:
70+
71+
1. Detects that `x_color` and `x_manufacturing_year` are sparse fields
72+
2. Identifies their container field (e.g., `x_custom_json`)
73+
3. Translates the domain to JSONB operators
74+
4. Executes the query using PostgreSQL's GIN index
75+
76+
## Debugging
77+
78+
Enable debug logging to see the JSONB translations:
79+
80+
```python
81+
import logging
82+
logging.getLogger('odoo.addons.base_sparse_field_jsonb_search').setLevel(logging.DEBUG)
83+
```
84+
85+
This will log messages like:
86+
87+
```
88+
JSONB search: product_template.x_color = 'red' -> x_custom_json->>'x_color'
89+
```
90+
91+
## Limitations
92+
93+
- Sorting on sparse fields is not supported (would require additional indexes)
94+
- Complex nested JSON paths are not supported
95+
- Full-text search requires additional configuration
96+
97+
## Contributors
98+
99+
- OBS Solutions B.V. <https://www.obs-solutions.com>
100+
- Stefcy <[email protected]>
101+
102+
## Credits
103+
104+
## Development
105+
106+
This module was developed by OBS Solutions B.V.

‎base_sparse_field_jsonb_search/README.rst‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
.. image:: https://odoo-community.org/readme-banner-image
2+
:target: https://odoo-community.org/get-involved?utm_source=readme
3+
:alt: Odoo Community Association
4+
5+
==============================
6+
Base Sparse Field JSONB Search
7+
==============================
8+
9+
..
10+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
11+
!! This file is generated by oca-gen-addon-readme !!
12+
!! changes will be overwritten. !!
13+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
14+
!! source digest: sha256:616a86600d04410afe4aa253e949cb8c75c79e513145b2f1a98812a1fd60be8f
15+
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
16+
17+
.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
18+
:target: https://odoo-community.org/page/development-status
19+
:alt: Beta
20+
.. |badge2| image:: https://img.shields.io/badge/license-LGPL--3-blue.png
21+
:target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
22+
:alt: License: LGPL-3
23+
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fserver--tools-lightgray.png?logo=github
24+
:target: https://github.com/OCA/server-tools/tree/19.0/base_sparse_field_jsonb_search
25+
:alt: OCA/server-tools
26+
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
27+
:target: https://translation.odoo-community.org/projects/server-tools-19-0/server-tools-19-0-base_sparse_field_jsonb_search
28+
:alt: Translate me on Weblate
29+
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
30+
:target: https://runboat.odoo-community.org/builds?repo=OCA/server-tools&target_branch=19.0
31+
:alt: Try me on Runboat
32+
33+
|badge1| |badge2| |badge3| |badge4| |badge5|
34+
35+
This module enables native PostgreSQL JSONB search operators for sparse
36+
fields stored in Serialized containers.
37+
38+
When combined with ``base_sparse_field_jsonb``, which upgrades
39+
Serialized fields from TEXT to JSONB storage, this module translates
40+
Odoo search domains into native PostgreSQL JSONB operators for
41+
significantly improved query performance.
42+
43+
Performance Improvement
44+
-----------------------
45+
46+
Without this module, searching on sparse fields requires:
47+
48+
1. Loading all records from the database
49+
2. Deserializing JSON data in Python
50+
3. Filtering records in Python memory
51+
52+
With this module, the same search uses native PostgreSQL:
53+
54+
.. code:: sql
55+
56+
-- Native JSONB query (fast, uses GIN index)
57+
SELECT * FROM product_template
58+
WHERE x_custom_json->>'x_color' = 'red'
59+
60+
Supported Operators
61+
-------------------
62+
63+
============================ =================================
64+
Odoo Operator JSONB Translation
65+
============================ =================================
66+
``=`` ``jsonb->>'key' = 'value'``
67+
``!=`` ``jsonb->>'key' != 'value'``
68+
``in`` ``jsonb->>'key' IN (...)``
69+
``not in`` ``jsonb->>'key' NOT IN (...)``
70+
``like`` ``jsonb->>'key' LIKE '%value%'``
71+
``ilike`` ``jsonb->>'key' ILIKE '%value%'``
72+
``>``, ``>=``, ``<``, ``<=`` Numeric cast + comparison
73+
============================ =================================
74+
75+
Boolean Fields
76+
--------------
77+
78+
Boolean sparse fields are handled specially:
79+
80+
.. code:: sql
81+
82+
-- Check if boolean field is True
83+
WHERE (jsonb->'field')::boolean = TRUE
84+
85+
-- Check if boolean field is False or not set
86+
WHERE (jsonb->'field' IS NULL OR (jsonb->'field')::boolean = FALSE)
87+
88+
**Table of contents**
89+
90+
.. contents::
91+
:local:
92+
93+
Usage
94+
=====
95+
96+
Automatic Activation
97+
--------------------
98+
99+
This module auto-installs when ``base_sparse_field_jsonb`` is installed.
100+
No additional configuration is required.
101+
102+
How It Works
103+
------------
104+
105+
When you search on a model with sparse fields:
106+
107+
.. code:: python
108+
109+
# Standard Odoo search on a sparse field
110+
products = self.env['product.template'].search([
111+
('x_color', '=', 'red'),
112+
('x_manufacturing_year', 'in', ['2022', '2023', '2024']),
113+
])
114+
115+
The module automatically:
116+
117+
1. Detects that ``x_color`` and ``x_manufacturing_year`` are sparse
118+
fields
119+
2. Identifies their container field (e.g., ``x_custom_json``)
120+
3. Translates the domain to JSONB operators
121+
4. Executes the query using PostgreSQL's GIN index
122+
123+
Debugging
124+
---------
125+
126+
Enable debug logging to see the JSONB translations:
127+
128+
.. code:: python
129+
130+
import logging
131+
logging.getLogger('odoo.addons.base_sparse_field_jsonb_search').setLevel(logging.DEBUG)
132+
133+
This will log messages like:
134+
135+
::
136+
137+
JSONB search: product_template.x_color = 'red' -> x_custom_json->>'x_color'
138+
139+
Limitations
140+
-----------
141+
142+
- Sorting on sparse fields is not supported (would require additional
143+
indexes)
144+
- Complex nested JSON paths are not supported
145+
- Full-text search requires additional configuration
146+
147+
Bug Tracker
148+
===========
149+
150+
Bugs are tracked on `GitHub Issues <https://github.com/OCA/server-tools/issues>`_.
151+
In case of trouble, please check there if your issue has already been reported.
152+
If you spotted it first, help us to smash it by providing a detailed and welcomed
153+
`feedback <https://github.com/OCA/server-tools/issues/new?body=module:%20base_sparse_field_jsonb_search%0Aversion:%2019.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
154+
155+
Do not contact contributors directly about support or help with technical issues.
156+
157+
Credits
158+
=======
159+
160+
Authors
161+
-------
162+
163+
* OBS Solutions B.V.
164+
165+
Contributors
166+
------------
167+
168+
- OBS Solutions B.V. https://www.obs-solutions.com
169+
- Stefcy [email protected]
170+
171+
Other credits
172+
-------------
173+
174+
Development
175+
~~~~~~~~~~~
176+
177+
This module was developed by OBS Solutions B.V.
178+
179+
Maintainers
180+
-----------
181+
182+
This module is maintained by the OCA.
183+
184+
.. image:: https://odoo-community.org/logo.png
185+
:alt: Odoo Community Association
186+
:target: https://odoo-community.org
187+
188+
OCA, or the Odoo Community Association, is a nonprofit organization whose
189+
mission is to support the collaborative development of Odoo features and
190+
promote its widespread use.
191+
192+
This module is part of the `OCA/server-tools <https://github.com/OCA/server-tools/tree/19.0/base_sparse_field_jsonb_search>`_ project on GitHub.
193+
194+
You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.

‎base_sparse_field_jsonb_search/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
from . import models

‎base_sparse_field_jsonb_search/__manifest__.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"name": "Base Sparse Field JSONB Search",
3+
"version": "19.0.1.0.0",
4+
"category": "Technical",
5+
"summary": "Enable native PostgreSQL JSONB operators in Odoo search domains",
6+
"author": "OBS Solutions B.V., Odoo Community Association (OCA)",
7+
"website": "https://github.com/OCA/server-tools",
8+
"license": "LGPL-3",
9+
"depends": [
10+
"base_sparse_field_jsonb",
11+
],
12+
"data": [],
13+
"installable": True,
14+
"auto_install": True,
15+
}

‎base_sparse_field_jsonb_search/models/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
from . import base_model
2+
from . import expression_patch

0 commit comments

Comments
 (0)