Efficient Document-Based Data Management with Empress

Developers
1

Introduction

In Empress, we use a document-based approach to data management, providing a flexible and efficient way to store, retrieve, and manipulate data. This guide will dive into our feature set around documents, allowing developers to understand and utilize these tools effectively.

The Basics: What is a Document?

A Document is an instance of a DocType. It is derived from the frappe.model.Document class and represents a single record in the database table. This means that every data entry you make in Empress corresponds to a Document.

Document Retrieval: frappe.get_doc

The frappe.get_doc function is your go-to tool for retrieving Documents. It can work with existing documents, create new ones, or define documents with keyword arguments.

Getting an existing Document

To get an existing Document, you need to know its doctype and name. If the Document doesn’t exist, a DoesNotExistError will be raised. If doctype is a Single DocType, name is not required.

doc = frappe.get_doc('Task', 'TASK00002')
doc.title = 'Test'
doc.save()

Creating a new Document

To create a new Document that doesn’t exist in the database yet, use a dictionary with the doctype and other key-value pairs to define the Document’s properties.

doc = frappe.get_doc({
    'doctype': 'Task',
    'title': 'New Task'
})
doc.insert()

Creating a new Document with keyword arguments

Alternatively, you can create a new Document using keyword arguments. This way, you can pass the doctype directly and any other key-value pairs as arguments to frappe.get_doc.

user = frappe.get_doc(doctype='User', email_id='test@example.com')
user.insert()

Getting the Last Document: frappe.get_last_doc

The frappe.get_last_doc function retrieves the most recently created Document under a specified doctype. You can also specify filters to refine your results.

task = frappe.get_last_doc('Task')

The order_by argument is set to creation desc by default, but you can override it to use other fields.

task = frappe.get_last_doc('Task', filters={"status": "Cancelled"}, order_by="timestamp desc")

Document Caching: frappe.get_cached_doc

The frappe.get_cached_doc function works like frappe.get_doc but checks the cache first before querying the database. This helps improve performance by reducing the number of database hits.

Creating a New Document: frappe.new_doc

The frappe.new_doc function is an alternative way to create a new Document.

doc = frappe.new_doc('Task')
doc.title = 'New Task 2'
doc.insert()

Deleting a Document: frappe.delete_doc

The frappe.delete_doc function deletes a Document and its children from the database, along with any related Communications, Comments, etc.

frappe.delete_doc('Task', 'TASK00002')

Renaming a Document: frappe.rename_doc

The frappe.rename_doc function renames a Document’s name (the primary key) from old_name to new_name. If merge is True and a Document with new_name exists, it will merge the records.

frappe.rename_doc('Task', 'TASK00002', 'TASK00003')

Getting Meta Information: frappe.get_meta

The frappe.get_meta function returns meta information for a doctype. This includes custom fields and property setters.

meta = frappe.get_meta('Task')
meta.has_field('status') # True
meta.get_custom_fields() # [field1, field2, ..]

Document Methods

Documents come with several built-in methods that you can use to manipulate the data, manage permissions, and interact with other parts of the system. These methods include:

  • doc.insert: Inserts a new Document into the database table.
  • doc.save: Saves changes to an existing Document.
  • doc.delete: Deletes the Document record from the database table.
  • doc.get_doc_before_save: Returns a version of the doc before changes were made.
  • doc.reload: Gets the latest values from the database and updates the doc state.
  • doc.check_permission: Checks if the current user has permission for the provided permtype.
  • doc.get_title: Gets the Document title based on title_field or field named title or name.

And many more. These methods allow developers to build complex workflows and business logic around Documents, enabling the creation of highly customized business solutions.

In conclusion, the Document feature of Empress provides a robust and flexible way for developers to manage data. From retrieving and creating documents, to manipulating and interacting with them, developers have a wide range of tools at their disposal. This not only enhances the development process but also allows for the creation of highly customized and efficient business solutions.