List Indexes

Retrieve information about database indexes with comprehensive filtering, sorting, and pagination options. This operation helps you monitor index usage, analyze performance, and manage your database optimization strategy.

Method Signature

listIndexes(
  tableName: string,
  query: ListIndexesQuery
): Promise<BolticSuccessResponse<ListIndexesResponse> | BolticErrorResponse>

Parameters

Parameter	Type	Required	Description
tableName	string	✅	Name of the table to list indexes for
query	ListIndexesQuery	✅	Query configuration for filtering, sorting, and pagination

ListIndexesQuery

interface ListIndexesQuery {
    page?: {
        // Pagination settings
        page_no: number; // Page number (1-based)
        page_size: number; // Items per page
    };
    filters?: Array<{
        // Filter conditions
        field: string; // Field to filter on
        operator: string; // Comparison operator
        values: unknown[]; // Values to compare against
    }>;
    sort?: Array<{
        // Sort order
        field: string; // Field to sort by
        direction: "asc" | "desc"; // Sort direction
    }>;
}

Property	Type	Required	Description
page	object	❌	Pagination settings (page_no, page_size)
filters	Array<FilterCondition>	❌	Filter conditions for index properties
sort	Array<SortOption>	❌	Sort order for results

Response

interface ListIndexesResponse {
    items: IndexListItem[]; // Array of index information
    page?: {
        // Pagination metadata
        page_no: number; // Current page number
        page_size: number; // Items per page
        total?: number; // Total number of items
    };
}

interface IndexListItem {
    schemaname?: string; // Database schema name
    relname?: string; // Table name
    indexrelname: string; // Index name
    method?: string; // Index method (btree, hash, gin, etc.)
    idx_scan?: number; // Number of index scans
    idx_tup_read?: number; // Number of tuples read
    idx_tup_fetch?: number; // Number of tuples fetched
    field_ids?: string[]; // Internal field IDs
    fields?: string[]; // Field names in index
    created_at?: string; // Creation timestamp
    created_by?: string; // Creator identifier
}

Examples

Basic Index Listing

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

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

// List all indexes for a table
const { data: indexes, error } = await client.indexes.listIndexes("users", {
    page: { page_no: 1, page_size: 50 },
});

if (error) {
    console.error("Failed to list indexes:", error.message);
} else {
    console.log(`Found ${indexes.items.length} indexes`);
    indexes.items.forEach((index) => {
        console.log(`- ${index.indexrelname} (${index.method})`);
    });
}

Filtering Indexes

// Filter by schema
const publicIndexes = await client.indexes.listIndexes("users", {
    filters: [{ field: "schemaname", operator: "=", values: ["public"] }],
});

// Filter by index method
const btreeIndexes = await client.indexes.listIndexes("users", {
    filters: [{ field: "method", operator: "=", values: ["btree"] }],
});

// Filter by table name
const userTableIndexes = await client.indexes.listIndexes("users", {
    filters: [{ field: "relname", operator: "=", values: ["users"] }],
});

// Multiple filters (AND condition)
const filteredIndexes = await client.indexes.listIndexes("users", {
    filters: [
        { field: "schemaname", operator: "=", values: ["public"] },
        { field: "method", operator: "!=", values: ["hash"] },
    ],
});

Sorting Results

// Sort by index name (ascending)
const sortedByName = await client.indexes.listIndexes("users", {
    sort: [{ field: "indexrelname", direction: "asc" }],
});

// Sort by scan count (descending) - most used indexes first
const sortedByUsage = await client.indexes.listIndexes("users", {
    sort: [{ field: "idx_scan", direction: "desc" }],
});

// Multiple sort criteria
const multiSort = await client.indexes.listIndexes("users", {
    sort: [
        { field: "method", direction: "asc" },
        { field: "indexrelname", direction: "asc" },
    ],
});

Chained Access Method

// Using chained access pattern
const { data: indexes } = await client
    .from("users")
    .indexes()
    .listIndexes({
        page: { page_no: 1, page_size: 50 },
        sort: [{ field: "indexrelname", direction: "asc" }],
    });