> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Smart Tables

> Créez et gérez des tables de données structurées avec des requêtes avancées, des filtres et un traitement de données alimenté par l'IA.

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

```bash theme={null}
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.

```typescript theme={null}
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

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
async getAllTables(): Promise<SmartTable[]>
```

**Exemple:**

```typescript theme={null}
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.

```typescript theme={null}
async getTable(tableId: string): Promise<SmartTable>
```

**Exemple:**

```typescript theme={null}
const table = await smartTablesSDK.getTable('table_123');
console.log('Table schema:', table.schema);
```

### \`createTable(title, description, metadata?)\`

Créez une nouvelle table.

```typescript theme={null}
async createTable(
  title: string,
  description: string,
  metadata?: Record<string, unknown>
): Promise<SmartTable>
```

**Exemple:**

```typescript theme={null}
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.

```typescript theme={null}
async updateTable(
  tableId: string,
  title: string,
  description?: string,
  metadata?: Record<string, unknown>
): Promise<void>
```

**Exemple:**

```typescript theme={null}
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.

```typescript theme={null}
async deleteTable(tableId: string): Promise<void>
```

**Exemple:**

```typescript theme={null}
await smartTablesSDK.deleteTable('table_123');
```

## Opérations de colonnes

### \`addColumn(tableId, column)\`

Ajoutez une nouvelle colonne à la table.

```typescript theme={null}
async addColumn(tableId: string, column: SmartTableColumn): Promise<void>
```

**Exemple:**

```typescript theme={null}
// 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.

```typescript theme={null}
async updateColumn(
  tableId: string,
  columnName: string,
  updates: Partial<SmartTableColumn>
): Promise<void>
```

**Exemple:**

```typescript theme={null}
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.

```typescript theme={null}
async deleteColumn(tableId: string, columnName: string): Promise<void>
```

**Exemple:**

```typescript theme={null}
await smartTablesSDK.deleteColumn('table_123', 'obsolete_column');
```

## Opérations de données

### \`addRow(tableId, data)\`

Ajoutez une nouvelle ligne à la table.

```typescript theme={null}
async addRow(tableId: string, data: Record<string, any>): Promise<any>
```

**Exemple:**

```typescript theme={null}
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.

```typescript theme={null}
async updateRow(
  tableId: string,
  rowId: string,
  columnName: string,
  newValue: any
): Promise<void>
```

**Exemple:**

```typescript theme={null}
// 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.

```typescript theme={null}
async deleteRow(tableId: string, rowId: string): Promise<void>
```

**Exemple:**

```typescript theme={null}
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.

```typescript theme={null}
async queryTable(
  tableId: string,
  options?: TableQueryOptions
): Promise<TableQueryResponse>
```

**TableQueryOptions:**

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

**Exemples:**

#### Requête de base

```typescript theme={null}
const results = await smartTablesSDK.queryTable('table_123');
console.log('All data:', results.data);
```

#### Requête filtrée

```typescript theme={null}
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

```typescript theme={null}
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.

```typescript theme={null}
async importTable(
  title: string,
  description: string,
  columnMappings: ColumnMapping[],
  file: File
): Promise<ImportResult>
```

**Interface ColumnMapping:**

```typescript theme={null}
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:**

```typescript theme={null}
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.

```typescript theme={null}
async computeRowColumns(
  dataTypeId: string,
  rowId: string,
  columnNames?: string[]
): Promise<void>
```

**Exemple:**

```typescript theme={null}
// 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.

```typescript theme={null}
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:**

```typescript theme={null}
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:

```typescript theme={null}
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.

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
// 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

```typescript theme={null}
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;
  }
}
```