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: string SQL filter expression

Returns¶

PermutationBuilder

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: Connection The connection to persist the permutation to
tableName: string The name of the table to create

Returns¶

PermutationBuilder

A new PermutationBuilder instance

Example¶

builder.persist(connection, "permutation_table");

shuffle()¶

shuffle(options): PermutationBuilder

Configure shuffling for the permutation.

Parameters¶

options: ShuffleOptions Configuration for shuffling

Returns¶

PermutationBuilder

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: SplitCalculatedOptions Configuration for calculated splitting

Returns¶

PermutationBuilder

A new PermutationBuilder instance

Example¶

builder.splitCalculated({ calculation: "user_id % 3" });

splitHash()¶

splitHash(options): PermutationBuilder

Configure hash-based splits for the permutation.

Parameters¶

options: SplitHashOptions Configuration for hash-based splitting

Returns¶

PermutationBuilder

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: SplitRandomOptions Configuration for random splitting

Returns¶

PermutationBuilder

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: SplitSequentialOptions Configuration for sequential splitting

Returns¶

PermutationBuilder

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 });