mirror of
https://github.com/lancedb/lancedb.git
synced 2026-05-25 16:00:49 +00:00
76bcc78910
Fixes the breaking CI for nodejs, related to the documentation of the
new Permutation API in typescript.
- Expanded the generated typings in `nodejs/lancedb/native.d.ts` to
include `SplitCalculatedOptions`, `splitNames` fields, and the
persist/options-based `splitCalculated` methods so the permutation
exports match the native API.
- The previous block comment block had an inconsistency.
`splitCalculated` takes an options object (`SplitCalculatedOptions`) in
our bindings, not a bare string. The previous example showed
`builder.splitCalculated("user_id % 3");`, which doesn’t match the
actual signature and would fail TS typecheck. I updated the comment to
`builder.splitCalculated({ calculation: "user_id % 3" });` so the
example is now correct.
- Updated the `splitCalculated` example in
`nodejs/lancedb/permutation.ts` to use the options object.
- Ran `npm docs` to ensure docs build correctly.
> [!NOTE]
> **Disclaimer**: I used GPT-5.1-Codex-Max to make these updates, but I
have read the code and run `npm run docs` to verify that they work and
are correct to the best of my knowledge.
251 lines
4.1 KiB
Markdown
251 lines
4.1 KiB
Markdown
[**@lancedb/lancedb**](../README.md) • **Docs**
|
|
|
|
***
|
|
|
|
[@lancedb/lancedb](../globals.md) / PermutationBuilder
|
|
|
|
# Class: PermutationBuilder
|
|
|
|
A PermutationBuilder for creating data permutations with splits, shuffling, and filtering.
|
|
|
|
This class provides a TypeScript wrapper around the native Rust PermutationBuilder,
|
|
offering methods to configure data splits, shuffling, and filtering before executing
|
|
the permutation to create a new table.
|
|
|
|
## Methods
|
|
|
|
### execute()
|
|
|
|
```ts
|
|
execute(): Promise<Table>
|
|
```
|
|
|
|
Execute the permutation and create the destination table.
|
|
|
|
#### Returns
|
|
|
|
`Promise`<[`Table`](Table.md)>
|
|
|
|
A Promise that resolves to the new Table instance
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
const permutationTable = await builder.execute();
|
|
console.log(`Created table: ${permutationTable.name}`);
|
|
```
|
|
|
|
***
|
|
|
|
### filter()
|
|
|
|
```ts
|
|
filter(filter): PermutationBuilder
|
|
```
|
|
|
|
Configure filtering for the permutation.
|
|
|
|
#### Parameters
|
|
|
|
* **filter**: `string`
|
|
SQL filter expression
|
|
|
|
#### Returns
|
|
|
|
[`PermutationBuilder`](PermutationBuilder.md)
|
|
|
|
A new PermutationBuilder instance
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
builder.filter("age > 18 AND status = 'active'");
|
|
```
|
|
|
|
***
|
|
|
|
### persist()
|
|
|
|
```ts
|
|
persist(connection, tableName): PermutationBuilder
|
|
```
|
|
|
|
Configure the permutation to be persisted.
|
|
|
|
#### Parameters
|
|
|
|
* **connection**: [`Connection`](Connection.md)
|
|
The connection to persist the permutation to
|
|
|
|
* **tableName**: `string`
|
|
The name of the table to create
|
|
|
|
#### Returns
|
|
|
|
[`PermutationBuilder`](PermutationBuilder.md)
|
|
|
|
A new PermutationBuilder instance
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
builder.persist(connection, "permutation_table");
|
|
```
|
|
|
|
***
|
|
|
|
### shuffle()
|
|
|
|
```ts
|
|
shuffle(options): PermutationBuilder
|
|
```
|
|
|
|
Configure shuffling for the permutation.
|
|
|
|
#### Parameters
|
|
|
|
* **options**: [`ShuffleOptions`](../interfaces/ShuffleOptions.md)
|
|
Configuration for shuffling
|
|
|
|
#### Returns
|
|
|
|
[`PermutationBuilder`](PermutationBuilder.md)
|
|
|
|
A new PermutationBuilder instance
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
// Basic shuffle
|
|
builder.shuffle({ seed: 42 });
|
|
|
|
// Shuffle with clump size
|
|
builder.shuffle({ seed: 42, clumpSize: 10 });
|
|
```
|
|
|
|
***
|
|
|
|
### splitCalculated()
|
|
|
|
```ts
|
|
splitCalculated(options): PermutationBuilder
|
|
```
|
|
|
|
Configure calculated splits for the permutation.
|
|
|
|
#### Parameters
|
|
|
|
* **options**: [`SplitCalculatedOptions`](../interfaces/SplitCalculatedOptions.md)
|
|
Configuration for calculated splitting
|
|
|
|
#### Returns
|
|
|
|
[`PermutationBuilder`](PermutationBuilder.md)
|
|
|
|
A new PermutationBuilder instance
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
builder.splitCalculated({ calculation: "user_id % 3" });
|
|
```
|
|
|
|
***
|
|
|
|
### splitHash()
|
|
|
|
```ts
|
|
splitHash(options): PermutationBuilder
|
|
```
|
|
|
|
Configure hash-based splits for the permutation.
|
|
|
|
#### Parameters
|
|
|
|
* **options**: [`SplitHashOptions`](../interfaces/SplitHashOptions.md)
|
|
Configuration for hash-based splitting
|
|
|
|
#### Returns
|
|
|
|
[`PermutationBuilder`](PermutationBuilder.md)
|
|
|
|
A new PermutationBuilder instance
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
builder.splitHash({
|
|
columns: ["user_id"],
|
|
splitWeights: [70, 30],
|
|
discardWeight: 0
|
|
});
|
|
```
|
|
|
|
***
|
|
|
|
### splitRandom()
|
|
|
|
```ts
|
|
splitRandom(options): PermutationBuilder
|
|
```
|
|
|
|
Configure random splits for the permutation.
|
|
|
|
#### Parameters
|
|
|
|
* **options**: [`SplitRandomOptions`](../interfaces/SplitRandomOptions.md)
|
|
Configuration for random splitting
|
|
|
|
#### Returns
|
|
|
|
[`PermutationBuilder`](PermutationBuilder.md)
|
|
|
|
A new PermutationBuilder instance
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
// Split by ratios
|
|
builder.splitRandom({ ratios: [0.7, 0.3], seed: 42 });
|
|
|
|
// Split by counts
|
|
builder.splitRandom({ counts: [1000, 500], seed: 42 });
|
|
|
|
// Split with fixed size
|
|
builder.splitRandom({ fixed: 100, seed: 42 });
|
|
```
|
|
|
|
***
|
|
|
|
### splitSequential()
|
|
|
|
```ts
|
|
splitSequential(options): PermutationBuilder
|
|
```
|
|
|
|
Configure sequential splits for the permutation.
|
|
|
|
#### Parameters
|
|
|
|
* **options**: [`SplitSequentialOptions`](../interfaces/SplitSequentialOptions.md)
|
|
Configuration for sequential splitting
|
|
|
|
#### Returns
|
|
|
|
[`PermutationBuilder`](PermutationBuilder.md)
|
|
|
|
A new PermutationBuilder instance
|
|
|
|
#### Example
|
|
|
|
```ts
|
|
// Split by ratios
|
|
builder.splitSequential({ ratios: [0.8, 0.2] });
|
|
|
|
// Split by counts
|
|
builder.splitSequential({ counts: [800, 200] });
|
|
|
|
// Split with fixed size
|
|
builder.splitSequential({ fixed: 1000 });
|
|
```
|