Alat bahasa manipulasi data (DML) di SQL MCP Server

Penting

Server Protokol Konteks Model SQL (MCP) tersedia di pembuat API Data versi 1.7 dan yang lebih baru. Untuk kemampuan terbaru dan perbaikan bug, gunakan rilis 2.0 terbaru.

Server SQL Model Context Protocol (MCP) memaparkan tujuh alat Data Manipulation Language (DML) ke agen AI. Alat-alat ini menyediakan permukaan CRUD yang diketik untuk operasi database—membuat, membaca, memperbarui, dan menghapus rekaman, menggabungkan data, ditambah menjalankan prosedur tersimpan. Semua alat menghormati kontrol akses berbasis peran (RBAC), izin entitas, dan kebijakan yang ditentukan dalam konfigurasi Anda.

Peringatan

Agar agen mengkueri entitas secara efektif, konfigurasikan metadata bidang di entitas Anda. Tanpa nama dan deskripsi bidang, agen hanya melihat nama entitas dan mungkin salah menebak nama kolom. Lihat Menambahkan deskripsi ke entitas untuk detailnya.

Apa itu alat DML?

Alat DML (Bahasa Manipulasi Data) menangani operasi data: membuat, membaca, memperbarui, dan menghapus rekaman, menggabungkan data, ditambah menjalankan prosedur tersimpan. Tidak seperti DDL (Bahasa Definisi Data) yang memodifikasi skema, DML bekerja secara eksklusif pada bidang data dalam tabel dan tampilan yang ada.

Tujuh alat DML adalah:

describe_entities - Menemukan entitas dan operasi yang tersedia
create_record - Menyisipkan baris baru
read_records - Kueri tabel dan tampilan
update_record - Memodifikasi baris yang ada
delete_record - Menghapus baris
execute_entity - Menjalankan prosedur tersimpan
aggregate_records - Melaksanakan kueri agregasi

Nota

Fungsionalitas SQL MCP Server yang dijelaskan di bagian ini tersedia di pembuat API Data versi 2.0 dan yang lebih baru. Untuk informasi selengkapnya, lihat Apa yang baru dalam versi 2.0.

Ketersediaan alat menurut versi

Tidak semua alat tersedia di setiap versi. Verifikasi alat yang tersedia di versi terinstal Anda sebelum mengandalkan perilaku yang didokumenkan.

Alat	1.7.x	2.0+	Diaktifkan secara default
`describe_entities`	Yes	Yes	Yes
`create_record`	Yes	Yes	Yes
`read_records`	Yes	Yes	Yes
`update_record`	Yes	Yes	Yes
`delete_record`	Yes	Yes	Yes
`execute_entity`	Yes	Yes	Yes
`aggregate_records`	No	Yes	Yes

Nota

Jika Anda menggunakan versi 1.7.x, aggregate_records tidak tersedia. Agen yang mencoba menjalankan kueri penghitungan atau agregasi harus membaca semua baris yang sesuai sebagai gantinya. Tingkatkan ke versi 2.0 atau yang lebih baru untuk dukungan agregasi asli.

Ketika alat DML diaktifkan secara global dan untuk entitas, SQL MCP Server mengeksposnya melalui protokol MCP. Agen tidak pernah berinteraksi langsung dengan skema database Anda - mereka bekerja melalui lapisan abstraksi penyusun API Data.

Alat-alat

list_tools respons

Saat agen memanggil list_tools, SQL MCP Server mengembalikan:

{
  "tools": [
    { "name": "describe_entities" },
    { "name": "create_record" },
    { "name": "read_records" },
    { "name": "update_record" },
    { "name": "delete_record" },
    { "name": "execute_entity" },
    { "name": "aggregate_records" }
  ]
}

jelaskan_entitas

Mengembalikan entitas yang tersedia untuk peran saat ini. Setiap entri mencakup nama bidang, deskripsi, dan operasi yang diizinkan. Alat ini tidak mengkueri database. Sebaliknya, ia membaca dari konfigurasi di dalam memori yang dibangun dari file konfigurasi Anda.

Metadata bidang berasal dari fields data dalam konfigurasi Anda. Jika Anda tidak menyertakannya, agen hanya melihat nama entitas dengan array kosong fields . Lihat Menambahkan deskripsi ke entitas untuk panduan penyiapan.

Nota

Respons mencakup nilai dari bidang name dan description dalam konfigurasi Anda. Jenis data dan indikator kunci utama tidak disertakan dalam respons saat ini. Parameter prosedur tersimpan juga tidak tercantum. Agen mengandalkan deskripsi entitas dan bidang—bersama dengan umpan balik kesalahan—untuk menentukan penggunaan yang benar.

