Insert Record

Insert new records into your Boltic Tables with full type safety and validation. The SDK provides multiple approaches for creating records with support for all field types.

Insert Operations

The SDK provides two approaches for inserting records:

Single Record Insert

client.records.insert(tableName: string, data: RecordData): Promise<ApiResponse<RecordWithId>>

Parameters

Parameter	Type	Required	Description
tableName	string	✅	Name or ID of the target table
data	RecordData	✅	Record data matching table schema

Bulk Record Insert

client.records.insertMany(
  tableName: string,
  records: RecordData[],
  options?: { validation?: boolean }
): Promise<ApiResponse<RecordBulkInsertResponse>>

Parameters

Parameter	Type	Required	Description
tableName	string	✅	Name or ID of the target table
records	RecordData[]	✅	Array of record data matching table schema
options	{ validation?: boolean }	❌	Validation options (default: { validation: true })

Bulk Insert Response

interface RecordBulkInsertResponse {
    data: {
        records: RecordWithId[]; // Array of inserted records with IDs
        insert_count: number; // Number of successfully inserted records
    };
    message: string; // Success message
}

RecordData Interface

interface RecordData {
    [fieldName: string]: unknown;
}

The record data should match your table's column definitions and their respective field types.

Examples

Direct Approach

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

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

// Simple user record
const userData = {
    name: "John Doe",
    email: "[email protected]",
    age: 30,
    is_active: true,
};

const { data: record, error } = await client.records.insert("users", userData);

if (error) {
    console.error("Insert failed:", error.message);
} else {
    console.log("Record created:", record.id);
    console.log("Created at:", record.created_at);
}

Bulk Insert

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

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

const usersData = [
    { name: "Jane Smith", email: "[email protected]", age: 28, is_active: true },
    { name: "Bob Johnson", email: "[email protected]", age: 35, is_active: true },
];

const { data: bulkResult, error } = await client.records.insertMany("users", usersData);

if (error) {
    console.error("Bulk insert failed:", error.message);
} else {
    console.log(`Successfully inserted ${bulkResult.insert_count} records`);
    console.log("Inserted records:", bulkResult.records);
}

Validation Option

await client.records.insertMany("users", usersData, { validation: false }); // Faster, less safe
// Default: { validation: true }

Bulk Insert Requirements

• Bulk inserts require complete records. Partial records are not supported.
• Include all required columns for each record according to the table schema.

const completeRecords = [
    { name: "User 1", email: "[email protected]", age: 25, is_active: true },
    { name: "User 2", email: "[email protected]", age: 30, is_active: true },
];

await client.records.insertMany("users", completeRecords);

Insert with All Field Types

const comprehensiveRecord = {
    // Text fields
    text_field: "John Doe",
    email_field: "[email protected]",
    long_text_field: "This is a comprehensive description with detailed information.",

    // Number fields
    number_field: 30,
    currency_field: 75000.5,

    // Boolean field
    checkbox_field: true,

    // Selection field
    dropdown_field: ["Option 1"], // Single selection
    // dropdown_field: ['Option 1', 'Option 2'],  // Multiple selections

    // Contact fields
    phone_field: "+91 987 654 3210",
    link_field: "https://johndoe.com",

    // Date field
    date_time_field: "2024-01-15T10:30:00Z",

    // Structured data
    json_field: {
        preferences: { theme: "dark", language: "en" },
        metadata: { source: "api", version: "1.0" },
    },

    // Vector fields for AI/ML
    vector_field: [0.1, 0.2, 0.3, 0.4, 0.5],
    half_vector_field: [0.1, 0.2, 0.3, 0.4, 0.5],
    sparse_vector_field: "{1:1,3:2,5:3}/5",
};

const { data: record, error } = await client.records.insert(
    "comprehensive-table",
    comprehensiveRecord,
);

Partial Insert (Single Records Only)

The SDK supports partial record insertion for single insert() operations, which means you only need to provide the fields you have data for. Missing fields will be automatically set to null.

// Only provide the fields you have data for
const minimalUser = {
    name: "Quick User",
    email: "[email protected]",
    // All other table fields will be automatically set to null
};

const { data: user, error } = await client.records.insert("users", minimalUser);

if (error) {
    console.error("Insert failed:", error.message);
} else {
    console.log("User created with ID:", user.id);
    // Other fields like phone, description, etc. will be null
}

Insert with Nullable Fields

