SDK Smart Tables

Le SmartTablesSDK offre une solution complète pour gérer des tables de données structurées avec des capacités avancées de requête, filtrage, tri et manipulation de données. Créez des applications puissantes de gestion de données avec facilité, avec support pour les vues personnalisées, l'importation/exportation de données et le traitement de données alimenté par l'IA.

Installation

npm install @odin-ai-staging/sdk

Démarrage rapide

Dans cet exemple, vous apprendrez comment utiliser SmartTablesSDK pour créer et gérer par programmation des tables de données structurées via l'API EKB. Vous commencez en initialisant le SDK avec vos identifiants API (URL de base, ID de projet, clé API et secret), puis suivez un flux de travail simple pour construire une base de données fonctionnelle : d'abord, vous créez une nouvelle table avec `createTable()` en fournissant un nom et une description (dans ce cas, « Base de données client »), puis vous définissez la structure de la table en ajoutant des colonnes avec `addColumn()`, en spécifiant le nom, le type de données (comme « texte » ou « e-mail ») et la description de chaque colonne. Une fois votre structure de table configurée, vous pouvez la remplir avec des données en utilisant `addRow()` pour insérer les enregistrements sous forme de paires clé-valeur, et enfin interroger vos données avec `queryTable()`, qui prend en charge le filtrage (avec des opérateurs comme « contains »), la pagination et d'autres paramètres de requête pour récupérer exactement les données dont vous avez besoin. Cela vous donne une solution complète et programmable pour créer des structures de type base de données avec des capacités alimentées par l'IA, parfaite pour construire des systèmes dynamiques de gestion de données, des outils CRM ou toute application où vous devez stocker, organiser et interroger des informations structurées via une API—sans gérer l'infrastructure traditionnelle de base de données.

import { SmartTablesSDK } from '@odin-ai-staging/sdk';

