Selecting fields | laravel-query-builder | Spatie

 SPATIE

  Laravel Query Builder
========================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-query-builder](https://spatie.be/docs/laravel-query-builder/v5)  Features  Selecting fields

 Version   v7   v6   v5   v4   v3   v2

 Other versions for crawler [v7](https://spatie.be/docs/laravel-query-builder/v7) [v6](https://spatie.be/docs/laravel-query-builder/v6) [v5](https://spatie.be/docs/laravel-query-builder/v5) [v4](https://spatie.be/docs/laravel-query-builder/v4) [v3](https://spatie.be/docs/laravel-query-builder/v3) [v2](https://spatie.be/docs/laravel-query-builder/v2)

- [ Introduction ](https://spatie.be/docs/laravel-query-builder/v5/introduction)
- [ Requirements ](https://spatie.be/docs/laravel-query-builder/v5/requirements)
- [ About us ](https://spatie.be/docs/laravel-query-builder/v5/about-us)
- [ Installation & setup ](https://spatie.be/docs/laravel-query-builder/v5/installation-setup)
- [ Support us ](https://spatie.be/docs/laravel-query-builder/v5/support-us)
- [ Questions and issues ](https://spatie.be/docs/laravel-query-builder/v5/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-query-builder/v5/changelog)

Features
--------

- [ Filtering ](https://spatie.be/docs/laravel-query-builder/v5/features/filtering)
- [ Sorting ](https://spatie.be/docs/laravel-query-builder/v5/features/sorting)
- [ Including relationships ](https://spatie.be/docs/laravel-query-builder/v5/features/including-relationships)
- [ Selecting fields ](https://spatie.be/docs/laravel-query-builder/v5/features/selecting-fields)

Advanced usage
--------------

- [ Extending query builder ](https://spatie.be/docs/laravel-query-builder/v5/advanced-usage/extending-query-builder)
- [ Pagination ](https://spatie.be/docs/laravel-query-builder/v5/advanced-usage/pagination)
- [ Front-end implementation ](https://spatie.be/docs/laravel-query-builder/v5/advanced-usage/front-end-implementation)
- [ Multi value delimiter ](https://spatie.be/docs/laravel-query-builder/v5/advanced-usage/multi-value-delimiter)

      You are viewing the documentation for **an older version** of this package. You can check the version you are using with the following command:

 `                                    composer show spatie/laravel-query-builder                                                                                                                                                                                                                                    `

Selecting fields
================

###  On this page

1. [ Basic usage ](#content-basic-usage)
2. [ Disallowed fields/selects ](#content-disallowed-fieldsselects)
3. [ Selecting fields for included relations ](#content-selecting-fields-for-included-relations)

Sometimes you'll want to fetch only a couple fields to reduce the overall size of your SQL query. This can be done by specifying some fields using the `allowedFields` method and using the `fields` request query parameter.

Basic usage
-----------------------------------------------------------------------------------------

The following example fetches only the users' `id` and `name`:

```
GET /users?fields[users]=id,name

$users = QueryBuilder::for(User::class)
    ->allowedFields(['id', 'name'])
    ->toSql();
```

The SQL query will look like this:

```
SELECT "id", "name" FROM "users"
```

When not allowing any fields explicitly, Eloquent's default behaviour of selecting all fields will be used.

Disallowed fields/selects
---------------------------------------------------------------------------------------------------------------------------------

When trying to select a column that's not specified in `allowedFields()` an `InvalidFieldQuery` exception will be thrown:

```
$users = QueryBuilder::for(User::class)
    ->allowedFields('name')
    ->get();

// GET /users?fields[users]=email will throw an `InvalidFieldQuery` exception as `email` is not an allowed field.
```

Selecting fields for included relations
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Selecting fields for included models works the same way. This is especially useful when you only need a couple of columns from an included relationship. Consider the following example:

```
GET /posts?include=author&fields[author]=id,name

QueryBuilder::for(Post::class)
    ->allowedFields('author.id', 'author.name')
    ->allowedIncludes('author');

// All posts will be fetched including _only_ the name of the author.
```

⚠️ Keep in mind that the fields query will completely override the `SELECT` part of the query. This means that you'll need to manually specify any columns required for Eloquent relationships to work, in the above example `author.id`. See issue #175 as well.

⚠️ `allowedFields` must be called before `allowedIncludes`. Otherwise the query builder won't know what fields to include for the requested includes and an exception will be thrown.