Laravel Query Builder Laravel Package

title: Selecting fields weight: 4

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

⚠️ 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.