@spec allowed_filter_modifiers() :: list()

Returns the filter modifiers supported byt the Query syntax

@spec by(tuple(), list()) :: tuple()

Adds a filter condition to the query.

This will work for Entries requiring a call to content_type before:

example

Example

import Contentful.Query
alias Contentful.Delivery.Entries

{:ok, entries, total: 1}
= Entries
  |> content_type("dogs")
  |> by(name: "Hasso", breed: "dalmatian")
  |> fetch_all

This will also allow for more complex queries using modifiers:

example-1

Example

import Contentful.Query
alias Contentful.Delivery.Entries

{:ok, entries, total: 100}
= Entries
  |> content_type("dogs")
  |> by(name: [ne: "Hasso"], breed: "dalmatian")
  |> fetch_all

Allowed modifiers are [:in, :nin, :ne, :lte, :gte, :lt, :gt, :match, :exist]. See the official docs for adding search parameters this way.

Working with Contentful.Delivery.Assets requires no content_type call:

example-2

Example

import Contentful.Query
alias Contentful.Delivery.Assets

{:ok, assets, total: 1} = Assets |> by(id: "foobar") |> fetch_all

Calling by/2 allows for adding multiple conditions to the query:

example-3

Example

import Contentful.Query
alias Contentful.Delivery.Assets

{:ok, assets, total: 200}
= Assets
  |> by(tags: [nin: "maps"])
  |> fetch_all

@spec 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

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

@spec 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

Examples

alias Contentful.Delivery.Entries
{:ok, entries, total: _total_count_of_entries} =
  Entries |> content_type("foobar") |> limit(1) |> fetch_all

@spec 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

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")

@spec 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

Example:

alias Contentful.Delivery.Entries
Entries |> include(2) |> fetch_all

# translates in the background to

"<api_url>/entries?include=2"

@spec 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

Examples

alias Contentful.Delivery.Assets
Assets |> limit(2) |> fetch_all

# translates in the background to

"<api_url>/assets?limit=2"

@spec search_full_text(tuple(), term()) :: tuple()

allows for full text search over all entries fields. The original nomenclature fromthe API docs is query.

This has been renamed for clarity here.

example

Example

import Contentful.Query
{Entries, [query: "Nyancat"]} = Entries |> search_full_text("Nyancat")

# or, with full `fetch_all`
{:ok, nyan_cats, total: 616} =
  Entries
  |> search_full_text("Nyancat")
  |> fetch_all

@spec 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

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"

@spec 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

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 is no collection endpoint