In Groq, there are 2 ways to use conditional logic: inline in a projection, or using the select function.
Conditions in a projection
In groq-builder, the project method allows inline conditional statements with the help of q.conditional$(...) or q.conditionalByType(...) using the following syntax:
type ContentResults = InferResultType<typeof contentQuery>;
// Same as:
type ContentResults = Array<
| { slug: string }
| { slug: string, title: string, subtitle: string }
>;
Notice that the conditions are wrapped in q.conditional$() and then spread into the projection. This is necessary for type-safety and runtime validation.
The $ in the method q.conditional$ indicates that this method is not completely type-safe; the condition statements (eg. _type == 'movie') are not strongly-typed (this may be improved in a future version).
However, the most common use-case is to base conditional logic off the document's _type. For this, we have the q.conditionalByType helper:
Strongly-typed conditions via q.conditionalByType(...)
The most common use-case for conditional logic is to check the _type field.
The q.conditionalByType(...) method makes this easier, by ensuring all conditional logic is strongly-typed, and it enables auto-complete. For example:
What
Adds methods to create "conditional" projections.
Docs: (copied from CONDITIONALS.md)
Conditionals
In Groq, there are 2 ways to use conditional logic: inline in a projection, or using the
select
function.Conditions in a projection
In
groq-builder
, theproject
method allows inline conditional statements with the help ofq.conditional$(...)
orq.conditionalByType(...)
using the following syntax:This outputs the following groq query:
And the result type is inferred as:
Notice that the conditions are wrapped in
q.conditional$()
and then spread into the projection. This is necessary for type-safety and runtime validation.The
$
in the methodq.conditional$
indicates that this method is not completely type-safe; the condition statements (eg._type == 'movie'
) are not strongly-typed (this may be improved in a future version).However, the most common use-case is to base conditional logic off the document's
_type
. For this, we have theq.conditionalByType
helper:Strongly-typed conditions via
q.conditionalByType(...)
The most common use-case for conditional logic is to check the
_type
field. Theq.conditionalByType(...)
method makes this easier, by ensuring all conditional logic is strongly-typed, and it enables auto-complete. For example:The resulting query is identical to the above example with
q.conditional$
.The result type here is inferred as:
Notice that this type is stronger than the example with
q.conditional$
, because we've detected that the conditions are "exhaustive".The
select
methodAdds support for the
select$
method:The
$
sign is to indicate that there's some "loosely typed" code in here -- the conditions are unchecked.This will output the following query:
And will have the following result type:
The
selectByType
methodAdds a
selectByType
helper, which facilitates type-based logic. This is completely strongly-typed: