View Source Query Arguments
Our GraphQL API would be pretty boring (and useless) if clients couldn't retrieve filtered data.
Let's assume that our API needs to add the ability to look-up users by their ID and get the posts that they've authored. Here's what a basic query to do that might look like:
{
user(id: "1") {
name
posts {
id
title
}
}
}
The query includes a field argument, id
, contained within the
parentheses after the user
field name. To make this all work, we need to modify
our schema a bit.
Defining Arguments
First, let's create a :user
type and define its relationship to
:post
while we're at it. We'll create a new module for the
account-related types and put it there; in
blog_web/schema/account_types.ex
:
defmodule BlogWeb.Schema.AccountTypes do
use Absinthe.Schema.Notation
@desc "A user of the blog"
object :user do
field :id, :id
field :name, :string
field :email, :string
field :posts, list_of(:post)
end
end
The :posts
field points to a list of :post
results. (This matches
up with what we have on the Ecto side, where Blog.Accounts.User
defines a has_many
association with Blog.Content.Post
.)
We've already defined the :post
type, but let's go ahead and add an
:author
field that points back to our :user
type. In
blog_web/schema/content_types.ex
:
object :post do
# post fields we defined earlier...
field :author, :user
end
Now let's add the :user
field to our query root object in our
schema, defining a mandatory :id
argument and using the
Resolvers.Accounts.find_user/3
resolver function. We also need to
make sure we import the types from BlogWeb.Schema.AccountTypes
so
that :user
is available.
In blog_web/schema.ex
:
defmodule BlogWeb.Schema do
use Absinthe.Schema
import_types Absinthe.Type.Custom
# Add this `import_types`:
import_types BlogWeb.Schema.AccountTypes
import_types BlogWeb.Schema.ContentTypes
alias BlogWeb.Resolvers
query do
@desc "Get all posts"
field :posts, list_of(:post) do
resolve &Resolvers.Content.list_posts/3
end
# Add this field:
@desc "Get a user of the blog"
field :user, :user do
arg :id, non_null(:id)
resolve &Resolvers.Accounts.find_user/3
end
end
end
Now let's use the argument in our resolver. In blog_web/resolvers/accounts.ex
:
defmodule BlogWeb.Resolvers.Accounts do
def find_user(_parent, %{id: id}, _resolution) do
case Blog.Accounts.find_user(id) do
nil ->
{:error, "User ID #{id} not found"}
user ->
{:ok, user}
end
end
end
Our schema marks the :id
argument as non_null
, so we can be
certain we will receive it. If :id
is left out of the query,
Absinthe will return an informative error to the user, and the resolve
function will not be called.
If you have experience writing Phoenix controller actions, you might wonder why we can match incoming arguments with atoms instead of having to use strings.
The answer is simple: you've defined the arguments in the schema using atom identifiers, so Absinthe knows what arguments will be used ahead of time, and will coerce as appropriate---culling any extraneous arguments given to a query. This means that all arguments can be supplied to the resolve functions with atom keys.
Finally you'll see that we can handle the possibility that the query, while valid from GraphQL's perspective, may still ask for a user that does not exist. We've decided to return an error in that case.
There's a valid argument for just returning
{:ok, nil}
when a record can't be found. Whether the absence of data constitutes an error is a decision you get to make.
Arguments and Non-Root Fields
Let's assume we want to query all posts from a user published within a
given time range. First, let's add a new field to our :post
object
type, :published_at
.
The GraphQL specification doesn't define any official date or time
types, but it does support custom scalar types (you can read more
about them in the related guide), and
Absinthe ships with several built-in scalar types. We'll use
:naive_datetime
(which doesn't include timezone information) here.
Edit blog_web/schema/content_types.ex
:
defmodule BlogWeb.Schema.ContentTypes do
use Absinthe.Schema.Notation
@desc "A blog post"
object :post do
field :id, :id
field :title, :string
field :body, :string
field :author, :user
# Add this:
field :published_at, :naive_datetime
end
end
To make the :naive_datetime
type available, add an import_types
line to
your blog_web/schema.ex
:
import_types Absinthe.Type.Custom
For more information about how types are imported, read the guide on the topic.
For now, just remember that
import_types
should only be used in top-level schema module. (Think of it like a manifest.)
Here's the query we'd like to be able to use, getting the posts for a user on a given date:
{
user(id: "1") {
name
posts(date: "2017-01-01") {
title
body
publishedAt
}
}
}
To use the passed date, we need to update our :user
object type and
make some changes to its :posts
field; it needs to support a :date
argument and use a custom resolver. In blog_web/schema/account_types.ex
:
defmodule BlogWeb.Schema.AccountTypes do
use Absinthe.Schema.Notation
alias BlogWeb.Resolvers
object :user do
field :id, :id
field :name, :string
field :email, :string
# Add the block here:
field :posts, list_of(:post) do
arg :date, :date
resolve &Resolvers.Content.list_posts/3
end
end
end
For the resolver, we've added another function head to
Resolvers.Content.list_posts/3
. This illustrates how you can use the
first argument to a resolver to match the parent object of a field. In
this case, that parent object would be a Blog.Accounts.User
Ecto
schema:
# Add this:
def list_posts(%Blog.Accounts.User{} = author, args, _resolution) do
{:ok, Blog.Content.list_posts(author, args)}
end
# Before this:
def list_posts(_parent, _args, _resolution) do
{:ok, Blog.Content.list_posts()}
end
Here we pass on the user and arguments to the domain logic function,
Blog.Content.list_posts/3
, which will find the posts for the user
and date (if it's provided; the :date
argument is optional). The
resolver, just as when it's used for the top level query :posts
,
returns the posts in an :ok
tuple.
Tip
Check out the full implementation of logic for
Blog.Content.list_posts/3
--and some simple seed data--in the absinthe_tutorial repository.
If you've done everything correctly (and have some data handy), if you
start up your server with mix phx.server
and head over
to http://localhost:4000/api/graphiql, you should be able to play
with the query.
It should look something like this:
![](assets/tutorial/graphiql_user_posts.png)
Next Step
Next up, we look at how to modify our data using mutations.