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

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

Link to this function

content_type(queryable, c_type)

View Source

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

fetch_all(queryable, space \\ Delivery.config(:space_id), env \\ Delivery.config(:environment), api_key \\ Delivery.config(:access_token))

View Source

Specs

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

fetch_one(queryable, id \\ nil, space \\ Delivery.config(:space_id), env \\ Delivery.config(:environment), api_key \\ Delivery.config(:access_token))

View Source

Specs

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

include(queryable, number \\ 1)

View Source

Specs

include({Contentful.Delivery.Entries, list()}, integer()) ::
  {Contentful.Delivery.Entries, list()}

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

limit(queryable, number \\ 1000)

View Source

Specs

limit({module(), list()}, integer()) :: {module(), list()}

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

stream(queryable, space \\ Delivery.config(:space_id), env \\ Delivery.config(:environment), api_key \\ Delivery.config(:access_token))

View Source

Specs

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