Skip to main content

​
Overview

The execute_query tool executes SQL queries against the GDELT GDELT database database, returning data for research, analysis, and iterative exploration.
This tool is designed for ad-hoc research and Q&A workflows. For creating alerts or saved queries, use present_sql instead.

​
When to use

Use execute_query for:
  • Ad-hoc research questions
  • Iterative data exploration
  • Testing queries before saving
  • Real-time analysis and insights
  • Answering specific user questions

​
Prerequisites

You must call prepare_gdelt_query BEFORE using this tool to fetch the correct schemas and codes.

​
Parameters

​
query
string
required
Complete SELECT query to execute on GDELT database GDELT database.Query requirements:
  • Must include date filter (e.g., WHERE day >= today() - INTERVAL 7 DAY)
  • Must include LIMIT clause (maximum 1000 rows)
  • Must select source URL column (source_url or document_identifier)
  • Must use valid table and column names from schemas
SELECT 
    day, 
    actor1_name, 
    event_code, 
    source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 7 DAY
    AND actor1_country_code = 'USA'
LIMIT 100
​
query_title
string
Concise title for this query (e.g., ‘Climate Protests in Europe’, ‘US Political Events’).Example: “Recent US Political Events”
Providing a title helps organize queries and is useful when creating alerts from query results.
​
query_description
string
Plain language description of what this query asks and returns.Example: “Finds all political events in the United States over the last 7 days with actor names and event codes”
A clear description helps with query documentation and improves the user experience when reviewing query results.

​
Response

​
data
array
required
Array of result objects. Each object contains columns as specified in your SELECT clause.
[
  {
    "day": "2025-01-28",
    "actor1_name": "UNITED STATES",
    "event_code": "042",
    "source_url": "https://example.com/article"
  }
]
​
count
integer
required
Number of rows returned by the query.
​
execution_time
float
Query execution time in seconds.
Use this to optimize slow queries. Events table typically < 1s, entity tables may be slower.
​
query
string
required
The executed SQL query (echoed back for reference).
​
query_title
string
The query title (if provided).
​
query_description
string
The query description (if provided).
​
error
string
Error message if query failed.Common errors include:
  • Invalid column names
  • Missing required filters
  • Syntax errors
  • Permission issues
​
suggestion
string
Helpful suggestion if query failed.Typically recommends calling prepare_gdelt_query to verify schemas.

​
Usage examples

# After calling prepare_gdelt_query
execute_query(
    query="""
        SELECT 
            day,
            actor1_name,
            actor2_name,
            event_code,
            goldstein_scale,
            source_url
        FROM gdelt_events
        WHERE day >= today() - INTERVAL 7 DAY
            AND actor1_country_code = 'CHN'
            AND event_root_code = '14'
        ORDER BY day DESC
        LIMIT 100
    """,
    query_title="China Protest Events",
    query_description="Find all protest events in China over the last 7 days with actor details and conflict intensity"
)

​
Query workflow

1

Prepare query context

Call prepare_gdelt_query to get schemas and codes.
prepare_gdelt_query(
    tables=["gdelt_events"],
    include_cameo_country_codes=True,
    include_cameo_event_codes=True
)
2

Build SQL query

Use the schemas to construct your SELECT query with:
  • Correct column names and types
  • Required date filter
  • Required LIMIT clause (max 1000)
  • Source URL column selection
SELECT day, actor1_name, source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 7 DAY
LIMIT 100
3

Execute and analyze

Call execute_query and analyze results.
result = execute_query(
    query="SELECT...",
    query_title="Your Query Title",
    query_description="Description of what this query returns"
)
Results are returned immediately for iterative exploration.
4

Iterate if needed

Refine your query based on results and execute again.This tool is designed for rapid iteration and exploration.

​
Validation

The tool automatically validates your query against GDELT requirements:
Rule: All queries must include a date/time filterValid examples:
WHERE day >= today() - INTERVAL 7 DAY
WHERE date_time >= now() - INTERVAL 24 HOUR
WHERE day BETWEEN '2025-01-01' AND '2025-01-31'
Why: Ensures reasonable query scope and prevents full table scans.
Rule: All queries must include LIMIT (maximum 1000)Valid examples:
LIMIT 100
LIMIT 500
LIMIT 1000
Why: Prevents excessive data transfer and timeout issues.
Rule: Must select source_url or document_identifierValid examples:
SELECT day, actor1_name, source_url FROM...
SELECT date_time, theme, document_identifier FROM...
Why: Enables citation and fact-checking of results.
Validation warnings are informational. Queries may still execute but might not follow best practices.

