# df-script API Reference (v2.4.0) > A zero-dependency, high-performance, expression-based DataFrame library for TypeScript/JavaScript. - **License**: MIT - **Website**: https://df-script.js.org - **GitHub**: https://github.com/trentamorris/df-script - **Overview (llms.txt)**: https://df-script.js.org/llms.txt - **API Schema (docs.json)**: https://df-script.js.org/docs.json # Column Expression API ## Namespace: $df.col.arrayExpr ## Operation Applies an aggregation expression or element-wise calculation over each array cell. ### Signature ```typescript $df.col().arr.agg(expr: IExpr) ``` ### Parameters - `expr` (any): Aggregation expression (e.g. $df.element().sum() or $df.element().max()) ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.agg($df.element().sum()).alias("sum_a")) shape: (2, 2) +-----------+-------+ | a | sum_a | +-----------+-------+ | [1, 2, 3] | 6 | | [4, 5] | 9 | +-----------+-------+ ``` --- ## Operation Returns true if all items in nested list cells are truthy. ### Signature ```typescript $df.col().arr.all() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.all().alias("all_true")) shape: (2, 2) +---------------+----------+ | a | all_true | +---------------+----------+ | [true, true] | true | | [true, false] | false | +---------------+----------+ ``` --- ## Operation Returns true if any item in nested list cells is truthy. ### Signature ```typescript $df.col().arr.any() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.any().alias("any_true")) shape: (2, 2) +---------------+----------+ | a | any_true | +---------------+----------+ | [true, true] | true | | [true, false] | true | +---------------+----------+ ``` --- ## Operation Finds the index of the maximum value in each array. ### Signature ```typescript $df.col().arr.argMax() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.argMax().alias("max_idx")) shape: (2, 2) +-----------+---------+ | a | max_idx | +-----------+---------+ | [1, 2, 3] | 2 | | [4, 5] | 1 | +-----------+---------+ ``` --- ## Operation Finds the index of the minimum value in each array. ### Signature ```typescript $df.col().arr.argMin() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.argMin().alias("min_idx")) shape: (2, 2) +-----------+---------+ | a | min_idx | +-----------+---------+ | [1, 2, 3] | 0 | | [4, 5] | 0 | +-----------+---------+ ``` --- ## Operation Checks if nested lists contain item. ### Signature ```typescript $df.col().arr.contains(item: IExpr | ValidScalarTypes) ``` ### Parameters - `item` (any): The element to search for. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.contains(3).alias("has_three")) shape: (2, 2) +-----------+-----------+ | a | has_three | +-----------+-----------+ | [1, 2, 3] | true | | [4, 5] | false | +-----------+-----------+ ``` --- ## Operation Checks if nested lists contain all elements in items. ### Signature ```typescript $df.col().arr.containsAll(items: IExpr | ValidScalarTypes[] | AnyTypedArray) ``` ### Parameters - `items` (any): Array of elements or column expression that must all be present. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.containsAll([1, 2]).alias("has_all")) shape: (2, 2) +-----------+---------+ | a | has_all | +-----------+---------+ | [1, 2, 3] | true | | [4, 5] | false | +-----------+---------+ ``` --- ## Operation Checks if nested lists contain any element in items. ### Signature ```typescript $df.col().arr.containsAny(items: IExpr | ValidScalarTypes[] | AnyTypedArray) ``` ### Parameters - `items` (any): Array of elements or column expression where at least one must be present. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.containsAny([2, 3]).alias("has_any")) shape: (2, 2) +--------+---------+ | a | has_any | +--------+---------+ | [1, 2] | true | | [3, 4] | true | +--------+---------+ ``` --- ## Operation Counts occurrence frequency of item inside nested lists. ### Signature ```typescript $df.col().arr.countMatches( item: IExpr | ValidScalarTypes, options: { keySelector?: (val: any) => any, strict?: boolean = false } = {} ) ``` ### Parameters - `item` (any): The value to count occurrences of. - `options` (any): Statistics and matching options. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.countMatches(2).alias("twos")) shape: (2, 2) +-----------+------+ | a | twos | +-----------+------+ | [1, 2, 3] | 1 | | [4, 5] | 0 | +-----------+------+ ``` --- ## Operation Evaluates subExpr element-wise across array lists. ### Signature ```typescript $df.col().arr.eval(expr: IExpr) ``` ### Parameters - `expr` (any): The sub-expression to evaluate inside each nested list. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.eval($df.element().mul(10)).alias("multiplied")) shape: (2, 2) +--------+------------+ | a | multiplied | +--------+------------+ | [1, 2] | [10, 20] | | [3, 4] | [30, 40] | +--------+------------+ ``` --- ## Operation Expands lists into row-wise elements and produces an index mapping for DataFrame unnesting. ### Signature ```typescript $df.col().arr.explode( options: { emptyAsNull?: boolean = true, keepNulls?: boolean = true } = {} ) ``` ### Parameters - `options` (any): Config options including handling of empty arrays and nulls. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.select([$df.col("group"), $df.col("values").arr.explode()]) shape: (2, 2) +-------+--------+ | group | values | +-------+--------+ | A | 1 | | A | 2 | +-------+--------+ ``` --- ## Operation Filters elements of list columns matching a boolean sub-expression. ### Signature ```typescript $df.col().arr.filter(expr: IExpr) ``` ### Parameters - `expr` (any): The boolean column expression to filter by. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.filter($df.element().gt(2)).alias("filtered")) shape: (2, 2) +-----------+----------+ | a | filtered | +-----------+----------+ | [1, 2, 3] | [3] | | [4, 5] | [4, 5] | +-----------+----------+ ``` --- ## Operation Returns the first element of each list. ### Signature ```typescript $df.col().arr.first(nullOnOob: boolean = true) ``` ### Parameters - `nullOnOob` (any): If true, returns null if the list is empty (default: true). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.first().alias("first_a")) shape: (2, 2) +-----------+---------+ | a | first_a | +-----------+---------+ | [1, 2, 3] | 1 | | [4, 5] | 4 | +-----------+---------+ ``` --- ## Operation Gathers specific indices from each nested list. ### Signature ```typescript $df.col().arr.gather( indices: NumericArg | number[] | AnyTypedArray, nullOnOob: boolean = true ) ``` ### Parameters - `indices` (any): Index or array of indices to extract. - `nullOnOob` (any): If true, returns null for indices out of bounds (default: true). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.gather([0, 2]).alias("g")) shape: (2, 2) +-----------+----------+ | a | g | +-----------+----------+ | [1, 2, 3] | [1, 3] | | [4, 5] | [4, null]| +-----------+----------+ ``` --- ## Operation Gather element slices with custom steps. ### Signature ```typescript $df.col().arr.gatherEvery( options: { maxItemsGathered?: number, nullOnOob?: boolean = true, offsetEnd?: number, offsetStart?: number = 0, step?: number = 1 } = {} ) ``` ### Parameters - `options` (any): Config options including offset, limit, and step size. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.gatherEvery({ step: 2 }).alias("ge")) shape: (2, 2) +-----------+--------+ | a | ge | +-----------+--------+ | [1, 2, 3] | [1, 3] | | [4, 5] | [4] | +-----------+--------+ ``` --- ## Operation Extracts a single list element by its index position. ### Signature ```typescript $df.col().arr.get( index: number | bigint | IExpr | null, nullOnOob: boolean = true ) ``` ### Parameters - `index` (any): The 0-based or negative index position to extract. - `nullOnOob` (any): If true, returns null if index is out of bounds (default: true). ### Returns: `ColumnExpression` ### Examples ```typescript // 1. Positive 0-based index: >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.get(1).alias("second")) shape: (2, 2) +-----------+--------+ | a | second | +-----------+--------+ | [1, 2, 3] | 2 | | [4, 5] | 5 | +-----------+--------+ // 2. Negative index (from the end): >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.get(-1).alias("last_val")) shape: (2, 2) +-----------+----------+ | a | last_val | +-----------+----------+ | [1, 2, 3] | 3 | | [4, 5] | 5 | +-----------+----------+ ``` --- ## Operation Joins elements of list columns into a single string column. ### Signature ```typescript $df.col().arr.join( separator: string = ",", options: { ignoreNulls?: boolean = false, limit?: number, nullValue?: string = "", prefix?: string = "", suffix?: string = "", truncationMarker?: string = "...", valueFormatter?: (val: any, index: number) => string } = {} ) ``` ### Parameters - `separator` (any): The character sequence separating list elements. - `options` (any): String conversion options. ### Returns: `ColumnExpression` ### Examples ```typescript // 1. Default delimiter join: >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.join("-").alias("joined")) shape: (2, 2) +-----------+---------+ | a | joined | +-----------+---------+ | [1, 2, 3] | "1-2-3" | | [4, 5] | "4-5" | +-----------+---------+ // 2. Custom delimiter with prefix and suffix options: >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.join(" | ", { prefix: "<", suffix: ">" }).alias("joined")) shape: (2, 2) +-----------+---------------+ | a | joined | +-----------+---------------+ | [1, 2, 3] | "<1 | 2 | 3>" | | [4, 5] | "<4 | 5>" | +-----------+---------------+ ``` --- ## Operation Returns the last element of each list. ### Signature ```typescript $df.col().arr.last(nullOnOob: boolean = true) ``` ### Parameters - `nullOnOob` (any): If true, returns null if the list is empty (default: true). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.last().alias("last_a")) shape: (2, 2) +-----------+--------+ | a | last_a | +-----------+--------+ | [1, 2, 3] | 3 | | [4, 5] | 5 | +-----------+--------+ ``` --- ## Operation Returns the length of each list inside the column cell. ### Signature ```typescript $df.col().arr.len() ``` --- ## Operation Returns the length of each list inside the column cell. ### Signature ```typescript $df.col().arr.lengths() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.lengths().alias("len_a")) shape: (2, 2) +-----------+-------+ | a | len_a | +-----------+-------+ | [1, 2, 3] | 3 | | [4, 5] | 2 | +-----------+-------+ ``` --- ## Operation Returns the maximum value of elements inside each list. ### Signature ```typescript $df.col().arr.max() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.max().alias("max_a")) shape: (2, 2) +-----------+-------+ | a | max_a | +-----------+-------+ | [1, 2, 3] | 3 | | [4, 5] | 5 | +-----------+-------+ ``` --- ## Operation Returns average of elements inside each list. ### Signature ```typescript $df.col().arr.mean() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.mean().alias("mean_a")) shape: (2, 2) +-----------+--------+ | a | mean_a | +-----------+--------+ | [1, 2, 3] | 2 | | [4, 5] | 4.5 | +-----------+--------+ ``` --- ## Operation Returns statistical median inside each list. ### Signature ```typescript $df.col().arr.median() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.median().alias("med")) shape: (2, 2) +-----------+------+ | a | med | +-----------+------+ | [1, 2, 3] | 2 | | [4, 5] | 4.5 | +-----------+------+ ``` --- ## Operation Returns minimum of elements inside each list. ### Signature ```typescript $df.col().arr.min() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.min().alias("min_a")) shape: (2, 2) +-----------+-------+ | a | min_a | +-----------+-------+ | [1, 2, 3] | 1 | | [4, 5] | 4 | +-----------+-------+ ``` --- ## Operation Returns the mode value inside each list. ### Signature ```typescript $df.col().arr.mode() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.mode().alias("mode_a")) shape: (2, 2) +-----------+-----------+ | a | mode_a | +-----------+-----------+ | [1, 2, 3] | [1, 2, 3] | | [4, 5] | [4, 5] | +-----------+-----------+ ``` --- ## Operation Returns the unique count of elements inside each list. ### Signature ```typescript $df.col().arr.nUnique( options: { keySelector?: (val: any) => any, strict?: boolean = false } = {} ) ``` ### Parameters - `options` (any): Formatting/statistics parameters. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.nUnique().alias("unique_len")) shape: (2, 2) +-----------+------------+ | a | unique_len | +-----------+------------+ | [1, 2, 3] | 3 | | [4, 5] | 2 | +-----------+------------+ ``` --- ## Operation Reverses elements of list columns. ### Signature ```typescript $df.col().arr.reverse() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.reverse().alias("reversed")) shape: (2, 2) +-----------+-----------+ | a | reversed | +-----------+-----------+ | [1, 2, 3] | [3, 2, 1] | | [4, 5] | [5, 4] | +-----------+-----------+ ``` --- ## Operation Shifts elements of list columns by N offsets. ### Signature ```typescript $df.col().arr.shift( n: number = 1, options: { fillValue?: any = null } = {} ) ``` ### Parameters - `n` (any): Positive or negative offsets shift amount (default: 1). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.shift(1).alias("shifted")) shape: (2, 2) +-----------+------------------+ | a | shifted | +-----------+------------------+ | [1, 2, 3] | [null, 1, 2] | | [4, 5] | [null, 4] | +-----------+------------------+ ``` --- ## Operation Slices nested list arrays. ### Signature ```typescript $df.col().arr.slice( start?: number, end?: number ) ``` ### Parameters - `start` (any): The slice starting index. - `end` (any): The slice ending index. ### Returns: `ColumnExpression` ### Examples ```typescript // 1. Positive slice with start and end offsets: >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.slice(1, 3).alias("sliced")) shape: (2, 2) +-----------+--------+ | a | sliced | +-----------+--------+ | [1, 2, 3] | [2, 3] | | [4, 5] | [5] | +-----------+--------+ // 2. Negative slice offset from the end: >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.slice(-2).alias("tail2")) shape: (2, 2) +-----------+--------+ | a | tail2 | +-----------+--------+ | [1, 2, 3] | [2, 3] | | [4, 5] | [4, 5] | +-----------+--------+ ``` --- ## Operation Sorts elements inside each list. ### Signature ```typescript $df.col().arr.sort( options?: { customComp?: ((a: any, b: any) => number) | Partial number>> | null, descending?: boolean | boolean[] = false, nullsLast?: boolean = true } ) ``` ### Parameters - `options` (any): Sort customization parameters (e.g. descending flag). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.sort().alias("sorted")) shape: (2, 2) +-----------+-----------+ | a | sorted | +-----------+-----------+ | [1, 2, 3] | [1, 2, 3] | | [4, 5] | [4, 5] | +-----------+-----------+ ``` --- ## Operation Splices elements in list cells. ### Signature ```typescript $df.col().arr.splice( start: number, deleteCount?: number, ...items: (Exclude | Date | AnyTypedArray)[] ) ``` ### Parameters - `start` (any): The index where array modifications begin. - `deleteCount` (any): The number of elements to remove. - `items` (any): The elements to insert. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.splice(1, 1, 10, 20).alias("spliced")) shape: (2, 2) +-----------+-----------------+ | a | spliced | +-----------+-----------------+ | [1, 2, 3] | [1, 10, 20, 3] | | [4, 5] | [4, 10, 20] | +-----------+-----------------+ ``` --- ## Operation Returns sample standard deviation of elements inside each list. ### Signature ```typescript $df.col().arr.std() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.std().alias("std_dev")) shape: (2, 2) +-----------+----------+ | a | std_dev | +-----------+----------+ | [1, 2, 3] | 1 | | [4, 5] | 0.707107 | +-----------+----------+ ``` --- ## Operation Returns sum of elements inside each list. ### Signature ```typescript $df.col().arr.sum() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.sum().alias("sum_a")) shape: (2, 2) +-----------+-------+ | a | sum_a | +-----------+-------+ | [1, 2, 3] | 6 | | [4, 5] | 9 | +-----------+-------+ ``` --- ## Operation Converts list column elements to struct columns. ### Signature ```typescript $df.col().arr.toStruct( options: { fields?: string[] | ((idx: number) => string) = `"field_0"`, `"field_1"`, etc, upperBound?: number = the maximum array length in the column } = {} ) ``` ### Parameters - `options` (any): Config flags including custom field names or upper bound size. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.toStruct({ fields: ["x", "y"] }).alias("struct_a")) shape: (2, 2) +--------+----------------+ | a | struct_a | +--------+----------------+ | [1, 2] | { x: 1, y: 2 } | | [3, 4] | { x: 3, y: 4 } | +--------+----------------+ ``` --- ## Operation Fills each list with unique elements only. ### Signature ```typescript $df.col().arr.unique( options: { keySelector?: (val: any) => any, strict?: boolean = false } = {} ) ``` ### Parameters - `options` (any): Custom uniqueness matching configuration. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.unique().alias("unique_a")) shape: (2, 2) +-----------+-----------+ | a | unique_a | +-----------+-----------+ | [1, 2, 3] | [1, 2, 3] | | [4, 5] | [4, 5] | +-----------+-----------+ ``` --- ## Operation Returns sample variance of elements inside each list. ### Signature ```typescript $df.col().arr.variance() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").arr.variance().alias("var_a")) shape: (2, 2) +-----------+-------+ | a | var_a | +-----------+-------+ | [1, 2, 3] | 1 | | [4, 5] | 0.5 | +-----------+-------+ ``` --- ## Namespace: $df.col.standardExpr ## Operation Computes the absolute value of the column values. ### Signature ```typescript $df.col().abs() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").abs().alias("abs_a")) shape: (3, 2) +---+-------+ | a | abs_a | +---+-------+ | 1 | 1 | | 2 | 2 | | 3 | 3 | +---+-------+ ``` --- ## Operation Adds a scalar value or another column expression. ### Signature ```typescript $df.col().add(val: number | bigint | IExpr | null) ``` ### Parameters - `val` (any): The number or column expression to add. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").add(10).alias("added")) shape: (3, 2) +---+-------+ | a | added | +---+-------+ | 1 | 11 | | 2 | 12 | | 3 | 13 | +---+-------+ ``` --- ## Operation Renames the output expression column key. ### Signature ```typescript $df.col().alias(name: string): this ``` ### Parameters - `name` (any): Name of the output column. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").alias("renamed_a")) shape: (3, 2) +---+-----------+ | a | renamed_a | +---+-----------+ | 1 | 1 | | 2 | 2 | | 3 | 3 | +---+-----------+ ``` --- ## Operation Aggregation: Returns true if all values in the group are truthy. ### Signature ```typescript $df.col().all() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [true, true, false, false], b: [true, false, true, false] }) >>> df shape: (4, 2) +-------+-------+ | a | b | +-------+-------+ | true | true | | true | false | | false | true | | false | false | +-------+-------+ >>> df.select($df.col("a").all().alias("all_true")) shape: (1, 1) +----------+ | all_true | +----------+ | false | +----------+ ``` --- ## Operation Aggregation: Checks if all values in the group are null. ### Signature ```typescript $df.col().allNull() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.select($df.col("a").allNull().alias("all_null")) shape: (1, 1) +----------+ | all_null | +----------+ | false | +----------+ ``` --- ## Operation Performs an element-wise logical AND operation between the column and another operand using Kleene 3-valued logic (true, false, null). In Kleene 3-valued logic: - `false` AND anything is `false`. - `true` AND `true` is `true`. - `true` AND `null` is `null` (unknown). - `null` AND `null` is `null` (unknown). ### Signature ```typescript $df.col().and(other: boolean | boolean[] | IExpr | null | undefined) ``` ### Parameters - `other` (any): The boolean column expression or literal value to compare. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [true, true, false, false], b: [true, false, true, false] }) >>> df shape: (4, 2) +-------+-------+ | a | b | +-------+-------+ | true | true | | true | false | | false | true | | false | false | +-------+-------+ >>> df.withColumns($df.col("a").and($df.col("b")).alias("and_res")) shape: (4, 3) +-------+-------+---------+ | a | b | and_res | +-------+-------+---------+ | true | true | true | | true | false | false | | false | false | false | | null | true | null | +-------+-------+---------+ ``` --- ## Operation Aggregation: Checks if any value in the group is truthy. ### Signature ```typescript $df.col().any() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [true, true, false, false], b: [true, false, true, false] }) >>> df shape: (4, 2) +-------+-------+ | a | b | +-------+-------+ | true | true | | true | false | | false | true | | false | false | +-------+-------+ >>> df.select($df.col("a").any().alias("any_true")) shape: (1, 1) +----------+ | any_true | +----------+ | true | +----------+ ``` --- ## Operation Aggregation: Checks if any value in the group is null. ### Signature ```typescript $df.col().anyNull() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.select($df.col("a").anyNull().alias("has_null")) shape: (1, 1) +----------+ | has_null | +----------+ | true | +----------+ ``` --- ## Operation Computes the mathematical arccosine (inverse cosine) of the column values. ### Signature ```typescript $df.col().arccos() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").arccos().alias("arccos_a")) shape: (3, 2) +---+----------+ | a | arccos_a | +---+----------+ | 1 | 0 | | 2 | null | | 3 | null | +---+----------+ ``` --- ## Operation Computes the hyperbolic arccosine of the column values. ### Signature ```typescript $df.col().arccosh() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").arccosh().alias("arccosh_a")) shape: (3, 2) +---+-----------+ | a | arccosh_a | +---+-----------+ | 1 | 0 | | 2 | 1.316958 | | 3 | 1.762747 | +---+-----------+ ``` --- ## Operation Computes the arcsine of the column values. ### Signature ```typescript $df.col().arcsin() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").arcsin().alias("arcsin_a")) shape: (3, 2) +---+----------+ | a | arcsin_a | +---+----------+ | 1 | 1.570796 | | 2 | null | | 3 | null | +---+----------+ ``` --- ## Operation Computes the hyperbolic arcsine of the column values. ### Signature ```typescript $df.col().arcsinh() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").arcsinh().alias("arcsinh_a")) shape: (3, 2) +---+-----------+ | a | arcsinh_a | +---+-----------+ | 1 | 0.881374 | | 2 | 1.443635 | | 3 | 1.818446 | +---+-----------+ ``` --- ## Operation Computes the arctangent of the column values. ### Signature ```typescript $df.col().arctan() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").arctan().alias("arctan_a")) shape: (3, 2) +---+----------+ | a | arctan_a | +---+----------+ | 1 | 0.785398 | | 2 | 1.107149 | | 3 | 1.249046 | +---+----------+ ``` --- ## Operation Computes the quadrant-aware arctangent of two values. ### Signature ```typescript $df.col().arctan2(val: number | bigint | IExpr | null) ``` ### Parameters - `val` (any): The x denominator number or column expression. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.withColumns($df.col("a").arctan2($df.col("b")).alias("arctan2_a")) shape: (3, 3) +---+----+-----------+ | a | b | arctan2_a | +---+----+-----------+ | 1 | 10 | 0.099669 | | 2 | 20 | 0.099669 | | 3 | 30 | 0.099669 | +---+----+-----------+ ``` --- ## Operation Computes the hyperbolic arctangent of the column values. ### Signature ```typescript $df.col().arctanh() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").arctanh().alias("arctanh_a")) shape: (3, 2) +---+-----------+ | a | arctanh_a | +---+-----------+ | 1 | null | | 2 | null | | 3 | null | +---+-----------+ ``` --- ## Operation Aggregation: Finds the index of the maximum value in the group. ### Signature ```typescript $df.col().argMax() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("val").argMax().alias("max_idx")) shape: (1, 1) +---------+ | max_idx | +---------+ | 2 | +---------+ ``` --- ## Operation Aggregation: Finds the index of the minimum value in the group. ### Signature ```typescript $df.col().argMin() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("val").argMin().alias("min_idx")) shape: (1, 1) +---------+ | min_idx | +---------+ | 0 | +---------+ ``` --- ## Operation Aggregation: Computes the arithmetic mean of the group. ### Signature ```typescript $df.col().avg() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").avg().alias("mean")) shape: (2, 2) +-------+------+ | group | mean | +-------+------+ | A | 15 | | B | 30 | +-------+------+ ``` --- ## Operation Checks if values fall inside lower and upper boundaries. ### Signature ```typescript $df.col().between( lower: ScalarArg | ArrayArg, upper: ScalarArg | ArrayArg, options: { closed?: "both" | "left" | "right" | "none" = "both" } = {} ) ``` ### Parameters - `lower` (any): The lower boundary value or expression. - `upper` (any): The upper boundary value or expression. - `[options]` (any): Boundary configuration options (see `BetweenOptions`). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.withColumns($df.col("a").between(1, 2).alias("in_range")) shape: (3, 3) +---+----+----------+ | a | b | in_range | +---+----+----------+ | 1 | 10 | true | | 2 | 20 | true | | 3 | 30 | false | +---+----+----------+ ``` --- ## Operation Aggregation: Computes bitwise AND across all elements in the group. ### Signature ```typescript $df.col().bitwiseAnd() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("a").bitwiseAnd().alias("res")) shape: (1, 1) +-----+ | res | +-----+ | 0 | +-----+ ``` --- ## Operation Aggregation: Computes bitwise OR across all elements in the group. ### Signature ```typescript $df.col().bitwiseOr() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("a").bitwiseOr().alias("res")) shape: (1, 1) +-----+ | res | +-----+ | 3 | +-----+ ``` --- ## Operation Aggregation: Computes bitwise XOR across all elements in the group. ### Signature ```typescript $df.col().bitwiseXor() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("a").bitwiseXor().alias("res")) shape: (1, 1) +-----+ | res | +-----+ | 0 | +-----+ ``` --- ## Operation Coerces the column data type to another type. ### Signature ```typescript $df.col().cast( dataType: Int8Type | Int16Type | Int32Type | Int64Type | UInt8Type | UInt16Type | UInt32Type | UInt64Type | Float32Type | Float64Type | DecimalType | BooleanType | Utf8Type | BinaryType | NullType | ObjectType | DateType | DatetimeType | TimeType | DurationType | ArrayType | StructType, options: { strict?: boolean = true } = {} ): this ``` ### Parameters - `dataType` (any): Registered target data type (e.g. `$df.DataType.Int32`, `$df.DataType.String`). - `[options]` (any): Type casting options (e.g. `{ strict: false }` to produce nulls instead of throwing on invalid values). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").cast($df.DataType.Float64).alias("float_a")) shape: (3, 2) +---+---------+ | a | float_a | +---+---------+ | 1 | 1.0 | | 2 | 2.0 | | 3 | 3.0 | +---+---------+ ``` --- ## Operation Computes the cube root of the column values. ### Signature ```typescript $df.col().cbrt() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").cbrt().alias("cbrt_a")) shape: (3, 2) +---+----------+ | a | cbrt_a | +---+----------+ | 1 | 1 | | 2 | 1.259921 | | 3 | 1.44225 | +---+----------+ ``` --- ## Operation Rounds column values up to the nearest integer. ### Signature ```typescript $df.col().ceil() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").ceil().alias("ceil_a")) shape: (3, 2) +---+--------+ | a | ceil_a | +---+--------+ | 1 | 1 | | 2 | 2 | | 3 | 3 | +---+--------+ ``` --- ## Operation Clamps column values between lower and upper numeric thresholds. ### Signature ```typescript $df.col().clip( lower: number | null = null, upper: number | null = null ) ``` ### Parameters - `lower` (any): The lower threshold value (default: null). - `upper` (any): The upper threshold value (default: null). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").clip(2, 3).alias("clipped")) shape: (3, 2) +---+---------+ | a | clipped | +---+---------+ | 1 | 2 | | 2 | 2 | | 3 | 3 | +---+---------+ ``` --- ## Operation Returns absolute value of expr with the sign of other. ### Signature ```typescript $df.col().copysign(val: number | bigint | IExpr | null) ``` ### Parameters - `val` (any): The sign source value or column expression. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.withColumns($df.col("a").copysign($df.col("b")).alias("signed")) shape: (3, 3) +---+----+--------+ | a | b | signed | +---+----+--------+ | 1 | 10 | 1 | | 2 | 20 | 2 | | 3 | 30 | 3 | +---+----+--------+ ``` --- ## Operation Aggregation: Computes the Pearson correlation coefficient between this column and another column expression or numeric array. Computes the sample Pearson product-moment correlation coefficient $r \in [-1, 1]$ using a single-pass, numerically stable Welford algorithm. Pairs containing `null`, `undefined`, or `NaN` are automatically dropped (pairwise deletion). Returns `null` if fewer than 2 valid pairs exist or if either column has zero variance. ### Signature ```typescript $df.col().corr(other: NumericArg | number[] | AnyTypedArray) ``` ### Parameters - `other` (NumericSeriesArg): The target column expression, numeric literal, or numeric array to correlate with. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.select($df.col("a").corr($df.col("b")).alias("correlation")) shape: (1, 1) +-------------+ | correlation | +-------------+ | 1 | +-------------+ ``` --- ## Operation Computes the cosine of the column values. ### Signature ```typescript $df.col().cos() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").cos().alias("cos_a")) shape: (3, 2) +---+-----------+ | a | cos_a | +---+-----------+ | 1 | 0.540302 | | 2 | -0.416147 | | 3 | -0.989992 | +---+-----------+ ``` --- ## Operation Computes the hyperbolic cosine of the column values. ### Signature ```typescript $df.col().cosh() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").cosh().alias("cosh_a")) shape: (3, 2) +---+-----------+ | a | cosh_a | +---+-----------+ | 1 | 1.543081 | | 2 | 3.762196 | | 3 | 10.067662 | +---+-----------+ ``` --- ## Operation Computes the cotangent of the column values. ### Signature ```typescript $df.col().cot() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").cot().alias("cot_a")) shape: (3, 2) +---+-----------+ | a | cot_a | +---+-----------+ | 1 | 0.642093 | | 2 | -0.457658 | | 3 | -7.015253 | +---+-----------+ ``` --- ## Operation Aggregation: Returns the count of records inside the group or column. ### Signature ```typescript $df.col().count( options: { includeNulls?: boolean = false } = {} ) ``` ### Parameters - `[options]` (CountOptions, default: {}): Configuration options for counting. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").count().alias("cnt")) shape: (2, 2) +-------+-----+ | group | cnt | +-------+-----+ | A | 2 | | B | 1 | +-------+-----+ ``` --- ## Operation Aggregation: Computes the sample covariance between this column and another column expression or numeric array. Computes sample covariance with $N - 1$ degrees of freedom using a single-pass, numerically stable Welford algorithm. Pairs containing `null`, `undefined`, or `NaN` are automatically dropped (pairwise deletion). Returns `null` if fewer than 2 valid pairs exist. ### Signature ```typescript $df.col().cov(other: NumericArg | number[] | AnyTypedArray) ``` ### Parameters - `other` (NumericSeriesArg): The target column expression, numeric literal, or numeric array to compute covariance with. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.select($df.col("a").cov($df.col("b")).alias("covariance")) shape: (1, 1) +------------+ | covariance | +------------+ | 10 | +------------+ ``` --- ## Operation Window: Computes cumulative count. ### Signature ```typescript $df.col().cumCount(reverse: boolean = false) ``` ### Parameters - `reverse` (any): Flag indicating whether to compute from reverse direction. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").cumCount().alias("c_count")) shape: (3, 2) +-----+---------+ | val | c_count | +-----+---------+ | 10 | 1 | | 20 | 2 | | 30 | 3 | +-----+---------+ ``` --- ## Operation Window: Computes cumulative maximum value. ### Signature ```typescript $df.col().cumMax(reverse: boolean = false) ``` ### Parameters - `reverse` (any): Flag indicating whether to compute in reverse direction. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").cumMax().alias("c_max")) shape: (3, 2) +-----+-------+ | val | c_max | +-----+-------+ | 10 | 10 | | 20 | 20 | | 30 | 30 | +-----+-------+ ``` --- ## Operation Window: Computes cumulative minimum value. ### Signature ```typescript $df.col().cumMin(reverse: boolean = false) ``` ### Parameters - `reverse` (any): Flag indicating whether to compute in reverse direction. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").cumMin().alias("c_min")) shape: (3, 2) +-----+-------+ | val | c_min | +-----+-------+ | 10 | 10 | | 20 | 10 | | 30 | 10 | +-----+-------+ ``` --- ## Operation Window: Computes cumulative product of values. ### Signature ```typescript $df.col().cumProd(reverse: boolean = false) ``` ### Parameters - `reverse` (any): Flag indicating whether to compute in reverse direction. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").cumProd().alias("c_prod")) shape: (4, 2) +---+--------+ | a | c_prod | +---+--------+ | 1 | 1 | | 2 | 2 | | 3 | 6 | | 4 | 24 | +---+--------+ ``` --- ## Operation Window: Computes cumulative sum of values. ### Signature ```typescript $df.col().cumSum(reverse: boolean = false) ``` ### Parameters - `reverse` (any): Flag indicating whether to compute in reverse direction. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").cumSum().alias("c_sum")) shape: (3, 2) +-----+-------+ | val | c_sum | +-----+-------+ | 10 | 10 | | 20 | 30 | | 30 | 60 | +-----+-------+ ``` --- ## Operation Converts angles from radians to degrees. ### Signature ```typescript $df.col().degrees() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").degrees().alias("deg")) shape: (3, 2) +---+------------+ | a | deg | +---+------------+ | 1 | 57.29578 | | 2 | 114.591559 | | 3 | 171.887339 | +---+------------+ ``` --- ## Operation Window: Computes dense rank (ranks without gaps) within group partition. ### Signature ```typescript $df.col().denseRank() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("score").denseRank().alias("dr")) shape: (2, 2) +-------+----+ | score | dr | +-------+----+ | 75 | 1 | | 95 | 2 | +-------+----+ ``` --- ## Operation Divides column values by a scalar or another column expression. ### Signature ```typescript $df.col().div(val: number | bigint | IExpr | null) ``` ### Parameters - `val` (any): The denominator value or column expression. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").div(2).alias("div_a")) shape: (3, 2) +---+-------+ | a | div_a | +---+-------+ | 1 | 0.5 | | 2 | 1 | | 3 | 1.5 | +---+-------+ ``` --- ## Operation Aggregation: Computes the dot product between this column and another column expression, numeric scalar, or array. Computes $\mathbf{x} \cdot \mathbf{y} = \sum_{i} x_i y_i$. Pairs containing `null`, `undefined`, or non-finite values (`NaN`, `Infinity`) are automatically dropped. Returns `null` if no valid pairs exist or if the DataFrame is empty. ### Signature ```typescript $df.col().dot(other: NumericArg | number[] | AnyTypedArray) ``` ### Parameters - `other` (NumericSeriesArg): The other column expression, numeric literal, or numeric array to compute the dot product with. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.select($df.col("a").dot($df.col("b")).alias("dot_product")) shape: (1, 1) +-------------+ | dot_product | +-------------+ | 32 | +-------------+ ``` --- ## Operation Aggregation: Computes the Shannon entropy of a column or group. ### Signature ```typescript $df.col().entropy( options: { base?: number = Math.E, normalize?: boolean = true } = { base: Math.E, normalize: true } ) ``` ### Parameters - `options` (any): Entropy options ({ base?: number, normalize?: boolean }, default base=Math.E, normalize=true). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("a").entropy().alias("h")) shape: (1, 1) +----------+ | h | +----------+ | 1.386294 | +----------+ ``` --- ## Operation Boolean comparison: Returns true if column values match the specified value exactly under Kleene logic. Evaluates strict equality (`===`) between this column and `val`. Under standard three-valued (Kleene) logic, comparing any value to `null` or `undefined` yields `null` (unknown). In IEEE-754 arithmetic, `NaN === NaN` yields `false`. ### Signature ```typescript $df.col().eq(val: ScalarArg | ArrayArg) ``` ### Parameters - `val` (ComparisonArg): The value, literal array, or column expression to compare against. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").eq(2).alias("is_two")) shape: (3, 2) +---+--------+ | a | is_two | +---+--------+ | 1 | false | | 2 | true | | 3 | false | +---+--------+ ``` --- ## Operation Equivalence comparison that treats null and missing values as equal to each other. Returns `true` if both values are identical, or if both values are nullish (`null` or `undefined`). Returns `false` if one value is nullish while the other is non-null. Non-null values follow standard equality. ### Signature ```typescript $df.col().eqMissing(val: ScalarArg | ArrayArg) ``` ### Parameters - `val` (ComparisonArg): The value, literal array, or column expression to compare against. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.withColumns($df.col("a").eqMissing(null).alias("is_missing")) shape: (3, 2) +------+------------+ | a | is_missing | +------+------------+ | 1 | false | | null | true | | 3 | false | +------+------------+ ``` --- ## Operation Window: Computes exponentially weighted moving kurtosis. ### Signature ```typescript $df.col().ewmKurt( options: { adjust?: boolean = true, alpha?: number, bias?: boolean = false, by?: string | IExpr, com?: number, fisher?: boolean = true, halfLife?: number | string, ignoreNulls?: boolean = false, minSamples?: number = 1, span?: number } ) ``` ### Parameters - `options` (any): Configuration specifying decay rate (`alpha`, `span`, `com`, `halfLife`), `adjust`, `minSamples`, `ignoreNulls`, and optional `by`. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").ewmKurt({ alpha: 0.5 }).alias("ewm_kurt")) shape: (3, 2) +---+----------+ | a | ewm_kurt | +---+----------+ | 1 | null | | 2 | -1 | | 3 | 1.052409 | +---+----------+ ``` --- ## Operation Window: Computes exponentially weighted moving average (mean). ### Signature ```typescript $df.col().ewmMean( options: { adjust?: boolean = true, alpha?: number, by?: string | IExpr, com?: number, halfLife?: number | string, ignoreNulls?: boolean = false, minSamples?: number = 1, span?: number } ) ``` ### Parameters - `options` (any): Configuration specifying decay rate (`alpha`, `span`, `com`, `halfLife`), `adjust`, `minSamples`, `ignoreNulls`, and optional `by`. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").ewmMean({ alpha: 0.5 }).alias("ewm_mean")) shape: (3, 2) +---+----------+ | a | ewm_mean | +---+----------+ | 1 | 1 | | 2 | 1.666667 | | 3 | 2.428571 | +---+----------+ ``` --- ## Operation Window: Computes exponentially weighted moving skewness. ### Signature ```typescript $df.col().ewmSkew( options: { adjust?: boolean = true, alpha?: number, bias?: boolean = false, by?: string | IExpr, com?: number, halfLife?: number | string, ignoreNulls?: boolean = false, minSamples?: number = 1, span?: number } ) ``` ### Parameters - `options` (any): Configuration specifying decay rate (`alpha`, `span`, `com`, `halfLife`), `adjust`, `minSamples`, `ignoreNulls`, optional `bias`, and optional `by`. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").ewmSkew({ alpha: 0.5 }).alias("ewm_skew")) shape: (3, 2) +---+-----------+ | a | ewm_skew | +---+-----------+ | 1 | null | | 2 | -0.816497 | | 3 | -1.125865 | +---+-----------+ ``` --- ## Operation Window: Computes exponentially weighted moving standard deviation. ### Signature ```typescript $df.col().ewmStd( options: { adjust?: boolean = true, alpha?: number, by?: string | IExpr, com?: number, halfLife?: number | string, ignoreNulls?: boolean = false, minSamples?: number = 1, span?: number } ) ``` ### Parameters - `options` (any): Configuration specifying decay rate (`alpha`, `span`, `com`, `halfLife`), `adjust`, `minSamples`, `ignoreNulls`, and optional `by`. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").ewmStd({ alpha: 0.5 }).alias("ewm_std")) shape: (3, 2) +---+----------+ | a | ewm_std | +---+----------+ | 1 | null | | 2 | 0.471405 | | 3 | 0.728431 | +---+----------+ ``` --- ## Operation Window: Computes exponentially weighted moving sum. ### Signature ```typescript $df.col().ewmSum( options: { alpha?: number, by?: string | IExpr, com?: number, halfLife?: number | string, ignoreNulls?: boolean = false, minSamples?: number = 1, span?: number } ) ``` ### Parameters - `options` (any): Configuration specifying decay rate (`alpha`, `span`, `com`, `halfLife`), `minSamples`, `ignoreNulls`, and optional `by`. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").ewmSum({ alpha: 0.5 }).alias("ewm_sum")) shape: (3, 2) +---+---------+ | a | ewm_sum | +---+---------+ | 1 | 1 | | 2 | 2.5 | | 3 | 4.25 | +---+---------+ ``` --- ## Operation Window: Computes exponentially weighted moving variance. ### Signature ```typescript $df.col().ewmVar( options: { adjust?: boolean = true, alpha?: number, by?: string | IExpr, com?: number, halfLife?: number | string, ignoreNulls?: boolean = false, minSamples?: number = 1, span?: number } ) ``` ### Parameters - `options` (any): Configuration specifying decay rate (`alpha`, `span`, `com`, `halfLife`), `adjust`, `minSamples`, `ignoreNulls`, and optional `by`. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").ewmVar({ alpha: 0.5 }).alias("ewm_var")) shape: (3, 2) +---+----------+ | a | ewm_var | +---+----------+ | 1 | null | | 2 | 0.222222 | | 3 | 0.530612 | +---+----------+ ``` --- ## Operation Computes natural exponent (e^x) of the column values. ### Signature ```typescript $df.col().exp() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").exp().alias("exp_a")) shape: (3, 2) +---+-----------+ | a | exp_a | +---+-----------+ | 1 | 2.718282 | | 2 | 7.389056 | | 3 | 20.085537 | +---+-----------+ ``` --- ## Operation Computes e^x - 1 for each element in the column. ### Signature ```typescript $df.col().expm1() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").expm1().alias("expm1_a")) shape: (3, 2) +---+-----------+ | a | expm1_a | +---+-----------+ | 1 | 1.718282 | | 2 | 6.389056 | | 3 | 19.085537 | +---+-----------+ ``` --- ## Operation Replaces targeted values ("null", "nan", or "all") with a specified value or strategy. ### Signature ```typescript $df.col().fill( target: "null" | "nan" | "all" | ScalarArg, options: { limit?: number, strategy?: "forward" | "backward" | "min" | "max" | "mean" | "zero" | "one", value?: IExpr | ValidScalarTypes } = {} ): this ``` ### Parameters - `target` (FillTarget): The target value type to replace: "null", "nan", or "all". - `[options]` (FillOptions, default: {}): Configuration options specifying replacement value, strategy, and optional limit. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.withColumns($df.col("a").fill("null", { value: 0 }).alias("filled")) shape: (3, 2) +------+--------+ | a | filled | +------+--------+ | 1 | 1 | | null | 0 | | 3 | 3 | +------+--------+ ``` --- ## Operation Replaces NaN values with a specified value or strategy. ### Signature ```typescript $df.col().fillNan( options: { limit?: number, strategy?: "forward" | "backward" | "min" | "max" | "mean" | "zero" | "one", value?: IExpr | ValidScalarTypes } = {} ): this ``` ### Parameters - `[options]` (FillNullOptions, default: {}): Configuration options specifying replacement value, strategy, and optional limit. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").fillNan({ value: 0 }).alias("clean")) shape: (3, 2) +---+-------+ | a | clean | +---+-------+ | 1 | 1 | | 2 | 2 | | 3 | 3 | +---+-------+ ``` --- ## Operation Replaces null, undefined, or missing values with a specified value or strategy. ### Signature ```typescript $df.col().fillNull( options: { limit?: number, strategy?: "forward" | "backward" | "min" | "max" | "mean" | "zero" | "one", value?: IExpr | ValidScalarTypes } = {} ): this ``` ### Parameters - `options` (any): Configuration options including fill value, strategy ("forward", "backward", "zero", "one", "mean", "min", "max"), and optional limit. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.withColumns($df.col("a").fillNull({ value: 0 }).alias("filled")) shape: (3, 2) +------+--------+ | a | filled | +------+--------+ | 1 | 1 | | null | 0 | | 3 | 3 | +------+--------+ ``` --- ## Operation Filters elements of the column expression where the predicate evaluates to truthy. ### Signature ```typescript $df.col().filter(predicate: IExpr): this ``` ### Parameters - `predicate` (any): Boolean column expression used to filter values. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("a").filter($df.col("a").gt(1)).alias("filtered")) shape: (2, 1) +----------+ | filtered | +----------+ | 2 | | 3 | +----------+ ``` --- ## Operation Aggregation: Finds the first value in the group. ### Signature ```typescript $df.col().first() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").first().alias("first_val")) shape: (2, 2) +-------+-----------+ | group | first_val | +-------+-----------+ | A | 10 | | B | 30 | +-------+-----------+ ``` --- ## Operation Rounds column values down to the nearest integer. ### Signature ```typescript $df.col().floor() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").floor().alias("floor_a")) shape: (3, 2) +---+---------+ | a | floor_a | +---+---------+ | 1 | 1 | | 2 | 2 | | 3 | 3 | +---+---------+ ``` --- ## Operation Performs integer division floor(x / y) on column values. ### Signature ```typescript $df.col().floordiv(val: number | bigint | IExpr | null) ``` ### Parameters - `val` (any): The divisor value or column expression. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").floordiv(2).alias("fdiv")) shape: (3, 2) +---+------+ | a | fdiv | +---+------+ | 1 | 0 | | 2 | 1 | | 3 | 1 | +---+------+ ``` --- ## Operation Boolean comparison: Returns true if greater than or equal to argument. ### Signature ```typescript $df.col().ge(val: ScalarArg | ArrayArg) ``` ### Parameters - `val` (any): The value or column expression to compare against. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").ge(2).alias("ge_two")) shape: (3, 2) +---+--------+ | a | ge_two | +---+--------+ | 1 | false | | 2 | true | | 3 | true | +---+--------+ ``` --- ## Operation Boolean comparison: Returns true if column value is greater than argument. ### Signature ```typescript $df.col().gt(val: ScalarArg | ArrayArg) ``` ### Parameters - `val` (any): The value or column expression to compare against. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").gt(2).alias("gt_two")) shape: (3, 2) +---+--------+ | a | gt_two | +---+--------+ | 1 | false | | 2 | false | | 3 | true | +---+--------+ ``` --- ## Operation Aggregation: Checks if any value in the group is null. ### Signature ```typescript $df.col().hasNulls() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.select($df.col("a").hasNulls().alias("has_nulls")) shape: (1, 1) +-----------+ | has_nulls | +-----------+ | true | +-----------+ ``` --- ## Operation Computes the hypotenuse sqrt(x^2 + y^2) of two values. ### Signature ```typescript $df.col().hypot(val: number | bigint | IExpr | null) ``` ### Parameters - `val` (any): The other numeric value or column expression. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.withColumns($df.col("a").hypot($df.col("b")).alias("hypot_a")) shape: (3, 3) +---+----+-----------+ | a | b | hypot_a | +---+----+-----------+ | 1 | 10 | 10.049876 | | 2 | 20 | 20.099751 | | 3 | 30 | 30.149627 | +---+----+-----------+ ``` --- ## Operation Aggregation: Combines all values in the group into a single array/list cell. ### Signature ```typescript $df.col().implode() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").implode().alias("list_val")) shape: (2, 2) +-------+----------+ | group | list_val | +-------+----------+ | A | [10, 20] | | B | [30] | +-------+----------+ ``` --- ## Operation Determines if floating-point values are approximately equal within tolerances. ### Signature ```typescript $df.col().isClose( other: any, options: { absTol?: number = 1e-8, nansEqual?: boolean = false, relTol?: number = 1e-8 } = {} ) ``` ### Parameters - `other` (any): The value or expression to compare against. - `options` (any): Tolerance values absolute (absTol) and relative (relTol), and NaN options. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").isClose(1.0).alias("close")) shape: (3, 2) +---+-------+ | a | close | +---+-------+ | 1 | true | | 2 | false | | 3 | false | +---+-------+ ``` --- ## Operation Checks if values occur more than once in the column. ### Signature ```typescript $df.col().isDuplicated() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").isDuplicated().alias("dup")) shape: (3, 2) +---+-------+ | a | dup | +---+-------+ | 1 | false | | 2 | false | | 3 | false | +---+-------+ ``` --- ## Operation Checks if values are finite numbers (not NaN or Infinity). ### Signature ```typescript $df.col().isFinite() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").isFinite().alias("finite")) shape: (3, 2) +---+--------+ | a | finite | +---+--------+ | 1 | true | | 2 | true | | 3 | true | +---+--------+ ``` --- ## Operation Checks if column values are members of a specified array or list. ### Signature ```typescript $df.col().isIn(values: ScalarArg | ArrayArg) ``` ### Parameters - `values` (any): An array of candidate values or a single value to match against. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").isIn(["apple", "banana"]).alias("in_list")) shape: (3, 2) +----------+---------+ | s | in_list | +----------+---------+ | "apple" | true | | "banana" | true | | "cherry" | false | +----------+---------+ ``` --- ## Operation Checks if values are positive or negative Infinity. ### Signature ```typescript $df.col().isInfinite() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").isInfinite().alias("inf")) shape: (3, 2) +---+-------+ | a | inf | +---+-------+ | 1 | false | | 2 | false | | 3 | false | +---+-------+ ``` --- ## Operation Checks if values are NaN. ### Signature ```typescript $df.col().isNan() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").isNan().alias("nan")) shape: (3, 2) +---+-------+ | a | nan | +---+-------+ | 1 | false | | 2 | false | | 3 | false | +---+-------+ ``` --- ## Operation Checks if column values match the N-th distinct value by positive or negative index position. ### Signature ```typescript $df.col().isNDistinct( index: number, options: { nullOnOob?: boolean = true } = {} ) ``` ### Parameters - `index` (any): The 0-based or negative index position into the ordered distinct values (e.g. 0 for first distinct, -1 for last distinct). - `nullOnOob` (any): If true, returns null if index is out of bounds (default: true). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.withColumns($df.col("a").isNDistinct(0).alias("is_first")) shape: (3, 3) +---+----+----------+ | a | b | is_first | +---+----+----------+ | 1 | 10 | true | | 2 | 20 | false | | 3 | 30 | false | +---+----+----------+ ``` --- ## Operation Checks if values are not NaN. ### Signature ```typescript $df.col().isNotNan() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").isNotNan().alias("not_nan")) shape: (3, 2) +---+---------+ | a | not_nan | +---+---------+ | 1 | true | | 2 | true | | 3 | true | +---+---------+ ``` --- ## Operation Checks if column values are non-null and valid (not null, undefined, or missing). ### Signature ```typescript $df.col().isNotNull() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.withColumns($df.col("a").isNotNull().alias("valid")) shape: (3, 2) +------+-------+ | a | valid | +------+-------+ | 1 | true | | null | false | | 3 | true | +------+-------+ ``` --- ## Operation Checks if column values are null, undefined, or missing. ### Signature ```typescript $df.col().isNull() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.withColumns($df.col("a").isNull().alias("missing")) shape: (3, 2) +------+---------+ | a | missing | +------+---------+ | 1 | false | | null | true | | 3 | false | +------+---------+ ``` --- ## Operation Checks if values occur exactly once in the column. ### Signature ```typescript $df.col().isUnique() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").isUnique().alias("uniq")) shape: (3, 2) +---+------+ | a | uniq | +---+------+ | 1 | true | | 2 | true | | 3 | true | +---+------+ ``` --- ## Operation Aggregation: Computes the kurtosis (peakedness/tailedness) of a numeric column. ### Signature ```typescript $df.col().kurtosis( options: { bias?: boolean = true, fisher?: boolean = true } = {} ) ``` ### Parameters - `options` (any): Kurtosis calculation options ({ fisher?: boolean, bias?: boolean }, default fisher=true, bias=true). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("a").kurtosis().alias("kurt")) shape: (1, 1) +-------+ | kurt | +-------+ | -1.36 | +-------+ ``` --- ## Operation Window: Shifts values down by offset, filling missing slots with default value. ### Signature ```typescript $df.col().lag( offset: number = 1, options: { fillValue?: any = null } = {} ) ``` ### Parameters - `offset` (any): Number of rows to shift down (default 1). - `options` (any): Shift options configuring fallback fillValue (default null). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").lag(1, { fillValue: 0 }).alias("prev")) shape: (3, 2) +-----+------+ | val | prev | +-----+------+ | 10 | 0 | | 20 | 10 | | 30 | 20 | +-----+------+ ``` --- ## Operation Aggregation: Finds the last value in the group. ### Signature ```typescript $df.col().last() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").last().alias("last_val")) shape: (2, 2) +-------+----------+ | group | last_val | +-------+----------+ | A | 20 | | B | 30 | +-------+----------+ ``` --- ## Operation Boolean comparison: Returns true if less than or equal to argument. ### Signature ```typescript $df.col().le(val: ScalarArg | ArrayArg) ``` ### Parameters - `val` (any): The value or column expression to compare against. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").le(2).alias("le_two")) shape: (3, 2) +---+--------+ | a | le_two | +---+--------+ | 1 | true | | 2 | true | | 3 | false | +---+--------+ ``` --- ## Operation Window: Shifts values up by offset, filling missing slots with default value. ### Signature ```typescript $df.col().lead( offset: number = 1, options: { fillValue?: any = null } = {} ) ``` ### Parameters - `offset` (any): Number of rows to shift up (default 1). - `options` (any): Shift options configuring fallback fillValue (default null). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").lead(1, { fillValue: 0 }).alias("next")) shape: (3, 2) +-----+------+ | val | next | +-----+------+ | 10 | 20 | | 20 | 30 | | 30 | 0 | +-----+------+ ``` --- ## Operation Computes the logarithm of positive values with a specified base. ### Signature ```typescript $df.col().log(base: number = Math.E) ``` ### Parameters - `base` (any): The base of the logarithm (default: Math.E). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").log(10).alias("log_a")) shape: (3, 2) +---+----------+ | a | log_a | +---+----------+ | 1 | 0 | | 2 | 0.30103 | | 3 | 0.477121 | +---+----------+ ``` --- ## Operation Computes natural logarithm of 1 + x. ### Signature ```typescript $df.col().log1p() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").log1p().alias("log1p_a")) shape: (3, 2) +---+----------+ | a | log1p_a | +---+----------+ | 1 | 0.693147 | | 2 | 1.098612 | | 3 | 1.386294 | +---+----------+ ``` --- ## Operation Boolean comparison: Returns true if less than argument. ### Signature ```typescript $df.col().lt(val: ScalarArg | ArrayArg) ``` ### Parameters - `val` (any): The value or column expression to compare against. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").lt(2).alias("lt_two")) shape: (3, 2) +---+--------+ | a | lt_two | +---+--------+ | 1 | true | | 2 | false | | 3 | false | +---+--------+ ``` --- ## Operation Aggregation: Finds the maximum value in the group. ### Signature ```typescript $df.col().max() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").max().alias("max_val")) shape: (2, 2) +-------+---------+ | group | max_val | +-------+---------+ | A | 20 | | B | 30 | +-------+---------+ ``` --- ## Operation Aggregation: Finds the value in this column corresponding to the maximum value in the `by` expression. ### Signature ```typescript $df.col().maxBy(by: ScalarArg | ArrayArg) ``` ### Parameters - `by` (any): Column or expression to order by. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.select($df.col("group").maxBy($df.col("val")).alias("top_group")) shape: (1, 1) +-----------+ | top_group | +-----------+ | B | +-----------+ ``` --- ## Operation Aggregation: Computes the arithmetic mean of elements in the group. ### Signature ```typescript $df.col().mean() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").mean().alias("mean_val")) shape: (2, 2) +-------+----------+ | group | mean_val | +-------+----------+ | A | 15 | | B | 30 | +-------+----------+ ``` --- ## Operation Aggregation: Computes the 50th percentile median. ### Signature ```typescript $df.col().median() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").median().alias("med")) shape: (2, 2) +-------+-----+ | group | med | +-------+-----+ | A | 15 | | B | 30 | +-------+-----+ ``` --- ## Operation Aggregation: Finds the minimum value in the group. ### Signature ```typescript $df.col().min() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").min().alias("min_val")) shape: (2, 2) +-------+---------+ | group | min_val | +-------+---------+ | A | 10 | | B | 30 | +-------+---------+ ``` --- ## Operation Aggregation: Finds the value in this column corresponding to the minimum value in the `by` expression. ### Signature ```typescript $df.col().minBy(by: ScalarArg | ArrayArg) ``` ### Parameters - `by` (any): Column or expression to order by. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.select($df.col("group").minBy($df.col("val")).alias("lowest_group")) shape: (1, 1) +--------------+ | lowest_group | +--------------+ | A | +--------------+ ``` --- ## Operation Computes modulo remainder (x % y) of column values. ### Signature ```typescript $df.col().mod(val: number | bigint | IExpr | null) ``` ### Parameters - `val` (any): The divisor value or column expression. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").mod(2).alias("mod_a")) shape: (3, 2) +---+-------+ | a | mod_a | +---+-------+ | 1 | 1 | | 2 | 0 | | 3 | 1 | +---+-------+ ``` --- ## Operation Aggregation: Finds the statistical mode (most frequent value). ### Signature ```typescript $df.col().mode() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.select($df.col("group").mode().alias("mode_group")) shape: (1, 1) +------------+ | mode_group | +------------+ | ["A"] | +------------+ ``` --- ## Operation Multiplies column values by a scalar or another column expression. ### Signature ```typescript $df.col().mul(val: number | bigint | IExpr | null) ``` ### Parameters - `val` (any): The multiplier value or column expression. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").mul(5).alias("multiplied")) shape: (3, 2) +---+------------+ | a | multiplied | +---+------------+ | 1 | 5 | | 2 | 10 | | 3 | 15 | +---+------------+ ``` --- ## Operation Aggregation: Finds the maximum value in the group, taking NaN values into account (NaN propagates). ### Signature ```typescript $df.col().nanMax() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("val").nanMax().alias("nan_max_val")) shape: (1, 1) +-------------+ | nan_max_val | +-------------+ | 30 | +-------------+ ``` --- ## Operation Aggregation: Finds the minimum value in the group, taking NaN values into account (NaN propagates). ### Signature ```typescript $df.col().nanMin() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("val").nanMin().alias("nan_min_val")) shape: (1, 1) +-------------+ | nan_min_val | +-------------+ | 10 | +-------------+ ``` --- ## Operation Boolean comparison: Returns true if values do not match. ### Signature ```typescript $df.col().ne(val: ScalarArg | ArrayArg) ``` ### Parameters - `val` (any): The value or column expression to compare against. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").ne(2).alias("not_two")) shape: (3, 2) +---+---------+ | a | not_two | +---+---------+ | 1 | true | | 2 | false | | 3 | true | +---+---------+ ``` --- ## Operation Negates column values (-x). ### Signature ```typescript $df.col().negate() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").negate().alias("negated")) shape: (3, 2) +---+---------+ | a | negated | +---+---------+ | 1 | -1 | | 2 | -2 | | 3 | -3 | +---+---------+ ``` --- ## Operation Difference check that treats null values as equal to each other. ### Signature ```typescript $df.col().neMissing(val: ScalarArg | ArrayArg) ``` ### Parameters - `val` (any): The value or column expression to compare against. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.withColumns($df.col("a").neMissing(null).alias("not_missing")) shape: (3, 2) +------+-------------+ | a | not_missing | +------+-------------+ | 1 | true | | null | false | | 3 | true | +------+-------------+ ``` --- ## Operation Logical negation. ### Signature ```typescript $df.col().not() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [true, true, false, false], b: [true, false, true, false] }) >>> df shape: (4, 2) +-------+-------+ | a | b | +-------+-------+ | true | true | | true | false | | false | true | | false | false | +-------+-------+ >>> df.withColumns($df.col("a").not().alias("not_a")) shape: (4, 3) +-------+-------+-------+ | a | b | not_a | +-------+-------+-------+ | true | true | false | | true | false | false | | false | false | true | | null | true | null | +-------+-------+-------+ ``` --- ## Operation Checks if values are not elements of a specific array or set list. ### Signature ```typescript $df.col().notIn(values: ScalarArg | ArrayArg) ``` ### Parameters - `values` (any): An array of candidate values or a single value to match against. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").notIn(["apple", "banana"]).alias("not_in")) shape: (3, 2) +----------+--------+ | s | not_in | +----------+--------+ | "apple" | false | | "banana" | false | | "cherry" | true | +----------+--------+ ``` --- ## Operation Aggregation: Counts the number of null or missing records. ### Signature ```typescript $df.col().nullCount() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.select($df.col("a").nullCount().alias("nulls")) shape: (1, 1) +-------+ | nulls | +-------+ | 1 | +-------+ ``` --- ## Operation Aggregation: Computes number of unique elements. ### Signature ```typescript $df.col().nUnique( options: { keySelector?: (val: any) => any, strict?: boolean = false } = {} ) ``` ### Parameters - `options` (any): Uniqueness options. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.select($df.col("group").nUnique().alias("unique_cnt")) shape: (1, 1) +------------+ | unique_cnt | +------------+ | 2 | +------------+ ``` --- ## Operation Logical OR check supporting Kleene logic. ### Signature ```typescript $df.col().or(other: boolean | boolean[] | IExpr | null | undefined) ``` ### Parameters - `other` (any): The other boolean column expression or literal value to compare. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [true, true, false, false], b: [true, false, true, false] }) >>> df shape: (4, 2) +-------+-------+ | a | b | +-------+-------+ | true | true | | true | false | | false | true | | false | false | +-------+-------+ >>> df.withColumns($df.col("a").or($df.col("b")).alias("or_res")) shape: (4, 3) +-------+-------+--------+ | a | b | or_res | +-------+-------+--------+ | true | true | true | | true | false | true | | false | false | false | | null | true | true | +-------+-------+--------+ ``` --- ## Operation Executes a window aggregation partitioned by column keys. ### Signature ```typescript $df.col().over(columns: string | IExpr | (string | IExpr)[]) ``` ### Parameters - `columns` (any): Column expression or array of columns to partition by. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.withColumns($df.col("val").sum().over("group").alias("cat_sum")) shape: (3, 3) +-------+-----+---------+ | group | val | cat_sum | +-------+-----+---------+ | A | 10 | 30 | | A | 20 | 30 | | B | 30 | 30 | +-------+-----+---------+ ``` --- ## Operation Raises column values to the specified power. ### Signature ```typescript $df.col().pow(val: number | bigint | IExpr | null) ``` ### Parameters - `val` (any): The exponent power value or column expression. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").pow(2).alias("pow_a")) shape: (3, 2) +---+-------+ | a | pow_a | +---+-------+ | 1 | 1 | | 2 | 4 | | 3 | 9 | +---+-------+ ``` --- ## Operation Aggregation: Computes the product of all elements in the group. ### Signature ```typescript $df.col().product() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").product().alias("p")) shape: (2, 2) +-------+-----+ | group | p | +-------+-----+ | A | 200 | | B | 30 | +-------+-----+ ``` --- ## Operation Aggregation: Computes the specific quantile values (0.0 to 1.0). ### Signature ```typescript $df.col().quantile(q: number) ``` ### Parameters - `q` (any): The quantile parameter value between 0.0 and 1.0. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("a").quantile(0.75).alias("q75")) shape: (1, 1) +------+ | q75 | +------+ | 3.25 | +------+ ``` --- ## Operation Converts angles from degrees to radians. ### Signature ```typescript $df.col().radians() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").radians().alias("rad")) shape: (3, 2) +---+----------+ | a | rad | +---+----------+ | 1 | 0.017453 | | 2 | 0.034907 | | 3 | 0.05236 | +---+----------+ ``` --- ## Operation Fills sequence with pseudo-random generated floats or integers. ### Signature ```typescript $df.col().rand( seed?: number, options: { integer?: boolean = false, max?: number = 1, min?: number = 0 } = {} ) ``` ### Parameters - `seed` (any): Optional seed to initialize the pseudo-random generator. - `options` (any): Config options including min, max, and integer flag. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").rand(42, { min: 1, max: 10, integer: true }).alias("random")) shape: (3, 2) +---+--------+ | a | random | +---+--------+ | 1 | 7 | | 2 | 8 | | 3 | 6 | +---+--------+ ``` --- ## Operation Window: Computes rank within group partition. ### Signature ```typescript $df.col().rank( options: { dense?: boolean = false } = {} ) ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("score").rank().alias("rank")) shape: (2, 2) +-------+------+ | score | rank | +-------+------+ | 75 | 1 | | 95 | 2 | +-------+------+ ``` --- ## Operation Reverses the order of values in the column. ### Signature ```typescript $df.col().reverse(): this ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").reverse().alias("reversed")) shape: (3, 2) +---+----------+ | a | reversed | +---+----------+ | 1 | 3 | | 2 | 2 | | 3 | 1 | +---+----------+ ``` --- ## Operation Window: Computes a rolling window reduction using a ColumnExpression or a custom callback function. ### Signature ```typescript $df.col().rolling( optionsOrWindowSize: { windowSize: number }, exprOrFn: IExpr | ((vals: any[]) => any) ) ``` ### Parameters - `optionsOrWindowSize` (any): Window row count or RollingOptions configuration. - `exprOrFn` (any): ColumnExpression to evaluate over each window slice, or a custom reducer function. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").rolling(2, $df.col("val").sum()).alias("r_sum")) shape: (3, 2) +-----+-------+ | val | r_sum | +-----+-------+ | 10 | 10 | | 20 | 30 | | 30 | 50 | +-----+-------+ ``` --- ## Operation Window: Computes rolling window maximum value. ### Signature ```typescript $df.col().rollingMax(windowSize: number) ``` ### Parameters - `windowSize` (any): Size of rolling window. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").rollingMax(2).alias("r_max")) shape: (3, 2) +-----+-------+ | val | r_max | +-----+-------+ | 10 | 10 | | 20 | 20 | | 30 | 30 | +-----+-------+ ``` --- ## Operation Window: Computes rolling window mean average. ### Signature ```typescript $df.col().rollingMean(windowSize: number) ``` ### Parameters - `windowSize` (any): Size of rolling window. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").rollingMean(2).alias("r_mean")) shape: (3, 2) +-----+--------+ | val | r_mean | +-----+--------+ | 10 | 10 | | 20 | 15 | | 30 | 25 | +-----+--------+ ``` --- ## Operation Window: Computes rolling window median value. ### Signature ```typescript $df.col().rollingMedian(windowSize: number) ``` ### Parameters - `windowSize` (any): Size of rolling window. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").rollingMedian(2).alias("r_med")) shape: (3, 2) +-----+-------+ | val | r_med | +-----+-------+ | 10 | 10 | | 20 | 15 | | 30 | 25 | +-----+-------+ ``` --- ## Operation Window: Computes rolling window minimum value. ### Signature ```typescript $df.col().rollingMin(windowSize: number) ``` ### Parameters - `windowSize` (any): Size of rolling window. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").rollingMin(2).alias("r_min")) shape: (3, 2) +-----+-------+ | val | r_min | +-----+-------+ | 10 | 10 | | 20 | 10 | | 30 | 20 | +-----+-------+ ``` --- ## Operation Window: Computes rolling window quantile value. ### Signature ```typescript $df.col().rollingQuantile( quantile: number, windowSize: number ) ``` ### Parameters - `quantile` (any): Quantile boundary between 0.0 and 1.0. - `windowSize` (any): Size of rolling window. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").rollingQuantile(0.5, 2).alias("r_quant")) shape: (3, 2) +-----+---------+ | val | r_quant | +-----+---------+ | 10 | 10 | | 20 | 15 | | 30 | 25 | +-----+---------+ ``` --- ## Operation Window: Computes rolling window rank. ### Signature ```typescript $df.col().rollingRank(windowSize: number) ``` ### Parameters - `windowSize` (any): Size of rolling window. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").rollingRank(2).alias("r_rank")) shape: (3, 2) +-----+--------+ | val | r_rank | +-----+--------+ | 10 | 1 | | 20 | 2 | | 30 | 2 | +-----+--------+ ``` --- ## Operation Window: Computes rolling window standard deviation. ### Signature ```typescript $df.col().rollingStd(windowSize: number) ``` ### Parameters - `windowSize` (any): Size of rolling window. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").rollingStd(2).alias("r_std")) shape: (3, 2) +-----+--------+ | val | r_std | +-----+--------+ | 10 | 0 | | 20 | 7.071 | | 30 | 7.071 | +-----+--------+ ``` --- ## Operation Window: Computes rolling window sum. ### Signature ```typescript $df.col().rollingSum(windowSize: number) ``` ### Parameters - `windowSize` (any): Size of rolling window. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("val").rollingSum(2).alias("r_sum")) shape: (3, 2) +-----+-------+ | val | r_sum | +-----+-------+ | 10 | 10 | | 20 | 30 | | 30 | 50 | +-----+-------+ ``` --- ## Operation Rounds values to a specific scale of decimal digits. ### Signature ```typescript $df.col().round(decimals: number = 0) ``` ### Parameters - `decimals` (any): Number of decimal places to round to (default: 0). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").round(1).alias("rounded")) shape: (3, 2) +---+---------+ | a | rounded | +---+---------+ | 1 | 1 | | 2 | 2 | | 3 | 3 | +---+---------+ ``` --- ## Operation Rounds values to a specific number of significant figures. ### Signature ```typescript $df.col().roundSigFigs(sigFigs: number) ``` ### Parameters - `sigFigs` (any): Number of significant figures. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").roundSigFigs(2).alias("sig_figs")) shape: (3, 2) +---+----------+ | a | sig_figs | +---+----------+ | 1 | 1 | | 2 | 2 | | 3 | 3 | +---+----------+ ``` --- ## Operation Window: Computes 1-indexed row number count within group partitions. ### Signature ```typescript $df.col().rowNumber() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.withColumns($df.col("val").rowNumber().over("group").alias("rn")) shape: (3, 3) +-------+-----+----+ | group | val | rn | +-------+-----+----+ | A | 10 | 1 | | A | 20 | 2 | | B | 30 | 1 | +-------+-----+----+ ``` --- ## Operation Shifts values by the given number of rows, filling newly introduced slots with null. Positive offsets shift values down (lag); negative offsets shift values up (lead). Supports windowing and partition grouping via `.over(...)`. ### Signature ```typescript $df.col().shift( n: number = 1, options: { fillValue?: any = null } = {} ) ``` ### Parameters - `n` (any): Number of rows to shift (positive for down, negative for up). Default 1. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").shift(1).alias("shifted")) shape: (3, 2) +---+---------+ | a | shifted | +---+---------+ | 1 | null | | 2 | 1 | | 3 | 2 | +---+---------+ ``` --- ## Operation Returns sign indicator of column values (-1, 0, or 1). ### Signature ```typescript $df.col().sign() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").sign().alias("sign_a")) shape: (3, 2) +---+--------+ | a | sign_a | +---+--------+ | 1 | 1 | | 2 | 1 | | 3 | 1 | +---+--------+ ``` --- ## Operation Computes the sine of the column values. ### Signature ```typescript $df.col().sin() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").sin().alias("sin_a")) shape: (3, 2) +---+----------+ | a | sin_a | +---+----------+ | 1 | 0.841471 | | 2 | 0.909297 | | 3 | 0.14112 | +---+----------+ ``` --- ## Operation Computes the hyperbolic sine of the column values. ### Signature ```typescript $df.col().sinh() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").sinh().alias("sinh_a")) shape: (3, 2) +---+-----------+ | a | sinh_a | +---+-----------+ | 1 | 1.175201 | | 2 | 3.62686 | | 3 | 10.017875 | +---+-----------+ ``` --- ## Operation Aggregation: Computes the sample skewness as the Fisher-Pearson coefficient of skewness. ### Signature ```typescript $df.col().skew( options: { bias?: boolean = true } = {} ) ``` ### Parameters - `options` (any): Skew calculation options ({ bias?: boolean }, default bias=true). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("a").skew().alias("skewness")) shape: (1, 1) +----------+ | skewness | +----------+ | 0 | +----------+ ``` --- ## Operation Aggregation: Computes the Spearman rank correlation coefficient. ### Signature ```typescript $df.col().spearmanCorr(other: NumericArg | number[] | AnyTypedArray) ``` ### Parameters - `other` (any): The other column expression to correlate with. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.select($df.col("a").spearmanCorr($df.col("b")).alias("spearman")) shape: (1, 1) +----------+ | spearman | +----------+ | 1 | +----------+ ``` --- ## Operation Computes the square root of non-negative column values. ### Signature ```typescript $df.col().sqrt() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").sqrt().alias("sqrt_a")) shape: (3, 2) +---+----------+ | a | sqrt_a | +---+----------+ | 1 | 1 | | 2 | 1.414214 | | 3 | 1.732051 | +---+----------+ ``` --- ## Operation Aggregation: Computes sample standard deviation. ### Signature ```typescript $df.col().std() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("val").std().alias("std_dev")) shape: (1, 1) +---------+ | std_dev | +---------+ | 10 | +---------+ ``` --- ## Operation Subtracts a scalar or another column expression. ### Signature ```typescript $df.col().sub(val: number | bigint | IExpr | null) ``` ### Parameters - `val` (any): The value or column expression to subtract. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").sub(5).alias("sub_a")) shape: (3, 2) +---+-------+ | a | sub_a | +---+-------+ | 1 | -4 | | 2 | -3 | | 3 | -2 | +---+-------+ ``` --- ## Operation Aggregation: Computes the sum of elements in the group. ### Signature ```typescript $df.col().sum() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").sum().alias("total")) shape: (2, 2) +-------+-------+ | group | total | +-------+-------+ | A | 30 | | B | 30 | +-------+-------+ ``` --- ## Operation Computes the tangent of the column values. ### Signature ```typescript $df.col().tan() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").tan().alias("tan_a")) shape: (3, 2) +---+-----------+ | a | tan_a | +---+-----------+ | 1 | 1.557408 | | 2 | -2.18504 | | 3 | -0.142547 | +---+-----------+ ``` --- ## Operation Computes the hyperbolic tangent of the column values. ### Signature ```typescript $df.col().tanh() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").tanh().alias("tanh_a")) shape: (3, 2) +---+----------+ | a | tanh_a | +---+----------+ | 1 | 0.761594 | | 2 | 0.964028 | | 3 | 0.995055 | +---+----------+ ``` --- ## Operation Truncates fractional digits of column values. ### Signature ```typescript $df.col().trunc() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.withColumns($df.col("a").trunc().alias("trunc_a")) shape: (3, 2) +---+---------+ | a | trunc_a | +---+---------+ | 1 | 1 | | 2 | 2 | | 3 | 3 | +---+---------+ ``` --- ## Operation Aggregation: Computes sample variance. ### Signature ```typescript $df.col().variance() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.col("val").variance().alias("v")) shape: (1, 1) +-----+ | v | +-----+ | 100 | +-----+ ``` --- ## Operation Aggregation: Computes weighted average. ### Signature ```typescript $df.col().wAvg(weights: NumericArg | number[] | AnyTypedArray) ``` ### Parameters - `weights` (any): The weight values or column expression. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.select($df.col("a").wAvg($df.col("b")).alias("w_mean")) shape: (1, 1) +----------+ | w_mean | +----------+ | 2.333333 | +----------+ ``` --- ## Operation Logical XOR check. ### Signature ```typescript $df.col().xor(other: boolean | boolean[] | IExpr | null | undefined) ``` ### Parameters - `other` (any): The other boolean column expression or literal value to compare. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [true, true, false, false], b: [true, false, true, false] }) >>> df shape: (4, 2) +-------+-------+ | a | b | +-------+-------+ | true | true | | true | false | | false | true | | false | false | +-------+-------+ >>> df.withColumns($df.col("a").xor($df.col("b")).alias("xor_res")) shape: (4, 3) +-------+-------+---------+ | a | b | xor_res | +-------+-------+---------+ | true | true | false | | true | false | true | | false | true | true | | false | false | false | +-------+-------+---------+ ``` --- ## Namespace: $df.col.stringExpr ## Operation Concatenates string elements with another string value or expression. ### Signature ```typescript $df.col().str.concat(other: string | IExpr) ``` ### Parameters - `other` (any): The string value or column expression to concatenate. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.concat("!").alias("exclaimed")) shape: (3, 2) +----------+-----------+ | s | exclaimed | +----------+-----------+ | "apple" | apple! | | "banana" | banana! | | "cherry" | cherry! | +----------+-----------+ ``` --- ## Operation Checks if a string contains the search substring pattern (supports Regex). ### Signature ```typescript $df.col().str.contains(pattern: string | RegExp) ``` ### Parameters - `pattern` (any): The search substring or regular expression pattern. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("email").str.contains("@example.com").alias("is_example")) shape: (2, 2) +------------------+------------+ | email | is_example | +------------------+------------+ | user@example.com | true | | admin@test.org | false | +------------------+------------+ ``` --- ## Operation Checks if a string contains any of the search patterns. ### Signature ```typescript $df.col().str.containsAny(patterns: (string | RegExp)[]) ``` ### Parameters - `patterns` (any): Array of substring or regular expression search patterns. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("email").str.containsAny(["@example.com", "@test.org"]).alias("is_target")) shape: (2, 2) +------------------+-----------+ | email | is_target | +------------------+-----------+ | user@example.com | true | | admin@test.org | true | +------------------+-----------+ ``` --- ## Operation Counts occurrences of a substring or regular expression match in each string element. ### Signature ```typescript $df.col().str.countMatches( pattern: string | RegExp, options: { literal?: boolean = false } = {} ) ``` ### Parameters - `pattern` (any): Search substring or regular expression. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.countMatches("a").alias("a_count")) shape: (3, 2) +----------+---------+ | s | a_count | +----------+---------+ | "apple" | 1 | | "banana" | 3 | | "cherry" | 0 | +----------+---------+ ``` --- ## Operation Decodes hex or base64 encoded string column values into string. ### Signature ```typescript $df.col().str.decode( options: { encoding: "hex" | "base64", strict?: boolean = true } ) ``` ### Parameters - `options` (any): Object containing encoding ("hex" | "base64") and optional strict flag ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.encode({ encoding: "hex" }).str.decode({ encoding: "hex" }).alias("decoded")) shape: (3, 2) +----------+---------+ | s | decoded | +----------+---------+ | "apple" | apple | | "banana" | banana | | "cherry" | cherry | +----------+---------+ ``` --- ## Operation Decodes Uniform Resource Identifier (URI) components. ### Signature ```typescript $df.col().str.decodeUriComponent() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.encodeUriComponent().str.decodeUriComponent().alias("decoded")) shape: (2, 2) +-------------+-------------+ | s | decoded | +-------------+-------------+ | " hello " | " hello " | | " world " | " world " | +-------------+-------------+ ``` --- ## Operation Encodes string column values into hex or base64. ### Signature ```typescript $df.col().str.encode( options: { encoding: "hex" | "base64" } ) ``` ### Parameters - `options` (any): Object containing encoding ("hex" | "base64") ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.encode({ encoding: "hex" }).alias("encoded")) shape: (3, 2) +----------+----------------+ | s | encoded | +----------+----------------+ | "apple" | 6170706c65 | | "banana" | 62616e616e61 | | "cherry" | 636865727279 | +----------+----------------+ ``` --- ## Operation Encodes Uniform Resource Identifier (URI) components. ### Signature ```typescript $df.col().str.encodeUriComponent() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.encodeUriComponent().alias("encoded")) shape: (2, 2) +-------------+-------------------+ | s | encoded | +-------------+-------------------+ | " hello " | "%20%20hello%20%20" | | " world " | "%20%20world%20%20" | +-------------+-------------------+ ``` --- ## Operation Checks if string ends with a suffix. ### Signature ```typescript $df.col().str.endsWith(suffix: string) ``` ### Parameters - `suffix` (any): The suffix substring. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("email").str.endsWith(".org").alias("is_org")) shape: (2, 2) +------------------+--------+ | email | is_org | +------------------+--------+ | user@example.com | false | | admin@test.org | true | +------------------+--------+ ``` --- ## Operation Escapes special regular expression characters in string elements. ### Signature ```typescript $df.col().str.escapeRegex( options: { mode?: "tc39" | "nonAlphanumericAscii" = "tc39" } = {} ) ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.escapeRegex().alias("escaped")) shape: (3, 2) +----------+---------+ | s | escaped | +----------+---------+ | "apple" | apple | | "banana" | banana | | "cherry" | cherry | +----------+---------+ ``` --- ## Operation Splits strings into lists of single characters. ### Signature ```typescript $df.col().str.explode() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.explode().alias("chars")) shape: (3, 2) +----------+-------------------------------------+ | s | chars | +----------+-------------------------------------+ | "apple" | ["a", "p", "p", "l", "e"] | | "banana" | ["b", "a", "n", "a", "n", "a"] | | "cherry" | ["c", "h", "e", "r", "r", "y"] | +----------+-------------------------------------+ ``` --- ## Operation Extracts a captured group from the first regex match. ### Signature ```typescript $df.col().str.extract( pattern: string | RegExp, options?: { asciiCaseInsensitive?: boolean = false, global?: boolean = false, groupIndex?: number | string = 1 } ) ``` ### Parameters - `pattern` (any): The regex pattern containing capture groups. - `options` (any): Options object. Use `groupIndex` to select the group (default 1). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("email").str.extract(/@(\w+)/).alias("domain")) shape: (2, 2) +------------------+---------+ | email | domain | +------------------+---------+ | user@example.com | example | | admin@test.org | test | +------------------+---------+ ``` --- ## Operation Extracts all occurrences matching a regular expression pattern. ### Signature ```typescript $df.col().str.extractAll( pattern: string | RegExp, options?: { asciiCaseInsensitive?: boolean = false, global?: boolean = false, groupIndex?: number | string = 1 } ) ``` ### Parameters - `pattern` (any): Search pattern (string or RegExp). - `options` (any): Options object. Use `groupIndex` to select the group (default 0). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.extractAll(/[aeiou]/).alias("vowels")) shape: (3, 2) +----------+-----------------+ | s | vowels | +----------+-----------------+ | "apple" | ["a", "e"] | | "banana" | ["a", "a", "a"] | | "cherry" | ["e"] | +----------+-----------------+ ``` --- ## Operation Extracts all captured groups from the first regex match into a structured object (struct). ### Signature ```typescript $df.col().str.extractGroups( pattern: string | RegExp, options: { asciiCaseInsensitive?: boolean = false, global?: boolean = false, groupIndex?: number | string = 1 } = {} ) ``` ### Parameters - `pattern` (any): Search pattern containing capture groups. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("email").str.extractGroups(/(?\w+)@(?\w+)/).alias("parsed")) shape: (2, 2) +------------------+------------------------------------+ | email | parsed | +------------------+------------------------------------+ | user@example.com | { user: "user", domain: "example" }| | admin@test.org | { user: "admin", domain: "test" } | +------------------+------------------------------------+ ``` --- ## Operation Extracts the first regex match for each pattern in a list of patterns. ### Signature ```typescript $df.col().str.extractMany( patterns: (string | RegExp)[], options: { asciiCaseInsensitive?: boolean = false, global?: boolean = false, groupIndex?: number | string = 0, leftmost?: boolean = false, overlapping?: boolean = false } = {} ) ``` ### Parameters - `patterns` (any): Array of regular expression patterns or strings. - `options` (any): Named options object ({ asciiCaseInsensitive, overlapping }). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.extractMany([/app/, /ban/, /che/]).alias("extracted")) shape: (3, 2) +----------+-------------+ | s | extracted | +----------+-------------+ | "apple" | ["app"] | | "banana" | ["ban"] | | "cherry" | ["che"] | +----------+-------------+ ``` --- ## Operation Return the byte offset of the first substring matching a pattern. Returns null if pattern is not found. ### Signature ```typescript $df.col().str.find( value: string | RegExp, options: { asciiCaseInsensitive?: boolean = false, global?: boolean = false, groupIndex?: number | string = 0, literal?: boolean = false, mode?: "tc39" | "nonAlphanumericAscii" = "tc39" } = {} ) ``` ### Parameters - `value` (any): Search string or regular expression. - `options` (any): Configuration options ({ literal, asciiCaseInsensitive }). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.find("a").alias("pos")) shape: (3, 2) +----------+------+ | s | pos | +----------+------+ | "apple" | 0 | | "banana" | 1 | | "cherry" | null | +----------+------+ ``` --- ## Operation Return the starting byte offset of each match for multiple patterns. ### Signature ```typescript $df.col().str.findMany( patterns: (string | RegExp)[], options: { asciiCaseInsensitive?: boolean = false, global?: boolean = false, groupIndex?: number | string = 0, leftmost?: boolean = false, literal?: boolean = false, mode?: "tc39" | "nonAlphanumericAscii" = "tc39", overlapping?: boolean = false } = {} ) ``` ### Parameters - `patterns` (any): Array of regular expressions or literal search strings. - `options` (any): Configuration options ({ literal, asciiCaseInsensitive, overlapping, leftmost }). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.findMany(["a", "e"]).alias("positions")) shape: (3, 2) +----------+-----------+ | s | positions | +----------+-----------+ | "apple" | [0, 4] | | "banana" | [1] | | "cherry" | [2] | +----------+-----------+ ``` --- ## Operation Extracts the first n characters of each string element. ### Signature ```typescript $df.col().str.head(n: number = 1) ``` ### Parameters - `n` (any): Number of characters to extract from the start of the string (default 1). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.head(3).alias("prefix")) shape: (3, 2) +----------+--------+ | s | prefix | +----------+--------+ | "apple" | app | | "banana" | ban | | "cherry" | che | +----------+--------+ ``` --- ## Operation Joins a list of string elements into a single string using a delimiter. Accepts `JoinArrayOptions` (`{ ignoreNulls, nullValue, prefix, suffix, limit, truncationMarker, valueFormatter }`). ### Signature ```typescript $df.col().str.join( delimiter: string = "", options: { ignoreNulls?: boolean = false, limit?: number, nullValue?: string = "", prefix?: string = "", suffix?: string = "", truncationMarker?: string = "...", valueFormatter?: (val: any, index: number) => string } = {} ) ``` ### Parameters - `delimiter` (any): The string delimiter to join elements with. - `options` (any): Formatting configuration options (`JoinArrayOptions`). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.withColumns($df.col("a").str.join("-").alias("joined")) shape: (2, 2) +------------+--------+ | a | joined | +------------+--------+ | ["a", "b"] | a-b | | ["c"] | c | +------------+--------+ ``` --- ## Operation Decodes JSON string elements into parsed objects or arrays. Reuses safeJsonParse utility. ### Signature ```typescript $df.col().str.jsonDecode( options: { allowPrimitives?: boolean = false, fallback?: unknown, format?: "json" | "ndjson" = "json", guard?: ((value: unknown) => value is unknown) | ((value: unknown) => boolean), ndjson?: { maxLines?: number, skipInvalidLines?: boolean = false, skipLines?: number = 0 }, onError?: (err: unknown) => void, reviver?: Parameters[1], trimBeforeParse?: boolean = false } = {} ) ``` ### Parameters - `options` (any): Configuration options for parsing (`SafeJsonParseOptions`). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.trim().str.jsonDecode().alias("parsed")) shape: (2, 2) +-------------+---------+ | s | parsed | +-------------+---------+ | " hello " | "hello" | | " world " | "world" | +-------------+---------+ ``` --- ## Operation Extracts fields or array elements from JSON strings using JSONPath syntax. ### Signature ```typescript $df.col().str.jsonPathMatch(jsonPath: string) ``` ### Parameters - `jsonPath` (any): The JSONPath expression (e.g. `"$.store.book[0].title"` or `"$.a.b"`). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.trim().str.jsonPathMatch("$").alias("val")) shape: (2, 2) +-------------+---------+ | s | val | +-------------+---------+ | " hello " | "hello" | | " world " | "world" | +-------------+---------+ ``` --- ## Operation Returns string length in UTF-16 code units. Alias for lenChars. ### Signature ```typescript $df.col().str.len() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.len().alias("length")) shape: (3, 2) +----------+--------+ | s | length | +----------+--------+ | "apple" | 5 | | "banana" | 6 | | "cherry" | 6 | +----------+--------+ ``` --- ## Operation Returns string length in UTF-8 encoded bytes. ### Signature ```typescript $df.col().str.lenBytes() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.lenBytes().alias("bytes")) shape: (3, 2) +----------+-------+ | s | bytes | +----------+-------+ | "apple" | 5 | | "banana" | 6 | | "cherry" | 6 | +----------+-------+ ``` --- ## Operation Returns string length in character count. ### Signature ```typescript $df.col().str.lenChars() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.lenChars().alias("length")) shape: (3, 2) +----------+--------+ | s | length | +----------+--------+ | "apple" | 5 | | "banana" | 6 | | "cherry" | 6 | +----------+--------+ ``` --- ## Operation Converts strings to lowercase. ### Signature ```typescript $df.col().str.lower() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.lower().alias("lowered")) shape: (3, 2) +-------------+-----------+ | s | lowered | +-------------+-----------+ | "HELLO" | hello | | "World" | world | | "df-script" | df-script | +-------------+-----------+ ``` --- ## Operation Pads start of strings to specified width. ### Signature ```typescript $df.col().str.lpad( width: number, fill: string = " " ) ``` ### Parameters - `width` (any): Minimum resulting string length. - `fill` (any): Character sequence used for padding. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.lpad(8, "_").alias("padded")) shape: (3, 2) +----------+----------+ | s | padded | +----------+----------+ | "apple" | ___apple | | "banana" | __banana | | "cherry" | __cherry | +----------+----------+ ``` --- ## Operation Normalizes Unicode strings using standard normalization forms (NFC, NFD, NFKC, NFKD). ### Signature ```typescript $df.col().str.normalize(form: "NFC" | "NFD" | "NFKC" | "NFKD" = "NFC") ``` ### Parameters - `form` (any): The Unicode normalization form to apply ("NFC", "NFD", "NFKC", or "NFKD"). Default is "NFC". ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.normalize("NFC").alias("normalized")) shape: (3, 2) +-------------+------------+ | s | normalized | +-------------+------------+ | "HELLO" | HELLO | | "World" | World | | "df-script" | df-script | +-------------+------------+ ``` --- ## Operation Pads end of strings to specified width. Alias for rpad. ### Signature ```typescript $df.col().str.padEnd( width: number, fill: string = " " ) ``` ### Parameters - `width` (any): Target string length. - `fill` (any): Character sequence used for padding. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.padEnd(8, "_").alias("padded")) shape: (3, 2) +----------+----------+ | s | padded | +----------+----------+ | "apple" | apple___ | | "banana" | banana__ | | "cherry" | cherry__ | +----------+----------+ ``` --- ## Operation Pads start of strings to specified width. Alias for lpad. ### Signature ```typescript $df.col().str.padStart( width: number, fill: string = " " ) ``` ### Parameters - `width` (any): Target string length. - `fill` (any): Character sequence used for padding. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.padStart(8, "_").alias("padded")) shape: (3, 2) +----------+----------+ | s | padded | +----------+----------+ | "apple" | ___apple | | "banana" | __banana | | "cherry" | __cherry | +----------+----------+ ``` --- ## Operation Replaces the first occurrence matching a string pattern. ### Signature ```typescript $df.col().str.replace( pattern: string | RegExp, replacement: string | StringReplacerFn, options?: { asciiCaseInsensitive?: boolean = false, global?: boolean = false, literal?: boolean = false, mode?: "tc39" | "nonAlphanumericAscii" = "tc39", n?: number = 1 } ) ``` ### Parameters - `pattern` (any): The search pattern string or regular expression. - `replacement` (any): The string value or match replacement function. - `options` (any): Optional replace options (literal, asciiCaseInsensitive, n). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("email").str.replace("example", "test").alias("updated")) shape: (2, 2) +------------------+---------------+ | email | updated | +------------------+---------------+ | user@example.com | user@test.com | | admin@test.org | admin@test.org| +------------------+---------------+ ``` --- ## Operation Replaces all occurrences matching a string pattern or global regular expression. ### Signature ```typescript $df.col().str.replaceAll( pattern: string | RegExp, replacement: string | StringReplacerFn, options: { asciiCaseInsensitive?: boolean = false, global?: boolean = false, literal?: boolean = false, mode?: "tc39" | "nonAlphanumericAscii" = "tc39" } = {} ) ``` ### Parameters - `pattern` (any): The search pattern string or regular expression. - `replacement` (any): The replacement value. - `options` (any): Optional replace options (literal, asciiCaseInsensitive). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.replaceAll("a", "@").alias("replaced")) shape: (3, 2) +----------+----------+ | s | replaced | +----------+----------+ | "apple" | @pple | | "banana" | b@n@n@ | | "cherry" | cherry | +----------+----------+ ``` --- ## Operation Replaces multiple string patterns simultaneously or sequentially with their respective replacements. Matches Polars `.str.replaceMany()` behavior, accepting pattern/replacement arrays or a pattern-to-replacement map dictionary. ### Signature ```typescript $df.col().str.replaceMany( patterns: RegexPatternSeriesArg | Record, replacements?: (string | StringReplacerFn)[], options?: { asciiCaseInsensitive?: boolean = false, global?: boolean = false, groupIndex?: number | string = 0, leftmost?: boolean = false, literal?: boolean = false, mode?: "tc39" | "nonAlphanumericAscii" = "tc39", overlapping?: boolean = false } ) ``` ### Parameters - `patterns` (any): Array of patterns or an object mapping target patterns to replacements. - `replacements` (any): Array of replacement strings/callbacks (when patterns is an array). - `options` (any): Configuration options ({ literal, asciiCaseInsensitive, mode }). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.replaceMany(["apple", "banana"], ["1", "2"]).alias("res")) shape: (3, 2) +----------+--------+ | s | res | +----------+--------+ | "apple" | 1 | | "banana" | 2 | | "cherry" | cherry | +----------+--------+ ``` --- ## Operation Reverses characters in each string element. ### Signature ```typescript $df.col().str.reverse() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.reverse().alias("rev")) shape: (3, 2) +----------+--------+ | s | rev | +----------+--------+ | "apple" | elppa | | "banana" | ananab | | "cherry" | yrrehc | +----------+--------+ ``` --- ## Operation Pads end of strings to specified width. ### Signature ```typescript $df.col().str.rpad( width: number, fill: string = " " ) ``` ### Parameters - `width` (any): Minimum resulting string length. - `fill` (any): Character sequence used for padding. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.rpad(8, "_").alias("padded")) shape: (3, 2) +----------+----------+ | s | padded | +----------+----------+ | "apple" | apple___ | | "banana" | banana__ | | "cherry" | cherry__ | +----------+----------+ ``` --- ## Operation Extracts a substring slice using start offset and length. ### Signature ```typescript $df.col().str.slice( offset: number, length?: number ) ``` ### Parameters - `offset` (any): Starting position index. - `length` (any): Number of characters to include. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.slice(0, 3).alias("sub")) shape: (3, 2) +----------+-----+ | s | sub | +----------+-----+ | "apple" | app | | "banana" | ban | | "cherry" | che | +----------+-----+ ``` --- ## Operation Splits strings into lists by delimiter with optional limit and exact padding. ### Signature ```typescript $df.col().str.split( delimiter: string, options?: { asciiCaseInsensitive?: boolean = false, exact?: boolean = false, global?: boolean = false, inclusive?: boolean = false, limit?: number, literal?: boolean = true, mode?: "tc39" | "nonAlphanumericAscii" = "tc39", strict?: boolean = false } ) ``` ### Parameters - `delimiter` (any): Substring delimiter. - `options` (any): Options for controlling limit and exact padding. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("email").str.split("@").alias("parts")) shape: (2, 2) +------------------+------------------------+ | email | parts | +------------------+------------------------+ | user@example.com | ["user", "example.com"]| | admin@test.org | ["admin", "test.org"] | +------------------+------------------------+ ``` --- ## Operation Checks if string starts with a prefix. ### Signature ```typescript $df.col().str.startsWith(prefix: string) ``` ### Parameters - `prefix` (any): The prefix substring. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.startsWith("a").alias("starts_a")) shape: (3, 2) +----------+----------+ | s | starts_a | +----------+----------+ | "apple" | true | | "banana" | false | | "cherry" | false | +----------+----------+ ``` --- ## Operation Strips matching characters from start and end of string. ### Signature ```typescript $df.col().str.stripChars( characters?: string | RegExp, options?: { maxMatchesEnd?: number | null, maxMatchesStart?: number | null, maxScanEnd?: number | null, maxScanStart?: number | null, mode?: "both" | "start" | "end" = "both", returnStringOnNull?: boolean = false, stringOptions?: { caseInsensitive?: boolean = false, literal?: boolean = false }, trimFirst?: boolean = false } ) ``` ### Parameters - `characters` (any): Characters or regex pattern to strip. - `options` (any): Configuration options for strip operation. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.stripChars().alias("stripped")) shape: (2, 2) +-------------+----------+ | s | stripped | +-------------+----------+ | " hello " | hello | | " world " | world | +-------------+----------+ ``` --- ## Operation Strips matching characters from end of string. ### Signature ```typescript $df.col().str.stripCharsEnd( characters?: string | RegExp, options?: { maxMatchesEnd?: number | null, maxMatchesStart?: number | null, maxScanEnd?: number | null, maxScanStart?: number | null, mode?: "both" | "start" | "end" = "both", returnStringOnNull?: boolean = false, stringOptions?: { caseInsensitive?: boolean = false, literal?: boolean = false }, trimFirst?: boolean = false } ) ``` ### Parameters - `characters` (any): Characters or regex pattern to strip. - `options` (any): Configuration options. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.stripCharsEnd().alias("stripped")) shape: (2, 2) +-------------+----------+ | s | stripped | +-------------+----------+ | " hello " | " hello" | | " world " | " world" | +-------------+----------+ ``` --- ## Operation Strips matching characters from start of string. ### Signature ```typescript $df.col().str.stripCharsStart( characters?: string | RegExp, options?: { maxMatchesEnd?: number | null, maxMatchesStart?: number | null, maxScanEnd?: number | null, maxScanStart?: number | null, mode?: "both" | "start" | "end" = "both", returnStringOnNull?: boolean = false, stringOptions?: { caseInsensitive?: boolean = false, literal?: boolean = false }, trimFirst?: boolean = false } ) ``` ### Parameters - `characters` (any): Characters or regex pattern to strip. - `options` (any): Configuration options. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.stripCharsStart().alias("stripped")) shape: (2, 2) +-------------+----------+ | s | stripped | +-------------+----------+ | " hello " | "hello " | | " world " | "world " | +-------------+----------+ ``` --- ## Operation Strips matching prefix substring from start of string. ### Signature ```typescript $df.col().str.stripPrefix(prefix: string) ``` ### Parameters - `prefix` (any): Prefix substring to remove. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.stripPrefix("df-").alias("stripped")) shape: (3, 2) +-------------+----------+ | s | stripped | +-------------+----------+ | "HELLO" | HELLO | | "World" | World | | "df-script" | script | +-------------+----------+ ``` --- ## Operation Strips matching suffix substring from end of string. ### Signature ```typescript $df.col().str.stripSuffix(suffix: string) ``` ### Parameters - `suffix` (any): Suffix substring to remove. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("email").str.stripSuffix(".com").alias("stripped")) shape: (2, 2) +------------------+----------------+ | email | stripped | +------------------+----------------+ | user@example.com | user@example | | admin@test.org | admin@test.org | +------------------+----------------+ ``` --- ## Operation Parses date/time string into Datetime. ### Signature ```typescript $df.col().str.strptime( options: { defaultTimeZone?: string = "UTC", format: string, strict?: boolean = true } ) ``` ### Parameters - `options` (any): Parsing configuration options. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").str.strptime({ format: "%Y-%m-%d" }).alias("parsed")) shape: (1, 2) +------------+--------------------------+ | d | parsed | +------------+--------------------------+ | 2026-05-20 | 2026-05-20T00:00:00.000Z | +------------+--------------------------+ ``` --- ## Operation Extracts the last n characters of each string element. ### Signature ```typescript $df.col().str.tail(n: number = 1) ``` ### Parameters - `n` (any): Number of characters to extract from the end of the string (default 1). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.tail(3).alias("suffix")) shape: (3, 2) +----------+--------+ | s | suffix | +----------+--------+ | "apple" | ple | | "banana" | ana | | "cherry" | rry | +----------+--------+ ``` --- ## Operation Converts string casing to camelCase. ### Signature ```typescript $df.col().str.toCamelCase() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.toCamelCase().alias("camel")) shape: (3, 2) +-------------+-----------+ | s | camel | +-------------+-----------+ | "HELLO" | hello | | "World" | world | | "df-script" | dfScript | +-------------+-----------+ ``` --- ## Operation Parses string into Date object. ### Signature ```typescript $df.col().str.toDate() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").str.toDate().alias("date")) shape: (1, 2) +------------+--------------------------+ | d | date | +------------+--------------------------+ | 2026-05-20 | 2026-05-20T00:00:00.000Z | +------------+--------------------------+ ``` --- ## Operation Parses string into Datetime value. ### Signature ```typescript $df.col().str.toDatetime() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").str.toDatetime().alias("dt")) shape: (1, 2) +------------+--------------------------+ | d | dt | +------------+--------------------------+ | 2026-05-20 | 2026-05-20T00:00:00.000Z | +------------+--------------------------+ ``` --- ## Operation Converts string into numeric decimal representation. ### Signature ```typescript $df.col().str.toDecimal( precision?: number, scale?: number ) ``` ### Parameters - `precision` (any): Optional precision limit. - `scale` (any): Optional scale limit. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.len().str.toDecimal().alias("num")) shape: (3, 2) +----------+-----+ | s | num | +----------+-----+ | "apple" | 5 | | "banana" | 6 | | "cherry" | 6 | +----------+-----+ ``` --- ## Operation Parses string into integer number. ### Signature ```typescript $df.col().str.toInteger() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.len().str.toInteger().alias("num")) shape: (3, 2) +----------+-----+ | s | num | +----------+-----+ | "apple" | 5 | | "banana" | 6 | | "cherry" | 6 | +----------+-----+ ``` --- ## Operation Converts string casing to kebab-case. ### Signature ```typescript $df.col().str.toKebabCase() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.toKebabCase().alias("kebab")) shape: (3, 2) +-------------+-----------+ | s | kebab | +-------------+-----------+ | "HELLO" | hello | | "World" | world | | "df-script" | df-script | +-------------+-----------+ ``` --- ## Operation Converts all string elements in the column to lowercase. ### Signature ```typescript $df.col().str.toLowerCase() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.toLowerCase().alias("lower_name")) shape: (3, 2) +-------------+------------+ | s | lower_name | +-------------+------------+ | "HELLO" | hello | | "World" | world | | "df-script" | df-script | +-------------+------------+ ``` --- ## Operation Converts string casing to PascalCase. ### Signature ```typescript $df.col().str.toPascalCase() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.toPascalCase().alias("pascal")) shape: (3, 2) +-------------+-----------+ | s | pascal | +-------------+-----------+ | "HELLO" | Hello | | "World" | World | | "df-script" | DfScript | +-------------+-----------+ ``` --- ## Operation Converts string casing to snake_case. ### Signature ```typescript $df.col().str.toSnakeCase() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.toSnakeCase().alias("snake")) shape: (3, 2) +-------------+-----------+ | s | snake | +-------------+-----------+ | "HELLO" | hello | | "World" | world | | "df-script" | df_script | +-------------+-----------+ ``` --- ## Operation Parses string into time component representation. ### Signature ```typescript $df.col().str.toTime() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.toTime().alias("time")) shape: (3, 2) +----------+------+ | s | time | +----------+------+ | "apple" | null | | "banana" | null | | "cherry" | null | +----------+------+ ``` --- ## Operation Converts string casing to Title Case. ### Signature ```typescript $df.col().str.toTitleCase() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.toTitleCase().alias("title")) shape: (3, 2) +-------------+-----------+ | s | title | +-------------+-----------+ | "HELLO" | Hello | | "World" | World | | "df-script" | Df Script | +-------------+-----------+ ``` --- ## Operation Converts all string elements in the column to uppercase. ### Signature ```typescript $df.col().str.toUpperCase() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.toUpperCase().alias("upper")) shape: (3, 2) +-------------+-----------+ | s | upper | +-------------+-----------+ | "HELLO" | HELLO | | "World" | WORLD | | "df-script" | DF-SCRIPT | +-------------+-----------+ ``` --- ## Operation Trims leading and trailing whitespace characters from each string element. ### Signature ```typescript $df.col().str.trim() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.trim().alias("clean")) shape: (2, 2) +-------------+-------+ | s | clean | +-------------+-------+ | " hello " | hello | | " world " | world | +-------------+-------+ ``` --- ## Operation Trims trailing whitespace characters from each string element. ### Signature ```typescript $df.col().str.trimEnd() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.trimEnd().alias("clean")) shape: (2, 2) +-------------+----------+ | s | clean | +-------------+----------+ | " hello " | " hello" | | " world " | " world" | +-------------+----------+ ``` --- ## Operation Trims leading whitespace characters from each string element. ### Signature ```typescript $df.col().str.trimStart() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.trimStart().alias("clean")) shape: (2, 2) +-------------+----------+ | s | clean | +-------------+----------+ | " hello " | "hello "| | " world " | "world "| +-------------+----------+ ``` --- ## Operation Converts string to uppercase. ### Signature ```typescript $df.col().str.upper() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.upper().alias("upper")) shape: (3, 2) +-------------+-----------+ | s | upper | +-------------+-----------+ | "HELLO" | HELLO | | "World" | WORLD | | "df-script" | DF-SCRIPT | +-------------+-----------+ ``` --- ## Operation Pads start of string with zeros to target width. ### Signature ```typescript $df.col().str.zfill(width: number) ``` ### Parameters - `width` (any): Minimum resulting string width. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ s: ["apple", "banana", "cherry"] }) >>> df shape: (3, 1) +----------+ | s | +----------+ | "apple" | | "banana" | | "cherry" | +----------+ >>> df.withColumns($df.col("s").str.zfill(8).alias("padded")) shape: (3, 2) +----------+----------+ | s | padded | +----------+----------+ | "apple" | 000apple | | "banana" | 00banana | | "cherry" | 00cherry | +----------+----------+ ``` --- ## Namespace: $df.col.structExpr ## Operation Extracts a sub-field property value from nested objects/struct columns. ### Signature ```typescript $df.col().struct.field(name: string) ``` ### Parameters - `name` (any): Name of the field key to extract. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ user: [{ name: "Alice", age: 30 }] }) >>> df shape: (1, 1) +--------------------------------+ | user | +--------------------------------+ | { name: "Alice", age: 30 } | +--------------------------------+ >>> df.withColumns($df.col("user").struct.field("name").alias("user_name")) shape: (1, 2) +---------------------------+-----------+ | user | user_name | +---------------------------+-----------+ | { name: "Alice", id: 1 } | Alice | +---------------------------+-----------+ ``` --- ## Operation Renames existing field keys inside structured object columns. ### Signature ```typescript $df.col().struct.renameFields(mapping: RenameMappingArg) ``` ### Parameters - `mapping` (any): Key-value map of current field names to new field names. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ user: [{ name: "Alice", age: 30 }] }) >>> df shape: (1, 1) +--------------------------------+ | user | +--------------------------------+ | { name: "Alice", age: 30 } | +--------------------------------+ >>> df.withColumns($df.col("user").struct.renameFields({ name: "first_name" }).alias("user_renamed")) shape: (1, 2) +---------------------------+--------------------------------+ | user | user_renamed | +---------------------------+--------------------------------+ | { name: "Alice", id: 1 } | { id: 1, first_name: "Alice" } | +---------------------------+--------------------------------+ ``` --- ## Operation Inserts or updates fields inside structured object columns. ### Signature ```typescript $df.col().struct.withFields(fields: IntoExprSeriesArg | ExprDict) ``` ### Parameters - `fields` (any): Expressions or field map defining new or updated fields. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ user: [{ name: "Alice", age: 30 }] }) >>> df shape: (1, 1) +--------------------------------+ | user | +--------------------------------+ | { name: "Alice", age: 30 } | +--------------------------------+ >>> df.withColumns($df.col("user").struct.withFields({ is_active: $df.lit(true) }).alias("updated_user")) shape: (1, 2) +------------------------------+-------------------------------------------+ | user | updated_user | +------------------------------+-------------------------------------------+ | { name: "Alice", age: 30 } | { name: "Alice", age: 30, is_active: true }| +------------------------------+-------------------------------------------+ ``` --- ## Operation Expands nested struct attributes into distinct columns in the DataFrame schema. ### Signature ```typescript $df.col().struct.unnest() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ user: [{ name: "Alice", age: 30 }] }) >>> df shape: (1, 1) +--------------------------------+ | user | +--------------------------------+ | { name: "Alice", age: 30 } | +--------------------------------+ >>> df.select($df.col("user").struct.unnest()) shape: (1, 2) +-------+-----+ | name | age | +-------+-----+ | Alice | 30 | +-------+-----+ ``` --- ## Namespace: $df.col.temporalExpr ## Operation Casts the schema time unit of a Datetime column (`"ms"`, `"us"`, `"ns"`). This is a metadata-only operation — underlying millisecond Date timestamps are preserved. ### Signature ```typescript $df.col().dt.castTimeUnit(unit: "ms" | "us" | "ns") ``` ### Parameters - `unit` (any): Target time unit: `"ms"` (milliseconds), `"us"` (microseconds), or `"ns"` (nanoseconds). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("ts").dt.castTimeUnit("us").alias("ts_us")) shape: (1, 2) +--------------------------+--------------------------+ | ts | ts_us | +--------------------------+--------------------------+ | 2026-05-20T10:00:00.123Z | 2026-05-20T10:00:00.123Z | +--------------------------+--------------------------+ ``` --- ## Operation Extracts the 1-indexed century component (e.g. 21 for 2026) from a Datetime column. ### Signature ```typescript $df.col().dt.century(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.century().alias("century")) shape: (1, 2) +------------+---------+ | d | century | +------------+---------+ | 2026-05-20 | 21 | +------------+---------+ ``` --- ## Operation Converts a Datetime column to a different IANA timezone. Preserves the exact UTC epoch instant while changing the timezone label, affecting how local wall-clock component extractors (`hour()`, `day()`, etc.) and `strftime` interpret values. Requires the column to already be timezone-aware; use `replace({ timeZone })` to assign a timezone to a naive column first. ### Signature ```typescript $df.col().dt.convertTimeZone(timeZone: string) ``` ### Parameters - `timeZone` (any): Target IANA timezone identifier (e.g. `"UTC"`, `"America/New_York"`, `"Europe/London"`). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("ts").dt.replace({ timeZone: "UTC" }).dt.convertTimeZone("America/New_York").alias("ts_ny")) shape: (1, 2) +--------------------------+-------------------------------+ | ts | ts_ny | +--------------------------+-------------------------------+ | 2026-05-20T10:00:00.123Z | 2026-05-20 06:00:00.123 EDT | +--------------------------+-------------------------------+ ``` --- ## Operation Extracts the Date object component from a Datetime column, truncating time to 00:00:00.000 UTC. ### Signature ```typescript $df.col().dt.date() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("ts").dt.date().alias("date_only")) shape: (1, 2) +--------------------------+--------------------------+ | ts | date_only | +--------------------------+--------------------------+ | 2026-05-20T10:00:00.123Z | 2026-05-20T00:00:00.000Z | +--------------------------+--------------------------+ ``` --- ## Operation Extracts the calendar day component (1-31) from a Datetime column. ### Signature ```typescript $df.col().dt.day(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.day().alias("day")) shape: (1, 2) +------------+-----+ | d | day | +------------+-----+ | 2026-05-20 | 20 | +------------+-----+ ``` --- ## Operation Extracts the total number of days in the month (28-31) for each Datetime value. ### Signature ```typescript $df.col().dt.daysInMonth(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.daysInMonth().alias("dim")) shape: (1, 2) +------------+-----+ | d | dim | +------------+-----+ | 2026-05-20 | 31 | +------------+-----+ ``` --- ## Operation Returns the epoch duration timestamp offset in the specified time resolution unit. ### Signature ```typescript $df.col().dt.epoch(unit: "s" | "ms" | "us" | "ns" = "ms") ``` ### Parameters - `unit` (any): Time resolution unit (`"ms"`, `"us"`, `"ns"`, `"s"`). Defaults to `"ms"`. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.epoch("s").alias("epoch_s")) shape: (1, 2) +------------+------------+ | d | epoch_s | +------------+------------+ | 2026-05-20 | 1779235200 | +------------+------------+ ``` --- ## Operation Extracts the local hour component (0-23) from a Datetime column. ### Signature ```typescript $df.col().dt.hour(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("ts").dt.hour().alias("hr")) shape: (1, 2) +--------------------------+----+ | ts | hr | +--------------------------+----+ | 2026-05-20T10:00:00.123Z | 10 | +--------------------------+----+ ``` --- ## Operation Evaluates whether each Datetime value falls on a business day. Supports custom weekend day definitions and holiday arrays or timestamp sets. ### Signature ```typescript $df.col().dt.isBusinessDay( options: { excludeWeekdays?: number[] = [6, 7], holidays?: (Date | string | number)[] | Set } = {} ) ``` ### Parameters - `options` (any): Business day rules and custom holiday configuration options. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.isBusinessDay().alias("is_bday")) shape: (1, 2) +------------+---------+ | d | is_bday | +------------+---------+ | 2026-05-20 | true | +------------+---------+ ``` --- ## Operation Checks if the calendar year of a Datetime value is a leap year (366 days). ### Signature ```typescript $df.col().dt.isLeapYear(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.isLeapYear().alias("leap")) shape: (1, 2) +------------+-------+ | d | leap | +------------+-------+ | 2026-05-20 | false | +------------+-------+ ``` --- ## Operation Extracts the ISO 8601 week-numbering year from a Datetime column. ### Signature ```typescript $df.col().dt.isoYear(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.isoYear().alias("iso_yr")) shape: (1, 2) +------------+--------+ | d | iso_yr | +------------+--------+ | 2026-05-20 | 2026 | +------------+--------+ ``` --- ## Operation Extracts the microsecond component (0-999,000) scaled from Datetime millisecond precision. ### Signature ```typescript $df.col().dt.microsecond(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("ts").dt.microsecond().alias("us")) shape: (1, 2) +--------------------------+--------+ | ts | us | +--------------------------+--------+ | 2026-05-20T10:00:00.123Z | 123000 | +--------------------------+--------+ ``` --- ## Operation Extracts the 1-indexed millennium component index (e.g. 3 for the year 2026) from a Datetime column. ### Signature ```typescript $df.col().dt.millennium(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.millennium().alias("mil")) shape: (1, 2) +------------+-----+ | d | mil | +------------+-----+ | 2026-05-20 | 3 | +------------+-----+ ``` --- ## Operation Extracts the millisecond component (0-999) from a Datetime column. ### Signature ```typescript $df.col().dt.millisecond(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("ts").dt.millisecond().alias("ms")) shape: (1, 2) +--------------------------+-----+ | ts | ms | +--------------------------+-----+ | 2026-05-20T10:00:00.123Z | 123 | +--------------------------+-----+ ``` --- ## Operation Extracts the minute component (0-59) from a Datetime column. ### Signature ```typescript $df.col().dt.minute(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("ts").dt.minute().alias("min")) shape: (1, 2) +--------------------------+-----+ | ts | min | +--------------------------+-----+ | 2026-05-20T10:00:00.123Z | 0 | +--------------------------+-----+ ``` --- ## Operation Extracts the calendar month component (1-12) from a Datetime column. ### Signature ```typescript $df.col().dt.month(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.month().alias("m")) shape: (1, 2) +------------+---+ | d | m | +------------+---+ | 2026-05-20 | 5 | +------------+---+ ``` --- ## Operation Returns a Datetime column shifted to the last calendar day of the month at 00:00:00.000 UTC. ### Signature ```typescript $df.col().dt.monthEnd() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.monthEnd().alias("m_end")) shape: (1, 2) +------------+--------------------------+ | d | m_end | +------------+--------------------------+ | 2026-05-20 | 2026-05-31T00:00:00.000Z | +------------+--------------------------+ ``` --- ## Operation Returns a Datetime column shifted to the first calendar day of the month at 00:00:00.000 UTC. ### Signature ```typescript $df.col().dt.monthStart() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.monthStart().alias("m_start")) shape: (1, 2) +------------+--------------------------+ | d | m_start | +------------+--------------------------+ | 2026-05-20 | 2026-05-01T00:00:00.000Z | +------------+--------------------------+ ``` --- ## Operation Extracts the nanosecond component (0-999,000,000) scaled from Datetime millisecond precision. ### Signature ```typescript $df.col().dt.nanosecond(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("ts").dt.nanosecond().alias("ns")) shape: (1, 2) +--------------------------+-----------+ | ts | ns | +--------------------------+-----------+ | 2026-05-20T10:00:00.123Z | 123000000 | +--------------------------+-----------+ ``` --- ## Operation Offsets a Datetime column by N calendar days (numeric constant, column reference, or expression). Reuses $df.duration({ days: n }) and expression addition math under the hood. ### Signature ```typescript $df.col().dt.offsetDay( n: number | bigint | IExpr | null, options: { excludeWeekdays?: number[] = [6, 7], holidays?: (Date | string | number)[] | Set, roll?: "raise" | "forward" | "backward" = "raise" } = {} ) ``` ### Parameters - `n` (any): Number of calendar days to offset (positive or negative). - `options` (any): Day offset configuration options. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.offsetDay(5).alias("later")) shape: (1, 2) +------------+--------------------------+ | d | later | +------------+--------------------------+ | 2026-05-20 | 2026-05-25T00:00:00.000Z | +------------+--------------------------+ ``` --- ## Operation Extracts the day of the year (1-366) from a Datetime column. ### Signature ```typescript $df.col().dt.ordinalDay(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.ordinalDay().alias("doy")) shape: (1, 2) +------------+-----+ | d | doy | +------------+-----+ | 2026-05-20 | 140 | +------------+-----+ ``` --- ## Operation Extracts the calendar quarter of the year (1-4) from a Datetime column. ### Signature ```typescript $df.col().dt.quarter(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.quarter().alias("qtr")) shape: (1, 2) +------------+-----+ | d | qtr | +------------+-----+ | 2026-05-20 | 2 | +------------+-----+ ``` --- ## Operation Replaces specific date and time components (`year`, `month`, `day`, `hour`, `minute`, `second`, `ms`, `timeZone`) of a Datetime column. Unspecified components are preserved from the original value. When `timeZone` is provided in options, components are interpreted in that timezone. Note: `month` is 1-indexed (1 = January, 12 = December); `day` is 1-indexed (1-31). ### Signature ```typescript $df.col().dt.replace( options: { day?: number, hour?: number, minute?: number, month?: number, ms?: number, second?: number, timeZone?: string | null, year?: number } ) ``` ### Parameters - `options` (any): Object specifying which components to replace. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("ts").dt.replace({ year: 2030, month: 1, day: 1 }).alias("replaced")) shape: (1, 2) +--------------------------+--------------------------+ | ts | replaced | +--------------------------+--------------------------+ | 2026-05-20T10:00:00.123Z | 2030-01-01T10:00:00.123Z | +--------------------------+--------------------------+ ``` --- ## Operation Extracts the second component (0-59) from a Datetime column. ### Signature ```typescript $df.col().dt.second() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("ts").dt.second().alias("sec")) shape: (1, 2) +--------------------------+-----+ | ts | sec | +--------------------------+-----+ | 2026-05-20T10:00:00.123Z | 0 | +--------------------------+-----+ ``` --- ## Operation Formats Datetime values into custom formatted strings using strftime directive pattern tokens. Automatically applies the column's assigned timezone unless explicitly overridden in options. ### Signature ```typescript $df.col().dt.strftime( options: { format: string, locale?: string = "en-US", timeZone?: string = "UTC" } ) ``` ### Parameters - `options` (any): Formatting pattern string (e.g. `"%Y-%m-%d %H:%M:%S"`) or configuration object. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.strftime("%Y/%m/%d").alias("formatted")) shape: (1, 2) +------------+------------+ | d | formatted | +------------+------------+ | 2026-05-20 | 2026/05/20 | +------------+------------+ ``` --- ## Operation Extracts the time component formatted string (`"HH:MM:SS.mmm"`) from a Datetime column. ### Signature ```typescript $df.col().dt.time() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("ts").dt.time().alias("time")) shape: (1, 2) +--------------------------+--------------+ | ts | time | +--------------------------+--------------+ | 2026-05-20T10:00:00.123Z | 10:00:00.123 | +--------------------------+--------------+ ``` --- ## Operation Returns numeric timestamp relative to Epoch. Alias for epoch. ### Signature ```typescript $df.col().dt.timestamp(unit: "s" | "ms" | "us" | "ns" = "ms") ``` ### Parameters - `unit` (any): Time unit resolution. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.timestamp("s").alias("ts")) shape: (1, 2) +------------+------------+ | d | ts | +------------+------------+ | 2026-05-20 | 1779235200 | +------------+------------+ ``` --- ## Operation Converts a Duration value (in milliseconds) to total days count. ### Signature ```typescript $df.col().dt.totalDays() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.duration({ days: $df.col("add") }).dt.totalDays().alias("days")) shape: (2, 3) +------------+-----+------+ | dt | add | days | +------------+-----+------+ | 2026-01-01 | 1 | 1 | | 2026-01-01 | 2 | 2 | +------------+-----+------+ ``` --- ## Operation Converts a Duration value (in milliseconds) to total hours count. ### Signature ```typescript $df.col().dt.totalHours() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.duration({ days: $df.col("add") }).dt.totalHours().alias("hrs")) shape: (2, 3) +------------+-----+-----+ | dt | add | hrs | +------------+-----+-----+ | 2026-01-01 | 1 | 24 | | 2026-01-01 | 2 | 48 | +------------+-----+-----+ ``` --- ## Operation Converts Duration to microsecond count. ### Signature ```typescript $df.col().dt.totalMicroseconds() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.duration({ days: $df.col("add") }).dt.totalMicroseconds().alias("us")) shape: (2, 3) +------------+-----+--------------+ | dt | add | us | +------------+-----+--------------+ | 2026-01-01 | 1 | 86400000000 | | 2026-01-01 | 2 | 172800000000 | +------------+-----+--------------+ ``` --- ## Operation Converts Duration to millisecond count. ### Signature ```typescript $df.col().dt.totalMilliseconds() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.duration({ days: $df.col("add") }).dt.totalMilliseconds().alias("ms")) shape: (2, 3) +------------+-----+-----------+ | dt | add | ms | +------------+-----+-----------+ | 2026-01-01 | 1 | 86400000 | | 2026-01-01 | 2 | 172800000 | +------------+-----+-----------+ ``` --- ## Operation Converts Duration to floating point minutes. ### Signature ```typescript $df.col().dt.totalMinutes() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.duration({ days: $df.col("add") }).dt.totalMinutes().alias("mins")) shape: (2, 3) +------------+-----+------+ | dt | add | mins | +------------+-----+------+ | 2026-01-01 | 1 | 1440 | | 2026-01-01 | 2 | 2880 | +------------+-----+------+ ``` --- ## Operation Converts Duration to nanosecond count. ### Signature ```typescript $df.col().dt.totalNanoseconds() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.duration({ days: $df.col("add") }).dt.totalNanoseconds().alias("ns")) shape: (2, 3) +------------+-----+-----------------+ | dt | add | ns | +------------+-----+-----------------+ | 2026-01-01 | 1 | 86400000000000 | | 2026-01-01 | 2 | 172800000000000 | +------------+-----+-----------------+ ``` --- ## Operation Converts Duration to floating point seconds. ### Signature ```typescript $df.col().dt.totalSeconds() ``` ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.duration({ days: $df.col("add") }).dt.totalSeconds().alias("secs")) shape: (2, 3) +------------+-----+--------+ | dt | add | secs | +------------+-----+--------+ | 2026-01-01 | 1 | 86400 | | 2026-01-01 | 2 | 172800 | +------------+-----+--------+ ``` --- ## Operation Returns the UTC offset of a timezone for a given Datetime value. Supports returning the total offset, the standard (base) offset, or just the daylight saving time component, in multiple output formats. ### Signature ```typescript $df.col().dt.utcOffset( timeZone?: string, options: { format?: "milliseconds" | "minutes" | "hours" | "iso" | "basic" = "milliseconds", type?: "base" | "total" | "daylightSavingTime" = "total" } = {} ) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the system local timezone. - `options` (any): Output configuration: `type` selects which offset component to return (`"total"` | `"standardTime"` | `"daylightSavingTime"`), and `format` controls the output unit (`"milliseconds"` | `"minutes"` | `"hours"` | `"iso"` | `"basic"`). ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.utcOffset("UTC").alias("offset")) shape: (1, 2) +------------+--------+ | d | offset | +------------+--------+ | 2026-05-20 | 0 | +------------+--------+ ``` --- ## Operation Extracts the ISO 8601 week number (1-53) from a Datetime column. ### Signature ```typescript $df.col().dt.week(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to the column timezone or UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.week().alias("week")) shape: (1, 2) +------------+------+ | d | week | +------------+------+ | 2026-05-20 | 21 | +------------+------+ ``` --- ## Operation Extracts weekday component (1=Monday, 7=Sunday). ### Signature ```typescript $df.col().dt.weekday(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.weekday().alias("wd")) shape: (1, 2) +------------+----+ | d | wd | +------------+----+ | 2026-05-20 | 3 | +------------+----+ ``` --- ## Operation Extracts the year component from a Datetime column. ### Signature ```typescript $df.col().dt.year(timeZone?: string) ``` ### Parameters - `timeZone` (any): Optional IANA timezone identifier. Defaults to UTC. ### Returns: `ColumnExpression` ### Examples ```typescript >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.withColumns($df.col("d").dt.year().alias("yr")) shape: (1, 2) +------------+------+ | d | yr | +------------+------+ | 2026-05-20 | 2026 | +------------+------+ ``` --- # DataFrame API ## Operation Casts columns in the DataFrame to the specified data type(s). ### Signature ```typescript df.cast( dtypes: RegisteredDataType | DataFrameSchema, options: { strict?: boolean = true } = {} ): DataFrame ``` ### Parameters - `dtypes` (CastTargetArg): Target data type for all columns, or mapping of column names to target data types. - `[options]` (CastOptions): Casting options (e.g. strict). ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.cast($df.Float64) >>> df.cast({ a: $df.Float64, b: $df.Utf8 }) >>> df.cast({ num_str: $df.Int64 }, { strict: false }) ``` --- ## Operation Creates a deep copy of the current DataFrame instance, duplicating all underlying column data arrays and schema metadata. Modifying columns or values in the cloned DataFrame will not mutate the original. ### Signature ```typescript df.clone(): DataFrame ``` ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ ``` --- ## Operation Gets array of column names in the DataFrame. ### Signature ```typescript df.columns: string[] ``` ### Returns: `Array of column name strings.` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.columns ["a", "b"] ``` --- ## Operation Concatenates items vertically, horizontally, or diagonally. ### Signature ```typescript df.concat( items: ConcatItem | ConcatItem[], options: { horizontal?: { strict?: boolean = true }, how?: "vertical" | "horizontal" | "diagonal" = "vertical" } = {} ): DataFrame ``` ### Parameters - `items` (ConcatItemsArg): Single DataFrame or array of DataFrames/rows to concatenate. - `[options]` (ConcatOptions): Configuration options for concatenation layout and strictness. ### Returns: `DataFrame` ### Examples ```typescript // 1. Vertical Concatenation (default): >>> const df1 = $df.data({ a: [1, 2] }) >>> const df2 = $df.data({ b: [10, 20] }) >>> df1 shape: (2, 1) +---+ | a | +---+ | 1 | | 2 | +---+ >>> df2 shape: (2, 1) +----+ | b | +----+ | 10 | | 20 | +----+ >>> df1.concat(df2, { how: "vertical" }) shape: (4, 1) +------+ | a | +------+ | 1 | | 2 | | null | | null | +------+ // 2. Horizontal Concatenation: >>> const df1 = $df.data({ a: [1, 2] }) >>> const df2 = $df.data({ b: [10, 20] }) >>> df1 shape: (2, 1) +---+ | a | +---+ | 1 | | 2 | +---+ >>> df2 shape: (2, 1) +----+ | b | +----+ | 10 | | 20 | +----+ >>> df1.concat(df2, { how: "horizontal" }) shape: (2, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | +---+----+ // 3. Diagonal Concatenation (mismatched columns): >>> const df1 = $df.data({ a: [1, 2] }) >>> const df2 = $df.data({ b: [10, 20] }) >>> df1 shape: (2, 1) +---+ | a | +---+ | 1 | | 2 | +---+ >>> df2 shape: (2, 1) +----+ | b | +----+ | 10 | | 20 | +----+ >>> df1.concat(df2, { how: "diagonal" }) shape: (4, 2) +------+------+ | a | b | +------+------+ | 1 | null | | 2 | null | | null | 10 | | null | 20 | +------+------+ ``` --- ## Operation Drops specified columns from the DataFrame. ### Signature ```typescript df.drop(...args: (K | K[])[]): DataFrame> ``` ### Parameters - `args` (ColumnKeyArg[]): Column names or arrays of column names to remove. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.drop("b") shape: (2, 1) +---+ | a | +---+ | 1 | | 2 | +---+ ``` --- ## Operation Drops rows with null or undefined values. ### Signature ```typescript df.dropNulls(subset?: string | string[]): DataFrame ``` ### Parameters - `[subset]` (ColumnKeyArg): Column name or array of column names to check for nulls. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.dropNulls() shape: (2, 1) +---+ | a | +---+ | 1 | | 3 | +---+ ``` --- ## Operation Gets array of registered column DataTypes matching current schema order. ### Signature ```typescript df.dtypes: RegisteredDataType[] ``` ### Returns: `Array of RegisteredDataType definitions.` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.dtypes [Float64, Utf8] ``` --- ## Operation Compares this DataFrame with another for equality. Checks shape, column names, column order, schemas, and row values. ### Signature ```typescript df.equals( other: DataFrame, options: { nullsEqual?: boolean = true } = {} ): boolean ``` ### Parameters - `other` (DataFrame): The other DataFrame to compare with. - `[options]` (EqualsOptions): Comparison configuration options. ### Returns: `boolean` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.equals(df2) true ``` --- ## Operation Explodes an array column into multiple rows, replicating non-target row attributes. ### Signature ```typescript df.explode( columns: IntoExpr | IntoExpr[], options?: { emptyAsNull?: boolean = true, keepNulls?: boolean = true } ): DataFrame ``` ### Parameters - `columns` (IntoExprArg): Target column expression or array column name to explode. - `[options]` (ExplodeOptions): Configuration options for empty array and null handling. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.explode("values") shape: (2, 2) +-------+--------+ | group | values | +-------+--------+ | A | 1 | | A | 2 | +-------+--------+ ``` --- ## Operation Fills targeted values ("null", "nan", or "all") across columns using scalar values or statistical strategies. ### Signature ```typescript df.fill( target: "null" | "nan" | "all" | ScalarArg, options: { limit?: number, strategy?: "forward" | "backward" | "min" | "max" | "mean" | "zero" | "one", value?: IExpr | ValidScalarTypes } = {} ): DataFrame ``` ### Parameters - `target` (FillTarget): Target type ("null", "nan", "all"). - `[options]` (FillOptions, default: {}): Configuration options specifying replacement value, strategy, and optional limit. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.fill("null", { value: 0 }) shape: (3, 1) +---+ | a | +---+ | 1 | | 0 | | 3 | +---+ ``` --- ## Operation Fills NaN values across numeric columns using scalar values or statistical strategies. ### Signature ```typescript df.fillNan( options: { limit?: number, strategy?: "forward" | "backward" | "min" | "max" | "mean" | "zero" | "one", value?: IExpr | ValidScalarTypes } = {} ): DataFrame ``` ### Parameters - `[options]` (FillNullOptions, default: {}): Configuration options specifying replacement value, strategy, and optional limit. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.fillNan({ value: 0 }) shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ ``` --- ## Operation Fills null values across columns using scalar values or statistical strategies. ### Signature ```typescript df.fillNull( options: { limit?: number, strategy?: "forward" | "backward" | "min" | "max" | "mean" | "zero" | "one", value?: IExpr | ValidScalarTypes } = {} ): DataFrame ``` ### Parameters - `[options]` (FillNullOptions): Configuration options for null replacement. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.fillNull({ value: 0 }) shape: (3, 1) +---+ | a | +---+ | 1 | | 0 | | 3 | +---+ ``` --- ## Operation Filters rows matching boolean column expressions or predicate callbacks. ### Signature ```typescript df.filter(...exprs: (IExpr | (row: T) => any | FilterPredicate[])[]): DataFrame ``` ### Parameters - `exprs` (FilterPredicateArg[]): Expressions or predicate functions evaluated per row. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.filter($df.col("a").gt(1)) shape: (2, 1) +---+ | a | +---+ | 2 | | 3 | +---+ ``` --- ## Operation Groups rows by key columns to prepare for aggregations. ### Signature ```typescript df.groupBy(keys: K | K[]): GroupedData ``` ### Parameters - `keys` (ColumnKeyArg): Column name or array of key column names. ### Returns: `GroupedData` ### Examples ```typescript // 1. Group by single column with single aggregation: >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").sum().alias("sum")) shape: (2, 2) +-------+-----+ | group | sum | +-------+-----+ | A | 30 | | B | 30 | +-------+-----+ // 2. Group by with multiple parallel aggregations: >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg( ... $df.col("val").mean().alias("avg"), ... $df.col("val").sum().alias("total") ... ) shape: (2, 3) +-------+-----+-------+ | group | avg | total | +-------+-----+-------+ | A | 15 | 30 | | B | 30 | 30 | +-------+-----+-------+ ``` --- ## Operation Groups dynamically based on a time or integer index column over sliding / stepping windows. ### Signature ```typescript df.groupByDynamic( indexColumn: K | IntoExpr, options: { by?: keyof any | keyof any[], checkSorted?: boolean = true, closed?: "both" | "left" | "right" | "none" = "left", every: number | string, groupBy?: keyof any | keyof any[], includeBoundaries?: boolean = false, label?: "left" | "right" | "datapoint" = "left", offset?: number | string = 0, period?: number | string = `every` if omitted, startBy?: "window" | "datapoint" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday" = "window", truncate?: boolean = true } ): GroupedData ``` ### Parameters - `indexColumn` (any): The time/integer column or column expression to group on. - `options` (any): Dynamic grouping configuration options (`every`, `period`, `offset`, `truncate`, `includeBoundaries`, `closed`, `label`, `by`, `startBy`, `checkSorted`). ### Returns: `GroupedData` ### Examples ```typescript >>> const df = $df.data([ ... { time: new Date("2024-01-01T00:00:00Z"), val: 10 }, ... { time: new Date("2024-01-01T12:00:00Z"), val: 20 }, ... { time: new Date("2024-01-02T00:00:00Z"), val: 30 } ... ]) >>> df shape: (3, 2) +--------------------------+-----+ | time | val | +--------------------------+-----+ | 2024-01-01T00:00:00.000Z | 10 | | 2024-01-01T12:00:00.000Z | 20 | | 2024-01-02T00:00:00.000Z | 30 | +--------------------------+-----+ >>> df.groupByDynamic("time", { every: "1d", period: "1d" }).agg($df.col("val").sum().alias("daily_sum")) shape: (2, 2) +--------------------------+-----------+ | time | daily_sum | +--------------------------+-----------+ | 2024-01-01T00:00:00.000Z | 30 | | 2024-01-02T00:00:00.000Z | 30 | +--------------------------+-----------+ ``` --- ## Operation Returns the first N rows as a new DataFrame. ### Signature ```typescript df.head(n: number = 10): DataFrame ``` ### Parameters - `n` (any): Number of leading rows to slice (default 10). ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.head(2) shape: (2, 1) +---+ | a | +---+ | 1 | | 2 | +---+ ``` --- ## Operation Gets height (total row count) of the DataFrame. ### Signature ```typescript df.height: number ``` ### Returns: `Number of rows.` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.height 3 ``` --- ## Operation Inserts a new column at a specific ordinal index position. ### Signature ```typescript df.insertColumn( index: number, name: string, expr: IntoExpr | ArrayLike ): DataFrame ``` ### Parameters - `index` (number): Target column index position. - `name` (string): Name of the inserted column. - `expr` (InsertColumnArg): Value expression, column definition, or raw column values array. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.insertColumn(1, "c", [10, 20]) shape: (2, 3) +---+----+---+ | a | c | b | +---+----+---+ | 1 | 10 | x | | 2 | 20 | y | +---+----+---+ ``` --- ## Operation Retrieves a single scalar cell value by row and column position or name. ### Signature ```typescript df.item( row?: number, column?: number | string ): any ``` ### Parameters - `[row]` (number): Row index position. - `[column]` (ColumnIndexOrNameArg): Column index or column name string. ### Returns: `any` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.item(0, "val") 42 ``` --- ## Operation Yields a generator iterating over raw column arrays. ### Signature ```typescript df.iterColumns(): Generator ``` ### Returns: `Generator of ColumnData arrays.` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ ``` --- ## Operation Yields a generator iterating over rows as tuples or named objects. ### Signature ```typescript df.iterRows( config: { named?: boolean = false } = {} ): Generator> ``` ### Parameters - `[config]` (any): Iteration format configuration. ### Returns: `Generator of rows.` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ ``` --- ## Operation Joins two DataFrames on key columns using a specified join strategy. ### Signature ```typescript df.join( other: DataFrame, options: { coalesce?: boolean = true, how?: "inner" | "outer" | "left" | "right" | "semi" | "anti" | "cross" = "inner", joinNulls?: boolean = false, leftOn?: keyof any | keyof any[], maintainOrder?: JoinMaintainOrder | boolean = "none", on?: keyof any & keyof any | (keyof any & keyof any)[], rightOn?: keyof any | keyof any[], suffixes?: [string, string] = ["", "_right"] } = {} ): DataFrame ``` ### Parameters - `other` (DataFrame): Right DataFrame to join with. - `[options]` (JoinOptions, default: {}): Join configuration object. ### Returns: `DataFrame` ### Examples ```typescript // 1. Inner join on matching key column: >>> const df1 = $df.data({ id: [1, 2], val: ["a", "b"] }) >>> const df2 = $df.data({ id: [1, 2], num: [100, 200] }) >>> df1 shape: (2, 2) +----+-----+ | id | val | +----+-----+ | 1 | a | | 2 | b | +----+-----+ >>> df2 shape: (2, 2) +----+-----+ | id | num | +----+-----+ | 1 | 100 | | 2 | 200 | +----+-----+ >>> df1.join(df2, { on: "id" }) shape: (2, 3) +----+-----+-----+ | id | val | num | +----+-----+-----+ | 1 | a | 100 | | 2 | b | 200 | +----+-----+-----+ // 2. Outer join on matching key column: >>> const df1 = $df.data({ id: [1, 2], val: ["a", "b"] }) >>> const df2 = $df.data({ id: [1, 2], num: [100, 200] }) >>> df1 shape: (2, 2) +----+-----+ | id | val | +----+-----+ | 1 | a | | 2 | b | +----+-----+ >>> df2 shape: (2, 2) +----+-----+ | id | num | +----+-----+ | 1 | 100 | | 2 | 200 | +----+-----+ >>> df1.join(df2, { on: "id", how: "outer" }) shape: (2, 3) +----+-----+-----+ | id | val | num | +----+-----+-----+ | 1 | a | 100 | | 2 | b | 200 | +----+-----+-----+ ``` --- ## Operation Performs an asof (as-of) join for inexact matching on ordered numeric or temporal key columns. Similar to a left join, but instead of exact key equality, matches the nearest key row from the right DataFrame according to the selected `strategy` ("backward", "forward", or "nearest") and optional `tolerance`. Both DataFrames must be sorted in ascending order on their respective `on` / `leftOn` / `rightOn` join keys. ### Signature ```typescript df.joinAsof( other: DataFrame, options: { allowExactMatches?: boolean = true, by?: keyof any & keyof any | (keyof any & keyof any)[], checkSorted?: boolean = true, coalesce?: boolean = true, leftBy?: keyof any | keyof any[], leftOn?: (keyof any), on?: (keyof any & keyof any), rightBy?: keyof any | keyof any[], rightOn?: (keyof any), strategy?: "backward" | "forward" | "nearest" = "backward", suffixes?: [string, string] = ["", "_right"], tolerance?: number | string } ): DataFrame ``` ### Parameters - `other` (DataFrame): The right DataFrame to join with. - `options` (JoinAsofOptions): Asof join configuration options. ### Returns: `A new DataFrame containing the joined results.` ### Examples ```typescript >>> const trades = $df.data([ ... { time: 1000, ticker: "AAPL", price: 150.0 }, ... { time: 1005, ticker: "AAPL", price: 150.5 }, ... { time: 1015, ticker: "AAPL", price: 151.0 } ... ]) >>> const quotes = $df.data([ ... { time: 998, ticker: "AAPL", bid: 149.9 }, ... { time: 1004, ticker: "AAPL", bid: 150.4 }, ... { time: 1010, ticker: "AAPL", bid: 150.8 } ... ]) >>> trades shape: (3, 3) +------+--------+-------+ | time | ticker | price | +------+--------+-------+ | 1000 | AAPL | 150.0 | | 1005 | AAPL | 150.5 | | 1015 | AAPL | 151.0 | +------+--------+-------+ >>> quotes shape: (3, 3) +------+--------+-------+ | time | ticker | bid | +------+--------+-------+ | 998 | AAPL | 149.9 | | 1004 | AAPL | 150.4 | | 1010 | AAPL | 150.8 | +------+--------+-------+ >>> trades.joinAsof(quotes, { on: "time", by: "ticker" }) shape: (3, 4) +------+--------+-------+-------+ | time | ticker | price | bid | +------+--------+-------+-------+ | 1000 | AAPL | 150.0 | 149.9 | | 1005 | AAPL | 150.5 | 150.4 | | 1015 | AAPL | 151.0 | 150.8 | +------+--------+-------+-------+ ``` --- ## Operation Joins two DataFrames based on arbitrary expression predicates (non-equi joins). Evaluates one or more boolean expressions across combined rows from both DataFrames. When column names collide between the two DataFrames, columns are suffixed according to `options.suffixes` (default `["", "_right"]`). ### Signature ```typescript df.joinWhere( other: DataFrame, ...args: { how?: "inner" | "left" | "right" = "inner", suffixes?: [string, string] = ["", "_right"] } ): DataFrame ``` ### Parameters - `other` (DataFrame): The right DataFrame to join with. - `args` (...JoinWhereArg): Predicate expression(s), arrays of expressions, and an optional configuration options object (`{ how, suffixes }`). ### Returns: `DataFrame` ### Examples ```typescript >>> const east = $df.data([ ... { id: 100, dur: 120, rev: 12, cores: 2 }, ... { id: 101, dur: 140, rev: 14, cores: 8 }, ... { id: 102, dur: 160, rev: 16, cores: 4 } ... ]) >>> const west = $df.data([ ... { t_id: 404, time: 90, cost: 9, cores: 4 }, ... { t_id: 498, time: 130, cost: 13, cores: 2 }, ... { t_id: 676, time: 150, cost: 15, cores: 1 }, ... { t_id: 742, time: 170, cost: 16, cores: 4 } ... ]) >>> east shape: (3, 4) +-----+-----+-----+-------+ | id | dur | rev | cores | +-----+-----+-----+-------+ | 100 | 120 | 12 | 2 | | 101 | 140 | 14 | 8 | | 102 | 160 | 16 | 4 | +-----+-----+-----+-------+ >>> west shape: (4, 4) +------+------+------+-------+ | t_id | time | cost | cores | +------+------+------+-------+ | 404 | 90 | 9 | 4 | | 498 | 130 | 13 | 2 | | 676 | 150 | 15 | 1 | | 742 | 170 | 16 | 4 | +------+------+------+-------+ ``` --- ## Operation Limits the output to N rows starting from offset. ### Signature ```typescript df.limit( n: number, options: { from?: "start" | "end" = "start", offset?: number = 0 } = {} ): DataFrame ``` ### Parameters - `n` (number): Maximum number of rows to take. - `[options]` (LimitOptions): Offset and slice direction options. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.limit(2, { offset: 1 }) shape: (2, 1) +----+ | a | +----+ | 20 | | 30 | +----+ ``` --- ## Operation Splits a DataFrame into sub-DataFrames partitioned by column names or expressions (reusing `.over()` partition semantics). ### Signature ```typescript df.partitionBy>( by: K | K[], options: { asDict?: boolean = false, maintainOrder?: boolean = true } = {} ): PartitionByResult ``` ### Parameters - `by` (ColumnKeyArg): Key column(s) or column expressions to partition by. - `[options]` (PartitionByOptions, default: {}): Partition configuration options. ### Returns: `PartitionByResult` ### Examples ```typescript ``` --- ## Operation Pivots columns from long format to a wide datagrid structure. ### Signature ```typescript df.pivot( config: { agg?: (values: any[]) => any | string, columns: keyof T, index: keyof T | keyof T[], values: keyof T } ): DataFrame ``` ### Parameters - `config` (any): Pivot table configuration options. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ year: [2020, 2020, 2021, 2021], month: ["Jan", "Feb", "Jan", "Feb"], revenue: [100, 150, 120, 180] }) >>> df shape: (4, 3) +------+-------+---------+ | year | month | revenue | +------+-------+---------+ | 2020 | Jan | 100 | | 2020 | Feb | 150 | | 2021 | Jan | 120 | | 2021 | Feb | 180 | +------+-------+---------+ >>> df.pivot({ index: "year", columns: "month", values: "revenue" }) shape: (2, 3) +------+-----+-----+ | year | Jan | Feb | +------+-----+-----+ | 2020 | 100 | 150 | | 2021 | 120 | 180 | +------+-----+-----+ ``` --- ## Operation Renames columns based on a key-value mapping dictionary. ### Signature ```typescript df.rename(mapping: RenameMappingArg = {}): DataFrame ``` ### Parameters - `[mapping]` (RenameMappingArg): Dictionary mapping old column names to new names. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.rename({ a: "id", b: "label" }) shape: (2, 2) +----+-------+ | id | label | +----+-------+ | 1 | x | | 2 | y | +----+-------+ ``` --- ## Operation Reverses the row ordering of the DataFrame. ### Signature ```typescript df.reverse(): DataFrame ``` ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.reverse() shape: (2, 2) +---+---+ | a | b | +---+---+ | 2 | y | | 1 | x | +---+---+ ``` --- ## Operation Gets current DataFrameSchema dictionary mapping column names to DataType. ### Signature ```typescript df.schema: DataFrameSchema ``` ### Returns: `DataFrameSchema mapping.` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.schema { a: Float64, b: Utf8 } ``` --- ## Operation Selects specific columns or evaluates column expressions. ### Signature ```typescript df.select(...args: (SelectItem | SelectItem[])[]): DataFrame ``` ### Parameters - `args` (SelectArg[]): Column names, column expressions, or object maps to evaluate. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.select("a", $df.col("b").add(100).alias("b_plus")) shape: (2, 2) +---+--------+ | a | b_plus | +---+--------+ | 1 | 110 | | 2 | 120 | +---+--------+ ``` --- ## Operation Gets DataFrame dimensions as [height, width] tuple. ### Signature ```typescript df.shape: DataFrameShape ``` ### Returns: `Tuple [height, width].` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.shape [2, 2] ``` --- ## Operation Slices a subset range of rows between start and end index. ### Signature ```typescript df.slice( start: number, end?: number ): DataFrame ``` ### Parameters - `start` (number): Starting row index. - `[end]` (number): Optional ending row index (exclusive). ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.slice(1, 3) shape: (2, 1) +----+ | a | +----+ | 20 | | 30 | +----+ ``` --- ## Operation Sorts DataFrame rows by one or more column expressions or custom sorters. ### Signature ```typescript df.sort( config?: { by: keyof any | keyof any[] | IExpr | IExpr[], customComp?: ((a: any, b: any) => number) | Partial number>> | null, descending?: boolean | boolean[] = false, nullsLast?: boolean = true } ): DataFrame ``` ### Parameters - `[config]` (SortOptions): Sort configuration options. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.sort({ by: "a", descending: true }) shape: (3, 2) +---+----+ | a | b | +---+----+ | 3 | 30 | | 2 | 20 | | 1 | 10 | +---+----+ ``` --- ## Operation Returns the last N rows as a new DataFrame. ### Signature ```typescript df.tail(n: number = 10): DataFrame ``` ### Parameters - `n` (any): Number of trailing rows to take (default 10). ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.tail(2) shape: (2, 1) +---+ | a | +---+ | 3 | | 4 | +---+ ``` --- ## Operation Evaluates a column expression or retrieves column values as a raw JavaScript array. ### Signature ```typescript df.toArray(nameOrExpr: K | IExpr): any[] ``` ### Parameters - `nameOrExpr` (ColumnOrExprArg): Target column name or column expression. ### Returns: `any[]` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.toArray("a") [10, 20] ``` --- ## Operation Converts columns into a JavaScript dictionary mapping column keys to raw arrays. ### Signature ```typescript df.toDict(): DataFrameColumns ``` ### Returns: `Column dictionary map.` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.toDict() { a: Float64Array([1, 2]), b: ["x", "y"] } ``` --- ## Operation Converts rows into an array of JavaScript objects. ### Signature ```typescript df.toDicts(): T[] ``` ### Returns: `Array of row record objects.` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.toDicts() [{ a: 1, b: "x" }] ``` --- ## Operation Transposes rows into columns and columns into rows. ### Signature ```typescript df.transpose( options: { columnNames?: string | Iterable, headerName?: string = "column", includeHeader?: boolean = false } = {} ): DataFrame ``` ### Parameters - `[options]` (TransposeOptions): Transpose layout options. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ year: [2020, 2020, 2021, 2021], month: ["Jan", "Feb", "Jan", "Feb"], revenue: [100, 150, 120, 180] }) >>> df shape: (4, 3) +------+-------+---------+ | year | month | revenue | +------+-------+---------+ | 2020 | Jan | 100 | | 2020 | Feb | 150 | | 2021 | Jan | 120 | | 2021 | Feb | 180 | +------+-------+---------+ >>> df.transpose({ includeHeader: true, headerName: "metric" }) shape: (2, 3) +--------+----------+----------+ | metric | column_0 | column_1 | +--------+----------+----------+ | q1 | 100 | 500 | | q2 | 120 | 600 | +--------+----------+----------+ ``` --- ## Operation Filters distinct unique rows matching target key columns. ### Signature ```typescript df.unique(columns?: K | K[]): DataFrame ``` ### Parameters - `[columns]` (ColumnKeyArg): Target column or array of column names to evaluate uniqueness. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.unique() shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ ``` --- ## Operation Unpivots a wide DataFrame into a long format structure. ### Signature ```typescript df.unpivot( config: { idVars: keyof T | keyof T[], valueName?: string = "value", valueVars: keyof T | keyof T[], varName?: string = "variable" } ): DataFrame ``` ### Parameters - `config` (UnpivotOptions): Unpivot configuration options. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ year: [2020, 2020, 2021, 2021], month: ["Jan", "Feb", "Jan", "Feb"], revenue: [100, 150, 120, 180] }) >>> df shape: (4, 3) +------+-------+---------+ | year | month | revenue | +------+-------+---------+ | 2020 | Jan | 100 | | 2020 | Feb | 150 | | 2021 | Jan | 120 | | 2021 | Feb | 180 | +------+-------+---------+ >>> df.unpivot({ idVars: "metric", valueVars: ["q1", "q2"], varName: "quarter", valueName: "val" }) shape: (4, 3) +--------+---------+-----+ | metric | quarter | val | +--------+---------+-----+ | sales | q1 | 100 | | sales | q2 | 120 | | clicks | q1 | 500 | | clicks | q2 | 600 | +--------+---------+-----+ ``` --- ## Operation Unstacks selected columns into multiple wide columns of size `step`. Reshapes data from long to wide format without aggregation. ### Signature ```typescript df.unstack( columns: IntoExpr | IntoExpr[], options: { fillValues?: any = null, how?: "vertical" | "horizontal" = "vertical", step: number } ): DataFrame ``` ### Parameters - `columns` (any): Column name(s) or selector(s) to unstack. - `options` (any): Unstack configuration options (`step`, `how`, `fillValues`). ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.unstack("a", { step: 2, how: "horizontal" }) shape: (2, 2) +-----+------+ | a_0 | a_1 | +-----+------+ | 1 | 2 | | 3 | null | +-----+------+ ``` --- ## Operation Gets width (total column count) of the DataFrame. ### Signature ```typescript df.width: number ``` ### Returns: `Number of columns.` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.width 2 ``` --- ## Operation Adds new columns or updates existing ones using column expressions. ### Signature ```typescript df.withColumns(...args: (SelectItem | SelectItem[])[]): DataFrame ``` ### Parameters - `args` (SelectArg[]): Expressions or field objects defining column calculations. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.withColumns($df.col("a").mul(10).alias("a_x10")) shape: (2, 3) +---+---+-------+ | a | b | a_x10 | +---+---+-------+ | 1 | x | 10 | | 2 | y | 20 | +---+---+-------+ ``` --- ## Operation Appends an incremental index column. ### Signature ```typescript df.withRowIndex( name: string = "index", offset: number = 0 ): DataFrame ``` ### Parameters - `[name]` (string): Name of index column (default "index"). - `[offset]` (number): Starting numeric index offset (default 0). ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.withRowIndex("idx") shape: (2, 3) +-----+---+---+ | idx | a | b | +-----+---+---+ | 0 | 1 | x | | 1 | 2 | y | +-----+---+---+ ``` --- ## Operation Writes DataFrame to CSV format string or file/stream target. ### Signature ```typescript df.writeCsv( file?: { write: (str: string) => void }, options: { dateFormat?: string, datetimeFormat?: string, includeBom?: boolean = false, includeHeader?: boolean = true, lineTerminator?: string = "\n", nullValue?: string = "", numericFormatOptions?: { accountingNegatives?: boolean = false, fallback?: string = "NaN", formatNonFinite?: boolean = false, locale?: string = "en-US" }, quoteChar?: string = '"', quoteStyle?: "necessary" | "always" | "never" | "non_numeric" = "necessary", replacerOptions?: { bigintStrategy?: "string" | "number" = "string", formatDate?: (v: Date) => string, handleCircular?: boolean = false, onBigInt?: (v: bigint) => any, onCircular?: (this: any, k: string, v: any) => any, onCustom?: (this: any, k: string, v: any) => any, onDate?: (v: Date) => any, onError?: (v: Error) => any, onMap?: (v: Map) => any, onRegExp?: (v: RegExp) => any, onSet?: (v: Set) => any, onTypedArray?: (v: any) => any, onURLSearchParams?: (v: URLSearchParams) => any, replacer?: ((this: any, k: string, v: any) => any) | (string | number)[] | null, voidBigIntReplacement?: boolean = false, voidDateReplacement?: boolean = false, voidMapReplacement?: boolean = false, voidRegExpReplacement?: boolean = false, voidSetReplacement?: boolean = false, voidTypedArrayReplacement?: boolean = false }, separator?: string = ",", timeFormat?: string } = {} ): string ``` ### Parameters - `[file]` (WriteFileTargetArg): Target file path or writable stream target (optional). - `[options]` (WriteCSVOptions): CSV formatting options. ### Returns: `string` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.writeCsv() "a,b\n1,x" ``` --- ## Operation Writes DataFrame rows to JSON format string or file/stream target. ### Signature ```typescript df.writeJson( file?: { write: (str: string) => void }, options: { format?: "json" | "ndjson" = "json", replacerOptions?: { bigintStrategy?: "string" | "number" = "string", formatDate?: (v: Date) => string, handleCircular?: boolean = false, onBigInt?: (v: bigint) => any, onCircular?: (this: any, k: string, v: any) => any, onCustom?: (this: any, k: string, v: any) => any, onDate?: (v: Date) => any, onError?: (v: Error) => any, onMap?: (v: Map) => any, onRegExp?: (v: RegExp) => any, onSet?: (v: Set) => any, onTypedArray?: (v: any) => any, onURLSearchParams?: (v: URLSearchParams) => any, replacer?: ((this: any, k: string, v: any) => any) | (string | number)[] | null, voidBigIntReplacement?: boolean = false, voidDateReplacement?: boolean = false, voidMapReplacement?: boolean = false, voidRegExpReplacement?: boolean = false, voidSetReplacement?: boolean = false, voidTypedArrayReplacement?: boolean = false } } = {} ): string ``` ### Parameters - `[file]` (WriteFileTargetArg): Target file path or writable stream target (optional). - `[options]` (WriteJSONOptions): JSON formatting and replacer options. ### Returns: `string` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.writeJson() '[{"a":1,"b":"x"}]' ``` --- ## Operation Aggregates grouped partitions using aggregation column expressions. ### Signature ```typescript df.groupBy(...exprs: (SelectItem | SelectItem[])[]).agg(...exprs: SelectArg[]): DataFrame ``` ### Parameters - `exprs` (any): One or more aggregation column expressions. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.col("val").sum().alias("sum_val")) shape: (2, 2) +-------+---------+ | group | sum_val | +-------+---------+ | A | 30 | | B | 30 | +-------+---------+ ``` --- ## Operation Converts group keys back into a single distinct DataFrame without aggregations. ### Signature ```typescript df.groupBy(...).toDataframe(): DataFrame ``` ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").toDataframe() shape: (2, 1) +-------+ | group | +-------+ | A | | B | +-------+ ``` --- # Top-Level Functions ## Operation Creates an expression targeting all columns in the DataFrame. ### Signature ```typescript $df.all(): ColumnExpr ``` ### Returns: `ColumnExpr` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.select($df.all()) shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ ``` --- ## Operation Returns the first non-null value among the specified expressions. ### Signature ```typescript $df.coalesce(...exprs: (ScalarArg | ScalarArg[])[]): ColumnExpr ``` ### Parameters - `exprs` (...CoalesceArg): The list of expressions or columns to coalesce. ### Returns: `ColumnExpr` ### Examples ```typescript // 1. Coalesce across multiple columns to pick the first non-null: >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.select($df.coalesce($df.col("a"), $df.col("b")).alias("ab")) shape: (3, 1) +----+ | ab | +----+ | 1 | | 2 | | 3 | +----+ // 2. Coalesce column with a fallback literal value: >>> const df = $df.data({ a: [1, null, 3], b: [null, 2, null] }) >>> df shape: (3, 2) +------+------+ | a | b | +------+------+ | 1 | null | | null | 2 | | 3 | null | +------+------+ >>> df.select($df.coalesce($df.col("a"), $df.lit(0)).alias("a0")) shape: (3, 1) +----+ | a0 | +----+ | 1 | | 0 | | 3 | +----+ ``` --- ## Operation Creates a column expression referencing one or more columns by name, regular expression, or data type. ### Signature ```typescript $df.col(name: keyof T | RegexPatternArg | (keyof T | RegexPatternArg)[] | DataType | Function | (DataType | Function)[]): ColumnExpr ``` ### Parameters - `name` (ColumnSelector): Column name, array of names, RegExp pattern, or DataType selector. ### Returns: `ColumnExpr` ### Examples ```typescript // 1. Select single column by name: >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.select($df.col("a")) shape: (2, 1) +---+ | a | +---+ | 1 | | 2 | +---+ // 2. Select multiple columns via array: >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.select($df.col(["a", "b"])) shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ // 3. Select columns matching a RegExp pattern: >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.select($df.col(/^b$/)) shape: (2, 1) +---+ | b | +---+ | x | | y | +---+ ``` --- ## Operation Concatenates items vertically, horizontally, or diagonally. ### Signature ```typescript $df.concat( rawItems: ConcatItem | ConcatItem[], options: { horizontal?: { strict?: boolean = true }, how?: "vertical" | "horizontal" | "diagonal" = "vertical" } = {} ): DataFrame ``` ### Parameters - `rawItems` (any): Single DataFrame or array of DataFrames/rows to concatenate. - `[options]` (any): Configuration options for concatenation layout and strictness. ### Returns: `DataFrame` ### Examples ```typescript // 1. Vertical Concatenation (default): >>> const df1 = $df.data({ a: [1, 2] }) >>> const df2 = $df.data({ b: [10, 20] }) >>> df1 shape: (2, 1) +---+ | a | +---+ | 1 | | 2 | +---+ >>> df2 shape: (2, 1) +----+ | b | +----+ | 10 | | 20 | +----+ >>> $df.concat([df1, df2], { how: "vertical" }) shape: (4, 1) +------+ | a | +------+ | 1 | | 2 | | null | | null | +------+ // 2. Horizontal Concatenation: >>> const df1 = $df.data({ a: [1, 2] }) >>> const df2 = $df.data({ b: [10, 20] }) >>> df1 shape: (2, 1) +---+ | a | +---+ | 1 | | 2 | +---+ >>> df2 shape: (2, 1) +----+ | b | +----+ | 10 | | 20 | +----+ >>> $df.concat([df1, df2], { how: "horizontal" }) shape: (2, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | +---+----+ // 3. Diagonal Concatenation (mismatched columns): >>> const df1 = $df.data({ a: [1, 2] }) >>> const df2 = $df.data({ b: [10, 20] }) >>> df1 shape: (2, 1) +---+ | a | +---+ | 1 | | 2 | +---+ >>> df2 shape: (2, 1) +----+ | b | +----+ | 10 | | 20 | +----+ >>> $df.concat([df1, df2], { how: "diagonal" }) shape: (4, 2) +------+------+ | a | b | +------+------+ | 1 | null | | 2 | null | | null | 10 | | null | 20 | +------+------+ ``` --- ## Operation Constructs a new DataFrame from an array of row records or a column dictionary. ### Signature ```typescript $df.data( data: T[] | ColumnDict, schema?: Record ): DataFrame ``` ### Parameters - `data` (DataFrameDataArg): Array of row objects or column data dictionary. - `[schema]` (DataFrameSchema): Optional explicit column schema mapping. ### Returns: `DataFrame` ### Examples ```typescript // 1. Construct DataFrame from a column dictionary: >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ // 2. Construct DataFrame from an array of row objects: >>> const df = $df.data([ ... { a: 1, b: "x" }, ... { a: 2, b: "y" } ... ]) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ ``` --- ## Operation Constructs a Duration expression column from numeric values, string intervals, column references, or expressions. ### Signature ```typescript $df.duration( options: { days?: IntoExpr | number, hours?: IntoExpr | number, microseconds?: IntoExpr | number, milliseconds?: IntoExpr | number, minutes?: IntoExpr | number, nanoseconds?: IntoExpr | number, seconds?: IntoExpr | number, weeks?: IntoExpr | number } = {} ): ColumnExpr ``` ### Parameters - `[options]` (DurationArg): Duration component options or string interval (e.g. "1d 12h"). ### Returns: `ColumnExpr` ### Examples ```typescript // 1. Construct from a duration component options object: >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.select($df.col("date").cast($df.Datetime).add($df.duration({ days: 1 })).alias("plus_1_day")) shape: (1, 1) +--------------------------+ | plus_1_day | +--------------------------+ | 2026-05-21T10:00:00.123Z | +--------------------------+ // 2. Construct from a duration string shorthand: >>> const df = $df.data({ date: ["2026-05-20T10:00:00.123Z"] }) >>> df shape: (1, 1) +--------------------------+ | date | +--------------------------+ | 2026-05-20T10:00:00.123Z | +--------------------------+ >>> df.select($df.col("date").cast($df.Datetime).add($df.duration("12h")).alias("plus_12h")) shape: (1, 1) +--------------------------+ | plus_12h | +--------------------------+ | 2026-05-20T22:00:00.123Z | +--------------------------+ ``` --- ## Operation Creates an expression referencing the current element(s) of an array during evaluation. Primarily used inside array operations like `filter`, `map`, or `eval`. ### Signature ```typescript $df.element(): ColumnExpr ``` ### Returns: `ColumnExpr` ### Examples ```typescript // 1. Filter elements within array cells: >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.select($df.col("a").arr.filter($df.element().gt(2)).alias("filtered")) shape: (2, 1) +----------+ | filtered | +----------+ | [3] | | [4, 5] | +----------+ // 2. Perform element-wise calculation across array cells: >>> const df = $df.data({ a: [[1, 2, 3], [4, 5]] }) >>> df shape: (2, 1) +-----------+ | a | +-----------+ | [1, 2, 3] | | [4, 5] | +-----------+ >>> df.select($df.col("a").arr.eval($df.element().mul(10)).alias("scaled")) shape: (2, 1) +--------------+ | scaled | +--------------+ | [10, 20, 30] | | [40, 50] | +--------------+ ``` --- ## Operation Creates an expression targeting all columns except the specified ones. ### Signature ```typescript $df.exclude(columns: string | string[]): ColumnExpr ``` ### Parameters - `columns` (ColumnKeyArg): The name or names of columns to exclude. ### Returns: `ColumnExpr` ### Examples ```typescript // 1. Exclude a single column by name: >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.select($df.exclude("a")) shape: (2, 1) +---+ | b | +---+ | x | | y | +---+ // 2. Exclude a single column from a multi-column dataset: >>> const df = $df.data({ a: [1, 2, 3], b: [10, 20, 30] }) >>> df shape: (3, 2) +---+----+ | a | b | +---+----+ | 1 | 10 | | 2 | 20 | | 3 | 30 | +---+----+ >>> df.select($df.exclude("a")) shape: (3, 1) +----+ | b | +----+ | 10 | | 20 | | 30 | +----+ ``` --- ## Operation Combines multiple columns or expressions horizontally into an array per row, allowing expression evaluation with `.eval($df.element()...)`, direct horizontal aggregations (`.sum()`, `.min()`, `.max()`, `.mean()`), or `.arr` operations across columns. ### Signature ```typescript $df.horizontal(...exprs: (IntoExpr | IntoExpr[])[]): HorizontalExpr ``` ### Parameters - `exprs` (...IntoExprArg): Column names, expressions, selectors (e.g. `$df.all()`), or arrays of them. ### Returns: `HorizontalExpr` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.select($df.horizontal("a", "b").sum().alias("row_sum")) shape: (2, 1) +---------+ | row_sum | +---------+ | 1 | | 2 | +---------+ ``` --- ## Operation Aggregates values of a column into a list within each group. ### Signature ```typescript $df.implode(column: IntoExpr | IntoExpr[]): ColumnExpr ``` ### Parameters - `column` (IntoExprArg): The column or expression to implode. ### Returns: `ColumnExpr` ### Examples ```typescript >>> const df = $df.data({ group: ["A", "A", "B"], val: [10, 20, 30] }) >>> df shape: (3, 2) +-------+-----+ | group | val | +-------+-----+ | A | 10 | | A | 20 | | B | 30 | +-------+-----+ >>> df.groupBy("group").agg($df.implode("val").alias("imploded")) shape: (2, 2) +-------+----------+ | group | imploded | +-------+----------+ | A | [10, 20] | | B | [30] | +-------+----------+ ``` --- ## Operation Creates a literal column expression that repeats the given value for all rows. ### Signature ```typescript $df.lit( value: any, options: { dtype?: Int8Type | Int16Type | Int32Type | Int64Type | UInt8Type | UInt16Type | UInt32Type | UInt64Type | Float32Type | Float64Type | DecimalType | BooleanType | Utf8Type | BinaryType | NullType | ObjectType | DateType | DatetimeType | TimeType | DurationType | ArrayType | StructType, name?: string } = {} ): ColumnExpr ``` ### Parameters - `value` (any): The literal value (number, string, boolean, etc.). - `[options]` (any): Configuration options. ### Returns: `ColumnExpr` ### Examples ```typescript // 1. Literal number repeated for every row: >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.select($df.lit(42).alias("answer")) shape: (2, 1) +--------+ | answer | +--------+ | 42 | | 42 | +--------+ // 2. Literal string repeated across rows: >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.withColumns($df.lit("active").alias("status")) shape: (2, 3) +---+---+--------+ | a | b | status | +---+---+--------+ | 1 | x | active | | 2 | y | active | +---+---+--------+ ``` --- ## Operation Reads a CSV string and constructs a DataFrame. Automatically infers column data types unless an explicit schema is provided. ### Signature ```typescript $df.readCsv( content: string, options: { hasHeader?: boolean = true, inferSchema?: boolean = true, nullValues?: string[] = ["", "NA", "null", "NaN"], quoteChar?: string = '"', schema?: Record, separator?: string = "," } = {} ): DataFrame ``` ### Parameters - `content` (any): The CSV content string. - `[options]` (any): Parse and configuration options. ### Returns: `DataFrame` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> $df.readCsv("a,b\n1,x\n2,y") shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ ``` --- ## Operation Parses JSON content (JSON or NDJSON) and loads it into a new DataFrame. ### Signature ```typescript $df.readJson( content: string, options: { allowPrimitives?: boolean = false, format?: "json" | "ndjson" = "json", ndjson?: { maxLines?: number, skipInvalidLines?: boolean = false, skipLines?: number = 0 }, reviver?: Parameters[1], schema?: Record, trimBeforeParse?: boolean = false } = {} ): DataFrame ``` ### Parameters - `content` (any): The JSON or NDJSON content string. - `[options]` (any): Parse and configuration options. ### Returns: `A new DataFrame instance populated with the parsed records.` ### Examples ```typescript >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> $df.readJson('[{"a":1,"b":"x"},{"a":2,"b":"y"}]') shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ ``` --- ## Operation Creates a column expression that generates a range of values. If mode is "cumulative" (default) or "independent", it generates a sequence. If mode is "constant", it repeats the given value. ### Signature ```typescript $df.seqRange( value: any, options: { dtype?: Int8Type | Int16Type | Int32Type | Int64Type | UInt8Type | UInt16Type | UInt32Type | UInt64Type | Float32Type | Float64Type | DecimalType | BooleanType | Utf8Type | BinaryType | NullType | ObjectType | DateType | DatetimeType | TimeType | DurationType | ArrayType | StructType, endIndex?: number, mode?: "constant" | "cumulative" | "independent" = "cumulative", n?: number = the slice or DataFrame height, name?: string, pad?: boolean = false, padValue?: any = null, startIndex?: number = 0, step?: number | ((context: CumulativeStepContext & IndependentStepContext) => any) = 1, strict?: boolean = true, truncate?: boolean = false } = { strict: true } ): ColumnExpr ``` ### Parameters - `value` (any): The initial value to start the sequence or the constant value to repeat. - `[options]` (any): Configuration options. ### Returns: `ColumnExpr` ### Examples ```typescript // 1. Ascending stepping sequence: >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.seqRange(1, { step: 2 }).alias("odd")) shape: (3, 1) +-----+ | odd | +-----+ | 1 | | 3 | | 5 | +-----+ // 2. Descending stepping sequence: >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select($df.seqRange(10, { step: -1 }).alias("countdown")) shape: (3, 1) +-----------+ | countdown | +-----------+ | 10 | | 9 | | 8 | +-----------+ ``` --- ## Operation Packages multiple expressions into a structured object column. ### Signature ```typescript $df.struct( fields: StructFieldsArg | IntoExpr, ...moreFields: (RegexPatternArg | IExpr)[] ): ColumnExpr ``` ### Parameters - `fields` (StructArg): An array of expressions, a record of field names to expressions, or a single expression. - `moreFields` (...IntoExpr[]): Additional fields when a single expression is passed as the first parameter. ### Returns: `ColumnExpr` ### Examples ```typescript // 1. Package fields using an object property mapping: >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.select($df.struct({ x: "a", y: "b" }).alias("coord")) shape: (2, 1) +------------------+ | coord | +------------------+ | { x: 1, y: "x" } | | { x: 2, y: "y" } | +------------------+ // 2. Package positional column expressions directly into a struct: >>> const df = $df.data({ a: [1, 2], b: ["x", "y"] }) >>> df shape: (2, 2) +---+---+ | a | b | +---+---+ | 1 | x | | 2 | y | +---+---+ >>> df.select($df.struct($df.col("a"), $df.col("b")).alias("pair")) shape: (2, 1) +------------------+ | pair | +------------------+ | { a: 1, b: "x" } | | { a: 2, b: "y" } | +------------------+ ``` --- ## Operation Provides conditional branch evaluations inside column expressions. ### Signature ```typescript $df.when(predicate: ComparisonArg | RowRecord | any[]): WhenThenChain ``` ### Parameters - `predicate` (WhenArg): The boolean condition or expression. ### Returns: `WhenThenChain` ### Examples ```typescript // 1. Binary condition with otherwise fallback: >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select( ... $df.when($df.col("a").gt(2)).then("High") ... .otherwise("Low").alias("tier") ... ) shape: (3, 1) +------+ | tier | +------+ | Low | | Low | | High | +------+ // 2. Multi-case conditional chaining: >>> const df = $df.data({ a: [1, 2, 3] }) >>> df shape: (3, 1) +---+ | a | +---+ | 1 | | 2 | | 3 | +---+ >>> df.select( ... $df.when($df.col("a").eq(1)).then("One") ... .when($df.col("a").eq(2)).then("Two") ... .otherwise("Other").alias("label") ... ) shape: (3, 1) +-------+ | label | +-------+ | One | | Two | | Other | +-------+ ``` --- # Data Types # Type Definitions ### ColumnExpr ```typescript export interface ColumnExpr extends StandardExpr, StringExpr, TemporalExpr, ArrayExpr, StructExpr { } ``` ### StructExprNamespace ```typescript export interface StructExprNamespace { /** Dynamic struct field accessor returning a `ColumnExpr` for the given property key. */ [key: string]: any; } ``` ### ArrayArg ```typescript export type ArrayArg = IExpr | ValidScalarTypes[] | AnyTypedArray; ``` ### BetweenOptions ```typescript export interface BetweenOptions { /** * Controls boundary inclusivity: * - `"both"`: `lower <= x <= upper` (default) * - `"left"`: `lower <= x < upper` * - `"right"`: `lower < x <= upper` * - `"none"`: `lower < x < upper` * @default "both" */ closed?: ClosedBoundary; } ``` ### BooleanArg ```typescript export type BooleanArg = ColumnKeyArg | IExpr | null | undefined; ``` ### ComparisonArg ```typescript export type ComparisonArg = ScalarArg | ArrayArg; ``` ### CountMatchesOptions ```typescript export interface CountMatchesOptions { /** * If true, treats the pattern as a literal string rather than a regular expression. * @default false */ literal?: boolean; } ``` ### CountOptions ```typescript export interface CountOptions { /** * Whether to include `null`, `undefined`, or `NaN` values in the count. * When `false`, counts only non-null, valid elements. * @default false */ includeNulls?: boolean; } ``` ### EwmKurtOptions ```typescript export type EwmKurtOptions = EwmOptions; ``` ### EwmMeanOptions ```typescript export type EwmMeanOptions = Omit; ``` ### EwmOptions ```typescript export interface EwmOptions extends CentralMomentsOptions, KurtosisOptions { /** * When `true`, divides by the decaying adjustment factor in beginning periods to account for imbalance in relative weightings. * @default true */ adjust?: boolean; /** * Smoothing factor `alpha` directly in `(0, 1]`. Mutually exclusive with `span`, `halfLife`, and `com`. */ alpha?: number; /** * When `false`, applies sample bias correction; when `true`, computes population moments without bias correction. * @default false */ bias?: boolean; /** * Optional timestamp/index column name or expression used to scale `halfLife` decay by elapsed time deltas. */ by?: ColumnOrExprArg; /** * Decay in terms of center of mass (`alpha = 1 / (1 + com)`), where `com >= 0`. */ com?: number; /** * When `true` (default), computes excess kurtosis (Fisher's definition, subtracting 3.0); when `false`, computes Pearson's kurtosis. * @default true */ fisher?: boolean; /** * Decay in terms of half-life (`alpha = 1 - exp(-ln(2) / halfLife)`), as a positive number or duration string. */ halfLife?: DurationValueArg; /** * When `true`, ignores missing/null values when calculating weights; when `false`, weights decay across null positions. * @default false */ ignoreNulls?: boolean; /** * Minimum number of non-null observations in window required to produce a value (otherwise `null`). * @default 1 */ minSamples?: number; /** * Decay in terms of span (`alpha = 2 / (span + 1)`), where `span >= 1`. */ span?: number; } ``` ### EwmSkewOptions ```typescript export type EwmSkewOptions = Omit; ``` ### EwmStdOptions ```typescript export type EwmStdOptions = Omit; ``` ### EwmSumOptions ```typescript export type EwmSumOptions = Omit; ``` ### EwmVarOptions ```typescript export type EwmVarOptions = Omit; ``` ### IsCloseOptions ```typescript export interface IsCloseOptions { /** * Non-negative absolute tolerance threshold. * @default 1e-8 */ absTol?: number; /** * When `true`, two `NaN` values are treated as close (`true`). * @default false */ nansEqual?: boolean; /** * Non-negative relative tolerance threshold scaled by operand magnitude. * @default 1e-8 */ relTol?: number; } ``` ### IsNDistinctOptions ```typescript export interface IsNDistinctOptions { /** * If true (default), returns null when index is out of bounds. * If false, throws an error if index is out of bounds. * @default true */ nullOnOob?: boolean; } ``` ### NumericArg ```typescript export type NumericArg = number | bigint | IExpr | null; ``` ### NumericSeriesArg ```typescript export type NumericSeriesArg = NumericArg | number[] | AnyTypedArray; ``` ### ProxyPropertyResolver ```typescript export type ProxyPropertyResolver = (prop: string, target: T) => any; ``` ### RandomOptions ```typescript export interface RandomOptions { /** * When `true`, generates random integers in `[min, max]`. When `false`, generates floating-point numbers in `[min, max)`. * @default false */ integer?: boolean; /** * Maximum bound (exclusive for floats, inclusive for integers) for generated random values. * @default 1 */ max?: number; /** * Minimum bound (inclusive) for generated random values. * @default 0 */ min?: number; } ``` ### RankOptions ```typescript export interface RankOptions { /** * When true, ranks are consecutive integers without gaps between tied values (1, 2, 2, 3). * When false (default), ranks have gaps for tied values (1, 2, 2, 4). * @default false */ dense?: boolean; } ``` ### ReplaceAllOptions ```typescript export type ReplaceAllOptions = Omit; ``` ### RollingOptions ```typescript export interface RollingOptions { /** * Number of consecutive elements in the moving window. */ windowSize: number; } ``` ### ShiftOptions ```typescript export interface ShiftOptions { /** * Fallback fill value for empty slots introduced by shift/lag/lead. * @default null */ fillValue?: any; } ``` ### StringArg ```typescript export type StringArg = ColumnOrExprArg; ``` ### StringDecodeOptions ```typescript export interface StringDecodeOptions extends StringEncodeOptions { /** * Whether invalid encoded sequences should throw an error (`true`) or return `null` (`false`). * @default true */ strict?: boolean; } ``` ### StringEncodeOptions ```typescript export interface StringEncodeOptions { /** * Target string encoding format (`"hex"` or `"base64"`). */ encoding: StringEncoding; } ``` ### StringReplacementArg ```typescript export type StringReplacementArg = string | StringReplacerFn; ``` ### StringReplacementSeriesArg ```typescript export type StringReplacementSeriesArg = StringReplacementArg[]; ``` ### StringReplacerArg ```typescript export type StringReplacerArg = ValidScalarTypes | RowRecord; ``` ### StringReplacerFn ```typescript export type StringReplacerFn = (match: string, ...args: StringReplacerArg[]) => string; ``` ### ToStructOptions ```typescript export interface ToStructOptions { /** * Explicit array of struct field names or a callback `(idx: number) => string` generating field names by element index. Defaults to `"field_0"`, `"field_1"`, etc. */ fields?: string[] | ((idx: number) => string); /** * Maximum number of array elements to extract into struct fields when `fields` is not an array. Defaults to the maximum array length in the column. */ upperBound?: number; } ``` ### UnicodeNormalizeForm ```typescript export type UnicodeNormalizeForm = "NFC" | "NFD" | "NFKC" | "NFKD"; ``` ### GroupedData ```typescript export interface GroupedData extends GroupedAggDelegatedOps { } ``` ### CastTargetArg ```typescript export type CastTargetArg = RegisteredDataType | DataFrameSchema; ``` ### DataFrameColumns ```typescript export type DataFrameColumns = { /** * Column data array or typed array for column `K`. */ [K in keyof T]: ColumnData; }; ``` ### DataFrameShape ```typescript export type DataFrameShape = [number, number]; ``` ### DynamicIndexColumnArg ```typescript export type DynamicIndexColumnArg = K | IntoExpr; ``` ### DynamicLabel ```typescript export type DynamicLabel = "left" | "right" | "datapoint"; ``` ### DynamicStartBy ```typescript export type DynamicStartBy = "window" | "datapoint" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday"; ``` ### EqualsOptions ```typescript export interface EqualsOptions { /** * Whether nulls and NaNs compare as equal. * @default true */ nullsEqual?: boolean; } ``` ### FilterPredicate ```typescript export type FilterPredicate = IExpr | RowPredicateFn; ``` ### FilterPredicateArg ```typescript export type FilterPredicateArg = ColumnKeyArg>; ``` ### GroupByDynamicOptions ```typescript export interface GroupByDynamicOptions { /** * Additional columns to partition / group by before dynamic windowing. */ by?: ColumnKeyArg; /** * Verify whether index column is sorted in ascending order. * @default true */ checkSorted?: boolean; /** * Which boundary of the window interval is closed (`"left"`, `"right"`, `"both"`, `"none"`). * @default "left" */ closed?: ClosedBoundary; /** * Time interval window step period (e.g. `"1d"`, `"1h"`, `1000`). */ every: DurationValueArg; /** * Polars alias for `by`. */ groupBy?: ColumnKeyArg; /** * Include the lower and upper window boundaries (`_lower_boundary`, `_upper_boundary`). * @default false */ includeBoundaries?: boolean; /** * Which window boundary to use as the timestamp label (`"left"`, `"right"`, `"datapoint"`). * @default "left" */ label?: DynamicLabel; /** * Offset window start by a duration. * @default 0 */ offset?: DurationValueArg; /** * Time period duration window width. Defaults to `every` if omitted. */ period?: DurationValueArg; /** * Strategy to determine window start (`"window"`, `"datapoint"`, or day of week). * @default "window" */ startBy?: DynamicStartBy; /** * Truncate the index column values to the window start. * @default true */ truncate?: boolean; } ``` ### GroupedAggDelegatedMethodNames ```typescript export type GroupedAggDelegatedMethodNames = | "all" | "avg" | "count" | "first" | "kurtosis" | "last" | "max" | "mean" | "median" | "min" | "nUnique" | "skew" | "std" | "sum" | "variance"; ``` ### GroupedAggDelegatedOps ```typescript export type GroupedAggDelegatedOps = { /** * Executes aggregation `K` across all non-key columns in each group. */ [K in GroupedAggDelegatedMethodNames]: (...args: Parameters[K]>) => DataFrame; }; ``` ### GroupMap ```typescript export type GroupMap = Map; ``` ### InsertColumnArg ```typescript export type InsertColumnArg = IntoExpr | ArrayLike; ``` ### IterRowResult ```typescript export type IterRowResult = any[] | T; ``` ### IterRowsOptions ```typescript export interface IterRowsOptions { /** * When `true`, yields row objects with column keys (`{ col: val }`). * When `false` (default), yields positional arrays (`[val1, val2]`). * @default false */ named?: boolean; } ``` ### JoinAsofOptions ```typescript export interface JoinAsofOptions { /** * Whether exact key matches are permitted. * @default true */ allowExactMatches?: boolean; /** * Optional exact-match group column(s) present in both DataFrames. */ by?: ColumnKeyArg; /** * Whether to verify that join keys are sorted ascending prior to matching. * @default true */ checkSorted?: boolean; /** * Coalescing behavior for join key columns. * @default true */ coalesce?: boolean; /** * Group column(s) for exact key matching in left DataFrame. */ leftBy?: ColumnKeyArg; /** * Left DataFrame join key column name. */ leftOn?: (keyof T); /** * Column name to join on (must exist in both DataFrames and be sorted ascending). */ on?: (keyof T & keyof U); /** * Group column(s) for exact key matching in right DataFrame. */ rightBy?: ColumnKeyArg; /** * Right DataFrame join key column name. */ rightOn?: (keyof U); /** * Match search strategy (`"backward"`, `"forward"`, or `"nearest"`). * @default "backward" */ strategy?: JoinAsofStrategy; /** * Column name suffixes `[leftSuffix, rightSuffix]` to resolve name collisions. * @default ["", "_right"] */ suffixes?: JoinSuffixes; /** * Maximum allowed distance between left key and right key. */ tolerance?: DurationValueArg; } ``` ### JoinAsofStrategy ```typescript export type JoinAsofStrategy = "backward" | "forward" | "nearest"; ``` ### JoinMaintainOrder ```typescript export type JoinMaintainOrder = "none" | "left" | "right" | "left_right" | "right_left"; ``` ### JoinOptions ```typescript export interface JoinOptions { /** * Coalescing behavior for join key columns. If `true`, coalesces join key values into left key columns and drops right key columns. * @default true */ coalesce?: boolean; /** * Join strategy (`"inner"`, `"left"`, `"right"`, `"outer"`, `"semi"`, `"anti"`, or `"cross"`). * @default "inner" */ how?: JoinType; /** * If `true`, null key values are treated as equal and match each other across DataFrames. * @default false */ joinNulls?: boolean; /** * Join key column(s) in the left DataFrame when key names differ. */ leftOn?: ColumnKeyArg; /** * Row order preservation strategy (`"none"`, `"left"`, `"right"`, `"left_right"`, `"right_left"`, or boolean). * @default "none" */ maintainOrder?: JoinMaintainOrder | boolean; /** * Join key column name or array of key column names that exist in both DataFrames. */ on?: ColumnKeyArg; /** * Join key column(s) in the right DataFrame when key names differ. */ rightOn?: ColumnKeyArg; /** * Suffix tuple `[leftSuffix, rightSuffix]` appended to overlapping non-key column names. Ignored for `"semi"` and `"anti"` joins. * @default ["", "_right"] */ suffixes?: JoinSuffixes; } ``` ### JoinSuffixes ```typescript export type JoinSuffixes = [string, string]; ``` ### JoinType ```typescript export type JoinType = "inner" | "outer" | "left" | "right" | "semi" | "anti" | "cross"; ``` ### JoinWhereArg ```typescript export type JoinWhereArg = IntoExprArg | JoinWhereOptions; ``` ### JoinWhereOptions ```typescript export interface JoinWhereOptions { /** * Join strategy: `"inner"`, `"left"`, or `"right"`. * @default "inner" */ how?: JoinWhereStrategy; /** * Column name suffixes `[leftSuffix, rightSuffix]` to resolve duplicate column names. * @default ["", "_right"] */ suffixes?: JoinSuffixes; } ``` ### JoinWhereStrategy ```typescript export type JoinWhereStrategy = "inner" | "left" | "right"; ``` ### LimitOptions ```typescript export interface LimitOptions { /** * Slice direction starting point (`"start"` or `"end"`). * @default "start" */ from?: LimitPosition; /** * Number of rows to skip before taking `n` rows. * @default 0 */ offset?: number; } ``` ### LimitPosition ```typescript export type LimitPosition = "start" | "end"; ``` ### PartitionByKey ```typescript export type PartitionByKey = ColumnOrExprArg; ``` ### PartitionByOptions ```typescript export interface PartitionByOptions { /** * If true, returns a Record/dictionary mapping each partition key string to its DataFrame. * If false (default), returns an array of DataFrames. * @default false */ asDict?: boolean; /** * If true (default), maintain original encounter order of partitions. * @default true */ maintainOrder?: boolean; } ``` ### PartitionByResult ```typescript export type PartitionByResult = DataFrame[] | Record>; ``` ### PivotOptions ```typescript export interface PivotOptions { /** * Aggregation function to apply when multiple values exist for a cell. */ agg?: AggFn | string; /** * Column whose distinct values become new wide column headers. */ columns: keyof T; /** * Key column(s) to use as new DataFrame rows. */ index: ColumnKeyArg; /** * Column whose cell values populate the pivoted grid cells. */ values: keyof T; } ``` ### RowPredicateFn ```typescript export type RowPredicateFn = (row: T) => any; ``` ### SelectArg ```typescript export type SelectArg = ColumnKeyArg; ``` ### SelectItem ```typescript export type SelectItem = ColumnOrExprArg | RowRecord; ``` ### SortOptions ```typescript export interface SortOptions extends SortArrayOptions { /** * Column name(s) or expression(s) to sort by. */ by: ColumnKeyArg | ColumnKeyArg; /** * Optional comparator function or dictionary mapping column names to custom comparator functions. */ customComp?: ((a: any, b: any) => number) | Partial number>> | null; /** * Sort order boolean or array of booleans per key. * @default false */ descending?: ColumnKeyArg; /** * When `true`, places nulls at the end of sorted output. * @default true */ nullsLast?: boolean; } ``` ### TransposeColumnNamesArg ```typescript export type TransposeColumnNamesArg = string | Iterable; ``` ### TransposeOptions ```typescript export interface TransposeOptions { /** * Column name or iterable of strings to use as transposed column headers. */ columnNames?: TransposeColumnNamesArg; /** * Name of the header column when `includeHeader` is `true`. * @default "column" */ headerName?: string; /** * When `true`, includes original column names as a new header column. * @default false */ includeHeader?: boolean; } ``` ### UnpivotOptions ```typescript export interface UnpivotOptions { /** * Key column(s) to retain as identifier variables. */ idVars: ColumnKeyArg; /** * Name for the new value column holding cell values. * @default "value" */ valueName?: string; /** * Column(s) to unpivot into variable-value pairs. */ valueVars: ColumnKeyArg; /** * Name for the new variable column holding old column headers. * @default "variable" */ varName?: string; } ``` ### UnstackDirection ```typescript export type UnstackDirection = "vertical" | "horizontal"; ``` ### UnstackOptions ```typescript export interface UnstackOptions { /** * Value to fill in empty cells when length is not evenly divisible by step. * @default null */ fillValues?: any; /** * Reshaping direction: * - "vertical" (default): fills down the new columns first before moving to the next column. * - "horizontal": fills across row-by-row before moving to the next row. * @default "vertical" */ how?: UnstackDirection; /** * Number of columns to reshape each input column into. */ step: number; } ``` ### WritableStreamTarget ```typescript export interface WritableStreamTarget { /** * Writes a serialized string chunk to the underlying stream target. */ write: (str: string) => void; } ``` ### WriteFileTargetArg ```typescript export type WriteFileTargetArg = string | WritableStreamTarget; ``` ### WriteJSONOptions ```typescript export interface WriteJSONOptions { /** * The format of the JSON output (`"json"` or `"ndjson"`). * @default "json" */ format?: JSONFormat; /** * Options for the safe JSON replacer. */ replacerOptions?: SafeJsonReplacerOptions; } ``` ### RegisteredDataType ```typescript export type RegisteredDataType = | Int8Type | Int16Type | Int32Type | Int64Type | UInt8Type | UInt16Type | UInt32Type | UInt64Type | Float32Type | Float64Type | DecimalType | BooleanType | Utf8Type | BinaryType | NullType | ObjectType | DateType | DatetimeType | TimeType | DurationType | ArrayType | StructType; ``` ### CoalesceArg ```typescript export type CoalesceArg = ColumnKeyArg; ``` ### DurationArg ```typescript export type DurationArg = DurationOptions | string; ``` ### DurationComponentArg ```typescript export type DurationComponentArg = IntoExpr | number; ``` ### DurationOptions ```typescript export interface DurationOptions { /** Number of days or column expression. */ days?: DurationComponentArg; /** Number of hours or column expression. */ hours?: DurationComponentArg; /** Number of microseconds or column expression. */ microseconds?: DurationComponentArg; /** Number of milliseconds or column expression. */ milliseconds?: DurationComponentArg; /** Number of minutes or column expression. */ minutes?: DurationComponentArg; /** Number of nanoseconds or column expression. */ nanoseconds?: DurationComponentArg; /** Number of seconds or column expression. */ seconds?: DurationComponentArg; /** Number of weeks or column expression. */ weeks?: DurationComponentArg; } ``` ### HorizontalExpr ```typescript export type HorizontalExpr = ColumnExpr & ArrayExprNamespace; ``` ### LitOptions ```typescript export interface LitOptions { /** * Registered data type to coerce and allocate for the literal column. */ dtype?: RegisteredDataType; /** * Output column name alias. */ name?: string; } ``` ### SeqRangeOptions ```typescript export interface SeqRangeOptions { /** * Registered data type to coerce and allocate for the generated sequence. */ dtype?: RegisteredDataType; /** * Ending row index (exclusive) in the DataFrame to insert the sequence (non-strict mode). */ endIndex?: number; /** * Sequence generation mode: `"constant"` repeats the initial value, `"cumulative"` increments from the previous value, and `"independent"` computes each element from its row index. * @default "cumulative" */ mode?: "constant" | "cumulative" | "independent"; /** * Number of values to generate. Defaults to the slice or DataFrame height. */ n?: number; /** * Output column name alias. */ name?: string; /** * Pads the sequence with `padValue` if shorter than target slice range (non-strict mode). * @default false */ pad?: boolean; /** * Value used for padding in non-strict mode. * @default null */ padValue?: any; /** * Starting row index in the DataFrame to insert the sequence (non-strict mode). * @default 0 */ startIndex?: number; /** * Step increment/multiplier value or step callback function. * @default 1 */ step?: number | ((context: CumulativeStepContext & IndependentStepContext) => any); /** * When `true`, throws a `ShapeError` if the generated sequence height does not match the target height. When `false`, allows padding, truncation, and slice bounds. * @default true */ strict?: boolean; /** * Truncates the sequence if it exceeds target slice range (non-strict mode). * @default false */ truncate?: boolean; } ``` ### StructArg ```typescript export type StructArg = StructFieldsArg | IntoExpr; ``` ### WhenArg ```typescript export type WhenArg = ComparisonArg | RowRecord | any[]; ``` ### AggFn ```typescript export type AggFn = (values: V[]) => R; ``` ### AnyTypedArray ```typescript export type AnyTypedArray = | Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array; ``` ### BusinessDayRollType ```typescript export type BusinessDayRollType = "raise" | "forward" | "backward"; ``` ### CastOptions ```typescript export interface CastOptions { /** * Whether cast errors should throw or produce `null` values. * @default true */ strict?: boolean; } ``` ### CentralMomentsOptions ```typescript export interface CentralMomentsOptions { /** * Whether to apply exponentially weighted bias adjustment. * @default true */ adjust?: boolean; /** * Minimum number of valid observations required to return a non-null result. * @default 1 */ minSamples?: number; } ``` ### CentralMomentsResult ```typescript export interface CentralMomentsResult { /** Number of valid numeric observations processed. */ count: number; /** Weighted 2nd central moment sum ($\sum w_i (x_i - \mu)^2$). */ m2Sum: number; /** Weighted 3rd central moment sum ($\sum w_i (x_i - \mu)^3$). */ m3Sum: number; /** Weighted 4th central moment sum ($\sum w_i (x_i - \mu)^4$). */ m4Sum: number; /** Weighted arithmetic mean, or `null` if `count < minSamples`. */ mean: number | null; /** Sample or weighted standard deviation, or `null` if insufficient samples. */ std: number | null; /** Sum of weights across valid observations. */ sumW: number; /** Sample or weighted variance, or `null` if insufficient samples. */ variance: number | null; /** Weighted sum of observation values. */ weightedSum: number; } ``` ### ClosedBoundary ```typescript export type ClosedBoundary = "both" | "left" | "right" | "none"; ``` ### ColumnData ```typescript export type ColumnData = ArrayLike & Iterable; ``` ### ColumnDict ```typescript export type ColumnDict = Record; ``` ### ColumnIndexOrNameArg ```typescript export type ColumnIndexOrNameArg = number | string; ``` ### ColumnKeyArg ```typescript export type ColumnKeyArg = K | K[]; ``` ### ColumnOrExprArg ```typescript export type ColumnOrExprArg = K | IExpr; ``` ### ColumnSelector ```typescript export type ColumnSelector = | ColumnKeyArg | ColumnKeyArg; ``` ### ConcatHow ```typescript export type ConcatHow = "vertical" | "horizontal" | "diagonal"; ``` ### ConcatItem ```typescript export type ConcatItem = DataFrame | DataFrameDataArg; ``` ### ConcatItemsArg ```typescript export type ConcatItemsArg = ColumnKeyArg; ``` ### ConcatOptions ```typescript export interface ConcatOptions { /** * Configuration options specific to horizontal concatenation. */ horizontal?: HorizontalConcatOptions; /** * Layout strategy: `"vertical"` (appends rows top-to-bottom), `"horizontal"` (joins unique columns side-by-side), or `"diagonal"` (concatenates mismatched columns with null padding). * @default "vertical" */ how?: ConcatHow; } ``` ### DataFrameDataArg ```typescript export type DataFrameDataArg = T[] | ColumnDict; ``` ### DataFrameSchema ```typescript export type DataFrameSchema = Record; ``` ### DateTimeParts ```typescript export interface DateTimeParts { /** 1-indexed day of the month from 1 to 31. */ day: number; /** 0-indexed day of week (0 = Sunday, 6 = Saturday). */ dayOfWeek?: number; /** 0-indexed hour of day from 0 to 23 (0 = Midnight). */ hour: number; /** 0-indexed minute of hour from 0 to 59. */ minute: number; /** 1-indexed calendar month from 1 to 12 (1 = January, 12 = December). */ month: number; /** 0-indexed millisecond from 0 to 999. */ ms: number; /** 0-indexed second of minute from 0 to 59. */ second: number; /** Optional target timezone identifier (e.g. "UTC", "America/New_York"). */ timeZone?: string | null; /** Calendar year (e.g. 2026). */ year: number; } ``` ### DatetimeTimeUnit ```typescript export type DatetimeTimeUnit = "ms" | "us" | "ns"; ``` ### DayOffsetOptions ```typescript export interface DayOffsetOptions extends IsBusinessDayOptions { /** * ISO weekday numbers (`1 = Monday` ... `7 = Sunday`) considered non-business weekend days. * @default [6, 7] */ excludeWeekdays?: number[]; /** * List or set of holiday dates (`Date`, ISO date string, or UTC timestamp) to exclude as business days. */ holidays?: (Date | string | number)[] | Set; /** * How to handle a starting date that falls on a non-business day: `"raise"`, `"forward"`, or `"backward"`. * @default "raise" */ roll?: BusinessDayRollType; } ``` ### DurationValueArg ```typescript export type DurationValueArg = number | string; ``` ### EntropyOptions ```typescript export interface EntropyOptions { /** * Logarithm base used to compute entropy. * @default Math.E */ base?: number; /** * If `true`, normalizes categorical value frequencies; if `false`, treats numeric values directly as discrete probabilities. * @default true */ normalize?: boolean; } ``` ### EscapeRegexMode ```typescript export type EscapeRegexMode = "tc39" | "nonAlphanumericAscii"; ``` ### EscapeRegexOptions ```typescript export interface EscapeRegexOptions { /** * Escaping mode: `"tc39"` (ECMAScript `RegExp.escape` specification) or `"nonAlphanumericAscii"` (escapes all `[^A-Za-z0-9]`). * @default "tc39" */ mode?: EscapeRegexMode; } ``` ### ExplodeOptions ```typescript export interface ExplodeOptions { /** * When `true`, converts empty arrays to `null` rows. * @default true */ emptyAsNull?: boolean; /** * When `true`, retains `null` array values during explosion. * @default true */ keepNulls?: boolean; } ``` ### ExprDict ```typescript export type ExprDict = Record; ``` ### ExtractManyOptions ```typescript export interface ExtractManyOptions extends ExtractRegexEngineOptions { /** * Whether matching should be case-insensitive for ASCII characters. * @default false */ asciiCaseInsensitive?: boolean; /** * Whether to return all matches (global flag). * @default false */ global?: boolean; /** * 0-based index or name of the capture group to extract. * @default 0 */ groupIndex?: ColumnIndexOrNameArg; /** * Guarantees that the leftmost match is selected when multiple patterns match. Cannot be combined with `overlapping: true`. * @default false */ leftmost?: boolean; /** * Whether overlapping matches across patterns are allowed. * @default false */ overlapping?: boolean; } ``` ### ExtractRegexEngineOptions ```typescript export interface ExtractRegexEngineOptions { /** * Whether matching should be case-insensitive for ASCII characters. * @default false */ asciiCaseInsensitive?: boolean; /** * Whether to return all matches (global flag). * @default false */ global?: boolean; /** * 0-based index or name of the capture group to extract. * @default 1 */ groupIndex?: ColumnIndexOrNameArg; } ``` ### FillNullOptions ```typescript export type FillNullOptions = FillOptions; ``` ### FillNullStrategy ```typescript export type FillNullStrategy = "forward" | "backward" | "min" | "max" | "mean" | "zero" | "one"; ``` ### FillOptions ```typescript export interface FillOptions { /** * Maximum number of consecutive target values to fill when using directional strategies (`"forward"`, `"backward"`). */ limit?: number; /** * Filling strategy to calculate or propagate replacement values (`"forward"`, `"backward"`, `"min"`, `"max"`, `"mean"`, `"zero"`, `"one"`). */ strategy?: FillNullStrategy; /** * Replacement scalar value or column expression to substitute in place of target values. */ value?: ScalarArg; } ``` ### FillTarget ```typescript export type FillTarget = "null" | "nan" | "all" | ScalarArg; ``` ### FindManyOptions ```typescript export interface FindManyOptions extends ExtractManyOptions, EscapeRegexOptions { /** * Whether matching should be case-insensitive for ASCII characters. * @default false */ asciiCaseInsensitive?: boolean; /** * Whether to return all matches (global flag). * @default false */ global?: boolean; /** * 0-based index or name of the capture group to locate. * @default 0 */ groupIndex?: ColumnIndexOrNameArg; /** * Guarantees that the leftmost match is selected when multiple patterns match. * @default false */ leftmost?: boolean; /** * Treat patterns as literal substrings instead of regular expressions. * @default false */ literal?: boolean; /** * Escaping mode when `literal` is `true`. * @default "tc39" */ mode?: EscapeRegexMode; /** * Whether overlapping matches across patterns are allowed. * @default false */ overlapping?: boolean; } ``` ### FindOptions ```typescript export interface FindOptions extends ExtractRegexEngineOptions, EscapeRegexOptions { /** * Whether matching should be case-insensitive for ASCII characters. * @default false */ asciiCaseInsensitive?: boolean; /** * Whether to return all matches (global flag). * @default false */ global?: boolean; /** * 0-based index or name of the capture group to locate. * @default 0 */ groupIndex?: ColumnIndexOrNameArg; /** * Treat pattern as a literal substring instead of a regular expression. * @default false */ literal?: boolean; /** * Escaping mode when `literal` is `true`. * @default "tc39" */ mode?: EscapeRegexMode; } ``` ### HorizontalConcatOptions ```typescript export interface HorizontalConcatOptions { /** * When `true`, throws an error if row counts mismatch in horizontal concatenation. Set `false` to pad shorter DataFrames with `null`. * @default true */ strict?: boolean; } ``` ### IExpr ```typescript export interface IExpr { /** Aggregation reducer function registered on the expression, or `null`. */ _aggFn?: AggFn | null; /** Parent base expression for struct field extraction or unnesting. */ _baseExpr?: IExpr; /** Left and right operand metadata for binary expressions. */ _binaryMeta?: { _left: any; _right: any }; /** Branch operands collected by `$df.when().then().otherwise()` chains. */ _branchOperands?: any[]; /** Target `RegisteredDataType` registered via `.cast()`. */ _castType?: RegisteredDataType; /** Source column name or expression selector marker. */ _colName?: string; /** Logs intermediate column state during expression evaluation and returns `this`. */ _debug(label?: string): this; /** Evaluates the full expression pipeline against `columns`. */ _evaluate(columns: ColumnDict, height: number): ColumnData; /** Evaluates post-aggregation or post-partition operations starting after `opsIndex`. */ _evaluatePost(opsIndex: number | undefined, aggregatedArray: any[], columns: ColumnDict): ColumnData; /** Evaluates pre-aggregation or pre-partition operations up to `opsIndex`. */ _evaluatePre(opsIndex: number | undefined, columns: ColumnDict, height: number): ColumnData; /** Evaluates a row-wise window operation over a partition slice. */ _evaluateWindow?(groupPreValues: any[], partitionIndices: number[], currentIndex: number): any; /** Struct field name targeted by `.struct.field()`. */ _fieldName?: string; /** Pipeline index marking the boundary of an `.agg()` reduction. */ _groupingOpsIndex?: number; /** Returns `true` if the expression performs a full-column reduction without window partitioning. */ _isGlobalAgg?(): boolean; /** Flag indicating whether the expression represents a constant literal value. */ _isLiteral?: boolean; /** Flag indicating whether the expression expands struct fields via `.struct.unnest()`. */ _isUnnest?: boolean; /** Flag indicating whether the expression requires window-function evaluation. */ _isWindow?: boolean; /** Raw literal value when `_isLiteral` is `true`. */ _literalValue?: any; /** Ordered pipeline of vectorized transformation functions. */ _ops: OpFn[]; /** Explicit output alias name assigned via `.alias()`. */ _outputName?: string; /** Partitioning column keys or expressions supplied to `.over()`. */ _partitionBy?: ColumnOrExprArg[] | null; /** Pipeline index marking the boundary of an `.over()` window partition. */ _partitionOpsIndex?: number; /** Resolves an operand into an evaluated column array or scalar value. */ _resolve(val: any, columns: ColumnDict, height: number): ColumnData | any; /** Window operation metadata descriptor when `_isWindow` is `true`. */ _windowOp?: { type: string;[key: string]: any } | null; } ``` ### IntoExpr ```typescript export type IntoExpr = RegexPatternArg | IExpr; ``` ### IntoExprArg ```typescript export type IntoExprArg = ColumnKeyArg; ``` ### IntoExprSeriesArg ```typescript export type IntoExprSeriesArg = IntoExpr[]; ``` ### IsBusinessDayOptions ```typescript export interface IsBusinessDayOptions { /** * ISO weekday numbers (`1 = Monday` ... `7 = Sunday`) considered non-business weekend days. * @default [6, 7] */ excludeWeekdays?: number[]; /** * List or set of holiday dates (`Date`, ISO date string, or UTC timestamp) to exclude as business days. */ holidays?: (Date | string | number)[] | Set; } ``` ### JSONFormat ```typescript export type JSONFormat = /** Standard JSON format. */ | "json" /** Newline Delimited JSON format. */ | "ndjson"; ``` ### KurtosisOptions ```typescript export interface KurtosisOptions extends SkewOptions { /** * If `true`, computes biased population kurtosis; if `false`, applies sample bias correction. * @default true */ bias?: boolean; /** * If `true`, computes Fisher's excess kurtosis (subtracts 3 so a normal distribution equals 0); if `false`, computes Pearson's kurtosis. * @default true */ fisher?: boolean; } ``` ### OpFn ```typescript export type OpFn = (vals: ColumnData, columns: ColumnDict) => ColumnData; ``` ### ReadCSVOptions ```typescript export interface ReadCSVOptions { /** * Whether the CSV has a header row. * @default true */ hasHeader?: boolean; /** * Try to infer types from values if no schema is provided. * @default true */ inferSchema?: boolean; /** * String representations of null values. * @default ["", "NA", "null", "NaN"] */ nullValues?: string[]; /** * The character used for quoting fields. * @default '"' */ quoteChar?: string; /** * Optional explicit schema mapping column names to their registered data types. */ schema?: DataFrameSchema; /** * Character that separates fields. * @default "," */ separator?: string; } ``` ### ReadJSONOptions ```typescript export interface ReadJSONOptions extends JSONParseOptions { /** * Whether to allow JSON primitive roots instead of requiring objects or arrays. * @default false */ allowPrimitives?: boolean; /** * Format of the JSON content: `"json"` (standard JSON) or `"ndjson"` (Newline Delimited JSON). * @default "json" */ format?: JSONFormat; /** * Options specific to NDJSON parsing when `format` is `"ndjson"`. */ ndjson?: NDJSONParseOptions; /** * Reviver function passed to `JSON.parse` for custom value transformation. */ reviver?: Parameters[1]; /** * Optional explicit schema mapping column names to their registered data types. */ schema?: DataFrameSchema; /** * Whether to trim leading and trailing whitespace before validating/parsing. * @default false */ trimBeforeParse?: boolean; } ``` ### RegexEngineOptions ```typescript export interface RegexEngineOptions { /** * Whether matching should be case-insensitive for ASCII characters. * @default false */ asciiCaseInsensitive?: boolean; /** * Whether to return all matches (global flag). * @default false */ global?: boolean; } ``` ### RegexPatternArg ```typescript export type RegexPatternArg = string | RegExp; ``` ### RegexPatternSeriesArg ```typescript export type RegexPatternSeriesArg = RegexPatternArg[]; ``` ### RenameMappingArg ```typescript export type RenameMappingArg = Partial>; ``` ### ReplaceDateOptions ```typescript export interface ReplaceDateOptions { /** Replacement 1-indexed day of the month (1 to 31). */ day?: number; /** Replacement 0-indexed hour of day (0 to 23). */ hour?: number; /** Replacement 0-indexed minute of hour (0 to 59). */ minute?: number; /** Replacement 1-indexed calendar month (1 to 12). */ month?: number; /** Replacement 0-indexed millisecond (0 to 999). */ ms?: number; /** Replacement 0-indexed second of minute (0 to 59). */ second?: number; /** Target timezone identifier used to interpret and re-project the replaced components. */ timeZone?: string | null; /** Replacement calendar year. */ year?: number; } ``` ### ReplaceManyOptions ```typescript export interface ReplaceManyOptions extends FindManyOptions { /** * Whether matching should be case-insensitive for ASCII characters. * @default false */ asciiCaseInsensitive?: boolean; /** * Whether to replace all matches globally. * @default false */ global?: boolean; /** * 0-based index or name of the capture group to replace. * @default 0 */ groupIndex?: ColumnIndexOrNameArg; /** * Guarantees that the leftmost match is selected when multiple patterns match. * @default false */ leftmost?: boolean; /** * Treat patterns as literal substrings instead of regular expressions. * @default false */ literal?: boolean; /** * Escaping mode when `literal` is `true`. * @default "tc39" */ mode?: EscapeRegexMode; /** * Whether overlapping matches across patterns are allowed. * @default false */ overlapping?: boolean; } ``` ### ReplaceOptions ```typescript export interface ReplaceOptions extends RegexEngineOptions, EscapeRegexOptions { /** * Whether matching should be case-insensitive for ASCII characters. * @default false */ asciiCaseInsensitive?: boolean; /** * Whether to replace all matches globally. * @default false */ global?: boolean; /** * Treat pattern as a literal substring instead of a regular expression. * @default false */ literal?: boolean; /** * Escaping mode when `literal` is `true`. * @default "tc39" */ mode?: EscapeRegexMode; /** * Maximum number of occurrences to replace (`-1` or `Infinity` replaces all). * @default 1 */ n?: number; } ``` ### RowRecord ```typescript export type RowRecord = Record; ``` ### ScalarArg ```typescript export type ScalarArg = IExpr | ValidScalarTypes; ``` ### SkewOptions ```typescript export interface SkewOptions { /** * If `true`, computes biased population skewness; if `false`, applies the Fisher-Pearson sample bias correction. * @default true */ bias?: boolean; } ``` ### SortArrayOptions ```typescript export interface SortArrayOptions { /** * Optional comparator function or dictionary mapping column names to custom comparator functions. */ customComp?: ((a: any, b: any) => number) | Partial number>> | null; /** * Sort order boolean or array of booleans per key. * @default false */ descending?: ColumnKeyArg; /** * When `true`, places nulls at the end of sorted output. * @default true */ nullsLast?: boolean; } ``` ### SplitOptions ```typescript export interface SplitOptions extends RegexEngineOptions, EscapeRegexOptions { /** * Whether matching should be case-insensitive for ASCII characters. * @default false */ asciiCaseInsensitive?: boolean; /** * If `true`, pads missing splits with `null` to guarantee `limit + 1` elements. * @default false */ exact?: boolean; /** * Whether to match globally. * @default false */ global?: boolean; /** * Include matched delimiter substrings in the split output array. * @default false */ inclusive?: boolean; /** * Maximum number of splits to perform. */ limit?: number; /** * Treat delimiter as a literal substring (`true`) or regular expression (`false`). * @default true */ literal?: boolean; /** * Escaping mode when `literal` is `true`. * @default "tc39" */ mode?: EscapeRegexMode; /** * If `true`, throws an `InvalidArgumentError` when the split yields fewer than `limit + 1` elements. * @default false */ strict?: boolean; } ``` ### StrftimeOptions ```typescript export interface StrftimeOptions { /** * Format string containing `%` date/time directives (e.g. `"%Y-%m-%d"`). */ format: string; /** * BCP 47 locale tag used for localized month and weekday names. * @default "en-US" */ locale?: string; /** * Target IANA timezone identifier used when formatting date/time parts. * @default "UTC" */ timeZone?: string; } ``` ### StringEncoding ```typescript export type StringEncoding = "hex" | "base64"; ``` ### StrptimeOptions ```typescript export interface StrptimeOptions { /** * Default IANA timezone or UTC offset applied when the parsed string has no `%z`/`%Z` directive. * @default "UTC" */ defaultTimeZone?: string; /** * Format string containing `%` date/time directives (e.g. `"%Y-%m-%d %H:%M:%S"`). */ format: string; /** * If `true`, throws an error when a string fails to match `format`; if `false`, returns `null`. * @default true */ strict?: boolean; } ``` ### StructFieldsArg ```typescript export type StructFieldsArg = IntoExprSeriesArg | ExprDict; ``` ### TimeUnit ```typescript export type TimeUnit = "s" | "ms" | "us" | "ns"; ``` ### UtcOffsetFormat ```typescript export type UtcOffsetFormat = "milliseconds" | "minutes" | "hours" | "iso" | "basic"; ``` ### UtcOffsetOptions ```typescript export interface UtcOffsetOptions { /** * Output format: `"milliseconds"`, `"minutes"`, `"hours"`, `"iso"` (`"+HH:MM"`), or `"basic"` (`"+HHMM"`). * @default "milliseconds" */ format?: UtcOffsetFormat; /** * Which offset component to compute: `"base"` (standard offset), `"total"` (wall-clock offset), or `"daylightSavingTime"` (DST delta). * @default "total" */ type?: UtcOffsetType; } ``` ### UtcOffsetType ```typescript export type UtcOffsetType = "base" | "total" | "daylightSavingTime"; ``` ### ValidPrimitiveTypes ```typescript export type ValidPrimitiveTypes = string | number | boolean | bigint | symbol | null | undefined; ``` ### ValidScalarTypes ```typescript export type ValidScalarTypes = Exclude | Date | AnyTypedArray; ``` ### ArrayCheckMode ```typescript export type ArrayCheckMode = "every" | "some"; ``` ### ArrayItemType ```typescript export type ArrayItemType = | "string" | "number" | "int" | "boolean" | "bigint" | "object" | "plainObject" | "date" | "regexp" | "array" | "any" | "null" | "undefined" | "nullish" | (new (...args: any[]) => any) | ((v: unknown) => any); ``` ### BigIntRange ```typescript export type BigIntRange = | { /** Minimum inclusive BigInt value. */ min: bigint; /** Maximum inclusive BigInt value. */ max: bigint; } | BigIntRangeType; ``` ### BigIntRangeType ```typescript export type BigIntRangeType = keyof typeof BIGINT_RANGES; ``` ### BinarySearchOptions ```typescript export interface BinarySearchOptions { /** * Optional accessor function `(index, item) => number` for indirect searching. */ getValue?: (index: number, item: T) => number; /** * Search side: `"left"` (first index `>= target`) or `"right"` (first index `> target`). * @default "left" */ side?: BinarySearchSide; } ``` ### BinarySearchSide ```typescript export type BinarySearchSide = "left" | "right"; ``` ### BinaryValidationOptions ```typescript export interface BinaryValidationOptions { /** * When `true`, requires strict binary buffer type matching. * @default false */ strict?: boolean; } ``` ### CandidateMatch ```typescript export interface CandidateMatch { /** Match end offset (exclusive) in the input string. */ _end: number; /** Pattern index in the input pattern array. */ _i: number; /** Extracted payload associated with the match. */ _payload: T; /** Match start offset (inclusive) in the input string. */ _start: number; } ``` ### ChangeCaseOptions ```typescript export interface ChangeCaseOptions { /** * Target casing format: `"camel"`, `"kebab"`, `"pascal"`, `"snake"`, or `"title"`. */ format: "camel" | "kebab" | "pascal" | "snake" | "title"; } ``` ### CumulativeStepContext ```typescript export interface CumulativeStepContext { /** The absolute index of the current element in the parent array. */ absoluteIndex: number; /** The relative iteration counter of the stepping process (starts at 1). */ index: number; /** The original value at the current index in the target array. */ originalValue: any; /** The accumulated value returned by the step function from the previous stepped index. */ prev: any; /** The entire target array being populated/modified. */ targetArray: any; } ``` ### DateDirective ```typescript export interface DateDirective { /** Formats a `Date` and decomposed `DateTimeParts` into the directive's string representation. */ _format: (d: Date, locale: string, timeZone: string, parts: import("../types").DateTimeParts) => string; /** Target date/time component field populated when this directive is parsed. */ _parseField?: "year" | "month" | "day" | "hour" | "minute" | "second" | "ms" | "ampm" | "offset"; /** Optional normalizer converting the matched substring into a numeric or string component value. */ _parseNormalize?: (valStr: string) => number | string; /** Regular expression pattern source used to match the directive during `strptime()`. */ _parseRegex?: string; } ``` ### DecimalOptions ```typescript export interface DecimalOptions { /** * Total maximum number of significant digits (1 to 38). * @default 38 */ precision?: number; /** * Number of digits to the right of the decimal point (`0 <= scale <= precision`). * @default 9 */ scale?: number; } ``` ### DurationInterval ```typescript export interface DurationInterval { /** Number of calendar days (`d`, `w`). */ days: number; /** Number of row index units (`i`). */ indexUnits: number; /** `true` if the interval contains calendar units (`months > 0` or `days > 0`). */ isCalendar: boolean; /** `true` if the interval is measured in row index units (`i`). */ isIndex: boolean; /** Number of calendar months (`mo`, `q`, `y`). */ months: number; /** Number of sub-day milliseconds (`h`, `m`, `s`, `ms`, `us`, `ns`). */ ms: number; } ``` ### DurationUnit ```typescript export type DurationUnit = "ns" | "us" | "ms" | "s" | "m" | "h" | "d" | "w" | "mo" | "q" | "y" | "i"; ``` ### FillSeqBaseOptions ```typescript export interface FillSeqBaseOptions { /** * Type coercion helper applied to each generated value before writing. */ coerce?: (v: any) => any; /** * Conditional predicate determining if a value should be written at a given index. */ condition?: (v: any, index: number, array: any[]) => boolean; /** * Exclusive boundary index at which iteration and writing stops. */ endIndex?: number; /** * If `true`, iterates and populates in reverse from `startIndex` down to `endIndex`. * @default false */ reverse?: boolean; /** * Index at which array iteration and writing begins. * @default 0 */ startIndex?: number; } ``` ### FillSeqOptions ```typescript export interface FillSeqOptions extends FillSeqBaseOptions { /** * Type coercion helper applied to each generated value before writing. */ coerce?: (v: any) => any; /** * Conditional predicate determining if a value should be written at a given index. */ condition?: (v: any, index: number, array: any[]) => boolean; /** * Exclusive boundary index at which iteration and writing stops. */ endIndex?: number; /** * Sequence generation mode: `"constant"`, `"cumulative"`, or `"independent"`. * @default "cumulative" */ mode?: "constant" | "cumulative" | "independent"; /** * If `true`, iterates and populates in reverse from `startIndex` down to `endIndex`. * @default false */ reverse?: boolean; /** * Index at which array iteration and writing begins. * @default 0 */ startIndex?: number; /** * Step increment value or callback function. * @default 1 */ step?: number | ((context: CumulativeStepContext & IndependentStepContext) => any); } ``` ### FilterByMaskOptions ```typescript export interface FilterByMaskOptions { /** * If `true`, non-matching elements are replaced with `null` while preserving array length; if `false`, they are omitted. * @default false */ nullify?: boolean; } ``` ### FloatOptions ```typescript export interface FloatOptions extends ParseNumberOptions { /** * Whether `NaN` is considered a valid number. * @default false */ allowNaN?: boolean; /** * Whether `Infinity` and `-Infinity` are considered valid numbers. * @default false */ allowNonFiniteNumbers?: boolean; /** * Floating-point precision target (`"Float32"` or `"Float64"`). */ floatPrecision?: FloatPrecision; /** * When `true`, allows scientific notation (e.g. `"1.5e3"`) when parsing numeric strings. * @default true */ floatScientific?: boolean; /** * When `true`, rejects strings containing currency symbols, percent signs, or non-standard formatting. * @default false */ strictNumericString?: boolean; } ``` ### FloatPrecision ```typescript export type FloatPrecision = "Float32" | "Float64"; ``` ### FormatCSVValueOptions ```typescript export interface FormatCSVValueOptions { /** * Custom `strftime` format string for `Date` values (e.g. `"%Y-%m-%d"`). */ dateFormat?: string; /** * Custom `strftime` format string for `Datetime` values (e.g. `"%Y-%m-%d %H:%M:%S"`). */ datetimeFormat?: string; /** * String representation to use for `null` or missing values. * @default "" */ nullValue?: string; /** * Options for numeric formatting (floats, ints, bigints). */ numericFormatOptions?: NumericFormatOptions; /** * Options for the safe JSON replacer used when formatting objects and arrays. */ replacerOptions?: SafeJsonReplacerOptions; /** * Custom `strftime` format string for `Time` values (e.g. `"%H:%M:%S"`). */ timeFormat?: string; } ``` ### IndependentStepContext ```typescript export interface IndependentStepContext { /** The absolute index of the current element in the parent array. */ absoluteIndex: number; /** The relative iteration counter of the generation process (starts at 0). */ index: number; /** The static starting value passed to the sequence generator. */ initialValue: any; /** The original value at the current index in the target array. */ originalValue: any; /** The entire target array being populated/modified. */ targetArray: any; } ``` ### IntCoerceType ```typescript export type IntCoerceType = "round" | "floor" | "ceil" | "truncate"; ``` ### IntOptions ```typescript export interface IntOptions { /** * Rounding strategy used by `toValidInt()` when coercing fractional numbers. */ coerce?: IntCoerceType; /** * Integer range bounds to validate against. */ range?: IntRange; } ``` ### IntRange ```typescript export type IntRange = | { /** Minimum inclusive integer value. */ min: number; /** Maximum inclusive integer value. */ max: number; } | IntRangeType; ``` ### IntRangeType ```typescript export type IntRangeType = keyof typeof INT_RANGES; ``` ### IsArrayOfTypeOptionsParams ```typescript export interface IsArrayOfTypeOptionsParams { /** * Whether an empty array is considered valid. * @default true */ allowEmpty?: boolean; /** * Whether `null` and `undefined` elements are permitted without failing validation. * @default false */ allowNulls?: boolean; /** * Optional custom coercion function applied to each element in `toArrayOfType()`. */ coerce?: (v: unknown) => any; /** * Quantifier mode: `"every"` requires all elements to match; `"some"` requires at least one element to match. * @default "every" */ mode?: ArrayCheckMode; } ``` ### IsUnicodeSurrogateOptions ```typescript export interface IsUnicodeSurrogateOptions { /** * Which surrogate code units to match: `"all"`, `"high"` (`0xD800..0xDBFF`), or `"low"` (`0xDC00..0xDFFF`). * @default "all" */ type?: UnicodeSurrogateType; } ``` ### IsValidBigIntOptions ```typescript export interface IsValidBigIntOptions { /** * 64-bit integer range bounds to validate against. * @default "Int64" */ range?: BigIntRange; } ``` ### JoinArrayOptions ```typescript export interface JoinArrayOptions { /** * If `true`, `null` and `undefined` elements are skipped during joining. * @default false */ ignoreNulls?: boolean; /** * Maximum number of array elements to join before truncating with `truncationMarker`. */ limit?: number; /** * Custom string representation for `null` and `undefined` elements when `ignoreNulls` is `false`. * @default "" */ nullValue?: string; /** * Prefix string prepended to the joined result. * @default "" */ prefix?: string; /** * Suffix string appended to the joined result. * @default "" */ suffix?: string; /** * Placeholder string appended when `limit` truncation occurs. * @default "..." */ truncationMarker?: string; /** * Callback function used to format each non-null element to a string. */ valueFormatter?: (val: any, index: number) => string; } ``` ### JSONParseOptions ```typescript export interface JSONParseOptions { /** * Whether to allow JSON primitive roots (numbers, booleans, strings, `null`) instead of requiring objects or arrays. * @default false */ allowPrimitives?: boolean; /** * Format of the JSON content: `"json"` (standard JSON) or `"ndjson"` (Newline Delimited JSON). * @default "json" */ format?: JSONFormat; /** * Options specific to NDJSON parsing when `format` is `"ndjson"`. */ ndjson?: NDJSONParseOptions; /** * Reviver function passed to `JSON.parse` for custom value transformation. */ reviver?: Parameters[1]; /** * Whether to trim leading and trailing whitespace before validating/parsing. * @default false */ trimBeforeParse?: boolean; } ``` ### JsonToken ```typescript export interface JsonToken { /** Ending array index (exclusive). Used by `"slice"` tokens. */ end?: number; /** Target index position. Used by `"idx"` tokens. Supports negative indices. */ idx?: number; /** Property name or recursive search key. Used by `"prop"` and `"rec"` tokens. */ key?: string; /** Starting array index (inclusive). Used by `"slice"` tokens. */ start?: number; /** Increment step value. Used by `"slice"` tokens. Cannot be 0. */ step?: number; /** The evaluation operation type. */ type: JsonTokenType; } ``` ### JsonTokenType ```typescript export type JsonTokenType = /** Selects an object property by name (e.g., `.foo` or `['foo']`). */ | "prop" /** Selects a zero-based or negative array index (e.g., `[0]` or `[-1]`). */ | "idx" /** Selects a range or stepped slice of an array (e.g., `[1:5:2]`). */ | "slice" /** Selects all immediate properties of an object or elements of an array (e.g., `.*` or `[*]`). */ | "wildcard" /** Recursively searches and collects matching keys down the hierarchy (e.g., `..foo`). */ | "rec"; ``` ### NDJSONParseOptions ```typescript export interface NDJSONParseOptions { /** * Maximum number of non-empty lines to validate or parse. */ maxLines?: number; /** * Skip malformed or invalid lines instead of failing the entire parse. * @default false */ skipInvalidLines?: boolean; /** * Number of non-empty lines to skip at the beginning of the content. * @default 0 */ skipLines?: number; } ``` ### NumericFormatOptions ```typescript export interface NumericFormatOptions extends Intl.NumberFormatOptions { /** * If `true`, formats negative numbers in accounting parentheses (e.g. `(1.23)`). * @default false */ accountingNegatives?: boolean; /** * Fallback string returned when the value cannot be parsed into a formattable number. * @default "NaN" */ fallback?: string; /** * If `true`, returns `fallback` for `Infinity` and `-Infinity` values. * @default false */ formatNonFinite?: boolean; /** * BCP 47 language tag (e.g. `"en-US"`, `"de-DE"`). * @default "en-US" */ locale?: string; } ``` ### NumericValidationOptions ```typescript export interface NumericValidationOptions { /** * Whether `NaN` is considered a valid number. * @default false */ allowNaN?: boolean; /** * Whether `Infinity` and `-Infinity` are considered valid numbers. * @default false */ allowNonFiniteNumbers?: boolean; } ``` ### ParseDurationStringOptions ```typescript export interface ParseDurationStringOptions { /** * Target unit to convert the parsed duration into. * @default "ms" */ to?: DurationUnit; } ``` ### ParseNumberOptions ```typescript export interface ParseNumberOptions extends NumericValidationOptions { /** * Whether `NaN` is considered a valid number. * @default false */ allowNaN?: boolean; /** * Whether `Infinity` and `-Infinity` are considered valid numbers. * @default false */ allowNonFiniteNumbers?: boolean; /** * When `true`, allows scientific notation (e.g. `"1.5e3"`) when parsing numeric strings. * @default true */ floatScientific?: boolean; /** * When `true`, rejects strings containing currency symbols, percent signs, or non-standard formatting. * @default false */ strictNumericString?: boolean; } ``` ### SafeJsonParseOptions ```typescript export interface SafeJsonParseOptions extends JSONParseOptions { /** * Whether to allow JSON primitive roots (numbers, booleans, strings, `null`) instead of requiring objects or arrays. * @default false */ allowPrimitives?: boolean; /** * Fallback value returned when parsing or guard validation fails. */ fallback?: F; /** * Format of the JSON content: `"json"` (standard JSON) or `"ndjson"` (Newline Delimited JSON). * @default "json" */ format?: JSONFormat; /** * Guard predicate to validate the parsed value. If it returns `false`, `onError` is called and `fallback` is returned. */ guard?: ((value: unknown) => value is T) | ((value: unknown) => boolean); /** * Options specific to NDJSON parsing when `format` is `"ndjson"`. */ ndjson?: NDJSONParseOptions; /** * Callback invoked when parsing fails or the `guard` check returns `false`. */ onError?: (err: unknown) => void; /** * Reviver function passed to `JSON.parse` for custom value transformation. */ reviver?: Parameters[1]; /** * Whether to trim leading and trailing whitespace before validating/parsing. * @default false */ trimBeforeParse?: boolean; } ``` ### SafeJsonReplacerOptions ```typescript export interface SafeJsonReplacerOptions { /** * Strategy for serializing `BigInt` values: `"string"` or `"number"`. * @default "string" */ bigintStrategy?: "string" | "number"; /** Custom formatter function for `Date` objects (ignored if `onDate` is specified). */ formatDate?: (v: Date) => string; /** * If `true`, replaces circular references instead of throwing. * @default false */ handleCircular?: boolean; /** Custom serialization override for `BigInt` values. */ onBigInt?: (v: bigint) => any; /** Custom callback invoked when a circular reference is encountered. */ onCircular?: (this: any, k: string, v: any) => any; /** Catch-all serialization override for custom types, executed after native type checks. */ onCustom?: (this: any, k: string, v: any) => any; /** Custom serialization override for `Date` objects (takes precedence over `formatDate`). */ onDate?: (v: Date) => any; /** Custom serialization override for `Error` objects. */ onError?: (v: Error) => any; /** Custom serialization override for `Map` objects. */ onMap?: (v: Map) => any; /** Custom serialization override for `RegExp` objects. */ onRegExp?: (v: RegExp) => any; /** Custom serialization override for `Set` objects. */ onSet?: (v: Set) => any; /** Custom serialization override for `TypedArray` values. */ onTypedArray?: (v: any) => any; /** Custom serialization override for `URLSearchParams` objects. */ onURLSearchParams?: (v: URLSearchParams) => any; /** Custom `JSON.stringify` replacer function or property whitelist array applied first. */ replacer?: ((this: any, k: string, v: any) => any) | (string | number)[] | null; /** * If `true`, disables default safe serialization for `BigInt` values. * @default false */ voidBigIntReplacement?: boolean; /** * If `true`, disables default safe serialization for `Date` objects. * @default false */ voidDateReplacement?: boolean; /** * If `true`, disables default safe serialization for `Map` objects. * @default false */ voidMapReplacement?: boolean; /** * If `true`, disables default safe serialization for `RegExp` objects. * @default false */ voidRegExpReplacement?: boolean; /** * If `true`, disables default safe serialization for `Set` objects. * @default false */ voidSetReplacement?: boolean; /** * If `true`, disables default safe serialization for `TypedArray` values. * @default false */ voidTypedArrayReplacement?: boolean; } ``` ### StepSliceArrayOptions ```typescript export interface StepSliceArrayOptions { /** * Maximum number of items to gather in the sliced result array. */ maxItemsGathered?: number; /** * If `true`, returns `null` when the starting offset is out of bounds; if `false`, throws an error. * @default true */ nullOnOob?: boolean; /** * Ending index (exclusive). Supports negative indices relative to array length. */ offsetEnd?: number; /** * Starting index (inclusive). Supports negative indices relative to array length. * @default 0 */ offsetStart?: number; /** * Step size to slice the array by (non-zero). Positive slices forward; negative slices backward. * @default 1 */ step?: number; } ``` ### StripCharsOptions ```typescript export interface StripCharsOptions { /** * Maximum number of non-contiguous matching blocks allowed to be stripped from the end (`-1` or `null` strips all). */ maxMatchesEnd?: number | null; /** * Maximum number of non-contiguous matching blocks allowed to be stripped from the start (`-1` or `null` strips all). */ maxMatchesStart?: number | null; /** * Maximum number of non-matching characters allowed to be skipped from the end before a match block is found (`-1` or `null` scans full length). */ maxScanEnd?: number | null; /** * Maximum number of non-matching characters allowed to be skipped from the start before a match block is found (`-1` or `null` scans full length). */ maxScanStart?: number | null; /** * Boundary strip mode: `"both"`, `"start"`, or `"end"`. * @default "both" */ mode?: StripMode; /** * If `true`, returns `""` instead of `null` when the stripped result is empty or input is `null`. * @default false */ returnStringOnNull?: boolean; /** * Options that apply only when `characters` is a string (and not a `RegExp`). */ stringOptions?: { /** * If `true`, treats `characters` as a literal substring rather than a set of characters. * @default false */ literal?: boolean; /** * If `true`, performs case-insensitive character and substring matching. * @default false */ caseInsensitive?: boolean; }; /** * If `true`, trims standard whitespace first before performing character stripping. * @default false */ trimFirst?: boolean; } ``` ### StripMode ```typescript export type StripMode = "both" | "start" | "end"; ``` ### ToDurationOptions ```typescript export interface ToDurationOptions extends ParseDurationStringOptions { /** * Fallback numeric value returned when the input cannot be parsed as a valid duration. */ fallback?: number; /** * Target unit to convert the parsed duration into. * @default "ms" */ to?: DurationUnit; } ``` ### ToValidArrayOptions ```typescript export interface ToValidArrayOptions { /** * If `true`, returns a shallow copy of an existing array. If `false`, returns the input array directly without cloning. * @default true */ clone?: boolean; /** * If `true`, wraps `null` or `undefined` into a single-element array. If `false`, returns an empty array `[]`. * @default false */ wrapNull?: boolean; } ``` ### toValidBigIntOptions ```typescript export interface toValidBigIntOptions extends IsValidBigIntOptions { /** * 64-bit integer range bounds to validate against. * @default "Int64" */ range?: BigIntRange; /** * When `true`, truncates fractional numbers/strings toward zero before converting to `bigint`. * @default false */ truncate?: boolean; } ``` ### TypedArrayConstructor ```typescript export type TypedArrayConstructor = new (length: number) => T; ``` ### UnicodeSurrogateType ```typescript export type UnicodeSurrogateType = "all" | "high" | "low"; ``` ### UniqueArrayStatsOptions ```typescript export interface UniqueArrayStatsOptions { /** * Custom function to extract a unique comparison key from each element. */ keySelector?: (val: any) => any; /** * If `true`, uses canonical serialization to group nested structures (Arrays, Sets, Maps, Dates) by value instead of reference. * @default false */ strict?: boolean; } ``` ### WriteCSVOptions ```typescript export interface WriteCSVOptions extends FormatCSVValueOptions { /** * Custom `strftime` format string for `Date` values (e.g. `"%Y-%m-%d"`). */ dateFormat?: string; /** * Custom `strftime` format string for `Datetime` values (e.g. `"%Y-%m-%d %H:%M:%S"`). */ datetimeFormat?: string; /** * Whether to include a UTF-8 Byte Order Mark (BOM) at the start of the output. * @default false */ includeBom?: boolean; /** * Whether to write the header row. * @default true */ includeHeader?: boolean; /** * String used to terminate each row. * @default "\n" */ lineTerminator?: string; /** * String representation to use for `null` or missing values. * @default "" */ nullValue?: string; /** * Options for numeric formatting (floats, ints, bigints). */ numericFormatOptions?: NumericFormatOptions; /** * Single-character quote symbol used for quoting fields. * @default '"' */ quoteChar?: string; /** * Quoting strategy for CSV fields: `"necessary"`, `"always"`, `"never"`, or `"non_numeric"`. * @default "necessary" */ quoteStyle?: "necessary" | "always" | "never" | "non_numeric"; /** * Options for the safe JSON replacer used when formatting objects and arrays. */ replacerOptions?: SafeJsonReplacerOptions; /** * Single-character delimiter that separates fields. * @default "," */ separator?: string; /** * Custom `strftime` format string for `Time` values (e.g. `"%H:%M:%S"`). */ timeFormat?: string; } ```