Database API

frappe.db.get_list

frappe.db.get_list(doctype, filters, or_filters, fields, order_by, group_by, start, page_length)

  • Juga dikenal sebagai frappe.get_list

Mengembalikan daftar catatan dari tabel doctype. ORM Wrapper untuk query SELECT. Juga akan menerapkan izin pengguna untuk catatan yang dimiliki pengguna sesi. Hanya mengembalikan nama dokumen jika argumen keyword fields tidak diberikan. Secara default, metode ini mengembalikan daftar dict, tetapi, Anda dapat mengambil bidang tertentu dengan memberikan argumen keyword pluck:

frappe.db.get_list('Employee')

# output
[{'name': 'HR-EMP-00008'},
 {'name': 'HR-EMP-00006'},
 {'name': 'HR-EMP-00010'},
 {'name': 'HR-EMP-00005'}
]

# dengan pluck
frappe.db.get_list('Employee', pluck='name')

# output
['HR-EMP-00008',
 'HR-EMP-00006',
 'HR-EMP-00010',
 'HR-EMP-00005'
]

Menggabungkan filter dan argumen lainnya:

frappe.db.get_list('Task',
    filters={
        'status': 'Open'
    },
    fields=['subject', 'date'],
    order_by='date desc',
    start=10,
    page_length=20,
    as_list=True
)

# output
(('Update Branding and Design', '2019-09-04'),
('Missing Documentation', '2019-09-02'),
('Fundraiser for Foundation', '2019-09-03'))

# Tasks dengan date setelah 2019-09-08
frappe.db.get_list('Task', filters={
    'date': ['>', '2019-09-08']
})

# Tasks dengan date antara 2020-04-01 dan 2021-03-31 (keduanya inklusif)
frappe.db.get_list('Task', filters=[[
    'date', 'between', ['2020-04-01', '2021-03-31']
]])

# Tasks dengan subject yang mengandung "test"
frappe.db.get_list('Task', filters<span="hljs-operator">={
    'subject': ['like', '%test%']
})

# Menghitung jumlah tasks dikelompokkan berdasarkan status
frappe.db.get_list('Task',
    fields=['count(name) as count', 'status'],
    group_by='status'
)
# output
[{'count': 1, 'status': 'Working'},
 {'count': 2, 'status': <span="hljs-string">'Overdue'},
 {'count': 2, 'status': 'Open'},
 {'count': 1, 'status': 'Filed'},
 {'count': 20, 'status': 'Completed'},
 {'count': 1, 'status': 'Cancelled'}]

frappe.db.get_all

frappe.db.get_all(doctype, filters, or_filters, fields, order_by, group_by, start, page_length)

  • Juga dikenal sebagai frappe.get_all

Mirip dengan frappe.db.get_list tetapi akan mengambil semua catatan tanpa menerapkan izin.

frappe.db.get_value

frappe.db.get_value(doctype, name, fieldname) atau frappe.db.get_value(doctype, filters, fieldname)

  • Juga dikenal sebagai frappe.get_value dan frappe.db.get_values

Mengembalikan nilai bidang dokumen atau daftar nilai.

# single value
subject = frappe.db.get_value('Task', 'TASK00002', 'subject')

# multiple values
subject, description = frappe.db.get_value('Task', 'TASK00002', ['subject', 'description'])

# sebagai dict
task_dict = frappe.db.get_value('Task', 'TASK00002', ['subject', 'description'], as_dict=1)
task_dict.subject
task_dict.description

# dengan filters, akan mengembalikan catatan pertama yang cocok dengan filter
subject, description = frappe.db.get_value('Task', {'status': 'Open'}, ['subject', 'description'])

frappe.db.get_single_value

frappe.db.get_single_value(doctype, fieldname)

Mengembalikan nilai field dari Single DocType.

timezone = frappe.db.get_single_value('System Settings', 'timezone')

frappe.db.set_value

frappe.db.set_value(doctype, name, fieldname, value)

  • Juga dikenal sebagai frappe.db.update

Menetapkan nilai field di database, tidak memanggil trigger ORM tetapi memperbarui timestamp modified (kecuali dinyatakan tidak untuk diperbarui).

