Records Overview

Records are the data rows in your Boltic Tables. The SDK provides comprehensive CRUD operations for managing records with advanced filtering, querying, pagination, and sorting capabilities. For complex queries and natural language interactions, see the SQL Operations section.

Core Operations

The Boltic Tables SDK provides methods for all record management:

Record Operations

The SDK provides two main approaches for working with records:

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

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

// Create records
const { data: record } = await client.records.insert("users", userData);
const { data: bulk } = await client.records.insertMany("users", [userData1, userData2]);

// Query records
const { data: records } = await client.records.findAll("users", options);
const { data: record } = await client.records.findOne("users", recordId);
const { data: record } = await client.records.get("users", recordId);

// Update records
const { data: updated } = await client.records.update("users", updateOptions);
const { data: updated } = await client.records.updateById("users", recordId, newData);

// Delete records
const { data: result } = await client.records.delete("users", deleteOptions);
const { data: result } = await client.records.deleteById("users", recordId);

• Use insert() for single records (supports partial payloads)
• Use insertMany() for bulk creation (requires complete records; optional validation)

Record Data Structure

RecordData Interface

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

Records are flexible objects where keys correspond to column names and values match the column types:

const userData: RecordData = {
    email: "[email protected]", // text/email column
    name: "John Doe", // text column
    age: 30, // number column
    salary: 75000.5, // currency column
    is_active: true, // checkbox column
    preferences: { theme: "dark" }, // json column
    tags: ["developer", "frontend"], // dropdown column (multiple)
    profile_vector: [0.1, 0.2, 0.3], // vector column
    created_at: "2024-01-15T10:30:00Z", // date-time column
};

RecordWithId Interface

Retrieved records include system-generated fields:

interface RecordWithId extends RecordData {
    id: string; // Unique record identifier
    created_at?: string; // ISO 8601 timestamp
    updated_at?: string; // ISO 8601 timestamp
}

Advanced Filtering System

The SDK supports multiple filtering approaches for different use cases:

1. Simple Where Clause Format

const { data: records } = await client.records.findAll("users", {
    filters: {
        age: { $gte: 18 }, // Age >= 18
        status: "active", // Direct equality
        department: { $in: ["eng", "design"] }, // Array membership
    },
});

2. Direct ApiFilter Format

const { data: records } = await client.records.findAll("users", {
    filters: [
        { field: "age", operator: ">=", values: [18] },
        { field: "status", operator: "=", values: ["active"] },
        { field: "department", operator: "IN", values: ["eng", "design"] },
    ],
});

3. FilterBuilder for Complex Queries

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

const complexFilters = createFilter()
    .greaterThan("age", 18)
    .equals("status", "active")
    .in("department", ["eng", "design"])
    .like("email", "%@company.com")
    .between("salary", 50000, 100000)
    .build();

const { data: records } = await client.records.findAll("users", {
    filters: complexFilters,
});

Pagination and Sorting

Pagination

const { data: records, pagination } = await client.records.findAll("users", {
    page: {
        page_no: 1, // Page number (1-based)
        page_size: 20, // Records per page
    },
});

console.log(pagination.current_page); // 1
console.log(pagination.total_pages); // Total pages
console.log(pagination.total_count); // Total records

Sorting

const { data: records } = await client.records.findAll("users", {
    sort: [
        { field: "created_at", direction: "desc" },
        { field: "name", direction: "asc" },
    ],
});

Combined Query Options

const { data: records } = await client.records.findAll("users", {
    // Filtering
    filters: {
        status: "active",
        age: { $gte: 18 },
    },

    // Pagination
    page: {
        page_no: 1,
        page_size: 25,
    },

    // Sorting
    sort: [{ field: "created_at", direction: "desc" }],

    // Field selection
    fields: ["id", "name", "email", "created_at"],
});

Column Type Support

The SDK supports all Boltic Tables column types with appropriate filtering:

Column Type	Example Value	Supported Filters
text	"John Doe"	=, !=, LIKE, ILIKE, STARTS WITH, IN, IS EMPTY
email	"[email protected]"	=, !=, LIKE, ILIKE, STARTS WITH, IN, IS EMPTY
long-text	"Long description..."	=, !=, IS EMPTY
number	42	=, !=, >, >=, <, <=, BETWEEN, IN
currency	1999.99	=, !=, >, >=, <, <=, BETWEEN, IN
checkbox	true	= (True), != (False)
dropdown	["Option 1"]	=, !=, LIKE, ILIKE, IN, IS EMPTY
date-time	"2024-01-15T10:30:00Z"	=, !=, >, >=, <, <=, BETWEEN, WITHIN
json	{"key": "value"}	=, !=, IS EMPTY
vector	[0.1, 0.2, 0.3]	=, !=, >, >=, <, <=, BETWEEN, Distance operators
halfvec	[0.1, 0.2, 0.3]	=, !=, >, >=, <, <=, BETWEEN, Distance operators
sparsevec	"{1:1,3:2}/3"	=, !=, Distance operators

Vector Search Operations

For AI/ML applications, the SDK supports advanced vector operations:

// Similarity search using vector distance
const { data: similar } = await client.records.findAll("documents", {
    filters: [
        {
            field: "content_vector",
            operator: "<->", // Euclidean distance
            values: ["[0.1, 0.2, 0.3, 0.4, 0.5]"],
        },
    ],
    sort: [
        { field: "content_vector", direction: "asc" }, // Closest first
    ],
    page: { page_no: 1, page_size: 10 },
});

Next Steps

• Add your first record - Start with basic record creation