// Record with nullable fields set to null (all fields must be included)
const completeRecord = {
    name: "Jane Smith",
    email: "[email protected]",

    // Required fields must have values
    status: "active",

    // Nullable fields must be explicitly set (cannot be omitted)
    description: null, // Must include, can be null
    phone: null, // Must include, can be null
    metadata: null, // Must include, can be null
    created_date: "2024-01-15T10:30:00Z", // Must include
    is_verified: false, // Must include
};

const { data: record } = await client.records.insert("users", completeRecord);

What this means:

• ✅ You can set nullable fields to null
• ❌ You cannot omit fields from the insert payload
• ✅ All table columns must be represented in your data object

Column Type Examples

Text and Email Columns

const textRecord = {
    // Basic text
    title: "Software Engineer",

    // Email with validation
    email: "[email protected]",

    // Long text for descriptions
    bio: `Experienced full-stack developer with expertise in TypeScript, 
        React, and Node.js. Passionate about building scalable applications 
        and mentoring junior developers.`,
};

Numeric Columns

const numericRecord = {
    // Integer number
    age: 28,

    // Decimal number
    score: 95.7,

    // Currency with decimal precision
    salary: 85000.5,
    annual_budget: 1250000.0,
};

Date and Time Fields

const dateRecord = {
    // ISO 8601 timestamp
    start_date: "2024-01-15T10:30:00Z",

    // Date only
    birth_date: "1990-05-20",

    // Time only
    event_time: "14:30:00",
};

Selection Fields

const selectionRecord = {
    // Single selection dropdown
    priority: ["High"],

    // Multiple selection dropdown
    skills: ["JavaScript", "TypeScript", "React", "Node.js"],

    // Single option (alternative format)
    status: "Active",
};

Structured Data

const structuredRecord = {
    // Complex JSON data
    preferences: {
        notifications: {
            email: true,
            sms: false,
            push: true,
        },
        display: {
            theme: "dark",
            language: "en-US",
            timezone: "America/New_York",
        },
    },

    // Array of objects
    addresses: [
        {
            type: "home",
            street: "123 Main St",
            city: "New York",
            zip: "10001",
        },
        {
            type: "work",
            street: "456 Business Ave",
            city: "New York",
            zip: "10002",
        },
    ],
};

Vector Fields for AI/ML

const vectorRecord = {
    // Full precision vector
    content_embedding: [
        0.1234, 0.5678, 0.9012, 0.3456, 0.789, 0.2345, 0.6789, 0.0123, 0.4567, 0.8901,
    ],

    // Half precision vector (same format)
    title_embedding: [0.123, 0.456, 0.789, 0.012, 0.345],

    // Sparse vector (index:value pairs)
    sparse_features: "{1:0.8,5:0.6,10:0.9,15:0.4}/20",
};

Validation and Constraints

Required Columns

Single Record Insert

// This will fail if ANY columns are missing (not just required ones)
const incompleteRecord = {
    name: "John Doe",
    // Missing ALL other table columns - this will fail
};

const { error } = await client.records.insert("users", incompleteRecord);
if (error) {
    console.error("Validation error:", error.message);
    // Error: Value for email_field, status_field, created_date are missing
}

// Correct approach - include ALL table columns
const completeRecord = {
    name: "John Doe",
    email: "[email protected]", // Required field
    status: "active", // Required field
    description: null, // Nullable field (set to null)
    phone: null, // Nullable field (set to null)
    created_date: "2024-01-15T10:30:00Z", // Must include
    is_verified: false, // Must include
};

const { data: record } = await client.records.insert("users", completeRecord);

Unique Constraints

// This will fail if unique constraint is violated
const duplicateRecord = {
    email: "[email protected]", // Already exists in table
    name: "Duplicate User",
};

const { error } = await client.records.insert("users", duplicateRecord);
if (error) {
    console.error("Unique constraint violation:", error.message);
}

Type Validation

// This will fail due to type mismatch
const invalidRecord = {
    name: "John Doe",
    email: "[email protected]",
    age: "thirty", // Should be number, not string
    is_active: "yes", // Should be boolean, not string
};

const { error } = await client.records.insert("users", invalidRecord);
if (error) {
    console.error("Type validation error:", error.message);
}

Return Value

Successful Response

interface BolticSuccessResponse<RecordWithId> {
    data: {
        id: string; // Generated unique ID
        created_at: string; // ISO 8601 timestamp
        updated_at: string; // ISO 8601 timestamp
        [fieldName: string]: unknown; // Your record data
    };
    error: null;
}

Error Response

interface BolticErrorResponse {
    data: null;
    error: {
        message: string; // Human-readable error message
        details?: unknown; // Additional error details
    };
}