# perbarui nilai field
frappe.db.set_value('Task', 'TASK00002', 'subject', 'New Subject')

# perbarui beberapa nilai
frappe.db.set_value('Task', 'TASK00002', {
    'subject': 'New Subject',
    'description': 'New Description'
})

# perbarui tanpa memperbarui timestamp `modified`
frappe.db.set_value('Task', 'TASK00002', 'subject', 'New Subject', update_modified=False)

Metode ini tidak akan memanggil trigger ORM seperti validate dan on_update. Gunakan metode ini untuk memperbarui bidang tersembunyi atau jika Anda tahu apa yang Anda lakukan.

frappe.db.exists

frappe.db.exists(doctype, name)

Mengembalikan true jika catatan dokumen ada.

Masukkan doctype dan docname:

frappe.db.exists("User", "jane@example.org", cache=True)

Masukkan dict filter yang mencakup kunci "doctype":

frappe.db.exists({"doctype": "User", "full_name": "Jane Doe"})

Masukkan doctype dan dict filter:

frappe.db.exists("User", {"full_name": "Jane Doe"})

frappe.db.count

frappe.db.count(doctype, filters)

Mengembalikan jumlah catatan untuk doctype dan filters yang diberikan.

# jumlah total tasks 
frappe.db.count('Task')

# jumlah total tasks Open
frappe.db.count('Task', {'status': <span="hljs-string">Open})

frappe.db.delete

frappe.db.delete(doctype, filters)

Hapus catatan doctype yang cocok dengan filters. Ini menjalankan perintah DML, yang berarti dapat di-rollback. Jika tidak ada filter yang ditentukan, semua catatan dari doctype dihapus.

frappe.db.delete("Route History", {
    "modified": ("&lt;=", last_record_to_keep[0].modified),
    "user": user
})

frappe.db.delete("Error Log")
frappe.db.delete("__Test Table")

Anda dapat memasukkan nama doctype atau nama tabel internal. Secara konvensional, tabel internal di Frappe diawali dengan __. API mengikuti ini. Perintah di atas menjalankan query DELETE tanpa syarat pada tabel tabError Log dan __Test Table.

frappe.db.truncate

frappe.db.truncate(doctype)

Truncate tabel dalam database. Ini menjalankan perintah DDL TRUNCATE TABLE, commit dipicu sebelum pernyataan dijalankan. Tindakan ini tidak dapat di-rollback. Anda mungkin ingin menggunakan ini untuk menghapus tabel log secara berkala.

frappe.db.truncate("Error Log")
frappe.db.truncate("__Test Table")

Perintah di atas menjalankan query TRUNCATE pada tabel tabError Log dan __Test Table.

frappe.db.commit

frappe.db.commit()

Melakukan commit transaksi saat ini. Memanggil SQL COMMIT.

Dalam banyak kasus, Anda tidak perlu melakukan commit secara manual. Lihat Model transaksi database Frappe di bawah ini.

frappe.db.savepoint

frappe.db.savepoint(save_point)

Buat savepoint bernama untuk kemudian dapat melakukan rollback ke savepoint tersebut.

frappe.db.rollback

frappe.db.rollback()

Melakukan rollback transaksi saat ini. Memanggil SQL ROLLBACK.

Frappe secara otomatis akan menjalankan frappe.db.rollback() jika terjadi exception selama Web Request dengan tipe POST atau PUT. Gunakan ini jika Anda harus melakukan rollback lebih awal dalam transaksi.

frappe.db.rollback(save_point="save_point_name")

Melakukan rollback ke savepoint tertentu daripada melakukan rollback transaksi penuh. Rollback ini tidak akan membatalkan perubahan yang dilakukan pada filesystem dan pengawas rollback lainnya.

frappe.db.sql

frappe.db.sql(query, values, as_dict)

Menjalankan query SQL arbitrer. Ini mungkin berguna untuk laporan sisi server yang kompleks dengan pernyataan join, menyesuaikan database ke fitur baru, dll.

Contoh:

values = {'company': 'Frappe Technologies Inc'}
data = frappe.db.sql("""
    SELECT
        acc.account_number
        gl.debit
        gl.credit
    FROM `tabGL Entry` gl
        LEFT JOIN `tabAccount` acc
        ON gl.account = acc.name
    WHERE gl.company = %(company)s
""", values=values, as_dict=0)

Hindari menggunakan metode ini karena akan melewati validasi dan pemeriksaan integritas. Lebih baik menggunakan frappe.get_doc, frappe.db.get_list, dll., jika memungkinkan.

frappe.db.multisql

frappe.db.multisql({'mariadb': mariadb_query, 'postgres': postgres_query})

Jalankan pernyataan SQL yang sesuai untuk mesin database yang didukung.

frappe.db.rename_table

frappe.db.rename_table(old_name, new_name)

Menjalankan query untuk mengubah nama tabel. Tentukan nama DocType atau nama tabel internal langsung untuk mengganti nama tabel.

Contoh:

frappe.db.rename_table("__internal_cache", "__temporary_cache")
frappe.db.rename_table("todo", "ToDo")

Contoh kedua hanya boleh digunakan jika Anda memahami konsekuensinya.

Jangan gunakan ini untuk mengganti nama tabel DocType. Gunakan frappe.rename_doc untuk itu.

frappe.db.describe

frappe.db.describe(doctype)

Mengembalikan tuple deskripsi tabel untuk DocType yang diberikan.

frappe.db.change_column_type

frappe.db.change_column_type(doctype, column, new_type)

Mengubah tipe kolom untuk DocType yang ditentukan.

frappe.db.add_index

frappe.db.add_index(doctype, fields, index_name)

Membuat indeks untuk doctypes untuk bidang yang ditentukan.

Catatan: jika Anda ingin indeks pada field TEXT atau BLOB, Anda harus menentukan panjang tetap untuk melakukannya.

Contoh:

frappe.db.add_index("Notes", ["id(10)", "content(500)"], index_name)

frappe.db.add_unique

frappe.db.add_unique(doctype, fields, constraint_name=None)

Membuat constraint unik untuk doctypes untuk bidang yang ditentukan.

Contoh:

frappe.db.add_unique("DoctypeName",["field1","field2"])


Hooks transaksi database

Catatan: API ini diperkenalkan di v15.

Frappe menyediakan hooks untuk menjalankan callback sebelum/sesudah perintah transaksi seperti commit/rollback diterbitkan. Hooks ini berguna untuk:

  • Melakukan rollback perubahan yang dilakukan di luar database jika transaksi di-rollback

  • Menflush perubahan di luar database hanya jika transaksi berhasil di-commit.

Hooks ini adalah:

  • frappe.db.before_commit.add(func: Callable)

  • frappe.db.after_commit.add(func: Callable)

  • frappe.db.before_rollback.add(func: Callable)

  • frappe.db.after_rollback.add(func: Callable)

Contoh penggunaan:

def create_file(self):
    self.write_file()
    # Ini memastikan rollback jika transaksi DB di-rollback
    frappe.db.after_rollback.add(self.rollback_file)

def rollback_file(self):
    self.delete_file()

Model transaksi database

Abstraksi database Frappe mengimplementasikan model transaksi yang wajar secara default. Jadi dalam banyak kasus, Anda tidak perlu menangani transaksi SQL secara manual. Deskripsi umum dari model ini dijelaskan di bawah ini:

Permintaan Web

  • Saat melakukan POST atau PUT, jika ada penulisan yang dilakukan ke database, mereka akan di-commit di akhir permintaan yang berhasil.

  • Panggilan AJAX yang dilakukan menggunakan frappe.call adalah POST secara default kecuali diubah.

  • Permintaan GET tidak menyebabkan commit implisit.

  • Setiap exception yang tidak tertangani selama penanganan permintaan akan melakukan rollback transaksi.

Pekerjaan latar belakang/terjadwal

  • Memanggil fungsi sebagai pekerjaan latar belakang atau terjadwal akan melakukan commit transaksi setelah selesai berhasil.

  • Setiap exception yang tidak tertangani akan menyebabkan rollback transaksi.


Discard
Save
Draft

Previous Page

Left

Next Page

Right

On this page

Review Changes ← Back to Content
Message Status Space Raised By Last update on