> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk export schema

> Every column in a downloaded events file, in Parquet and CSV.

Bulk downloads hand you the same coded events the API serves, as files instead of pages of
JSON. One file per calendar month, plus a rolling full-history file, in two formats.

## Files

|              |                                                                                               |
| ------------ | --------------------------------------------------------------------------------------------- |
| Formats      | Parquet (`.parquet`) and gzipped CSV (`.csv.gz`) — identical rows, identical column names     |
| Partitioning | One file per calendar month, named `<dataset>_YYYY-MM`, plus `<dataset>_all`                  |
| Integrity    | Every file publishes a `sha256`, a byte size and a row count. Check the digest before loading |
| Ordering     | Deterministic. Re-exporting an unchanged month reproduces the same bytes and the same digest  |

## Reading the two formats

Parquet carries real types: a null is a null, an array is a `LIST`, and a timestamp is a
`TIMESTAMP`. Prefer it if your tooling can read it.

CSV has neither nulls nor arrays, so two conventions apply and they are the only differences
between the formats:

* **Array columns are JSON arrays**, written as a single quoted field — parse them with your
  JSON reader, not by splitting on a delimiter. A title containing a comma would break the row
  otherwise, and titles contain commas.
* **An empty field is a null.** CSV cannot distinguish "no value" from "the empty string", and
  in this data the distinction matters: see the note on metrics below.

## Nulls are information, not gaps

A null metric does not mean zero. It means the column does not apply to that row: the conflict
family carries no `magnitude`, `systemic_importance`, `propagation_potential` or
`market_sensitivity`, and the CAMEO+ family carries no `fatalities`. Coalescing these to `0`
on load will invent measurements that were never taken, and any average you compute afterwards
will be wrong in a direction you cannot recover.

The same applies to `civilian_targeting`, which is deliberately three-valued: `true` where a
coder judged civilians were targeted, `false` where a coder judged they were not, and null
where no coder evaluated the question at all.

## Backtesting: what you can and cannot claim as-of

These files support a real point-in-time filter, and they do not support a full vintage.
The difference decides whether a backtest is sound, so it is worth being exact.

### The event SET is point-in-time. Use `coded_at`.

`coded_at` is the moment our coder produced the event, recorded per row and populated on
**100% of rows**. Every event is derived from articles published before it, and those
articles are cited in `source_urls`, so the claim is checkable rather than asserted.

That means `WHERE coded_at <= T` gives you the set of events that existed in our database at
time T. It is a filter on a recorded fact, not a reconstruction. It is the same lever the API
exposes as `observed_start` / `observed_end`.

Measured over July 2026 (42,603 events): **79.4%** were coded within a day of the event date,
**98.6%** within two days, **99.2%** within seven. Median lag 16 hours, 90th percentile 33.
Only **0.61%** of July events were coded after July ended.

**So do not filter a backtest on `event_date` alone.** Doing so hands your strategy events it
could not have seen — about 1.4% of any given month arrived more than two days late, and the
tail runs to weeks.

### The VALUES in a row are not vintaged.

The row carries what we know now, not what we knew at `coded_at`. A later article can sharpen
the location, the entity resolver can attach a name it could not resolve at the time, an
adjudicator can merge the event with another. The settle overwrites in place; there is no
per-field history. So `coded_at <= T` gives you the right ROWS with today's VALUES.

For most event-driven work that is fine — what happened, where, to whom and when we knew it
are all stable. It matters if your signal keys on a revisable field: the metric scores,
`entity_names`, or `incident_uid`, which is assigned by an adjudicator that runs after coding.

One consequence worth designing for: `event_uid` is a stable hash of the cluster, but
`event_date` is the coder's judgement and is re-derived on a re-code. An event whose date
moves therefore moves BETWEEN monthly files rather than changing position within one. Match
on `event_uid` across files, not on `event_uid` within a month.

## Coverage

Each file records the settled dates it covers against the calendar days in its period. A month
is only complete when those two agree; the manifest publishes both, so a partial month is
visible rather than silently short.

## Events

One row per record, ordered by `event_date, event_uid`. Every column below is a field
[`/api/v2/events`](/api-reference) returns — the file and the endpoint read the same table, so a
row in the file and the same row from the API agree field for field.

