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 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.

Link to this function

create_ordering(orders)

View Source
create_ordering([binary() | {binary(), atom()}] | Map.t()) :: [
  GoogleApi.Firestore.V1.Model.Order.t()
]
Link to this function

direction(atom)

View Source
direction(atom()) :: binary()

Convert a direction atom to its string representation.

Link to this function

field_filter(operator, field, value)

View Source

Creates a Filter model with the fieldFilter attribute set.

Link to this function

field_op(atom, list)

View Source
field_op(atom(), term()) :: binary()

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.

Link to this function

from(collection)

View Source
from(binary()) :: t()

Constructs a new query object that executes against the given collection.

Link to this function

from(query, collection)

View Source
from(t() | binary(), binary() | Keyword.t()) :: t()

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.

Link to this function

from(query, collection, options)

View Source
from(t(), binary(), Keyword.t()) :: t()

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.
Link to this function

limit(query \\ %StructuredQuery{}, num)

View Source
limit(t(), integer()) :: t()
Link to this function

offset(query \\ %StructuredQuery{}, num)

View Source
offset(t(), integer()) :: t()
Link to this function

order(query \\ %StructuredQuery{}, orders)

View Source
order(t(), [binary() | {binary(), atom()}] | Map.t()) :: t()

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.

Link to this function

where(query \\ %StructuredQuery{}, conditions)

View Source
where(t(), Keyword.t() | Map.t()) :: t()

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.