Skip to main content

List Tables

Retrieve all tables in your account with optional filtering, sorting, and pagination using the client.tables.findAll() method. This operation allows you to discover and manage your table collection efficiently.

Method Signature​

client.tables.findAll(options?: TableQueryOptions): Promise<ApiResponse<TableRecord[]>>

Parameters​

TableQueryOptions​

ParameterTypeRequiredDescription
whereRecord<string, unknown>❌Filter conditions for tables
fieldsstring[]❌Specific fields to return (reduces payload size)
sortSortOption[]❌Sort order for results
limitnumber❌Maximum number of tables to return
offsetnumber❌Number of tables to skip (for pagination)

SortOption Structure​

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

Return Value​

TableRecord​

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; // Deletion 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
    source?: "boltic" | "copilot"; // Creation source
    account_status?: "active" | "suspended" | "deleted"; // Account status
}

Examples​

List All Tables​

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

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

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

if (error) {
    console.error("Failed to list tables:", error.message);
} else {
    console.log(`Found ${tables.length} tables:`);
    tables.forEach((table) => {
        console.log(`- ${table.name}: ${table.description || "No description"}`);
    });
}

Filtered Table Listing​

// List only public tables
const { data: publicTables } = await client.tables.findAll({
    where: {
        is_public: true,
    },
});

// List tables created after a specific date
const { data: recentTables } = await client.tables.findAll({
    where: {
        created_at: {
            $gte: "2024-01-01T00:00:00Z",
        },
    },
    sort: [{ field: "created_at", direction: "desc" }],
});

// List tables with specific naming pattern
const { data: userTables } = await client.tables.findAll({
    where: {
        name: {
            $like: "%user%",
        },
    },
});

Paginated Results​

// Implement pagination
const pageSize = 10;
const pageNumber = 1;

const { data: paginatedTables } = await client.tables.findAll({
    limit: pageSize,
    offset: (pageNumber - 1) * pageSize,
    sort: [{ field: "name", direction: "asc" }],
});

console.log(`Page ${pageNumber} of tables:`, paginatedTables);

Optimized Field Selection​

// Only fetch essential fields to reduce bandwidth
const { data: tableSummary } = await client.tables.findAll({
    fields: ["id", "name", "description", "created_at"],
    sort: [{ field: "name", direction: "asc" }],
});

// Create a lookup map
const tableMap = new Map(tableSummary.map((table) => [table.name, table]));

Filter Operators​

The where clause supports various operators for flexible filtering:

Comparison Operators​

// Equal
{
    name: "users";
}

// Not equal
{
    name: {
        $ne: "temp_table";
    }
}

// Greater than / Less than
{
    created_at: {
        $gt: "2024-01-01T00:00:00Z";
    }
}
{
    created_at: {
        $lt: "2024-12-31T23:59:59Z";
    }
}

// Greater/Less than or equal
{
    created_at: {
        $gte: "2024-01-01T00:00:00Z";
    }
}
{
    created_at: {
        $lte: "2024-12-31T23:59:59Z";
    }
}

String Operators​

// Contains (case-sensitive)
{
    name: {
        $like: "%product%";
    }
}

// Contains (case-insensitive)
{
    name: {
        $ilike: "%USER%";
    }
}

// Starts with
{
    name: {
        $like: "prod_%";
    }
}

// Ends with
{
    name: {
        $like: "%_temp";
    }
}

Array Operators​

// In array
{
    name: {
        $in: ["users", "products", "orders"];
    }
}

// Not in array
{
    name: {
        $nin: ["temp_table", "test_table"];
    }
}

Logical Operators​

// AND (implicit)
{
  is_public: true,
  is_deleted: false
}

// OR
{
  $or: [
    { name: { $like: '%user%' } },
    { name: { $like: '%customer%' } }
  ]
}

Sorting Options​

Single Field Sorting​

// Sort by name ascending
const { data: tables } = await client.tables.findAll({
    sort: [{ field: "name", direction: "asc" }],
});

// Sort by creation date descending (newest first)
const { data: tables } = await client.tables.findAll({
    sort: [{ field: "created_at", direction: "desc" }],
});

Multi-Field Sorting​

// Sort by public status first, then by name
const { data: tables } = await client.tables.findAll({
    sort: [
        { field: "is_public", direction: "desc" }, // Public tables first
        { field: "name", direction: "asc" }, // Then alphabetically
    ],
});

Pagination Strategies​

Offset-Based Pagination​

async function getTablePage(pageNumber: number, pageSize: number = 20) {
    return await client.tables.findAll({
        limit: pageSize,
        offset: (pageNumber - 1) * pageSize,
        sort: [{ field: "created_at", direction: "desc" }],
    });
}

// Usage
const page1 = await getTablePage(1);
const page2 = await getTablePage(2);

Cursor-Based Pagination (by timestamp)​

async function getTablesAfter(lastCreatedAt?: string, limit: number = 20) {
    const where: any = { name: { $ne: "temp_table" } };

    if (lastCreatedAt) {
        where.created_at = { $gt: lastCreatedAt };
    }

    return await client.tables.findAll({
        where,
        limit,
        sort: [{ field: "created_at", direction: "asc" }],
    });
}

// Usage
let lastTimestamp: string | undefined;
let hasMore = true;

while (hasMore) {
    const { data: tables } = await getTablesAfter(lastTimestamp);

    if (tables.length === 0) {
        hasMore = false;
    } else {
        // Process tables
        console.log(`Processing ${tables.length} tables`);

        // Update cursor
        lastTimestamp = tables[tables.length - 1].created_at;
    }
}

Validation Errors​

The error.meta array contains specific validation errors:

  • 'page_no' must be greater than 0.
  • 'page_size' must be greater than 0.
  • 'sort' must be a list.
  • Each item in 'sort' must have a 'field' key with a string value.
  • Each item in 'sort' must have a 'direction' key with a value of 'asc' or 'desc'.

Performance Tips​

Optimize Query Performance​

  1. Use Field Selection: Only request fields you need

    // Good: Minimal fields
    fields: ["id", "name", "created_at"];

    // Avoid: Fetching all fields when unnecessary
    // (no fields parameter)

  2. Implement Pagination: Don't fetch all tables at once

    // Good: Paginated
    { limit: 50, offset: 0 }

    // Avoid: Fetching thousands of tables
    // (no limit)

  3. Use Specific Filters: Reduce the result set

    // Good: Specific filters
    where: {
        is_public: true;
    }

    // Avoid: Filtering in application code

  4. Index-Friendly Sorting: Sort by indexed fields

    // Good: Sort by indexed fields
    sort: [{ field: "created_at", direction: "desc" }];