module pixeltable.functions

General Pixeltable UDFs. This parent module contains general-purpose UDFs that apply to multiple data types.

func filter()

Signature

filter(
    expr: pixeltable.exprs.expr.Expr,
    predicate: Callable[[pixeltable.exprs.expr.Expr], Any]
) -> pixeltable.exprs.expr.Expr

Keeps the elements of a JSON array for which a predicate holds, producing a new array. filter() is used like a UDF, for example in select() or add_computed_column(). Parameters:

expr (pixeltable.exprs.expr.Expr): The array to filter; an expression of type pxt.Json that resolves to a JSON array. Its element type is preserved in the result.
predicate (typing.Callable[[pixeltable.exprs.expr.Expr], typing.Any]): A Python function (typically a lambda) that decides which elements to keep. It receives x, a stand-in for a single array element, and returns a boolean condition; the element is kept when it is true. Operate on x exactly as you would on a column: comparisons, indexing (x[0]), field access (x.field), and JSON methods all work. Combine multiple conditions with & and |, and negate with ~ (not Python and/or/not). Example: lambda x: (x > 0) & (x < 10).

Returns:

pixeltable.exprs.expr.Expr: A new array containing the elements of expr for which predicate is true, unchanged. If expr is null or does not resolve to a JSON array, the result is null.

Examples: Given a table tbl with a pxt.Json column data holding lists of numbers, add a column that keeps only the positive numbers:

tbl.add_computed_column(
    positives=pxt.functions.filter(tbl.data, lambda x: x > 0)
)

When data holds lists of objects such as {'score': 0.9, 'label': 'cat'}, keep only the high-confidence ones:

tbl.select(
    confident=pxt.functions.filter(tbl.data, lambda x: x.score >= 0.9)
).collect()

func map()

Signature

map(
    expr: pixeltable.exprs.expr.Expr,
    fn: Callable[[pixeltable.exprs.expr.Expr], Any]
) -> pixeltable.exprs.expr.Expr

Applies a function to each element of a JSON array, producing a new array. map() is used like a UDF, for example in select() or add_computed_column(). Parameters:

expr (pixeltable.exprs.expr.Expr): The array to map over; an expression of type pxt.Json that resolves to a JSON array. If its elements have a known type (e.g. the column is declared pxt.Json[[int]]), that type is available to fn and carries through to the result.
fn (typing.Callable[[pixeltable.exprs.expr.Expr], typing.Any]): A Python function (typically a lambda) applied to each element to produce its replacement. It receives x, a stand-in for a single array element, and returns the value to store in its place. Operate on x exactly as you would on a column: arithmetic, indexing (x[0]), field access (x.field), and JSON methods (x.len(), x.sum(), etc.) all work.

Returns:

pixeltable.exprs.expr.Expr: A new array holding fn(x) for each element x of expr. If expr is null or does not resolve to a JSON array, the result is null.

Examples: Given a table tbl with a pxt.Json column data holding lists of numbers, add a column that doubles each number:

tbl.add_computed_column(
    doubled=pxt.functions.map(tbl.data, lambda x: x * 2)
)

When data holds lists of objects such as {'score': 0.9, 'label': 'cat'}, extract each score:

tbl.select(
    scores=pxt.functions.map(tbl.data, lambda x: x.score)
).collect()

func sort()

Signature

sort(
    expr: pixeltable.exprs.expr.Expr,
    key: Optional[Callable[[pixeltable.exprs.expr.Expr], Any]] = None,
    *,
    asc: bool = True
) -> pixeltable.exprs.expr.Expr

Sorts the elements of a JSON array, producing a new array. sort() is used like a UDF, for example in select() or add_computed_column(). Parameters:

expr (pixeltable.exprs.expr.Expr): The array to sort; an expression of type pxt.Json that resolves to a JSON array. Its element type is preserved in the result.
key (typing.Optional[typing.Callable[[pixeltable.exprs.expr.Expr], typing.Any]]): An optional Python function (typically a lambda) that produces the value each element is ordered by. It receives x, a stand-in for a single array element, and returns the sort key. Operate on x exactly as you would on a column: arithmetic, indexing (x[0]), field access (x.field), and JSON methods all work. When key is omitted, the elements are ordered by their own natural ordering.
asc (bool, default: True): Whether to sort in ascending (the default) or descending order.

Returns:

pixeltable.exprs.expr.Expr: A new array with the elements of expr in sorted order. If expr is null or does not resolve to a JSON array, the result is null. Sorting a list of scalars without a key, or by non-orderable keys, raises if the values are not mutually comparable (matching Python’s sorted()).

Examples: Given a table tbl with a pxt.Json column data holding lists of numbers, add a column that sorts each list in descending order:

tbl.add_computed_column(ranked=pxt.functions.sort(tbl.data, asc=False))

When data holds lists of objects such as {'score': 0.9, 'label': 'cat'}, sort each list by score:

tbl.select(
    by_score=pxt.functions.sort(
        tbl.data, key=lambda x: x.score, asc=False
    )
).collect()

uda count()

Signatures

# Signature 1:
@pxt.uda
count(val: pxt.String | None) -> pxt.Int

# Signature 2:
@pxt.uda
count(val: pxt.Bool | None) -> pxt.Int

# Signature 3:
@pxt.uda
count(val: pxt.Int | None) -> pxt.Int

# Signature 4:
@pxt.uda
count(val: pxt.Float | None) -> pxt.Int