Parameter-parameternya

Parameter	Tipe	Required	Deskripsi
`nameOnly`	Boolean	No	Ketika `true`, mengembalikan daftar nama dan deskripsi entitas yang ringan tanpa metadata bidang.
`entities`	kumpulan string	No	Membatasi respons terhadap entitas yang ditentukan. Saat dihilangkan, semua entitas yang diaktifkan MCP dikembalikan.

Contoh permintaan

{
  "method": "tools/call",
  "params": {
    "name": "describe_entities",
    "arguments": {
      "entities": ["Products"]
    }
  }
}

Contoh tanggapan

{
  "entities": [
    {
      "name": "Products",
      "description": "Product catalog with pricing and inventory",
      "fields": [
        {
          "name": "ProductId",
          "description": "Unique product identifier"
        },
        {
          "name": "ProductName",
          "description": "Display name of the product"
        },
        {
          "name": "Price",
          "description": "Retail price in USD"
        }
      ],
      "operations": [
        "read_records",
        "update_record"
      ]
    }
  ]
}

Nota

Opsi entitas yang digunakan oleh salah satu ALAT CRUD dan menjalankan DML berasal langsung dari describe_entities. Deskripsi semantik internal yang dilampirkan ke setiap alat memberlakukan alur dua langkah ini.

buat_rekam

Membuat baris baru dalam tabel. Memerlukan izin buat pada entitas untuk peran saat ini. Alat ini memvalidasi input terhadap skema entitas, memberlakukan izin tingkat bidang, menerapkan kebijakan pembuatan, dan mengembalikan rekaman yang dibuat dengan nilai yang dihasilkan.

Parameter-parameternya

Parameter	Tipe	Required	Deskripsi
`entity`	string	Yes	Nama entitas tempat membuat rekaman.
`data`	objek	Yes	Pasangan kunci-nilai nama bidang dan nilai untuk rekaman baru.

read_records

Melakukan kueri pada tabel atau tampilan. Mendukung pemfilteran, pengurutan, penomoran halaman, dan pemilihan bidang. Alat ini membangun SQL deterministik dari parameter terstruktur, menerapkan izin baca dan proyeksi lapangan, dan memberlakukan kebijakan keamanan tingkat baris.

Parameter-parameternya

Parameter	Tipe	Required	Deskripsi
`entity`	string	Yes	Nama entitas yang akan dibaca.
`select`	string	No	Daftar nama bidang yang dipisahkan koma untuk dikembalikan (misalnya, `"id,title,price"`).
`filter`	string	No	Ekspresi filter gaya OData (misalnya, `"Price gt 10 and Category eq 'Books'"`).
`orderby`	kumpulan string	No	Urutkan ekspresi. Setiap elemen adalah nama bidang dengan arah opsional (misalnya, `["Price desc", "Name asc"]`).
`first`	bilangan bulat	No	Jumlah maksimum rekaman yang akan dikembalikan.
`after`	string	No	Kursor kelanjutan dari respons sebelumnya untuk paginasi.

Peringatan

Parameter orderby harus berupa array string, bukan satu string. Meneruskan nilai string dapat memicu UnexpectedError. Gunakan ["Name asc"] alih-alih "Name asc".

Respons pengelolaan halaman

Ketika lebih banyak hasil tersedia, respon menyertakan kursor after. Untuk mengambil halaman berikutnya, berikan nilai ini sebagai after parameter dalam permintaan berikutnya.

{
  "value": [ ... ],
  "after": "W3siRW50aXR5TmFtZ..."
}

Kehadiran bidang after menunjukkan bahwa terdapat lebih banyak halaman. Ketika after tidak ada, respons berisi halaman terakhir.

Penting

Hasil dari read_records secara otomatis dicache menggunakan sistem caching Data API builder. Anda dapat mengonfigurasi cache time-to-live (TTL) secara global atau per entitas untuk mengurangi beban database.

Operasi Penggabungan (JOIN)

Alat read_records ini dirancang untuk satu tabel atau tampilan. Akibatnya, operasi JOIN tidak didukung dalam alat ini. Desain ini membantu mengisolasi tanggung jawab, meningkatkan performa, dan membatasi dampak pada jendela konteks sesi Anda.

Namun, operasi JOIN bukan kasus tepi, dan penyusun API Data (DAB) sudah mendukung kueri canggih melalui titik akhir GraphQL. Untuk kueri yang lebih kompleks, sebaiknya gunakan tampilan alih-alih tabel. Anda juga dapat menggunakan alat execute_entity untuk menjalankan prosedur tersimpan yang membungkus kueri berparameter.

