SQL MCP Server'da veri işleme dili (DML) araçları

Önemli

SQL Model Bağlam Protokolü (MCP) Sunucusu, Veri API oluşturucusu sürüm 1.7 ve sonraki sürümlerde kullanılabilir. En son özellikler ve hata düzeltmeleri için en son 2.0 sürümünü kullanın.

SQL Model Bağlam Protokolü (MCP) Sunucusu, yedi Veri İşleme Dili (DML) aracını yapay zeka aracılarına sunar. Bu araçlar, kayıt oluşturma, okuma, güncelleştirme ve silme, verileri toplama ve saklı yordamları yürütme gibi veritabanı işlemleri için türlenmiş bir CRUD yüzeyi sağlar. Tüm araçlar rol tabanlı erişim denetimine (RBAC), varlık izinlerine ve yapılandırmanızda tanımlanan ilkelere uyar.

Uyarı

Aracıların varlıkları etkili bir şekilde sorgulaması için varlıklarınızdaki alan meta verilerini yapılandırın. Alan adları ve açıklamalar olmadan aracılar yalnızca varlık adlarını görür ve sütun adlarını yanlış tahmin edebilir. Ayrıntılar için bkz. Varlıklara açıklama ekleme .

DML araçları nedir?

DML (Veri İşleme Dili) araçları veri işlemlerini işler: kayıtları oluşturma, okuma, güncelleştirme ve silme, verileri toplama ve saklı yordamları yürütme. Şemayı değiştiren DDL'nin (Veri Tanım Dili) aksine, DML yalnızca mevcut tablo ve görünümlerdeki veri düzleminde çalışır.

Yedi DML aracı şunlardır:

  • describe_entities - Kullanılabilir varlıkları ve işlemleri bulur
  • create_record - Yeni satır ekler
  • read_records - Sorgu tabloları ve görünümleri
  • update_record - Varolan satırları değiştirir
  • delete_record - Satırları kaldırır
  • execute_entity - Saklı yordamları çalıştırır
  • aggregate_records - Toplama sorguları gerçekleştirir

Uyarı

Bu bölümde açıklanan SQL MCP Server işlevselliği, Veri API oluşturucusu 2.0 ve sonraki sürümlerde kullanılabilir. Daha fazla bilgi için bkz. Sürüm 2.0'daki yenilikler.

Sürüme göre araçların kullanılabilirliği

Tüm araçlar her sürümde kullanılamaz. Belgelenmiş davranışa güvenmeden önce yüklü sürümünüzde kullanılabilen araçları doğrulayın.

Aracı 1.7.x 2.0+ Varsayılan olarak etkin
describe_entities Evet Evet Evet
create_record Evet Evet Evet
read_records Evet Evet Evet
update_record Evet Evet Evet
delete_record Evet Evet Evet
execute_entity Evet Evet Evet
aggregate_records Hayır Evet Evet

Uyarı

1.7.x sürümünü kullanıyorsanız aggregate_records mevcut değildir. Sayı veya toplama sorgularını deneyen aracıların bunun yerine tüm eşleşen satırları okuması gerekir. Yerel toplama desteği için sürüm 2.0 veya sonraki bir sürüme yükseltin.

DML araçları genel olarak ve bir varlık için etkinleştirildiğinde, SQL MCP Server bunları MCP protokolü aracılığıyla kullanıma sunar. Aracılar hiçbir zaman veritabanı şemanızla doğrudan etkileşim kurmaz; Veri API'sinin oluşturucu soyutlama katmanı üzerinden çalışır.

Araçlar

list_tools yanıtı

Bir aracı çağırdığında list_tools, SQL MCP Server şunu döndürür:

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

varlıkları tanımla

Geçerli role uygun varlıkları geri döndürür. Her girdi alan adlarını, açıklamaları ve izin verilen işlemleri içerir. Bu araç veritabanını sorgulamaz. Bunun yerine, yapılandırma dosyanızdan oluşturulan bellek içi yapılandırmadan okur.

