Overview
GDELT Cloud provides access to 10 GDELT database tables covering structured events, raw article metadata, entity extractions, and historical tracking. Each table is optimized for specific query patterns and use cases.Access schemas programmatically using the
get_resource tool or via MCP resource URIs (gdelt://schema/*).Table selection guide
Choose tables based on your question type:Events
gdelt_eventsWHO-WHAT-WHERE-WHEN structured eventsSpeed: < 1s
GKG
gdelt_gkgRaw article metadata (use extracted tables instead)Speed: SLOW
Mentions
gdelt_mentionsEvent-to-article bridge tableCoverage analysis
Stats (View)
mv_event_mention_statsPre-aggregated trendingSpeed: < 0.5s (fastest)
Themes
gdelt_gkg_themes_extractedTopic/theme filteringENV_, ECON_, etc.
Persons
gdelt_gkg_persons_extractedPerson mentions in articles30-day window
Organizations
gdelt_gkg_organizations_extractedOrganization mentions30-day window
Locations
gdelt_gkg_locations_extractedGeographic mentionsWith coordinates
Persons Master
gdelt_persons_masterHistorical person trackingAll-time data
Orgs Master
gdelt_organizations_masterHistorical org trackingAll-time data
Core tables
gdelt_events
The primary table for structured event data with WHO-WHAT-WHERE-WHEN information.Schema details
Schema details
Primary keys:
event_id(UInt64) - Unique event identifierday(Date) - Event date for partitioning
actor1_name,actor2_name(String) - Actor namesactor1_country_code,actor2_country_code(FixedString(3)) - ISO-3 country codesactor*_type1_code,actor*_type2_code,actor*_type3_code(FixedString(3)) - CAMEO type codesactor*_known_group_code(String) - Known organization codesactor*_ethnic_code,actor*_religion1_code(String) - Identity codes
event_code(FixedString(4)) - Full CAMEO event codeevent_base_code(FixedString(3)) - Base event codeevent_root_code(FixedString(2)) - Root category (01-20)goldstein_scale(Float32) - Event intensity (-10 to +10)quad_class(Int8) - Quad classification (1-4)num_mentions(UInt32) - Number of source articlesnum_sources(UInt32) - Number of unique sourcesavg_tone(Float32) - Average sentiment tone
action_geo_country_code,actor1_geo_country_code,actor2_geo_country_code(FixedString(2)) - FIPS country codesaction_geo_latitude,action_geo_longitude(Float32) - Geographic coordinatesaction_geo_full_name(String) - Full location name
date_added(DateTime) - When event was addedsource_url(String) - Source article URL
gdelt://schema/events- WHO: Track specific actors or countries (military, government, organizations)
- WHAT: Filter by event types (protests, violence, cooperation, statements)
- WHERE: Geographic analysis by location or country
- WHEN: Time series analysis of event patterns
- HOW INTENSE: Filter by Goldstein scale for conflict/cooperation levels
gdelt_mentions
Bridge table connecting events to GKG articles. One event can have many mentions across different sources.Schema details
Schema details
Primary keys:
event_id(UInt64) - Links to gdelt_eventsmention_identifier(String) - Unique mention identifierday(Date) - Mention date for partitioning
mention_time_date(DateTime) - When article was publishedmention_type(UInt8) - Type of mention (1=web, 2=citation, etc.)mention_source_name(String) - Source publication namemention_doc_len(UInt32) - Document length in charactersmention_doc_tone(Float32) - Document sentiment toneconfidence(UInt8) - Confidence score (0-100)
event_date(DateTime) - Original event date from gdelt_events
gdelt://schema/mentions- Coverage analysis: Count mentions per event
- Source tracking: Find which outlets covered an event
- Temporal tracking: Track when coverage peaked
- Join events to GKG: Bridge to themes, entities, locations
gdelt_gkg
The raw Global Knowledge Graph (GKG) table containing article-level metadata including themes, entities, locations, tone, and more. This table is SLOW - use the extracted tables instead for most queries.Schema details
Schema details
Primary keys:
gkg_record_id(String) - Unique GKG record identifierdate(DateTime) - Article publication date and timedocument_identifier(String) - Source article URL/identifier
source_collection_identifier(UInt8) - Collection ID (1=web, 2=print)source_common_name(String) - Source publication name
v1_themes,v2_themes(String) - Theme codes (ENV_, ECON_, etc.)v1_persons,v2_persons(String) - Person mentionsv1_organizations,v2_organizations(String) - Organization mentionsv1_locations,v2_locations(String) - Location mentions with coordinates
v1_5_tone(String) - Format: tone,positive,negative,polarity,activity,self_ref,word_count
v1_counts,v2_counts(String) - Count codes (KILL#150#CIVILIAN#Syria)v2_1_enhanced_dates(String) - Temporal referencesv2_gcam(String) - Global Content Analysis Measuresv2_1_quotations(String) - Direct quotes with attributionv2_1_sharing_image(String) - Primary sharing image URLv2_extras_xml(String) - Extended metadata in XML
ingested_at(DateTime) - Ingestion timestamp
gdelt://schema/gkg- ✅ Tone/sentiment analysis (simple field parsing)
- ✅ Source comparison (indexed field)
- ✅ Access to extended fields (v2_gcam, quotations, etc.)
- ❌ Theme filtering (use gdelt_gkg_themes_extracted instead)
- ❌ Person/org/location filtering (use extracted tables instead)
Materialized views
mv_event_mention_stats
Pre-aggregated materialized view with coverage metrics per event. This is the fastest table for trending analysis.Schema details
Schema details
Primary keys:
event_id(UInt64) - Unique event identifierday(Date) - Event date
event_date(DateTime) - Event timestampmention_count(UInt32) - Total mentionssource_count(UInt32) - Unique source countavg_tone(Float32) - Average sentiment across mentionsmin_tone,max_tone(Float32) - Tone rangeconfidence_avg(Float32) - Average confidence score
gdelt://schema/event-mention-stats- Trending/viral event detection: Find events with high mention counts
- Breaking news: Identify rapidly growing stories
- Source diversity: Filter by number of unique sources
- Sentiment analysis: Find highly negative or positive events
GKG extraction tables
gdelt_gkg_themes_extracted
Theme codes extracted from GKG (Global Knowledge Graph) articles. Use for topic-based filtering.Schema details
Schema details
Primary keys:
document_identifier(String) - Unique article identifierday(Date) - Article date for partitioning
theme(String) - Theme code (ENV_, ECON_, CONFLICT_*, etc.)char_offset(Int32) - Character position in article
date_time(DateTime) - Article publication timesource_common_name(String) - Source publicationtone(Float32) - Article sentiment tonelocation_country_code(FixedString(2)) - Primary location country
gdelt://schema/themes-extracted- Topic filtering: Find articles about specific themes
- Theme trending: Track theme mentions over time
- Sentiment by topic: Analyze tone for specific themes
- Cross-reference: Join with events via mentions table
- ENV_* - Environmental themes (climate, disasters, etc.)
- ECON_* - Economic themes (trade, inflation, markets, etc.)
- CONFLICT_* - Conflict themes (military, terrorism, etc.)
- GOV_* - Governance themes (elections, policy, corruption, etc.)
- HEALTH_* - Health themes (pandemic, policy, etc.)
- WB_* - World Bank indicator themes
- UNGP_* - UN Global Pulse themes
- CRISISLEX_* - Crisis/disaster terms
gdelt_gkg_persons_extracted
Person names mentioned in articles. 30-day rolling window.Schema details
Schema details
Primary keys:
document_identifier(String) - Article identifierday(Date) - Article date
person_name(String) - Person’s name as mentionedchar_offset(Int32) - Position in article
date_time(DateTime) - Article publication timesource_common_name(String) - Source publicationtone(Float32) - Article sentiment
gdelt://schema/persons-extracted- Person tracking: Monitor mentions of specific individuals
- Co-mentions: Find who is mentioned together
- Sentiment tracking: Analyze tone of coverage for individuals
- Geographic tracking: Where is a person being discussed
gdelt_gkg_organizations_extracted
Organization names mentioned in articles. 30-day rolling window.Schema details
Schema details
Primary keys:
document_identifier(String) - Article identifierday(Date) - Article date
organization_name(String) - Organization name as mentionedchar_offset(Int32) - Position in article
date_time(DateTime) - Article publication timesource_common_name(String) - Source publicationtone(Float32) - Article sentiment
gdelt://schema/organizations-extracted- Organization tracking: Monitor companies, NGOs, institutions
- Industry analysis: Track sector-specific organizations
- Crisis monitoring: Identify organizations in crisis situations
- Sentiment tracking: Analyze coverage tone for organizations
gdelt_gkg_locations_extracted
Geographic locations mentioned in articles with coordinates. 30-day rolling window.Schema details
Schema details
Primary keys:
document_identifier(String) - Article identifierday(Date) - Article date
location_name(String) - Location name as mentionedcountry_code(FixedString(2)) - FIPS country codelatitude,longitude(Float32) - Geographic coordinatesfeature_id(String) - Geonames feature IDchar_offset(Int32) - Position in article
date_time(DateTime) - Article publication timesource_common_name(String) - Source publicationtone(Float32) - Article sentiment
gdelt://schema/locations-extracted- Geographic analysis: Map where events are being discussed
- Country-level filtering: Focus on specific countries
- Proximity analysis: Find articles about nearby locations
- Regional trends: Track coverage by region
Historical master tables
gdelt_persons_master
Historical person tracking across all time (no 30-day limit). Aggregated view of person mentions.Schema details
Schema details
Primary key:
person_name(String) - Person’s name
first_seen(Date) - First mention datelast_seen(Date) - Most recent mention datemention_count(UInt64) - Total lifetime mentionsavg_tone(Float32) - Average sentiment across all mentionssource_count(UInt32) - Unique sources mentioning
gdelt://schema/persons-master- Historical analysis: Track individuals over months/years
- Comparative analysis: Compare coverage patterns across people
- Trend identification: Find when someone entered the news
- Lifetime metrics: Total coverage and sentiment
gdelt_organizations_master
Historical organization tracking across all time (no 30-day limit). Aggregated view of organization mentions.Schema details
Schema details
Primary key:
organization_name(String) - Organization name
first_seen(Date) - First mention datelast_seen(Date) - Most recent mention datemention_count(UInt64) - Total lifetime mentionsavg_tone(Float32) - Average sentiment across all mentionssource_count(UInt32) - Unique sources mentioning
gdelt://schema/organizations-master- Historical analysis: Track organizations over time
- Crisis analysis: Identify coverage spikes
- Reputation tracking: Monitor long-term sentiment
- Industry analysis: Compare organizations
JOIN patterns
Events → Mentions → GKG
Connect events to articles and their extracted entities:Events → Stats
Use pre-aggregated stats for faster trending analysis:Performance comparison
| Table | Speed | Best for | Date limit |
|---|---|---|---|
| mv_event_mention_stats | < 0.5s | Trending events | 30 days |
| gdelt_events | < 1s | Structured queries | 30 days |
| gdelt_gkg_themes_extracted | 1-2s | Topic filtering | 30 days |
| gdelt_mentions | 2-3s | Coverage analysis | 30 days |
| gdelt_gkg_*_extracted | 2-4s | Entity tracking | 30 days |
| gdelt_*_master | 2-5s | Historical analysis | All time |