​
Performance tips

Use the fastest table for your question:
  • mv_event_mention_stats - Pre-aggregated, fastest (< 0.5s)
  • gdelt_events - Structured events, very fast (< 1s)
  • gdelt_gkg_themes_extracted - Theme filtering, fast (1-2s)
  • Entity tables - Slower for large date ranges (2-5s)
Optimize date ranges:
  • 1-7 days: Excellent performance on all tables
  • 7-30 days: Good performance, consider aggregation
  • 30+ days: Use master tables or aggressive filtering
Use selective filters:
-- Fast: Specific filters
WHERE actor1_country_code = 'USA' 
    AND event_root_code = '14'

-- Slow: Broad string matching
WHERE actor1_name LIKE '%government%'

​
Error handling

Error: “Unknown column ‘xyz’ in ‘field list’”Solution: Call prepare_gdelt_query to see available columns. Check for typos.Common mistakes:
  • country_code vs actor1_country_code vs action_geo_country_code
  • source_url vs document_identifier (different tables use different names)
Error: “Table ‘xyz’ doesn’t exist”Solution: Verify table name against the 9 available tables. Use underscore format: gdelt_events, not gdelt.events.
Error: “Query exceeded timeout limit”Solution:
  • Reduce date range
  • Add more selective filters
  • Use pre-aggregated views (mv_event_mention_stats)
  • Reduce LIMIT if selecting many columns
Error: “Authentication required” or “Invalid token”Solution: Ensure your bearer token is valid and properly configured. See authentication guide.
Error: “Rate limit exceeded”Solution: Wait before retrying. See rate limits in your plan details.

​
Common query patterns

​
Event analysis by country and event type

SELECT 
    day,
    actor1_name,
    actor2_name,
    event_code,
    goldstein_scale,
    source_url
FROM gdelt_events
WHERE day >= today() - INTERVAL 7 DAY
    AND actor1_country_code = 'RUS'
    AND event_root_code IN ('14', '18', '19')
ORDER BY day DESC, goldstein_scale ASC
LIMIT 200

SELECT 
    day,
    theme,
    COUNT(*) as mention_count
FROM gdelt_gkg_themes_extracted
WHERE day >= today() - INTERVAL 30 DAY
    AND theme LIKE 'ENV_%'
GROUP BY day, theme
ORDER BY day DESC, mention_count DESC
LIMIT 1000

​
Viral events detection

SELECT 
    event_id,
    event_date,
    mention_count,
    source_count,
    avg_tone
FROM mv_event_mention_stats
WHERE day = today() - 1
    AND mention_count >= 50
ORDER BY mention_count DESC
LIMIT 100

​
Person mentions with location context

SELECT 
    t.day,
    t.person_name,
    t.document_identifier,
    l.location_name,
    l.country_code
FROM gdelt_gkg_persons_extracted t
LEFT JOIN gdelt_gkg_locations_extracted l
    ON t.document_identifier = l.document_identifier
    AND t.day = l.day
WHERE t.day >= today() - INTERVAL 7 DAY
    AND t.person_name = 'Elon Musk'
LIMIT 500

​
Best practices

Include title and description when appropriate - Helps organize queries and improves UX when creating alerts
Test with small LIMIT first - Start with LIMIT 10-50 to verify results before requesting more
Use appropriate date ranges - Match your date range to your question (7 days for “recent”, 1 day for “today”)
Select only needed columns - Fewer columns = faster queries and smaller responses
Don’t skip prepare_gdelt_query - Attempting to guess column names leads to errors and wasted requests

​
Next steps

Prepare Query

Get schemas and codes before executing queries

Present SQL

Build and validate SQL for alerts or saved queries

Table Schemas

Learn about the 9 available GDELT tables

Code References

Explore CAMEO codes and filtering options