cartodb-postgresql/doc/CDB_Overviews.md

Overviews are tables that represent a *reduced* version of a dataset intended
for efficient rendering at certain zoom levels while preserving the
general visual appearance of the complete dataset.

The *reduction* consists in a fewer number of records
(while each overview record may represent an aggregation of multiple records)
and/or simplified record geometries.

Overviews are created through the `CDB_CreateOverviews`.
The statement timeout may need to be adjusted before using this function,
as overview creation for large tables is a time-consuming operation.

The `CDB_Overviews` function can be used determine what overview tables
exist for a given dataset table and which zoom levels correspond to it.

The `CDB_DropOverviews` remove a dataset's existing overviews.

### CDB_CreateOverviews

Create overviews for vector dataset.

#### Using the function

The table for which overviews will be generated should be
a Cartodbfied dataset with vector geometry.

```sql
SELECT CDB_CreateOverviews('table_name');
--- Generates overview tables for the dataset
```

#### Arguments

CDB_CreateOverviews(table_name, ref_z_strategy, reduction_strategy)

* **table_name** regclass, table for which overviews will be generated
* **ref_z_strategy** regproc, optional function that provides
  the Z-scale strategy.
  It returns the base Z level for the dataset.
  It should have these arguments:
  - **table_name** regclass, table to compute the reference Z scale for
* **reduction_strategy** regproc, optional function that provides
  the reduction strategy to generate an overview table from a table
  for a smaller scale (higher Z number).
  It returns the name of the generated table.
  It should have these arguments:
  - **base_table_name** regclass, base table to be reduced.
  - **base_z** integer, base Z level assigned to the base table.
  - **overview_z** integer, Z level for which to generate the overview.

#### Tolerance / level of detail

The level of detail to be representable by each overview layer can
be specified as a tolerance in pixels (if different from the default of 2 pixels)
with the function `CDB_CreateOverviewsWithToleranceInPixels`
which has as a second additional argument the desired tolerance.

### CDB_Overviews

Obtain overview metadata for a given table (existing overviews).
The returned relation will be empty if the table has no overviews.

The function can be applied to a single table:

```sql
SELECT CDB_Overviews('table_name');
--- Return existing overview Z levels and corresponding tables
```

Or to multiple tables passed as an array; this can be used
to obtain the overviews that can be applied to a query by
combining it with `CDB_QueryTablesText`:

```sql
SELECT CDB_Overviews(CDB_QueryTablesText('SELECT * FROM table1, table2'));
--- Return existing overview Z levels and corresponding tables
```

The result of `CDB_Overviews` has three columns:

| base_table | z | overview_table |
|------------+---+----------------|
| table1     | 1 | table1_ov1     |
| table1     | 2 | table1_ov2     |
| table1     | 4 | table1_ov4     |
| table2     | 1 | table1_ov1     |
| table2     | 2 | table1_ov2     |

#### Arguments

CDB_Overviews(table_name)

* **table_name** regclass, oid of table to obtain existing overviews for

CDB_Overviews(table_names)

* **table_names** regclass[], array of table oids


### CDB_DropOverviews

Remove the overviews of a table, if present.

```sql
SELECT CDB_DropOverviews('table_name');
```

#### Arguments

CDB_Overviews(table_name)

* **table_name** regclass, table for which to drop existing overviews.