| Column                      | Parquet     | CSV                       | Nullable | Description                                                                                                                                                                                                                                                        |
| --------------------------- | ----------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `event_uid`                 | UTF8        | text                      | no       | Stable event identifier. Primary key with event\_date; the same id /api/v2/events/\{id} serves.                                                                                                                                                                    |
| `event_date`                | DATE        | YYYY-MM-DD                | no       | The day the event occurred — the content clock, not the day we coded it.                                                                                                                                                                                           |
| `incident_uid`              | UTF8        | text                      | no       | Shared by events judged to be the same real-world incident. Defaults to the event’s own uid when nothing was adjudicated, so grouping by it is always safe.                                                                                                        |
| `event_family`              | UTF8        | text                      | no       | Which taxonomy coded it: "cameoplus" or "conflict" (ACLED methodology).                                                                                                                                                                                            |
| `category`                  | UTF8        | text                      | yes      | Top-level category — the CAMEO+ domain, or the ACLED event type.                                                                                                                                                                                                   |
| `subcategory`               | UTF8        | text                      | yes      | Taxonomy IDENTIFIER, and exactly what ?subcategory= accepts. A CAMEO+ code ("EC04", "042") or an ACLED sub-event type ("Peaceful protest").                                                                                                                        |
| `subcategory_label`         | UTF8        | text                      | yes      | The human-readable name for subcategory. Equal to subcategory for the conflict family, where the label IS the identifier.                                                                                                                                          |
| `event_code`                | UTF8        | text                      | yes      | Raw CAMEO+ code. Empty on conflict-family rows.                                                                                                                                                                                                                    |
| `title`                     | UTF8        | text                      | yes      | Event title.                                                                                                                                                                                                                                                       |
| `summary`                   | UTF8        | text                      | yes      | One-paragraph description of the event.                                                                                                                                                                                                                            |
| `url`                       | UTF8        | text                      | yes      | Public GDELT Cloud page for this event — open it to see the evidence behind the row.                                                                                                                                                                               |
| `country`                   | UTF8        | text                      | yes      | Country, as an English display name.                                                                                                                                                                                                                               |
| `country_iso3`              | UTF8        | text                      | yes      | ISO 3166-1 alpha-3. Join on this, not on country.                                                                                                                                                                                                                  |
| `region`                    | UTF8        | text                      | yes      | Sub-region label.                                                                                                                                                                                                                                                  |
| `admin1`                    | UTF8        | text                      | yes      | First-level administrative division (state, province, oblast).                                                                                                                                                                                                     |
| `location`                  | UTF8        | text                      | yes      | Most specific place name resolved for the event.                                                                                                                                                                                                                   |
| `latitude`                  | DOUBLE      | decimal                   | yes      | Latitude, WGS84.                                                                                                                                                                                                                                                   |
| `longitude`                 | DOUBLE      | decimal                   | yes      | Longitude, WGS84.                                                                                                                                                                                                                                                  |
| `geo_precision`             | INT         | integer                   | yes      | How precisely the location is known: 1 exact, 2 admin area, 3 country. Read this before mapping the coordinates.                                                                                                                                                   |
| `source_actor`              | UTF8        | text                      | yes      | CAMEO+ acting party. On conflict rows this is actor1 — a party to the clash, not an initiator.                                                                                                                                                                     |
| `source_actor_country_iso3` | UTF8        | text                      | yes      | Acting party’s country, ISO3.                                                                                                                                                                                                                                      |
| `target_actor`              | UTF8        | text                      | yes      | CAMEO+ receiving party. On conflict rows this is actor2.                                                                                                                                                                                                           |
| `target_actor_country_iso3` | UTF8        | text                      | yes      | Receiving party’s country, ISO3.                                                                                                                                                                                                                                   |
| `significance`              | DOUBLE      | decimal                   | yes      | Composite importance, 0–1. Comparable WITHIN a family; not calibrated across families.                                                                                                                                                                             |
| `goldstein_scale`           | DOUBLE      | decimal                   | yes      | Goldstein cooperation/conflict scale, −10 to +10. CAMEO political and the conflict family only.                                                                                                                                                                    |
| `quad_class`                | UTF8        | text                      | yes      | Goldstein quad class as a label (verbal/material × cooperation/conflict).                                                                                                                                                                                          |
| `magnitude`                 | DOUBLE      | decimal                   | yes      | How large the event is in its own terms, 0–10. CAMEO+ only.                                                                                                                                                                                                        |
| `fatalities`                | INT         | integer                   | yes      | Reported deaths. Conflict family only — NULL on CAMEO+ rows, never 0.                                                                                                                                                                                              |
| `civilian_targeting`        | BOOLEAN     | true / false              | yes      | True where the coder judged civilians were targeted, false where it judged they were not, NULL where no coder evaluated it.                                                                                                                                        |
| `systemic_importance`       | DOUBLE      | decimal                   | yes      | How central the affected node is, 0–1. CAMEO+ only.                                                                                                                                                                                                                |
| `propagation_potential`     | DOUBLE      | decimal                   | yes      | How likely effects are to spread, 0–1. CAMEO+ only.                                                                                                                                                                                                                |
| `market_sensitivity`        | DOUBLE      | decimal                   | yes      | How exposed markets are to this event, 0–1. CAMEO+ only.                                                                                                                                                                                                           |
| `confidence`                | DOUBLE      | decimal                   | yes      | Coder confidence in the classification, 0–1. Well calibrated above \~0.8 and NOT below it — do not threshold on low values.                                                                                                                                        |
| `metric_version`            | UTF8        | text                      | yes      | Which metric definition produced the scores and metric\_inputs on this row. "v2-2026-07-24" carries a per-sub-factor `why`; earlier rows are a thinner shape with values only.                                                                                     |
| `metric_inputs`             | UTF8 (JSON) | JSON object               | yes      | JSON: every metric sub-factor with its value and — from v2-2026-07-24 — the coder’s stated reason. This is how magnitude, systemic\_importance, propagation\_potential and market\_sensitivity were arrived at — read it to audit a score rather than trusting it. |
| `article_count`             | INT         | integer                   | yes      | Articles in the story this event was coded from.                                                                                                                                                                                                                   |
| `source_urls`               | LIST\<UTF8> | JSON array                | no       | Article URLs the coder read to produce this event. The evidence, so a row can be checked.                                                                                                                                                                          |
| `story_id`                  | UTF8        | text                      | yes      | The story this event was coded from.                                                                                                                                                                                                                               |
| `entity_names`              | LIST\<UTF8> | JSON array                | no       | Resolved entities linked to this event, after the identity arbiter collapses duplicates.                                                                                                                                                                           |
| `coded_at`                  | TIMESTAMP   | YYYY-MM-DD hh:mm:ss (UTC) | yes      | UTC timestamp when the coder produced this event — the processing clock.                                                                                                                                                                                           |
| `as_of`                     | TIMESTAMP   | YYYY-MM-DD hh:mm:ss (UTC) | no       | What this row knew, and when. Events are NOT vintaged — the next settle overwrites — so this is a currency ceiling, not a point-in-time snapshot.                                                                                                                  |

