البيانات والـ API في SDK
تمر كل عمليات البيانات عبر endpoints مخصصة تنشئها في بنّاء الـ API. لا تولّد DYPAI تلقائياً endpoints من نوع REST لجداولك — تحتاج دائماً إلى إنشائها أولاً.
استدعاء Endpoints (dypai.api)
استخدم dypai.api لاستدعاء أي endpoint أُنشئ بـ بنّاء الـ API. كل طرق HTTP مدعومة.
GET (قراءة)
استرجع البيانات مع تصفية وترقيم صفحات مضمّنين.
// Simple list
const { data, error } = await dypai.api.get('get_products', {
params: { category: 'electronics', limit: 10 }
});
// Paged list
const { data, error } = await dypai.api.get('get_products', {
params: { limit: 20, offset: 0 }
});
POST (إنشاء / إجراء)
أنشئ سجلات أو شغّل سير عمل معقّداً.
const { data, error } = await dypai.api.post('create_order', {
customer_id: 'uuid-123',
items: [{ id: 'p1', qty: 2 }]
});
PUT / PATCH (تحديث)
const { data, error } = await dypai.api.put('update_product/product-uuid', {
price: 29.99
});
DELETE
const { error } = await dypai.api.delete('delete_product/product-uuid');
يجب أن يقابل كل اسم endpoint (مثلاً get_products و create_order) endpoint أنشأته في بنّاء الـ API. إذا لم يكن endpoint موجوداً، سيُرجع SDK خطأ 404.
تبث endpoint وكيل ذكاء اصطناعي؟
لـ endpoints وكلاء الذكاء الاصطناعي (وأي endpoint معلَّم بـ is_tool)، استخدم dypai.api.stream(name, body) لاستقبال الرموز أثناء توليدها. يغلّف خطاف useChat هذا لك — راجع دردشة الذكاء الاصطناعي.
عوامل التصفية
عند استخدام params في طلبات GET، يمكنك استخدام عوامل قوية:
| العامل | الوصف | مثال |
|---|---|---|
eq | يساوي | status: { eq: 'active' } |
gt / gte | أكبر من | price: { gte: 100 } |
contains | بحث نصي | name: { contains: 'pizza' } |
in | في قائمة | id: { in: ['1', '2'] } |
الوصول المباشر إلى قاعدة البيانات (db.direct)
جانب الخادم فقط. هذا للسكربتات والهجرات والبذور وكود الخلفية. لا تعرض serviceRoleKey أبداً في كود المتصفح. لوصول بيانات المستخدم النهائي، استخدم endpoints عبر dypai.api.
يتجاوز الوصول المباشر إلى قاعدة البيانات endpoints وسير العمل. يتطلب serviceRoleKey:
import { createClient } from '@dypai-ai/client-sdk';
const dypaiAdmin = createClient('https://your-project.dypai.app', {
serviceRoleKey: process.env.DYPAI_SERVICE_ROLE_KEY!,
});
التحديد مع التصفيات
const { data } = await dypaiAdmin.db.direct
.from('products')
.eq('active', true)
.gt('price', 50)
.orderBy('price', 'DESC')
.limit(20)
.select();
// Select specific columns
const { data } = await dypaiAdmin.db.direct.from('products').select('id, name, price');
// Single row
const { data: user } = await dypaiAdmin.db.direct.from('users').eq('id', id).single();
// Count
const { data: count } = await dypaiAdmin.db.direct.from('orders').eq('status', 'pending').count();
الإدراج والتحديث والحذف
// Insert (single or bulk — auto-chunks at 1,000 rows)
await dypaiAdmin.db.direct.from('products').insert({ name: 'Widget', price: 9.99 });
await dypaiAdmin.db.direct.from('products').insert(thousandRows);
// Update (filter required)
await dypaiAdmin.db.direct.from('products').eq('category', 'old').update({ active: false });
// Delete (filter required)
await dypaiAdmin.db.direct.from('products').eq('id', 'abc').delete();
// Upsert (insert or update on conflict)
await dypaiAdmin.db.direct.from('products').upsert({ id: '1', name: 'Widget' }, 'id');
SQL خام
await dypaiAdmin.db.direct.sql('ALTER TABLE products ADD COLUMN sku TEXT');
const { data } = await dypaiAdmin.db.direct.sql(
'SELECT category, COUNT(*) FROM products WHERE price > $1 GROUP BY category',
[25]
);
التصفيات المتاحة
| الطريقة | SQL | مثال |
|---|---|---|
.eq(col, val) | = | .eq('status', 'active') |
.neq(col, val) | != | .neq('role', 'banned') |
.gt() .gte() .lt() .lte() | > >= < <= | .gt('price', 50) |
.like(col, val) | ILIKE %val% | .like('name', 'widget') |
.in(col, arr) | IN (...) | .in('status', ['a', 'b']) |
.isNull(col) | IS NULL | .isNull('deleted_at') |
.notNull(col) | IS NOT NULL | .notNull('email') |
.contains(col, val) | @> (array/JSONB) | .contains('tags', ['sale']) |
.containedBy(col, val) | <@ | .containedBy('tags', ['a','b']) |
.overlaps(col, val) | && (array overlap) | .overlaps('tags', ['x']) |
.textSearch(col, q) | Full-text search | .textSearch('desc', 'wireless') |
.not(col, op, val) | Negate any filter | .not('status', 'eq', 'deleted') |
.or([...]) | OR group | .or([{column:'a',operator:'eq',value:1}]) |