# LGND Embeddings This extension integrates the [**LGND AI Embeddings API**](https://embeddings.api.lgnd.ai/v1/reference#tag/search) into CARTO Workflows, enabling satellite imagery search and analysis powered by geospatial foundational models (GEOFMs). It exposes the LGND catalog of pre-computed embeddings as Workflows components, so you can find similar locations, detect changes over time, or browse coverage in a given area — directly inside a Workflows pipeline. {% hint style="info" %} Most components require a valid LGND AI account and three credentials: a **Tenant ID** (`ten_...`), a **Collection ID** (`col_...`) and an **API Token** (`sk_...`). You can list the tenant–collection pairs available to your account with the [LGND Catalog Browser](#lgnd-catalog-browser) component. See the [LGND Embeddings API reference](https://embeddings.api.lgnd.ai/v1/reference#tag/search) for additional details. This extension is available for the **BigQuery** connector. {% endhint %} ## LGND Catalog Browser **Description** Lists all tenant–collection pairs available to the authenticated LGND account. Use this component to discover which `tenant_id` and `collection_id` values to plug into the rest of the LGND components. **Settings** * **API Token:** Your LGND API authentication token (`sk_...`). **Output** * **Output table:** One row per collection, across all tenants accessible by the token. Includes `tenant_id`, `tenant_name`, `collection_id`, `collection_name`, `collection_status` (`QUEUED`, `PROCESSING`, `READY` or `FAILED`), `start_date`, `end_date`, `model_name` (e.g. `clay-v1.5`) and `imagery_source` (e.g. `naip`, `sentinel-2-l2a`). Only collections with status `READY` can be used as inputs to the other LGND components. ## LGND Text Search **Description** Performs a similarity search using a natural language text query. The query is converted to an embedding by LGND and matched against the chip embeddings in the selected collection. The top results are returned ordered by similarity. Optionally, you can constrain the search by date range, by a spatial filter, and by providing positive and/or negative example chips to steer the embedding. **Inputs** * **Geometry Filter** *(optional)*: A table containing a single Polygon or MultiPolygon used to restrict results to chips intersecting that geometry. * **Positive Examples** *(optional)*: A table containing chip IDs whose embeddings should be used as positive examples (the search will be pulled towards these). * **Negative Examples** *(optional)*: A table containing chip IDs whose embeddings should be used as negative examples (the search will be pushed away from these). **Settings** * **Tenant ID:** Your LGND tenant identifier (`ten_...`). * **Collection ID:** The collection to search (`col_...`). * **API Token:** Your LGND API authentication token (`sk_...`). * **Natural Language Query:** Text describing what to search for, e.g. `construction site with heavy machinery`. * **Top K:** Number of results to return. Between 1 and 100. Default: 10. * **Start Date** *(optional)*: Only consider imagery captured on or after this date (`YYYY-MM-DD`). * **End Date** *(optional)*: Only consider imagery captured on or before this date (`YYYY-MM-DD`). * **Geometry Column** *(optional)*: Geography column in the Geometry Filter table. * **Positive Chip ID Column** *(optional)*: Column in the Positive Examples table containing the chip IDs. * **Negative Chip ID Column** *(optional)*: Column in the Negative Examples table containing the chip IDs. **Output** * **Output table:** The chips ranked by similarity score. Each row contains `chip_id`, `raster_id`, `cell_id`, `datetime`, `score` (higher = more similar), `distance` (cosine distance, lower = more similar), `collection`, `centroid` and `geometry`. ## LGND Chip Search **Description** Performs a similarity search using an existing chip's embedding as the query vector. Use this to find locations that look similar to a chip you already know — for example, the top result of a previous Text Search or Location Search. **Inputs** * **Geometry Filter** *(optional)*: A table containing a single Polygon or MultiPolygon used to restrict results to chips intersecting that geometry. **Settings** * **Tenant ID:** Your LGND tenant identifier (`ten_...`). * **Collection ID:** The collection to search (`col_...`). * **API Token:** Your LGND API authentication token (`sk_...`). * **Chip ID:** Identifier of the reference chip whose embedding will be used as the search query (`chip_...`). * **Top K:** Number of results to return. Between 1 and 100. Default: 10. * **Start Date** *(optional)*: Only consider imagery captured on or after this date (`YYYY-MM-DD`). * **End Date** *(optional)*: Only consider imagery captured on or before this date (`YYYY-MM-DD`). * **Geometry Column** *(optional)*: Geography column in the Geometry Filter table. **Output** * **Output table:** The chips ranked by similarity score. Each row contains `chip_id`, `raster_id`, `cell_id`, `datetime`, `score`, `distance`, `collection`, `centroid` and `geometry`. ## LGND Location Search **Description** Performs a similarity search using a geographic point. The component looks up the chip at the given latitude/longitude and uses its embedding to find similar chips across the collection. **Inputs** * **Geometry Filter** *(optional)*: A table containing a single Polygon or MultiPolygon used to restrict results to chips intersecting that geometry. **Settings** * **Tenant ID:** Your LGND tenant identifier (`ten_...`). * **Collection ID:** The collection to search (`col_...`). * **API Token:** Your LGND API authentication token (`sk_...`). * **Latitude:** Latitude of the reference location, between -90 and 90. * **Longitude:** Longitude of the reference location, between -180 and 180. * **Top K:** Number of results to return. Between 1 and 100. Default: 10. * **Start Date** *(optional)*: When resolving the reference chip, only consider imagery captured on or after this date (`YYYY-MM-DD`). * **End Date** *(optional)*: When resolving the reference chip, only consider imagery captured on or before this date (`YYYY-MM-DD`). * **Geometry Column** *(optional)*: Geography column in the Geometry Filter table. **Output** * **Output table:** The chips ranked by similarity score. Each row contains `chip_id`, `raster_id`, `cell_id`, `datetime`, `score`, `distance`, `collection`, `centroid` and `geometry`. ## LGND Geometry Filter **Description** Returns all chips in the collection whose geometry intersects a provided polygon, ordered by `datetime` newest first. No similarity search is performed — this is a pure spatial filter, useful for browsing coverage in an area. **Inputs** * **Geometry Filter:** A table containing a single Polygon or MultiPolygon. Must intersect the collection's spatial bounds. **Settings** * **Tenant ID:** Your LGND tenant identifier (`ten_...`). * **Collection ID:** The collection to filter (`col_...`). * **API Token:** Your LGND API authentication token (`sk_...`). * **Geometry Column:** Geography column in the Geometry Filter table. * **Start Date** *(optional)*: Only return chips captured on or after this date (`YYYY-MM-DD`). * **End Date** *(optional)*: Only return chips captured on or before this date (`YYYY-MM-DD`). * **Max Results:** Maximum number of chips to return. Between 1 and 1000. Default: 100. **Output** * **Output table:** Chips intersecting the provided geometry, ordered by `datetime` newest first. Each row contains `chip_id`, `cell_id`, `raster_id`, `geometry`, `datetime`, `collection` and `centroid`. ## LGND Change Detection **Description** Detects changes over time by comparing historical chips against the most recent chips within each geographic cell. For each cell, the component scores chips against a "past state" description and a "current state" description, and returns the cells where both signals are strongest — i.e. cells that used to match the past description and now match the current description. Optional negative descriptions can be provided for either state to steer the embedding away from likely false positives. **Inputs** * **Geometry Filter** *(optional)*: A table containing a single Polygon or MultiPolygon used to restrict results to chips intersecting that geometry. **Settings** * **Tenant ID:** Your LGND tenant identifier (`ten_...`). * **Collection ID:** The collection to search (`col_...`). * **API Token:** Your LGND API authentication token (`sk_...`). * **Past State - Positive Description** *(optional)*: Semicolon-separated descriptions of what the area looked like historically. Each term is used as a separate search signal. Example: `agricultural cropland; fields`. * **Past State — Negative Description** *(optional)*: Semicolon-separated descriptions of what the historical area did NOT look like, used to steer away from false positives. Example: `homes; buildings; roads`. * **Current State - Positive Description** *(optional)*: Semicolon-separated descriptions of what the area looks like now. Example: `solar panel installation; industrial area`. * **Current State — Negative Description** *(optional)*: Semicolon-separated descriptions of what the current area does NOT look like. Example: `agricultural cropland; fields`. * **Top K:** Maximum number of changed chip pairs to return. Between 1 and 100. Default: 10. * **Geometry Column** *(optional)*: Geography column in the Geometry Filter table. **Output** * **Output table:** Detected change pairs, one row per geographic cell. Each row contains the shared `cell_id`, the combined `score` (higher = more change), `score_past` and `score_current`, and the past/current chip details (`chip_id_past`, `raster_id_past`, `datetime_past`, `geometry_past`, `chip_id_current`, `raster_id_current`, `datetime_current`, `geometry_current`) plus `collection`. ## LGND Chip Thumbnail URL **Description** Adds a thumbnail URL column to any table that contains chip IDs — typically the output of one of the LGND search components. For each chip, the component fetches the authenticated LGND thumbnail image, uploads it to a GCS bucket, and returns the public URL, which can then be rendered as a tooltip or popup image in a CARTO map. **Inputs** * **Input Table:** A table containing a column with chip IDs. **Settings** * **Chip ID Column:** Column in the input table containing the chip IDs (`chip_...`). * **API Token:** Your LGND API Bearer token used to authenticate the thumbnail requests (`sk_...`). **Output** * **Output table:** The input table with one additional column, `{chip_id_column}_thumbnail_url`, containing the public GCS URL of the thumbnail image for each chip. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.carto.com/carto-user-manual/workflows/components/lgnd-embeddings.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.