Alan meta verileri, yapılandırmanızdaki verilerden fields gelir. Eklemezseniz, aracılar yalnızca boş fields bir diziye sahip varlık adlarını görür. Kurulum kılavuzu için bkz. Varlıklara açıklama ekleme .

Uyarı

Yanıt, yapılandırmanızdaki alanı name ve description değerleri içerir. Veri türleri ve birincil anahtar göstergeleri geçerli yanıta dahil değildir. Saklı yordam parametreleri de listelenmez. Aracılar, doğru kullanımı belirlemek için varlık ve alan açıklamalarının yanı sıra hata geri bildirimlerine de güvenir.

Parametreler

Parametre Türü Zorunlu Açıklama
nameOnly Boolean Hayır olduğunda true, alan meta verileri olmadan varlık adlarının ve açıklamalarının basit bir listesini döndürür.
entities stringler dizisi Hayır Yanıtı belirtilen varlıklarla sınırlar. Hariç tutulduğunda, tüm MCP özellikli varlıklar döndürülür.

Örnek istek

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

Örnek yanıt

{
  "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"
      ]
    }
  ]
}

Uyarı

CRUD ve yürütme DML araçlarından herhangi biri tarafından kullanılan varlık seçenekleri doğrudan describe_entities öğesinden gelir. Her araca bağlı iç anlamsal açıklama, bu iki adımlı akışı sağlar.

kayıt oluştur

Tabloda yeni bir satır oluşturur. Geçerli rol için birimde oluşturma izni gerektirir. Araç girişi varlık şemasına göre doğrular, alan düzeyi izinleri zorlar, oluşturma ilkeleri uygular ve oluşturulan kaydı oluşturulan tüm değerlerle döndürür.

Parametreler

Parametre Türü Zorunlu Açıklama
entity String Evet Kayıt oluşturulacak varlık adı.
data nesne Evet Yeni kayıt için alan adları ve değerlerine ait anahtar-değer çiftleri.

kayıtları_oku

Bir tablo veya görünümü sorgular. Filtreleme, sıralama, sayfalandırma ve alan seçimini destekler. Araç yapılandırılmış parametrelerden deterministik SQL oluşturur, okuma izinleri ve alan projeksiyonları uygular ve satır düzeyi güvenlik ilkelerini uygular.

Parametreler

Parametre Türü Zorunlu Açıklama
entity String Evet Okunacak varlık adı.
select String Hayır Döndürülecek alan adlarının virgülle ayrılmış listesi (örneğin, "id,title,price").
filter String Hayır OData stili filtre ifadesi (örneğin, "Price gt 10 and Category eq 'Books'").
orderby stringler dizisi Hayır İfadeleri sırala Her öğe isteğe bağlı yönü olan bir alan adıdır (örneğin, ["Price desc", "Name asc"]).
first tamsayı Hayır Döndürülecek en fazla kayıt sayısı.
after String Hayır Sayfalandırma için önceki bir yanıttan devam imleci.

Uyarı

orderby parametresi tek bir dize şeklinde olmamalı, bir dizeler dizisi olmalıdır. Dize değerinin geçirilmesi bir UnexpectedError öğesine neden olur. ["Name asc"]yerine "Name asc" kullanın.

Sayfalandırma yanıtı

Daha fazla sonuç olduğunda, yanıt bir after imleç içerir. Sonraki sayfayı getirmek için bu değeri bir sonraki istekte parametre olarak after geçirin.

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

Alan after daha fazla sayfanın varlığını gösterir. Yanıt after olmadığında son sayfayı içerir.

Önemli

read_records sonuçları, Veri API'si oluşturucusundan gelen önbelleğe alma sistemi kullanılarak otomatik olarak önbelleğe alınır. Veritabanı yükünü azaltmak için önbellek yaşam süresini (TTL) genel olarak veya varlık başına yapılandırabilirsiniz.

JOIN işlemleri

Araç read_records , tek bir tablo veya görünüm için tasarlanmıştır. Sonuç olarak, JOIN işlemleri bu araçta desteklenmez. Bu tasarım sorumluluğu yalıtmanıza, performansı iyileştirmenize ve oturumunuzun bağlam penceresi üzerindeki etkiyi sınırlamanıza yardımcı olur.

