Skip to main content

Create Table

Create new tables with custom schemas and field definitions using the client.tables.create() method. This operation sets up the structure for your data and defines how information will be stored and validated.

Method Signature​

client.tables.create(data: TableCreateRequest): Promise<ApiResponse<TableCreateResponse>>

System-Generated Columns​

When you create a table, Boltic automatically adds the following system columns that you don't need to define:

ColumnTypeDescription
idtextUnique record identifier (primary key)
created_atdate-timeTimestamp when the record was created
updated_atdate-timeTimestamp when the record was last updated

These columns are managed automatically and cannot be modified or deleted.

Parameters​

TableCreateRequest​

ParameterTypeRequiredDescription
namestring✅Unique table name (must be unique within your account)
fieldsFieldDefinition[]✅Array of field definitions that define the table schema
descriptionstring❌Optional description for the table

FieldDefinition Structure​

For detailed information about field definitions, data types, and field-specific properties, see the Columns Documentation.

Basic field structure:

interface FieldDefinition {
    name: string; // Field name
    type: FieldType; // Data type (text, number, currency, etc.)
    is_nullable?: boolean; // Whether field can be null
    is_unique?: boolean; // Whether field values must be unique
    is_indexed?: boolean; // Whether to create database index
    description?: string; // Field description
    // ... additional type-specific properties
}

Return Value​

TableCreateResponse​

interface TableCreateResponse {
    id: string; // Unique table identifier
    message: string; // Success message
}

Examples​

Basic Table Creation​

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

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

const { data: table, error } = await client.tables.create({
    name: "users",
    fields: [
        {
            name: "email",
            type: "email",
            is_nullable: false,
            is_unique: true,
        },
        {
            name: "first_name",
            type: "text",
            is_nullable: false,
        },
        {
            name: "last_name",
            type: "text",
            is_nullable: false,
        },
    ],
    description: "User account information",
});

if (error) {
    console.error("Failed to create table:", error.message);
} else {
    console.log("Table created successfully:", table.id);
}

Advanced Table with Constraints​

const { data: ordersTable, error } = await client.tables.create({
    name: "orders",
    fields: [
        {
            name: "order_id",
            type: "text",
            is_nullable: false,
            is_unique: true,
            is_indexed: true,
            description: "Unique order identifier",
        },
        {
            name: "customer_email",
            type: "email",
            is_nullable: false,
            is_indexed: true,
        },
        {
            name: "total_amount",
            type: "currency",
            is_nullable: false,
            currency_format: "USD",
        },
        {
            name: "status",
            type: "dropdown",
            is_nullable: false,
            selectable_items: ["pending", "processing", "shipped", "delivered", "cancelled"],
            default_value: "pending",
        },
        {
            name: "order_details",
            type: "json",
            is_nullable: true,
            description: "Structured order data",
        },
        {
            name: "shipping_address",
            type: "json",
            is_nullable: false,
            description: "Customer shipping address",
        },
    ],
    description: "Order management system",
});

Error Handling​

Common Error Scenarios​

const { data, error } = await client.tables.create(tableData);

if (error) {
    // Common error messages:
    // - "Table name is required"
    // - "Table name cannot be longer than 50 characters"
    // - "Table description cannot be longer than 255 characters"
    // - "Table already exists"
    // - "Column validation errors"

    console.log("Error creating table:", error.meta);
}

Best Practices​

Schema Design​

  1. Plan Your Schema: Think about your data requirements upfront

    // Good: Well-planned schema
    const fields = [
        { name: "id", type: "text", is_unique: true, is_indexed: true },
        { name: "email", type: "email", is_unique: true },
        { name: "created_at", type: "date-time", is_nullable: false },
    ];

  2. Use Appropriate Data Types: Choose the most specific type for your data

    // Good: Specific types
    { name: 'price', type: 'currency', currency_format: 'USD' }
    { name: 'email', type: 'email' }
    { name: 'active', type: 'checkbox' }

    // Avoid: Generic types when specific ones exist
    { name: 'price', type: 'text' }  // Use 'currency' instead

  3. Set Constraints Appropriately: Use nullable, unique, and indexed wisely

    // Primary identifiers should be unique and indexed
    { name: 'user_id', type: 'text', is_unique: true, is_indexed: true }

    // Frequently queried fields should be indexed
    { name: 'email', type: 'email', is_indexed: true }

    // Optional fields should be nullable
    { name: 'middle_name', type: 'text', is_nullable: true }

After creating a table, you can: