Host GraphQL endpoints in Data API builder

Entities configured to be available via GraphQL are available at the default path: https://{base_url}//graphql. Data API builder automatically generates a GraphQL schema with query and mutation fields for all configured entities. The GraphQL schema can be explored using a modern GraphQL client that includes features like autocomplete.

If you followed the Getting Started example, where there are the books and the authors entity configured for GraphQL access, you can see how easy is to use GraphQL.

Result set format

The returned result is a JSON object with this format:

{
    "data": {}    
}

Supported root types

Data API builder supports the following GraphQL root types:

Queries Mutations

Queries

Each entity has support for the following actions:

• Pagination
• Query by Primary key
• Generic Query

Data API builder, unless otherwise specified, uses the singular name of an entity whenever the query is expected to return a single item. Conversely, the Data API builder uses the plural name of an entity whenever the query is expected to return a list of items. For example, the book entity has:

• book_by_pk(): to return zero or one entity
• books(): to return a list of zero or more entities

Pagination

All query types returning zero or more items support pagination:

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}

• the item object allows access to entity fields
• hasNextPage is set to true if there are more items to be returned
• endCursor returns an opaque cursor string that can be used with first and after query parameters to get the next set (or page) of items.

Query by primary key

Every entity support retrieval of a specific item via its Primary Key, using the following query format:

<entity>_by_pk(<pk_colum>:<pk_value>)
{
    <fields>
}

For example:

{
  book_by_pk(id:1010) {
    title
  }
}

Generic query

Every entity also supports a generic query pattern so that you can ask for only the items you want, in the order you want, using the following parameters:

• filter: filters the returned items
• orderBy: defines how the returned data is sorted
• first and after: returns only the top n items

For example:

{
  authors(
    filter: {
        or: [
          { first_name: { eq: "Isaac" } }
          { last_name: { eq: "Asimov" } }
        ]
    }
  ) {
    items {
      first_name
      last_name
      books(orderBy: { year: ASC }) {
        items {
          title
          year
        }
      }
    }
  }
}

filter

The value of the filter parameter is predicate expression (an expression that returns a boolean value) using entity's fields. Only items where the expression evaluates to 'True' are included in the response. For example:

{
  books(filter: { title: { contains: "Foundation" } })
  {
    items {
      id
      title
      authors {
        items {
          first_name
          last_name
        }
      }
    }
  }
}

This query returns all the books with the word Foundation in the title.

The operators supported by the filter parameter are:

orderBy

The value of the orderby set the order with which the items in the resultset are returned. For example:

{
  books(orderBy: {title: ASC} )
  {
    items {
      id
      title
    }
  }
}

This query returns books ordered by title.

first and after

The parameter first limits the number of items returned. For example:

query {
  books(first: 5)
  {
    items {
      id
      title
    }
    hasNextPage
    endCursor
  }
}

This query returns the first five books. When no orderBy is specified, items are ordered based on the underlying primary key. The value provided to orderBy must be a positive integer.

If there are more items in the book entity than those entities requested via first, the hasNextPage field will evaluate to true, and the endCursor will return a string that can be used with the after parameter to access the next items. For example:

query {
  books(first: 5, after: "W3siVmFsdWUiOjEwMDQsIkRpcmVjdGlvbiI6MCwiVGFibGVTY2hlbWEiOiIiLCJUYWJsZU5hbWUiOiIiLCJDb2x1bW5OYW1lIjoiaWQifV0=")
  {
    items {
      id
      title
    }
    hasNextPage
    endCursor
  }
}

Mutations

For each entity, mutations to support create, update, and delete operations are automatically created. The mutation operation is created using the following name pattern: <operation><entity>. For example, for the book entity, the mutations would be:

• createbook: create a new book
• updatebook: update an existing book
• deletebook: delete the specified book

Create

To create a new element of the desired entity, the create<entity> mutation is provided. The created mutation requires the item parameter, where values for entity's mandatory fields, to be used when creating the new item, are specified.

create<entity>(item: <entity_fields>)
{
    <fields>
}

For example:

mutation {
  createbook(item: {
    id: 2000,
    title: "Leviathan Wakes"    
  }) {
    id
    title
  }  
}

Update

To update an element of the desired entity, the update<entity> mutation is provided. The update mutation requires two parameters:

• <primary_key>, the key-value list of primary key columns and related values to identify the element to be updated
• item: parameter, with entity's mandatory fields values, to be used when updating the specified item

update<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,] item: <entity_fields>)
{
    <fields>
}

For example:

mutation {
  updatebook(id: 2000, item: {
    year: 2011,
    pages: 577    
  }) {
    id
    title
    year
    pages
  }
}

Delete

To delete an element of the desired entity, the delete<entity> mutation is provided. The primary key of the element to be deleted is the required parameter.

delete<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,])
{
    <fields>
}

For example:

mutation {
  deletebook(id: 1234)
  {
    id
    title
  }  
}

Database transactions for a mutation

To process a typical GraphQL mutation request, Data API builder constructs two database queries. One of the database queries performs the update (or) insert (or) delete action that is associated with the mutation. The other database query fetches the data requested in the selection set.

Data API builder executes both database queries in a transaction. Transactions are created only for SQL database types.

The following table lists the isolation levels with which the transactions are created for each database type.

Related content

• GraphQL configuration reference
• OpenAPI