CARTO Layers

CARTO layers render cloud data from any connection (BigQuery, Snowflake, Redshift, Postgres, Databricks). Layer types pydeck-carto wrap the equivalent layer types from deck.gl <https://deck.gl/docs/api-reference/carto/overview#carto-layers>_.

Pydeck-carto layers are not included in pydeck by default, so calling :meth:pydeck_carto.register_layers is required to register the CARTO layers with pydeck.

Example ^^^^^^^

.. code-block:: python

import pydeck as pdk
import pydeck_carto as pdkc
from carto_auth import CartoAuth

# Authentication with CARTO
carto_auth = CartoAuth.from_oauth()

# Register CARTO layers in pydeck
pdkc.register_layers()

# Create CARTO data source
data = pdkc.sources.vector_query_source(
    access_token=carto_auth.get_access_token(),
    api_base_url=carto_auth.get_api_base_url(),
    connection_name="carto_dw",
    sql_query="SELECT geom, name FROM carto-demo-data.demo_tables.world_airports",
)

# Render CARTO layer in pydeck
layer = pdk.Layer(
    "VectorTileLayer",
    data=data,
    get_fill_color=[238, 77, 90],
    point_radius_min_pixels=2.5,
    pickable=True,
)

view_state = pdk.ViewState(latitude=0, longitude=0, zoom=1)
tooltip={"html": "<b>Name:</b> {name}", "style": {"color": "white"}}
pdk.Deck(layer, map_style=pdk.map_styles.ROAD, initial_view_state=view_state, tooltip=tooltip)

.. figure:: images/layer-table.png

.. code-block:: python

# SQL query from a BigQuery connection
data = pdkc.sources.vector_query_source(
    access_token=carto_auth.get_access_token(),
    api_base_url=carto_auth.get_api_base_url(),
    connection_name="carto_dw",
    sql_query="""
        SELECT a.geom, a.name
        FROM `carto-demo-data.demo_tables.world_airports` AS a,
             `carto-do-public-data.natural_earth.geography_glo_admin0countries_410` AS g
        WHERE g.ADMIN = 'Spain' AND
              ST_INTERSECTS(a.geom, g.geom)
    """,
)

# Render CARTO layer in pydeck
layer = pdk.Layer(
    "VectorTileLayer",
    data=data,
    get_fill_color=[238, 77, 90],
    point_radius_min_pixels=2.5,
    pickable=True,
)

view_state = pdk.ViewState(latitude=36, longitude=-7.44, zoom=4)
tooltip = {"html": "<b>Name:</b> {name}", "style": {"color": "white"}}
pdk.Deck(layer, map_style=pdk.map_styles.ROAD, initial_view_state=view_state, tooltip=tooltip)

.. figure:: images/layer-query.png

Error management ^^^^^^^^^^^^^^^^

Any data error is displayed instead of the map to provide instant feedback about the input parameters. For example, the user is not authorized, the connection or the column names do not exist, etc.

.. figure:: images/error-message-column.png

Properties ^^^^^^^^^^

See deck.gl documentation for all layer properties <https://deck.gl/docs/api-reference/carto/overview#carto-layers>_.

VectorTileLayer


* **data**: (``pydeck-carto.types.Source``) Source created with
  :meth:`pydeck_carto.sources.vector_table_source`,
  :meth:`pydeck_carto.sources.vector_query_source`, or
  :meth:`pydeck_carto.sources.vector_tileset_source`.

H3TileLayer
~~~~~~~~~~~

* **data**: (``pydeck-carto.types.Source``) Source created with
  :meth:`pydeck_carto.sources.h3_table_source`,
  :meth:`pydeck_carto.sources.h3_query_source`, or
  :meth:`pydeck_carto.sources.h3_tileset_source`.

QuadbinTileLayer

data: (pydeck-carto.types.Source) Source created with :meth:pydeck_carto.sources.quadbin_table_source, :meth:pydeck_carto.sources.quadbin_query_source, or :meth:pydeck_carto.sources.quadbin_tileset_source.

Reference ^^^^^^^^^

.. automodule:: pydeck_carto :members: