SmartTablesSDK Documentation

The SmartTablesSDK provides a comprehensive solution for managing structured data tables with advanced querying, filtering, sorting, and data manipulation capabilities. Build powerful data management applications with ease, featuring support for custom views, data import/export, and AI-powered data processing.

Installation
Quick Start
Configuration
Core Concepts
Table Management
Column Operations
Data Operations
Querying & Filtering
Views & Customization
Data Import/Export
AI-Powered Features
Error Handling
Examples
Best Practices

Installation

npm install @odin-ai-staging/sdk

Quick Start

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

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

// Quick example: Create table and add data
async function quickExample() {
  // Create a new table
  const table = await smartTablesSDK.createTable(
    'Customer Database',
    'Manage customer information'
  );
  
  // Add columns
  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'
  });
  
  // Add data
  await smartTablesSDK.addRow(table.id, {
    name: 'John Doe',
    email: 'john@example.com'
  });
  
  // Query data
  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

SmartTablesSDKConfig Interface

interface SmartTablesSDKConfig {
  baseUrl: string;          // API endpoint URL
  projectId: string;        // Your project identifier
  apiKey?: string;          // API key for authentication
  apiSecret?: string;       // API secret for authentication
  accessToken?: string;     // Access token for web app usage
}

The SmartTablesSDK uses the same configuration as other SDK components, extending the BaseClientConfig.

Core Concepts

SmartTable

A SmartTable represents a structured data table with schema, metadata, and data management capabilities.

interface SmartTable {
  id: string;                    // Unique table identifier
  project_id: string;            // Project this table belongs to
  title: string;                 // Display name of the table
  description: string;           // Table description
  schema: SmartTableColumn[];    // Column definitions
  table_name: string;           // Internal table name
  created_at?: number;          // Creation timestamp
  updated_at?: number;          // Last update timestamp
}

SmartTableColumn

Defines the structure and properties of table columns.

interface SmartTableColumn {
  name: string;                           // Column name
  type: ColumnType;                       // Data type
  description?: string;                   // Column description
  notNull?: boolean;                      // Required field
  unique?: boolean;                       // Unique constraint
  defaultValue?: string | number | boolean | null;  // Default value
  options?: Record<string, unknown>;      // Additional options
}

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

Filtering & Querying

Advanced filtering system with multiple operators and sorting options.

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;
}

Table Management

`getAllTables()`

Retrieve all tables in the project.

async getAllTables(): Promise<SmartTable[]>

Example:

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

`getTable(tableId)`

Get a specific table by ID.

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

Example:

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

`createTable(title, description, metadata?)`

Create a new table.

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

Example:

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

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

Update table metadata.

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

Example:

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

`deleteTable(tableId)`

Delete a table and all its data permanently.

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

Example:

await smartTablesSDK.deleteTable('table_123');

Column Operations

`addColumn(tableId, column)`

Add a new column to the table.

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

Example:

// Add a text column
await smartTablesSDK.addColumn('table_123', {
  name: 'product_name',
  type: 'text',
  description: 'Name of the product',
  notNull: true
});

// Add a number column with default value
await smartTablesSDK.addColumn('table_123', {
  name: 'price',
  type: 'number',
  description: 'Product price in USD',
  defaultValue: 0,
  notNull: true
});

// Add an email column with validation
await smartTablesSDK.addColumn('table_123', {
  name: 'supplier_email',
  type: 'email',
  description: 'Supplier contact email',
  unique: true
});

`updateColumn(tableId, columnName, updates)`

Update column properties.

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

Example:

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

`deleteColumn(tableId, columnName)`

Remove a column from the table.

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

Example:

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

Data Operations

`addRow(tableId, data)`

Add a new row to the table.

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

Example:

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)`

Update a specific cell in the table.

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

Example:

// Update product price
await smartTablesSDK.updateRow(
  'table_123',
  'row_456',
  'price',
  89.99
);

// Update stock status
await smartTablesSDK.updateRow(
  'table_123',
  'row_456',
  'in_stock',
  false
);

`deleteRow(tableId, rowId)`

Delete a row from the table.

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

Example:

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

Querying & Filtering

`queryTable(tableId, options?)`

Query table data with advanced filtering, sorting, and pagination.

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

TableQueryOptions:

interface TableQueryOptions {
  filters?: TableFilter[];      // Filter conditions
  sort?: TableSort[];          // Sort configurations
  pagination?: TablePagination; // Pagination settings
}

Examples:

Basic Query

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

Filtered Query

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' }
  ]
});

Sorted Query with 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)}`);

Data Import/Export

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

Import data from CSV or Excel files.

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

ColumnMapping Interface:

