Tables

Tables are the core building blocks of your Boltic database. They define the structure of your data through schemas that specify columns, data types, and constraints. The Boltic Tables SDK provides comprehensive table management capabilities through the client.tables interface.

import { createClient } from "@boltic/sdk";

const client = createClient("your-api-key");

// All table operations
const operations = client.tables;

What are Tables?

In Boltic Tables, a table is a structured collection of data organized in rows and columns. Each table has:

• Schema Definition: Column specifications with data types and constraints
• Metadata: Name, description, creation date, and access permissions
• Access Control: Public/private visibility settings
• Records: The actual data stored in the table

Key Concepts

Table Schema

A table schema defines the structure of your data through columns. Each column specifies:

• Name: The column identifier
• Type: The data type (text, number, currency, etc.)
• Constraints: Whether the field is nullable, unique, or indexed
• Properties: Type-specific configurations like date formats or currency codes

For detailed information about field types and their properties, see the Columns Documentation.

Table Access Control

Tables can be shared with other users in the account by setting the is_shared flag to true`. This allows other users to read and write data to the table.

Table Operations

The SDK provides comprehensive table management through these operations:

• Create: Define new tables with custom schemas
• Read: List, find, and retrieve table information
• Update: Modify table properties and metadata
• Delete: Remove tables and all associated data
• Rename: Change table names while preserving data
• Access Control: Manage table visibility and sharing

Method Overview

Method	Description	Parameters
create()	Create a new table with schema	TableCreateRequest
findAll()	List tables with filtering	TableQueryOptions?
findById()	Get table by ID	string
findByName()	Get table by name	string
findOne()	Get table with custom query	TableQueryOptions
update()	Update table properties	string, TableUpdateRequest
delete()	Delete table and all data	string
rename()	Rename a table	string, string
setAccess()	Control table visibility	TableAccessRequest

Type Definitions

Core Types

interface TableRecord {
    id: string; // Unique table identifier
    name: string; // Table name
    account_id: string; // Account identifier
    internal_db_name: string; // Database name
    db_id?: string; // Database UUID
    resource_id?: string; // Resource identifier
    description?: string; // Table description
    type?: string; // Table type
    parent_table_id?: string; // Parent table reference
    is_deleted: boolean; // Soft-delete status
    is_public: boolean; // Public visibility
    created_by: string; // Creator identifier
    created_at: string; // Creation timestamp
    updated_at: string; // Last update timestamp
    updated_by: string; // Last updater identifier
    account_status: "active" | "inactive" | "deleted"; // Account status
    source?: "boltic" | "copilot"; // Creation source
}

interface ApiResponse<T> {
    data?: T;
    error?: {
        code: string;
        message: string;
        meta?: string[];
    };
}

Request Types

interface TableCreateRequest {
    name: string; // Table name
    fields: FieldDefinition[]; // Schema definition
    description?: string; // Optional description
}

interface TableUpdateRequest {
    name?: string; // New name
    description?: string; // Updated description
    is_shared?: boolean; // Public visibility
}

interface TableQueryOptions {
    where?: Record<string, unknown>; // Filter conditions
    fields?: string[]; // Field selection
    sort?: SortOption[]; // Sort order
    limit?: number; // Result limit
    offset?: number; // Pagination offset
}

interface TableAccessRequest {
    table_name: string; // Table to modify
    is_shared: boolean; // Public visibility
}

interface SortOption {
    field: string; // Field to sort by
    direction: "asc" | "desc"; // Sort direction
}

For column schema information, see the Columns Documentation.

Table Lifecycle

1. Creation

// Create a new table with schema
const { data: table, error } = await client.tables.create({
    name: "products",
    fields: [
        { name: "title", type: "text", is_nullable: false },
        { name: "price", type: "currency", currency_format: "USD" },
    ],
    description: "Product catalog",
});

2. Management

// List all tables
const { data: tables } = await client.tables.findAll();

// Get specific table
const { data: table } = await client.tables.findByName("products");

// Update table properties
const { data: updated } = await client.tables.update("products", {
    description: "Updated product catalog",
});

3. Data Operations

Once a table is created, you can perform data operations using the records API:

// Insert data
const { data: record } = await client.records.insert("products", {
    title: "MacBook Pro",
    price: 2499.99,
});

// Query data
const { data: products } = await client.records.findAll("products", {
    where: { price: { $gt: 1000 } },
});

Table Constraints and Validation

Schema Validation

• Column names must be unique within a table
• Required columns must be specified during record creation
• Data types are strictly enforced on insert/update operations

Naming Conventions

• Table names must be unique within your account
• Names should use lowercase letters, numbers, and underscores
• Reserved keywords are not allowed as table names

Size Limits

• Maximum table name length: 50 characters
• Maximum description length: 255 characters
• Maximum records per table: Subject to plan

Performance Considerations

Query Optimization

• Use specific field selections to reduce data transfer
• Implement pagination for large result sets
• Leverage filtering at the database level

Best Practices

Schema Design

1. Use descriptive names for tables and fields
2. Define constraints appropriate for your data

Error Handling

1. Always check for errors before using response data
2. Implement retries for transient failures
3. Log errors for debugging and monitoring

Security

1. Use private tables for sensitive data
2. Implement proper access controls before sharing
3. Validate input data before table operations