Document API

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.


frappe.get_doc(doctype, name)

Returns a Document object of the record identified by doctype and name. If no document is found, a DoesNotExistError is raised. If doctype is a Single DocType name is not required.

# get an existing document
doc = frappe.get_doc('Task', 'TASK00002')
doc.title = 'Test'

# get a single doctype
doc = frappe.get_doc('System Settings')
doc.timezone # Asia/Kolkata


Returns a new Document object in memory which does not exist yet in the database.

# create a new document
doc = frappe.get_doc({
    'doctype': 'Task',
    'title': 'New Task'

frappe.get_doc(doctype={document_type}, key1 = value1, key2 = value2, ...)

Returns a new Document object in memory which does not exist yet in the database.

# create new object with keyword arguments
user = frappe.get_doc(doctype='User', email_id='')


frappe.get_last_doc(doctype, filters, order_by)

Returns the last Document object created under the mentioned doctype.

# get the last Task created
task = frappe.get_last_doc('Task')

You can also specify filters to refine your results. For instance, you can retrieve the last canceled Task by adding a filter.

# get the last available Cancelled Task
task = frappe.get_last_doc('Task', filters={"status": "Cancelled"})

By default, the order_by argument is set to creation desc, but this value can be overridden to use other non-standard fields that can serve the same purpose. For instance, you have a field timestamp under the Task DocType that tracks the time it was approved or marked valid instead of the time it was created.

# get the last Task created based on a non-standard field
task = frappe.get_last_doc('Task', filters={"Status": "Cancelled"}, order_by="timestamp desc")

Alternatively, you can choose to go completely against all of this and as a part of a joke change it to "creation asc" to retrieve the first document instead.


Similar to frappe.get_doc but will look up the document in cache first before hitting the database.



Alternative way to create a new Document.

# create a new document
doc = frappe.new_doc('Task')
doc.title = 'New Task 2'


frappe.delete_doc(doctype, name)

Deletes the record and its children from the database. Also deletes other documents like Communication, Comments, etc linked to it.

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


frappe.rename_doc(doctype, old_name, new_name, merge=False)

Rename a document's name (primary key) from old_name to new_name. If merge is True and a record with new_name exists, will merge the record with it.

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

Rename will only work if Allow Rename is set in the DocType Form.



Returns meta information of doctype. This will also apply custom fields and property setters.

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

To get the original document of DocType (without custom fields and property setters) use frappe.get_doc('DocType', doctype_name)

Document Methods

This section lists out common methods that are available on the doc object.


This method inserts a new document into the database table. It will check for user permissions and execute before_insert, validate, on_update, after_insert methods if they are written in the controller.

It has some escape hatches that can be used to skip certain checks explained below.

    ignore_permissions=True, # ignore write permissions during insert
    ignore_links=True, # ignore Link validation in the document
    ignore_if_duplicate=True, # dont insert if DuplicateEntryError is thrown
    ignore_mandatory=True # insert even if mandatory fields are not set

This method saves changes to an existing document. This will check for user permissions and execute validate before updating and on_update after updating values.
    ignore_permissions=True, # ignore write permissions during insert
    ignore_version=True # do not create a version record


Delete the document record from the database table. This method is an alias to frappe.delete_doc.



Will return a version of the doc before the changes were made. You can use it to compare what changed from the last version.

old_doc = doc.get_doc_before_save()
if old_doc.price != doc.price:
    # price changed


Will get the latest values from the database and update the doc state.

When you are working with a document, it may happen that some other part of code updates the value of some field directly in the database. In such cases you can use this method to reload the doc.



Throw if the current user has no permission for the provided permtype.

doc.check_permission(permtype='write') # throws if no write permission


Get the document title based on title_field or field named title or name.

title = doc.get_title()


Publish realtime event to indicate that the document has been modified. Client side event handlers react to this event by updating the form.



Set a field value of the document directly in the database and update the modified timestamp.

This method does not trigger controller validations and should be used very carefully.

# updates value in database, updates the modified timestamp
doc.db_set('price', 2300)

# updates value in database, will trigger doc.notify_update()
doc.db_set('price', 2300, notify=True)

# updates value in database, will also run frappe.db.commit()
doc.db_set('price', 2300, commit=True)

# updates value in database, does not update the modified timestamp
doc.db_set('price', 2300, update_modified=False)


Append a new item to a child table.

doc.append("childtable", {
    "child_table_field": "value",
    "child_table_int_field": 0,


Returns Desk URL for this document. For e.g: /app/task/TASK00002

url = doc.get_url()


Add a comment to this document. Will show up in timeline in Form view.

# add a simple comment
doc.add_comment('Comment', text='Test Comment')

# add a comment of type Edit
doc.add_comment('Edit', 'Values changed')

# add a comment of type Shared
doc.add_comment("Shared", "{0} shared this document with everyone".format(user))


Add the given/current user to list of users who have seen this document. Will update the _seen column in the table. It is stored as a JSON Array.

# add john to list of seen

# add session user to list of seen

This works only if Track Seen is enabled in the DocType.


Add a view log when a user views a document i.e opens the Form.

# add a view log by john

# add a view log by session user

This works only if Track Views is enabled in the DocType.


Add a tag to a document. Tags are generally used to filter and group documents.

# add tags


Returns a list of tags associated with the specific document.

# get all tags


Run method if defined in controller, will also trigger hooks if defined.



Run a controller method in background. If the method has an inner function, like _submit for submit, it will call that method instead.

doc.queue_action('send_emails', emails=email_list, message='Howdy')


Only available on tree DocTypes (inherited from NestedSet).

Returns a generator that yields an instance of NestedSet for each child record.

for child_doc in doc.get_children():

It can also be applied recursively:

for child_doc in doc.get_children():
    for grandchild_doc in child_doc.get_children():


Only available on tree DocTypes (inherited from NestedSet).

Returns an instance of NestedSet for the parent record.

parent_doc = doc.get_parent()
grandparent_doc = parent_doc.get_parent()