Looking for the Prisma documentation? You can find it here

Query API

Last updated a day ago Edit this page

#Overview

A GraphQL query is used to fetch data from a GraphQL endpoint. This is an example query:

Query Variables
Hit the Play Button to get a response here
Docs

You can click the Play-button in the code snippet to run the query and see the server response. You can also modify the query and observe the changes in the responses that are sent by the server.

Here's a list of available queries. To explore them, use the playground for your service.

Some queries support query arguments to further control the query response.

#Type queries

#Fetching a single node

For each model type in your service, the Simple API provides an auto-generated query to fetch one specific node of that type. To specify the node, all you need to provide is its id or another unique field.

For example, for a type called Post a top-level query Post will be generated.

Specifying the node by id

You can always use the system-managed id field to identify a node.

Query a specific post by its id:

Query Variables
Hit the Play Button to get a response here
Docs

Specifying the node by another unique field

You can also supply any unique field as an argument to the query to identify a node. For example, if you already declared the slug field of the Post type to be unique, you could select a post by specifying its slug:

Query a specific Post node by its slug:

Query Variables
Hit the Play Button to get a response here
Docs

Note: You cannot specify two or more unique arguments for one query at the same time.

#Fetch multiple nodes

The Simple API contains automatically generated queries to fetch all nodes of a certain model type. For example, for the Post type the top-level query allPosts will be generated.

Fetch all nodes of a specific type

Query all Post nodes:

Query Variables
Hit the Play Button to get a response here
Docs

Here are a few examples for the generated query names:

  • type name: Post, query name: allPosts
  • type name: Todo, query name: allTodoes
  • type name: Hobby, query name: allHobbies.

Note: The query name approximate the plural rules of the English language. If you are unsure about the actual query name, explore available queries in your playground.

Fetch certain nodes of a specific type

Query all Post nodes with a title that contains the string biggest:

Query Variables
Hit the Play Button to get a response here
Docs

#Type aggregation queries

For every type in your GraphQL schema, different aggregation queries are available.

Fetch the number of all nodes

Count the number of all User nodes:

Query Variables
Hit the Play Button to get a response here
Docs

Count the number of nodes matching a certain filter condition

Count the number of all User nodes with accessRole ADMIN:

Query Variables
Hit the Play Button to get a response here
Docs

More aggregation options

Currently, count is the only available aggregation. For specific use cases, you can use functions to precalculate certain aggregations and update them when data changes.

#Relation queries

Every available relation in your type definitions adds a new field to the type queries of the two connected types.

For example, with the following schema:

1
2
3
4
5
6
7
8
9
10
11
type Post @model {
  id: ID! @isUnique
  title: String!
  author: User @relation(name: "UserOnPost")
}

type User @model {
  id: ID! @isUnique
  name : String!
  posts: [Post!]! @relation(name: "UserOnPost")
}

the following fields will be available:

#Traversing a single node

Traversing edges that connect the current node to the one side of a relation can be done by simply selecting the according field defined with the relation.

Query information on the author node connected to a specific Post node:

Query Variables
Hit the Play Button to get a response here
Docs

The author field exposes a further selection of properties that are defined on the Author type.

Note: You can add filter query arguments to an inner field returning a single node.

#Traversing many nodes

In the Simple API, traversing edges connecting the current node to the many side of a relation works the same as for a one side of a relation. Simply select the relation field.

Query information on all Post nodes of a certain author node:

Query Variables
Hit the Play Button to get a response here
Docs

The posts field exposes a further selection of properties that are defined on the Post type.

Note: Query arguments for an inner field returning multiple nodes work similar as elsewhere.

#Relation aggregation

Nodes connected to multiple nodes via a one-to-many or many-to-many edge expose the _<edge>Meta field that can be used to query meta information of a connection rather than the actual connected nodes.

Query meta information on all Post nodes of a certain author node:

Query Variables
Hit the Play Button to get a response here
Docs

Query meta information on certain Post nodes of a certain author node:

Query Variables
Hit the Play Button to get a response here
Docs

#Query arguments

All queries and fields that return many nodes accept different query arguments to further control the query response. The response can be either of the following:

These query arguments can be combined to achieve very specific query responses.

#Ordering by field

When querying all nodes of a model type you can supply the orderBy argument for every scalar field of the type: orderBy: <field>_ASC or orderBy: <field>_DESC.