perbarui_catatan

Memodifikasi baris yang sudah ada. Memerlukan kunci utama dan bidang yang akan diperbarui. Alat ini memvalidasi kunci utama yang sudah ada, menegakkan izin dan kebijakan pembaruan, dan hanya memperbarui bidang yang dapat diubah oleh peran pengguna saat ini.

Parameter-parameternya

Parameter	Tipe	Required	Deskripsi
`entity`	string	Yes	Nama entitas yang akan diperbarui.
`keys`	objek	Yes	Pasangan kunci-nilai yang mengidentifikasi rekaman (misalnya, `{"id": 42}`).
`fields`	objek	Yes	Pasangan kunci-nilai nama bidang dan nilai baru.

hapus_rekam

Menghapus baris yang sudah ada. Memerlukan kunci primer. Alat ini memvalidasi kunci utama yang ada, memberlakukan izin dan kebijakan penghapusan, dan melakukan penghapusan yang aman dengan dukungan transaksi.

Parameter-parameternya

Parameter	Tipe	Required	Deskripsi
`entity`	string	Yes	Nama entitas yang akan dihapus.
`keys`	objek	Yes	Pasangan kunci-nilai yang mengidentifikasi rekaman (misalnya, `{"id": 42}`).

Nota

Beberapa skenario produksi menonaktifkan alat ini secara global untuk membatasi model secara luas. Pilihan ini terserah Anda, dan perlu diingat bahwa izin tingkat entitas tetap menjadi cara terpenting untuk mengontrol akses. Bahkan dengan delete-record diaktifkan, jika peran tidak memiliki izin penghapusan pada entitas, peran tersebut tidak dapat menggunakan alat ini untuk entitas tersebut.

execute_entity

Menjalankan prosedur tersimpan. Mendukung parameter input dan hasil output. Alat ini memvalidasi parameter input terhadap tanda tangan prosedur, memberlakukan izin eksekusi, dan melewati parameter dengan aman.

Parameter-parameternya

Parameter	Tipe	Required	Deskripsi
`entity`	string	Yes	Nama entitas prosedur tersimpan.
`parameters`	objek	No	Pasangan kunci-nilai dari nama dan nilai parameter input.

menggabungkan_catatan

Melakukan kueri agregasi pada tabel dan tampilan. Mendukung fungsi agregat umum seperti hitungan, jumlah, rata-rata, minimum, dan maksimum. Alat ini membangun SQL deterministik dari parameter terstruktur, menerapkan izin baca dan proyeksi lapangan, dan memberlakukan kebijakan keamanan tingkat baris.

Parameter-parameternya

Parameter	Tipe	Required	Deskripsi
`entity`	string	Yes	Nama entitas untuk diagregasikan.
`function`	string	Yes	Fungsi agregat: `count`, , `sum`, `avg`, `min`atau `max`.
`field`	string	Yes	Bidang untuk diagregasi. Gunakan `"*"` untuk `count`.
`filter`	string	No	Filter gaya OData diterapkan sebelum agregasi.
`distinct`	Boolean	No	Ketika `true`, menghapus nilai duplikat sebelum menggabungkan.
`groupby`	kumpulan string	No	Nama bidang untuk mengelompokkan hasil menurut (misalnya, `["Category", "Status"]`).
`having`	objek	No	Memfilter grup menurut nilai agregat. Menggunakan operator: `eq`, , `neq`, `gt`, `gtelt`, , `ltein`.
`orderby`	kumpulan string	No	Urutkan ekspresi untuk hasil yang dikelompokkan (misalnya, `["count desc"]`).
`first`	bilangan bulat	No	Jumlah maksimum hasil yang dikelompokkan yang akan dikembalikan.
`after`	string	No	Kursor kelanjutan untuk paginating mengelompokkan hasil.

Contoh: menghitung dengan GROUP BY dan HAVING

{
  "method": "tools/call",
  "params": {
    "name": "aggregate_records",
    "arguments": {
      "entity": "Todo",
      "function": "count",
      "field": "*",
      "groupby": ["UserId"],
      "having": { "gt": 2 }
    }
  }
}

Alat ini aggregate-records dapat dikonfigurasi sebagai boolean atau sebagai objek dengan lebih banyak pengaturan:

{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

Properti query-timeout menentukan waktu eksekusi maksimum dalam detik (rentang: 1–600). Pengaturan ini membantu mencegah kueri agregasi jangka panjang mengonsumsi sumber daya yang berlebihan.

Konfigurasi runtime

Konfigurasikan alat DML secara global di bagian runtime Anda dab-config.json:

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "path": "/mcp",
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": true
      }
    }
  }
}

