CARTO cloud native integration

docs/api-reference/carto/basemap.md

@@ -35,14 +35,14 @@ import {BASEMAP} from '@deck.gl/carto';
 To use pre-bundled scripts:
 
 ```html
-<script src="https://unpkg.com/deck.gl@^8.2.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/carto@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/deck.gl@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.5.0/dist.min.js"></script>
 
 <!-- or -->
-<script src="https://unpkg.com/@deck.gl/core@^8.0.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/layers@^8.2.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/geo-layers@^8.2.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/carto@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/core@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/layers@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/geo-layers@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.5.0/dist.min.js"></script>
 ```
 
 ```js

docs/api-reference/carto/carto-bqtiler-layer.md

@@ -1,11 +1,10 @@
-
-
 # CartoBQTilerLayer
+>CartoBQTilerLayer will be deprecated in future versions. Use CartoLayer instead.  If you've existing code using this layer, check [the migration steps](#migration-to-cartolayer).
 
 `CartoBQTilerLayer` is a layer to visualize large datasets (millions or billions of rows) directly from [Google BigQuery](https://cloud.google.com/bigquery) without having to move data outside of BigQuery.
 
-First you need first to generate a tileset of your dataset in your BigQuery account using CARTO BigQuery Tiler. For more info click [here](https://carto.com/bigquery/beta/).
-
+First you need first to generate a tileset of your dataset in your BigQuery account using CARTO BigQuery Tiler. For more info click [here](https://carto.com/bigquery-tiler/).
+ 
 ```js
 import DeckGL from '@deck.gl/react';
 import {CartoBQTilerLayer} from '@deck.gl/carto';
@@ -23,6 +22,28 @@ function App({viewState}) {
 }
 ```
 
+## Migration to CartoLayer
+
+To migrate from `CartoBQTilerLayer` to `CartoLayer` you only need to change the layer name and set `type` property to `MAP_TYPES.TILESET`:
+
+```js
+import DeckGL from '@deck.gl/react';
+import {CartoLayer, MAP_TYPES} from '@deck.gl/carto';
+
+function App({viewState}) {
+  const layer = new CartoLayer({
+    type: MAP_TYPES.TILESET,
+    data: 'cartobq.maps.nyc_taxi_points_demo_id',
+    getLineColor: [255, 255, 255],
+    getFillColor: [238, 77, 90],
+    pointRadiusMinPixels: 2,
+    lineWidthMinPixels: 1
+  });
+
+  return <DeckGL viewState={viewState} layers={[layer]} />;
+}
+```
+
 ## Installation
 
 To install the dependencies from NPM:
@@ -41,14 +62,14 @@ new CartoBQTilerLayer({});
 To use pre-bundled scripts:
 
 ```html
-<script src="https://unpkg.com/deck.gl@^8.2.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/carto@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/deck.gl@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.5.0/dist.min.js"></script>
 
 <!-- or -->
-<script src="https://unpkg.com/@deck.gl/core@^8.0.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/layers@^8.2.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/geo-layers@^8.2.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/carto@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/core@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/layers@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/geo-layers@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.5.0/dist.min.js"></script>
 ```
 
 ```js
@@ -73,6 +94,10 @@ Optional. Needed for highlighting a feature split across two or more tiles if no
 
 A string pointing to a tile attribute containing a unique identifier for features across tiles.
 
+##### `credentials` (Object)
+
+Optional. Overrides the configuration to connect with CARTO. Check the parameters [here](overview#carto-credentials).
+
 ### Callbacks
 
 #### `onDataLoad` (Function, optional)

docs/api-reference/carto/carto-layer.md

@@ -0,0 +1,149 @@
+# CartoLayer
+
+`CartoLayer` is the layer to visualize data using the CARTO Maps API.
+
+## Usage
+
+```js
+import DeckGL from '@deck.gl/react';
+import {CartoLayer, setDefaultCredentials, MAP_TYPES, API_VERSIONS} from '@deck.gl/carto';
+
+setDefaultCredentials({
+  apiVersion: API_VERSIONS.V2,
+  username: 'public',
+  apiKey: 'default_public'
+});
+
+function App({viewState}) {
+  const layer = new CartoLayer({
+    type: MAP_TYPES.QUERY,
+    data: 'SELECT * FROM world_population_2015',
+    pointRadiusMinPixels: 2,
+    getLineColor: [0, 0, 0, 125],
+    getFillColor: [238, 77, 90],
+    lineWidthMinPixels: 1
+  })
+
+  return <DeckGL viewState={viewState} layers={[layer]} />;
+}
+```
+
+## Usage Carto Cloud Native
+
+```js
+import DeckGL from '@deck.gl/react';
+import {CartoLayer, setDefaultCredentials, MAP_TYPES, API_VERSIONS} from '@deck.gl/carto';
+
+setDefaultCredentials({
+  apiVersion: API_VERSIONS.V3
+  apiBaseUrl: 'https://gcp-us-east1.api.carto.com', 
+  accessToken: 'XXX',
+});
+
+function App({viewState}) {
+  const layer = new CartoLayer({
+    type: MAP_TYPES.QUERY,
+    connection: 'bigquery',
+    data: 'SELECT * FROM cartobq.testtables.points_10k',
+    pointRadiusMinPixels: 2,
+    getLineColor: [0, 0, 0, 200],
+    getFillColor: [238, 77, 90],
+    lineWidthMinPixels: 1
+  })
+
+  return <DeckGL viewState={viewState} layers={[layer]} />;
+}
+```
+
+> **CARTO Cloud Native** is currently available only in a private beta. If you want to test it, please contact us at [support@carto.com](mailto:support@carto.com?subject=Access%20to%20Cloud%20%Native%20%API%20(v3)).
+
+## Installation
+
+To install the dependencies from NPM:
+
+```bash
+npm install deck.gl
+# or
+npm install @deck.gl/core @deck.gl/layers @deck.gl/carto
+```
+
+```js
+import {CartoLayer} from '@deck.gl/carto';
+new CartoLayer({});
+```
+
+To use pre-bundled scripts:
+
+```html
+<script src="https://unpkg.com/deck.gl@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.5.0/dist.min.js"></script>
+
+<!-- or -->
+<script src="https://unpkg.com/@deck.gl/core@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/layers@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/geo-layers@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.5.0/dist.min.js"></script>
+```
+
+```js
+new deck.carto.CartoLayer({});
+```
+
+## Properties
+
+This layer allows to work with the different CARTO Maps API versions (v1, v2 and v3). When using version v1 and v2, the layer always works with vector tiles so it inherits all properties from [`MVTLayer`](/docs/api-reference/geo-layers/mvt-layer.md). When using v3, the layer works with vector tiles if the `type` property is `MAP_TYPES.TILESET` and with GeoJSON data if the `type` is `MAP_TYPES.QUERY` or `MAP_TYPES.TABLE`. When using GeoJSON data, the layer inherits all properties from [`GeoJsonLayer`](/docs/api-reference/layers/geojson-layer.md).
+
+##### `data` (String)
+
+Required. Either a SQL query or a name of dataset/tileset.
+
+##### `type` (String)
+
+Required. Data type. Possible values are:
+
+- `MAP_TYPES.QUERY`, if `data` is a SQL query. 
+- `MAP_TYPES.TILESET`, if `data` is a tileset name.
+- `MAP_TYPES.TABLE`, if `data` is a dataset name. Only supported with API v3.
+
+##### `connection` (String)
+
+Required when apiVersion is `API_VERSIONS.V3`. 
+
+Name of the connection registered in the [CARTO workspace].
+
+##### `uniqueIdProperty` (String)
+
+* Default: `cartodb_id`
+
+Optional. A string pointing to a unique attribute at the result of the query. A unique attribute is needed for highlighting with vector tiles when a feature is split across two or more tiles.
+
+##### `credentials` (Object)
+
+Optional. Overrides the configuration to connect with CARTO. Check the parameters [here](overview#carto-credentials).
+
+
+### Callbacks
+
+#### `onDataLoad` (Function, optional)
+
+`onDataLoad` is called when the request to the CARTO Maps API was completed successfully.
+
+* Default: `data => {}`
+
+Receives arguments:
+
+* `data` (Object) - Data received from CARTO Maps API
+
+##### `onDataError` (Function, optional)
+
+`onDataError` is called when the request to the CARTO Maps API failed. By default the Error is thrown.
+
+* Default: `null`
+
+Receives arguments:
+
+* `error` (`Error`)
+
+## Source
+
+[modules/carto/src/layers/carto-layer.js](https://github.com/visgl/deck.gl/tree/master/modules/carto/src/layers/carto-layer.js)

docs/api-reference/carto/carto-sql-layer.md

@@ -1,9 +1,8 @@
-
-
 # CartoSQLLayer
+>CartoSQLLayer will be deprecated in future versions. Use CartoLayer instead.  If you've existing code using this layer, check [the migration steps](#migration-to-cartolayer).
 
 `CartoSQLLayer` is a layer to visualize data hosted in your CARTO account and to apply custom SQL.
-
+ 
 ```js
 import DeckGL from '@deck.gl/react';
 import {CartoSQLLayer, setDefaultCredentials} from '@deck.gl/carto';
@@ -17,7 +16,34 @@ function App({viewState}) {
   const layer = new CartoSQLLayer({
     data: 'SELECT * FROM world_population_2015',
     pointRadiusMinPixels: 2,
-    getLineColor: [0, 0, 0, 0.75],
+    getLineColor: [0, 0, 0, 125],
+    getFillColor: [238, 77, 90],
+    lineWidthMinPixels: 1
+  })
+
+  return <DeckGL viewState={viewState} layers={[layer]} />;
+}
+```
+
+## Migration to CartoLayer
+
+To migrate from `CartoSQLLayer` to `CartoLayer` you only need to change the layer name and set `type` property to `MAP_TYPES.QUERY`:
+
+```js
+import DeckGL from '@deck.gl/react';
+import {CartoLayer, setDefaultCredentials, MAP_TYPES} from '@deck.gl/carto';
+
+setDefaultCredentials({
+  username: 'public',
+  apiKey: 'default_public'
+});
+
+function App({viewState}) {
+  const layer = new CartoLayer({
+    type: MAP_TYPES.QUERY,
+    data: 'SELECT * FROM world_population_2015',
+    pointRadiusMinPixels: 2,
+    getLineColor: [0, 0, 0, 125],
     getFillColor: [238, 77, 90],
     lineWidthMinPixels: 1
   })
@@ -44,14 +70,14 @@ new CartoSQLLayer({});
 To use pre-bundled scripts:
 
 ```html
-<script src="https://unpkg.com/deck.gl@^8.2.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/carto@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/deck.gl@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.5.0/dist.min.js"></script>
 
 <!-- or -->
-<script src="https://unpkg.com/@deck.gl/core@^8.0.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/layers@^8.2.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/geo-layers@^8.2.0/dist.min.js"></script>
-<script src="https://unpkg.com/@deck.gl/carto@^8.2.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/core@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/layers@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/geo-layers@^8.5.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/carto@^8.5.0/dist.min.js"></script>
 ```
 
 ```js
@@ -74,32 +100,9 @@ Required. Either a sql query or a name of dataset
 
 Optional. A string pointing to a unique attribute at the result of the query. A unique attribute is needed for highlighting a feature split across two or more tiles.
 
-
 ##### `credentials` (Object)
 
-Optional. Object with the credentials to connect with CARTO.
-
-* Default:
-
-```js
-{
-  username: 'public',
-  apiKey: 'default_public'
-}
-```
-
-##### `bufferSize` (Number)
-
-Optional. MVT BufferSize in tile coordinate space as defined by MVT specification
-
-* Default: `16`
-
-
-##### `tileExtent` (String)
-
-Optional. Tile extent in tile coordinate space as defined by MVT specification.
-
-* Default: `4096`
+Optional. Overrides the configuration to connect with CARTO. Check the parameters [here](overview#carto-credentials).
 
 ### Callbacks