Semantic model
A semantic model is a structured layer of business meaning over the data sources on your map. It tells an AI Agent what your tables and columns mean, how your datasets relate, how your metrics are calculated, and how your spatial data is structured, so the Agent writes correct SQL and applies your definitions consistently.
It builds on Apache Ossie, the open standard for describing what data means, extended by CARTO with spatial context.
Creating a semantic model
There are three ways to add a semantic model when configuring an AI Agent:
Write or edit it directly. The Agent Configuration dialog includes a built-in editor where you define datasets, fields, metrics, relationships, and spatial context, following the Apache Ossie structure.
Import a YAML file. Bring in an existing Ossie-based semantic model as YAML.
Let the Agent Config Assistant build or edit it. Describe your data in plain language and the Assistant writes or updates the semantic model for you.
Whichever way you choose, CARTO validates that the model is well-formed YAML.
Semantic model structure
A semantic model is YAML. It declares a version and a semantic_model list, and each entry describes:
Datasets and their fields — the tables and columns on your map, with plain-language meaning.
Relationships — how datasets join.
Metrics — reusable calculations the Agent applies consistently, so the same question returns the same answer.
These follow the Apache Ossie standard; see the Apache Ossie documentation for the full field reference. The example below shows them in context.
An Ossie relationship joins two datasets on matching column values, like a shared ID. Some spatial joins have no shared column, for example towers within 10 km of a fire, or points inside a polygon. Ossie cannot express that geometric condition, so describe the spatial join in the relationship's ai_context (for example, "join with ST_DWITHIN within 10 km") and the Agent uses it when writing the query.
The CARTO spatial extension
The only CARTO-specific part of the model is a field-level custom_extensions entry with vendor_name: CARTO, added only on fields that carry spatial data. Non-spatial fields carry no extension. Its data value is a string containing serialized JSON with a single spatial_data object.
type (required) — the kind of spatial data in the field:
point,line,polygon— vector geometries.raster— raster data.spatial_index— an H3 or Quadbin index column.
srid — the EPSG code of the coordinate system, for example 4326 (WGS84). Include it for geometry types (point, line, polygon, raster). Not used for spatial_index.
geography — include it only when the field is a nested geographic level in an administrative hierarchy (for example country → state → county). Do not add it to per-feature geometry such as a store point, an event path, or a route.
level— the name of this level, for examplecensus_block_group.hierarchy.parent— the adjacent coarser level, for examplecensus_tract.hierarchy.children— the adjacent finer levels, for example["census_block"].
spatial_index (required when type is spatial_index):
system—h3orquadbin.resolution— the index resolution as an integer (for example8). Include it only when you know it; do not guess.hierarchy— optional, the adjacent roll-up resolutions as integers, for example{ "parent": 7, "children": [9] }for an H3 resolution-8 cell.
Examples
data is always a string containing serialized JSON, not a nested YAML object. Quote the whole object.
Semantic model example
A model with two datasets: census block group polygons and the same demographics on an H3 grid. Note the field-level CARTO spatial_data extension on the spatial fields, and the population-weighted metric.
Last updated
Was this helpful?