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.
4.1 KiB
@lancedb/lancedb • Docs
@lancedb/lancedb / 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()
execute(): Promise<Table>
Execute the permutation and create the destination table.
Returns
Promise<Table>
A Promise that resolves to the new Table instance
Example
const permutationTable = await builder.execute();
console.log(`Created table: ${permutationTable.name}`);
filter()
filter(filter): PermutationBuilder
Configure filtering for the permutation.
Parameters
- filter:
stringSQL filter expression
Returns
A new PermutationBuilder instance
Example
builder.filter("age > 18 AND status = 'active'");
persist()
persist(connection, tableName): PermutationBuilder
Configure the permutation to be persisted.
Parameters
-
connection:
ConnectionThe connection to persist the permutation to -
tableName:
stringThe name of the table to create
Returns
A new PermutationBuilder instance
Example
builder.persist(connection, "permutation_table");
shuffle()
shuffle(options): PermutationBuilder
Configure shuffling for the permutation.
Parameters
- options:
ShuffleOptionsConfiguration for shuffling
Returns
A new PermutationBuilder instance
Example
// Basic shuffle
builder.shuffle({ seed: 42 });
// Shuffle with clump size
builder.shuffle({ seed: 42, clumpSize: 10 });
splitCalculated()
splitCalculated(options): PermutationBuilder
Configure calculated splits for the permutation.
Parameters
- options:
SplitCalculatedOptionsConfiguration for calculated splitting
Returns
A new PermutationBuilder instance
Example
builder.splitCalculated({ calculation: "user_id % 3" });
splitHash()
splitHash(options): PermutationBuilder
Configure hash-based splits for the permutation.
Parameters
- options:
SplitHashOptionsConfiguration for hash-based splitting
Returns
A new PermutationBuilder instance
Example
builder.splitHash({
columns: ["user_id"],
splitWeights: [70, 30],
discardWeight: 0
});
splitRandom()
splitRandom(options): PermutationBuilder
Configure random splits for the permutation.
Parameters
- options:
SplitRandomOptionsConfiguration for random splitting
Returns
A new PermutationBuilder instance
Example
// 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()
splitSequential(options): PermutationBuilder
Configure sequential splits for the permutation.
Parameters
- options:
SplitSequentialOptionsConfiguration for sequential splitting
Returns
A new PermutationBuilder instance
Example
// 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 });