diff --git a/docs/src/js/classes/Table.md b/docs/src/js/classes/Table.md index b2f72012f..87582376a 100644 --- a/docs/src/js/classes/Table.md +++ b/docs/src/js/classes/Table.md @@ -501,6 +501,34 @@ Modeled after ``VACUUM`` in PostgreSQL. *** +### prewarmData() + +```ts +abstract prewarmData(columns?): Promise +``` + +Prewarm one or more columns of data in the table. + +#### Parameters + +* **columns?**: `string`[] + The columns to prewarm. If undefined, all columns are prewarmed. + This will load the column data into the page cache so that future queries that + read those columns avoid the initial cold-start latency. This call initiates + prewarming and returns once the request is accepted; the warming itself may + continue in the background. Calling it on already-prewarmed columns is a + no-op on the server. + Prewarming is generally useful for columns used in filters or projections. + Large columns (e.g. high-dimensional vectors or binary data) may not be + practical to prewarm. + This feature is currently only supported on remote tables. + +#### Returns + +`Promise`<`void`> + +*** + ### prewarmIndex() ```ts diff --git a/nodejs/__test__/table.test.ts b/nodejs/__test__/table.test.ts index 21c081ada..36c616438 100644 --- a/nodejs/__test__/table.test.ts +++ b/nodejs/__test__/table.test.ts @@ -1870,6 +1870,25 @@ describe.each([arrow15, arrow16, arrow17, arrow18])( expect(results.length).toBe(3); }); + test("prewarmData errors on local tables", async () => { + const db = await connect(tmpDir.name); + const data = [ + { text: "alpha", vector: [0.1, 0.2, 0.3] }, + { text: "beta", vector: [0.4, 0.5, 0.6] }, + ]; + const table = await db.createTable("prewarm_data_test", data); + + // prewarmData is only supported on remote tables. We verify the call + // is wired through napi and surfaces the expected error for both + // arg shapes (undefined and string[]). + await expect(table.prewarmData()).rejects.toThrow( + "prewarm_data is currently only supported on remote tables", + ); + await expect(table.prewarmData(["text"])).rejects.toThrow( + "prewarm_data is currently only supported on remote tables", + ); + }); + test("full text index on list", async () => { const db = await connect(tmpDir.name); const data = [ diff --git a/nodejs/lancedb/table.ts b/nodejs/lancedb/table.ts index ca33504e4..264b8897d 100644 --- a/nodejs/lancedb/table.ts +++ b/nodejs/lancedb/table.ts @@ -285,6 +285,25 @@ export abstract class Table { */ abstract prewarmIndex(name: string): Promise; + /** + * Prewarm one or more columns of data in the table. + * + * @param columns The columns to prewarm. If undefined, all columns are prewarmed. + * + * This will load the column data into the page cache so that future queries that + * read those columns avoid the initial cold-start latency. This call initiates + * prewarming and returns once the request is accepted; the warming itself may + * continue in the background. Calling it on already-prewarmed columns is a + * no-op on the server. + * + * Prewarming is generally useful for columns used in filters or projections. + * Large columns (e.g. high-dimensional vectors or binary data) may not be + * practical to prewarm. + * + * This feature is currently only supported on remote tables. + */ + abstract prewarmData(columns?: string[]): Promise; + /** * Waits for asynchronous indexing to complete on the table. * @@ -710,6 +729,10 @@ export class LocalTable extends Table { await this.inner.prewarmIndex(name); } + async prewarmData(columns?: string[]): Promise { + await this.inner.prewarmData(columns); + } + async waitForIndex( indexNames: string[], timeoutSeconds: number, diff --git a/nodejs/src/table.rs b/nodejs/src/table.rs index cad21838a..6100d7bd7 100644 --- a/nodejs/src/table.rs +++ b/nodejs/src/table.rs @@ -159,6 +159,14 @@ impl Table { .default_error() } + #[napi(catch_unwind)] + pub async fn prewarm_data(&self, columns: Option>) -> napi::Result<()> { + self.inner_ref()? + .prewarm_data(columns) + .await + .default_error() + } + #[napi(catch_unwind)] pub async fn wait_for_index(&self, index_names: Vec, timeout_s: i64) -> Result<()> { let timeout = std::time::Duration::from_secs(timeout_s.try_into().unwrap());