Document API

Working with documents using get_doc, new_doc, and document methods

The Document API provides methods to create, read, update, and delete documents in Frappe.

Getting documents

get_doc

Return a Document object.

doctype · str

DocType name

name · str

Document name (optional for Single DocTypes)

for_update · bool · default: "False"

Select document with FOR UPDATE clause for locking

check_permission · str | bool

Permission type to check (e.g., “read”, “write”). True checks “read” permission

return · Document

Document object with all fields and child tables loaded

# Get existing document
user = frappe.get_doc("User", "[e-mail]")
print(user.full_name)

# Get Single DocType
settings = frappe.get_doc("System Settings")

# Create from dict
user = frappe.get_doc({
    "doctype": "User",
    "email": "[e-mail]",
    "first_name": "Test"
})

# Get with permission check
doc = frappe.get_doc("Customer", "CUST-001", check_permission="write")

# Select for update (row locking)
doc = frappe.get_doc("Customer", "CUST-001", for_update=True)

get_lazy_doc

Return a Document object without loading child tables. Child tables are loaded on access.

doctype · str · required

DocType name

name · str · required

Document name

for_update · bool · default: "False"

Select with FOR UPDATE clause

check_permission · str | bool

Permission type to check

# Lazy load document - faster when you don't need child tables
doc = frappe.get_lazy_doc("Sales Order", "SO-001")
print(doc.customer)  # Parent fields are loaded
print(doc.items)  # Child table loaded on access

get_cached_doc

Get a document from cache or database.

doctype · str · required

DocType name

name · str · required

Document name

# Get from cache if available
doc = frappe.get_cached_doc("Customer", "CUST-001")

get_last_doc

Get the last created document of a DocType.

doctype · str · required

DocType name

filters · dict

Additional filters

# Get most recently created customer
last_customer = frappe.get_last_doc("Customer")

# With filters
last_active = frappe.get_last_doc("Customer", {"disabled": 0})

Creating documents

new_doc

Create a new document instance.

doctype · str · required

DocType name

as_dict · bool · default: "False"

Return as dict instead of Document object

return · Document

New document instance with default values

# Create new document
customer = frappe.new_doc("Customer")
customer.customer_name = "John Doe"
customer.insert()

# Create as dict
customer_dict = frappe.new_doc("Customer", as_dict=True)

copy_doc

Create a copy of a document.

doc · Document · required

Document to copy

no_copy · list

Fields to exclude from copy

# Copy existing document
original = frappe.get_doc("Sales Order", "SO-001")
copy = frappe.copy_doc(original)
copy.insert()

Document methods

insert

Insert the document into the database.

ignore_permissions · bool · default: "False"

Bypass permission checks

ignore_mandatory · bool · default: "False"

Skip mandatory field validation

ignore_if_duplicate · bool · default: "False"

Don’t raise error if duplicate

doc = frappe.new_doc("Customer")
doc.customer_name = "Jane Doe"
doc.insert()
print(f"Created: {doc.name}")

save

Update the document in the database.

ignore_permissions · bool · default: "False"

Bypass permission checks

ignore_version · bool · default: "False"

Don’t create version on save

doc = frappe.get_doc("Customer", "CUST-001")
doc.territory = "India"
doc.save()

submit

Submit a submittable document.

doc = frappe.get_doc("Sales Order", "SO-001")
doc.submit()
print(doc.docstatus)  # 1 (submitted)

cancel

Cancel a submitted document.

doc = frappe.get_doc("Sales Order", "SO-001")
doc.cancel()
print(doc.docstatus)  # 2 (cancelled)

delete

Delete the document.

doc = frappe.get_doc("Customer", "CUST-001")
doc.delete()

reload

Reload the document from database.

doc = frappe.get_doc("Customer", "CUST-001")
# ... some changes ...
doc.reload()  # Discard changes and reload from DB

Field access

get

Get a field value with a default.

fieldname · str · required

Field name

default · any

Default value if field is not set

territory = doc.get("territory", "All Territories")

set

Set a field value.

fieldname · str · required

Field name

value · any · required

Value to set

doc.set("territory", "India")

db_set

Set a field value directly in the database without loading the document.

fieldname · str | dict · required

Field name or dict of field-value pairs

value · any

Value to set

update_modified · bool · default: "True"

Update modified timestamp

notify_update · bool · default: "False"

Trigger update event

# Set single field
doc.db_set("status", "Active")

# Set multiple fields
doc.db_set({
    "status": "Active",
    "verified": 1
})

db_get

Get the latest field value from database.

fieldname · str · required

Field name

latest_status = doc.db_get("status")

Child table operations

append

Append a row to a child table.

fieldname · str · required

Child table fieldname

values · dict

Field values for the new row

return · Document

The appended child document

# Add item to Sales Order
so = frappe.get_doc("Sales Order", "SO-001")
item_row = so.append("items", {
    "item_code": "ITEM-001",
    "qty": 10,
    "rate": 100
})
so.save()

remove

Remove a child table row.

child_doc · Document · required

Child document to remove

for item in so.items:
    if item.qty == 0:
        so.remove(item)
so.save()

Permission checks

has_permission

Check if user has a specific permission on the document.

ptype · str · default: "read"

Permission type: “read”, “write”, “submit”, “cancel”, “delete”

user · str

User to check permission for. Default: current user

return · bool

True if user has permission

if doc.has_permission("write"):
    doc.status = "Approved"
    doc.save()

check_permission

Check permission and raise exception if not permitted.

ptype · str · default: "read"

Permission type to check

doc.check_permission("submit")
doc.submit()

Document state

as_dict

Convert document to dictionary.

no_default_fields · bool · default: "False"

Exclude default fields like owner, creation

no_child_table_fields · bool · default: "False"

Exclude child table fields

data = doc.as_dict()
print(data["customer_name"])

as_json

Convert document to JSON string.

json_str = doc.as_json()

Helper functions

delete_doc

Delete a document by doctype and name.

doctype · str · required

DocType name

name · str · required

Document name

force · bool · default: "False"

Delete even if document is linked

ignore_permissions · bool · default: "False"

Bypass permission checks

delete_permanently · bool · default: "False"

Delete permanently without creating Deleted Document

# Delete with permission check
frappe.delete_doc("Customer", "CUST-001")

# Force delete linked document
frappe.delete_doc("Item", "ITEM-001", force=True)

rename_doc

Rename a document.

doctype · str · required

DocType name

old · str · required

Current name

new · str · required

New name

merge · bool · default: "False"

Merge with existing document if new name exists

force · bool · default: "False"

Force rename even if links exist

# Rename document
frappe.rename_doc("Customer", "CUST-001", "CUST-NEW-001")

# Merge with existing
frappe.rename_doc("Customer", "CUST-001", "CUST-002", merge=True)