Bununla birlikte, JOIN işlemleri bir uç durum değildir ve Veri API oluşturucusu (DAB), GraphQL uç noktası üzerinden karmaşık sorgulamayı zaten destekler. Daha karmaşık sorgular için tablo yerine görünüm kullanmanızı öneririz. Aracı, parametreli sorguları kapsülleyen saklı yordamları çalıştırmak için de kullanabilirsiniz execute_entity.

kayıt_güncelle

Var olan bir satırı değiştirir. Güncellenecek birincil anahtar ve alanlar gereklidir. Araç birincil anahtarın mevcut olduğunu doğrular, güncelleştirme izinlerini ve ilkelerini zorlar ve yalnızca geçerli rolün değiştirebileceği alanları güncelleştirir.

Parametreler

Parametre Türü Zorunlu Açıklama
entity String Evet Güncellenecek varlık adı.
keys nesne Evet Kaydı tanımlayan anahtar-değer çiftleri (örneğin, {"id": 42}).
fields nesne Evet Alan adlarının ve yeni değerlerin anahtar-değer çiftleri.

kayıt_sil

Varolan bir satırı kaldırır. Ana anahtarı gerektirir. Araç birincil anahtarın mevcut olduğunu doğrular, silme izinlerini ve ilkelerini zorlar ve işlem desteğiyle güvenli silme gerçekleştirir.

Parametreler

Parametre Türü Zorunlu Açıklama
entity String Evet Silinecek varlık adı.
keys nesne Evet Kaydı tanımlayan anahtar-değer çiftleri (örneğin, {"id": 42}).

Uyarı

Bazı üretim senaryoları, modelleri kapsamlı bir şekilde kısıtlamak için bu aracı genel olarak devre dışı bırakır. Bu seçim size kalmıştır ve varlık düzeyi izinlerinin erişimi denetlemenin en önemli yolu olmaya devam ettiğini unutmayın. delete-record Etkin olsa bile, bir rolün varlık üzerinde silme izni yoksa bu rol bu varlık için bu aracı kullanamaz.

execute_entity

Bir saklı yordam çalıştırır. Giriş parametrelerini ve çıkış sonuçlarını destekler. Araç giriş parametrelerini yordam imzasına karşı doğrular, yürütme izinlerini zorlar ve parametreleri güvenli bir şekilde geçirir.

Parametreler

Parametre Türü Zorunlu Açıklama
entity String Evet Saklı yordam varlık adı.
parameters nesne Hayır Giriş parametresi adlarının ve değerlerinin anahtar-değer çiftleri.

kayıtları birleştir

Tablolarda ve görünümlerde toplama sorguları gerçekleştirir. Count, sum, average, minimum ve maximum gibi yaygın toplama işlevlerini destekler. Araç yapılandırılmış parametrelerden deterministik SQL oluşturur, okuma izinleri ve alan projeksiyonları uygular ve satır düzeyi güvenlik ilkelerini uygular.

Parametreler

Parametre Türü Zorunlu Açıklama
entity String Evet Toplanacak öğe adı.
function String Evet Toplama işlevi: count, sum, avg, minveya max.
field String Evet Toplanacak alan. "*" için count kullanın.
filter String Hayır Toplamadan önce uygulanan OData stili filtre.
distinct Boolean Hayır olduğunda true, toplamadan önce yinelenen değerleri kaldırır.
groupby stringler dizisi Hayır Sonuçları gruplandırmak için alan adları (örneğin, ["Category", "Status"]).
having nesne Hayır Grupları toplama değerine göre filtreler. İşleçleri kullanır: eq, neq, gt, gte, lt, lte, in.
orderby stringler dizisi Hayır Gruplandırılmış sonuçlar için ifadeleri sıralama (örneğin, ["count desc"]).
first tamsayı Hayır Döndürülecek en fazla gruplandırılmış sonuç sayısı.
after String Hayır Gruplandırılmış sonuçları sayfalandırmak için devam imleci.

