---
title: Query Builder
---

# Query Builder

<div class="documentation__toc"></div>

## Introduction

Query builders in the Streams Platform work just the same as [query builders in Laravel](https://laravel.com/docs/queries) with the addition of a few cool features.

### Starting Queries

You can use repositories to start queries.

```php
$repository = app(\Anomaly\PagesModule\Page\Contract\PageRepositoryInterface::class);

$pages = $repository->newQuery()->where('enabled', true)->get();
```

You can also use the model itself as you would in Laravel.

```php
use \Anomaly\PagesModule\Page\PageModel;

$pages = (new PageModel)->where('enabled', true)->get();
```

## Database Cache

The query builder provides a direct API for storing query results in the model's `cache collection`. The cache collection is automatically cleared when the model's table is altered in any way (such as saving, deleting, etc).

### Enabling Database Cache

#### Settings Module

You can enable database caching and default TTL using the [Settings Module](/documentation/settings-module) by navigating to **Settings > System**.

#### Environmental Configuration

You can also manage cache using the `.env` file:

```bash
DB_CACHE=true
DB_CACHE_TTL=300
```

#### Configuration

And lastly you can set the config value dynamically at run time:

```php
config([
    'streams::database.cache' => true,
    'streams::database.ttl' => 300,
]);
```

### Caching Queries

You can set the cache lifetime in `seconds` by using the `ttl` method:

```php
$results = $model->where('status', true)->ttl(300)->get();
```

> Caching queries uses query strings and bindings to ensure uniqueness.{.note}

### Fetching Fresh Results

If you are leveraging query caching you may want to temporarily omit cache. You can do this by using the `fresh` method.

```php
$results = $model->where('status', true)->fresh()->get();
```

### Manually Flushing Cache

Model related cache is flushed automatically when entries are updated, created, or deleted.
 
You can manually flush the cache by using the model's `flushCache` method:
 
```php
$model->flushCache();
```

### Clearing Cache

You can use the `cache:clear` CLI command to clear **all** cache including database cache.

```bash
php artisan cache:clear
```


You can also clear all Laravel cache including database cache using `php artisan cache:clear`. 

### Model TTL

Some models define their own default `ttl` property. When database caching is enabled, queries for these models will be cached automatically by default.

```php
protected $ttl = 300; // 5 minutes
```

If the value is `null` (default) then the default TTL (3600 by default) will be used:

```php
protected $ttl = null;
```

You can also disable default database caching for a model by using `false`:

```php
protected $ttl = false;
```


## Translating

You can automatically join translation tables and therefore field values using the `translate` method.

An optional `locale` maybe passed otherwise the active locale will be used.

> This method can **not** be called from the model to **start** a query like others.{.important}

```php
$default = $model->newQuery()->translate()->where('name', 'Cool Thing')->get();

$german = $model->newQuery()->translate('de')->where('name', 'Coole Sache')->get();
```