Order the list of all Post nodes ascending by title:

Query Variables
Hit the Play Button to get a response here
Docs

Order the list of all Post nodes descending by published:

Query Variables
Hit the Play Button to get a response here
Docs

Note: The field you are ordering by does not have to be selected in the actual query. If you do not specify an ordering, the response is implicitely ordered ascending by the id field

#Filtering by field

When querying all nodes of a type you can supply different parameters to the filter argument to filter the query response accordingly. The available options depend on the scalar fields defined on the type in question.

You can also include filters when including related fields in your queries to traverse your data graph.

Applying single filters

If you supply exactly one parameter to the filter argument, the query response will only contain nodes that adhere to this constraint.

Filtering by value

The easiest way to filter a query response is by supplying a field value to filter by.

Query all Post nodes that are not yet published:

Query Variables
Hit the Play Button to get a response here
Docs
Advanced filter criteria

Depending on the type of the field you want to filter by, you have access to different advanced criteria you can use to filter your query response. See how to explore available filter criteria.

Query all Post nodes whose title is in a given list of strings:

Query Variables
Hit the Play Button to get a response here
Docs

Note: you have to supply a list as the <field>_in argument: title_in: ["My biggest Adventure", "My latest Hobbies"].

Relation filters

For to-one relations, you can define conditions on the related node by nesting the according argument in filter

Query all Post nodes where the author has the USER access role:

Query Variables
Hit the Play Button to get a response here
Docs

For to-many relations, three additional arguments are available: every, some and none, to define that a condition should match every, some or none related nodes.

Query all User nodes that have at least one Post node that's published:

Query Variables
Hit the Play Button to get a response here
Docs

Relation filters are also available in the nested arguments for to-one or to-many relations.

Query all User nodes that did not like a Post of an author in the ADMIN access role:

Query Variables
Hit the Play Button to get a response here
Docs

Combining multiple filters

You can use the filter combinators OR and AND to create an arbitrary logical combination of filter conditions.

Using OR or AND

Let's start with an easy example:

Query all Post nodes that are published and whose title is in a given list of strings:

Query Variables
Hit the Play Button to get a response here
Docs

Note: OR and AND accept a list as input where individual list items have to be wrapped by {}: AND: [{title_in: ["My biggest Adventure", "My latest Hobbies"]}, {published: true}]

Arbitrary combination of filters with AND and OR

You can combine and even nest the filter combinators AND and OR to create arbitrary logical combinations of filter conditions.

Query all Post nodes that are either published and whose title is in a list of given strings, or have the specific id we supply:

Query Variables
Hit the Play Button to get a response here
Docs

Notice how we nested the AND combinator inside the OR combinator, on the same level with the id value filter.

Explore available filter criteria

Apart from the filter combinators AND and OR, the available filter arguments for a query for all nodes of a type depend on the fields of the type and their types.

Let's consider the following schema:

1
2
3
4
5
6
7
8
9
10
type Meta {
  id: ID! @isUnique
  text: String!
  number: Int!
  decimal: Float!
  flag: Boolean!
  date: DateTime!
  enum: SomeEnum!
  object: Json!
}