Örnek: COUNT ile GROUP BY ve HAVING

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

Araç aggregate-records boole olarak veya daha fazla ayara sahip bir nesne olarak yapılandırılabilir:

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

query-timeout özelliği en fazla yürütme süresini saniye cinsinden belirtir (aralık: 1-600). Bu ayar, uzun süre çalışan toplama sorgularının aşırı kaynak tüketmesini önlemeye yardımcı olur.

Çalışma zamanı yapılandırması

DML araçlarını, çalışma dab-config.jsonzamanı bölümünde genel olarak yapılandırın:

{
  "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
      }
    }
  }
}

altındaki runtime.mcp.dml-tools her araç özelliği veya truekabul ederfalse. Araç, aggregate-recordsenabledquery-timeout ile bir nesne biçimini de destekler.

{
  "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
        }
      }
    }
  }
}

Tüm DML araçlarını aynı anda etkinleştirmek veya devre dışı bırakmak için "dml-tools" değerini true veya false olarak ayarlayın.

CLI'yi kullanma

Veri API'si oluşturucu CLI'sını kullanarak özellikleri ayrı ayrı ayarlayın:

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

Araçları devre dışı bırakma

Bir aracı çalışma zamanı düzeyinde devre dışı bırakırsanız, varlık izinlerinden veya rol yapılandırmasından bağımsız olarak aracılara hiçbir zaman gösterilmez. Bu ayar, katı operasyonel sınırlara ihtiyacınız olduğunda kullanışlıdır.

Yaygın senaryolar

  • Üretimde veri kaybını önlemek için devre dışı bırakma delete-record
  • "create-record'yi salt okunur raporlama uç noktaları için devre dışı bırak"
  • execute-entity saklı yordamlar kullanılmadığında devre dışı bırakın
  • Toplama sorguları gerekli olmadığında devre dışı bırakma aggregate-records

Bir araç genel olarak devre dışı bırakıldığında, araç yanıttan gizlenir list_tools ve çağrılamıyor.

Varlık ayarları

Siz açıkça kısıtlamadığınız sürece varlıklar MCP'ye otomatik olarak katılır. Bir mcp varlık üzerindeki özellik, MCP katılımını denetler. Açık denetim için nesne biçimini kullanın.

Nesne biçimi

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

Bir varlıkta belirtmezseniz mcp , MCP genel olarak etkinleştirildiğinde DML araçları varsayılan olarak etkin olur.

Saklı yordamlar için özel araçlar

Depolanmış yordam varlıkları için, yordamı custom-tool özelliğini kullanarak adlandırılmış bir MCP aracı olarak da kaydedebilirsiniz. Kurulum yönergeleri için bkz. Özel MCP araçlarını yapılandırma .

Araç başına denetimin kapsamı

Araç başına geçişler yalnızca genel çalışma zamanı düzeyinde runtime.mcp.dml-tools altında yapılandırılır.

Varlık düzeyinde, mcp bir boole kapısıdır veya dml-tools ve custom-tool özelliklerine sahip bir nesnedir.

{
  "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
      }
    }
  }
}

Bir araç yalnızca genel olarak etkinleştirildiğinde kullanılabilir ve varlık DML araçlarına izin verir.

RBAC entegrasyonu

Her DML aracı işlemi rol tabanlı erişim denetimi kurallarınızı zorunlu kılar. Bir temsilcinin rolü, hangi varlıkların görünür olduğunu, hangi işlemlere izin verileceğini, hangi alanların dahil edileceğini ve satır seviyesinde politikaların uygulanıp uygulanmayacağını belirler.

anonymous rolü yalnızca Products üzerinde okuma izni veriyorsa:

  • describe_entitiesyalnızca işlemlerde gösterilir read_records
  • create_record, update_recordve delete_record kullanılamıyor
  • Şemada yalnızca anonymous için izin verilen alanlar görünür.

dab-config.json içindeki rollerinizi yapılandırın.

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

İlgili içerik

  • Last updated on