Filtres et requêtes avancés

Dodock offre des fonctionnalités puissantes pour filtrer et interroger les données de votre système. Cette page explique comment utiliser les opérateurs avancés de filtrage, notamment l'opérateur between récemment ajouté.

Utilisation de l'opérateur between

L'opérateur between permet de filtrer des enregistrements dont une valeur se situe entre deux bornes. Cet opérateur est particulièrement utile pour les champs de type date, heure ou numérique.

Syntaxe de base

# Filtrer les enregistrements où le champ 'montant' est compris entre 100 et 500
filters = [
    ["Facture", "montant", "between", [100, 500]]
]

# Filtrer les enregistrements où la date est comprise entre deux dates
filters = [
    ["Facture", "date", "between", ["2026-01-01", "2026-12-31"]]
]

Cas d'usage avec les dates

L'opérateur between est particulièrement utile pour les rapports périodiques. Voici quelques exemples concrets :

Exemple 1 : Factures du trimestre

Pour obtenir toutes les factures émises au cours du deuxième trimestre 2026 :

from frappe import get_list

factures = get_list(
    "Facture",
    filters=[
        ["date", "between", ["2026-04-01", "2026-06-30"]],
        ["statut", "=", "Payée"]
    ],
    fields=["nom", "client", "montant_total", "date"]
)

Exemple 2 : Commandes dans une plage horaire

Pour les champs de type datetime, vous pouvez spécifier des plages horaires précises :

commandes = get_list(
    "Commande",
    filters=[
        ["date_creation", "between", ["2026-08-01 08:00:00", "2026-08-01 18:00:00"]]
    ]
)

::: info Remarque importante : Lorsque vous utilisez des chaînes de caractères au format ISO-8601 (comme "2026-08-01T12:00:00"), le système préserve la composante horaire. Cependant, pour les dates simples (sans heure), le système considère automatiquement la borne inférieure comme le début de la journée (00:00:00) et la borne supérieure comme la fin de la journée (23:59:59). :::

Utilisation dans les rapports personnalisés

L'opérateur between peut être utilisé dans les rapports personnalisés pour créer des filtres dynamiques :

1. Allez dans Développeur > Rapport > Nouveau Rapport
2. Dans la section Filtres, ajoutez un nouveau filtre
3. Sélectionnez le champ approprié (date, numérique, etc.)
4. Choisissez l'opérateur between
5. Spécifiez les valeurs de début et de fin

      
flowchart TD
    A[Début] --> B[Sélectionner le type de rapport]
    B --> C[Ajouter un filtre]
    C --> D[Choisir le champ]
    D --> E[Sélectionner 'between']
    E --> F[Définir les bornes]
    F --> G[Exécuter le rapport]

    

Bonnes pratiques

• Pour les dates : Utilisez toujours le format AAAA-MM-JJ pour éviter toute ambiguïté
• Pour les heures : Utilisez le format AAAA-MM-JJ HH:MM:SS ou le format ISO-8601 AAAA-MM-JJTHH:MM:SS
• Pour les nombres : Assurez-vous que la borne inférieure est toujours inférieure à la borne supérieure
• Combinaison avec d'autres filtres : L'opérateur between peut être combiné avec d'autres opérateurs pour des requêtes complexes

Exemple complet : Analyse des ventes

Voici un exemple complet montrant comment utiliser l'opérateur between pour analyser les ventes d'un mois spécifique :

from frappe import get_all

# Obtenir toutes les factures payées du mois d'août 2026
debut_mois = "2026-08-01"
fin_mois = "2026-08-31"

factures = get_all(
    "Facture",
    filters=[
        ["date", "between", [debut_mois, fin_mois]],
        ["statut", "=", "Payée"]
    ],
    fields=["nom", "client", "montant_total", "date"],
    order_by="date asc"
)

# Calculer le total des ventes
total_ventes = sum(f.montant_total for f in factures)

# Afficher les résultats
print(f"Nombre de factures : {len(factures)}")
print(f"Total des ventes : {total_ventes} €")

# Regrouper par client
from collections import defaultdict
ventes_par_client = defaultdict(float)

for facture in factures:
    ventes_par_client[facture.client] += facture.montant_total

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

Autres opérateurs de filtrage utiles

En plus de between, Dodock offre plusieurs autres opérateurs de filtrage :

Dépannage

Si vos filtres between ne retournent pas les résultats attendus :

1. Vérifiez le format des dates : Assurez-vous que les dates sont au format AAAA-MM-JJ
2. Vérifiez l'ordre des bornes : La borne inférieure doit toujours être inférieure à la borne supérieure
3. Vérifiez le type de champ : L'opérateur between fonctionne avec les champs date, datetime et numérique
4. Vérifiez les permissions : Assurez-vous que l'utilisateur a accès aux enregistrements filtrés
5. Vérifiez les fuseaux horaires : Pour les champs datetime, tenez compte des fuseaux horaires si nécessaire

::: warning Limitation connue : Lorsque vous utilisez des chaînes de caractères contenant T (format ISO-8601 complet), la composante horaire est préservée. Cependant, pour les dates simples, le système considère automatiquement la borne inférieure comme le début de la journée et la borne supérieure comme la fin de la journée. :::

Conclusion

L'opérateur between est un outil puissant pour créer des requêtes précises sur des plages de valeurs. Que vous travailliez avec des dates, des montants ou d'autres valeurs numériques, cet opérateur vous permet de filtrer efficacement vos données pour obtenir exactement les informations dont vous avez besoin.

Pour aller plus loin, consultez la documentation sur :

• Les requêtes personnalisées
• La création de rapports
• L'API de filtrage avancé