Data Grids and Pagination
Relevant source files
The following files were used as context for generating this wiki page:
KamehaDB utilizes a sophisticated data grid system to render results from various database engines, including PostgreSQL, MySQL, SQLite, MongoDB, and Redis. The system is designed to handle large datasets through efficient server-side pagination and client-side virtualization, providing a consistent interface for both relational and document-based data.
The primary goal of the data grid is to provide a read-only (by default) preview of table and collection data. It supports dynamic column resizing, sorting, and advanced filtering to help developers inspect local or private databases safely.
Sources: PLAN.md:10-15, PLAN.md:41-45
Architecture and Data Flow
The data grid architecture follows a strict request-response cycle between the React-based desktop frontend and the Node.js sidecar. The frontend uses TanStack Table for rendering result grids and TanStack Query to manage asynchronous data fetching from the sidecar APIs.
Data Acquisition Flow
This diagram illustrates how a user request for data is processed from the UI through to the database.
The sidecar enforces safety guards, such as a default preview limit of 100 rows and a query display limit of 1000 rows, to prevent memory exhaustion in the desktop application.
Sources: PLAN.md:83-91, PLAN.md:144-150, PLAN.md:238-245
Pagination Logic
Pagination in KamehaDB is implemented server-side to ensure performance. The system tracks the current page and calculates the skip (offset) based on a defined pageLimit.
Pagination Parameters
| Parameter | Type | Description | Default Value |
|---|---|---|---|
limit | number | The number of rows to return per page. | 20 (UI) / 100 (API) |
offset / skip | number | The number of records to skip before starting to return rows. | 0 |
page | number | The 0-indexed current page number. | 0 |
Sources: apps/desktop/src/components/mongo-view.tsx:50-55, PLAN.md:243
In the MongoDB view, the skip value is calculated as page * pageLimit. The interface provides a "Next" and "Prev" button, along with a direct page input that clamps values between 1 and the maximum calculated page.
const PAGE_SIZE = 20;
// ... inside handleRun(currentPage)
const res = await post<DocumentResult>(`/mongo/${connectionId}/aggregate`, {
collection,
database: db,
pipeline: parsed,
skip: currentPage * PAGE_SIZE,
limit: PAGE_SIZE,
});
Sources: apps/desktop/src/components/mongo-query.tsx:23, apps/desktop/src/components/mongo-query.tsx:69-75
Data Grid Features
Column Management and Resizing
The grids support dynamic column generation. For document databases like MongoDB, the system derives column headers by scanning the keys of the returned documents.
const columns = useMemo(() => {
const keys = new Set<string>();
documents.forEach((doc) => Object.keys(doc).forEach((k) => keys.add(k)));
return Array.from(keys);
}, [documents]);
Sources: apps/desktop/src/components/mongo-view.tsx:543-547
A custom useColumnResize hook is used to manage table-fixed layouts, allowing users to manually adjust the width of individual columns.
Sources: apps/desktop/src/components/mongo-view.tsx:611, CHANGELOG.md:139
Sorting and Filtering
Users can toggle sorting on any column. The sorting state is serialized and sent to the backend as part of the query input.
- SQL Engines: Uses
sortColumnandsortDirection('asc' | 'desc'). - MongoDB: Uses a sort object (e.g.,
{ [field]: 1 }for ascending).
Sources: packages/shared/src/index.ts:133-134, apps/desktop/src/components/mongo-view.tsx:75-92
Results Normalization
The QueryResult structure ensures that regardless of the underlying database engine, the frontend receives a uniform data shape for rendering.
export type QueryResult = {
columns: QueryColumn[];
rows: Record<string, unknown>[];
rowCount: number;
durationMs: number;
truncated: boolean;
};
Sources: packages/shared/src/index.ts:68-74
Implementation Varieties
The project implements specialized views for different data types, optimizing the grid experience for each.
1. SQL Table View
Focuses on strict schemas, displaying column types, primary keys, and index statistics. It utilizes apps/desktop/src/components/table-stats.tsx to show a size breakdown and bloat analysis alongside the data.
Sources: apps/desktop/src/components/table-stats.tsx:40-75
2. MongoDB Document View
Offers a choice between a "Table" view (flat grid) and a "List" view (expandable JSON cards). It includes specialized logic for handling MongoDB's _id and nested objects.
Sources: apps/desktop/src/components/mongo-view.tsx:43-48
3. Aggregate Query Result Grid
Used in the MongoQuery component, this grid is optimized for dynamic pipelines where the resulting schema may change entirely between executions.
Sources: apps/desktop/src/components/mongo-query.tsx:162-180
Summary
Data Grids and Pagination in KamehaDB bridge the gap between various database paradigms by providing a unified, performant, and safe interface. By leveraging server-side pagination and a normalized QueryResult contract, the application can display large datasets from SQL, NoSQL, and Vector databases without compromising the local-first desktop experience. Key features like dynamic column resizing, multi-mode views, and integrated performance statistics make it a comprehensive tool for database inspection.