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