Documentation
Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
API

Filtres et requêtes avancés

Utiliser les opérateurs de filtre avancés de Dodock, dont between, pour interroger des dates, des heures et des nombres.

Filtres et requêtes avancés

Cette page décrit les opérateurs de filtre de frappe.get_list, frappe.get_all et de l'API REST. Elle détaille l'opérateur between sur les dates et les heures.

Les exemples utilisent les champs standard de Facture de vente (Sales Invoice). Les noms de clients sont fictifs.

Format d'un filtre

Un filtre est une liste [champ, opérateur, valeur]. Plusieurs filtres se combinent par ET. Pour un champ d'une table enfant, ajoutez le type de document en premier : [doctype, champ, opérateur, valeur].

frappe.get_list(
    "Sales Invoice",
    filters=[
        ["posting_date", "between", ["2026-04-01", "2026-06-30"]],
        ["status", "=", "Paid"],
        ["Sales Invoice Item", "item_code", "=", "CHAISE-001"],
    ],
    fields=["name", "customer", "grand_total", "posting_date"],
)

Opérateurs

OpérateurRôleExemple
=, !=Égal, différent["status", "!=", "Cancelled"]
>, >=, <, <=Comparaison["grand_total", ">=", 1000]
like, not likeContient un motif (% = n'importe quels caractères)["customer", "like", "%Maison%"]
in, not inDans une liste, hors d'une liste["status", "in", ["Paid", "Partly Paid"]]
betweenEntre deux bornes, bornes incluses["grand_total", "between", [100, 500]]
isRenseigné ou vide["due_date", "is", "set"], ["due_date", "is", "not set"]
timespanPériode relative["posting_date", "timespan", "this month"]
descendants of, ancestors ofDescendants ou ancêtres dans un arbre["territory", "descendants of", "France"]
not descendants of, not ancestors of, descendants of (inclusive)Variantes des opérateurs d'arbre["item_group", "descendants of (inclusive)", "Mobilier"]
regexExpression régulière["customer", "regex", "^SARL"]

L'opérateur between

between reçoit une liste de deux bornes. Il fonctionne sur les champs nombre, date et date et heure.

Sur un champ Date

Les bornes sont des dates AAAA-MM-JJ. Une valeur date et heure est ramenée à sa date.

# Factures du deuxième trimestre 2026
frappe.get_list(
    "Sales Invoice",
    filters=[["posting_date", "between", ["2026-04-01", "2026-06-30"]]],
)

Sur un champ Date et heure

Ceci s'applique aux champs Date et heure et aux champs creation et modified.

  • Une borne date seule ("2026-08-01") couvre la journée : la borne basse devient 00:00:00, la borne haute 23:59:59.999999.
  • Une borne avec une heure, séparée par une espace ("2026-08-01 08:00:00"), garde son heure.
# Factures créées le 1er août 2026 entre 8 h et 18 h
frappe.get_list(
    "Sales Invoice",
    filters=[["creation", "between", ["2026-08-01 08:00:00", "2026-08-01 18:00:00"]]],
)
N'utilisez pas le séparateur T du format ISO 8601 ("2026-08-01T08:00:00"). Dodock lit alors la borne comme une date seule et ignore l'heure. Le filtre couvre la journée entière.

Exemple complet : ventes d'un mois

from collections import defaultdict

import frappe

factures = frappe.get_all(
    "Sales Invoice",
    filters=[
        ["posting_date", "between", ["2026-08-01", "2026-08-31"]],
        ["docstatus", "=", 1],
    ],
    fields=["name", "customer", "grand_total", "posting_date"],
    order_by="posting_date asc",
)

total_ventes = sum(f.grand_total for f in factures)
print(f"Nombre de factures : {len(factures)}")
print(f"Total des ventes : {total_ventes} €")

ventes_par_client = defaultdict(float)
for facture in factures:
    ventes_par_client[facture.customer] += facture.grand_total

for client, montant in ventes_par_client.items():
    print(f"- {client} : {montant} €")

Pour faire la somme dans la base au lieu de Python, utilisez fields=["customer", {"SUM": "grand_total", "as": "total"}] et group_by="customer".

Dépannage

Si un filtre between ne renvoie pas les lignes attendues :

  1. Vérifiez le format des dates : AAAA-MM-JJ, et AAAA-MM-JJ HH:MM:SS avec une espace pour une heure.
  2. Vérifiez l'ordre des bornes : la première borne doit être la plus petite.
  3. Vérifiez le type du champ dans le type de document.
  4. Avec frappe.get_list, vérifiez les autorisations de l'utilisateur. frappe.get_all ne les contrôle pas.

Voir aussi