// Initialiser le SDK
const smartTablesSDK = new SmartTablesSDK({
  baseUrl: 'https://your-api-endpoint.com/',
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

// Exemple rapide : Créer une table et ajouter des données
async function quickExample() {
  // Créer une nouvelle table
  const table = await smartTablesSDK.createTable(
    'Customer Database',
    'Manage customer information'
  );
  
  // Ajouter des colonnes
  await smartTablesSDK.addColumn(table.id, {
    name: 'name',
    type: 'text',
    description: 'Customer name'
  });
  
  await smartTablesSDK.addColumn(table.id, {
    name: 'email',
    type: 'email',
    description: 'Customer email address'
  });
  
  // Ajouter des données
  await smartTablesSDK.addRow(table.id, {
    name: 'John Doe',
    email: 'john@example.com'
  });
  
  // Interroger les données
  const results = await smartTablesSDK.queryTable(table.id, {
    filters: [{ column: 'name', operator: 'contains', value: 'John' }],
    pagination: { limit: 10, page: 1 }
  });
  
  console.log('Query results:', results.data);
}

Configuration

Interface SmartTablesSDKConfig

interface SmartTablesSDKConfig {
  baseUrl: string;          // URL de point d'accès API
  projectId: string;        // Votre identifiant de projet
  apiKey?: string;          // Clé API pour l'authentification
  apiSecret?: string;       // Secret API pour l'authentification
  accessToken?: string;     // Jeton d'accès pour l'utilisation d'application web
}

SmartTablesSDK utilise la même configuration que les autres composants SDK, étendant BaseClientConfig.

Concepts clés

SmartTable

Une SmartTable représente une table de données structurée avec schéma, métadonnées et capacités de gestion de données.

interface SmartTable {
  id: string;                    // Identifiant unique de la table
  project_id: string;            // Projet auquel appartient cette table
  title: string;                 // Nom d'affichage de la table
  description: string;           // Description de la table
  schema: SmartTableColumn[];    // Définitions de colonnes
  table_name: string;           // Nom interne de la table
  created_at?: number;          // Horodatage de création
  updated_at?: number;          // Horodatage de dernière mise à jour
}

SmartTableColumn

Définit la structure et les propriétés des colonnes de table.

interface SmartTableColumn {
  name: string;                           // Nom de la colonne
  type: ColumnType;                       // Type de données
  description?: string;                   // Description de la colonne
  notNull?: boolean;                      // Champ obligatoire
  unique?: boolean;                       // Contrainte d'unicité
  defaultValue?: string | number | boolean | null;  // Valeur par défaut
  options?: Record<string, unknown>;      // Options supplémentaires
}

type ColumnType = 'text' | 'number' | 'boolean' | 'date' | 'email' | 'url' | 'json';

Filtrage et requête

Système de filtrage avancé avec plusieurs opérateurs et options de tri.

interface TableFilter {
  column: string;
  operator: FilterOperator;
  value: string | number | boolean | null;
}

type FilterOperator = 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'startswith' | 'endswith';

interface TableSort {
  column: string;
  direction: 'asc' | 'desc';
}

interface TablePagination {
  page?: number;
  limit?: number;
  search?: string;
}

Gestion de table

`getAllTables()`

Récupérez toutes les tables du projet.

async getAllTables(): Promise<SmartTable[]>

Exemple:

const tables = await smartTablesSDK.getAllTables();
tables.forEach(table => {
  console.log(\`Table: \${table.title} (\${table.id})\`);
  console.log(\`Columns: \${table.schema.length}\`);
});

`getTable(tableId)`

Obtenez une table spécifique par ID.

async getTable(tableId: string): Promise<SmartTable>

Exemple:

const table = await smartTablesSDK.getTable('table_123');
console.log('Table schema:', table.schema);

`createTable(title, description, metadata?)`

Créez une nouvelle table.

async createTable(
  title: string,
  description: string,
  metadata?: Record<string, unknown>
): Promise<SmartTable>

Exemple:

const table = await smartTablesSDK.createTable(
  'Product Catalog',
  'Manage product information and inventory',
  { category: 'inventory', owner: 'admin' }
);

`updateTable(tableId, title, description?, metadata?)`

Mettez à jour les métadonnées de table.

async updateTable(
  tableId: string,
  title: string,
  description?: string,
  metadata?: Record<string, unknown>
): Promise<void>

Exemple:

await smartTablesSDK.updateTable(
  'table_123',
  'Updated Product Catalog',
  'Enhanced product management system',
  { version: '2.0' }
);

`deleteTable(tableId)`

Supprimez une table et toutes ses données de façon permanente.

async deleteTable(tableId: string): Promise<void>

Exemple:

await smartTablesSDK.deleteTable('table_123');

Opérations de colonnes

`addColumn(tableId, column)`

Ajoutez une nouvelle colonne à la table.

async addColumn(tableId: string, column: SmartTableColumn): Promise<void>

Exemple:

// Ajouter une colonne texte
await smartTablesSDK.addColumn('table_123', {
  name: 'product_name',
  type: 'text',
  description: 'Name of the product',
  notNull: true
});

// Ajouter une colonne nombre avec valeur par défaut
await smartTablesSDK.addColumn('table_123', {
  name: 'price',
  type: 'number',
  description: 'Product price in USD',
  defaultValue: 0,
  notNull: true
});

// Ajouter une colonne e-mail avec validation
await smartTablesSDK.addColumn('table_123', {
  name: 'supplier_email',
  type: 'email',
  description: 'Supplier contact email',
  unique: true
});

`updateColumn(tableId, columnName, updates)`

Mettez à jour les propriétés de colonne.

async updateColumn(
  tableId: string,
  columnName: string,
  updates: Partial<SmartTableColumn>
): Promise<void>

Exemple:

await smartTablesSDK.updateColumn('table_123', 'product_name', {
  description: 'Updated product name field',
  notNull: true,
  unique: true
});

`deleteColumn(tableId, columnName)`

Supprimez une colonne de la table.

async deleteColumn(tableId: string, columnName: string): Promise<void>

Exemple:

await smartTablesSDK.deleteColumn('table_123', 'obsolete_column');

Opérations de données

`addRow(tableId, data)`

Ajoutez une nouvelle ligne à la table.

async addRow(tableId: string, data: Record<string, any>): Promise<any>

Exemple:

const newRow = await smartTablesSDK.addRow('table_123', {
  product_name: 'Wireless Headphones',
  price: 99.99,
  supplier_email: 'supplier@example.com',
  in_stock: true
});

console.log('New row ID:', newRow.id);

`updateRow(tableId, rowId, columnName, newValue)`

Mettez à jour une cellule spécifique dans la table.

async updateRow(
  tableId: string,
  rowId: string,
  columnName: string,
  newValue: any
): Promise<void>

Exemple:

// Mettre à jour le prix du produit
await smartTablesSDK.updateRow(
  'table_123',
  'row_456',
  'price',
  89.99
);

// Mettre à jour le statut de stock
await smartTablesSDK.updateRow(
  'table_123',
  'row_456',
  'in_stock',
  false
);

`deleteRow(tableId, rowId)`

Supprimez une ligne de la table.

async deleteRow(tableId: string, rowId: string): Promise<void>

Exemple:

await smartTablesSDK.deleteRow('table_123', 'row_456');

Requête et filtrage

`queryTable(tableId, options?)`

Interrogez les données de table avec filtrage avancé, tri et pagination.

async queryTable(
  tableId: string,
  options?: TableQueryOptions
): Promise<TableQueryResponse>

TableQueryOptions:

interface TableQueryOptions {
  filters?: TableFilter[];      // Conditions de filtre
  sort?: TableSort[];          // Configurations de tri
  pagination?: TablePagination; // Paramètres de pagination
}

Exemples:

Requête de base

const results = await smartTablesSDK.queryTable('table_123');
console.log('All data:', results.data);

Requête filtrée

const results = await smartTablesSDK.queryTable('table_123', {
  filters: [
    { column: 'price', operator: 'gte', value: 50 },
    { column: 'in_stock', operator: 'eq', value: true },
    { column: 'product_name', operator: 'contains', value: 'headphones' }
  ]
});

Requête triée avec pagination

const results = await smartTablesSDK.queryTable('table_123', {
  sort: [
    { column: 'price', direction: 'desc' },
    { column: 'product_name', direction: 'asc' }
  ],
  pagination: {
    page: 2,
    limit: 20,
    search: 'wireless'
  }
});

console.log(\`Found \${results.total} items\`);
console.log(\`Page \${results.page} of \${Math.ceil(results.total / results.limit)}\`);

Importation/exportation de données

`importTable(title, description, columnMappings, file)`

Importez des données à partir de fichiers CSV ou Excel.

async importTable(
  title: string,
  description: string,
  columnMappings: ColumnMapping[],
  file: File
): Promise<ImportResult>

Interface ColumnMapping:

interface ColumnMapping {
  sourceColumn: string;     // Nom de colonne dans le fichier source
  targetColumn: string;     // Nom de colonne dans la table cible
  dataType: string;         // Type de données cible
}

Exemple:

const fileInput = document.getElementById('csvFile') as HTMLInputElement;
const file = fileInput.files[0];

const columnMappings: ColumnMapping[] = [
  { sourceColumn: 'Name', targetColumn: 'product_name', dataType: 'text' },
  { sourceColumn: 'Price', targetColumn: 'price', dataType: 'number' },
  { sourceColumn: 'Email', targetColumn: 'supplier_email', dataType: 'email' }
];

const result = await smartTablesSDK.importTable(
  'Imported Products',
  'Products imported from CSV',
  columnMappings,
  file
);

console.log(\`Imported \${result.rows_imported} rows\`);
console.log(\`Table ID: \${result.data_type_id}\`);

Fonctionnalités alimentées par l'IA

`computeRowColumns(dataTypeId, rowId, columnNames?)`

Déclenchez le calcul par IA pour des colonnes de ligne spécifiques.

async computeRowColumns(
  dataTypeId: string,
  rowId: string,
  columnNames?: string[]
): Promise<void>

Exemple:

// Calculer des colonnes spécifiques pour une ligne
await smartTablesSDK.computeRowColumns(
  'table_123',
  'row_456',
  ['ai_summary', 'sentiment_score']
);

`computeAllRows(dataTypeId)`

Déclenchez le calcul par IA pour toutes les lignes de la table.

async computeAllRows(dataTypeId: string): Promise<{
  message: string;
  total_rows_processed: number;
  total_columns_updated: number;
  updated_columns: string[];
  failed_rows: number[];
  stopped_due_to_failures: boolean;
  retry_attempts: Record<number, number>;
  computation_id?: string;
  history_table?: string;
}>

Exemple:

const result = await smartTablesSDK.computeAllRows('table_123');
console.log(\`Processed \${result.total_rows_processed} rows\`);
console.log(\`Updated \${result.total_columns_updated} columns\`);
console.log(\`Updated columns: \${result.updated_columns.join(', ')}\`);

if (result.failed_rows.length > 0) {
  console.log(\`Failed rows: \${result.failed_rows.join(', ')}\`);
}

Gestion des erreurs

SmartTablesSDK utilise la même gestion des erreurs que les autres composants SDK:

try {
  const table = await smartTablesSDK.createTable('My Table', 'Description');
} catch (error) {
  if (error instanceof APIError) {
    console.error(\`API Error \${error.status}: \${error.message}\`);
    if (error.detail) {
      console.error('Details:', error.detail);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Exemples

Application complète de gestion de données

Dans cet exemple, vous apprendrez comment construire un système complet de gestion de produits en utilisant SmartTablesSDK avec une classe bien structurée qui gère l'inventaire et les informations de produits. La classe `ProductManager` initialise le SDK avec les variables d'environnement et fournit un flux de travail complet pour gérer un catalogue de produits : la méthode `initializeTable()` crée une nouvelle table « Catalogue de produits » et configure un schéma complet avec huit colonnes incluant différents types de données (texte, nombre, booléen, e-mail, url et date), ainsi que des contraintes comme `notNull` pour les champs obligatoires et `defaultValue` pour la disponibilité des stocks. Une fois initialisée, vous pouvez ajouter des produits en utilisant `addProduct()`, qui insère de nouvelles lignes et horodate automatiquement chaque entrée avec la date actuelle, et effectuer des recherches sophistiquées avec `searchProducts()`, qui vous permet de filtrer les produits par catégorie, plage de prix (en utilisant les opérateurs « gte » et « lte » pour les comparaisons supérieur-ou-égal et inférieur-ou-égal), appliquer une recherche textuelle sur la table et trier les résultats alphabétiquement par nom de produit. Cela vous donne un modèle prêt pour la production pour construire des systèmes d'inventaire e-commerce, des bases de données de produits ou toute application nécessitant une gestion de données structurée avec des capacités de requête avancées—démontrant comment combiner plusieurs conditions de filtre, pagination, tri et fonctionnalité de recherche dans une solution cohésive de gestion de données.

import { SmartTablesSDK } from '@odin-ai-staging/sdk';

class ProductManager {
  private sdk: SmartTablesSDK;
  private tableId?: string;

  constructor() {
    this.sdk = new SmartTablesSDK({
      baseUrl: process.env.API_BASE_URL,
      projectId: process.env.PROJECT_ID,
      apiKey: process.env.API_KEY,
      apiSecret: process.env.API_SECRET
    });
  }

  async initializeTable() {
    try {
      // Créer la table
      const table = await this.sdk.createTable(
        'Product Catalog',
        'Manage product inventory and information'
      );
      this.tableId = table.id;

      // Ajouter des colonnes
      await this.addColumns();
      
      console.log('Table initialized:', this.tableId);
      return table;
    } catch (error) {
      console.error('Failed to initialize table:', error);
      throw error;
    }
  }

  private async addColumns() {
    const columns = [
      { name: 'name', type: 'text', description: 'Product name', notNull: true },
      { name: 'description', type: 'text', description: 'Product description' },
      { name: 'price', type: 'number', description: 'Price in USD', notNull: true },
      { name: 'category', type: 'text', description: 'Product category' },
      { name: 'in_stock', type: 'boolean', description: 'Stock availability', defaultValue: true },
      { name: 'supplier_email', type: 'email', description: 'Supplier contact' },
      { name: 'website', type: 'url', description: 'Product website' },
      { name: 'created_at', type: 'date', description: 'Creation date' }
    ];

    for (const column of columns) {
      await this.sdk.addColumn(this.tableId!, column);
    }
  }

  async addProduct(productData: any) {
    if (!this.tableId) throw new Error('Table not initialized');
    
    try {
      const result = await this.sdk.addRow(this.tableId, {
        ...productData,
        created_at: new Date().toISOString()
      });
      
      console.log('Product added:', result);
      return result;
    } catch (error) {
      console.error('Failed to add product:', error);
      throw error;
    }
  }

  async searchProducts(searchTerm: string, category?: string, minPrice?: number, maxPrice?: number) {
    if (!this.tableId) throw new Error('Table not initialized');

    const filters = [];
    
    if (category) {
      filters.push({ column: 'category', operator: 'eq', value: category });
    }
    
    if (minPrice !== undefined) {
      filters.push({ column: 'price', operator: 'gte', value: minPrice });
    }
    
    if (maxPrice !== undefined) {
      filters.push({ column: 'price', operator: 'lte', value: maxPrice });
    }

    try {
      const results = await this.sdk.queryTable(this.tableId, {
        filters,
        pagination: {
          search: searchTerm,
          limit: 50
        },
        sort: [
          { column: 'name', direction: 'asc' }
        ]
      });

      return results;
    } catch (error) {
      console.error('Search failed:', error);
      throw error;
    }
  }
}

// Usage
const productManager = new ProductManager();
await productManager.initializeTable();
await productManager.addProduct({
  name: 'Wireless Headphones',
  price: 199.99,
  category: 'Electronics'
});

Meilleures pratiques

Requête efficace

• Utilisez la pagination pour les grands ensembles de données
• Appliquez des filtres pour réduire le transfert de données
• Combinez plusieurs opérations lorsque c'est possible

// Bon : Requête efficace avec filtres et pagination
const results = await smartTablesSDK.queryTable(tableId, {
  filters: [{ column: 'status', operator: 'eq', value: 'active' }],
  pagination: { limit: 50, page: 1 },
  sort: [{ column: 'created_at', direction: 'desc' }]
});

// Mauvais : Récupérer toutes les données sans filtres
const allResults = await smartTablesSDK.queryTable(tableId);

Conception du schéma

• Définissez les types de colonnes appropriés
• Utilisez les contraintes (notNull, unique) de manière appropriée
• Fournissez des descriptions significatives

// Bon : Schéma de colonne bien défini
await smartTablesSDK.addColumn(tableId, {
  name: 'email',
  type: 'email',
  description: 'Customer email address',
  notNull: true,
  unique: true
});

// Mauvais : Définition de colonne vague
await smartTablesSDK.addColumn(tableId, {
  name: 'data',
  type: 'text'
});

Gestion des erreurs et validation

• Gérez toujours les erreurs gracieusement
• Validez les données avant les opérations
• Utilisez les transactions pour les opérations liées

async function safeTableOperation(tableId: string, data: any) {
  try {
    // Valider les données d'abord
    if (!data.email || !data.email.includes('@')) {
      throw new Error('Invalid email format');
    }
    
    // Effectuer l'opération
    const result = await smartTablesSDK.addRow(tableId, data);
    return result;
  } catch (error) {
    console.error('Operation failed:', error);
    // Traiter les types d'erreurs spécifiques
    if (error.message.includes('unique constraint')) {
      throw new Error('Email already exists');
    }
    throw error;
  }
}