Enrich a product master with live Amazon details, in one statement
CALL + RESULT_SCAN round-trips, no Python middle-tier. dbt models, Snowflake Tasks, Streamlit apps, and any BI tool consume the output transparently.
What you get
- One UDTF, every Web Search Agent. Pass an agent name (
amazon_pdp,google_maps_search,linkedin_search_companies,yelp_serp,walmart_serp,zillow_pdp, …) and that agent’s input params. The same function shape covers every domain — retail, real estate, social, local business, healthcare, jobs. - Typed structured output, no LLM in the loop. Each agent parses its target domain server-side and returns purpose-built fields — product title, price, ratings, review count, ranking position. No Cortex Complete pass needed to extract values from markdown.
- One input row → one or many output rows. PDP-style agents return a single product object per input. SERP-style agents return an array; pair the UDTF with
LATERAL FLATTENto expand into per-product rows. - Per-row error isolation. A 429 on one input row surfaces as
status='http_429'for that row only. The rest of the lateral join still completes — easy to filter, easy to retry. - Stays inside your Snowflake account. Only authorized outbound calls hit Nimble. Secrets live in Snowflake’s secret manager.
Prerequisites
ACCOUNTADMINrole for one-time setup- Snowflake Enterprise edition or higher
- A Nimble API key (sign up free)
Install in Snowflake
Run the shared setup (skip if already installed)
NIMBLE_AGENT_RUN shares the same role, database, warehouse, secret, and External Access Integration as NIMBLE_SEARCH and NIMBLE_EXTRACT. If you already deployed those for the Cortex Agents integration, skip ahead.cookbook/snowflake/setup/setup.sql
Full setup script: role, grants, database, schema, warehouse, network rule, secret, EAI
Deploy NIMBLE_AGENT_RUN
A Python UDTF that wraps Nimble’s agents/run API. The signature is
(agent_name STRING, params OBJECT) — every Web Search Agent’s params body is a JSON object, so OBJECT removes the need for a ::VARIANT cast on every call site.cookbook/snowflake/udtf-data-feeds/nimble_agent_run.sql
Full UDTF with per-row error isolation, request-timeout handling, and smoke tests
Verify with a smoke test
Pick the response shape that matches the agent you want to call. PDP-style agents (Amazon PDP, LinkedIn Profile, Walmart PDP, …) return a single product object. SERP-style agents (Amazon SERP, Google Search, …) return an array of products.Both should return a populated result within ~30 seconds.
Common workflows
Local business discovery at scale
Build a fresh, location-aware view of every business that matters for a category in a market: feed aLOCATION_QUERIES table of research terms, get back the ranked Google Maps landscape — one row per business per query per refresh. Useful for market sizing, account-universe building, competitive territory mapping, and POI databases.
google_maps_search returns up to 20 results per query with rich per-place data: name, address, rating, review count, phone, business status, price level, sponsored flag, plus opening hours and accessibility metadata. The lateral join plus LATERAL FLATTEN on the nested results array is a single SQL statement.
LOCATION_QUERIES
| query | category |
|---|---|
| coffee shop in austin texas | Food & Beverage |
| veterinary clinic in seattle wa | Pet care |
| boutique fitness studio in brooklyn ny | Fitness |
LOCAL_BUSINESSES (one row per business per refresh)
| query | position | name | address | rating | review_count | price_level | sponsored |
|---|---|---|---|---|---|---|---|
| coffee shop in austin texas | 1 | Epoch Coffee | 221 W N Loop Blvd, … | 4.5 | 2481 | $ | FALSE |
| coffee shop in austin texas | 2 | Mozart’s Coffee | 3825 Lake Austin Blvd, … | 4.5 | 10618 | $$ | FALSE |
| coffee shop in austin texas | 3 | Jo’s Coffee | 1300 S Congress Ave, … | 4.4 | 1958 | $$ | FALSE |
V_NEW_ENTRANTS view can layer on top, flagging place IDs ranking in the top 20 for a tracked query for the first time in the last 7 days — useful for catching new market entrants before they take real share.
cookbook/snowflake/recipes/amazon_keyword_research/
Companion cookbook recipe (Amazon SERP flavor): full notebook, sample data, the lateral-join INSERT, the V_NEW_ENTRANTS view, and the daily Task — drop-in adapt the agent name and FLATTEN target to switch to
google_maps_search or any other SERP-style WSAProduct-master enrichment
Some agents return a single structured object instead of an array — Amazon PDP, LinkedIn Profile, Walmart PDP, Best Buy PDP. Use them when you already know which products you care about and want a full attribute dump per identifier: brand, description, color, packaging, pricing, availability, reviews.LATERAL FLATTEN needed — the agent already returns the typed product as a single object. PDP-style agents typically return ~30 attribute fields per product; project whichever subset your downstream models need.
Schedule recurring enrichment
NIMBLE_AGENT_RUN runs at a single SQL statement, which means a Snowflake Task can execute the enrichment directly. No wrapper procedure required.
cookbook/snowflake/recipes/amazon_keyword_research/schedule.sql
Reference cookbook Task (Amazon SERP flavor): incremental load, category column, error-row filtering — adapt the agent name and FLATTEN target for
google_maps_search or any other WSAUse as a dbt incremental model
The lateral-join +FLATTEN shape is also a valid dbt model body. Drop the SQL block above into models/local_businesses.sql, add a config block for incremental materialization, and dbt orchestrates the daily refresh — the same way it would for any other model.
Roll out across your organization
- Tune for your Nimble rate-limit tier. Each
NIMBLE_AGENT_RUNcall is one upstream request — one per row in your input table. For high-cardinality inputs (thousands of rows), watch for 429s; they surface per-row asstatus='http_429', so a single retry pass over those rows is the typical recovery. Nimble’s rate-limits page lists per-tier ceilings. - Right-size the warehouse.
XSMALLwith 60-second auto-suspend is fine for daily Task runs over a few hundred input rows. For larger enrichments (10K+ rows), step up toSMALLorMEDIUMonly for the duration of the scheduled task; Snowflake bills per second. - Surface failures separately. Filter
status='success'for analytical views, but log non-success rows to a_FAILURESaudit table —status='http_429','http_4xx','request_error'— so a sudden spike is visible without grepping Task logs. - Don’t ship guesses. Field names inside
parsingdiffer per agent. Inspect the shape once per agent (SELECT raw FROM …orSELECT OBJECT_KEYS(parsing[0]) FROM …) before pinning a projection into a dbt model or production view.
When to use which surface
The Snowflake integration ships three primitives across two pages. Pick by question:| You want to… | Use | Page |
|---|---|---|
| Chat with an agent in Snowflake Intelligence that knows the web | A pre-built Cortex Agent wired to scalar UDFs | Cortex Agents |
Call generic web search or page extraction inline in a SELECT | NIMBLE_SEARCH / NIMBLE_EXTRACT scalar UDFs | Cortex Agents |
| Enrich N warehouse rows with structured fields per row | NIMBLE_AGENT_RUN UDTF | This page |
NIMBLE_AGENT_RUN lives here as a sibling surface, not as a third tool on the agent.
Resources
Nimbleway/cookbook (snowflake/)
Every SQL file referenced on this page, plus the Amazon keyword research recipe
Nimble Web Search Agents
Overview of WSAs — what they are, when to use them, how they parse
Nimble Agent Gallery
Browse the catalog of pre-built agents and their per-agent parsing shapes
Snowflake Python UDTFs
How Snowflake’s tabular UDFs work —
process() handler, RETURNS TABLE, lateral-join semanticsSnowflake External Access Integration
How Snowflake gates outbound HTTPS from UDFs and stored procedures
Cortex Agents (sibling surface)
Scalar UDFs for Search + Extract, wired into a pre-built Cortex Agent