HORIZON HASKELLDocslts/ghc-10.0.x8c2f8e82026-10-19Search names, modules, packages, or :: a typeCtrl K

GHC 10.0.0.20260917 · lts/ghc-10.0.x · 8c2f8e8 · 2026-10-19

Modulebeam-core-0.11.1.0Haskell2010

Database.Beam.Query

  • 31 types
  • 15 classes
  • 226 values

Query type

0 declarations

module Database.Beam.Query.Types

Query expression contexts

A context is a type-level value that signifies where an expression can be used. For example, QExpr corresponds to QGenExprs that result in values. In reality, QExpr is really QGenExpr parameterized over the QValueContext. Similarly, QAgg represents expressions that contain aggregates, but it is just QGenExpr parameterized over QAggregateContext

datadata QGroupingContext
#
Instances4QGroupable, ContextName
  • Beamable tbl => QGroupable (tbl (Nullable (QExpr be s))) (tbl (Nullable (QGroupExpr be s)))Defined in beam-core-0.11.1.0 · Database.Beam.Query.Aggregate

    group_ for any Beamable type. Adds every field in the type to the grouping key. This is the equivalent of including the grouping expression of each field in the type as part of the aggregate projection

  • Beamable tbl => QGroupable (tbl (QExpr be s)) (tbl (QGroupExpr be s))Defined in beam-core-0.11.1.0 · Database.Beam.Query.Aggregate

    group_ for any Beamable type. Adds every field in the type to the grouping key. This is the equivalent of including the grouping expression of each field in the type as part of the aggregate projection

  • QGroupable (QExpr be s a) (QGroupExpr be s a)Defined in beam-core-0.11.1.0 · Database.Beam.Query.Aggregate

    group_ for simple value expressions.

  • type ContextName QGroupingContext = "an aggregate grouping"Defined in beam-core-0.11.1.0 · Database.Beam.Query.Internal
datadata QValueContext
#
Instances10SqlUpdatable, QGroupable, SqlJustable, ContextName, …
datadata QField s ty
#
Instances9ProjectibleWithPredicate, SqlUpdatable, Eq, Ord, Show, …
valueas_ :: QGenExpr ctxt be s a -> QGenExpr ctxt be s a
#

Convenience function that allows you to use type applications to specify the result of a QGenExpr.

Useful to disambiguate the types of QGenExprs without having to provide a complete type signature. As an example, the countAll_ aggregate can return a result of any Integral type. Without further constraints, the type is ambiguous. You can use as_ to disambiguate the return type.

For example, this is ambiguous

aggregate_ (\_ -> countAll_) ..

But this is not

aggregate_ (\_ -> as_ @Int32 countAll_) ..
valuedefault_ :: BeamSqlBackend be => QGenExpr ctxt be s a
#

SQL DEFAULT support.

Note that default_ has restrictions not currently represented in the Haskell type system. For example, using default_ as the argument to a function like coalesce_ will result in a runtime error, just like the SQL code COALESCE (NULL, DEFAULT) would raise a runtime error.

valueguard_' :: BeamSqlBackend be => QExpr be s SqlBool -> Q be db s ()
#

Only allow results for which the QExpr yields TRUE.

This function operates over SqlBool, which are like haskell Bools, except for the special UNKNOWN value that occurs when comparisons include NULL. For a version that operates over known non-NULL booleans, see guard_.

valueleftJoin_
  1. :: (BeamSqlBackend be, Projectible be r, ThreadRewritable (QNested s) r, Retaggable (QExpr be s) (WithRewrittenThread (QNested s) s r))
  2. => Q be db (QNested s) r
  3. -> WithRewrittenThread (QNested s) s r -> QExpr be s Bool
  4. -> Q be db s (Retag Nullable (WithRewrittenThread (QNested s) s r))
#

Introduce a table using a left join. The ON clause is required here.Because this is not an inner join, the resulting table is made nullable. This means that each field that would normally have type 'QExpr x' will now have type 'QExpr (Maybe x)'.

The ON condition given must return Bool. For a version that accepts an ON condition returning SqlBool, see leftJoin_'.