41 columns, 34 of them nullable.

## How the export differs from the warehouse

Most columns ship exactly as stored. Two conventions apply to all of them, and a handful of
columns are computed at export time.

**An absent value is null, never an empty string.** Wherever a value is missing the file
carries a true null in Parquet and an empty field in CSV, so an `IS NULL` check finds every
absent value. **Column names are the API's names**, so a row in the file and the same row
from `/api/v2/events` agree field for field.

| Column               | What to know                                                                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `incident_uid`       | Matches the API exactly (schema 142 serve rule). The stored column is empty on unadjudicated rows; publishing that as NULL would collapse every unadjudicated event into one group.        |
| `subcategory`        | DERIVED. The stored column holds a retired composite form on partitions settled before 2026-08-17.                                                                                         |
| `subcategory_label`  | DERIVED from the same taxonomy map the API uses.                                                                                                                                           |
| `civilian_targeting` | Stored as a tri-state UInt8. The CAST is load-bearing — a bare `!= 0` yields UInt8, which Parquet writes as an INTEGER, so the file would ship 1/0 against a dictionary promising BOOLEAN. |
| `article_count`      | Renamed from canonical\_cluster\_article\_count — the stored name is internal vocabulary.                                                                                                  |
| `story_id`           | An event carries exactly one story (the canonical cluster), so the stored array is flattened to a scalar.                                                                                  |
| `entity_names`       | Renamed from entity\_ref\_names — "ref" is internal vocabulary. The parallel id/type/id\_space/wikipedia arrays are API-only; a flat file wants the names.                                 |