# Moving from v3

Source: https://developers.novilabs.com/data/migrate-from-v3/

> What changes when you move from the v3 REST API or bulk export to Novi UDM Data (v4).

v4 uses Novi's unified data model and is queried with SQL. v3 and v4 run side by side, so you can move one integration at a time.
New datasets and enhancements land in v4.

## How you connect

| | v3 | v4 |
| --- | --- | --- |
| Interface | REST API at `/api/v3`, one endpoint per resource, JSON responses | SQL against views in Snowflake, in the web interface, a driver or BI tool, or over HTTPS through Snowflake's SQL API |
| Authentication | Access token from the `/api/v3/sessions` endpoint | Snowflake login, programmatic access token, or key pair. See [Delivery options](https://developers.novilabs.com/data/delivery/) |
| Choosing data | A `scope` parameter selects the dataset on each call | You filter, join, and aggregate in SQL and return only the rows and columns you need |
| Bulk files | `/api/v3/bulk` and `/api/v3/bulk-diffs` | The `DOWNLOADS_FULL` and `DOWNLOADS_DIFF` views. See [Bulk files](https://developers.novilabs.com/data/delivery/#bulk-files) |
| New-file emails | Sent when bulk files are ready | Not sent yet. Check the views |
| Canada | Available | [Planned] Keep using v3 for Canadian data until then |

## What changes in the data

### Wells and wellbores are separate

Each well has a `WELL_KEY` and each wellbore a `WELLBORE_KEY`, both built from the regulatory ID, for example `US:API10:4212340567` and `US:API10:4212340567:0`.
Production, completions, tests, spacing, and forecasts are per wellbore. See [Well identifiers](https://developers.novilabs.com/data/identifiers/).

### Well type is two columns

Two wellbore columns replace the single v3 well type:

| Column | Answers | Examples |
| --- | --- | --- |
| `WELLBORE_TYPE_NORMALIZED` | What the wellbore does | `PRODUCER`, `INJECTOR`, `DISPOSAL`, `CYCLIC`, `STORAGE`, `OBSERVATION_TEST` |
| `PRIMARY_STREAM` | What it produces or handles | `OIL`, `GAS`, `OIL_AND_GAS`, `WATER`, `CO2`, `STEAM`, `DRY` |

Both are built from each state's filed code where Novi recognizes it. The filed code is in `WELLBORE_TYPE_REPORTED`.
Slant is in `DIRECTION`, for example `HORIZONTAL` or `U_TURN_HORIZONTAL`.

### Dates live in well events

Permit, spud, total depth, completion, first production, and plugging dates are events in `WELL_EVENT`, one timeline per well.
`WELLBORE_HEADER` and `WELL_DETAIL` still give one row per wellbore with `SPUD_DATE`, `TD_DATE`, `COMPLETION_DATE`, `FIRST_PRODUCTION_DATE`, and `PA_DATE` derived from those events.

### Forecasts are monthly and exclude history

Forecast volumes are monthly. Forecast cumulative columns add up forecast volumes only, from the first forecast period, and exclude earlier production.
To compare with a lifetime cumulative, add historical production from `PRODUCTION`.

### Standardized values

- `STATE` is the two-letter USPS code.
- `COUNTY` is the county or parish name. `COUNTY_CODE` is the five-digit FIPS code.
- Normalized status, type, and slant columns such as `STATUS`, `WELLBORE_TYPE_NORMALIZED`, and `DIRECTION` hold uppercase codes from controlled vocabularies. The `_REPORTED` columns keep the source's wording.

### Every row has lineage

All 29 base views have `SOURCE_ID`, which joins to `SOURCE`. 22 of them also have `CREATED_AT` and `UPDATED_AT`. Use them to trace a value or pick up only what changed.

## Field mapping guide

[Planned]

A guide that maps each v3 column to its v4 equivalent. Until it is published, ask your Customer Success Advisor for help mapping an existing integration.

> **Tip:**
> For a single wide table, use `WELL_DETAIL`: one row per wellbore with header, completion design, production roll-ups, and spacing.