valueouterJoin_
  1. :: (BeamSqlBackend be, BeamSqlBackendSupportsOuterJoin be, Projectible be a, Projectible be b, ThreadRewritable (QNested s) a, ThreadRewritable (QNested s) b, Retaggable (QExpr be s) (WithRewrittenThread (QNested s) s a), Retaggable (QExpr be s) (WithRewrittenThread (QNested s) s b))
  2. => Q be db (QNested s) a
  3. -> Q be db (QNested s) b
  4. -> (WithRewrittenThread (QNested s) s a, WithRewrittenThread (QNested s) s b) -> QExpr be s Bool
  5. -> Q be db s (Retag Nullable (WithRewrittenThread (QNested s) s a), Retag Nullable (WithRewrittenThread (QNested s) s b))
#

Outer join. every row of each table, returning NULL for any row of either table for which the join condition finds no related rows.

This expects a join expression returning Bool, for a version that accepts a SqlBool (a possibly UNKNOWN boolean, that maps more closely to the SQL standard), see outerJoin_'

valueouterJoin_'
  1. :: (BeamSqlBackend be, BeamSqlBackendSupportsOuterJoin be, Projectible be a, Projectible be b, ThreadRewritable (QNested s) a, ThreadRewritable (QNested s) b, Retaggable (QExpr be s) (WithRewrittenThread (QNested s) s a), Retaggable (QExpr be s) (WithRewrittenThread (QNested s) s b))
  2. => Q be db (QNested s) a
  3. -> Q be db (QNested s) b
  4. -> (WithRewrittenThread (QNested s) s a, WithRewrittenThread (QNested s) s b) -> QExpr be s SqlBool
  5. -> Q be db s (Retag Nullable (WithRewrittenThread (QNested s) s a), Retag Nullable (WithRewrittenThread (QNested s) s b))
#

Like outerJoin_, but accepting SqlBool. Pairs of rows for which the join condition is unknown are considered to be unrelated, by SQL compliant databases at least.

