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/v7)  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/v7/introduction)
- [ Requirements ](https://spatie.be/docs/laravel-query-builder/v7/requirements)
- [ About us ](https://spatie.be/docs/laravel-query-builder/v7/about-us)
- [ Installation & setup ](https://spatie.be/docs/laravel-query-builder/v7/installation-setup)
- [ Support us ](https://spatie.be/docs/laravel-query-builder/v7/support-us)
- [ Questions and issues ](https://spatie.be/docs/laravel-query-builder/v7/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-query-builder/v7/changelog)

Features
--------

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

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

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

 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[authors]=id,name

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

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

⚠️ **Note:** In `allowedFields`, you must always use the *snake case plural* of your relation name. If you want to change this behavior, you can change the settings in the [configuration file](https://spatie.be/docs/laravel-query-builder/v7/installation-setup)

⚠️ 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](https://github.com/spatie/laravel-query-builder/issues/175) as well.