Skip to main content

​
Overview

The prepare_gdelt_query tool is the essential first step in any GDELT query workflow. It fetches the complete table schemas and code references you need to construct accurate SQL queries.
Always call this tool BEFORE using execute_query or present_sql. Attempting to query without preparation will result in validation errors.

​
When to use

Use prepare_gdelt_query when:
  • Starting any new query workflow
  • A user asks to analyze GDELT data
  • Building SQL for alerts or saved queries
  • You need to understand available tables and columns

​
Parameters

​
tables
array
required
Tables to query. Select based on question type.Available tables:
  • gdelt_events - WHO-WHAT-WHERE-WHEN structured events
  • gdelt_mentions - Coverage tracking and event-to-article bridging
  • mv_event_mention_stats - Trending/viral events (pre-aggregated, fastest)
  • gdelt_gkg_themes_extracted - Topic/theme filtering (ENV_, ECON_, PROTEST, etc.)
  • gdelt_gkg_persons_extracted - Person mentions in articles
  • gdelt_gkg_organizations_extracted - Organization mentions in articles
  • gdelt_gkg_locations_extracted - Geographic location mentions with coordinates
  • gdelt_persons_master - Historical person tracking (all-time, no 30-day limit)
  • gdelt_organizations_master - Historical org tracking (all-time, no 30-day limit)
​
include_cameo_country_codes
boolean
default:"false"
Include ISO-3 country codes (USA, CHN, GBR) for filtering WHO is involved.Use with actor1_country_code, actor2_country_code in gdelt_events.
​
include_fips_country_codes
boolean
default:"false"
Include FIPS 2-char country codes (US, CH, UK) for filtering WHERE events happened.Use with *_geo_country_code in gdelt_events, or country_code in gdelt_gkg_locations_extracted.
​
include_cameo_type_codes
boolean
default:"false"
Include CAMEO actor type codes (GOV, MIL, COP, EDU, etc.) for filtering actor classifications.Use with actor*_type1_code, actor*_type2_code, actor*_type3_code in gdelt_events.
​
include_cameo_known_groups
boolean
default:"false"
Include known group codes (NATO, UN, IGO, etc.) for filtering international organizations.Use with actor*_known_group_code in gdelt_events. High precision, low recall.
​
include_cameo_ethnic_codes
boolean
default:"false"
Include ethnic group codes for filtering by ethnic identity.Use with actor*_ethnic_code in gdelt_events. Sparse field, use as secondary filter.
​
include_cameo_religion_codes
boolean
default:"false"
Include religion codes for filtering by religious affiliation.Use with actor*_religion1_code, actor*_religion2_code in gdelt_events. Sparse field.
​
include_cameo_event_codes
boolean
default:"false"
Include CAMEO event codes (01-20 root codes) for filtering WHAT happened.Use with event_code, event_base_code, event_root_code in gdelt_events.Root codes: 14=protest, 18=assault, 19=fight, 20=mass violence, etc.
​
include_goldstein_scale
boolean
default:"false"
Include Goldstein scale reference (-10 to +10) for filtering event intensity.Includes natural language mapping: ‘violent conflict’ (-10 to -7), ‘cooperation’ (+3 to +6), etc.Use with goldstein_scale and quad_class in gdelt_events.
​
include_theme_gdelt_taxonomy
boolean
default:"false"
Include GDELT theme taxonomy (ENV_, ECON_, CONFLICT_, GOV_, HEALTH_, WB_, UNGP_*) for filtering article topics.Use with theme column in gdelt_gkg_themes_extracted.
​
include_theme_crisislex
boolean
default:"false"
Include CrisisLex terms for filtering crisis/disaster content.Covers: casualties, evacuations, damage, relief efforts, etc.Use with theme column (CRISISLEX_* patterns) in gdelt_gkg_themes_extracted.

​
Response

Returns a comprehensive text response containing:
  1. Complete table schemas - All columns with types, descriptions, and sample values
  2. Code references - Valid codes for filtering based on your flags
  3. JOIN guidance - How to connect multiple tables correctly
  4. Query requirements - Critical rules for valid GDELT queries
The response includes everything you need to build a valid SQL query without additional lookups.

​
Usage examples

# Basic events query
prepare_gdelt_query(
    tables=["gdelt_events"],
    include_cameo_country_codes=True,
    include_cameo_event_codes=True
)

​
Query workflow

1

Prepare your query

Call prepare_gdelt_query with your selected tables and code flags.
prepare_gdelt_query(
    tables=["gdelt_events"],
    include_cameo_country_codes=True,
    include_cameo_event_codes=True
)
You now have complete schemas and codes to build your SQL query.
2

Build your SQL

Use the returned schemas to construct your SELECT query with proper:
  • Column names
  • Date filters (required)
  • LIMIT clause (required, max 1000)
  • Source URL column (required)
3

Execute or present

Choose your next step:
  • Research/analysis: Use execute_query to run the query and get results
  • Alerts/saved queries: Use present_sql to validate and present the query

​
Table selection guide

Use gdelt_events for structured event data with actors, actions, locations, and timestamps.Examples:
  • “What did China do in Taiwan last month?”
  • “Show me military actions by Russia”
  • “Find protests in France involving labor unions”
Use gdelt_gkg_themes_extracted to filter articles by subject matter.Examples:
  • “Find articles about climate change (ENV_CLIMATECHANGE)”
  • “Show me economic news (ECON_*)”
  • “Track health policy discussions (HEALTH_*, GOV_HEALTH)”
Use entity extraction tables for mentions in article text.Examples:
  • “Find articles mentioning Elon Musk”
  • “Track coverage of Microsoft”
  • “Show locations discussed in climate articles”
Use master tables for all-time entity tracking (no 30-day limit).Examples:
  • “How has Biden been covered over the past year?”
  • “Track Tesla mentions across all time”
  • “Historical presence of NATO in news”

​
Best practices

Request only the codes you need. Each code flag adds significant content to the response. Only include flags for codes you’ll actually use in your query.
FIPS vs CAMEO country codes: These serve different purposes:
  • FIPS (2-char): WHERE events happened (location filtering)
  • CAMEO (ISO-3): WHO was involved (actor filtering)
Never mix these up in your queries.
Multiple tables: You can select multiple tables in one call. The response will include JOIN guidance showing you how to connect them correctly.

​
Common patterns

​
Simple event analysis

prepare_gdelt_query(
    tables=["gdelt_events"],
    include_cameo_event_codes=True,
    include_fips_country_codes=True
)

​
Theme-based article search

prepare_gdelt_query(
    tables=["gdelt_gkg_themes_extracted"],
    include_theme_gdelt_taxonomy=True
)

​
Multi-table with entities

prepare_gdelt_query(
    tables=[
        "gdelt_events",
        "gdelt_mentions", 
        "gdelt_gkg_persons_extracted"
    ],
    include_cameo_country_codes=True,
    include_cameo_event_codes=True
)

​
Error handling

Error: “At least one table must be specified”Solution: Always provide at least one table in the tables array.
Error: “Table ‘xyz’ not found in GDELT schema”Solution: Use only the 9 valid table names listed in the parameters section.
Error: “Authentication required”Solution: Ensure your bearer token is properly configured in your MCP client. See authentication guide.

​
Next steps

Execute Query

Run your SQL query and get results for research and analysis

Present SQL

Validate and present SQL for alerts or saved queries