Frappe Search API in Version 15

The Search API in Frappe v15 allows developers to perform full-text and link-field searches across DocTypes. This includes global search (full-text indexed) and link-field suggestions used in forms. The search APIs help implement features like autocomplete, quick-search bars, or custom search pages.

What kinds of search does Frappe support?

Frappe provides two major search mechanisms:

How to use Full-text / Global Search in Frappe v15

What does frappe.utils.global_search.search do?

• Performs a full-text search across all configured DocTypes and fields.
• Returns a list of matched records (doctype, name, content snippet, etc.). Frappe Documentation+1

Basic usage (server-side)

import frappe
from frappe.utils.global_search import search
results = search(text="apple iPod", start=0, limit=50)
for r in results:
print(r.doctype, r.name, r.content)

Typical response structure (as JSON via REST)

When used via REST (/api/method/frappe.utils.global_search.search), the response is:
{
"message": [
{
"doctype": "Item",
"name": "ITEM-0001",
"content": "Item Name : iPod Touch ||| Description : black iPod with 16GB ...",
"rank": 1,
"image": ""
},
...
]
}

This allows building search UIs, global search bars, or custom search pages. Gist+1

When should you use global search

• Building site-wide search bars (e.g. in ERPNext “Awesome Bar”).
• Searching across multiple DocTypes (e.g. Items, Customers, Sales Orders).
• Quick-search or fuzzy search requirements.

How to use Link-field / DocType Search with search_link

When you need to implement a field autocomplete (e.g. selecting a Customer in a form), or a UI that suggests names, you use the Link-field search API.

Example: calling the search endpoint

GET /api/method/frappe.desk.search.search_link?doctype=Customer&txt=Acme&page_length=10

Parameters:

• doctype (required): name of the DocType to search
• txt (required): search text (partial or full)
• page_length (optional): number of results to return
• filters (optional): additional filter conditions

This returns a list of matching documents based on the DocType’s “search fields,” which are configured in the DocType metadata.

This API is ideal when you want to replicate the standard “Link” behaviour in desk forms, but in custom UI or REST endpoints.

Important considerations & best practices

Permissions & Security

• Search results may expose data which a user should not see. Always ensure permission checks are applied when exposing search results via custom endpoints.
• The global search API historically had issues with insufficient access control — make sure to test thoroughly after upgrades. Altion+1

Performance & Indexing

• Full-text search relies on Frappe’s search index; if indexing is not up-to-date, results may be stale. Regularly run background jobs to maintain index freshness.
• For large data sets, prefer using link-field search (on specific DocTypes) rather than global search for better performance.

Fuzzy and E-commerce-style Search

• For very advanced search (fuzzy matching, ranking, autocomplete, faceted search) — especially in e-commerce — consider integrating search engines like RediSearch (as used by ERPNext E-Commerce module) to complement or replace built-in full-text search.

When to use which search method

Related Topics & Cross-References

• Global Search User Guide (for end users) — explains how the search bar works in ERPNext UI.
• Search Integration with E-Commerce — combining Frappe + RediSearch for advanced product search.
• DocType Metadata: Search Fields Configuration — how DocType search fields influence search_link behaviour.
• REST API for resources — for combining search results with standard resource APIs.