Queries

CLASSiceaxe.queries.QueryBuilder

QueryBuilder

The QueryBuilder owns all construction of the SQL string given python method chaining. Each function call returns a reference to self, so you can construct as many queries as you want in a single line of code.

Internally we store most input-arguments as-is. We provide runtime value-checking to make sure the right objects are being passed in to query manipulation functions so our final build() will deterministically succeed if the query build was successful.

Note that this runtime check-checking validates different types than the static analysis. To satisfy Python logical operations (like join(ModelA.id == ModelB.id)) we have many overloaded operators that return objects at runtime but are masked to their Python types for the purposes of static analysis. This implementation detail should be transparent to the user but is noted in case you see different types through runtime inspection than you see during the typehints.

Class Attributes

  • Name
    query_type
    Type
    QueryType | None
    Description
  • Name
    main_model
    Type
    Type[TableBase] | None
    Description
  • Name
    return_typehint
    Type
    P
    Description
  • Name
    where_conditions
    Type
    list[FieldComparison | FieldComparisonGroup]
    Description
  • Name
    order_by_clauses
    Type
    list[str]
    Description
  • Name
    join_clauses
    Type
    list[str]
    Description
  • Name
    limit_value
    Type
    int | None
    Description
  • Name
    offset_value
    Type
    int | None
    Description
  • Name
    group_by_fields
    Type
    list[DBFieldClassDefinition]
    Description
  • Name
    having_conditions
    Type
    list[FieldComparison]
    Description
  • Name
    update_values
    Type
    list[tuple[DBFieldClassDefinition, Any]]
    Description
  • Name
    select_fields
    Type
    list[QueryLiteral]
    Description
  • Name
    select_raw
    Type
    list[DBFieldClassDefinition | Type[TableBase] | FunctionMetadata]
    Description
  • Name
    select_aggregate_count
    Type
    Description
  • Name
    text_query
    Type
    str | None
    Description
  • Name
    text_variables
    Type
    list[Any]
    Description

Class Methods

  • Name
    select
    Return type
    QueryBuilder[tuple[T, *Ts], Literal['SELECT']] | QueryBuilder[T, Literal['SELECT']]
    Description

    Creates a new select query for the given fields. Returns the same QueryBuilder that is now flagged as a SELECT query.

  • Name
    update
    Return type
    QueryBuilder[None, Literal['UPDATE']]
    Description

    Creates a new update query for the given model. Returns the same QueryBuilder that is now flagged as an UPDATE query.

  • Name
    delete
    Return type
    QueryBuilder[None, Literal['DELETE']]
    Description

    Creates a new delete query for the given model. Returns the same QueryBuilder that is now flagged as a DELETE query.

  • Name
    where
    Return type
    Description

    Adds a where condition to the query. The conditions are combined with AND. If you need to use OR, you can use the and_ and or_ constructors.

  • Name
    order_by
    Return type
    Description

    Adds an order by clause to the query. The field must be a column.

  • Name
    join
    Return type
    Description

    Adds a join clause to the query. The on parameter should be a comparison between two columns.

  • Name
    set
    Return type
    Description

    Sets a column to a specific value in an update query.

  • Name
    limit
    Return type
    Description

    Limit the number of rows returned by the query. Useful in pagination or in only selecting a subset of the results.

  • Name
    offset
    Return type
    Description

    Offset the number of rows returned by the query.

  • Name
    group_by
    Return type
    Description

    Groups the results of the query by the given fields. This allows you to use aggregation functions in your selection queries. See func for the supported aggregation functions.

  • Name
    having
    Return type
    Description

    Require the result of an aggregation query like func.sum(MyTable.column) to be within a certain range. This is similar to the where clause but for aggregation results.

  • Name
    text
    Return type
    Description

    Override the ORM builder and use a raw SQL query instead.

  • Name
    build
    Return type
    tuple[str, list[Any]]
    Description

    Builds the query and returns the query string and the variables that should be sent over the wire.

CLASSiceaxe.functions.FunctionMetadata

FunctionMetadata

Class Constructor

  • Name
    literal
    Type
    QueryLiteral
    Description
  • Name
    original_field
    Type
    DBFieldClassDefinition
    Description
  • Name
    local_name
    Type
    str | None
    Description

    Default: None

Class Methods

  • Name
    to_query
    Return type
    Description

::: iceaxe.functions.func

Conditions

If you want to add conditions to your query, you can use the where method. If you pass multiple conditions to this, they'll be chained together as an AND filter. To combine OR and AND predicates together, you can use and_ and or_.

FUNCTIONiceaxe.queries.and_

and_

Parameters

  • Name
    conditions
    Type
    bool
    Description

    Default: ()

FUNCTIONiceaxe.queries.or_

or_

Parameters

  • Name
    conditions
    Type
    bool
    Description

    Default: ()

Shortcuts

We offer convenience functions for the most common SQL operations. This avoids the need to instantiate a QueryBuilder directly every time you want a new SQL query and typically results in cleaner code.

FUNCTIONiceaxe.queries.select

select

Shortcut to create a SELECT query with a new QueryBuilder.

Parameters

  • Name
    fields
    Type
    T | Type[T] | tuple[T | Type[T], *Ts]
    Description
FUNCTIONiceaxe.queries.update

update

Shortcut to create an UPDATE query with a new QueryBuilder.

Parameters

  • Name
    model
    Type
    Type[TableBase]
    Description
FUNCTIONiceaxe.queries.delete

delete

Shortcut to create a DELETE query with a new QueryBuilder.

Parameters

  • Name
    model
    Type
    Type[TableBase]
    Description

--

Enums

::: iceaxe.queries.JoinType

::: iceaxe.queries.OrderDirection