Overriding Link Query in Frappe Framework (v15)

Introduction: Why Override Link Queries?

Link fields are central to ERPNext workflows. By default, a Link field shows all records of the linked DocType. In real-world ERP implementations, this behavior is often insufficient.
Frappe Framework v15 allows developers to override Link field queries using client scripts, enabling:

• Context-aware dropdown values
• Business rule enforcement
• Cleaner, error-free data entry

This guide explains how to override link queries correctly and safely in Frappe v15.

What Is a Link Query in Frappe?

A Link Query determines how records are fetched and displayed inside a Link field dropdown.

By default:

• Frappe queries the linked DocType
• No additional filters are applied
• All permitted records are shown

Overriding the query allows developers to filter, restrict, or customize this behavior.

When Should You Override a Link Query?

You should override a link query when:

• Dropdown options depend on another field
• Only active or approved records should be selectable
• Business logic must be enforced at entry level
• You want to reduce user errors and rework

How to Override a Link Query in Frappe?

The recommended approach in Frappe Framework v15 is using the get_query method inside a client script.

Basic Example: Override Link Query Using Client Script

Scenario

Filter a Customer Link field to show only customers in a selected territory.

Client Script (v15 Compatible)

frappe.ui.form.on('Sales Order', {
onload: function(frm) {
frm.set_query('customer', function() {
return {
filters: {
territory: frm.doc.territory
}
};
});
}
});

Key Concepts

• frm.set_query() overrides the default query
• Filters are applied dynamically
• Runs entirely on the client side

✔ Fully supported in Frappe v15
✔ No server restart required

How Does frm.set_query() Work?

frm.set_query(fieldname, callback) assigns a custom query function to a Link field.

Callback Return Structure

{
filters: { ... }
}

Optional keys:

• query → Custom server method
• filters → Standard DocType filters

Using Multiple Filters in a Link Query

frm.set_query('item_code', function() {
return {
filters: {
is_stock_item: 1,
disabled: 0
}
};
});

Best Use Case

• Restrict inactive records
• Enforce master data quality

How to Override Link Query Using a Custom Server Method?

Use this approach when:

• Logic is complex
• Performance matters
• Filters require joins or conditions

Client Script

frm.set_query('supplier', function() {
return {
query: 'my_app.api.get_active_suppliers',
filters: {
country: frm.doc.country
}
};
});

Server Script (Python – Frappe v15)

@frappe.whitelist()
def get_active_suppliers(doctype, txt, searchfield, start, page_len, filters):
return frappe.db.get_list(
'Supplier',
filters={
'disabled': 0,
'country': filters.get('country')
},
fields=['name'],
start=start,
page_length=page_len
)

✔ Uses standard Frappe query signature
✔ Safe and upgrade-friendly

Overriding Link Query in Child Table Fields

Child table fields require referencing cdt and cdn.

frm.set_query('batch_no', 'items', function(doc, cdt, cdn) {
let row = locals[cdt][cdn];
return {
filters: {
item: row.item_code
}
};
});

Common Use Case

• Batch filtering per item
• Warehouse-specific selections

Best Practices for Overriding Link Queries

Performance Best Practices

• Prefer client-side filters when simple
• Use server queries only when needed
• Avoid heavy joins inside queries

UX Best Practices

• Ensure dependent fields are filled first
• Add field dependencies where required
• Keep dropdowns small and meaningful

Common Mistakes to Avoid

Real-World ERPNext Use Cases

Accounting

• Show only active Cost Centers
• Filter Accounts by Company

Manufacturing

• Filter BOMs by Item
• Restrict Workstations

CRM

• Filter Leads by Status
• Show only active Sales Persons

Industry Relevance

Overriding link queries is critical in:

• Manufacturing ERP
• Finance & Accounting
• Supply Chain Management
• Real Estate ERP Solutions

It ensures data accuracy at the point of entry.

Target Audience

• ERPNext Developers
• Frappe Framework Consultants
• ERP Implementers
• Functional & Technical Consultan

Troubleshooting Common Issues

Link Field Shows No Data

• Check filter values
• Ensure dependent fields are set
• Validate permission rules

Custom Query Not Triggering

• Confirm script is loaded
• Check fieldname spelling
• Verify DocType name

Summary: Mastering Link Queries in Frappe v15

In Frappe Framework v15, overriding link queries using frm.set_query() is the recommended, upgrade-safe approach to control data selection.

When implemented correctly, it:

• Improves user experience
• Prevents data inconsistencies
• Enforces real business logic