LegendQL TDS Frame

The LegendQLApiTdsFrame class provides a Python-like interface for working with TDS (Tabular Data Store) frames. It offers methods for data manipulation, filtering, aggregation, joins, and window functions.

Row Selection Methods

head

LegendQLApiTdsFrame.head(count=5)[source]

Return the first n rows of the TDS frame.

This function returns the first count rows from the frame. It is useful for quickly inspecting the data without loading the entire dataset.

Parameters:: count (int) – Number of rows to return.
Returns:: A new TDS frame containing only the first n rows.
Return type:: LegendQLApiTdsFrame

See also

limit: Alias for head.
drop: Skip the first n rows.
slice: Return a subset of rows by index range.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Get first 5 rows (default)
frame.head().to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10248	1996-07-04	1996-08-01	1996-07-16	Vins et alcools Chevalier
1	10249	1996-07-05	1996-08-16	1996-07-10	Toms Spezialitäten
2	10250	1996-07-08	1996-08-05	1996-07-12	Hanari Carnes
3	10251	1996-07-08	1996-08-05	1996-07-15	Victuailles en stock
4	10252	1996-07-09	1996-08-06	1996-07-11	Suprêmes délices

# Get first 3 rows
frame.head(3).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10248	1996-07-04	1996-08-01	1996-07-16	Vins et alcools Chevalier
1	10249	1996-07-05	1996-08-16	1996-07-10	Toms Spezialitäten
2	10250	1996-07-08	1996-08-05	1996-07-12	Hanari Carnes

limit

LegendQLApiTdsFrame.limit(count=5)[source]

Return the first n rows of the TDS frame.

Alias for head(). This function returns the first count rows from the frame.

Parameters:: count (int) – Number of rows to return.
Returns:: A new TDS frame containing only the first n rows.
Return type:: LegendQLApiTdsFrame

See also

head: Equivalent method.
drop: Skip the first n rows.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Limit to 2 rows
frame.limit(2).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10248	1996-07-04	1996-08-01	1996-07-16	Vins et alcools Chevalier
1	10249	1996-07-05	1996-08-16	1996-07-10	Toms Spezialitäten

drop

LegendQLApiTdsFrame.drop(count=5)[source]

Skip the first n rows of the TDS frame.

Return a new TDS frame with the first count rows removed. This is useful for pagination or skipping header-like rows.

Parameters:: count (int) – Number of rows to skip from the beginning.
Returns:: A new TDS frame with the first n rows removed.
Return type:: LegendQLApiTdsFrame

See also

head: Return the first n rows.
slice: Return a subset of rows by index range.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Skip first 5 rows (default), then show next 5
frame.drop().head(5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10253	1996-07-10	1996-07-24	1996-07-16	Hanari Carnes
1	10254	1996-07-11	1996-08-08	1996-07-23	Chop-suey Chinese
2	10255	1996-07-12	1996-08-09	1996-07-15	Richter Supermarkt
3	10256	1996-07-15	1996-08-12	1996-07-17	Wellington Importadora
4	10257	1996-07-16	1996-08-13	1996-07-22	HILARION-Abastos

# Skip first 10 rows
frame.drop(10).head(5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10258	1996-07-17	1996-08-14	1996-07-23	Ernst Handel
1	10259	1996-07-18	1996-08-15	1996-07-25	Centro comercial Moctezuma
2	10260	1996-07-19	1996-08-16	1996-07-29	Ottilies Käseladen
3	10261	1996-07-19	1996-08-16	1996-07-30	Que Delícia
4	10262	1996-07-22	1996-08-19	1996-07-25	Rattlesnake Canyon Grocery

slice

LegendQLApiTdsFrame.slice(start_row, end_row_exclusive)[source]

Return a subset of rows by index range.

Select rows from start_row (inclusive) to end_row_exclusive (exclusive). This is similar to Python’s list slicing behavior.

Parameters:

start_row (int) – Starting row index (0-based, inclusive).
end_row_exclusive (int) – Ending row index (0-based, exclusive).

Returns:

A new TDS frame containing only the rows in the specified range.

Return type:

LegendQLApiTdsFrame

See also

head: Return the first n rows.
drop: Skip the first n rows.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Get rows 0-4 (first 5 rows)
frame.slice(0, 5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10248	1996-07-04	1996-08-01	1996-07-16	Vins et alcools Chevalier
1	10249	1996-07-05	1996-08-16	1996-07-10	Toms Spezialitäten
2	10250	1996-07-08	1996-08-05	1996-07-12	Hanari Carnes
3	10251	1996-07-08	1996-08-05	1996-07-15	Victuailles en stock
4	10252	1996-07-09	1996-08-06	1996-07-11	Suprêmes délices

# Get rows 5-9
frame.slice(5, 10).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10253	1996-07-10	1996-07-24	1996-07-16	Hanari Carnes
1	10254	1996-07-11	1996-08-08	1996-07-23	Chop-suey Chinese
2	10255	1996-07-12	1996-08-09	1996-07-15	Richter Supermarkt
3	10256	1996-07-15	1996-08-12	1996-07-17	Wellington Importadora
4	10257	1996-07-16	1996-08-13	1996-07-22	HILARION-Abastos

# Get rows 2-6
frame.slice(2, 7).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10250	1996-07-08	1996-08-05	1996-07-12	Hanari Carnes
1	10251	1996-07-08	1996-08-05	1996-07-15	Victuailles en stock
2	10252	1996-07-09	1996-08-06	1996-07-11	Suprêmes délices
3	10253	1996-07-10	1996-07-24	1996-07-16	Hanari Carnes
4	10254	1996-07-11	1996-08-08	1996-07-23	Chop-suey Chinese

Column Selection Methods

select

LegendQLApiTdsFrame.select(columns)[source]

Select specific columns from the TDS frame.

Return a new TDS frame containing only the specified columns. This is useful for reducing the data to only the columns of interest.

Parameters:

columns (Union[str, List[str], Callable[[LegendQLApiTdsRow], Union[LegendQLApiPrimitive, List[LegendQLApiPrimitive]]]]) –

Column(s) to select:

str : Single column name.
list of str : List of column names.
callable : A function that takes a TDS row and returns the column(s) to select.

Returns:

A new TDS frame containing only the selected columns.

Return type:

LegendQLApiTdsFrame

See also

distinct: Get unique rows.
project: Create new computed columns.
extend: Add new columns while keeping existing ones.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Select a single column
frame.select("Ship Name").head(5).to_pandas()

	Ship Name
0	Vins et alcools Chevalier
1	Toms Spezialitäten
2	Hanari Carnes
3	Victuailles en stock
4	Suprêmes délices

# Select multiple columns
frame.select(["Order Id", "Ship Name", "Order Date"]).head(5).to_pandas()

	Order Id	Ship Name	Order Date
0	10248	Vins et alcools Chevalier	1996-07-04
1	10249	Toms Spezialitäten	1996-07-05
2	10250	Hanari Carnes	1996-07-08
3	10251	Victuailles en stock	1996-07-08
4	10252	Suprêmes délices	1996-07-09

# Using a callable to select columns
frame.select(lambda r: [r["Order Id"], r["Ship Name"]]).head(5).to_pandas()

	Order Id	Ship Name
0	10248	Vins et alcools Chevalier
1	10249	Toms Spezialitäten
2	10250	Hanari Carnes
3	10251	Victuailles en stock
4	10252	Suprêmes délices

distinct

LegendQLApiTdsFrame.distinct(columns=None)[source]

Return unique rows based on specified columns.

Remove duplicate rows from the TDS frame. If columns are specified, uniqueness is determined based on those columns only. If no columns are specified, all columns are used to determine uniqueness.

Parameters:

columns (Union[str, List[str], Callable[[LegendQLApiTdsRow], Union[LegendQLApiPrimitive, List[LegendQLApiPrimitive]]], None]) –

Column(s) to consider for identifying duplicates:

None : Use all columns to determine uniqueness.
str : Single column name.
list of str : List of column names.
callable : A function that takes a TDS row and returns column(s) to use for uniqueness.

Returns:

A new TDS frame with duplicate rows removed.

Return type:

LegendQLApiTdsFrame

See also

select: Select specific columns.
filter: Filter rows based on a condition.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Get distinct values for a single column
frame.distinct("Ship Name").head(10).to_pandas()

	Ship Name
0	Chop-suey Chinese
1	Ernst Handel
2	HILARION-Abastos
3	Hanari Carnes
4	Richter Supermarkt
5	Suprêmes délices
6	Toms Spezialitäten
7	Victuailles en stock
8	Vins et alcools Chevalier
9	Wellington Importadora

# Get distinct combinations of multiple columns
frame.distinct(["Ship Name", "Order Date"]).head(10).to_pandas()

	Ship Name	Order Date
0	Chop-suey Chinese	1996-07-11
1	HILARION-Abastos	1996-07-16
2	Hanari Carnes	1996-07-08
3	Hanari Carnes	1996-07-10
4	Richter Supermarkt	1996-07-12
5	Suprêmes délices	1996-07-09
6	Toms Spezialitäten	1996-07-05
7	Victuailles en stock	1996-07-08
8	Vins et alcools Chevalier	1996-07-04
9	Wellington Importadora	1996-07-15

# Using a callable to specify columns
frame.distinct(lambda r: [r["Ship Name"], r["Order Date"]]).head(10).to_pandas()

	Ship Name	Order Date
0	Chop-suey Chinese	1996-07-11
1	HILARION-Abastos	1996-07-16
2	Hanari Carnes	1996-07-08
3	Hanari Carnes	1996-07-10
4	Richter Supermarkt	1996-07-12
5	Suprêmes délices	1996-07-09
6	Toms Spezialitäten	1996-07-05
7	Victuailles en stock	1996-07-08
8	Vins et alcools Chevalier	1996-07-04
9	Wellington Importadora	1996-07-15

Sorting and Filtering

sort

LegendQLApiTdsFrame.sort(sort_infos)[source]

Sort the TDS frame by specified columns.

Return a new TDS frame sorted by the given column(s). Supports ascending and descending sort orders.

Parameters:

sort_infos (Union[str, List[str], Callable[[LegendQLApiTdsRow], Union[LegendQLApiPrimitive, LegendQLApiSortInfo, List[Union[LegendQLApiPrimitive, LegendQLApiSortInfo]]]]]) –

Column(s) to sort by:

str : Single column name (ascending order).
list of str : List of column names (all ascending order).
callableA function that takes a TDS row and returns:
- A column (ascending order by default).
- A LegendQLApiSortInfo with direction (use .ascending() or .descending() on columns).
- A list of columns and/or LegendQLApiSortInfo objects.

Returns:

A new TDS frame with rows sorted according to the specified criteria.

Return type:

LegendQLApiTdsFrame

See also

head: Return the first n rows.
filter: Filter rows based on a condition.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Sort by single column (ascending by default)
frame.sort("Ship Name").head(5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10835	1998-01-15	1998-02-12	1998-01-21	Alfred's Futterkiste
1	10702	1997-10-13	1997-11-24	1997-10-21	Alfred's Futterkiste
2	11011	1998-04-09	1998-05-07	1998-04-13	Alfred's Futterkiste
3	10952	1998-03-16	1998-04-27	1998-03-24	Alfred's Futterkiste
4	10692	1997-10-03	1997-10-31	1997-10-13	Alfred's Futterkiste

# Sort by multiple columns (all ascending)
frame.sort(["Ship Name", "Order Date"]).head(5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10692	1997-10-03	1997-10-31	1997-10-13	Alfred's Futterkiste
1	10702	1997-10-13	1997-11-24	1997-10-21	Alfred's Futterkiste
2	10835	1998-01-15	1998-02-12	1998-01-21	Alfred's Futterkiste
3	10952	1998-03-16	1998-04-27	1998-03-24	Alfred's Futterkiste
4	11011	1998-04-09	1998-05-07	1998-04-13	Alfred's Futterkiste

# Sort with explicit direction using callable
frame.sort(lambda r: r["Ship Name"].descending()).head(5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	11044	1998-04-23	1998-05-21	1998-05-01	Wolski Zajazd
1	10611	1997-07-25	1997-08-22	1997-08-01	Wolski Zajazd
2	10870	1998-02-04	1998-03-04	1998-02-13	Wolski Zajazd
3	10792	1997-12-23	1998-01-20	1997-12-31	Wolski Zajazd
4	10906	1998-02-25	1998-03-11	1998-03-03	Wolski Zajazd

# Sort by multiple columns with different directions
frame.sort(
    lambda r: [r["Ship Name"].ascending(), r["Order Id"].descending()]
).head(5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	11011	1998-04-09	1998-05-07	1998-04-13	Alfred's Futterkiste
1	10952	1998-03-16	1998-04-27	1998-03-24	Alfred's Futterkiste
2	10835	1998-01-15	1998-02-12	1998-01-21	Alfred's Futterkiste
3	10702	1997-10-13	1997-11-24	1997-10-21	Alfred's Futterkiste
4	10692	1997-10-03	1997-10-31	1997-10-13	Alfred's Futterkiste

filter

LegendQLApiTdsFrame.filter(filter_function)[source]

Filter rows based on a condition.

Return a new TDS frame containing only the rows that satisfy the given condition.

Parameters:: filter_function (Callable[[LegendQLApiTdsRow], Union[bool, PyLegendBoolean]]) – A function that takes a TDS row and returns a boolean value. Rows where the function returns True are kept.
Returns:: A new TDS frame containing only the rows that match the condition.
Return type:: LegendQLApiTdsFrame

See also

distinct: Remove duplicate rows.
head: Return the first n rows.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Filter by equality
frame.filter(lambda r: r["Ship Name"] == "Wolski Zajazd").head(5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10374	1996-12-05	1997-01-02	1996-12-09	Wolski Zajazd
1	10611	1997-07-25	1997-08-22	1997-08-01	Wolski Zajazd
2	10792	1997-12-23	1998-01-20	1997-12-31	Wolski Zajazd
3	10870	1998-02-04	1998-03-04	1998-02-13	Wolski Zajazd
4	10906	1998-02-25	1998-03-11	1998-03-03	Wolski Zajazd

# Filter with comparison operators
frame.filter(lambda r: r["Order Id"] > 10500).head(5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10501	1997-04-09	1997-05-07	1997-04-16	Blauer See Delikatessen
1	10502	1997-04-10	1997-05-08	1997-04-29	Pericles Comidas clásicas
2	10503	1997-04-11	1997-05-09	1997-04-16	Hungry Owl All-Night Grocers
3	10504	1997-04-11	1997-05-09	1997-04-18	White Clover Markets
4	10505	1997-04-14	1997-05-12	1997-04-21	Mère Paillarde

# Filter with multiple conditions (AND)
frame.filter(
    lambda r: (r["Order Id"] > 10250) & (r["Order Id"] < 10560)
).head(5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10251	1996-07-08	1996-08-05	1996-07-15	Victuailles en stock
1	10252	1996-07-09	1996-08-06	1996-07-11	Suprêmes délices
2	10253	1996-07-10	1996-07-24	1996-07-16	Hanari Carnes
3	10254	1996-07-11	1996-08-08	1996-07-23	Chop-suey Chinese
4	10255	1996-07-12	1996-08-09	1996-07-15	Richter Supermarkt

Column Transformation Methods

rename

LegendQLApiTdsFrame.rename(column_renames)[source]

Rename columns in the TDS frame.

Return a new TDS frame with specified columns renamed.

Parameters:

column_renames (Union[Tuple[str, str], List[Tuple[str, str]], Callable[[LegendQLApiTdsRow], Union[Tuple[LegendQLApiPrimitive, str], List[Tuple[LegendQLApiPrimitive, str]]]]]) –

Column rename specification:

tuple (str, str) : Single rename as (old_name, new_name).
list of tuples : Multiple renames as [(old1, new1), (old2, new2), …].
callable : A function that takes a TDS row and returns tuple(s) of (column, new_name).

Returns:

A new TDS frame with the specified columns renamed.

Return type:

LegendQLApiTdsFrame

See also

select: Select specific columns.
extend: Add new columns.
project: Create new computed columns.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Rename a single column
frame.rename(("Ship Name", "Vessel Name")).head(3).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Vessel Name
0	10248	1996-07-04	1996-08-01	1996-07-16	Vins et alcools Chevalier
1	10249	1996-07-05	1996-08-16	1996-07-10	Toms Spezialitäten
2	10250	1996-07-08	1996-08-05	1996-07-12	Hanari Carnes

# Rename multiple columns
frame.rename(
    [("Ship Name", "Vessel Name"), ("Order Date", "Date Ordered")]
).head(3).to_pandas()

	Order Id	Date Ordered	Required Date	Shipped Date	Vessel Name
0	10248	1996-07-04	1996-08-01	1996-07-16	Vins et alcools Chevalier
1	10249	1996-07-05	1996-08-16	1996-07-10	Toms Spezialitäten
2	10250	1996-07-08	1996-08-05	1996-07-12	Hanari Carnes

# Using a callable to rename columns
frame.rename(lambda r: (r["Ship Name"], "Vessel Name")).head(3).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Vessel Name
0	10248	1996-07-04	1996-08-01	1996-07-16	Vins et alcools Chevalier
1	10249	1996-07-05	1996-08-16	1996-07-10	Toms Spezialitäten
2	10250	1996-07-08	1996-08-05	1996-07-12	Hanari Carnes

extend

LegendQLApiTdsFrame.extend(extend_columns)[source]

Add new computed columns to the TDS frame.

Return a new TDS frame with additional columns computed from existing data. The original columns are preserved.

Parameters:

extend_columns (Union[Tuple[str, Callable[[LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]]], Tuple[str, Callable[[LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]], Callable[[PyLegendPrimitiveCollection], PyLegendPrimitive]], List[Union[Tuple[str, Callable[[LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]]], Tuple[str, Callable[[LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]], Callable[[PyLegendPrimitiveCollection], PyLegendPrimitive]]]]]) –

Column extension specification:

tuple (name, func) : Add a column with given name using the function to compute values from each row.
tuple (name, func, agg_func) : Add a column with an aggregation function applied.
list of tuples : Add multiple columns.

Returns:

A new TDS frame with the additional computed columns.

Return type:

LegendQLApiTdsFrame

See also

project: Create new columns (replacing existing).
rename: Rename existing columns.
select: Select specific columns.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Add a single computed column
extended = frame.extend(("Ship Name Upper", lambda r: r["Ship Name"].upper()))
extended.select(["Ship Name", "Ship Name Upper"]).head(5).to_pandas()

	Ship Name	Ship Name Upper
0	Vins et alcools Chevalier	VINS ET ALCOOLS CHEVALIER
1	Toms Spezialitäten	TOMS SPEZIALITÄTEN
2	Hanari Carnes	HANARI CARNES
3	Victuailles en stock	VICTUAILLES EN STOCK
4	Suprêmes délices	SUPRÊMES DÉLICES

# Add multiple computed columns
cols = ["Ship Name", "Ship Name Upper", "Ship Name Lower"]
frame.extend([
    ("Ship Name Upper", lambda r: r["Ship Name"].upper()),
    ("Ship Name Lower", lambda r: r["Ship Name"].lower())
]).select(cols).head(5).to_pandas()

	Ship Name	Ship Name Upper	Ship Name Lower
0	Vins et alcools Chevalier	VINS ET ALCOOLS CHEVALIER	vins et alcools chevalier
1	Toms Spezialitäten	TOMS SPEZIALITÄTEN	toms spezialitäten
2	Hanari Carnes	HANARI CARNES	hanari carnes
3	Victuailles en stock	VICTUAILLES EN STOCK	victuailles en stock
4	Suprêmes délices	SUPRÊMES DÉLICES	suprêmes délices

project

LegendQLApiTdsFrame.project(project_columns)[source]

Create a new TDS frame with specified computed columns.

Unlike extend(), which adds columns to existing ones, project creates a new frame with only the specified columns.

Parameters:

project_columns (Union[Tuple[str, Callable[[LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]]], List[Tuple[str, Callable[[LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]]]]]) –

Column specification(s) as (column_name, function):

tuple (str, callable) : Single column with name and computation function.
list of tuples : Multiple columns.

The function takes a TDS row and returns the column value.

Returns:

A new TDS frame containing only the projected columns.

Return type:

LegendQLApiTdsFrame

See also

extend: Add columns while keeping existing ones.
select: Select existing columns.
rename: Rename existing columns.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Project single column (copy with new name)
frame.project(("Order Number", lambda r: r["Order Id"])).head(5).to_pandas()

	Order Number
0	10248
1	10249
2	10250
3	10251
4	10252

# Project multiple columns with transformations
frame.project([
    ("Order Number", lambda r: r["Order Id"]),
    ("Vessel", lambda r: r["Ship Name"].upper()),
    ("Vessel Lower", lambda r: r["Ship Name"].lower())
]).head(5).to_pandas()

	Order Number	Vessel	Vessel Lower
0	10248	VINS ET ALCOOLS CHEVALIER	vins et alcools chevalier
1	10249	TOMS SPEZIALITÄTEN	toms spezialitäten
2	10250	HANARI CARNES	hanari carnes
3	10251	VICTUAILLES EN STOCK	victuailles en stock
4	10252	SUPRÊMES DÉLICES	suprêmes délices

# Project with existing column values
frame.project([
    ("ID", lambda r: r["Order Id"]),
    ("Name", lambda r: r["Ship Name"]),
    ("Date", lambda r: r["Order Date"])
]).head(5).to_pandas()

	ID	Name	Date
0	10248	Vins et alcools Chevalier	1996-07-04
1	10249	Toms Spezialitäten	1996-07-05
2	10250	Hanari Carnes	1996-07-08
3	10251	Victuailles en stock	1996-07-08
4	10252	Suprêmes délices	1996-07-09

cast

LegendQLApiTdsFrame.cast(column_type_map)[source]

Cast specific columns to new types.

Return a new TDS frame where the types of the specified columns are updated according to the provided type map. All other columns retain their original types.

Parameters:: column_type_map (Dict[str, Union[PrimitiveType, Tuple[PrimitiveType, ...]]]) – A mapping from column names to target types. Use functions from the pylegend.type_factory module to create target types.
Returns:: A new TDS frame with the specified columns cast to the new types.
Return type:: LegendQLApiTdsFrame

Examples

Download Interactive Notebook

from pylegend import type_factory as tf
from pylegend.core.tds.tds_column import PrimitiveTdsColumn
from pylegend.extensions.tds.legendql_api.frames.legendql_api_table_spec_input_frame import (
    LegendQLApiTableSpecInputFrame
)

frame = LegendQLApiTableSpecInputFrame(
    ['db', 'schema', 'order'],
    [
        PrimitiveTdsColumn.integer_column("Order Id"),
        PrimitiveTdsColumn.date_column("Order Date"),
        PrimitiveTdsColumn.string_column("Ship Name"),
        PrimitiveTdsColumn.float_column("Amount"),
        PrimitiveTdsColumn.decimal_column("Discount"),
    ]
)

# Cast using simple types
cast_frame_1 = frame.cast({
    "Order Date": tf.datetime(),
    "Order Id": tf.number(),
    "Amount": tf.number(),
})
print(cast_frame_1.to_pure_query())

#Table(db.schema.order)#
  ->cast(@meta::pure::metamodel::relation::Relation<('Order Id':Number, 'Order Date':DateTime, 'Ship Name':String, Amount:Number, Discount:Decimal)>)

# Cast using precise primitive types (including parameterized)
cast_frame_2 = frame.cast({
    "Order Date": tf.timestamp(),
    "Order Id": tf.bigint(),
    "Ship Name": tf.varchar(200),
    "Amount": tf.float4(),
    "Discount": tf.numeric(10, 2),
})
print(cast_frame_2.to_pure_query())

#Table(db.schema.order)#
  ->cast(@meta::pure::metamodel::relation::Relation<('Order Id':BigInt, 'Order Date':Timestamp, 'Ship Name':Varchar(200), Amount:Float4, Discount:Numeric(10, 2))>)

Combining Frames

concatenate

LegendQLApiTdsFrame.concatenate(other)[source]

Concatenate two TDS frames vertically.

Append the rows of another TDS frame to the current frame. Both frames must have compatible schemas (same columns).

Parameters:: other (LegendQLApiTdsFrame) – The TDS frame to append to the current frame.
Returns:: A new TDS frame containing all rows from both frames.
Return type:: LegendQLApiTdsFrame

See also

join: Combine frames horizontally based on a condition.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Get first 3 rows and rows 10-12, then concatenate
first_rows = frame.head(3)
other_rows = frame.slice(10, 13)
first_rows.concatenate(other_rows).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name
0	10248	1996-07-04	1996-08-01	1996-07-16	Vins et alcools Chevalier
1	10249	1996-07-05	1996-08-16	1996-07-10	Toms Spezialitäten
2	10250	1996-07-08	1996-08-05	1996-07-12	Hanari Carnes
3	10258	1996-07-17	1996-08-14	1996-07-23	Ernst Handel
4	10259	1996-07-18	1996-08-15	1996-07-25	Centro comercial Moctezuma
5	10260	1996-07-19	1996-08-16	1996-07-29	Ottilies Käseladen

join

LegendQLApiTdsFrame.join(other, join_condition, join_type='LEFT_OUTER')[source]

Join two TDS frames based on a condition.

Combine columns from two TDS frames based on a join condition.

Parameters:

other (LegendQLApiTdsFrame) – The right TDS frame to join with.
join_condition (Callable[[LegendQLApiTdsRow, LegendQLApiTdsRow], Union[bool, PyLegendBoolean]]) – A function that takes two TDS rows (left, right) and returns a boolean indicating whether the rows should be joined.
join_type (str) –
Type of join to perform:
- 'INNER' : Only matching rows from both frames.
- 'LEFT_OUTER' : All rows from left, matching from right.
- 'RIGHT_OUTER' : All rows from right, matching from left.
- 'FULL' : All rows from both frames.

Returns:

A new TDS frame with columns from both frames.

Return type:

LegendQLApiTdsFrame

See also

inner_join: Convenience method for inner join.
left_join: Convenience method for left outer join.
right_join: Convenience method for right outer join.
full_join: Convenience method for full outer join.
as_of_join: Join based on temporal proximity.
concatenate: Combine frames vertically.

Examples

Download Interactive Notebook

import pylegend
orders = pylegend.samples.legendql_api.northwind_orders_frame()

# Self-join example: join orders with a filtered version
# Rename duplicate columns to avoid conflicts
cols = ["Order Id", "Ship Name"]
renames = [("Order Id", "Right Order Id"), ("Ship Name", "Filtered Ship Name")]
filtered_orders = orders.filter(
    lambda r: r["Order Id"] > 10300
).select(cols).rename(renames)
orders.join(
    filtered_orders,
    lambda l, r: l["Order Id"] == r["Right Order Id"],
    "INNER"
).head(5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name	Right Order Id	Filtered Ship Name
0	10301	1996-09-09	1996-10-07	1996-09-17	Die Wandernde Kuh	10301	Die Wandernde Kuh
1	10302	1996-09-10	1996-10-08	1996-10-09	Suprêmes délices	10302	Suprêmes délices
2	10303	1996-09-11	1996-10-09	1996-09-18	Godos Cocina Típica	10303	Godos Cocina Típica
3	10304	1996-09-12	1996-10-10	1996-09-17	Tortuga Restaurante	10304	Tortuga Restaurante
4	10305	1996-09-13	1996-10-11	1996-10-09	Old World Delicatessen	10305	Old World Delicatessen

inner_join

LegendQLApiTdsFrame.inner_join(other, join_condition)[source]

Perform an inner join with another TDS frame.

Return only the rows that have matching values in both frames.

Parameters:

other (LegendQLApiTdsFrame) – The right TDS frame to join with.
join_condition (Callable[[LegendQLApiTdsRow, LegendQLApiTdsRow], Union[bool, PyLegendBoolean]]) – A function that takes two TDS rows (left, right) and returns a boolean indicating whether the rows should be joined.

Returns:

A new TDS frame containing only matching rows from both frames.

Return type:

LegendQLApiTdsFrame

See also

join: General join method with configurable join type.
left_join: Left outer join.
right_join: Right outer join.

Examples

Download Interactive Notebook

import pylegend
orders = pylegend.samples.legendql_api.northwind_orders_frame()

# Inner join with filtered data
# Rename duplicate columns to avoid conflicts
cols = ["Order Id", "Ship Name"]
renames = [("Order Id", "Right Order Id"), ("Ship Name", "Filtered Ship Name")]
filtered = orders.filter(
    lambda r: r["Order Id"] > 10300
).select(cols).rename(renames)
orders.inner_join(
    filtered,
    lambda l, r: l["Order Id"] == r["Right Order Id"]
).head(5).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name	Right Order Id	Filtered Ship Name
0	10301	1996-09-09	1996-10-07	1996-09-17	Die Wandernde Kuh	10301	Die Wandernde Kuh
1	10302	1996-09-10	1996-10-08	1996-10-09	Suprêmes délices	10302	Suprêmes délices
2	10303	1996-09-11	1996-10-09	1996-09-18	Godos Cocina Típica	10303	Godos Cocina Típica
3	10304	1996-09-12	1996-10-10	1996-09-17	Tortuga Restaurante	10304	Tortuga Restaurante
4	10305	1996-09-13	1996-10-11	1996-10-09	Old World Delicatessen	10305	Old World Delicatessen

left_join

LegendQLApiTdsFrame.left_join(other, join_condition)[source]

Perform a left outer join with another TDS frame.

Return all rows from the left frame, with matching rows from the right frame. Non-matching rows will have null values for the right frame columns.

Parameters:

other (LegendQLApiTdsFrame) – The right TDS frame to join with.
join_condition (Callable[[LegendQLApiTdsRow, LegendQLApiTdsRow], Union[bool, PyLegendBoolean]]) – A function that takes two TDS rows (left, right) and returns a boolean indicating whether the rows should be joined.

Returns:

A new TDS frame with all left rows and matching right rows.

Return type:

LegendQLApiTdsFrame

See also

join: General join method with configurable join type.
inner_join: Inner join.
right_join: Right outer join.

Examples

Download Interactive Notebook

import pylegend
orders = pylegend.samples.legendql_api.northwind_orders_frame()

# Left join - all orders with filtered info where available
# Rename duplicate columns to avoid conflicts
cols = ["Order Id", "Ship Name"]
renames = [("Order Id", "Right Order Id"), ("Ship Name", "Filtered Ship Name")]
filtered_info = orders.filter(
    lambda r: r["Order Id"] > 10300
).select(cols).rename(renames).head(10)
orders.head(15).left_join(
    filtered_info,
    lambda l, r: l["Order Id"] == r["Right Order Id"]
).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name	Right Order Id	Filtered Ship Name
0	10248	1996-07-04	1996-08-01	1996-07-16	Vins et alcools Chevalier	<NA>	NaN
1	10249	1996-07-05	1996-08-16	1996-07-10	Toms Spezialitäten	<NA>	NaN
2	10250	1996-07-08	1996-08-05	1996-07-12	Hanari Carnes	<NA>	NaN
3	10251	1996-07-08	1996-08-05	1996-07-15	Victuailles en stock	<NA>	NaN
4	10252	1996-07-09	1996-08-06	1996-07-11	Suprêmes délices	<NA>	NaN
5	10253	1996-07-10	1996-07-24	1996-07-16	Hanari Carnes	<NA>	NaN
6	10254	1996-07-11	1996-08-08	1996-07-23	Chop-suey Chinese	<NA>	NaN
7	10255	1996-07-12	1996-08-09	1996-07-15	Richter Supermarkt	<NA>	NaN
8	10256	1996-07-15	1996-08-12	1996-07-17	Wellington Importadora	<NA>	NaN
9	10257	1996-07-16	1996-08-13	1996-07-22	HILARION-Abastos	<NA>	NaN
10	10258	1996-07-17	1996-08-14	1996-07-23	Ernst Handel	<NA>	NaN
11	10259	1996-07-18	1996-08-15	1996-07-25	Centro comercial Moctezuma	<NA>	NaN
12	10260	1996-07-19	1996-08-16	1996-07-29	Ottilies Käseladen	<NA>	NaN
13	10261	1996-07-19	1996-08-16	1996-07-30	Que Delícia	<NA>	NaN
14	10262	1996-07-22	1996-08-19	1996-07-25	Rattlesnake Canyon Grocery	<NA>	NaN

right_join

LegendQLApiTdsFrame.right_join(other, join_condition)[source]

Perform a right outer join with another TDS frame.

Return all rows from the right frame, with matching rows from the left frame. Non-matching rows will have null values for the left frame columns.

Parameters:

other (LegendQLApiTdsFrame) – The right TDS frame to join with.
join_condition (Callable[[LegendQLApiTdsRow, LegendQLApiTdsRow], Union[bool, PyLegendBoolean]]) – A function that takes two TDS rows (left, right) and returns a boolean indicating whether the rows should be joined.

Returns:

A new TDS frame with all right rows and matching left rows.

Return type:

LegendQLApiTdsFrame

See also

join: General join method with configurable join type.
inner_join: Inner join.
left_join: Left outer join.

Examples

Download Interactive Notebook

import pylegend
orders = pylegend.samples.legendql_api.northwind_orders_frame()

# Right join example
# Rename duplicate columns to avoid conflicts
cols = ["Order Id", "Ship Name"]
renames = [("Order Id", "Right Order Id"), ("Ship Name", "Filtered Ship Name")]
filtered_info = orders.filter(
    lambda r: r["Order Id"] > 10300
).select(cols).rename(renames).head(10)
orders.head(5).right_join(
    filtered_info,
    lambda l, r: l["Order Id"] == r["Right Order Id"]
).to_pandas()

	Order Id	Order Date	Required Date	Shipped Date	Ship Name	Right Order Id	Filtered Ship Name
0	<NA>	NaT	NaT	NaT	NaN	10301	Die Wandernde Kuh
1	<NA>	NaT	NaT	NaT	NaN	10302	Suprêmes délices
2	<NA>	NaT	NaT	NaT	NaN	10303	Godos Cocina Típica
3	<NA>	NaT	NaT	NaT	NaN	10304	Tortuga Restaurante
4	<NA>	NaT	NaT	NaT	NaN	10305	Old World Delicatessen
5	<NA>	NaT	NaT	NaT	NaN	10306	Romero y tomillo
6	<NA>	NaT	NaT	NaT	NaN	10307	Lonesome Pine Restaurant
7	<NA>	NaT	NaT	NaT	NaN	10308	Ana Trujillo Emparedados y helados
8	<NA>	NaT	NaT	NaT	NaN	10309	Hungry Owl All-Night Grocers
9	<NA>	NaT	NaT	NaT	NaN	10310	The Big Cheese

Aggregation

group_by

LegendQLApiTdsFrame.group_by(grouping_columns, aggregate_specifications)[source]

Group rows and apply aggregate functions.

Group the TDS frame by the specified columns and compute aggregate values for each group.

Parameters:

grouping_columns (Union[str, List[str], Callable[[LegendQLApiTdsRow], Union[LegendQLApiPrimitive, List[LegendQLApiPrimitive]]]]) –
Column(s) to group by:
- str : Single column name.
- list of str : Multiple column names.
- callable : A function returning column(s) to group by.
aggregate_specifications (Union[Tuple[str, Callable[[LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]], Callable[[PyLegendPrimitiveCollection], PyLegendPrimitive]], List[Tuple[str, Callable[[LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]], Callable[[PyLegendPrimitiveCollection], PyLegendPrimitive]]]]) –
Aggregation specification as tuple(s) of: (result_column_name, column_selector, aggregate_function)

Common aggregate functions from pylegend.agg:
- count() : Count of values.
- sum() : Sum of values.
- avg() : Average of values.
- min() : Minimum value.
- max() : Maximum value.

Returns:

A new TDS frame with grouped and aggregated data.

Return type:

LegendQLApiTdsFrame

See also

distinct: Get unique rows.
filter: Filter rows before grouping.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Group by single column with count using lambda syntax
frame.group_by(
    lambda r: r["Ship Name"],
    ("Order Count", lambda r: r["Order Id"], lambda col: col.count())
).head(10).to_pandas()

	Ship Name	Order Count
0	Alfred's Futterkiste	5
1	Alfreds Futterkiste	1
2	Ana Trujillo Emparedados y helados	4
3	Antonio Moreno Taquería	7
4	Around the Horn	13
5	B's Beverages	10
6	Berglunds snabbköp	18
7	Blauer See Delikatessen	7
8	Blondel père et fils	11
9	Bon app'	17

# Group by single column with multiple aggregations using lambda syntax
frame.group_by(
    lambda r: r["Ship Name"],
    [
        ("Order Count", lambda r: r["Order Id"], lambda col: col.count()),
        ("Min Order Id", lambda r: r["Order Id"], lambda col: col.min()),
        ("Max Order Id", lambda r: r["Order Id"], lambda col: col.max())
    ]
).head(10).to_pandas()

	Ship Name	Order Count	Min Order Id	Max Order Id
0	Alfred's Futterkiste	5	10692	11011
1	Alfreds Futterkiste	1	10643	10643
2	Ana Trujillo Emparedados y helados	4	10308	10926
3	Antonio Moreno Taquería	7	10365	10856
4	Around the Horn	13	10355	11016
5	B's Beverages	10	10289	11023
6	Berglunds snabbköp	18	10278	10924
7	Blauer See Delikatessen	7	10501	11058
8	Blondel père et fils	11	10265	10826
9	Bon app'	17	10331	11076

# Chained group_by operations - grouping on result of previous aggregation
frame2 = frame.group_by(
    lambda r: r["Ship Name"],
    ("Order Count", lambda r: r["Order Id"], lambda col: col.count())
)
frame2.group_by(
    lambda r: r["Ship Name"],
    ("Count of Counts", lambda r: r["Order Count"], lambda col: col.count())
).head(10).to_pandas()

	Ship Name	Count of Counts
0	Alfred's Futterkiste	1
1	Alfreds Futterkiste	1
2	Ana Trujillo Emparedados y helados	1
3	Antonio Moreno Taquería	1
4	Around the Horn	1
5	B's Beverages	1
6	Berglunds snabbköp	1
7	Blauer See Delikatessen	1
8	Blondel père et fils	1
9	Bon app'	1

Window Functions

rows

LegendQLApiTdsFrame.rows(start, end)[source]

Create a row-based window frame specification.

Define a window frame based on row offsets relative to the current row. Used with window() and window_extend() for window functions.

Parameters:

start (Union[str, int]) –
Start boundary of the window:
- "unbounded" : From the first row of the partition.
- 0 : Current row.
- Negative int : That many rows before current row.
- Positive int : That many rows after current row.
end (Union[str, int]) –
End boundary of the window:
- "unbounded" : To the last row of the partition.
- 0 : Current row.
- Negative int : That many rows before current row.
- Positive int : That many rows after current row.

Returns:

A window frame specification for use with window functions.

Return type:

PyLegendWindowFrame

See also

range: Create a range-based window frame.
window: Create a window specification.
window_extend: Apply window functions.

range

LegendQLApiTdsFrame.range(*, number_start=None, number_end=None, duration_start=None, duration_start_unit=None, duration_end=None, duration_end_unit=None)[source]

Create a range-based window frame specification.

Define a window frame based on value ranges (numeric or duration) relative to the current row’s order-by column value. Used with window() and window_extend() for window functions.

Parameters:

number_start (Union[str, int, float, None]) – Numeric start boundary. Use "unbounded" for no lower limit.
number_end (Union[str, int, float, None]) – Numeric end boundary. Use "unbounded" for no upper limit.
duration_start (Union[str, int, float, None]) – Duration start boundary for time-based ranges.
duration_start_unit (Optional[str]) – Time unit for duration_start (e.g., "DAYS", "HOURS").
duration_end (Union[str, int, float, None]) – Duration end boundary for time-based ranges.
duration_end_unit (Optional[str]) – Time unit for duration_end.

Returns:

A window frame specification for use with window functions.

Return type:

PyLegendWindowFrame

Raises:

ValueError – If neither numeric nor duration range is provided, or if both are provided.

See also

rows: Create a row-based window frame.
window: Create a window specification.
window_extend: Apply window functions.

window

LegendQLApiTdsFrame.window(partition_by=None, order_by=None, frame=None)[source]

Create a window specification for window functions.

Define how rows are partitioned, ordered, and framed for window function calculations.

Parameters:

partition_by (Union[str, List[str], Callable[[LegendQLApiTdsRow], Union[LegendQLApiPrimitive, List[LegendQLApiPrimitive]]], None]) –
Column(s) to partition the data by. Each partition is processed independently for window calculations.
- None : Entire dataset is one partition.
- str : Single column name.
- list of str : Multiple column names.
- callable : Function returning column(s).
order_by (Union[str, List[str], Callable[[LegendQLApiTdsRow], Union[LegendQLApiPrimitive, LegendQLApiSortInfo, List[Union[LegendQLApiPrimitive, LegendQLApiSortInfo]]]], None]) –
Column(s) to order rows within each partition.
- None : No specific order.
- str : Single column name (ascending).
- list of str : Multiple columns (ascending).
- callable : Function returning column(s) with optional .ascending() or .descending() direction.
frame (Optional[PyLegendWindowFrame]) – Window frame specification created by rows() or range(). Defines which rows relative to the current row are included in the calculation.

Returns:

A window specification for use with window_extend().

Return type:

PyLegendWindow

See also

rows: Create a row-based window frame.
range: Create a range-based window frame.
window_extend: Apply window functions using the window specification.

window_extend

LegendQLApiTdsFrame.window_extend(window, extend_columns)[source]

Add columns computed using window functions.

Extend the TDS frame with new columns calculated using window functions over the specified window.

Parameters:

window (PyLegendWindow) – Window specification created by window().
extend_columns (Union[Tuple[str, Callable[[LegendQLApiPartialFrame, PyLegendWindowReference, LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]]], Tuple[str, Callable[[LegendQLApiPartialFrame, PyLegendWindowReference, LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]], Callable[[PyLegendPrimitiveCollection], PyLegendPrimitive]], List[Union[Tuple[str, Callable[[LegendQLApiPartialFrame, PyLegendWindowReference, LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]]], Tuple[str, Callable[[LegendQLApiPartialFrame, PyLegendWindowReference, LegendQLApiTdsRow], Union[int, float, str, bool, date, datetime, Decimal, PyLegendPrimitive]], Callable[[PyLegendPrimitiveCollection], PyLegendPrimitive]]]]]) –
Column specification(s) as:
- tuple (name, func) : Column name and function that receives (partial_frame, window_ref, row) and returns a value.
- tuple (name, func, agg_func) : With aggregation function.
- list of tuples : Multiple window columns.
The function parameters:
- partial_frame : Access to partitioned frame data.
- window_ref : Window reference for functions like row_number(), rank(), lead(), lag().
- row : Current row data.

Returns:

A new TDS frame with additional window-computed columns.

Return type:

LegendQLApiTdsFrame

See also

window: Create a window specification.
rows: Create a row-based window frame.
range: Create a range-based window frame.
extend: Add computed columns without window functions.

Examples

Download Interactive Notebook

import pylegend
frame = pylegend.samples.legendql_api.northwind_orders_frame()

# Add a single window function column
win = frame.window(partition_by="Ship Name", order_by="Order Id")
frame.window_extend(
    win,
    ("RowNumber", lambda p, w, r: p.row_number(r))
).select(
    ["Ship Name", "Order Id", "RowNumber"]
).head(5).to_pandas()

	Ship Name	Order Id	RowNumber
0	Vins et alcools Chevalier	10248	1
1	Toms Spezialitäten	10249	1
2	Hanari Carnes	10250	1
3	Victuailles en stock	10251	1
4	Suprêmes délices	10252	1

# Add basic window function columns
frame.window_extend(
    frame.window(partition_by="Ship Name", order_by="Order Id"),
    [
        ("RowNumber", lambda p, w, r: p.row_number(r)),
        ("Rank", lambda p, w, r: p.rank(w, r))
    ]
).select(
   ["Ship Name", "Order Id", "RowNumber", "Rank"]
).head(5).to_pandas()

	Ship Name	Order Id	RowNumber	Rank
0	Vins et alcools Chevalier	10248	1	1
1	Toms Spezialitäten	10249	1	1
2	Hanari Carnes	10250	1	1
3	Victuailles en stock	10251	1	1
4	Suprêmes délices	10252	1	1

PyLegend

Table of Contents

Quick Search

LegendQL TDS Frame

Row Selection Methods

head

limit

drop

slice

Column Selection Methods

select

distinct

Sorting and Filtering

sort

filter

Column Transformation Methods

rename

extend

project

cast

Combining Frames

concatenate

join

inner_join

left_join

right_join

Aggregation

group_by

Window Functions

rows

range

window

window_extend