valuewithWindow_
  1. :: (ProjectibleWithPredicate WindowFrameContext be (WithExprContext (BeamSqlBackendWindowFrameSyntax' be)) window, Projectible be r, Projectible be a, ContextRewritable a, ThreadRewritable (QNested s) (WithRewrittenContext a QValueContext))
  2. => (r -> window)

    Window builder function

  3. -> (r -> window -> a)

    Projection builder function. Has access to the windows generated above

  4. -> Q be db (QNested s) r

    Query to window over

  5. -> Q be db s (WithRewrittenThread (QNested s) s (WithRewrittenContext a QValueContext))
#

Compute a query over windows.

The first function builds window frames using the frame_, partitionBy_, etc functions. The return type can be a single frame, tuples of frame, or any arbitrarily nested tuple of the above. Instances up to 8-tuples are provided.

The second function builds the resulting projection using the result of the subquery as well as the window frames built in the first function. In this function, window expressions can be included in the output using the over_ function.

familytype family HaskellLiteralForQExpr x
#
Instances3HaskellLiteralForQExpr
newtypenewtype QIfElse context be s a
#
classclass BeamSqlBackend be => SqlDeconstructMaybe be a nonNullA s | a s -> be, a -> nonNullA, a -> s, nonNullA -> s where
#

Type class for anything which can be checked for null-ness. This includes 'QExpr (Maybe a)' as well as Tables or PrimaryKeys over 'Nullable QExpr'.

Methods

  • isJust_ :: a -> QGenExpr ctxt be s Bool

    Returns a QExpr that evaluates to true when the first argument is not null

  • isNothing_ :: a -> QGenExpr ctxt be s Bool

    Returns a QExpr that evaluates to true when the first argument is null

  • maybe_ :: QGenExpr ctxt be s y -> (nonNullA -> QGenExpr ctxt be s y) -> a -> QGenExpr ctxt be s y

    Given an object (third argument) which may or may not be null, return the default value if null (first argument), or transform the value that could be null to yield the result of the expression (second argument)

Instances2SqlDeconstructMaybe
classclass SqlJustable a b | b -> a where
#

Type class for things that can be nullable. This includes 'QExpr (Maybe a)', 'tbl (Nullable QExpr)', and 'PrimaryKey tbl (Nullable QExpr)'

Methods

  • just_ :: a -> b

    Given something of type 'QExpr a', 'tbl QExpr', or 'PrimaryKey tbl QExpr', turn it into a 'QExpr (Maybe a)', 'tbl (Nullable QExpr)', or 'PrimaryKey t (Nullable QExpr)' respectively that contains the same values.

  • nothing_ :: b

    Return either a 'QExpr (Maybe x)' representing Nothing or a nullable Table or PrimaryKey filled with Nothing.

Instances5SqlJustable
classclass SqlOrderable be a | a -> be where
#
Instances10SqlOrderable, …
classclass SqlValable a where
#

Methods

Instances3SqlValable
valuemanyToManyPassthrough_
  1. :: (Database be db, Table joinThrough, Table left, Table right, BeamSqlBackend be, SqlEq (QExpr be s) (PrimaryKey left (QExpr be s)), SqlEq (QExpr be s) (PrimaryKey right (QExpr be s)))
  2. => DatabaseEntity be db (TableEntity joinThrough)
  3. -> joinThrough (QExpr be s) -> PrimaryKey left (QExpr be s)
  4. -> joinThrough (QExpr be s) -> PrimaryKey right (QExpr be s)
  5. -> Q be db s (left (QExpr be s))
  6. -> Q be db s (right (QExpr be s))
  7. -> Q be db s (joinThrough (QExpr be s), left (QExpr be s), right (QExpr be s))
#

Used to define many-to-many relationships with additional data. Takes the join table and two key extraction functions from that table to the related tables. Also takes two Qs representing the table sources to relate.

See the manual for more information.

valuemanyToMany_
  1. :: (Database be db, Table joinThrough, Table left, Table right, BeamSqlBackend be, SqlEq (QExpr be s) (PrimaryKey left (QExpr be s)), SqlEq (QExpr be s) (PrimaryKey right (QExpr be s)))
  2. => DatabaseEntity be db (TableEntity joinThrough)
  3. -> joinThrough (QExpr be s) -> PrimaryKey left (QExpr be s)
  4. -> joinThrough (QExpr be s) -> PrimaryKey right (QExpr be s)
  5. -> Q be db s (left (QExpr be s))
  6. -> Q be db s (right (QExpr be s))
  7. -> Q be db s (left (QExpr be s), right (QExpr be s))
#

Used to define many-to-many relationships without any additional data. Takes the join table and two key extraction functions from that table to the related tables. Also takes two Qs representing the table sources to relate.

See the manual for more information.

valueoneToManyOptional_
  1. :: (BeamSqlBackend be, Database be db, Table tbl, Table rel, HasTableEqualityNullable be (PrimaryKey tbl))
  2. => DatabaseEntity be db (TableEntity rel)

    Table to fetch

  3. -> (rel (QExpr be s) -> PrimaryKey tbl (Nullable (QExpr be s)))

    Foreign key

  4. -> tbl (QExpr be s)
  5. -> Q be db s (rel (Nullable (QExpr be s)))
#

Used to define one-to-many (or one-to-one) relationships with a nullable foreign key. Takes the table to fetch, a way to extract the foreign key from that table, and the table to relate to.

valueoneToMaybe_
  1. :: (BeamSqlBackend be, Database be db, Table tbl, Table rel, HasTableEqualityNullable be (PrimaryKey tbl))
  2. => DatabaseEntity be db (TableEntity rel)

    Table to fetch

  3. -> (rel (QExpr be s) -> PrimaryKey tbl (Nullable (QExpr be s)))

    Foreign key

  4. -> tbl (QExpr be s)
  5. -> Q be db s (rel (Nullable (QExpr be s)))
#

Used to define one-to-many (or one-to-one) relationships with a nullable foreign key. Takes the table to fetch, a way to extract the foreign key from that table, and the table to relate to.

typetype ManyToManyThrough be (db :: (Type -> Type) -> Type) (through :: (Type -> Type) -> Type) (left :: (Type -> Type) -> Type) (right :: (Type -> Type) -> Type) = forall s. (BeamSqlBackend be, SqlEq (QExpr be s) (PrimaryKey left (QExpr be s)), SqlEq (QExpr be s) (PrimaryKey right (QExpr be s))) => Q be db s (left (QExpr be s)) -> Q be db s (right (QExpr be s)) -> Q be db s (through (QExpr be s), left (QExpr be s), right (QExpr be s))
#

Convenience type to declare many-to-many relationships with additional data. See the manual section on relationships for more information

datadata ReusableQ be (db :: (Type -> Type) -> Type) res where
#

Query results that have been introduced into a common table expression via selecting that can be used in future queries with reuse.

newtypenewtype With be (db :: (Type -> Type) -> Type) a
#

Monad in which SELECT statements can be made (via selecting) and bound to result names for re-use later. This has the advantage of only computing each result once. In SQL, this is translated to a common table expression.

Once introduced, results can be re-used in future queries with reuse.

With is also a member of MonadFix for backends that support recursive CTEs. In this case, you can use mdo or rec notation (with RecursiveDo enabled) to bind result values (again, using reuse) even before they're introduced.

See further documentation here.

Instances4Monad, Functor, MonadFix, Applicative
classclass HasSqlDate tgt
#

Type-class for types that contain a date component

Instances3HasSqlDate
classclass HasSqlTime tgt
#

Type-class for types that contain a time component

Instances3HasSqlTime

Operators

14 declarations
datadata SqlBool
#

Phantom type representing a SQL Tri-state boolean -- true, false, and unknown

This type has no values because it cannot be sent to or retrieved from the database directly. Use isTrue_, isFalse_, isNotTrue_, isNotFalse_, isUnknown_, isNotUnknown_, and unknownAs_ to retrieve the corresponding Bool value.

ANSI SQL Booleans

valuepossiblyNullBool_
  1. :: QGenExpr context be s SqlBool
  2. -> QGenExpr context be s (Maybe Bool)
#

Retrieve a SqlBool value as a potentially NULL Bool. This is useful if you want to get the value of a SQL boolean expression directly, without having to specify what to do on UNKNOWN. Note that both NULL and UNKNOWN will be returned as Nothing.

Unquantified comparison operators

classclass BeamSqlBackend be => HasSqlEqualityCheck be a where
#

Class for Haskell types that can be compared for equality in the given backend

Methods

Instances22HasSqlEqualityCheck, …
classclass HasSqlEqualityCheck be a => HasSqlQuantifiedEqualityCheck be a where
#

Class for Haskell types that can be compared for quantified equality in the given backend

Methods

Instances22HasSqlQuantifiedEqualityCheck, …
classclass SqlEq (expr :: Type -> Type) a | a -> expr where
#

Class for expression types or expression containers for which there is a notion of equality.

Instances are provided to check the equality of expressions of the same type as well as entire Beamable types parameterized over QGenExpr

Methods

  • (==.) :: a -> a -> expr Boolinfix 4

    Given two expressions, returns whether they are equal, using Haskell semantics (NULLs handled properly)

  • (/=.) :: a -> a -> expr Boolinfix 4

    Given two expressions, returns whether they are not equal, using Haskell semantics (NULLs handled properly)

  • (==?.) :: a -> a -> expr SqlBoolinfix 4

    Given two expressions, returns the SQL tri-state boolean when compared for equality

  • (/=?.) :: a -> a -> expr SqlBoolinfix 4

    Given two expressions, returns the SQL tri-state boolean when compared for inequality

Instances3SqlEq
classclass SqlOrd (expr :: Type -> Type) e | e -> expr where
#

Class for expression types or expression containers for which there is a notion of ordering.

Instances are provided to check the ordering of expressions of the same type. Since there is no universal notion of ordering for an arbitrary number of expressions, no instance is provided for Beamable types.

Methods

  • (<.) :: e -> e -> expr Boolinfix 4
  • (>.) :: e -> e -> expr Boolinfix 4
  • (<=.) :: e -> e -> expr Boolinfix 4
  • (>=.) :: e -> e -> expr Boolinfix 4
Instances1SqlOrd

Quantified Comparison Operators

classclass SqlEq expr a => SqlEqQuantified (expr :: Type -> Type) quantified a | a -> expr quantified where
#

Class for expression types for which there is a notion of quantified equality.

Methods

  • (==*.) :: a -> quantified -> expr SqlBoolinfix 4

    Quantified equality and inequality using SQL semantics (tri-state boolean)

  • (/=*.) :: a -> quantified -> expr SqlBoolinfix 4

    Quantified equality and inequality using SQL semantics (tri-state boolean)

Instances1SqlEqQuantified
classclass SqlOrd expr e => SqlOrdQuantified (expr :: Type -> Type) quantified e | e -> expr quantified where
#

Class for things which can be quantifiably compared.

Methods

  • (<*.) :: e -> quantified -> expr Boolinfix 4
  • (>*.) :: e -> quantified -> expr Boolinfix 4
  • (<=*.) :: e -> quantified -> expr Boolinfix 4
  • (>=*.) :: e -> quantified -> expr Boolinfix 4
Instances1SqlOrdQuantified
datadata QQuantified be s r
#

A data structure representing the set to quantify a comparison operator over.

Instances2SqlEqQuantified, SqlOrdQuantified
valueaggregate_
  1. :: (BeamSqlBackend be, Aggregable be a, Projectible be r, Projectible be a, ContextRewritable a, ThreadRewritable (QNested s) (WithRewrittenContext a QValueContext))
  2. => (r -> a)

    Aggregate projection

  3. -> Q be db (QNested s) r

    Query to aggregate over

  4. -> Q be db s (WithRewrittenThread (QNested s) s (WithRewrittenContext a QValueContext))
#

Compute an aggregate over a query.

The supplied aggregate projection should return an aggregate expression (an expression containing an aggregate function such as count_, sum_, countAll_, etc), a grouping key (specified with the group_ function), or a combination of tuples of the above.

Appropriate instances are provided up to 8-tuples.

Semantically, all grouping expressions in the projection will be added to a SQL GROUP BY clause and all aggregate expressions will be computed.

The return value will be the type of the aggregate projection, but transformed to be in the normal value context (i.e., everything will become QExprs).

For usage examples, see the manual.

valueallInGroupExplicitly_ :: IsSql92AggregationSetQuantifierSyntax s => Maybe s
#

Compute an aggregate over all values in a group. Corresponds to the AGG(ALL ..) syntax. Note that ALL is the default for most aggregations, so you don't normally explicitly specify ALL. However, if you need to, you can use this function. To be explicit about quantification in the beam query DSL, but not produce an explicit ALL, use allInGroup_. allInGroup_ has the same semantic meaning, but does not produce an explicit ALL.

classclass QGroupable expr grouped | expr -> grouped, grouped -> expr where
#

Type class for grouping keys. expr is the type of the grouping key after projection. grouped is the type of the grouping key in the aggregate expression (usually something that contains QGenExprs in the QGroupingContext).

Methods

Instances3QGroupable
  • Beamable tbl => QGroupable (tbl (Nullable (QExpr be s))) (tbl (Nullable (QGroupExpr be s)))Defined in beam-core-0.11.1.0 · Database.Beam.Query.Aggregate

    group_ for any Beamable type. Adds every field in the type to the grouping key. This is the equivalent of including the grouping expression of each field in the type as part of the aggregate projection

  • Beamable tbl => QGroupable (tbl (QExpr be s)) (tbl (QGroupExpr be s))Defined in beam-core-0.11.1.0 · Database.Beam.Query.Aggregate

    group_ for any Beamable type. Adds every field in the type to the grouping key. This is the equivalent of including the grouping expression of each field in the type as part of the aggregate projection

  • QGroupable (QExpr be s a) (QGroupExpr be s a)Defined in beam-core-0.11.1.0 · Database.Beam.Query.Aggregate

    group_ for simple value expressions.

module Database.Beam.Query.CustomSQL

module Database.Beam.Query.DataTypes

SQL Command construction and execution

0 declarations

SELECT

INSERT

UPDATE

valueupdate
  1. :: (BeamSqlBackend be, Beamable table)
  2. => DatabaseEntity be db (TableEntity table)

    The table to insert into

  3. -> (forall s. table (QField s) -> QAssignment be s)

    A sequence of assignments to make.

  4. -> (forall s. table (QExpr be s) -> QExpr be s Bool)

    Build a WHERE clause given a table containing expressions

  5. -> SqlUpdate be table
#

Build a SqlUpdate given a table, a list of assignments, and a way to build a WHERE clause.

Use update' for comparisons with SqlBool.

See the (<-.) operator for ways to build assignments. The argument to the second argument is a the table parameterized over QField, which represents the left hand side of assignments. Sometimes, you'd like to also get the current value of a particular column. You can use the current_ function to convert a QField to a QExpr.

valuesave
  1. :: (Table table, BeamSqlBackend be, SqlValableTable be (PrimaryKey table), SqlValableTable be table, HasTableEquality be (PrimaryKey table))
  2. => DatabaseEntity be db (TableEntity table)

    Table to update

  3. -> table Identity

    Value to set to

  4. -> SqlUpdate be table
#

Generate a SqlUpdate that will update the given table row with the given value.

The SQL UPDATE that is generated will set every non-primary key field for the row where each primary key field is exactly what is given.

Note: This is a pure SQL UPDATE command. This does not upsert or merge values.

Use save' for an internal SqlBool comparison.

valueupdate'
  1. :: (BeamSqlBackend be, Beamable table)
  2. => DatabaseEntity be db (TableEntity table)

    The table to insert into

  3. -> (forall s. table (QField s) -> QAssignment be s)

    A sequence of assignments to make.

  4. -> (forall s. table (QExpr be s) -> QExpr be s SqlBool)

    Build a WHERE clause given a table containing expressions

  5. -> SqlUpdate be table
#

Build a SqlUpdate given a table, a list of assignments, and a way to build a WHERE clause.

Uses a SqlBool comparison. Use update for comparisons with Bool.

See the (<-.) operator for ways to build assignments. The argument to the second argument is a the table parameterized over QField, which represents the left hand side of assignments. Sometimes, you'd like to also get the current value of a particular column. You can use the current_ function to convert a QField to a QExpr.

valuesave'
  1. :: (Table table, BeamSqlBackend be, SqlValableTable be (PrimaryKey table), SqlValableTable be table, HasTableEquality be (PrimaryKey table))
  2. => DatabaseEntity be db (TableEntity table)

    Table to update

  3. -> table Identity

    Value to set to

  4. -> SqlUpdate be table
#

Generate a SqlUpdate that will update the given table row with the given value. This is a variant using update' and a SqlBool comparison.

The SQL UPDATE that is generated will set every non-primary key field for the row where each primary key field is exactly what is given.

Note: This is a pure SQL UPDATE command. This does not upsert or merge values.

Use save for an internal Bool comparison.

valueupdateTableRow
  1. :: (BeamSqlBackend be, Table table, HasTableEquality be (PrimaryKey table), SqlValableTable be (PrimaryKey table))
  2. => DatabaseEntity be db (TableEntity table)

    The table to update

  3. -> table Identity

    The row to update

  4. -> table (QFieldAssignment be table)

    Updates to be made (use set to construct an empty field)

  5. -> SqlUpdate be table
#

Convenience form of updateTable that generates a WHERE clause that matches only the already existing entity.

Use updateTableRow' for an internal SqlBool comparison.

valueupdateTableRow'
  1. :: (BeamSqlBackend be, Table table, HasTableEquality be (PrimaryKey table), SqlValableTable be (PrimaryKey table))
  2. => DatabaseEntity be db (TableEntity table)

    The table to update

  3. -> table Identity

    The row to update

  4. -> table (QFieldAssignment be table)

    Updates to be made (use set to construct an empty field)

  5. -> SqlUpdate be table
#

Convenience form of updateTable' that generates a WHERE clause that matches only the already existing entity.

Uses update' with a SqlBool comparison. Use updateTableRow for an internal Bool comparison.

DELETE