blaze v0.1.1 Blaze.Query View Source
Simplifies the process of constructing a Firestore query, similar to how Ecto.Query simplifies queries to its supported databases.
The simplest way to get started is to import Blaze.Query
:
import Blaze.Query
query = from("bookCollection", allDescendants: false)
|> limit(1)
|> where(author: "Donald Knuth")
Blaze.API.run_query(conn, parent_path, query)
Link to this section Summary
Functions
Create a single filter for one field. This could result in either a
UnaryFilter
or a FieldFilter
being generated, although everything gets
wrapped in a Filter
model anyway for some reason.
Creates one or more filters from a keyword list or map of conditions.
Conditions may either be field comparisons filters or unary field filters. See
the module documentation sections for Comparison Operators
and Unary Filters
for more information.
Convert a direction atom to its string representation.
Creates a Filter
model with the fieldFilter
attribute set.
Convert a field operator atom to its string representation. Uses the value as
context to determine both validity and, in the case of :contains
, which
specific string representation is needed.
Constructs a new query object that executes against the given collection.
Updates an existing query to execute against the given collection. If a query isn't given, a new query object is created for the given collection and options list.
Updates ane existing query to execute against the given collection with the given set of options. Options can be
Adds one or more order by
clauses to the query. If a list is provided, the
elements may be either field references or a tuple with a field reference and
an atom representing directionality: :asc
or :desc
. If a map is provided,
every key must be a field reference and every value must be a direction atom.
Creates a filter for the query. If a where
clause has already been added to
the query, the filter is either "upgraded" to a composite filter from a field
or unary filter, or the new conditions are simply added to the existing
composite filter.
Link to this section Types
Link to this section Functions
create_filter(arg)
View Sourcecreate_filter({binary(), term()}) :: GoogleApi.Firestore.V1.Model.Filter.t()
Create a single filter for one field. This could result in either a
UnaryFilter
or a FieldFilter
being generated, although everything gets
wrapped in a Filter
model anyway for some reason.
create_filters(conditions)
View Sourcecreate_filters(Keyword.t() | Map.t()) :: GoogleApi.Firestore.V1.Model.Filter.t()
Creates one or more filters from a keyword list or map of conditions.
Conditions may either be field comparisons filters or unary field filters. See
the module documentation sections for Comparison Operators
and Unary Filters
for more information.
create_order(field)
View Sourcecreate_order(binary() | {binary(), atom()}) :: GoogleApi.Firestore.V1.Model.Order.t()
create_ordering(orders)
View Sourcecreate_ordering([binary() | {binary(), atom()}] | Map.t()) :: [ GoogleApi.Firestore.V1.Model.Order.t() ]
Convert a direction atom to its string representation.
field_filter(operator, field, value)
View Sourcefield_filter(binary(), binary(), term()) :: GoogleApi.Firestore.V1.Model.Filter.t()
Creates a Filter
model with the fieldFilter
attribute set.
Convert a field operator atom to its string representation. Uses the value as
context to determine both validity and, in the case of :contains
, which
specific string representation is needed.
Constructs a new query object that executes against the given collection.
Updates an existing query to execute against the given collection. If a query isn't given, a new query object is created for the given collection and options list.
Updates ane existing query to execute against the given collection with the given set of options. Options can be:
allDescendants
-boolean
- When false, only selects collections that are immediate descendants of the parent path specified in the API call.
Adds one or more order by
clauses to the query. If a list is provided, the
elements may be either field references or a tuple with a field reference and
an atom representing directionality: :asc
or :desc
. If a map is provided,
every key must be a field reference and every value must be a direction atom.
Creates a filter for the query. If a where
clause has already been added to
the query, the filter is either "upgraded" to a composite filter from a field
or unary filter, or the new conditions are simply added to the existing
composite filter.
Unary Filters
It's possible to perform one of two unary filters on a field:
- Checking for "NaN"
- Checking for "Null"
To perform either of these built-in unary filters, you can do the following:
# Check for "NaN"
where(query, grade: :nan)
# Check for "Null"
where(query, grade: nil)
Any time a key for a given field is either :nan
or nil
, a unary filter
is created. If additional fields and values are given, any unary filters will
be added to a composite filter along with the remainder of the fields.
Comparison Operators
By default, if the value for a field is a list then the filter uses the in
operator (e.g. day_of_week in [1, 2, 3]
). For all other values the filter
uses =
as the operator (e.g. day_of_week = 5
). You can customize the
operator by passing a tuple for the value in the form of {op, val}
. For
example:
# Filter for `grade >= 80`
where(query, grade: {:gte, 80})
# Filter for `regions contains "us-west"`
where(query, regions: {:contains, "us-west"})
The full list of possible operators:
:eq
- Field equals a value:lt
- Field less than a value:lte
- Field less than or equal a value:gt
- Field is greater than a value:gte
- Field is greater than or equal to a value:contains
- Field contains at least one of a set of values:in
- Field matches at least one of a set of values
For the :contains
operator, this only works when the field being filtered
is an array type. When the value is a list, the :contains
operator is
equivalent to "the field has at least one element that matches an element in
the given value list." When the value is anything else, the :contains
operator is equivalent to "the field has at least one element that matches the
given value."
For the :in
operator, this only works when the field being filtered is
not an array or map type. The value list passed in must be an array of
values that match the type of the field. E.g. if the field being filtered is
an integer then the list of possible values must be a list of integers.
Caveats
Warning: Firestore only supports and
operators for composite filters,
so calling where
multiple times will create multiple and
conditions. For
example:
query
|> where(author: "Donald Knuth")
|> where(author: "William Gibson")
The above won't work because Firestore can only interpret that as "author is
Donald Knuth AND William Gibson". Calling the where
function multiple
times is better suited for composing incremental, compounding filters rather
than expanding existing filters.