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
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'
doc.save()
# get a single doctype
doc = frappe.get_doc('System Settings')
doc.timezone # Asia/Kolkata
frappe.get_doc(dict)
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'
})
doc.insert()
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='test@example.com')
user.insert()
frappe.get_last_doc
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.
frappe.get_cached_doc
Similar to
frappe.get_doc
but will look up the document in cache first before hitting the database.
frappe.new_doc
frappe.new_doc(doctype)
Alternative way to create a new Document.
# create a new document
doc = frappe.new_doc('Task')
doc.title = 'New Task 2'
doc.insert()
frappe.delete_doc
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
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.
frappe.get_meta
frappe.get_meta(doctype)
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.
doc.insert
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.
doc.insert(
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
)
doc.save
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.
doc.save(
ignore_permissions=True, # ignore write permissions during insert
ignore_version=True # do not create a version record
)
doc.delete
Delete the document record from the database table. This method is an alias to
frappe.delete_doc
.
doc.delete()
doc.get_doc_before_save
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
pass
doc.has_value_changed
Will return True if the value of the given field was changed before and after saving.
price_changed = doc.has_value_changed("price")
if price_changed:
pass
doc.reload
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.
doc.reload()
doc.check_permission
Throw if the current user has no permission for the provided permtype.
doc.check_permission(permtype='write') # throws if no write permission
doc.get_title
Get the document title based on
title_field
or field named
title
or
name
.
title = doc.get_title()
doc.notify_update
Publish realtime event to indicate that the document has been modified. Client side event handlers react to this event by updating the form.
doc.notify_update()
doc.db_set
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)
doc.append
Append a new item to a child table.
doc.append("childtable", {
"child_table_field": "value",
"child_table_int_field": 0,
...
})
doc.get_url
Returns Desk URL for this document. For e.g:
/app/task/TASK00002
url = doc.get_url()
doc.add_comment
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))
doc.add_seen
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
doc.add_seen('john@doe.com')
# add session user to list of seen
doc.add_seen()
This works only if Track Seen is enabled in the DocType.
doc.add_viewed
Add a view log when a user views a document i.e opens the Form.
# add a view log by john
doc.add_viewed('john@doe.com')
# add a view log by session user
doc.add_viewed()
This works only if Track Views is enabled in the DocType.
doc.add_tag
Add a tag to a document. Tags are generally used to filter and group documents.
# add tags
doc.add_tag('developer')
doc.add_tag('frontend')
doc.get_tags
Returns a list of tags associated with the specific document.
# get all tags
doc.get_tags()
doc.run_method
Run method if defined in controller, will also trigger hooks if defined.
doc.run_method('validate')
doc.queue_action
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')
doc.get_children()
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():
print(child_doc.name)
It can also be applied recursively:
for child_doc in doc.get_children():
print(child_doc.name)
for grandchild_doc in child_doc.get_children():
print(grandchild_doc.name)
doc.get_parent()
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()
doc.db_insert()
Serialize and insert a document into database. Warning: This bypasses all validations and controller methods that might be required to run before and after inserting. When in doubt use
doc.insert()
instead.
doc = frappe.get_doc(doctype="Controller", data="")
doc.db_insert()
doc.db_update()
Serialize and update a document into database. Warning: This bypasses all validations and controller methods that might be required to run before and after updating. When in doubt use
doc.save()
instead.
doc = frappe.get_last_doc("User")
doc.last_active = now()
doc.db_update()