interface ColumnMapping {
  sourceColumn: string;     // Column name in source file
  targetColumn: string;     // Column name in target table
  dataType: string;         // Target data type
}

Example:

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}`);

AI-Powered Features

`computeRowColumns(dataTypeId, rowId, columnNames?)`

Trigger AI computation for specific row columns.

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

Example:

// Compute specific columns for a row
await smartTablesSDK.computeRowColumns(
  'table_123',
  'row_456',
  ['ai_summary', 'sentiment_score']
);

`computeAllRows(dataTypeId)`

Trigger AI computation for all rows in the 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;
}>

Example:

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(', ')}`);
}

Error Handling

The SmartTablesSDK uses the same error handling as other SDK components:

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);
  }
}

Examples

Complete Data Management Application

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 {
      // Create table
      const table = await this.sdk.createTable(
        'Product Catalog',
        'Manage product inventory and information'
      );
      this.tableId = table.id;

      // Add columns
      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'
});

Best Practices

1. Efficient Querying

Use pagination for large datasets
Apply filters to reduce data transfer
Combine multiple operations when possible

// Good: Efficient query with filters and 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' }]
});

// Bad: Fetching all data without filters
const allResults = await smartTablesSDK.queryTable(tableId);

2. Schema Design

Define appropriate column types
Use constraints (notNull, unique) appropriately
Provide meaningful descriptions

// Good: Well-defined column schema
await smartTablesSDK.addColumn(tableId, {
  name: 'email',
  type: 'email',
  description: 'Customer email address',
  notNull: true,
  unique: true
});

// Bad: Vague column definition
await smartTablesSDK.addColumn(tableId, {
  name: 'data',
  type: 'text'
});

3. Error Handling and Validation

Always handle errors gracefully
Validate data before operations
Use transactions for related operations

async function safeTableOperation(tableId: string, data: any) {
  try {
    // Validate data first
    if (!data.email || !data.email.includes('@')) {
      throw new Error('Invalid email format');
    }
    
    // Perform operation
    const result = await smartTablesSDK.addRow(tableId, data);
    return result;
  } catch (error) {
    console.error('Operation failed:', error);
    // Handle specific error types
    if (error.message.includes('unique constraint')) {
      throw new Error('Email already exists');
    }
    throw error;
  }
}

For more information about other SDK components, see:

Get Started!

SDK

Chat

Interfaces

Agents

Workflows

Project Settings

Knowledge Base

Platform Admin

My Account

Public Chatbot

General Information

​SmartTablesSDK Documentation

​Table of Contents

​Installation

​Quick Start

​Configuration

​SmartTablesSDKConfig Interface

​Core Concepts

​SmartTable

​SmartTableColumn

​Filtering & Querying

​Table Management

​getAllTables()

​getTable(tableId)

​createTable(title, description, metadata?)

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

​deleteTable(tableId)

​Column Operations

​addColumn(tableId, column)

​updateColumn(tableId, columnName, updates)

​deleteColumn(tableId, columnName)

​Data Operations

​addRow(tableId, data)

​updateRow(tableId, rowId, columnName, newValue)

​deleteRow(tableId, rowId)

​Querying & Filtering

​queryTable(tableId, options?)

​Basic Query

​Filtered Query

​Sorted Query with Pagination

​Data Import/Export

​importTable(title, description, columnMappings, file)

​AI-Powered Features

​computeRowColumns(dataTypeId, rowId, columnNames?)

​computeAllRows(dataTypeId)

​Error Handling

​Examples

​Complete Data Management Application

​Best Practices

​1. Efficient Querying

​2. Schema Design

​3. Error Handling and Validation

SmartTablesSDK Documentation

Table of Contents

Installation

Quick Start

Configuration

SmartTablesSDKConfig Interface

Core Concepts

SmartTable

SmartTableColumn

Filtering & Querying

Table Management

`getAllTables()`

`getTable(tableId)`

`createTable(title, description, metadata?)`

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

`deleteTable(tableId)`

Column Operations

`addColumn(tableId, column)`

`updateColumn(tableId, columnName, updates)`

`deleteColumn(tableId, columnName)`

Data Operations

`addRow(tableId, data)`

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

`deleteRow(tableId, rowId)`

Querying & Filtering

`queryTable(tableId, options?)`

Basic Query

Filtered Query

Sorted Query with Pagination

Data Import/Export

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

AI-Powered Features

`computeRowColumns(dataTypeId, rowId, columnNames?)`

`computeAllRows(dataTypeId)`

Error Handling

Examples

Complete Data Management Application

Best Practices

1. Efficient Querying

2. Schema Design

3. Error Handling and Validation