Contentful SDK v0.3.2 Contentful.Query View Source
This module provides the chainable query syntax for building queries against the APIs of Contentful.
The chains will then be serialized to a URL and send to the API. A basic query looks like this:
Entity
|> skip(3)
|> limit(2)
|> fetch_all
wherein Entity
is one of the modules that exhibit Contentful.Queryable
behaviour, such as
Contentful.Delivery.Entries
, Contentful.Delivery.Assets
and Contentful.Delivery.ContentTypes
.
As an example, querying all entries of a given Contentful.Space
(represented by its space_id
) can
be done as follows:
Contentful.Delivery.Entries
|> Contentful.Query.fetch_all(space_id)
Link to this section Summary
Functions
adds a content_type
parameter for filtering sets of Contentful.Entry
by a Contentful.ContentType
, effectively allowing for scoping by content type.
will resolve a query chain by eagerly calling the API and resolving the response immediately
will resolve a query chain by eagerly calling the API asking for one entity
adds the include
parameter to a query.
adds the limit
parameter to a call, limiting the amount of entities returned.
The caller will still retreive the total amount of entities, if successful.
adds the skip
parameter to API calls, allowing to skip over a number of entities, effectively
allowing the implementation of pagination if desired.
will resolve a query chain by constructing a Stream.resource
around a possible API response
allowing for lazy evaluation of queries. Cann be helpful with translating collection calls of
unknown size.
Link to this section Functions
Specs
content_type( {Contentful.Delivery.Entries, list()}, String.t() | Contentful.ContentType.t() ) :: {Contentful.Delivery.Entries, list()}
adds a content_type
parameter for filtering sets of Contentful.Entry
by a Contentful.ContentType
, effectively allowing for scoping by content type.
content_type
will only work with Contentful.Delivery.Entries
at the moment.
Examples
alias Contentful.Delivery.Entries
Entries |> content_type("foobar") |> fetch_all
# translates in the background to
"<api_url>/entries?content_type=foobar"
# also works with passing `Contentful.ContentType`:
my_content_type = %Contentful.ContentType{sys: %Contentful.SysData{id: "foobar"}}
Entries |> content_type(my_content_type) |> fetch_all
fetch_all(queryable, space \\ Delivery.config(:space_id), env \\ Delivery.config(:environment), api_key \\ Delivery.config(:access_token))
View SourceSpecs
fetch_all({module(), list()}, String.t(), String.t(), String.t()) :: {:ok, [struct()], [{:total, non_neg_integer()}]} | {:error, :rate_limit_exceeded, [{:wait_for, integer()}]} | {:error, atom(), [{:original_message, String.t()}]}
will resolve a query chain by eagerly calling the API and resolving the response immediately
Examples
alias Contentful.Delivery.Entries
{:ok, entries, total: _total_count_of_entries} =
Entries |> content_type("foobar") |> limit(1) |> fetch_all
fetch_one(queryable, id \\ nil, space \\ Delivery.config(:space_id), env \\ Delivery.config(:environment), api_key \\ Delivery.config(:access_token))
View SourceSpecs
fetch_one(module(), String.t() | nil, String.t(), String.t(), String.t()) :: {:ok, struct()} | {:error, :rate_limit_exceeded, [{:wait_for, integer()}]} | {:error, atom(), [{:original_message, String.t()}]}
will resolve a query chain by eagerly calling the API asking for one entity
Examples
import Contentful.Query
alias Contentful.Delivery.{Spaces, Entries}
# Note: Spaces is the only Queryable that can be fetched without an id
Spaces |> fetch_one
# all others would throw an error, so an id has to be passed:
Entries |> fetch_one("my_entry_id")
Specs
adds the include
parameter to a query.
This allows for fetching associated items up to a collection of Contentful.Entry
.
The include
call will only work with Contentful.Delivery.Entries
, as it is meaningless to
other entities.
Example:
alias Contentful.Delivery.Entries
Entries |> include(2) |> fetch_all
# translates in the background to
"<api_url>/entries?include=2"
Specs
adds the limit
parameter to a call, limiting the amount of entities returned.
The caller will still retreive the total amount of entities, if successful.
The limit defaults to 1000
, the maximum limit
allowed for API calls.
Examples
alias Contentful.Delivery.Assets
Assets |> limit(2) |> fetch_all
# translates in the background to
"<api_url>/assets?limit=2"
Specs
skip({module(), list()}, non_neg_integer()) :: {module(), list()}
adds the skip
parameter to API calls, allowing to skip over a number of entities, effectively
allowing the implementation of pagination if desired.
Examples
alias Contentful.Delivery.Assets
Assets |> skip(10) |> fetch_all
# translates in the background to a call to the API
"<api_url>/assets?skip=10"
stream(queryable, space \\ Delivery.config(:space_id), env \\ Delivery.config(:environment), api_key \\ Delivery.config(:access_token))
View SourceSpecs
stream(tuple(), String.t(), String.t(), String.t()) :: Enumerable.t()
will resolve a query chain by constructing a Stream.resource
around a possible API response
allowing for lazy evaluation of queries. Cann be helpful with translating collection calls of
unknown size.
Be careful when using this, as one can run into API rate limits quickly for very large sets.
Examples
import Contentful.Query
alias Contentful.Delivery.{Assets, Spaces}
# translates into two api calls in the background
Assets |> stream |> Enum.take(2000)
# you can use limit() to set the page size, in the example, stream would call the API
# 10 times total.
Assets |> limit(100) |> Enum.take(1000)
# will not work with Spaces, though, as they