Setiap properti alat di bawah runtime.mcp.dml-tools menerima true atau false. Alat ini aggregate-records juga mendukung format objek dengan enabled dan query-timeout:

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

Untuk mengaktifkan atau menonaktifkan semua alat DML sekaligus, atur "dml-tools" ke true atau false.

Menggunakan CLI

Atur properti satu per satu menggunakan CLI penyusun API Data:

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true
dab configure --runtime.mcp.dml-tools.aggregate-records.query-timeout 30

Menonaktifkan alat

Saat Anda menonaktifkan alat di tingkat runtime, alat tersebut tidak pernah muncul untuk agen, terlepas dari izin entitas atau konfigurasi peran. Pengaturan ini berguna ketika Anda memerlukan batas operasional yang ketat.

Skenario umum

Nonaktifkan delete-record untuk mencegah kehilangan data dalam produksi
Nonaktifkan create-record untuk titik akhir pelaporan baca-saja
Nonaktifkan execute-entity saat prosedur tersimpan tidak digunakan
Nonaktifkan aggregate-records saat kueri agregasi tidak diperlukan

Ketika alat dinonaktifkan secara global, alat disembunyikan dari list_tools respons dan tidak dapat dipanggil.

Pengaturan entitas

Entitas berpartisipasi dalam MCP secara otomatis kecuali Anda secara eksplisit membatasinya. Properti mcp pada entitas mengontrol partisipasi MCP-nya. Gunakan format objek untuk kontrol eksplisit.

Format objek

{
  "entities": {
    "Products": {
      "mcp": {
        "dml-tools": true
      }
    },
    "SensitiveData": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

Jika Anda tidak menentukan mcp pada entitas, alat DML default untuk diaktifkan saat MCP diaktifkan secara global.

Alat kustom untuk prosedur tersimpan

Untuk entitas prosedur tersimpan, Anda juga dapat mendaftarkan prosedur tersebut sebagai alat MCP bernama dengan menggunakan properti custom-tool. Lihat Mengonfigurasi alat MCP kustom untuk instruksi penyiapan.

Cakupan kontrol per alat

Pengalih per alat hanya dikonfigurasikan pada tingkat runtime global di bawah runtime.mcp.dml-tools.

Pada tingkat entitas, mcp adalah gerbang boolean atau objek dengan properti dml-tools dan custom-tool.

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": false,
        "execute-entity": true,
        "aggregate-records": true
      }
    }
  }
}

Alat hanya tersedia jika diaktifkan secara global dan entitas mengizinkan alat DML.

Integrasi RBAC

Setiap operasi alat DML memberlakukan aturan kontrol akses berbasis peran Anda. Peran agen menentukan entitas mana yang terlihat, operasi mana yang diizinkan, kolom mana yang disertakan, dan apakah kebijakan tingkat baris berlaku.

Jika peran anonymous hanya mengizinkan izin baca pada Products:

describe_entities hanya menampilkan read_records dalam operasi
create_record, update_record, dan delete_record tidak tersedia
Hanya bidang yang diizinkan untuk anonymous muncul dalam skema

Konfigurasikan peran di `dab-config.json`:

{
  "entities": {
    "Products": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["ProductId", "ProductName", "Price"],
                "exclude": ["Cost"]
              }
            }
          ]
        },
        {
          "role": "admin",
          "actions": [
            {
              "action": "*"
            }
          ]
        }
      ]
    }
  }
}

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-06-19

Alat bahasa manipulasi data (DML) di SQL MCP Server

Apa itu alat DML?

Ketersediaan alat menurut versi

Alat-alat

list_tools respons

jelaskan_entitas

Parameter-parameternya

Contoh permintaan

Contoh tanggapan

buat_rekam

Parameter-parameternya

read_records

Parameter-parameternya

Respons pengelolaan halaman

Operasi Penggabungan (JOIN)

perbarui_catatan

Parameter-parameternya

hapus_rekam

Parameter-parameternya

execute_entity

Parameter-parameternya

menggabungkan_catatan

Parameter-parameternya

Contoh: menghitung dengan GROUP BY dan HAVING

Konfigurasi runtime

Menggunakan CLI

Menonaktifkan alat

Skenario umum

Pengaturan entitas

Format objek

Alat kustom untuk prosedur tersimpan

Cakupan kontrol per alat

Integrasi RBAC

Konfigurasikan peran di dab-config.json:

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan:

Konfigurasikan peran di `dab-config.json`: