orcalib.table_query

TableQuery

TableQuery(
    db_name,
    primary_table,
    columns=None,
    filter=None,
    order_by_columns=None,
    limit=None,
    default_order=Order.ASCENDING,
)

Bases: Generic[T]

A query on a (for now) single table. This is used to build up a query and then execute it with .fetch()

Note

Usually this is not called directly but through the table.select method.

Parameters:

• db_name (str) –

  The name of the database to query

• primary_table (TableHandle) –

  The primary table to query

• columns (list[ColumnName] | None, default: None ) –

  The columns we’re selecting to return

• filter (OrcaExpr | None, default: None ) –

  The filter to apply to the query

• order_by_columns (OrderByColumns | None, default: None ) –

  The columns to order by

• limit (int | None, default: None ) –

  The maximum number of rows to return

• default_order (Order, default: ASCENDING ) –

  The default order to use with order_by if no order is specified

select

select(*columns)

Selects the given columns from the table. If no columns are specified, all columns are selected.

Parameters:

• columns (ColumnName | ColumnHandle | tuple[ColumnName | ColumnHandle, Order], default: () ) –

  The columns to select

Returns:

• T –

  query handle for chaining

Examples:

>>> query.select("column1", "column2").fetch(1)
[{"column1": "value1", "column2": "value2"}]

where

where(filter)

Filters the table by the given filter expression.

Parameters:

• filter (OrcaExpr) –

  The filter expression

Returns:

• T –

  query handle for chaining

Examples:

>>> query.where(table.column1 == "value1").fetch(1)
[{"column1": "value1", "column2": "value2"}]

order_by

order_by(*columns, default_order=Order.ASCENDING)

Orders the table by the given columns. If no columns are specified, the table is ordered by the primary key.

Parameters:

• columns (ColumnName | ColumnHandle | tuple[ColumnName | ColumnHandle, Order], default: () ) –

  The columns to order by

• default_order (Order, default: ASCENDING ) –

  The default order to use with order_by if no order is specified

Returns:

• T –

  query handle for chaining

Examples:

>>> query.order_by("column1", (table.column2, "ASC")).fetch(1)
[{"column1": "value1", "column2": "value2"}]

limit

limit(limit)

Limits the number of rows returned by the query.

Parameters:

• limit (int) –

  The maximum number of rows to return

Returns:

• T –

  query handle for chaining

Examples:

>>> query.limit(1).fetch()
[{"column1": "value1", "column2": "value2"}]

fetch

fetch(limit=None, include_ids=False)

Fetch rows from the table

Parameters:

• limit (int | None, default: None ) –

  The maximum number of rows to return

• include_ids (bool, default: False ) –

  Whether to include the row ids in the result

Returns:

• list[dict[ColumnName, Any] | tuple[int, dict[ColumnName, Any]]] –

  A list of dictionaries containing column value mappings

df

df(limit)

Fetch rows from the table and return as a DataFrame

Parameters:

• limit (int | None) –

  The maximum number of rows to return

Returns:

• DataFrame –

  A DataFrame containing the rows