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.

Query Builder

Fonctions de date dans le Query Builder

Utilisez les fonctions de date (YEAR, MONTH, QUARTER) dans frappe.get_list et frappe.get_all pour grouper ou filtrer vos données par période.

Fonctions de date dans le Query Builder

Les fonctions YEAR, MONTH et QUARTER extraient l'année, le mois ou le trimestre d'un champ date. Utilisez-les dans frappe.get_list et frappe.get_all pour grouper des enregistrements par période, sans SQL brut.

Elles fonctionnent sur MariaDB, PostgreSQL et SQLite. Dodock produit le SQL adapté à la base du site. Le résultat est toujours un nombre entier.

Fonctions disponibles

Fonction	Classe Python	Résultat
`YEAR`	`Year`	Année, par exemple `2026`
`MONTH`	`Month`	Mois, de `1` à `12`
`QUARTER`	`Quarter`	Trimestre, de `1` à `4`
`MONTHNAME`	`MonthName`	Nom du mois en anglais, par exemple `November`

Syntaxe dans `fields`

Passez un dictionnaire dans fields : la clé est le nom de la fonction, la valeur est le champ. La clé as donne un alias à la colonne. Utilisez cet alias dans group_by et order_by.

frappe.get_list(
    "User",
    fields=[{"YEAR": "creation", "as": "creation_year"}],
    group_by="creation_year",
)

Dodock refuse les fonctions SQL écrites en texte, comme "YEAR(creation)" ou "count(*) as total". Utilisez toujours la syntaxe dictionnaire, dans fields comme dans group_by (par l'alias).

Exemples

Les noms de clients et de fournisseurs sont fictifs.

Grouper des factures par année

import frappe

resultats = frappe.get_list(
    "Sales Invoice",
    fields=[
        {"YEAR": "posting_date", "as": "annee"},
        {"COUNT": "*", "as": "total_factures"},
        {"SUM": "grand_total", "as": "chiffre_affaires"},
    ],
    filters={"docstatus": 1},
    group_by="annee",
    order_by="annee asc",
)

for ligne in resultats:
    print(f"Année {ligne.annee} : {ligne.total_factures} factures, {ligne.chiffre_affaires} €")

Grouper des commandes par mois

resultats = frappe.get_list(
    "Sales Order",
    fields=[
        {"MONTH": "transaction_date", "as": "mois"},
        {"COUNT": "*", "as": "nb_commandes"},
    ],
    filters={"docstatus": 1, "customer": "Maison Verte SARL"},
    group_by="mois",
)

Grouper des achats par trimestre

resultats = frappe.get_list(
    "Purchase Invoice",
    fields=[
        {"QUARTER": "posting_date", "as": "trimestre"},
        {"SUM": "grand_total", "as": "total_achats"},
    ],
    filters={"supplier": "Bureau Moderne", "docstatus": 1},
    group_by="trimestre",
)

Utiliser les classes avec `frappe.qb`

Avec le Query Builder, importez les classes depuis frappe.query_builder.functions :

import frappe
from frappe.query_builder.functions import Count, Year

SalesInvoice = frappe.qb.DocType("Sales Invoice")

query = (
    frappe.qb.from_(SalesInvoice)
    .select(
        Year(SalesInvoice.posting_date).as_("annee"),
        Count("*").as_("nb"),
    )
    .where(SalesInvoice.docstatus == 1)
    .groupby(Year(SalesInvoice.posting_date))
)

resultats = query.run(as_dict=True)

SQL produit

Base	`YEAR(posting_date)` devient
MariaDB	`YEAR(posting_date)`
PostgreSQL	`CAST(date_part('year', posting_date) AS INTEGER)`
SQLite	`CAST(STRFTIME('%Y', posting_date) AS INTEGER)`

La liste des fonctions acceptées dans fields est le dictionnaire FUNCTION_MAPPING de frappe/database/query.py. Une application ne peut pas y ajouter de fonction. Pour une autre fonction de date, comme le jour de la semaine, écrivez la requête avec frappe.qb.