API Base de données

L'API base de données lit et écrit les données sans passer par les objets Document. Elle est plus rapide que l'API de documents, mais elle n'exécute pas les méthodes des contrôleurs.

Les exemples utilisent le type de document ToDo (champs description, status, priority, date, allocated_to). Les valeurs sont fictives.

frappe.db.get_list

frappe.db.get_list(doctype, filters=None, or_filters=None, fields=None, order_by=None, group_by=None, limit=None, offset=None, as_list=False, pluck=None)

Alias : frappe.get_list.

Renvoie une liste d'enregistrements d'un type de document. Dodock applique les autorisations de l'utilisateur de la session. Par défaut, chaque enregistrement est un dictionnaire.

frappe.db.get_list(
    "ToDo",
    filters={"status": "Open"},
    fields=["description", "date"],
    order_by="date desc",
    offset=10,
    limit=20,
    as_list=True,
)
# résultat
# (("Relancer le devis", datetime.date(2026, 11, 4)),
#  ("Préparer la réunion", datetime.date(2026, 11, 2)))

# Tâches dont la date est après le 8 septembre 2026
frappe.db.get_list("ToDo", filters={"date": [">", "2026-09-08"]})

# Tâches dont la description contient « devis »
frappe.db.get_list("ToDo", filters={"description": ["like", "%devis%"]})

# Liste simple des noms
frappe.db.get_list("ToDo", filters={"status": "Open"}, pluck="name")
# ["a1b2c3d4e5", "f6g7h8i9j0"]

# Nombre de tâches par statut
frappe.db.get_list(
    "ToDo",
    fields=["status", {"COUNT": "name", "as": "count"}],
    group_by="status",
)
# [{"status": "Open", "count": 12},
#  {"status": "Closed", "count": 40},
#  {"status": "Cancelled", "count": 3}]

Les arguments start, page_length, limit_start et limit_page_length fonctionnent encore, mais ils sont dépréciés. Utilisez offset et limit.

frappe.db.get_all

Alias : frappe.get_all.

Même signature que frappe.db.get_list, mais sans contrôle des autorisations. Utilisez-la dans du code serveur qui n'expose pas le résultat à n'importe quel utilisateur.

frappe.db.get_value

frappe.db.get_value(doctype, filters=None, fieldname="name", as_dict=False, order_by=..., cache=False, for_update=False)

Alias : frappe.get_value.

Renvoie la valeur d'un ou plusieurs champs du premier enregistrement trouvé. filters est le nom d'un document ou un dictionnaire de filtres. Si aucun enregistrement ne correspond, la méthode renvoie None.

# Une valeur
description = frappe.db.get_value("ToDo", "a1b2c3d4e5", "description")

# Plusieurs valeurs
description, status = frappe.db.get_value("ToDo", "a1b2c3d4e5", ["description", "status"])

# Dictionnaire
todo = frappe.db.get_value("ToDo", "a1b2c3d4e5", ["description", "status"], as_dict=True)
todo.description

# Avec des filtres : premier enregistrement qui correspond
description, status = frappe.db.get_value("ToDo", {"status": "Open"}, ["description", "status"])

frappe.db.get_values

frappe.db.get_values(doctype, filters=None, fieldname="name", as_dict=False, limit=None)

Comme get_value, mais renvoie tous les enregistrements qui correspondent, sous forme de liste.

frappe.db.get_values("ToDo", {"status": "Open"}, ["name", "description"], as_dict=True)

frappe.db.get_single_value

frappe.db.get_single_value(doctype, fieldname, cache=True)

Renvoie la valeur d'un champ d'un type de document unique (Single).

time_zone = frappe.db.get_single_value("System Settings", "time_zone")

frappe.db.set_value

frappe.db.set_value(doctype, name, fieldname, value=None, update_modified=True)

Écrit la valeur d'un ou plusieurs champs directement dans la base de données. name peut aussi être un dictionnaire de filtres. Dodock met à jour la date de modification, sauf avec update_modified=False.

# Un champ
frappe.db.set_value("ToDo", "a1b2c3d4e5", "status", "Closed")

# Plusieurs champs
frappe.db.set_value("ToDo", "a1b2c3d4e5", {"status": "Closed", "priority": "Low"})

# Sans changer la date de modification
frappe.db.set_value("ToDo", "a1b2c3d4e5", "status", "Closed", update_modified=False)

frappe.db.exists

frappe.db.exists(doctype, name=None, cache=False)

Renvoie le nom du document s'il existe, sinon None.

# Par nom
frappe.db.exists("ToDo", "a1b2c3d4e5")  # "a1b2c3d4e5"

# Par filtres
frappe.db.exists("ToDo", {"status": "Open", "allocated_to": "jean@example.com"})

# Par filtres, avec la clé "doctype"
frappe.db.exists({"doctype": "ToDo", "status": "Open"})

frappe.db.count

frappe.db.count(doctype, filters=None, cache=False)

Renvoie le nombre d'enregistrements qui correspondent aux filtres.

frappe.db.count("ToDo")
frappe.db.count("ToDo", {"status": "Open"})

frappe.db.delete

frappe.db.delete(doctype, filters=None)

Supprime les enregistrements qui correspondent aux filtres, avec une requête DELETE. Les méthodes du contrôleur ne s'exécutent pas et Dodock ne garde pas de copie dans Document supprimé. Pour supprimer un document avec ses contrôles, utilisez frappe.delete_doc.

frappe.db.delete("ToDo", {"status": "Cancelled"})

frappe.db.commit

frappe.db.commit()

Valide la transaction en cours avec la requête SQL COMMIT.

Dodock valide la transaction à la fin d'une requête web réussie de type POST, PUT, PATCH ou DELETE. Il ne la valide pas pour une requête GET. Vous n'avez donc pas besoin d'appeler cette méthode dans la plupart des cas. Appelez-la pour valider un long traitement en plusieurs fois, par exemple dans une tâche d'arrière-plan.

frappe.db.rollback

frappe.db.rollback(save_point=None)

Annule la transaction en cours avec la requête SQL ROLLBACK. Avec save_point, annule jusqu'au point de sauvegarde créé avec frappe.db.savepoint(nom).

Dodock annule la transaction si une exception se produit pendant une requête web.