Use Frappe Global Search via Rest API

GlobalSearch.Md

Using Search via Rest API in Frappe Framework

If you are interested in looking at how search is implemented in Frappe, have a look here and here Frappe uses python library Whoosh, it is an open-source, pure Python search engine library which stores its index in a file system.

frappe.utils.global_search in Frappe Framework allows you to perform full text search on any doctype using a custom FullTextSearch class. It uses a third-party library called Whoosh, which is a full text search library written in Python. The code for implementing frappe.utils.global_search is in the global_search.py file of Frappe Framework.

frappe.utils.global_search is best used for searching documents that have specific or rare keywords or need advanced filtering or sorting options. It is also useful for creating custom search classes for different purposes.

It can also be used via REST via api/method/frappe.utils.global_search.search url.

The params supported by frappe.utils.global_search are

text: The keyword to search for scope: The doctype to filter the results by (optional). This can be an array too. limit: The maximum number of results to return (optional, default is 20) start: The starting index of the results (optional, default is 0) doctype: Similar to scope, you can pass a doctype to restrict search, but won't accept multiple.

To use frappe.utils.global_search via REST API, you need to send a POST request to the endpoint /api/method/frappe.utils.global_search.search with the above parameters. For example, if you want to search for the keyword ‘customer’ in the Customer doctype and get the first 10 results, you can use the following curl command:

curl -X POST \
  http://<base-url>/api/method/frappe.utils.global_search.search \
  -H 'Authorization: token api_key:api_secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "customer",
    "limit": 10,
    "scope": "Customer"
}'

If in JS

var headers = new Headers();
headers.append("Authorization", "sid or key");
headers.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "text": "search keyword",
  "start": "1",
  "limit": 2,
  "doctype": "Customer"
});

var requestOptions = {
  method: 'POST',
  headers: headers,
  body: raw,
  redirect: 'follow'
};

fetch("https://myurl.com/api/method/frappe.utils.global_search.search", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

The format returned by this endpoint is a JSON object with a list of matching records under the data key. Each record will be a frappe._dict object with the following fields:

1. name: The name of the record
2. doctype: The doctype of the record
3. content: A snippet of the record content that matches the keyword
4. route: The URL path to view the record in Frappe Framework

For example, the response might look like this

{
  "data": [
    {
      "name": "CUST-00001",
      "doctype": "Customer",
      "content": "Customer Name: Acme Corporation\nCustomer Group: All Customer Groups\nTerritory: All Territories",
      "route": "/app/customer/CUST-00001"
    },
    {
      "name": "CUST-00002",
      "doctype": "Customer",
      "content": "Customer Name: Beta Inc.\nCustomer Group: All Customer Groups\nTerritory: All Territories",
      "route": "/app/customer/CUST-00002"
    },
    ...
  ]
}

Hints on limiting search to doctype

• To search across all doctypes in index, don't specify a scope or doctype.
• To restrict search to one doctype use, "doctype" : "doctype_name" or "scope": "doctype_name".
• To restrict search to more than one doctype use, ` "scope": ["Account", "Customer","Contact", "Timesheet"]

Using in python

To use frappe.utils.global_search in Python code, you need to import the module and call the search function

import frappe
from frappe.utils.global_search import search

results = search(text='customer', scope='Customer', limit=10, start=0)

for result in results:
    print(result.name, result.content)

The search function will return a list of frappe._dict objects that match the keyword. Each object will have the following fields:

1. name: The name of the record
2. doctype: The DocType of the record
3. content: A snippet of the record content that matches the keyword
4. route: The URL path to view the record in Frappe Framework

Sometimes resource endpoint is all you need

The alternative to frappe.utils.global_search is to use the /api/resource/:doctype endpoint to get a list of records of a doctype via REST API with some filters. The parameters accepted by this endpoint are:

fields: A list of fields to fetch (optional) filters: A list of filters to apply (optional) order_by: The field name to sort by (optional) limit_start: The starting index of the results (optional, default is 0) limit_page_length: The maximum number of results to return (optional, default is 20)

For example, if you want to get the first 10 records of Customer doctype with only name and email fields, you can use the following curl command:

curl -X GET \
  http://<base-url>/api/resource/Customer \
  -H 'Authorization: token api_key:api_secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "fields": ["name", "email"],
    "limit_page_length": 10
}'

The format returned by this endpoint is a JSON object with a list of records under the data key. Each record will be a JSON object with the requested fields as keys and values. For example, the response might look like this:

{
  "data": [
    {
      "name": "CUST-00001",
      "email": "[email protected]"
    },
    {
      "name": "CUST-00002",
      "email": "[email protected]"
    },
    ...
  ]
}

REST API Request Format Update

REST API request format, reflecting the change from scope to doctype for proper results:

curl -X POST \
  http://<base-url>/api/method/frappe.utils.global_search.search \
  -H 'Authorization: token api_key:api_secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "customer",
    "limit": 10,
    "doctype": "Customer"
}'

Additional Information

Global Search in Custom Doctype: To enable global search functionality for a custom doctype, ensure that the doctype is added to the list in Global Search Settings within your application.