Based on this type, a MetaFilter type will be generated with the following fields, grouped by field type.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
input MetaFilter {
  # logical operators
  AND: [MetaFilter!] # combines all passed `MetaFilter` objects with logical AND
  OR: [MetaFilter!] # combines all passed `MetaFilter` objects with logical OR

  # DateTime filters
  createdAt: DateTime # matches all nodes with exact value
  createdAt_not: DateTime # matches all nodes with different value
  createdAt_in: [DateTime!] # matches all nodes with value in the passed list
  createdAt_not_in: [DateTime!] # matches all nodes with value not in the passed list
  createdAt_lt: DateTime # matches all nodes with lesser value
  createdAt_lte: DateTime # matches all nodes with lesser or equal value
  createdAt_gt: DateTime # matches all nodes with greater value
  createdAt_gte: DateTime # matches all nodes with greater or equal value

  # Float filters
  decimal: Float # matches all nodes with exact value
  decimal_not: Float # matches all nodes with different value
  decimal_in: [Float!] # matches all nodes with value in the passed list
  decimal_not_in: [Float!] # matches all nodes with value not in the passed list
  decimal_lt: Float # matches all nodes with lesser value
  decimal_lte: Float # matches all nodes with lesser or equal value
  decimal_gt: Float # matches all nodes with greater value
  decimal_gte: Float # matches all nodes with greater or equal value

  # Enum filters
  enum: META_ENUM # matches all nodes with exact value
  enum_not: META_ENUM # matches all nodes with different value
  enum_in: [META_ENUM!] # matches all nodes with value in the passed list
  enum_not_in: [META_ENUM!] # matches all nodes with value not in the passed list

  # Boolean filters
  flag: Boolean # matches all nodes with exact value
  flag_not: Boolean # matches all nodes with different value

  # ID filters
  id: ID # matches all nodes with exact value
  id_not: ID # matches all nodes with different value
  id_in: [ID!] # matches all nodes with value in the passed list
  id_not_in: [ID!] # matches all nodes with value not in the passed list
  id_lt: ID # matches all nodes with lesser value
  id_lte: ID # matches all nodes with lesser or equal value
  id_gt: ID # matches all nodes with greater value
  id_gte: ID # matches all nodes with greater or equal value
  id_contains: ID # matches all nodes with a value that contains given substring
  id_not_contains: ID # matches all nodes with a value that does not contain given substring
  id_starts_with: ID # matches all nodes with a value that starts with given substring
  id_not_starts_with: ID # matches all nodes with a value that does not start with given substring
  id_ends_with: ID # matches all nodes with a value that ends with given substring
  id_not_ends_with: ID # matches all nodes with a value that does not end with given substring

  # Int filters
  number: Int # matches all nodes with exact value
  number_not: Int # matches all nodes with different value
  number_in: [Int!] # matches all nodes with value in the passed list
  number_not_in: [Int!] # matches all nodes with value not in the passed list
  number_lt: Int # matches all nodes with lesser value
  number_lte: Int # matches all nodes with lesser or equal value
  number_gt: Int # matches all nodes with greater value
  number_gte: Int # matches all nodes with greater or equal value

  # String filters
  text: String # matches all nodes with exact value
  text_not: String # matches all nodes with different value
  text_in: [String!] # matches all nodes with value in the passed list
  text_not_in: [String!] # matches all nodes with value not in the passed list
  text_lt: String # matches all nodes with lesser value
  text_lte: String # matches all nodes with lesser or equal value
  text_gt: String # matches all nodes with greater value
  text_gte: String # matches all nodes with greater or equal value
  text_contains: String # matches all nodes with a value that contains given substring
  text_not_contains: String # matches all nodes with a value that does not contain given substring
  text_starts_with: String # matches all nodes with a value that starts with given substring
  text_not_starts_with: String # matches all nodes with a value that does not start with given substring
  text_ends_with: String # matches all nodes with a value that ends with given substring
  text_not_ends_with: String # matches all nodes with a value that does not end with given substring
}

#Custom queries

For use cases that are not covered by the automatically generated CRUD API, resolver functions can be used to extend your service's GraphQL schema with custom queries and mutations.

You can define the name, input arguments and payload of the query and resolve it with a Graphcool Function.

#Example

Validate the age of a user

Schema Extension SDL document:

1
2
3
4
5
6
7
8
type AgePayload {
  isValid: Boolean!
  age: Int!
}

extend type Query {
  isValidAge(age: Int!): AgePayload
}

Graphcool Function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
module.exports = function age(event) {
  const age = event.data.age

  if (age < 0) {
    return {
      error: "Invalid input"
    }
  }

  const isValid = age >= 18

  return {
    data: {
      isValid,
      age
    }
  }
}

Then the query can be called like this using the Simple API:

1
2
3
4
5
6
query {
  isValidAge(age: 12) {
    isValid # false
    age # 12
  }
}

Note that the returned object contains a data key, which in turn contains the number field that was specified in the RandomNumberPayload in the SDL document. Error handling works similarly to other Graphcool Functions, if an object containing the error key is returned.

#The authenticated User (only for legacy Console projects)

If the request of a query contains authentication information on the session user, you can use the user query to query information on that user. All fields of the User type are available.

Query Variables
Hit the Play Button to get a response here
Docs

If no user is signed in, the query response will look like this:

Query Variables
Hit the Play Button to get a response here
Docs

Note that you have to set appropriate permissions on the User type to use the user query.

Was this page helpful?