# Signature 5:
@pxt.uda
count(val: pxt.Timestamp | None) -> pxt.Int

# Signature 6:
@pxt.uda
count(val: pxt.Json | None) -> pxt.Int

# Signature 7:
@pxt.uda
count(val: pxt.Array | None) -> pxt.Int

# Signature 8:
@pxt.uda
count(val: pxt.Image | None) -> pxt.Int

# Signature 9:
@pxt.uda
count(val: pxt.Video | None) -> pxt.Int

# Signature 10:
@pxt.uda
count(val: pxt.Audio | None) -> pxt.Int

# Signature 11:
@pxt.uda
count(val: pxt.Document | None) -> pxt.Int

# Signature 12:
@pxt.uda
count(val: pxt.Date | None) -> pxt.Int

# Signature 13:
@pxt.uda
count(val: pxt.UUID | None) -> pxt.Int

# Signature 14:
@pxt.uda
count(val: pxt.Binary | None) -> pxt.Int

Aggregate function that counts the number of non-null values in a column or grouping. Parameters:

val (String | None): The value to count.

Returns:

pxt.Int: The count of non-null values.

Examples: Count the number of non-null values in the value column of the table tbl:

tbl.select(pxt.functions.count(tbl.value)).collect()

Group by the category column and compute the count of non-null values in the value column for each category, assigning the name 'category_count' to the new column:

tbl.group_by(tbl.category).select(
    tbl.category, category_count=pxt.functions.count(tbl.value)
).collect()

uda max()

Signatures

# Signature 1:
@pxt.uda
max(val: pxt.String | None) -> pxt.String | None

# Signature 2:
@pxt.uda
max(val: pxt.Int | None) -> pxt.Int | None

# Signature 3:
@pxt.uda
max(val: pxt.Float | None) -> pxt.Float | None

# Signature 4:
@pxt.uda
max(val: pxt.Bool | None) -> pxt.Bool | None

# Signature 5:
@pxt.uda
max(val: pxt.Timestamp | None) -> pxt.Timestamp | None

Aggregate function that computes the maximum value in a column or grouping. Parameters:

val (String | None): The value to compare.

Returns:

pxt.String | None: The maximum value, or None if there are no non-null values.

Examples: Compute the maximum value in the value column of the table tbl:

tbl.select(pxt.functions.max(tbl.value)).collect()

Group by the category column and compute the maximum value in the value column for each category, assigning the name 'category_max' to the new column:

tbl.group_by(tbl.category).select(
    tbl.category, category_max=pxt.functions.max(tbl.value)
).collect()

uda mean()

Signatures

# Signature 1:
@pxt.uda
mean(val: pxt.Int | None) -> pxt.Float | None

# Signature 2:
@pxt.uda
mean(val: pxt.Float | None) -> pxt.Float | None

Aggregate function that computes the mean (average) of non-null values of a numeric column or grouping. Parameters:

val (Int | None): The numeric value to include in the mean.

Returns:

pxt.Float | None: The mean of the non-null values, or None if there are no non-null values.

Examples: Compute the mean of the values in the value column of the table tbl:

tbl.select(pxt.functions.mean(tbl.value)).collect()

Group by the category column and compute the mean of the value column for each category, assigning the name 'category_mean' to the new column:

tbl.group_by(tbl.category).select(
    tbl.category, category_mean=pxt.functions.mean(tbl.value)
).collect()

uda min()

Signatures

# Signature 1:
@pxt.uda
min(val: pxt.String | None) -> pxt.String | None

# Signature 2:
@pxt.uda
min(val: pxt.Int | None) -> pxt.Int | None

# Signature 3:
@pxt.uda
min(val: pxt.Float | None) -> pxt.Float | None

# Signature 4:
@pxt.uda
min(val: pxt.Bool | None) -> pxt.Bool | None

# Signature 5:
@pxt.uda
min(val: pxt.Timestamp | None) -> pxt.Timestamp | None

Aggregate function that computes the minimum value in a column or grouping. Parameters:

val (String | None): The value to compare.

Returns:

pxt.String | None: The minimum value, or None if there are no non-null values.

Examples: Compute the minimum value in the value column of the table tbl:

tbl.select(pxt.functions.min(tbl.value)).collect()

Group by the category column and compute the minimum value in the value column for each category, assigning the name 'category_min' to the new column:

tbl.group_by(tbl.category).select(
    tbl.category, category_min=pxt.functions.min(tbl.value)
).collect()

uda sum()

Signatures

# Signature 1:
@pxt.uda
sum(val: pxt.Int | None) -> pxt.Int | None

# Signature 2:
@pxt.uda
sum(val: pxt.Float | None) -> pxt.Float | None

Aggregate function that computes the sum of non-null values of a numeric column or grouping. Parameters:

val (Int | None): The numeric value to add to the sum.

Returns:

pxt.Int | None: The sum of the non-null values, or None if there are no non-null values.

Examples: Sum the values in the value column of the table tbl:

tbl.select(pxt.functions.sum(tbl.value)).collect()

Group by the category column and compute the sum of the value column for each category, assigning the name 'category_total' to the new column:

tbl.group_by(tbl.category).select(
    tbl.category, category_total=pxt.functions.sum(tbl.value)
).collect()

​module pixeltable.functions

​func filter()

​func map()

​func sort()

​uda count()

​uda max()

​uda mean()

​uda min()

​uda sum()

module pixeltable.functions

func filter()

func map()

func sort()

uda count()

uda max()

uda mean()

uda min()

uda sum()