Analytics Toolbox for BigQuery

Analytics Toolbox for BigQuery

Creating and visualizing tilesets

Creating a tileset

From the CARTO Workspace

The CARTO Workspace offers a user interface that you can use to create tilesets. The option Create a tileset is available from the Data Explorer from the Connections tab. To create a tileset from your data, select an available connection and click on a specific table (database/project(s), schemas/datasets and tables) from the collapsible tree.

Create tileset button available from the Data Explorer

Clicking on the Create a tileset button will trigger a tileset creation wizard that you can follow along to configure your tileset. For step-by-step instructions, please visit this guide.

Create tileset wizard from the Data Explorer

From the BigQuery console or client

As a CARTO Analytics Toolbox module, the Tiler’s capabilities are available as SQL procedures that can be executed directly from your BigQuery console or client of choice after connecting your CARTO account to BigQuery.

To check that your Google account or service account has access to the Tiler, try running this query:

𝅺
1
SELECT `carto-un`.carto.VERSION_ADVANCED()

Check the Getting Access section if you run into any errors when running the query above.

Once you are all set getting access to the Tiler, creating a tileset is as easy as opening your BigQuery console or client and running a query. In this case, we are going to create a simple tileset (see Tileset procedures) from a couple of joined tables: one containing demographic information for the US at the blockgroup level, the other containing the geometries of the blockgroups.

The result will be a tileset with the geometry and total population per blockgroup:

𝅺
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
CALL `carto-un`.carto.CREATE_SIMPLE_TILESET(
  R'''
  (
    SELECT
      d.geoid,
      d.total_pop,
      g.geom
    FROM `carto-do-public-data.usa_acs.demographics_sociodemographics_usa_blockgroup_2015_5yrs_20142018` d
    JOIN `carto-do-public-data.carto.geography_usa_blockgroup_2015` g
      ON d.geoid = g.geoid
  ) _input
  ''',
  R'''`cartobq.maps.blockgroup_pop`''',
  R'''
  {
    "zoom_min": 0,
    "zoom_max": 14,
    "max_tile_size_kb": 3072,
    "properties":{
      "geoid": "String",
      "total_pop": "Number"
    }
  }'''
);

Creating a tileset by means of CREATE_SIMPLE_TILESET can sometimes be cumbersome due to the large amount of parameters that users have to manage. In order to relieve them of this responsibility, we provide a wrapper function in which the tiler configuration is automatically set by performing a previous analysis of the input data. This analysis also serves as a validation step to avoid BigQuery limitations. As a result, the above generated tileset can also be obtained by executing:

𝅺
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
CALL `carto-un`.carto.CREATE_TILESET(
  R'''
  (
    SELECT
      d.geoid,
      d.total_pop,
      g.geom
    FROM `carto-do-public-data.usa_acs.demographics_sociodemographics_usa_blockgroup_2015_5yrs_20142018` d
    JOIN `carto-do-public-data.carto.geography_usa_blockgroup_2015` g
      ON d.geoid = g.geoid
  ) _input
  ''',
  R'''`cartobq.maps.blockgroup_pop`''',
  null
);

or by defining explicitly the options if they are required:

𝅺
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
CALL `carto-un`.carto.CREATE_TILESET(
  R'''
  (
    SELECT
      d.geoid,
      d.total_pop,
      g.geom
    FROM `carto-do-public-data.usa_acs.demographics_sociodemographics_usa_blockgroup_2015_5yrs_20142018` d
    JOIN `carto-do-public-data.carto.geography_usa_blockgroup_2015` g
      ON d.geoid = g.geoid
  ) _input
  ''',
  R'''`cartobq.maps.blockgroup_pop`''',
  STRUCT
  (
    null AS name,
    null AS description,
    null AS legend,
    0 AS zoom_min,
    14 AS zoom_max,
    null AS geom_column_name,
    null AS zoom_min_column,
    null AS zoom_max_column,
    3072 AS max_tile_size_kb,
    null AS tile_feature_order,
    null AS drop_duplicates,
    null AS extra_metadata
  )
);

Visualizing a tileset

From the CARTO Workspace

The CARTO Workspace offers access to the Data Explorer, where you will be able to preview your tilesets, and Builder, CARTO’s state-of-the-art map making tool, where you will be able to style them, include them in your visualizations and share them.

Previewing tilesets from the Data Explorer

The Data Explorer offers a preview of your tilesets and displays their associated details and metadata, such as their size, number of records and statistics regarding the tile sizes per zoom level. Please refer to this page for more information regarding the Data Explorer.

Tileset preview from the Data Explorer
Creating maps with tilesets using Builder

You can include tilesets as layers in your maps created with Builder. To do so, you have two options:

  • use the Create map option from the tileset preview page in the Data Explorer (see previous screenshot). This action will create a new map with your tileset as a its only layer.
  • adding a layer to an existing map.

For the latter option, you simply need to follow these simple steps:

  1. Click on the Add source from button in Builder, that can be found at the bottom left of the screen.
Choosing connection to add tileset from
  1. Choose the BigQuery connection from where your tileset is accessible.
  2. Browse your projects and datasets until you find your tileset in the data explorer tree.
Choosing tileset to add as layer
  1. Select your tileset. Your tileset will then be added as a layer.
Tileset added as layer
  1. Style your tileset like any other layer in Builder. For more details on how to style your layers, please visit this page.
Tileset added as layer and styled