[Skip to content](#main)

[→](/)

[![Avunu](/brand/avunu-logo.svg)![Avunu](/brand/avunu-logo-light.svg)](/)[Services](/services/)[Consulting](/services/consulting/)[ERP](/services/erp/)[Odoo](/services/erp/odoo/)[ERPNext](/services/erp/erpnext/)[Custom software](/services/custom-software/)[Devices & IoT](/services/devices-iot/)[Websites](/services/websites/)[Infrastructure](/services/infrastructure/)[Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

[About Avunu](/about/)[Team](/about/team/)[Insights](/insights/)[Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

- [Services](/services/)[Consulting](/services/consulting/)
- [ERP](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)
- [Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

- [About Avunu](/about/)
- [Team](/about/team/)
- [Insights](/insights/)
- [Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

[Knowledge base](/kb/)[Frappe](/kb/frappe/)Common Query Patterns

Search the knowledge basePress/

ESC

Jump to

[Browse the knowledge base](/kb/)[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

↵select↑↓navigateescclose

Search the knowledge base

[Skip to the article](#kb-article)[Frappe](/kb/frappe/)20 articles

- [Overview](/kb/frappe/)
- [Bench Operations](/kb/frappe/bench-operations/)
- [Builder Page Scripts](/kb/frappe/builder-page-scripts/)
- [Client-Side Recipes](/kb/frappe/client-side-recipes/)
- [Common Query Patterns](/kb/frappe/common-query-patterns/)
- [Custom Field Controllers](/kb/frappe/custom-field-controllers/)
- [Custom Pages](/kb/frappe/custom-pages/)
- [Custom Views](/kb/frappe/custom-views/)
- [Customizations API](/kb/frappe/customizations-api/)
- [Customizing Grid Columns for Child Tables](/kb/frappe/customizing-grid-columns-child-tables/)
- [Doctype States & Status Fields](/kb/frappe/doctype-states-status-fields/)
- [Grandchild Table Fields](/kb/frappe/grandchild-table-fields/)
- [Portal Views](/kb/frappe/portal-views/)
- [Project Structure & Hooks](/kb/frappe/project-structure-hooks/)
- [Query Builder & PyPika Extensions](/kb/frappe/query-builder-pypika/)
- [Quick Entry Forms](/kb/frappe/quick-entry-forms/)
- [Script Reports](/kb/frappe/script-reports/)
- [Testing on Live Databases](/kb/frappe/testing-live-databases/)
- [Type Annotations & Controller Overrides](/kb/frappe/type-annotations-controller-overrides/)
- [Vite & TypeScript Compilation](/kb/frappe/vite-typescript-compilation/)
- [Web Forms](/kb/frappe/web-forms/)

Other sections[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

In Frappe: 20 articles

[Overview](/kb/frappe/)[Bench Operations](/kb/frappe/bench-operations/)[Builder Page Scripts](/kb/frappe/builder-page-scripts/)[Client-Side Recipes](/kb/frappe/client-side-recipes/)[Common Query Patterns](/kb/frappe/common-query-patterns/)[Custom Field Controllers](/kb/frappe/custom-field-controllers/)[Custom Pages](/kb/frappe/custom-pages/)[Custom Views](/kb/frappe/custom-views/)[Customizations API](/kb/frappe/customizations-api/)[Customizing Grid Columns for Child Tables](/kb/frappe/customizing-grid-columns-child-tables/)[Doctype States & Status Fields](/kb/frappe/doctype-states-status-fields/)[Grandchild Table Fields](/kb/frappe/grandchild-table-fields/)[Portal Views](/kb/frappe/portal-views/)[Project Structure & Hooks](/kb/frappe/project-structure-hooks/)[Query Builder & PyPika Extensions](/kb/frappe/query-builder-pypika/)[Quick Entry Forms](/kb/frappe/quick-entry-forms/)[Script Reports](/kb/frappe/script-reports/)[Testing on Live Databases](/kb/frappe/testing-live-databases/)[Type Annotations & Controller Overrides](/kb/frappe/type-annotations-controller-overrides/)[Vite & TypeScript Compilation](/kb/frappe/vite-typescript-compilation/)[Web Forms](/kb/frappe/web-forms/)

Other sections[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

FrappeCommon Query Patterns

Everyday ways to read Frappe data from Python and JavaScript, including filters, child tables, existence checks, and restricting Link fields.

UpdatedOct 1, 2026

Applies toFrappe v15Frappe v16

Tagsfrappepythonjavascriptqueriesset-query

Reading time4 min

On this page[Server Side (Python)](#server-side-python)[List Records](#list-records)[Filter on a Child Table](#filter-on-a-child-table)[Select Child Table Columns](#select-child-table-columns)[Read a Single Value](#read-a-single-value)[Query Builder](#query-builder)[Client Side (JavaScript)](#client-side-javascript)[List Records](#list-records-2)[Read a Value or a Document](#read-a-value-or-a-document)[Check Whether a Record Exists](#check-whether-a-record-exists)[Restrict Link Field Options with set_query](#restrict-link-field-options-with-set_query)[Filter by Another Field](#filter-by-another-field)[Contacts Linked to the Selected Customer](#contacts-linked-to-the-selected-customer)[Link Fields Inside a Child Table](#link-fields-inside-a-child-table)

This is a quick reference for reading data in Frappe: the server-side `frappe.get_all` family, the client-side `frappe.db` helpers, and `set_query` for limiting what a Link field offers. For joins, aggregates, and anything the dictionary filters can't express, see [Query Builder & PyPika Extensions](/kb/frappe/query-builder-pypika/).

## Server Side (Python)

### List Records

`frappe.get_all` ignores user permissions; `frappe.get_list` applies them. Both take the same arguments:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">contacts </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.get_all(</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Contact"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">filters</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">{</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"status"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Open"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">},</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">fields</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">[</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"full_name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"email_id"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">],</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">order_by</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"creation desc"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">start</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">0</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">page_length</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">20</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">)</span>
```

`filters` takes a dict (`{"status": "Open"}`), operators (`{"creation": [">", "2024-01-01"]}`), or a list of `[field, operator, value]` lists.

`pluck="name"` returns a flat list of one field instead of dicts.

`limit` is an alias for `page_length`. Leave both out to get every row. (The HTTP endpoint `frappe.client.get_list` and the JavaScript helpers default to 20.)

### Filter on a Child Table

Use the four-item form `[child_doctype, field, operator, value]`. For example, every Contact linked to a given Customer through the `links` (Dynamic Link) table:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">contact_names </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.get_all(</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Contact"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">filters</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">[</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        [</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Dynamic Link"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"link_doctype"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"="</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Customer"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">],</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        [</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Dynamic Link"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"link_name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"="</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"<CUSTOMER_NAME>"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">],</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    ],</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">pluck</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">)</span>
```

### Select Child Table Columns

Reference child columns with the backtick table syntax, and Frappe joins the child table for you. You get one row per child row:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">rows </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.get_all(</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Sales Order"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">filters</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">{</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"docstatus"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">1</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">},</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">fields</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">[</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"customer"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"`tabSales Order Item`.item_code"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"`tabSales Order Item`.qty"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">],</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">)</span>
```

### Read a Single Value

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">status </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.db.get_value(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Customer"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"<CUSTOMER_NAME>"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"disabled"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">)</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">email, phone </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.db.get_value(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Contact"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, {</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"user"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: frappe.session.user}, [</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"email_id"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"mobile_no"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">])</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">exists </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.db.exists(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Customer"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"<CUSTOMER_NAME>"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">)</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">contact_name </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.db.exists(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Contact"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, {</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"user"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: frappe.session.user})</span>
```

`frappe.db.exists` accepts a name or a filter dict and returns the matching name (or `None`).

### Query Builder

For anything more involved, use the query builder. Note that conditions compare `Field` objects, not bare names:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">Contact </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.qb.DocType(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Contact"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">)</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">rows </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> (</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    frappe.qb.from_(Contact)</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    .select(Contact.name, Contact.full_name)</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    .where(Contact.last_name </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">==</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"<LAST_NAME>"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">)</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    .orderby(Contact.creation, </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">order</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">frappe.qb.desc)</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    .limit(</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">20</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">)</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">).run(</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">as_dict</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">True</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">)</span>
```

## Client Side (JavaScript)

The `frappe.db` helpers return promises and respect the current user's permissions.

### List Records

```
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">const</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">records</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">await</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.db.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">get_list</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Item Price"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    fields: [</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"item_code"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"price_list_rate"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">],</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    filters: { price_list: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Standard Selling"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> },</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    order_by: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"item_code asc"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    limit: </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">100</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">});</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">records.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">forEach</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">((</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">row</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">) </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> console.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">log</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(row.item_code, row.price_list_rate));</span>
```

`get_list` returns 20 rows unless you pass `limit`.

### Read a Value or a Document

```
<span style="--shiki-dark:#8B949E;--shiki-light:#6E7781">// Single field; the value is on r.message</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">const</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">r</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">await</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.db.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">get_value</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Customer"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"<CUSTOMER_NAME>"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"customer_group"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">);</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">console.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">log</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(r.message.customer_group);</span>

<span style="--shiki-dark:#8B949E;--shiki-light:#6E7781">// Whole document, including child tables</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">const</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">customer</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">await</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.db.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">get_doc</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Customer"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"<CUSTOMER_NAME>"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">);</span>

<span style="--shiki-dark:#8B949E;--shiki-light:#6E7781">// Single doctype value</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">const</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">currency</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">await</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.db.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">get_single_value</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Global Defaults"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"default_currency"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">);</span>

<span style="--shiki-dark:#8B949E;--shiki-light:#6E7781">// Count</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">const</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">open_orders</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">await</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.db.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">count</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Sales Order"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, { filters: { status: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"To Deliver and Bill"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> } });</span>
```

### Check Whether a Record Exists

On the client, `frappe.db.exists(doctype, name)` only checks by **name**. To check by other fields, ask for the name with a filter:

```
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">const</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">exists</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">await</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.db.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">exists</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Customer"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"<CUSTOMER_NAME>"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">);</span>

<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">const</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">r</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">await</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> frappe.db.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">get_value</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Contact"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, { email_id: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"jane@example.com"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> }, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"name"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">);</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">const</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">contact_exists</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">Boolean</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(r.message?.name);</span>
```

Note

Unlike the Python version, the JavaScript `frappe.db.exists` wraps its second argument as `{ name: ... }`, so passing a filter object silently returns `false`.

## Restrict Link Field Options with set_query

`frm.set_query` controls the filters (or the server-side search method) behind a Link field's dropdown. Call it once in `setup` or `onload`; the function runs every time the dropdown opens, so it can read current form values.

### Filter by Another Field

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">frappe.ui.form.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">on</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Sales Order"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">setup</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">frm</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">) {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        frm.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">set_query</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"project"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, () </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> ({</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            filters: { customer: frm.doc.customer, status: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Open"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> },</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        }));</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    },</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">});</span>
```

### Contacts Linked to the Selected Customer

Contacts and addresses link to customers through a Dynamic Link child table, which plain filters can't reach. Frappe ships search methods for exactly this (`address_query` in `frappe.contacts.doctype.address.address` works the same way for addresses):

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">frappe.ui.form.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">on</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"<DOCTYPE>"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">setup</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">frm</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">) {</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        frm.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">set_query</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"contact_person"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, () </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> ({</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            query: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"frappe.contacts.doctype.contact.contact.contact_query"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">            filters: { link_doctype: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Customer"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, link_name: frm.doc.customer },</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        }));</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    },</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">});</span>
```

### Link Fields Inside a Child Table

Pass the child table's fieldname as the second argument. This example, taken from Frappe's own Contact form, limits the **Link Document Type** column of the `links` table to doctypes that have a `contact_html` field:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">frm.</span><span style="--shiki-dark:#D2A8FF;--shiki-light:#8250DF">set_query</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"link_doctype"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"links"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, () </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> ({</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    query: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"frappe.contacts.address_and_contact.filter_dynamic_link_doctypes"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    filters: { fieldtype: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"HTML"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, fieldname: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"contact_html"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> },</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">}));</span>
```

The function also receives `(doc, cdt, cdn)`, so you can filter on values from the current child row with `locals[cdt][cdn]`.

Sources

- [docs.frappe.io/framework/user/en/api/database](https://docs.frappe.io/framework/user/en/api/database)
- [docs.frappe.io/framework/user/en/api/form](https://docs.frappe.io/framework/user/en/api/form)
- [github.com/frappe/frappe/blob/version-15/frappe/public/js/frappe/db.js](https://github.com/frappe/frappe/blob/version-15/frappe/public/js/frappe/db.js)
- [github.com/frappe/frappe/blob/version-15/frappe/contacts/doctype/contact/contact.py](https://github.com/frappe/frappe/blob/version-15/frappe/contacts/doctype/contact/contact.py)

Need help with Frappe?

Our notes can take you a long way, but sometimes you'd rather have someone who's done it before.

[ERPNext implementation](/services/erp/erpnext/)

[← PreviousClient-Side Recipes](/kb/frappe/client-side-recipes/)[Next →Custom Field Controllers](/kb/frappe/custom-field-controllers/)

CC0This article is in the public domain ([CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/)), code samples included. Use it however helps you.

On this page

- [Server Side (Python)](#server-side-python)
- [List Records](#list-records)
- [Filter on a Child Table](#filter-on-a-child-table)
- [Select Child Table Columns](#select-child-table-columns)
- [Read a Single Value](#read-a-single-value)
- [Query Builder](#query-builder)
- [Client Side (JavaScript)](#client-side-javascript)
- [List Records](#list-records-2)
- [Read a Value or a Document](#read-a-value-or-a-document)
- [Check Whether a Record Exists](#check-whether-a-record-exists)
- [Restrict Link Field Options with set_query](#restrict-link-field-options-with-set_query)
- [Filter by Another Field](#filter-by-another-field)
- [Contacts Linked to the Selected Customer](#contacts-linked-to-the-selected-customer)
- [Link Fields Inside a Child Table](#link-fields-inside-a-child-table)

[Back to top↑](#top)

Services

- [ERP implementation](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)

Resources

- [Our work](/work/)
- [Open source](/open-source/)
- [Knowledge base](/kb/)
- [Insights](/insights/)

Company

- [About](/about/)
- [Team](/about/team/)
- [Partners](/partners/)
- [Contact](/contact/)

Clients

- [Project portal](https://erp.avunu.net/projects)
- [Invoices](https://erp.avunu.net/)
- [Support](https://erp.avunu.net/)

[![Avunu](/brand/avunu-logo-light.svg)](/)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M20.400 20.500h-3.600v-5.600c0-1.300 0-3-1.800-3s-2.100 1.400-2.100 2.900v5.700H9.400V9h3.400v1.600c.5-.9 1.600-1.900 3.400-1.900 3.600 0 4.300 2.400 4.300 5.500v6.300zM5.300 7.400a2.100 2.100 0 1 1 0-4.100 2.100 2.100 0 0 1 0 4.100zm1.800 13.100H3.600V9h3.500v11.500zM22.200 0H1.800C.8 0 0 .8 0 1.700v20.600c0 .9.800 1.700 1.800 1.700h20.400c1 0 1.800-.8 1.800-1.700V1.700C24 .8 23.200 0 22.200 0z">\</path>\</svg>\</av-icon>](https://www.linkedin.com/company/avunu)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M12 .3a12 12 0 0 0-3.8 23.4c.6.1.8-.3.8-.6v-2c-3.3.7-4-1.6-4-1.6-.6-1.4-1.4-1.8-1.4-1.8-1-.7.1-.7.1-.7 1.2.1 1.8 1.2 1.8 1.2 1 1.8 2.8 1.3 3.5 1 .1-.8.4-1.3.7-1.6-2.7-.3-5.5-1.3-5.5-5.9 0-1.3.5-2.4 1.2-3.2-.1-.3-.5-1.5.1-3.2 0 0 1-.3 3.3 1.2a11.500 11.500 0 0 1 6 0c2.300-1.500 3.300-1.200 3.300-1.200.6 1.700.2 2.900.1 3.200.8.8 1.200 1.900 1.200 3.200 0 4.600-2.800 5.600-5.500 5.900.4.400.8 1.100.8 2.200v3.300c0 .3.2.7.8.6A12 12 0 0 0 12 .3">\</path>\</svg>\</av-icon>](https://github.com/Avunu)[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

Avunu LLC · 948 East Philadelphia Street, York, PA 17403 · (717) 814-8540Knowledge base articles are in the public domain[Privacy](/privacy/)[Terms](/terms/)
