frappe-core-search

Name: frappe-core-search
Author: Impertio-Studio

151stars49forks

How to install frappe-core-search?

impertio-studio/frappe_claude_skill_package/frappe-core-search

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-core-search

Installs into the current project.

Summary

Use when implementing search functionality in Frappe v14-v16. Covers link field search (search_link), global search, FullTextSearch (Whoosh), SQLiteSearch FTS5 [v15+], Awesomebar customization, search_fields configuration, custom search queries, and website search. Prevents commo

Files · 1

View on GitHub

SKILL.md

1	# Frappe Search System
2
3	## Four Search Subsystems
4
5	\| Subsystem \| Module \| Purpose \| Real-time? \|
6	\|-----------\|--------\|---------\|:----------:\|
7	\| Link Field Search \| `frappe.desk.search` \| Autocomplete in link fields \| Yes \|
8	\| Global Search \| `frappe.utils.global_search` \| Cross-doctype search (desk + web) \| No (15min sync) \|
9	\| FullTextSearch \| `frappe.search.full_text_search` \| Whoosh-based index (website) \| On rebuild \|
10	\| SQLiteSearch [v15+] \| `frappe.search.sqlite_search` \| FTS5 with scoring + spelling \| Yes (5min queue) \|
11
12	---
13
14	## Decision Tree
15
16	```
17	What search do you need?
18	│
19	├─ Link field autocomplete (user types in a Link field)?
20	│ ├─ Default behavior sufficient → Configure search_fields on DocType
21	│ └─ Custom logic needed → standard_queries hook or query parameter
22	│
23	├─ Cross-doctype search (user searches for anything)?
24	│ ├─ Desk users → Global Search (auto-enabled)
25	│ │ └─ Set in_global_search=1 on important fields
26	│ └─ Website visitors → web_search() or WebsiteSearch (Whoosh)
27	│
28	├─ Custom full-text search for your app [v15+]?
29	│ └─ SQLiteSearch subclass + sqlite_search hook
30	│ → Spelling correction, recency boost, custom scoring
31	│
32	└─ Awesomebar customization?
33	└─ Client-side: override build_options or use search dialog
34	```
35
36	---
37
38	## Link Field Search
39
40	### Configuring search_fields (Most Common Need)
41
42	```python
43	# In DocType JSON or via customize form
44	{
45	"search_fields": "customer_name, customer_group",
46	"title_field": "customer_name",
47	"show_title_field_in_link": 1
48	}
49	```
50
51	ALWAYS set `search_fields` — Without it, users can only search by `name` (often a code like `CUST-001`).
52
53	### How Link Search Works
54
55	1. User types in link field → calls `search_link(doctype, txt)`
56	2. Searches across: `name` + `title_field` + `search_fields`
57	3. Allowed field types: Data, Text, Small Text, Long Text, Link, Select, Autocomplete, Read Only, Text Editor
58	4. Prefix matches rank higher than substring matches
59	5. Respects `enabled`/`disabled` fields automatically
60
61	### Custom Link Query
62
63	```python
64	# hooks.py — override search for a specific DocType
65	standard_queries = {
66	"Customer": "my_app.queries.customer_query"
67	}
68	```
69
70	```python
71	# my_app/queries.py — MUST be @frappe.whitelist()
72	@frappe.whitelist()
73	def customer_query(doctype, txt, searchfield, start, page_length, filters,
74	as_dict=False, reference_doctype=None,
75	ignore_user_permissions=False):
76	# Return list of dicts: [{"value": name, "description": label}, ...]
77	return frappe.db.sql("""
78	SELECT name, customer_name as description
79	FROM `tabCustomer`
80	WHERE (name LIKE %(txt)s OR customer_name LIKE %(txt)s)
81	AND status = 'Active'
82	ORDER BY customer_name
83	LIMIT %(start)s, %(page_length)s
84	""", {"txt": f"%{txt}%", "start": start, "page_length": page_length},
85	as_dict=True)
86	```
87
88	### Per-Field Query Override
89
90	```javascript
91	// In Client Script or Form JS
92	frappe.ui.form.on("Sales Order", {
93	setup(frm) {
94	frm.set_query("customer", () => ({
95	filters: { status: "Active", territory: frm.doc.territory }
96	}));
97	}
98	});
99	```
100
101	---
102
103	## Global Search
104
105	### Enabling
106
107	Set `in_global_search = 1` on DocType fields that should be searchable.
108
109	### How It Works
110
111	- Indexed fields stored in `__global_search` table
112	- Synced via Redis queue every 15 minutes
113	- Uses DB-native fulltext: MariaDB `MATCH...AGAINST`, PostgreSQL `TSVECTOR`
114	- Permission-filtered results
115
116	### Rebuilding Index
117
118	```python
119	# Rebuild for specific DocType
120	from frappe.utils.global_search import rebuild_for_doctype
121	rebuild_for_doctype("Sales Order")
122
123	# Rebuild everything
124	from frappe.utils.global_search import rebuild
125	rebuild()
126	```
127
128	### hooks.py Configuration
129
130	```python
131	# Default doctypes for global search
132	global_search_doctypes = {
133	"Default": [
134	{"doctype": "Contact"},
135	{"doctype": "Customer"},
136	{"doctype": "Sales Order"},
137	]
138	}
139	```
140
141	---
142
143	## SQLiteSearch [v15+]
144
145	### Creating Custom Search
146
147	```python
148	# my_app/search.py
149	from frappe.search.sqlite_search import SQLiteSearch
150
151	class ProjectSearch(SQLiteSearch):
152	INDEX_SCHEMA = {
153	"metadata_fields": ["project", "owner", "status"],

People who liked this also viewed

6 picks

Type

frappe-core-search

151stars49forks

View on GitHub

How to install frappe-core-search?

impertio-studio/frappe_claude_skill_package/frappe-core-search

$npx -y skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-core-search

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Frappe Search System
2
3	## Four Search Subsystems
4
5	\| Subsystem \| Module \| Purpose \| Real-time? \|
6	\|-----------\|--------\|---------\|:----------:\|
7	\| Link Field Search \| `frappe.desk.search` \| Autocomplete in link fields \| Yes \|
8	\| Global Search \| `frappe.utils.global_search` \| Cross-doctype search (desk + web) \| No (15min sync) \|
9	\| FullTextSearch \| `frappe.search.full_text_search` \| Whoosh-based index (website) \| On rebuild \|
10	\| SQLiteSearch [v15+] \| `frappe.search.sqlite_search` \| FTS5 with scoring + spelling \| Yes (5min queue) \|
11
12	---
13
14	## Decision Tree
15
16	```
17	What search do you need?
18	│
19	├─ Link field autocomplete (user types in a Link field)?
20	│ ├─ Default behavior sufficient → Configure search_fields on DocType
21	│ └─ Custom logic needed → standard_queries hook or query parameter
22	│
23	├─ Cross-doctype search (user searches for anything)?
24	│ ├─ Desk users → Global Search (auto-enabled)
25	│ │ └─ Set in_global_search=1 on important fields
26	│ └─ Website visitors → web_search() or WebsiteSearch (Whoosh)
27	│
28	├─ Custom full-text search for your app [v15+]?
29	│ └─ SQLiteSearch subclass + sqlite_search hook
30	│ → Spelling correction, recency boost, custom scoring
31	│
32	└─ Awesomebar customization?
33	└─ Client-side: override build_options or use search dialog
34	```
35
36	---
37
38	## Link Field Search
39
40	### Configuring search_fields (Most Common Need)
41
42	```python
43	# In DocType JSON or via customize form
44	{
45	"search_fields": "customer_name, customer_group",
46	"title_field": "customer_name",
47	"show_title_field_in_link": 1
48	}
49	```
50
51	ALWAYS set `search_fields` — Without it, users can only search by `name` (often a code like `CUST-001`).
52
53	### How Link Search Works
54
55	1. User types in link field → calls `search_link(doctype, txt)`
56	2. Searches across: `name` + `title_field` + `search_fields`
57	3. Allowed field types: Data, Text, Small Text, Long Text, Link, Select, Autocomplete, Read Only, Text Editor
58	4. Prefix matches rank higher than substring matches
59	5. Respects `enabled`/`disabled` fields automatically
60
61	### Custom Link Query
62
63	```python
64	# hooks.py — override search for a specific DocType
65	standard_queries = {
66	"Customer": "my_app.queries.customer_query"
67	}
68	```
69
70	```python
71	# my_app/queries.py — MUST be @frappe.whitelist()
72	@frappe.whitelist()
73	def customer_query(doctype, txt, searchfield, start, page_length, filters,
74	as_dict=False, reference_doctype=None,
75	ignore_user_permissions=False):
76	# Return list of dicts: [{"value": name, "description": label}, ...]
77	return frappe.db.sql("""
78	SELECT name, customer_name as description
79	FROM `tabCustomer`
80	WHERE (name LIKE %(txt)s OR customer_name LIKE %(txt)s)
81	AND status = 'Active'
82	ORDER BY customer_name
83	LIMIT %(start)s, %(page_length)s
84	""", {"txt": f"%{txt}%", "start": start, "page_length": page_length},
85	as_dict=True)
86	```
87
88	### Per-Field Query Override
89
90	```javascript
91	// In Client Script or Form JS
92	frappe.ui.form.on("Sales Order", {
93	setup(frm) {
94	frm.set_query("customer", () => ({
95	filters: { status: "Active", territory: frm.doc.territory }
96	}));
97	}
98	});
99	```
100
101	---
102
103	## Global Search
104
105	### Enabling
106
107	Set `in_global_search = 1` on DocType fields that should be searchable.
108
109	### How It Works
110
111	- Indexed fields stored in `__global_search` table
112	- Synced via Redis queue every 15 minutes
113	- Uses DB-native fulltext: MariaDB `MATCH...AGAINST`, PostgreSQL `TSVECTOR`
114	- Permission-filtered results
115
116	### Rebuilding Index
117
118	```python
119	# Rebuild for specific DocType
120	from frappe.utils.global_search import rebuild_for_doctype
121	rebuild_for_doctype("Sales Order")
122
123	# Rebuild everything
124	from frappe.utils.global_search import rebuild
125	rebuild()
126	```
127
128	### hooks.py Configuration
129
130	```python
131	# Default doctypes for global search
132	global_search_doctypes = {
133	"Default": [
134	{"doctype": "Contact"},
135	{"doctype": "Customer"},
136	{"doctype": "Sales Order"},
137	]
138	}
139	```
140
141	---
142
143	## SQLiteSearch [v15+]
144
145	### Creating Custom Search
146
147	```python
148	# my_app/search.py
149	from frappe.search.sqlite_search import SQLiteSearch
150
151	class ProjectSearch(SQLiteSearch):
152	INDEX_SCHEMA = {
153	"metadata_fields": ["project", "owner", "status"],

People who liked this also viewed

6 picks

Type