Eloquent: Getting Started

Lighthouse makes it easy for you to perform queries and mutations on your Eloquent models.

Defining Models

Eloquent models usually map directly to GraphQL types.

type User {
  id: ID!
  name: String!
}

It is strongly advised to name the field that corresponds to your primary key id. Popular client libraries such as Apollo provide out-of-the-box caching if you follow that convention.

Retrieving Models

Instead of defining your own resolver manually, you can just rely on Lighthouse to build the Query for you.

type Query {
  users: [User!]! @all
}

The @all directive will assume the name of your model to be the same as the return type of the Field you are trying to resolve and automatically uses Eloquent to resolve the field.

The following query:

{
  users {
    id
    name
  }
}

Will return the following result:

{
  "data": {
    "users": [
      { "id": 1, "name": "James Bond" },
      { "id": 2, "name": "Madonna" }
    ]
  }
}

Pagination

You can leverage the @paginate directive to query a large list of models in chunks.

type Query {
  posts: [Post!]! @paginate
}

The schema definition is automatically transformed to this:

type Query {
  posts(count: Int!, page: Int): PostPaginator
}

type PostPaginator {
  data: [Post!]!
  paginatorInfo: PaginatorInfo!
}

And can be queried like this:

{
  posts(count: 10) {
    data {
      id
      title
    }
    paginatorInfo {
      currentPage
      lastPage
    }
  }
}

Adding query constraints

Lighthouse provides built-in directives to enhance your queries by giving additional query capabilities to the client.

The following field definition allows you to fetch a single User by ID.

type Query {
  user(id: ID! @eq): User @find
}

You can query this field like this:

{
  user(id: 69) {
    name
  }
}

And, if a result is found, receive a result like this:

{
  "data": {
    "user": {
      "name": "Chuck Norris"
    }
  }
}

Create

The easiest way to create data on your server is to use the @create directive.

type Mutation {
  createUser(name: String!): User! @create
}

This will take the arguments that the createUser field receives and use them to create a new model instance.

mutation {
  createUser(name: "Donald") {
    id
    name
  }
}

The newly created user is returned as a result:

{
  "data": {
    "createUser": {
      "id": "123",
      "name": "Donald"
    }
  }
}

Update

You can update a model with the @update directive.

type Mutation {
  updateUser(id: ID!, name: String): User @update
}

Since GraphQL allows you to update just parts of your data, it is best to have all arguments except id as optional.

mutation {
  updateUser(id: "123", name: "Hillary") {
    id
    name
  }
}

{
  "data": {
    "updateUser": {
      "id": "123",
      "name": "Hillary"
    }
  }
}

Be aware that while a create operation will always return a result, provided you pass valid data, the update may fail to find the model you provided and return null:

{
  "data": {
    "updateUser": null
  }
}

Delete

Deleting models is a breeze using the @delete directive. Dangerously easy.

type Mutation {
  deleteUser(id: ID!): User @delete
}

Simply call it with the ID of the user you want to delete.

mutation {
  deleteUser(id: "123") {
    secret
  }
}

This mutation will return the deleted object, so you will have a last chance to look at the data. Use it wisely.

{
  "data": {
    "deleteUser": {
      "secret": "Pink is my favorite color!"
    }
  }
}