deck.gl 与 CARTO 数据源Data Sources完全指南从 vector/h3/quadbin TableSource 到 QuerySource 的声明式取数【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl导读本文聚焦 deck.gl 的 CARTO 模块deck.gl/carto及其底层数据源函数Data Sources。这些函数是对浏览器fetch的封装让你不必手动拼接 URL 和解析响应而是用一组描述性的参数如表名、SQL 查询、连接名直接声明我要什么数据并配合 CARTO 平台的矢量瓦片、H3/Quadbin 空间索引瓦片与栅格瓦片能力进行大规模可视化。读完本文你将掌握所有数据源函数的参数语义、Promise 异步模型、内置缓存机制以及如何与VectorTileLayer、H3TileLayer、QuadbinTileLayer、HeatmapTileLayer、RasterTileLayer等 CARTO 图层无缝衔接写出可复用、可类型检查、可缓存的数据接入层。一、数据源是什么对 fetch 的一层声明式封装在 deck.gl 的 CARTO 模块总览 中CARTO 平台为 deck.gl 提供了两套协作组件CARTO 图层H3TileLayer、HeatmapTileLayer、QuadbinTileLayer、RasterTileLayer、VectorTileLayer等负责将瓦片数据渲染到屏幕上数据源函数Data Sources负责从 CARTO 平台取回数据供上述图层使用。数据源函数位于carto/api-client包中而deck.gl/carto模块会在其入口文件 modules/carto/src/index.ts 中统一 re-export因此你可以直接从deck.gl/carto导入import {vectorTableSource} from carto/api-client; // 或 import {vectorTableSource} from deck.gl/carto;从 源码 可以看到deck.gl/carto除了 re-export 数据源函数外还 re-export 了query直接 SQL 查询、CartoAPIError错误类型与SOURCE_DEFAULTS默认配置常量方便上层应用统一引用。从概念上讲这些函数可以被视为浏览器fetch的包装器——只不过你不传 URL而是传一组描述 CARTO 数据的选项。数据源函数会负责构造正确的 CARTO API 请求包括 Maps API 的瓦片清单请求并返回一个可直接交给 deck.gl 图层data属性的结果对象。一个最简单的示例——从数据仓库连接carto_dw中获取一张表import {vectorTableSource} from carto/api-client; const data vectorTableSource({ accessToken: XXX, connectionName: carto_dw, tableName: carto-demo-data.demo_tables.chicago_crime_sample });这里tableName使用 CARTO 平台的三段式命名空间project.dataset.table/database.schema.table数据本身仍然托管在你的云数据仓库Google BigQuery、Amazon Redshift、Snowflake、Databricks 或 PostgreSQL 兼容数据库中无需迁移到 CARTO。二、Promise API把 Promise 直接交给 data 属性所有数据源函数都返回一个Promise。这个 Promise 可以 resolve 为实际的Tilejson结果即TilejsonResult类型包含瓦片 URL 模板、瓦片方案、元数据等信息的瓦片清单。但更重要的是deck.gl 核心图层的data属性本身支持 Promise见 Layer 文档 中的 data 属性说明因此通常你不需要手动 await 或 resolve直接把这个 Promise 传给data即可框架会自动处理异步解析与图层重绘import {H3TileLayer} from deck.gl/carto; import {h3TilesetSource} from carto/api-client; new H3TileLayer({ data: h3TilesetSource({ accessToken: XXX, connectionName: carto_dw, tableName: carto-demo-data.demo_tables.h3_data }), getFillColor: d d.properties.color });这种声明式 Promise的用法让代码极其简洁你描述数据在哪剩下的解析、失败处理、重新加载都由 deck.gl 与数据源函数协作完成。以H3TileLayer为例其data属性要求一个合法的TilejsonResult官方文档明确推荐用 h3TableSource、h3QuerySource、h3TilesetSource三个数据源之一来获取见 H3TileLayer 文档同理VectorTileLayer 推荐配合vectorTableSource、vectorQuerySource、vectorTilesetSource使用。三、类型系统全部函数均带完整 TypeScript 类型所有数据源函数都是完全类型化的参数对象有精确的 option 类型定义返回值有精确的结果类型。这意味着在 TypeScript 项目中传入错误的参数名、拼错表名选项会得到编译期报错编辑器会给出完整的参数提示与补全返回值类型如TilejsonResult会被正确推断传递给图层的data属性时类型安全。deck.gl/carto的入口文件 modules/carto/src/index.ts 中同样 re-export 了全部相关类型SourceOptions、VectorTableSourceOptions、VectorQuerySourceOptions、H3TableSourceOptions、QuadbinTableSourceOptions、BoundaryTableSourceOptions、QueryParameters等方便统一从一处导入。四、内置缓存放心在 render() 里使用数据源函数内部实现了一个缓存机制只要传给函数的参数没有变化它就不会再次向服务器发起请求而是直接返回缓存的 Promise 结果。这一设计带来的直接收益是你可以在 React 的render()函数、Vue 的 computed 属性、或其他高频调用的代码路径中直接调用数据源函数而无需手动 memoization。即使组件因为无关的 state 变化而反复重渲染只要数据源参数表名、SQL、连接名等不变网络请求就只会发生一次。值得注意的是判断缓存命中的依据是参数是否改变因此实践中建议将稳定不变的数据源调用放在模块顶层或useMemo/useCallback中让同一组参数对应同一个缓存条目需要强制刷新数据时改变某个参数如追加一个版本号或时间戳字段以触发缓存失效。五、全局选项 SourceOptions所有数据源函数都接受一组全局选项global options类型定义如下type SourceOptions { accessToken: string; connectionName: string; apiBaseUrl?: string; clientId?: string; headers?: Recordstring, string; maxLengthURL?: number; };各字段说明字段必填说明accessToken是用于向 CARTO API 认证/授权请求的令牌。CARTO 平台使用不同的认证方法签发令牌详见 CARTO 模块总览 的 Authentication 一节connectionName是在 CARTO 平台中配置的连接名称。连接connection定义了 CARTO 与你云数据仓库BigQuery、Redshift、Snowflake、Databricks、PostgreSQL 兼容数据库等之间的集成apiBaseUrl否CARTO API 的基础 URL用于覆盖默认的 API 端点例如在自托管或不同环境/区域部署时使用clientId否客户端标识符CARTO 平台用于识别应用来源headers否附加的 HTTP 请求头以Recordstring, string形式传入会随请求一并发送maxLengthURL否URL 最大长度阈值。当请求 URL 超过该长度时数据源会改用 POST 方式提交请求例如承载较长 SQL 查询的场景六、全部数据源函数详解数据源按取数形式分为两类TableSource按表名取数如vectorTableSource、h3TableSource、quadbinTableSourceQuerySource按SQL 查询取数如vectorQuerySource、h3QuerySource、quadbinQuerySourceTilesetSource按现有瓦片集取数表内数据已按空间索引预聚合为瓦片集。下面逐一列出各函数专属的参数类型。除专属参数外每个函数都接受上一节的全局SourceOptions。6.1 vectorTableSource —— 矢量表数据源type VectorTableSourceOptions { columns?: string[]; spatialDataColumn?: string; tableName: string; aggregationExp?: string; };参数必填说明tableName是数据表名使用三段式命名空间columns否需要返回的列名数组用于裁剪传输的数据量spatialDataColumn否空间数据列名。默认情况下数据源会自动探测空间列如geom、geography、h3、quadbin等当表中有多个空间列或需要显式指定时使用aggregationExp否聚合表达式。用于在服务器端按空间索引进行预聚合例如SUM(value)减少下传数据量返回结果可直接传给 VectorTileLayer 的data属性。6.2 vectorQuerySource —— 矢量 SQL 查询数据源type VectorQuerySourceOptions { spatialDataColumn?: string; sqlQuery: string; queryParameters: QueryParameters; aggregationExp?: string; };参数必填说明sqlQuery是要执行的 SQL 查询语句直接在你的数据仓库上执行queryParameters是SQL 查询参数占位符绑定值具体格式取决于数据仓库 provider见下文第七节spatialDataColumn否同上显式指定空间列aggregationExp否同上服务器端预聚合表达式6.3 vectorTilesetSource —— 矢量瓦片集数据源type VectorTilesetSourceOptions { tableName: string; };适用于表中数据已经以矢量瓦片集tileset形式组织好的场景只需指定tableName即可。6.4 h3TableSource —— H3 索引表数据源type H3TableSourceOptions { aggregationExp: string; aggregationResLevel?: number; columns?: string[]; spatialDataColumn?: string; tableName: string; };参数必填说明tableName是数据表名aggregationExp是聚合表达式如SUM(population)因为 H3 表在取数时需要按 H3 单元做聚合aggregationResLevel否H3 聚合分辨率级别指定聚合到哪一级 H3 网格columns否返回列数组spatialDataColumn否空间列名默认探测通常是 H3 索引列返回结果可用于 H3TileLayer。6.5 h3QuerySource —— H3 索引 SQL 查询数据源type H3QuerySourceOptions { aggregationExp: string; aggregationResLevel?: number; spatialDataColumn?: string; sqlQuery: string; queryParameters: QueryParameters; };与h3TableSource类似但数据来源是 SQL 查询而非表名。aggregationExp必填queryParameters用于绑定 SQL 占位符。6.6 h3TilesetSource —— H3 瓦片集数据源type H3TilesetSourceOptions { tableName: string; };数据已按 H3 空间索引组织为瓦片集时使用仅需表名。6.7 quadbinTableSource —— Quadbin 索引表数据源type QuadbinTableSourceOptions { aggregationExp: string; aggregationResLevel?: number; columns?: string[]; spatialDataColumn?: string; tableName: string; };与h3TableSource结构一致但面向Quadbin四叉树二进制空间索引编码的数据适用于 QuadbinTileLayer。6.8 quadbinQuerySource —— Quadbin 索引 SQL 查询数据源type QuadbinQuerySourceOptions { aggregationExp: string; aggregationResLevel?: number; spatialDataColumn?: string; sqlQuery: string; queryParameters: QueryParameters; };6.9 quadbinTilesetSource —— Quadbin 瓦片集数据源type QuadbinTilesetSourceOptions { tableName: string; };6.10 rasterSource —— 栅格数据源type RasterSourceOptions { tableName: string; };面向栅格Raster数据适用于 RasterTileLayer。栅格数据通常由 CARTO 平台预先生成瓦片因此只需表名。6.11 Boundary 数据源边界数据源Boundary 数据源是一类特殊的数据源其tileset与properties两个属性都需要特定的 schema才能正常工作用于几何边界 属性分离的应用场景例如行政区划边界瓦片 单独的属性表。关于 Boundaries 的完整用法CARTO 平台有专门的开发者指南见 Boundaries 指南。boundaryTableSourcetype BoundaryTableSourceOptions { tilesetTableName: string; columns?: string[]; propertiesTableName: string; };参数必填说明tilesetTableName是边界几何瓦片集表名propertiesTableName是属性数据表名与边界通过唯一 ID 关联columns否属性列数组boundaryQuerySourcetype BoundaryQuerySourceOptions { tilesetTableName: string; propertiesSqlQuery: string; queryParameters?: QueryParameters; };参数必填说明tilesetTableName是边界几何瓦片集表名propertiesSqlQuery是用于查询属性数据的 SQLqueryParameters否SQL 查询参数可选七、QueryParameters按 provider 绑定的 SQL 参数QueryParameters用于给 SQL 查询中的占位符绑定值。具体格式取决于数据源所连接的数据仓库 provider两者必须匹配否则查询会失败。官方文档给出了以下各 provider 的示例PostgreSQL 与 Redshift位置参数$1vectorQuerySource({ // ... 全局选项 sqlQuery: select * from users where username$1, queryParameters: [my-name] })BigQuery 位置参数$1vectorQuerySource({ // ... 全局选项 sqlQuery: select * from users where username$1, queryParameters: [my-name] })BigQuery 命名参数usernamevectorQuerySource({ // ... 全局选项 sqlQuery: select * from users where usernameusername, queryParameters: { username: my-name } })Snowflake 位置参数?vectorQuerySource({ // ... 全局选项 sqlQuery: select * from users where username?, queryParameters: [my-name] });Snowflake 也支持编号占位符:1vectorQuerySource({ // 注意此处使用 data 键传入查询语句 data: select * from users where username:1, queryParameters: [my-name] });DatabricksODBC?vectorQuerySource({ // ... 全局选项 data: select * from users where username?, queryParameters: [my-name] });注意官方文档中 Snowflake 与 Databricks 示例使用了data键而非sqlQuery键来传入查询语句。实践中请以你使用的carto/api-client版本实际导出的类型定义为准VectorQuerySourceOptions的标准字段是sqlQuery。八、与 CARTO 图层的组合实战将数据源与 CARTO 图层组合是官方推荐的标准模式。下面是一个完整的 React 组合示例综合 总览 与 VectorTileLayer 文档import {DeckGL} from deck.gl/react; import {VectorTileLayer} from deck.gl/carto; import {vectorQuerySource} from carto/api-client; function App() { const data vectorQuerySource({ accessToken: XXX, connectionName: carto_dw, sqlQuery: SELECT * FROM cartobq.testtables.points_10k, }); const layer new VectorTileLayer({ data, pointRadiusMinPixels: 2, getLineColor: [0, 0, 0, 200], getFillColor: [238, 77, 90], lineWidthMinPixels: 1 }); return DeckGL layers{[layer]} /; }各图层的推荐数据源对照CARTO 图层推荐数据源VectorTileLayervectorTableSource、vectorQuerySource、vectorTilesetSourceH3TileLayerh3TableSource、h3QuerySource、h3TilesetSourceQuadbinTileLayerquadbinTableSource、quadbinQuerySource、quadbinTilesetSourceHeatmapTileLayer基于 SQL/表的 H3 聚合类数据源RasterTileLayerrasterSource从 modules/carto/src/layers 目录的源码结构看这些图层背后共享一套瓦片基础设施例如spatial-index-tile-layer.ts继承了 deck.gl 的TileLayer为 H3/Quadbin 空间索引瓦片提供按要素高亮auto-highlight能力见 modules/carto/src/layers/spatial-index-tile-layer.ts并注册了 CARTO 的空间瓦片加载器CartoSpatialTileLoader见同文件 第 5-8 行。数据源函数产生的TilejsonResult正是驱动这套瓦片加载管线的入口。安装依赖npm install deck.gl # 或按需安装各模块 npm install deck.gl/core deck.gl/layers deck.gl/geo-layers deck.gl/carto数据源函数来自carto/api-client包它作为deck.gl/carto的依赖被自动安装见 modules/carto/package.json因此你既可以import {vectorTableSource} from deck.gl/carto也可以显式安装后从carto/api-client导入。九、与 query 函数的区别如果你不需要瓦片化渲染而只想直接拿数据例如与 deck.gl 的其他通用图层如ScatterplotLayer、GeoJsonLayer配合CARTO 模块还提供query()函数它直接调用 CARTO SQL API 返回行数据配合dataTransform使用import {DeckGL} from deck.gl/react; import {query} from deck.gl/carto; function App() { const data query({ accessToken: XXX, connectionName: carto_dw, sqlQuery: SELECT * FROM cartobq.testtables.points_10k, }); const layer new ScatterplotLayer({ data, dataTransform: data data.rows, getPosition: d d.geom.coordinates, getRadius: d d.size }); return DeckGL layers{[layer]} /; }选择建议数据量小、需要直接使用原始行数据、或与 CARTO 瓦片图层外的通用图层集成时用query数据量大、追求性能与可伸缩性时使用本数据源函数 对应的瓦片图层CARTO 以瓦片方式提供数据正是为了突破浏览器内存限制见 CARTO 模块总览。十、最佳实践小结能传 Promise 就不手动 awaitdeck.gl 的data属性原生支持 Promise直接传递数据源返回值即可。利用内置缓存把参数稳定不变的数据源调用放在渲染路径中无需额外 memo框架会缓存结果。正确选择空间索引数据已按 H3/Quadbin 组织则用对应的 Table/Tileset 源需要动态聚合则配合aggregationExp与aggregationResLevel在服务器端预聚合显著降低传输与渲染压力。匹配 provider 的占位符语法QueryParameters的绑定语法必须与底层数据仓库一致$1、name、?、:1否则 SQL 无法正确执行。善用类型全部数据源函数与选项均为 TypeScript 类型化在 IDE 中可获得完整的参数提示与校验。长查询注意maxLengthURL当 SQL 很长导致 URL 超限时配置maxLengthURL让请求自动切换为 POST 方式。围绕这套数据源 API你可以用极少的样板代码把 deck.gl 与 CARTO 平台的云数仓数据打通构建面向海量空间数据的高性能 Web 可视化应用。【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 deck.gl 与 CARTO 数据源（Data Sources）完全指南：从 vector/h3/quadbin TableSource 到 QuerySource 的声明式取数
deck.gl 与 CARTO 数据源Data Sources完全指南从 vector/h3/quadbin TableSource 到 QuerySource 的声明式取数【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl导读本文聚焦 deck.gl 的 CARTO 模块deck.gl/carto及其底层数据源函数Data Sources。这些函数是对浏览器fetch的封装让你不必手动拼接 URL 和解析响应而是用一组描述性的参数如表名、SQL 查询、连接名直接声明我要什么数据并配合 CARTO 平台的矢量瓦片、H3/Quadbin 空间索引瓦片与栅格瓦片能力进行大规模可视化。读完本文你将掌握所有数据源函数的参数语义、Promise 异步模型、内置缓存机制以及如何与VectorTileLayer、H3TileLayer、QuadbinTileLayer、HeatmapTileLayer、RasterTileLayer等 CARTO 图层无缝衔接写出可复用、可类型检查、可缓存的数据接入层。一、数据源是什么对 fetch 的一层声明式封装在 deck.gl 的 CARTO 模块总览 中CARTO 平台为 deck.gl 提供了两套协作组件CARTO 图层H3TileLayer、HeatmapTileLayer、QuadbinTileLayer、RasterTileLayer、VectorTileLayer等负责将瓦片数据渲染到屏幕上数据源函数Data Sources负责从 CARTO 平台取回数据供上述图层使用。数据源函数位于carto/api-client包中而deck.gl/carto模块会在其入口文件 modules/carto/src/index.ts 中统一 re-export因此你可以直接从deck.gl/carto导入import {vectorTableSource} from carto/api-client; // 或 import {vectorTableSource} from deck.gl/carto;从 源码 可以看到deck.gl/carto除了 re-export 数据源函数外还 re-export 了query直接 SQL 查询、CartoAPIError错误类型与SOURCE_DEFAULTS默认配置常量方便上层应用统一引用。从概念上讲这些函数可以被视为浏览器fetch的包装器——只不过你不传 URL而是传一组描述 CARTO 数据的选项。数据源函数会负责构造正确的 CARTO API 请求包括 Maps API 的瓦片清单请求并返回一个可直接交给 deck.gl 图层data属性的结果对象。一个最简单的示例——从数据仓库连接carto_dw中获取一张表import {vectorTableSource} from carto/api-client; const data vectorTableSource({ accessToken: XXX, connectionName: carto_dw, tableName: carto-demo-data.demo_tables.chicago_crime_sample });这里tableName使用 CARTO 平台的三段式命名空间project.dataset.table/database.schema.table数据本身仍然托管在你的云数据仓库Google BigQuery、Amazon Redshift、Snowflake、Databricks 或 PostgreSQL 兼容数据库中无需迁移到 CARTO。二、Promise API把 Promise 直接交给 data 属性所有数据源函数都返回一个Promise。这个 Promise 可以 resolve 为实际的Tilejson结果即TilejsonResult类型包含瓦片 URL 模板、瓦片方案、元数据等信息的瓦片清单。但更重要的是deck.gl 核心图层的data属性本身支持 Promise见 Layer 文档 中的 data 属性说明因此通常你不需要手动 await 或 resolve直接把这个 Promise 传给data即可框架会自动处理异步解析与图层重绘import {H3TileLayer} from deck.gl/carto; import {h3TilesetSource} from carto/api-client; new H3TileLayer({ data: h3TilesetSource({ accessToken: XXX, connectionName: carto_dw, tableName: carto-demo-data.demo_tables.h3_data }), getFillColor: d d.properties.color });这种声明式 Promise的用法让代码极其简洁你描述数据在哪剩下的解析、失败处理、重新加载都由 deck.gl 与数据源函数协作完成。以H3TileLayer为例其data属性要求一个合法的TilejsonResult官方文档明确推荐用 h3TableSource、h3QuerySource、h3TilesetSource三个数据源之一来获取见 H3TileLayer 文档同理VectorTileLayer 推荐配合vectorTableSource、vectorQuerySource、vectorTilesetSource使用。三、类型系统全部函数均带完整 TypeScript 类型所有数据源函数都是完全类型化的参数对象有精确的 option 类型定义返回值有精确的结果类型。这意味着在 TypeScript 项目中传入错误的参数名、拼错表名选项会得到编译期报错编辑器会给出完整的参数提示与补全返回值类型如TilejsonResult会被正确推断传递给图层的data属性时类型安全。deck.gl/carto的入口文件 modules/carto/src/index.ts 中同样 re-export 了全部相关类型SourceOptions、VectorTableSourceOptions、VectorQuerySourceOptions、H3TableSourceOptions、QuadbinTableSourceOptions、BoundaryTableSourceOptions、QueryParameters等方便统一从一处导入。四、内置缓存放心在 render() 里使用数据源函数内部实现了一个缓存机制只要传给函数的参数没有变化它就不会再次向服务器发起请求而是直接返回缓存的 Promise 结果。这一设计带来的直接收益是你可以在 React 的render()函数、Vue 的 computed 属性、或其他高频调用的代码路径中直接调用数据源函数而无需手动 memoization。即使组件因为无关的 state 变化而反复重渲染只要数据源参数表名、SQL、连接名等不变网络请求就只会发生一次。值得注意的是判断缓存命中的依据是参数是否改变因此实践中建议将稳定不变的数据源调用放在模块顶层或useMemo/useCallback中让同一组参数对应同一个缓存条目需要强制刷新数据时改变某个参数如追加一个版本号或时间戳字段以触发缓存失效。五、全局选项 SourceOptions所有数据源函数都接受一组全局选项global options类型定义如下type SourceOptions { accessToken: string; connectionName: string; apiBaseUrl?: string; clientId?: string; headers?: Recordstring, string; maxLengthURL?: number; };各字段说明字段必填说明accessToken是用于向 CARTO API 认证/授权请求的令牌。CARTO 平台使用不同的认证方法签发令牌详见 CARTO 模块总览 的 Authentication 一节connectionName是在 CARTO 平台中配置的连接名称。连接connection定义了 CARTO 与你云数据仓库BigQuery、Redshift、Snowflake、Databricks、PostgreSQL 兼容数据库等之间的集成apiBaseUrl否CARTO API 的基础 URL用于覆盖默认的 API 端点例如在自托管或不同环境/区域部署时使用clientId否客户端标识符CARTO 平台用于识别应用来源headers否附加的 HTTP 请求头以Recordstring, string形式传入会随请求一并发送maxLengthURL否URL 最大长度阈值。当请求 URL 超过该长度时数据源会改用 POST 方式提交请求例如承载较长 SQL 查询的场景六、全部数据源函数详解数据源按取数形式分为两类TableSource按表名取数如vectorTableSource、h3TableSource、quadbinTableSourceQuerySource按SQL 查询取数如vectorQuerySource、h3QuerySource、quadbinQuerySourceTilesetSource按现有瓦片集取数表内数据已按空间索引预聚合为瓦片集。下面逐一列出各函数专属的参数类型。除专属参数外每个函数都接受上一节的全局SourceOptions。6.1 vectorTableSource —— 矢量表数据源type VectorTableSourceOptions { columns?: string[]; spatialDataColumn?: string; tableName: string; aggregationExp?: string; };参数必填说明tableName是数据表名使用三段式命名空间columns否需要返回的列名数组用于裁剪传输的数据量spatialDataColumn否空间数据列名。默认情况下数据源会自动探测空间列如geom、geography、h3、quadbin等当表中有多个空间列或需要显式指定时使用aggregationExp否聚合表达式。用于在服务器端按空间索引进行预聚合例如SUM(value)减少下传数据量返回结果可直接传给 VectorTileLayer 的data属性。6.2 vectorQuerySource —— 矢量 SQL 查询数据源type VectorQuerySourceOptions { spatialDataColumn?: string; sqlQuery: string; queryParameters: QueryParameters; aggregationExp?: string; };参数必填说明sqlQuery是要执行的 SQL 查询语句直接在你的数据仓库上执行queryParameters是SQL 查询参数占位符绑定值具体格式取决于数据仓库 provider见下文第七节spatialDataColumn否同上显式指定空间列aggregationExp否同上服务器端预聚合表达式6.3 vectorTilesetSource —— 矢量瓦片集数据源type VectorTilesetSourceOptions { tableName: string; };适用于表中数据已经以矢量瓦片集tileset形式组织好的场景只需指定tableName即可。6.4 h3TableSource —— H3 索引表数据源type H3TableSourceOptions { aggregationExp: string; aggregationResLevel?: number; columns?: string[]; spatialDataColumn?: string; tableName: string; };参数必填说明tableName是数据表名aggregationExp是聚合表达式如SUM(population)因为 H3 表在取数时需要按 H3 单元做聚合aggregationResLevel否H3 聚合分辨率级别指定聚合到哪一级 H3 网格columns否返回列数组spatialDataColumn否空间列名默认探测通常是 H3 索引列返回结果可用于 H3TileLayer。6.5 h3QuerySource —— H3 索引 SQL 查询数据源type H3QuerySourceOptions { aggregationExp: string; aggregationResLevel?: number; spatialDataColumn?: string; sqlQuery: string; queryParameters: QueryParameters; };与h3TableSource类似但数据来源是 SQL 查询而非表名。aggregationExp必填queryParameters用于绑定 SQL 占位符。6.6 h3TilesetSource —— H3 瓦片集数据源type H3TilesetSourceOptions { tableName: string; };数据已按 H3 空间索引组织为瓦片集时使用仅需表名。6.7 quadbinTableSource —— Quadbin 索引表数据源type QuadbinTableSourceOptions { aggregationExp: string; aggregationResLevel?: number; columns?: string[]; spatialDataColumn?: string; tableName: string; };与h3TableSource结构一致但面向Quadbin四叉树二进制空间索引编码的数据适用于 QuadbinTileLayer。6.8 quadbinQuerySource —— Quadbin 索引 SQL 查询数据源type QuadbinQuerySourceOptions { aggregationExp: string; aggregationResLevel?: number; spatialDataColumn?: string; sqlQuery: string; queryParameters: QueryParameters; };6.9 quadbinTilesetSource —— Quadbin 瓦片集数据源type QuadbinTilesetSourceOptions { tableName: string; };6.10 rasterSource —— 栅格数据源type RasterSourceOptions { tableName: string; };面向栅格Raster数据适用于 RasterTileLayer。栅格数据通常由 CARTO 平台预先生成瓦片因此只需表名。6.11 Boundary 数据源边界数据源Boundary 数据源是一类特殊的数据源其tileset与properties两个属性都需要特定的 schema才能正常工作用于几何边界 属性分离的应用场景例如行政区划边界瓦片 单独的属性表。关于 Boundaries 的完整用法CARTO 平台有专门的开发者指南见 Boundaries 指南。boundaryTableSourcetype BoundaryTableSourceOptions { tilesetTableName: string; columns?: string[]; propertiesTableName: string; };参数必填说明tilesetTableName是边界几何瓦片集表名propertiesTableName是属性数据表名与边界通过唯一 ID 关联columns否属性列数组boundaryQuerySourcetype BoundaryQuerySourceOptions { tilesetTableName: string; propertiesSqlQuery: string; queryParameters?: QueryParameters; };参数必填说明tilesetTableName是边界几何瓦片集表名propertiesSqlQuery是用于查询属性数据的 SQLqueryParameters否SQL 查询参数可选七、QueryParameters按 provider 绑定的 SQL 参数QueryParameters用于给 SQL 查询中的占位符绑定值。具体格式取决于数据源所连接的数据仓库 provider两者必须匹配否则查询会失败。官方文档给出了以下各 provider 的示例PostgreSQL 与 Redshift位置参数$1vectorQuerySource({ // ... 全局选项 sqlQuery: select * from users where username$1, queryParameters: [my-name] })BigQuery 位置参数$1vectorQuerySource({ // ... 全局选项 sqlQuery: select * from users where username$1, queryParameters: [my-name] })BigQuery 命名参数usernamevectorQuerySource({ // ... 全局选项 sqlQuery: select * from users where usernameusername, queryParameters: { username: my-name } })Snowflake 位置参数?vectorQuerySource({ // ... 全局选项 sqlQuery: select * from users where username?, queryParameters: [my-name] });Snowflake 也支持编号占位符:1vectorQuerySource({ // 注意此处使用 data 键传入查询语句 data: select * from users where username:1, queryParameters: [my-name] });DatabricksODBC?vectorQuerySource({ // ... 全局选项 data: select * from users where username?, queryParameters: [my-name] });注意官方文档中 Snowflake 与 Databricks 示例使用了data键而非sqlQuery键来传入查询语句。实践中请以你使用的carto/api-client版本实际导出的类型定义为准VectorQuerySourceOptions的标准字段是sqlQuery。八、与 CARTO 图层的组合实战将数据源与 CARTO 图层组合是官方推荐的标准模式。下面是一个完整的 React 组合示例综合 总览 与 VectorTileLayer 文档import {DeckGL} from deck.gl/react; import {VectorTileLayer} from deck.gl/carto; import {vectorQuerySource} from carto/api-client; function App() { const data vectorQuerySource({ accessToken: XXX, connectionName: carto_dw, sqlQuery: SELECT * FROM cartobq.testtables.points_10k, }); const layer new VectorTileLayer({ data, pointRadiusMinPixels: 2, getLineColor: [0, 0, 0, 200], getFillColor: [238, 77, 90], lineWidthMinPixels: 1 }); return DeckGL layers{[layer]} /; }各图层的推荐数据源对照CARTO 图层推荐数据源VectorTileLayervectorTableSource、vectorQuerySource、vectorTilesetSourceH3TileLayerh3TableSource、h3QuerySource、h3TilesetSourceQuadbinTileLayerquadbinTableSource、quadbinQuerySource、quadbinTilesetSourceHeatmapTileLayer基于 SQL/表的 H3 聚合类数据源RasterTileLayerrasterSource从 modules/carto/src/layers 目录的源码结构看这些图层背后共享一套瓦片基础设施例如spatial-index-tile-layer.ts继承了 deck.gl 的TileLayer为 H3/Quadbin 空间索引瓦片提供按要素高亮auto-highlight能力见 modules/carto/src/layers/spatial-index-tile-layer.ts并注册了 CARTO 的空间瓦片加载器CartoSpatialTileLoader见同文件 第 5-8 行。数据源函数产生的TilejsonResult正是驱动这套瓦片加载管线的入口。安装依赖npm install deck.gl # 或按需安装各模块 npm install deck.gl/core deck.gl/layers deck.gl/geo-layers deck.gl/carto数据源函数来自carto/api-client包它作为deck.gl/carto的依赖被自动安装见 modules/carto/package.json因此你既可以import {vectorTableSource} from deck.gl/carto也可以显式安装后从carto/api-client导入。九、与 query 函数的区别如果你不需要瓦片化渲染而只想直接拿数据例如与 deck.gl 的其他通用图层如ScatterplotLayer、GeoJsonLayer配合CARTO 模块还提供query()函数它直接调用 CARTO SQL API 返回行数据配合dataTransform使用import {DeckGL} from deck.gl/react; import {query} from deck.gl/carto; function App() { const data query({ accessToken: XXX, connectionName: carto_dw, sqlQuery: SELECT * FROM cartobq.testtables.points_10k, }); const layer new ScatterplotLayer({ data, dataTransform: data data.rows, getPosition: d d.geom.coordinates, getRadius: d d.size }); return DeckGL layers{[layer]} /; }选择建议数据量小、需要直接使用原始行数据、或与 CARTO 瓦片图层外的通用图层集成时用query数据量大、追求性能与可伸缩性时使用本数据源函数 对应的瓦片图层CARTO 以瓦片方式提供数据正是为了突破浏览器内存限制见 CARTO 模块总览。十、最佳实践小结能传 Promise 就不手动 awaitdeck.gl 的data属性原生支持 Promise直接传递数据源返回值即可。利用内置缓存把参数稳定不变的数据源调用放在渲染路径中无需额外 memo框架会缓存结果。正确选择空间索引数据已按 H3/Quadbin 组织则用对应的 Table/Tileset 源需要动态聚合则配合aggregationExp与aggregationResLevel在服务器端预聚合显著降低传输与渲染压力。匹配 provider 的占位符语法QueryParameters的绑定语法必须与底层数据仓库一致$1、name、?、:1否则 SQL 无法正确执行。善用类型全部数据源函数与选项均为 TypeScript 类型化在 IDE 中可获得完整的参数提示与校验。长查询注意maxLengthURL当 SQL 很长导致 URL 超限时配置maxLengthURL让请求自动切换为 POST 方式。围绕这套数据源 API你可以用极少的样板代码把 deck.gl 与 CARTO 平台的云数仓数据打通构建面向海量空间数据的高性能 Web 可视化应用。【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考