Overview
The Research Agent is an AI-powered interface that translates natural language questions into SQL queries against the GDELT database. Ask questions in plain English and receive structured data about global events, actors, and media coverage.How It Works
1
Natural language input
Type your question in the chat interface using everyday language.
2
AI translation
The Research Agent uses advanced LLMs (gpt-5.2-mini) to understand your intent and translate it to optimized SQL.
3
Query execution
The generated SQL query runs against GDELT database with automatic query optimization.
4
Results presentation
Data is returned in a structured format with event details, actors, locations, and sentiment.
Example Questions
The Research Agent can answer a wide variety of questions about global events:Event-Based Queries
Actor-Based Queries
Geographic Queries
Theme & Sentiment Analysis
Features
Conversational Context
The Research Agent maintains conversation context, allowing follow-up questions:- Initial Question
- Follow-up 1
- Follow-up 2
You: What protests happened in France last week?Agent: Returns 47 protest events in France
Query Refinement
If your initial question is ambiguous, the Agent will ask clarifying questions:Ambiguous Time Range
Ambiguous Time Range
You: Show me protests in the Middle EastAgent: Would you like to see protests from:
- Today
- This week
- This month
- Custom date range
Multiple Interpretations
Multiple Interpretations
You: What’s happening in China?Agent: I can show you:
- All events where China is the actor
- All events occurring in China
- All events mentioning China in news coverage
Data Visualization
Results can be displayed in multiple formats:Table View
Structured data with sortable columns and filtering options
Timeline View
Events displayed chronologically with trend indicators
Map View
Geographic visualization of event locations
Export
Download results as CSV or JSON for further analysis
Understanding Results
Event Data Fields
When querying the Events table, results include:| Field | Description | Example |
|---|---|---|
| day | Event date | 2025-01-15 |
| actor1_name | Primary actor | ”United States” |
| actor2_name | Secondary actor | ”China” |
| event_code | CAMEO event type | ”14” (Protest) |
| goldstein_scale | Conflict/cooperation (-10 to +10) | -5.0 |
| num_mentions | Media coverage frequency | 247 |
| avg_tone | Sentiment score | -3.2 |
| action_geo_country_code | Event location | USA |
GKG Data Fields
When querying the GKG table, results include:| Field | Description | Example |
|---|---|---|
| date | Article timestamp | 2025-01-15 14:30:00 |
| source_common_name | News source | ”BBC News” |
| v2_themes | Article themes | ”ECON_TRADE,LEADER” |
| v1_5_tone | Sentiment metrics | ”-2.5,65.2,3.1” |
| v2_persons | Named persons | ”Biden;Xi Jinping” |
| v2_organizations | Named organizations | ”United Nations;NATO” |
Goldstein Scale Interpretation
The Goldstein scale measures event cooperation/conflict intensity:- Cooperative (+10 to +5)
- Neutral (+4 to -4)
- Conflictual (-5 to -10)
- +10: Yield
- +8.3: Agree
- +7.0: Consult
- +6.0: Approve
- +5.0: Promise
Tips for Power Users
Use CAMEO codes
Reference specific event types: “Show event code 14 in France” (protests)
Combine with SQL
For complex analysis, export data and use the Query API directly
Track specific actors
Monitor named entities consistently across time
Compare time periods
Ask for data from different periods and compare trends