# Novi Developers
> Docs for Novi Labs' oil and gas data, forecasts and analytics: Novi UDM Data (v4), the Novi Forecasts API, the Novi EVA API and Novi M&A Intelligence.
---
# Which API do I need?
Source: https://developers.novilabs.com/start/
> Pick the Novi product, delivery path and credential that fit your job, and see how the surfaces relate.
## By job
| Job | Product | Delivery | Credential | Status |
| --- | --- | --- | --- | --- |
| Load well, production and completion data into your warehouse | [Novi UDM Data (v4)](https://developers.novilabs.com/data/) | [Snowflake share](https://developers.novilabs.com/data/delivery/#share-into-your-snowflake-account) into your account, or a [Novi-hosted reader account](https://developers.novilabs.com/data/delivery/#novi-hosted-reader-account) | Your Snowflake users, or a Snowflake login from Novi | [Available] |
| Load the same data into another database | Novi UDM Data (v4) | [Bulk files](https://developers.novilabs.com/data/delivery/#bulk-files): full and diff zips per basin, built every weekday | A Snowflake login, to list signed download links | [Available] |
| Connect Databricks, Tableau or Power BI with no person logging in | Novi UDM Data (v4) | [BI or lakehouse connection](https://developers.novilabs.com/data/delivery/#connection-for-a-bi-or-lakehouse-tool) | Key pair | [Preview] |
| Query well data from a script or pipeline | Novi UDM Data (v4) | [SQL over HTTPS](https://developers.novilabs.com/data/delivery/#sql-over-https) | Snowflake programmatic access token | [Available] |
| Read forecast volumes and Arps parameters for wells in the record | Novi UDM Data (v4) | Forecast views in Snowflake, P50 only | As above | [Available] |
| Forecast planned wells and run development plans | [Novi Forecasts API](https://developers.novilabs.com/forecasts/) | REST | Novi API token | [Available] |
| Move forecasts into ARIES, ComboCurve, Val Nav or a pipeline | Novi Forecasts API | [Exports](https://developers.novilabs.com/forecasts/guides/exports/) and [partner sync](https://developers.novilabs.com/forecasts/guides/partner-sync/) | Novi API token | [Available] |
| Read EVA field values, production and forecasts for a list of wells | [Novi EVA API](https://developers.novilabs.com/eva/) | [REST](https://developers.novilabs.com/eva/api/) | EVA Developer API Token | [Preview] |
| Query upstream M&A deals, parties and valuations in SQL | [Novi M&A Intelligence](https://developers.novilabs.com/ma/) | [Snowflake](https://developers.novilabs.com/ma/data/): reader account, share or SQL over HTTPS | Your Snowflake users, or a Snowflake login from Novi | [Available] |
| Ask questions from Claude or another agent | [AI and MCP](https://developers.novilabs.com/ai/) | MCP servers for Forecasts, EVA and M&A Intelligence | Novi sign-in, or a Novi API token on Forecasts and M&A Intelligence | [Preview] |
| Work with forecasts in Claude Code | [Claude skill](https://developers.novilabs.com/forecasts/mcp/) | Skill download from the Forecasts app | Novi API token, or none with an export zip | [Available] |
| Build an app | Novi Forecasts API, or Novi UDM Data over HTTPS | REST or SQL over HTTPS, called from your server | As above | [Available] |
| Use a typed client library | Novi Forecasts API | Python and TypeScript SDKs | Novi API token | [Planned] |
Call the APIs from a server, script or notebook. Browser code on your own web pages can't call the Novi Forecasts API.
## How the surfaces relate
- **Novi UDM Data (v4)** is Novi's well record: wells, wellbores, production, completions, permits and activity for the US, in one SQL data model.
- **Novi Forecasts API** forecasts the wells you plan, from existing wells, their production and their spacing.
- **Novi EVA API** opens Novi EVA, Novi's well analytics and forecasting application, to scripts and AI assistants.
- **Novi M&A Intelligence** shares Snowflake with Novi UDM Data. The other products each have their own delivery, credential and well keys.
- **MCP servers** act as you, with your permissions.
Before you join data across products, read [Well identity](https://developers.novilabs.com/concepts/well-identity/).
## Next
- [Accounts and access](https://developers.novilabs.com/start/access/): What you need for each product, and who grants it.
- [Authentication](https://developers.novilabs.com/start/authentication/): Every credential type side by side.
- [Quickstarts](https://developers.novilabs.com/start/quickstarts/): A first call in each product.
- [Concepts](https://developers.novilabs.com/concepts/): Well identity, units, P-levels and freshness across products.
---
# Accounts and access
Source: https://developers.novilabs.com/start/access/
> What you need for each Novi product, who grants it, and what you receive.
## At a glance
| Product | You need | Who sets it up | You receive |
| --- | --- | --- | --- |
| Novi UDM Data (v4) | A subscription that names your basins | Novi. Start with your Customer Success Advisor or support@novilabs.com | A reader-account welcome email, a setup script for your own Snowflake account, or BI connection details |
| Novi Forecasts API | A Novi login at your company's host, with Access Forecasts. Access MCP to see the API tokens page | Your company's Novi administrator grants the permissions through a role. You create your own tokens | Novi API tokens |
| Novi EVA API (REST) | An EVA organization | You create a Developer API Token on EVA's **Organization Settings** page | A key for the `x-api-key` header |
| EVA MCP server [Preview] | Access EVA and Access MCP, and membership in the company whose host you use | Your company's Novi administrator grants Access MCP through a role | A sign-in from your assistant |
| M&A Intelligence MCP server [Preview] | Access Intelligence M&A. Access MCP to sign in from an assistant | Your company's Novi administrator | A sign-in, or use of a Novi API token |
## Novi UDM Data (v4)
| Path | What happens | Who acts |
| --- | --- | --- |
| [Reader account](https://developers.novilabs.com/data/delivery/#novi-hosted-reader-account) | Novi adds each person, who gets a welcome email with a login. The role is `DATA_READER` and the warehouse `NOVI_WH` | Novi |
| [Share into your account](https://developers.novilabs.com/data/delivery/#share-into-your-snowflake-account) | Your Snowflake administrator sends Novi your account details, then runs the setup script Novi emails, `novi_setup.sql`. You pay for the warehouse that runs your queries | Novi, then your Snowflake administrator |
| [BI or lakehouse connection](https://developers.novilabs.com/data/delivery/#connection-for-a-bi-or-lakehouse-tool) [Preview] | Novi creates one machine user and sends connection details with a private key link that works for 72 hours | Novi, on request |
- Every path shows only the basins in your subscription.
- The same database can also hold `NOVI_INTEL`, `NOVI_MA_INTEL` and `NOVI_NDN`. Each needs its own subscription.
## Novi Forecasts API
1. Sign in to Novi at your company's host. Your user needs the **Access Forecasts** permission to use the API.
2. To create tokens you also need **Access MCP**. Without it, **API tokens** does not appear in the Forecasts app's **Settings**.
3. Create a token under **Settings**, then **API tokens**. See [Authentication](https://developers.novilabs.com/start/authentication/#novi-api-token).
A token sees your company's plans and data and nothing else.
## Novi EVA API
- **REST:** create a Developer API Token on the **Organization Settings** page in EVA. The key acts for your EVA organization. It is not a Novi API token.
- **MCP server:** your Novi user needs **Access EVA** and **Access MCP** and must belong to the company whose host you use. API keys and Novi API tokens don't work here: you sign in from your assistant. See [Connect Claude to EVA](https://developers.novilabs.com/eva/connect-claude/).
## Novi M&A Intelligence
The MCP server needs **Access Intelligence M&A**. Signing in from an assistant also needs **Access MCP**. A Novi API token for a user with Access Intelligence M&A works too. See [Agents and MCP](https://developers.novilabs.com/ai/).
---
# Authentication
Source: https://developers.novilabs.com/start/authentication/
> Every Novi credential type side by side, where each is used, how long it lasts and how to rotate it.
Each product takes its own credential today.
## Compare credentials
| Credential | Used for | How you send it | Lifetime | Rotate or revoke |
| --- | --- | --- | --- | --- |
| [Snowflake login](#snowflake-login-and-token) | Novi UDM Data reader account: Snowflake web interface, drivers, BI tools | Snowflake sign-in | A temporary password you change at first sign-in | Not published yet |
| Your own Snowflake users | Novi UDM Data shared into your Snowflake account | Your Snowflake sign-in | Your account's policy | Your Snowflake administrator |
| [Snowflake programmatic access token](#snowflake-login-and-token) | Novi UDM Data over HTTPS | `Authorization: Bearer` header | Reader-account starter token: 14 days by default. Replace it with a 365-day token | Remove and add the token with `ALTER USER` |
| [Key pair](https://developers.novilabs.com/data/delivery/#connection-for-a-bi-or-lakehouse-tool) [Preview] | Novi UDM Data BI or lakehouse connection | Private key file in your tool | While your subscription is active. The download link lasts 72 hours | Not published yet |
| [Novi API token](#novi-api-token) | Novi Forecasts API and its MCP server, M&A Intelligence MCP server | `Authorization: Bearer` header | 1 to 365 days. The Forecasts app offers 7, 30 or 90 days, 1 year, or custom; 90 days is the default | Revoke on the API tokens page; it stops working within two minutes. Create a new one to rotate |
| [Novi sign-in for assistants](#novi-sign-in-for-assistants) [Preview] | MCP servers for Forecasts, EVA and M&A Intelligence | Your assistant signs you in | 30 days | Sign in again. Removing Access MCP cuts access within about two minutes |
| [EVA Developer API Token](#eva-developer-api-token) | Novi EVA REST API | `x-api-key` header | Not published yet | Not published yet |
Keep every credential in an environment variable or a secret manager. Never put one in code, a URL or a shared notebook. See [Security](https://developers.novilabs.com/platform/security/).
## Snowflake login and token
In a reader account, each person gets a login by welcome email and signs in with role `DATA_READER`. For SQL over HTTPS, send a programmatic access token as a bearer token to your account URL followed by `/api/v2/statements`.
```bash title="Novi UDM Data over HTTPS"
curl -X POST "$NOVI_SNOWFLAKE_URL/api/v2/statements" \
-H "Authorization: Bearer $NOVI_SNOWFLAKE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"statement": "SELECT COUNT(*) FROM NOVI_WELLS.WELL", "warehouse": "NOVI_WH", "database": "NOVI_DATA_ACCESS"}'
```
The reader-account starter token lasts 14 days by default: [replace it](https://developers.novilabs.com/data/delivery/#replace-the-starter-token) with a one-year token. On your own Snowflake account, the setup script's optional step issues the token.
## Novi API token
A Novi API token acts as one person, with that person's access.
```bash title="Novi Forecasts API"
curl -sS --fail-with-body \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
"$NOVI_API_BASE/me"
```
- **Create** it in the Forecasts app under **Settings**, then **API tokens**. You need the Access MCP permission to see that page.
- **Copy it when you create it.** Novi shows it only once.
- **Format:** tokens start with `novi_pat_`, which helps secret scanners find one committed by mistake.
- **Revoke** it on the same page. Anything using it stops working within two minutes.
- **Issued for you:** an administrator with user-management rights can also issue a token for a user. It acts as that user.
- **Limits:** no token can create or manage tokens. Novi API tokens don't work on the EVA MCP server or the EVA REST API.
Read-only service tokens not tied to a person are [Planned].
## Novi sign-in for assistants
[Preview]
Your assistant signs you in with your Novi login; you paste no token.
1. Add the server URL to your assistant.
2. Your browser opens Novi sign-in. Sign in as usual.
3. Novi's consent page shows the client, the product, your company, your email and how long the sign-in lasts. Approve it.
4. The assistant can now use that product at your company, through its MCP server only. The sign-in does not work on Novi's REST APIs or other products.
You need Access MCP and the product's own permission. Supported clients: Claude (claude.ai and Claude Desktop), Claude Code and OpenAI Codex. Sign-in uses OAuth 2.1 with PKCE. Setup: [Connect an assistant](https://developers.novilabs.com/ai/connect/).
## EVA Developer API Token
Create it on EVA's **Organization Settings** page and send it in the `x-api-key` header. It acts for your EVA organization.
```bash title="Novi EVA REST API"
curl -s "$NOVI_EVA_API_BASE/v1/data/fields?group=Header" \
-H "x-api-key: $NOVI_EVA_API_KEY"
```
`NOVI_EVA_API_BASE` is the base URL on the [EVA REST API](https://developers.novilabs.com/eva/api/) page.
> **Note:**
> The variable names on this page are placeholders. Set them from your welcome email, your Novi host and the token pages above.
---
# Quickstarts
Source: https://developers.novilabs.com/start/quickstarts/
> A first working call in each Novi product, and the fastest way to connect Claude.
Each quickstart lives with its product. Have the credential from [Accounts and access](https://developers.novilabs.com/start/access/) ready first.
- [Novi UDM Data (v4)](https://developers.novilabs.com/data/delivery/#novi-hosted-reader-account): Sign in to your reader account, check your session and run a first query. Needs a Novi UDM Data subscription.
- [Novi Forecasts API](https://developers.novilabs.com/forecasts/quickstart/): Create a token, call the API and read a done plan's curves. Needs a Novi login with Access Forecasts.
- [Novi EVA API](https://developers.novilabs.com/eva/api/#quickstart): Find field keys, then get values and production for a list of wells. Needs an EVA Developer API Token.
- [Novi M&A Intelligence](https://developers.novilabs.com/ma/data/#connect): Set your session and count deals in SQL or over HTTPS. Needs an M&A Intelligence subscription.
- [Connect Claude](https://developers.novilabs.com/ai/connect/): Add a Novi MCP server to Claude or Claude Code and ask a first question. Signing in needs Access MCP.
## After your first call
- [Cookbook](https://developers.novilabs.com/cookbook/): SQL recipes for Novi Wells, Novi Intelligence and Novi M&A Intelligence.
- [Well identity](https://developers.novilabs.com/concepts/well-identity/): Match your API numbers to each product's keys.
---
# Concepts
Source: https://developers.novilabs.com/concepts/
> The conventions that differ across Novi products, and how to line them up before you combine data.
Novi UDM Data (v4), the Novi Forecasts API and the Novi EVA API each define wells, units, P-levels and versions in their own way today. Read these pages before you join or compare numbers across products.
- [Well identity](https://developers.novilabs.com/concepts/well-identity/): API numbers, how each product keys wells, and well versus wellbore.
- [Units and conventions](https://developers.novilabs.com/concepts/units-and-conventions/): Volumes, BOE, dates, time grain and coordinates per product.
- [P-levels](https://developers.novilabs.com/concepts/p-levels/): Two naming conventions in use, and how to read Low, Mid and High.
- [Freshness and releases](https://developers.novilabs.com/concepts/freshness-and-releases/): How each product numbers releases and how to tell what you have.
---
# Well identity
Source: https://developers.novilabs.com/concepts/well-identity/
> API numbers, how each Novi product keys wells and wellbores, and how to match a pasted list.
Match wells across products and against your own lists. Each product keys wells its own way today: match on the API10 when you can, and normalize both sides first.
## API numbers
US wells carry an API number. You will see it as 10, 12 or 14 digits, with or without dashes.
| Form | What it identifies |
| --- | --- |
| API10 | The well: the 10-digit US regulatory identifier |
| API12 | The API10 plus two more digits |
| API14 | A single wellbore or completion |
The first 10 digits of any form are the API10. To match a pasted list, strip everything that is not a digit, then keep the first 10 digits. Dashed forms, API10, API12 and API14 then all match.
```sql title="Novi UDM Data: match pasted API numbers"
SELECT w.WELL_KEY, w.WELL_NAME, w.NATIVE_ID, w.STATE, w.COUNTY
FROM NOVI_WELLS.WELL w
WHERE w.NATIVE_ID IN (
SELECT LEFT(REGEXP_REPLACE(value, '[^0-9]', ''), 10)
FROM TABLE(SPLIT_TO_TABLE('42-000-00001, 4200000002, 42000000030000', ','))
)
ORDER BY w.WELL_KEY;
```
```python title="The same rule in Python"
import re
def api10(value: str) -> str:
return re.sub(r"[^0-9]", "", value)[:10]
print([api10(v) for v in ["42-000-00001", "4200000002", "42000000030000"]])
```
## How each product keys wells
| Product | Well | Wellbore | What to match on |
| --- | --- | --- | --- |
| Novi UDM Data (v4) | `WELL_KEY`, for example `US:API10:4212340567` | `WELLBORE_KEY`, for example `US:API10:4212340567:0` | `WELL.NATIVE_ID` holds the API10 |
| Novi Forecasts API, existing wells | Not keyed separately | `wellbore_key` from `GET /wells` | Read the key from the API. Its format is not published yet |
| Novi Forecasts API, planned wells | `key`, unique within one plan only. `well_uid`, 32 characters, the same on every read of that plan | Not used | `well_uid`. A plan run again gets a new id, so its wells get new `well_uid` values |
| Novi EVA API, MCP server | `Header.EntityName`: the API10 for US wells, the UWI or a local identifier elsewhere | Not used | `Header.EntityName` |
| Novi EVA API, REST | The identifiers you send in `wellList`, returned as you sent them | Not used | The identifier types it takes are not published yet. Its examples use 16-character Canadian UWIs, such as `100091802103W500` |
To join EVA results to Novi UDM Data for US wells, match `Header.EntityName` to `WELL.NATIVE_ID`. Both hold the API10. Normalize both sides to 10 digits first.
How Novi UDM Data builds `WELL_KEY` and `WELLBORE_KEY`: [Well identifiers](https://developers.novilabs.com/data/identifiers/).
## Well and wellbore
A well is the surface location and its regulatory record. A wellbore is a hole drilled from it. One well can have several wellbores.
| Product | Grain of a row |
| --- | --- |
| Novi UDM Data (v4) | Well-level attributes join on `WELL_KEY`. Production, completions, tests, spacing and forecasts are per wellbore and join on `WELLBORE_KEY`. Count wells with `COUNT(DISTINCT WELL_KEY)` |
| Novi Forecasts API | An existing well is a wellbore, keyed by `wellbore_key`. A planned well is one drawn lateral |
| Novi EVA API | One row per well, keyed by `Header.EntityName` |
## Plan wells in other tools
Planned wells have no API number. To keep them in step with another tool, key them on `well_uid`. Exports write it when you send `identity.well_id: "uid"`. See [Partner sync](https://developers.novilabs.com/forecasts/guides/partner-sync/).
## Planned
| Item | Status |
| --- | --- |
| Canadian wells in Novi UDM Data, keyed on `UWI-DLS`, for example `CA:UWI-DLS:00/02-13-069-09W5/0:0` | [Planned] |
| US wellbores in Novi UDM Data keyed on API14 | [Planned] |
---
# Units and conventions
Source: https://developers.novilabs.com/concepts/units-and-conventions/
> Volumes, BOE, depths, coordinates, dates and time grain in each Novi product, side by side.
Check units, BOE, dates and time grain here before you combine numbers across products. Novi UDM Data and the Novi Forecasts API use fixed field units; the EVA MCP server lets you choose a unit system.
## Per product
| Topic | Novi UDM Data (v4) | Novi Forecasts API | Novi EVA MCP server |
| --- | --- | --- | --- |
| Oil and water | bbl. Condensate and NGL in bbl too | bbl | `hybrid` units, the default: oil in Mbbl |
| Gas | Mcf | mcf | `hybrid`: MMcf |
| Unit system | One | One. Field names and descriptions carry the unit | `options.units`: `hybrid`, `si` or `imperial`. Results label their units |
| BOE | 6 Mcf = 1 BOE | Oil plus gas at 6 mcf per bbl | 6:1 in charts. Stored BOE columns use the 6:1 or 20:1 ratio the column names |
| Depths and lengths | ft | ft | `hybrid`: lateral length in m |
| Coordinates | Decimal degrees, WGS 84 (EPSG:4326) | `[lng, lat]` in request bodies, `"lng,lat"` in query strings, WGS 84 degrees | Polygon filters take one closed WGS 84 ring |
| Dates | `PRODUCTION_DATE` is the first day of the month. Events carry `EVENT_DT` (when it happened) and `EFFECTIVE_DT` (when it counts) | `YYYY-MM-DD`, or a date-time with a zone | `YYYY-MM-DD` in filters. `between` includes the lower bound and excludes the upper |
| Time grain | Monthly and weekly rows. Filter on `PERIOD_GRANULARITY = 'monthly'` | Cumulative volume by `ip_day`, the days since first production. Curves every 30 days to EUR, or by calendar month with `start_date` | Production charts by producing month or by date. Calendar-year volumes with `volume_years` |
| Month counter | `MONTHS_ON_PRODUCTION` starts at 1 and counts calendar months from first production, shut-in months included | Curve point `cum[m-1]` is the cumulative at day 30·m | Producing months: a month with no oil, gas or water is skipped |
| Percentages | Fractions: 0.18 means 18% | Not published yet | Not published yet |
The EVA REST API does not publish its units yet.
## BOE is not built the same way
| Product | What goes into BOE |
| --- | --- |
| Novi UDM Data (v4) | Reported BOE cumulatives hold oil, condensate and gas at 6 Mcf = 1 BOE. They exclude NGL |
| Novi Forecasts API | Oil plus gas divided by 6 |
| Novi EVA MCP server | Charts: oil plus gas divided by 6. Stored cumulative BOE columns: oil, condensate, NGL and gas at the column's stated ratio |
## "First 12 months" differs by product
The same well can show three different 12-month cumulatives.
| Product | Window | Where |
| --- | --- | --- |
| Novi UDM Data (v4) | Months 1 to 12 on production, shut-in months included. Reported values; null when the well has no producing month at month 12 or later | `CUM_OIL_12_REPORTED` and its siblings |
| Novi Forecasts API | Day 0 to day 360 of the forecast | `cum[11]` on a curve |
| Novi EVA MCP server | The first 12 producing months. Null when the well has fewer | `Production_Summary.Cumulative12MonthsOil` and its siblings |
Oil differs too. Novi UDM Data's reported oil cumulatives may include condensate. In EVA, stored cumulative oil is reported oil only, while chart oil includes condensate.
> **Caution:**
> Compare like with like. Before you set a Novi UDM Data figure beside an EVA or Forecasts figure, check the window, the oil definition and the BOE ratio.
## Cohort years
In EVA, a year with no other qualifier means production vintage (`Dates.Vintage_Year`), not completion year. In Novi UDM Data, first production and completion are events in `WELL_EVENT`. `WELL_DETAIL` carries `FIRST_PRODUCTION_DATE` and `COMPLETION_DATE` per wellbore.
## More detail
- Novi UDM Data: [Data model, units and conventions](https://developers.novilabs.com/data/model/)
- Novi Forecasts API: [Overview, conventions](https://developers.novilabs.com/forecasts/) and `GET /conventions` on your host
- Novi EVA: [EVA MCP server, conventions](https://developers.novilabs.com/eva/mcp/)
---
# P-levels
Source: https://developers.novilabs.com/concepts/p-levels/
> Novi products use two opposite P-level conventions today, so read every P10 and P90 by its case label.
> **The products disagree today:**
> In the Novi Forecasts API, P10 is the Low case. In EVA charts, P10 is the High case. Read P10 and P90 by the case label, Low, Mid (P50) or High, never by the number alone.
## Two conventions
| P-level | Percentile | Exceedance |
| --- | --- | --- |
| P10 | Low: 10% of outcomes fall below it | High: 10% chance of exceeding it |
| P50 | Mid, the median | Mid, the median |
| P90 | High: 90% of outcomes fall below it | Low: 90% chance of exceeding it |
| Used by | Novi Forecasts API | EVA charts. Also SPE PRMS reserves practice |
## Per product
| Product | Where P-levels appear | P10 | P90 | Status |
| --- | --- | --- | --- | --- |
| Novi Forecasts API | Bands with `bands: true` (`p10`, `p90`), export `p_levels`, curves `p_levels` | Low | High | [Available] |
| Novi EVA MCP server | `get_chart` statistics `p10`, `p50`, `p90`, and the `type_curve` preset | High | Low | [Preview] |
| Novi UDM Data (v4) | `SCENARIO` on the forecast views | The dictionary calls it optimistic | The dictionary calls it conservative | [Available] P50 only |
- **Novi Forecasts API.** Low and High are bands around one well's forecast, so a plan's summed Low is not the plan's own Low. Details: [Low, Mid and High](https://developers.novilabs.com/forecasts/guides/forecasts-and-curves/#low-mid-and-high).
- **Novi EVA MCP server.** Chart statistics pool every well in the filter. `group_by` offers an exact median (P50) and no other percentile measure. EVA treats a bare "P75" as ambiguous and asks which convention you mean.
- **Novi UDM Data (v4).** Only the P50 scenario ships, so `SCENARIO` holds `P50` on every row. The data dictionary's wording for P10 and P90 follows the exceedance direction. No P10 or P90 rows exist yet.
## How to read and move numbers
1. Read the case label: Low, Mid (P50) or High.
2. When you move a curve between products, map it by case. A Forecasts P10 is the Low case; an EVA chart P10 is the High case.
3. Label your own outputs by case, and state the convention once.
4. When you ask an agent for a P-level, name the case you want.
These docs label every P-level by case.
---
# Freshness and releases
Source: https://developers.novilabs.com/concepts/freshness-and-releases/
> How each Novi product numbers its releases, how often data moves, and how to tell which version you have.
Data refreshes and API releases are separate: check both.
## Per product
| | Novi UDM Data (v4) | Novi Forecasts API | Novi EVA API |
| --- | --- | --- | --- |
| Release number | Novi release numbers, such as 26.4.3. Each release also records its data model version | API version in semver, such as 1.102.0, plus the platform release that carries it, such as 1.31 | Path version `/v1`. Release numbers not published yet |
| Current | Release 26.4.3, 2026-10-29, data model version v1.6.80 | API 1.103.0 on platform 1.32, 2026-11-18 | `/v1` |
| Data refresh | On a regular schedule. Each query returns the latest load. Bulk files are built every weekday | Each model set's dataset has an as-of date | Not published yet |
| What you have | The data dictionary names the release. `DOWNLOADS_FULL` and `DOWNLOADS_DIFF` give each file's `RUN_ID` | `GET /health` returns `version` and `app_version`. `GET /dataset` returns `as_of` | MCP data results carry `schema_version` |
| Per-table refresh times | Not published yet | Not applicable | Not published yet |
## Novi UDM Data (v4)
- The current release, 26.4.3, is the first release of Novi Wells in Snowflake. Every view and column in it is new.
- Between releases, data refreshes on a regular schedule. Existing columns can change through fixes, improved logic or deprecation. They are not removed.
- Columns documented but not yet released are marked staged. You cannot query them.
- 22 of the 29 base views carry `CREATED_AT` and `UPDATED_AT`, so you can pick up only what changed.
- Bulk diff zips carry changes from one weekday run to the next. `DOWNLOADS_DIFF` keeps the last 7 runs.
## Novi Forecasts API
- `/api/v1` only grows. Some releases tighten validation, so a request accepted loosely before can become an invalid-input error.
- A done plan does not change, except its name and whether it is saved. Curve points past `model_months` can move with a release.
- Legacy Forecasts, your company's earlier predrill forecast runs served as read-only plans, can change. Read one again when its `origin.indexed_at` is newer.
## Novi EVA API
The REST API is versioned by its `/v1` path. MCP data results carry `schema_version` in every envelope.
## Planned
| Item | Status |
| --- | --- |
| A "data as of" time and refresh cadence for each Novi UDM Data view | [Planned] |
---
# Novi UDM Data (v4)
Source: https://developers.novilabs.com/data/
> Well-level US oil and gas data in one SQL data model, delivered through Snowflake, over HTTPS, or as bulk files.
Query Novi's well-level oil and gas data for the US Lower 48 with SQL, in one data model: Novi's Unified Data Model (UDM). It lives in Snowflake:
database `NOVI_DATA_ACCESS`, with the well dataset in schema `NOVI_WELLS`. The current release is **26.4.3**, released
2026-10-29.
- [Upstream Energy Data on novilabs.com](https://novilabs.com/energy-analytics/upstream-data/): Accurate oil and gas upstream data, sourced from public and private channels and refined by Novi's reservoir engineers.
## What is in it
`NOVI_WELLS` holds 41 views: 10 presentation views that join the most-used data for you, 29 base views with full
detail, and 2 that list bulk download files.
| Group | What you get | Main views |
| --- | --- | --- |
| Wells and wellbores | Well and wellbore headers, surface locations, trajectories, directional survey stations | `WELL`, `WELLBORE`, `SURFACE_LOCATION` |
| Production and tests | Monthly and weekly volumes by stream, reported roll-ups, well tests | `PRODUCTION`, `WELL_PRODUCTION_SUMMARY`, `WELL_TEST` |
| Completion and stimulation | Completion design and intensity, FracFocus disclosures | `WELL_COMPLETION`, `FRAC_FOCUS_SUMMARY` |
| Forecasts | Monthly forecast volumes, Arps segments and parameters, county supply projections | `PRODUCTION_FORECAST`, `PRODUCTION_FORECAST_ARPS_SEGMENT` |
| Spacing and subsurface | Neighbor distances, parent and child, rock properties | `WELL_SPACING`, `SUBSURFACE_PROPERTY` |
| Permits and well events | Permit filings and one lifecycle timeline per well | `PLANNED_WELL`, `WELL_PERMIT`, `WELL_EVENT` |
| Acreage, activity, and prices | Company acreage parcels, rig and frac activity, weekly WTI and Henry Hub prices | `COMPANY_ACREAGE`, `RIG_FRAC_ACTIVITY`, `PRICE_WEEKLY` |
| Reference lists | Operators, operator contacts, basins, data lineage | `OPERATOR`, `BASIN`, `SOURCE` |
Start with `WELL_DETAIL`: one row per wellbore with location, completion design, production totals and spacing already joined.
## Grain: wells and wellbores
A well is the surface location and its regulatory record. One well can have several wellbores, the holes drilled from it.
- Well-level attributes join on `WELL_KEY`. Production, completions, well tests, spacing, forecasts and frac chemistry are per wellbore and join on `WELLBORE_KEY`.
- To count wells, count distinct `WELL_KEY` values.
Every join: [Data model](https://developers.novilabs.com/data/model/). How keys are built: [Well identifiers](https://developers.novilabs.com/data/identifiers/).
## How you get it
**Novi-hosted reader account**
Novi creates a Snowflake account for your team. Log in with the link in your welcome email. No Snowflake administrator needed.
**Share into your Snowflake account**
Novi shares the data to your own Snowflake account. Your administrator runs one setup script.
**SQL over HTTPS**
Send SQL to Snowflake's SQL API with a programmatic access token. Works with either account type.
**Bulk files**
Download full and daily diff zips of tab-separated files per basin, built every weekday.
- [Compare delivery options](https://developers.novilabs.com/data/delivery/): Steps, who sets it up, and what each path grants.
## Coverage and access
- **Country:** United States. Canada is planned.
- **Basins:** you see the basins in your subscription. Views keyed by a well or wellbore filter rows for you.
- **Reference lists** such as operators, basins, and weekly prices are complete for every account.
- **Freshness:** the data refreshes on a regular schedule. Each query returns the latest load.
> **Note:**
> The same `NOVI_DATA_ACCESS` database can also hold other Novi datasets, each with its own subscription:
> `NOVI_INTEL` (Novi Intelligence basin research data), `NOVI_MA_INTEL` (upstream M&A deals), and `NOVI_NDN` (contributor-supplied well header and completion data).
> This section documents `NOVI_WELLS`.
## Next steps
- [All views](https://developers.novilabs.com/data/tables/): Every view with its columns, types, and units.
- [Cookbook](https://developers.novilabs.com/cookbook/): Ready-to-run SQL for Novi Wells, Novi Intelligence and Novi M&A Intelligence.
- [Releases and versioning](https://developers.novilabs.com/data/releases/): Release numbers, the current release and how versions are supported.
- [Moving from v3](https://developers.novilabs.com/data/migrate-from-v3/): What changes when you move from the v3 REST API or bulk export.
---
# Delivery options
Source: https://developers.novilabs.com/data/delivery/
> Every way to receive Novi UDM Data, who sets each one up, and the exact steps.
Pick how you receive Novi UDM Data and follow its steps. Every path reaches the same database, `NOVI_DATA_ACCESS`, and the same views, so the same SQL works everywhere and reads the latest load. To start, contact your Customer Success Advisor or support@novilabs.com.
## Compare the options
| Path | Best for | Who sets it up | How you sign in |
| --- | --- | --- | --- |
| [Reader account](#novi-hosted-reader-account) | Teams without Snowflake | Novi | Personal username and password, role `DATA_READER` |
| [Share into your account](#share-into-your-snowflake-account) | Teams that already use Snowflake | Novi, then your Snowflake administrator runs one script | Your own Snowflake users and roles |
| [SQL over HTTPS](#sql-over-https) | Scripts, apps, and pipelines | Comes with either account | Programmatic access token |
| [BI or lakehouse connection](#connection-for-a-bi-or-lakehouse-tool) [Preview] | Databricks, Tableau, or Power BI with no person logging in | Novi, on request | RSA key pair |
| [Bulk files](#bulk-files) | Loading into your own database | Comes with either account | Query a view for a signed link |
| [Export jobs](#planned-export-jobs) [Planned] | Large extracts without writing SQL | Not available yet | Not available yet |
Every path sees only the basins in your subscription.
## Novi-hosted reader account
Novi hosts a Snowflake account for your team, so you need no Snowflake administrator.
1. Novi gives each person their own login. A welcome email brings a login URL, a username and a temporary password. Change the password at first sign-in.
2. Sign in. Your role is `DATA_READER` and your warehouse `NOVI_WH`.
3. Set the database and schema, then check your session:
```sql title="Check your session"
USE DATABASE NOVI_DATA_ACCESS;
USE SCHEMA NOVI_WELLS;
SELECT current_account() AS account,
current_role() AS role,
current_warehouse() AS warehouse,
current_database() AS database,
current_schema() AS schema;
```
4. Browse **Databases > NOVI_DATA_ACCESS > NOVI_WELLS > Views**, or run a [cookbook recipe](https://developers.novilabs.com/cookbook/).
The welcome email includes the data dictionary and example queries, and, when API access is part of your setup, an API endpoint and a starter token for [SQL over HTTPS](#sql-over-https).
> **Tip:**
> After about a minute idle, the next query takes 10 to 30 seconds to start. The same SQL run again within 24 hours returns at once.
## Share into your Snowflake account
Novi shares the data to your Snowflake account as a private listing. You manage users, roles and warehouses as usual, and pay for the warehouse that runs your queries.
1. Your Snowflake administrator runs this and sends the result to Novi:
```sql title="Identify your account"
SELECT
CURRENT_ORGANIZATION_NAME() || '.' || CURRENT_ACCOUNT_NAME() AS org_account_name,
CURRENT_ACCOUNT() AS account_locator,
CURRENT_REGION() AS region;
```
2. Novi emails your technical contacts a setup script, `novi_setup.sql`.
3. Your administrator opens a worksheet as `ACCOUNTADMIN`, pastes the script, replaces placeholders such as `YOUR_USERNAME`, and runs it.
4. Run the script's verification step as the new user. Each product returns a row count.
The listing also appears in Snowsight under **Data sharing > External sharing > Shared with you**; **Get** there does the script's first step.
| Step | Statement | Effect |
| --- | --- | --- |
| 1 | `CREATE DATABASE NOVI_DATA_ACCESS FROM LISTING '...'` | Adds the listing as a database |
| 2 | `CREATE WAREHOUSE IF NOT EXISTS ...` | Creates a warehouse. Skip it if you have one |
| 3 | `CREATE ROLE IF NOT EXISTS ...` and `GRANT USAGE ON WAREHOUSE` | Creates a role that can use the warehouse |
| 4 | `GRANT IMPORTED PRIVILEGES ON DATABASE NOVI_DATA_ACCESS TO ROLE ...` | Lets the role read the views |
| 5 | `CREATE USER IF NOT EXISTS YOUR_USERNAME ...` and `GRANT ROLE` | Creates a user with the role, or grant it to an existing user |
| 5b | `ALTER USER YOUR_USERNAME ADD PROGRAMMATIC ACCESS TOKEN ...` | Optional. A token for [SQL over HTTPS](#sql-over-https) |
| 6 | `SELECT COUNT(*) FROM NOVI_WELLS.WELL` | Verifies access |
If a role gets a permission error on a view, grant it `DR_WELLS_STANDARD` or `DR_WELLS_FULL`, Novi's database roles in `NOVI_DATA_ACCESS`.
> **Caution:**
> Outside AWS us-east-2, the listing can take a few hours to appear the first time. If `CREATE DATABASE` fails, wait and run the script again.
## SQL over HTTPS
Send SQL to Snowflake's SQL API and get JSON back, from either account type.
- **Endpoint:** your account URL followed by `/api/v2/statements`, shown in your welcome email.
- **Token:** a programmatic access token, sent as a bearer token.
- **Body:** JSON with `statement`, `warehouse`, and `database`. On your own account, use your warehouse name.
**macOS and Linux**
```bash title="Run a query"
curl -X POST "$NOVI_SNOWFLAKE_URL/api/v2/statements" \
-H "Authorization: Bearer $NOVI_SNOWFLAKE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"statement": "SELECT WELL_KEY, WELL_NAME, BASIN, STATE, COUNTY, STATUS FROM NOVI_WELLS.WELL LIMIT 100", "warehouse": "NOVI_WH", "database": "NOVI_DATA_ACCESS"}'
```
**Windows Command Prompt**
```bat title="Run a query"
curl -X POST "%NOVI_SNOWFLAKE_URL%/api/v2/statements" -H "Authorization: Bearer %NOVI_SNOWFLAKE_TOKEN%" -H "Content-Type: application/json" -d "{\"statement\": \"SELECT COUNT(*) FROM NOVI_WELLS.WELL\", \"warehouse\": \"NOVI_WH\", \"database\": \"NOVI_DATA_ACCESS\"}"
```
A successful call returns a `data` array of rows and the message `Statement executed successfully.` Full API: docs.snowflake.com/en/developer-guide/sql-api/guide.
### Replace the starter token
The reader-account starter token is short-lived. Replace it with a one-year token under the same name, using the name and role from your welcome email:
```sql title="Rotate your token"
ALTER USER REMOVE PROGRAMMATIC ACCESS TOKEN novi_api;
ALTER USER ADD PROGRAMMATIC ACCESS TOKEN novi_api
ROLE_RESTRICTION = 'DATA_READER'
DAYS_TO_EXPIRY = 365;
```
Save the token output at once: it cannot be shown again.
## Connection for a BI or lakehouse tool
[Preview]
For a tool with no person logging in, Novi creates one machine user in a Novi-hosted account, on request. One email brings the connection details (host, port 443, user, role, warehouse, database, key fingerprint) and a private key link that works for 72 hours. Novi keeps no copy. The key works while your subscription is active.
| Tool | How to connect |
| --- | --- |
| Databricks | In Catalog Explorer, create a Snowflake connection with auth type PEM Private Key and paste the flattened key file. Then create a foreign catalog on `NOVI_DATA_ACCESS`. Needs Unity Catalog and a SQL warehouse |
| Tableau | Snowflake, key-pair authentication, the `.p8` file |
| Power BI | Get data, Snowflake, key-pair authentication, the `.p8` file |
Statements on this connection stop after 2 hours.
## Bulk files
Download zips to load into your own systems. Novi builds a new set every weekday; two views list the links.
- **Full zips:** one per basin in your subscription, plus a USA zip if you have every US basin. Each holds the reference lists too.
- **Diff zips:** the changes from one run to the next.
1. List your full zips:
```sql title="Full zips"
SELECT BASIN, ZIP_NAME, RUN_ID, RUN_AT_UTC, ZIP_SIZE_MB, URL
FROM NOVI_WELLS.DOWNLOADS_FULL
ORDER BY BASIN;
```
2. Download and load a zip. Its `RUN_ID` is the run you hold.
3. List the newer diffs, oldest first:
```sql title="Diffs to apply"
SELECT DAYS_PRIOR, BASE_RUN_ID, RUN_ID, ZIP_SIZE_MB, URL
FROM NOVI_WELLS.DOWNLOADS_DIFF
WHERE BASIN = 'Permian'
AND RUN_ID > '20261016_171714'
ORDER BY RUN_ID;
```
4. Apply each diff in `RUN_ID` order, only if its `BASE_RUN_ID` is the run you hold. You then hold its `RUN_ID`.
Each link works for 2 hours; a started download continues. Anyone with a link can use it, so do not share it.
| In a zip | What it is |
| --- | --- |
| File name | The run, for example `Permian_20261016_171714.zip` |
| `Database/` | One tab-separated file per base view, with a header row, in title case: `Database/Well.tsv`, `Database/Well_Completion.tsv` |
| Not included | `WELL_PERMIT`, `WELL_PRODUCTION_SUMMARY`, `OPERATOR_CONTACT` and the presentation views. Query them in Snowflake |
| `Shapefiles/` | Full zips of basins with acreage data: company acreage polygons in WGS84 (EPSG:4326), per operator in `Shapefiles//` and for all in `Shapefiles/All/` |
| `Database/--deleted.tsv` | Diff zips: key columns of rows to delete. Apply first |
| `Database/--diff.tsv` | Diff zips: full rows to insert or replace, on the same keys |
| `Database/.tsv` in a diff | Replaces your whole copy of that table, for example after a column change |
`DOWNLOADS_DIFF` keeps the last 7 runs. If the next diff's `BASE_RUN_ID` is not the run you hold, download the full zip again. `DAYS_PRIOR` counts runs, not days. Novi does not yet email you when new files are ready: check the views.
## Planned: export jobs
[Planned]
Send a filter or area of interest and get a short-lived download link to the same data.
## Not offered
Direct reads of Novi's storage from Spark, Trino, or other engines. Use the [BI or lakehouse connection](#connection-for-a-bi-or-lakehouse-tool) or [bulk files](#bulk-files).
---
# Data model
Source: https://developers.novilabs.com/data/model/
> How the NOVI_WELLS views are grouped, what one row means in each, and how they join.
Novi UDM Data uses one data model, Novi's Unified Data Model (UDM). Two keys connect almost everything: `WELL_KEY` for wells and `WELLBORE_KEY` for wellbores.
Reference lists such as operators have their own IDs, for example `OPERATOR_ID`.
## The core rule: wells and wellbores
- `WELL` has one row per well. `WELLBORE` has one row per wellbore. `WELL` 1:N `WELLBORE` on `WELL_KEY`.
- Production, completions, well tests, spacing, forecasts, and frac chemistry are recorded per wellbore and join on `WELLBORE_KEY`.
- If you join wellbore data to a well and add it up per well, check that you do not count the same volume twice.
## Base views by domain
| Domain | View | One row per | Key |
| --- | --- | --- | --- |
| Wells and wellbores | `WELL` | Well | `WELL_KEY` |
| | `WELLBORE` | Wellbore (lateral, sidetrack, or re-entry) | `WELLBORE_KEY` |
| | `SURFACE_LOCATION` | Surface location record of a well | `SURFACE_LOCATION_ID` |
| | `WELLBORE_TRAJECTORY` | Wellbore, as a WKT LineString | `TRAJECTORY_ID` |
| | `DIRECTIONAL_SURVEY_STATION` | Survey station along a wellbore, ordered by measured depth | `SURVEY_STATION_ID` |
| Production and tests | `PRODUCTION` | Wellbore and period, monthly or weekly | `WELLBORE_KEY` + period |
| | `WELL_PRODUCTION_SUMMARY` | Well, carried on its lowest-sequence wellbore: reported roll-ups and forecast EUR | `WELL_PRODUCTION_SUMMARY_ID` |
| | `WELL_TEST` | Wellbore and test date | `WELL_TEST_ID` |
| Completion and stimulation | `WELL_COMPLETION` | Completion event of a wellbore | `WELL_COMPLETION_ID` |
| | `FRAC_FOCUS_SUMMARY` | FracFocus disclosure (wellbore and frac sequence number) | `FRAC_FOCUS_SUMMARY_ID` |
| | `FRAC_FOCUS_INGREDIENT` | Ingredient of a disclosure | `FRAC_FOCUS_INGREDIENT_ID` |
| Forecasts | `PRODUCTION_FORECAST` | Wellbore, forecast period, and scenario | `PRODUCTION_FORECAST_ID` groups one forecast's rows |
| | `PRODUCTION_FORECAST_ARPS_SEGMENT` | Arps segment of one stream of a wellbore | `SEGMENT_UID` |
| | `PRODUCTION_FORECAST_ARPS_SEGMENT_PARAMETER` | Parameter set of a segment | `SEGMENT_PARAMETER_UID` |
| | `SUPPLY_PROJECTION` | County, production-start month, and month on production | `SUPPLY_PROJECTION_ID` |
| Spacing and subsurface | `WELL_SPACING` | Wellbore | `WELL_SPACING_ID` |
| | `WELL_SPACING_CONFIGURATION` | Basin and subbasin | `WELL_SPACING_CONFIG_ID` |
| | `SUBSURFACE_PROPERTY` | Measurement point along a wellbore | `SUBSURFACE_PROPERTY_ID` |
| Permits and well events | `PLANNED_WELL` | Public permit filing | `PLANNED_WELL_ID` |
| | `WELL_PERMIT` | Permit filing of a wellbore | `PERMIT_ID` + `WELLBORE_KEY` |
| | `WELL_EVENT` | Lifecycle event of a well or wellbore | `WELL_EVENT_ID` |
| Acreage | `COMPANY_ACREAGE` | Leasehold parcel | `COMPANY_ACREAGE_ID` |
| Market and activity | `RIG_ACTIVITY_WEEKLY` | State, county, basin, and subbasin in an ISO week | `RIG_ACTIVITY_WEEKLY_ID` |
| | `RIG_FRAC_ACTIVITY` | Rig or frac fleet observation on an activity date | `RIG_FRAC_ACTIVITY_ID` |
| | `PRICE_WEEKLY` | Week, dated the Friday | `PRICE_WEEKLY_ID` |
| Reference lists | `OPERATOR` | Company | `OPERATOR_ID` |
| | `OPERATOR_CONTACT` | Operator registration or presence in a jurisdiction | `OPERATOR_CONTACT_ID` |
| | `BASIN` | Basin and subbasin | `BASIN`, `SUBBASIN` |
| | `SOURCE` | Data lineage record | `SOURCE_ID` |
Every base view has `SOURCE_ID`, which joins to `SOURCE` and tells you which dataset a row came from.
## Relationships
| From | Join on | To | Notes |
| --- | --- | --- | --- |
| `WELLBORE` | `WELL_KEY` | `WELL` | One well, many wellbores |
| `WELL` | `OPERATOR_ID` | `OPERATOR` | Current operator of record |
| `SURFACE_LOCATION` | `WELL_KEY` | `WELL` | At most one row per well |
| `WELLBORE_TRAJECTORY`, `DIRECTIONAL_SURVEY_STATION`, `WELL_SPACING`, `WELL_TEST`, `WELL_COMPLETION`, `FRAC_FOCUS_SUMMARY`, `PRODUCTION`, `WELL_PRODUCTION_SUMMARY`, `PRODUCTION_FORECAST`, `SUBSURFACE_PROPERTY` | `WELLBORE_KEY` | `WELLBORE` | Wellbore-grain data |
| `PRODUCTION` | `OPERATOR_ID` | `OPERATOR` | Operator of record for that period, not today's operator |
| `SUBSURFACE_PROPERTY` | `SURVEY_STATION_ID` | `DIRECTIONAL_SURVEY_STATION` | Only rows with survey coverage |
| `FRAC_FOCUS_INGREDIENT` | `FRAC_FOCUS_SUMMARY_ID` | `FRAC_FOCUS_SUMMARY` | Ingredients of one disclosure |
| `PRODUCTION_FORECAST_ARPS_SEGMENT` | `PRODUCTION_FORECAST_ID` | `PRODUCTION_FORECAST` | Returns every month of that forecast |
| `PRODUCTION_FORECAST_ARPS_SEGMENT_PARAMETER` | `FORECAST_SEGMENT_ID` = `SEGMENT_UID` | `PRODUCTION_FORECAST_ARPS_SEGMENT` | Decline parameters of a segment |
| `WELL_PERMIT` | `WELLBORE_KEY`, `OPERATOR_ID` | `WELLBORE`, `OPERATOR` | Key is `PERMIT_ID` + `WELLBORE_KEY` |
| `WELL_EVENT` | `WELL_KEY`, `WELLBORE_KEY` | `WELL`, `WELLBORE` | Well-level events have a NULL `WELLBORE_KEY` |
| `WELL_EVENT` | `PERMIT_ID` + `WELLBORE_KEY` | `WELL_PERMIT` | Join on both columns |
| `PLANNED_WELL` | `MATERIALIZED_WELL_KEY` = `WELL_KEY` | `WELL` | Set once the permitted well has been drilled |
| `PLANNED_WELL`, `COMPANY_ACREAGE`, `OPERATOR_CONTACT`, `RIG_FRAC_ACTIVITY` | `OPERATOR_ID` | `OPERATOR` | |
| Every base view | `SOURCE_ID` | `SOURCE` | Lineage |
### Views that join on shared columns
These views share no key with the others. Combine them on the columns listed.
| View | Join on | How to use it |
| --- | --- | --- |
| `BASIN` | `BASIN`, `SUBBASIN` | Every view keyed by a well or wellbore carries `BASIN` and `SUBBASIN`, so filter on them directly |
| `PRICE_WEEKLY` | `DATE` | Prices are dated the Friday of each week. Match a date to the Friday of its week |
| `RIG_ACTIVITY_WEEKLY` | `COUNTY_CODE`, `YEAR`, `WEEK` | Join to `WELL` on `COUNTY_CODE`, the five-digit FIPS code. A county that spans basins has a row per basin, so sum by county and week first |
| `SUPPLY_PROJECTION` | `COUNTY_CODE`, `MONTH_OF_PRODUCTION_START`, `MONTHS_ON_PRODUCTION` | Join to `WELL` on `COUNTY_CODE`, then pick the start month and month on production you need |
| `WELL_SPACING_CONFIGURATION` | `BASIN`, `SUBBASIN` | The search radii and cutoffs behind a wellbore's spacing values |
## Presentation views
The presentation views join base views for you. Where a value appears in both, the base view is authoritative. Their columns can change between releases as they are extended.
| View | One row per | Other keys |
| --- | --- | --- |
| `WELL_DETAIL` | `WELLBORE_KEY` | `WELL_KEY`, `OPERATOR_ID`, `PERMIT_ID`, `WELL_COMPLETION_ID`, `WELL_SPACING_ID` |
| `WELLBORE_HEADER` | `WELLBORE_KEY` | `WELL_KEY`, `OPERATOR_ID`, `PERMIT_ID` |
| `WELLBORE_COMPLETION_DESIGN` | `WELLBORE_KEY` | `WELL_COMPLETION_ID` |
| `WELLBORE_PRODUCTION_SUMMARY` | `WELLBORE_KEY` | None |
| `WELLBORE_DECLINE_PARAMETERS` | `WELLBORE_KEY`, `PRODUCTION_FORECAST_ID`, `PRODUCTION_STREAM`, `SEGMENT_NUMBER` | `SEGMENT_UID`, `SEGMENT_PARAMETER_UID` |
| `WELLBORE_SPACING_DETAIL` | `WELLBORE_KEY` | `WELL_SPACING_ID` |
| `WELLBORE_SUBSURFACE_PROPERTY` | `WELLBORE_KEY`, `LOCATION_TYPE`, `FORMATION` | `SUBSURFACE_PROPERTY_ID`, `SURVEY_STATION_ID` |
| `WELLBORE_TEST_HISTORY` | `WELLBORE_KEY`, `TEST_DATE` | `WELL_TEST_ID` |
| `PRODUCTION_MONTHLY` | `WELLBORE_KEY`, `YEAR`, `MONTH` | None |
| `PRODUCTION_FORECAST_MONTHLY` | `WELLBORE_KEY`, `SCENARIO`, `YEAR`, `MONTH` | `PRODUCTION_FORECAST_ID` |
`WELL_DETAIL` is the composition of `WELLBORE_HEADER`, `WELLBORE_PRODUCTION_SUMMARY`, `WELLBORE_COMPLETION_DESIGN`, and `WELLBORE_SPACING_DETAIL`.
The narrow views are not cheaper than `WELL_DETAIL`. They are just narrower to read.
> **Caution:**
> `PRODUCTION_MONTHLY` and `PRODUCTION_FORECAST_MONTHLY` overlap. A wellbore can have an actual and a forecast row for the same month, and the overlap grows until the forecast is regenerated.
> Do not add the two for a period. Take actuals where they exist and the forecast only beyond them.
## Rules that keep numbers right
| Rule | Why |
| --- | --- |
| Filter `PRODUCTION` and `PRODUCTION_FORECAST` on `PERIOD_GRANULARITY = 'monthly'` | `PRODUCTION` holds monthly and weekly rows; without the filter, totals count the same volume twice. `PRODUCTION_FORECAST` ships monthly rows only today; keep the filter so the query stays right if other granularities ship |
| Collapse `PRODUCTION` to one row per wellbore and month before windowed math | The view does not guarantee a single row per wellbore, year, and month |
| Align wells on `MONTHS_ON_PRODUCTION`, not on date | It counts calendar months from first production, starting at 1, including shut-in months |
| Check a well has month 1 before a fixed window such as months 1 to 60 | A few wells have no early records and start at 2 or later |
| Never add ratios such as GOR, WOR, or proppant per foot | Compute them per well or well-month, then average |
| Read percentage columns as fractions | 0.18 means 18% |
| Never add `EUR_*` columns across horizons | The 20, 30, and 50-year EUR columns overlap |
| Count wells with `COUNT(DISTINCT WELL_KEY)` | One well can have several wellbores |
| Name only the columns you need and filter on `WELLBORE_KEY`, date, and granularity | `PRODUCTION` has hundreds of millions of rows |
## Units and conventions
- **Volumes:** oil, condensate, NGL, and water in barrels (bbl). Gas in thousand cubic feet (Mcf).
- **BOE:** 6 Mcf of gas = 1 barrel of oil equivalent.
- **Depths and lengths:** feet.
- **Coordinates:** decimal degrees, WGS 84 (EPSG:4326).
- **Production streams** on forecast segments: `oil`, `gas`, `water`, `ngl`, `condensate`.
- **Forecast scenarios:** this release publishes `P50`, the median forecast, only.
See [All views](https://developers.novilabs.com/data/tables/) for every column, its type, and its unit.
---
# Well identifiers
Source: https://developers.novilabs.com/data/identifiers/
> How Novi UDM Data identifies wells and wellbores, and how to match your API numbers to them.
Every well has a `WELL_KEY` and every wellbore has a `WELLBORE_KEY`. Both are stable strings built from the regulatory identifier.
Join on the keys. Use `NATIVE_ID` to match identifiers that come from outside Novi.
## Key formats
| Key | Format | US example |
| --- | --- | --- |
| `WELL_KEY` | `{COUNTRY}:{NATIVE_ID_TYPE}:{NATIVE_ID}` | `US:API10:4212340567` |
| `WELLBORE_KEY` | `{COUNTRY}:{NATIVE_ID_TYPE}:{NATIVE_ID}:{SEQUENCE_NUMBER}` | `US:API10:4212340567:0` |
The parts are columns on the same row:
| Column | On `WELL` | On `WELLBORE` |
| --- | --- | --- |
| `COUNTRY` | ISO 3166-1 alpha-2 code, for example `US` | Same as its well |
| `NATIVE_ID_TYPE` | `API10` in the US, `UWI-DLS` in Canada | `API14` when a borehole and event suffix is available, otherwise `API10`. `UWI-DLS` in Canada. `PLANNED` for a planned wellbore with no regulatory ID yet |
| `NATIVE_ID` | The regulatory ID in canonical form: 10 digits for API10, no hyphens | The wellbore's regulatory ID. API14 is 14 contiguous digits. For `PLANNED` it is a Novi ID |
| `SEQUENCE_NUMBER` | Not used | Ordinal of wellbores that share a `NATIVE_ID`, starting at 0 |
`SEQUENCE_NUMBER` is 0 on every row in the current release: no `NATIVE_ID` yet resolves to more than one wellbore.
## Match your API numbers
`WELL.NATIVE_ID` holds the API10. Normalize the values you have before you match: strip everything that is not a digit, then take the first 10 digits.
Dashed forms, API10, API12, and API14 then all match.
```sql
SELECT w.WELL_KEY, w.WELL_NAME, w.NATIVE_ID, w.STATE, w.COUNTY, w.STATUS
FROM NOVI_WELLS.WELL w
WHERE w.NATIVE_ID IN (
SELECT LEFT(REGEXP_REPLACE(value, '[^0-9]', ''), 10)
FROM TABLE(SPLIT_TO_TABLE('42-000-00001, 4200000002, 42000000030000', ','))
)
ORDER BY w.WELL_KEY;
```
Replace the sample list with your own comma-separated API numbers.
## Rules of thumb
- Join well-level attributes on `WELL_KEY` and wellbore-level data on `WELLBORE_KEY`.
- Count wells with `COUNT(DISTINCT WELL_KEY)`. Count wellbores with `COUNT(DISTINCT WELLBORE_KEY)`.
- `WELL_NAME` is for display. It is not a key.
- `OPERATOR_ID` identifies an operator. `OPERATOR.NAME`, `OPERATOR_REPORTED`, and `OPERATOR_ORIGINAL` are names, not keys. `OPERATOR.NAME` is stored as the source spelled it and may carry padding, so match it with `LOWER(TRIM(NAME))`.
- `COUNTY` is a county or parish name. `COUNTY_CODE` is the five-digit FIPS code.
- `STATE` is the two-letter USPS code.
- `LEASE_NUMBER` on `WELL` is a state lease or production-unit identifier, not a key. Texas files the Railroad Commission district and lease number joined by a semicolon, for example `08;39152`. Oklahoma files the 14-digit production unit number. It is NULL in every other state today.
## Planned
- **API14 wellbore identifiers for US wells.** The model supports `API14` for wellbores. Distinct US wellbores keyed on API14 are planned.
- **Canadian wells.** Canadian wells will use the `CA` country code and Canadian UWI schemes such as `UWI-DLS`, for example `CA:UWI-DLS:00/02-13-069-09W5/0:0` for a wellbore. See [Releases](https://developers.novilabs.com/data/releases/#coverage).
## Glossary
| Term | Meaning |
| --- | --- |
| API10 | The 10-digit API well number, the US regulatory identifier for a well |
| API14 | The 14-digit API number, which identifies a single wellbore or completion |
| UWI | Unique well identifier: the API number in the US, or the Canadian equivalent (UWI-DLS) |
| `NATIVE_ID` / `NATIVE_ID_TYPE` | The regulatory identifier of a well or wellbore and the kind of identifier it is |
---
# All views
Source: https://developers.novilabs.com/data/tables/
> Every view in the NOVI_WELLS schema. Filter the views, or find a column across all of them.
Release 26.4.3 publishes 41 views in `NOVI_DATA_ACCESS.NOVI_WELLS`: ten presentation views, 29 base views, and two views that list bulk download files. Start with `WELL_DETAIL` for one row per wellbore with the most-used attributes joined. Use the base views when you need full detail.
## Find a view
| View | Group | Columns | Summary |
| --- | --- | --- | --- |
| [`WELL_DETAIL`](https://developers.novilabs.com/data/tables/presentation-views/#well_detail) | Presentation views | 125 | Wide one-row-per-wellbore reporting view. |
| [`WELLBORE_HEADER`](https://developers.novilabs.com/data/tables/presentation-views/#wellbore_header) | Presentation views | 63 | Identity, jurisdiction, geology, operator, status and lifecycle dates. |
| [`WELLBORE_COMPLETION_DESIGN`](https://developers.novilabs.com/data/tables/presentation-views/#wellbore_completion_design) | Presentation views | 19 | First-completion design plus intensity ratios. |
| [`WELLBORE_PRODUCTION_SUMMARY`](https://developers.novilabs.com/data/tables/presentation-views/#wellbore_production_summary) | Presentation views | 40 | Production roll-ups as the source of record reports them per well, carried rather than recomputed. |
| [`WELLBORE_DECLINE_PARAMETERS`](https://developers.novilabs.com/data/tables/presentation-views/#wellbore_decline_parameters) | Presentation views | 22 | Arps parameters per segment per stream, shaped for ARIES export. |
| [`WELLBORE_SPACING_DETAIL`](https://developers.novilabs.com/data/tables/presentation-views/#wellbore_spacing_detail) | Presentation views | 17 | Parent/child classification and neighbour distances for interference work. |
| [`WELLBORE_SUBSURFACE_PROPERTY`](https://developers.novilabs.com/data/tables/presentation-views/#wellbore_subsurface_property) | Presentation views | 43 | Rock properties and landing-zone geometry at one measurement point. |
| [`WELLBORE_TEST_HISTORY`](https://developers.novilabs.com/data/tables/presentation-views/#wellbore_test_history) | Presentation views | 16 | Well-test rates and flowing and shut-in pressures. |
| [`PRODUCTION_MONTHLY`](https://developers.novilabs.com/data/tables/presentation-views/#production_monthly) | Presentation views | 19 | Monthly volumes by stream across calendar, producing and economic time axes. |
| [`PRODUCTION_FORECAST_MONTHLY`](https://developers.novilabs.com/data/tables/presentation-views/#production_forecast_monthly) | Presentation views | 18 | Monthly forecast rates and cumulatives by stream, per scenario. |
| [`WELL`](https://developers.novilabs.com/data/tables/wells/#well) | Wells and wellbores | 23 | Canonical identity and slowly changing attributes for a well. |
| [`WELLBORE`](https://developers.novilabs.com/data/tables/wells/#wellbore) | Wells and wellbores | 49 | A specific bore/lateral associated with a well. |
| [`SURFACE_LOCATION`](https://developers.novilabs.com/data/tables/wells/#surface_location) | Wells and wellbores | 16 | Surface location and legal description for a well. |
| [`WELLBORE_TRAJECTORY`](https://developers.novilabs.com/data/tables/wells/#wellbore_trajectory) | Wells and wellbores | 9 | Stores a wellbore trajectory as a polyline for spatial analysis (spacing, overlap, inventory sizing, and map visualization). |
| [`DIRECTIONAL_SURVEY_STATION`](https://developers.novilabs.com/data/tables/wells/#directional_survey_station) | Wells and wellbores | 19 | Station-level directional survey data for a wellbore. |
| [`PRODUCTION`](https://developers.novilabs.com/data/tables/production/#production) | Production and tests | 36 | The production record for a single wellbore at either monthly or weekly granularity, identified by wellbore\_key and a period selector. |
| [`WELL_PRODUCTION_SUMMARY`](https://developers.novilabs.com/data/tables/production/#well_production_summary) | Production and tests | 42 | Production roll-ups reported at well level. |
| [`WELL_TEST`](https://developers.novilabs.com/data/tables/production/#well_test) | Production and tests | 17 | Periodic well test measurement for a single wellbore on a specific test date. |
| [`WELL_COMPLETION`](https://developers.novilabs.com/data/tables/completions/#well_completion) | Completion and stimulation | 20 | Completion/stimulation state and summary parameters for a wellbore. |
| [`FRAC_FOCUS_SUMMARY`](https://developers.novilabs.com/data/tables/completions/#frac_focus_summary) | Completion and stimulation | 30 | Summary of a FracFocus chemical disclosure for a hydraulic fracturing event. |
| [`FRAC_FOCUS_INGREDIENT`](https://developers.novilabs.com/data/tables/completions/#frac_focus_ingredient) | Completion and stimulation | 20 | Detailed chemical ingredient from a FracFocus disclosure. |
| [`PRODUCTION_FORECAST`](https://developers.novilabs.com/data/tables/forecasts/#production_forecast) | Forecasts | 23 | Forecasted monthly production for a wellbore. |
| [`PRODUCTION_FORECAST_ARPS_SEGMENT`](https://developers.novilabs.com/data/tables/forecasts/#production_forecast_arps_segment) | Forecasts | 14 | An ARPS forecast segment refers to a specific time range for a single production stream of a wellbore. |
| [`PRODUCTION_FORECAST_ARPS_SEGMENT_PARAMETER`](https://developers.novilabs.com/data/tables/forecasts/#production_forecast_arps_segment_parameter) | Forecasts | 11 | Parameter values associated with a single ARPS forecast segment. |
| [`SUPPLY_PROJECTION`](https://developers.novilabs.com/data/tables/forecasts/#supply_projection) | Forecasts | 14 | County-level type curve projections for oil and gas supply modeling. |
| [`WELL_SPACING`](https://developers.novilabs.com/data/tables/spacing-subsurface/#well_spacing) | Spacing and subsurface | 18 | Spacing metrics for a single wellbore, including nearest neighbor distances, parent/child classification, and density metrics. |
| [`WELL_SPACING_CONFIGURATION`](https://developers.novilabs.com/data/tables/spacing-subsurface/#well_spacing_configuration) | Spacing and subsurface | 15 | Configuration settings used to compute well\_spacing metrics. |
| [`SUBSURFACE_PROPERTY`](https://developers.novilabs.com/data/tables/spacing-subsurface/#subsurface_property) | Spacing and subsurface | 44 | Subsurface petrophysical and geomechanical properties at a specific point/depth along a wellbore, optionally mapped to a directional survey station when one exists. |
| [`PLANNED_WELL`](https://developers.novilabs.com/data/tables/permits-events/#planned_well) | Permits and well events | 15 | Permitted wells, sourced from state and other public drilling permit filings. |
| [`WELL_PERMIT`](https://developers.novilabs.com/data/tables/permits-events/#well_permit) | Permits and well events | 10 | Regulatory drilling permit records associated with a wellbore. |
| [`WELL_EVENT`](https://developers.novilabs.com/data/tables/permits-events/#well_event) | Permits and well events | 13 | Ledger of lifecycle milestones and state changes for wells and wellbores (planning -> drilling -> completion -> production -> workovers -> P&A). |
| [`COMPANY_ACREAGE`](https://developers.novilabs.com/data/tables/activity-land/#company_acreage) | Acreage | 16 | Land-parcel acreage positions held by an operator or mineral rights company. |
| [`RIG_ACTIVITY_WEEKLY`](https://developers.novilabs.com/data/tables/activity-land/#rig_activity_weekly) | Market and activity | 16 | Weekly horizontal rig count by county and basin, sourced from Baker Hughes North American Rotary Rig Count. |
| [`RIG_FRAC_ACTIVITY`](https://developers.novilabs.com/data/tables/activity-land/#rig_frac_activity) | Market and activity | 22 | Combined rig and frac fleet activity details. |
| [`PRICE_WEEKLY`](https://developers.novilabs.com/data/tables/activity-land/#price_weekly) | Market and activity | 7 | Weekly benchmark commodity prices. |
| [`OPERATOR`](https://developers.novilabs.com/data/tables/reference/#operator) | Operators and reference lists | 8 | A company that operates wells. |
| [`OPERATOR_CONTACT`](https://developers.novilabs.com/data/tables/reference/#operator_contact) | Operators and reference lists | 17 | How to reach an operator about a particular jurisdiction, and the registration that jurisdiction issued. |
| [`BASIN`](https://developers.novilabs.com/data/tables/reference/#basin) | Operators and reference lists | 3 | Reference list of basins and subbasins. |
| [`SOURCE`](https://developers.novilabs.com/data/tables/reference/#source) | Operators and reference lists | 8 | Data lineage dimension. |
| [`DOWNLOADS_FULL`](https://developers.novilabs.com/data/tables/downloads/#downloads_full) | Bulk downloads | 6 | Full zip files you can download. |
| [`DOWNLOADS_DIFF`](https://developers.novilabs.com/data/tables/downloads/#downloads_diff) | Bulk downloads | 9 | Diff zip files you can download, one row per basin per run. |
## Find a column
---
# Presentation views
Source: https://developers.novilabs.com/data/tables/presentation-views/
> Ten ready-joined views with one row per wellbore, month, test, or decline segment.
These views join the base views for you, so the most common questions need no joins. Where a value appears both here and in a base view, the base view is authoritative. Their columns can change between releases as they are extended.
Views live in `NOVI_DATA_ACCESS.NOVI_WELLS`. Column descriptions are from the Wells data dictionary, release 26.4.3.
## WELL_DETAIL
Wide one-row-per-wellbore reporting view: the composition of `WELLBORE_HEADER`, `WELLBORE_PRODUCTION_SUMMARY`, `WELLBORE_COMPLETION_DESIGN` and `WELLBORE_SPACING_DETAIL`. Grain: one row per wellbore\_key. Every column is defined by the narrow view it comes from.
| Column | Description |
| --- | --- |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key. |
| `WELL_KEY` | Foreign key to well.well\_key, linking this wellbore to its parent well. |
| `NATIVE_ID` | Wellbore-level identifier. For regulatory schemes (API10/API14/UWI-DLS) this is the external regulatory id, API14 captures the sidetrack/event suffix (positions 11-14) that disambiguates per-wellbore borehole+event; the well-level well.native\_id carries the well-level root (API10 for US, UWI-DLS for Canada). Use the contiguous 14-digit API14 (digits only, no hyphens). For the PLANNED scheme (planned wellbores with no regulatory id yet) this is the Novi-internal id (the planned\_well\_id). The scheme is named by native\_id\_type, which conditionally validates this value's canonical format per scheme; this value is the third component of wellbore\_key. |
| `OPERATOR_ID` | Current operator of record. Historical changes should be captured as events (e.g., `OPERATOR_CHANGE`) or in a dedicated attribute history. |
| `PERMIT_ID` | Regulatory permit identifier as issued by the state/agency. Primary key for the permit record. |
| `WELL_COMPLETION_ID` | Surrogate key of the completion event this row collapsed to, the first completion. Carried so a consumer can trace back to the source row and audit the collapse. |
| `WELL_SPACING_ID` | Surrogate key. |
| `NATIVE_ID_TYPE` | Identifier scheme of native\_id (API10, API14, UWI-DLS, or PLANNED). API14 when a borehole/event suffix is available, otherwise API10 (e.g. single-wellbore wells or API10-only sources), UWI-DLS in Canada, or PLANNED for planned wellbores with no regulatory identifier yet. Second component of wellbore\_key. |
| `COUNTRY` | Two-letter ISO 3166-1 alpha-2 country code where the wellbore is located (e.g., US, CA). First component of wellbore\_key; matches the parent well.country. |
| `SEQUENCE_NUMBER` | Ordinal distinguishing wellbores that share a native\_id, part of the conformed identity (native\_id + native\_id\_type + country + sequence\_number). It is 0 on every row in current data, no native\_id yet resolves to more than one wellbore, and is retained because the identity is only unique with it. |
| `WELL_NAME` | Human-friendly well name (operator or regulatory naming). Use for display; not a key. |
| `FIELD_NAME` | Name of the oil/gas field the well is in. |
| `STATE` | US state (USPS two-letter) or Canadian province/territory (Statistics Canada two-letter) code where the well is located. |
| `COUNTY` | Name of the county (or parish in Louisiana) where the well is located, as reported (e.g., "Reeves"); a name, never a code. The FIPS code is in `COUNTY_CODE`. NULL when not reported. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `FORMATION` | Canonical formation name used for analytics grouping. Represents Novi's best estimate of the landing zone formation. |
| `FORMATION_REPORTED` | Formation name as reported by the data source (raw regulatory filing string). |
| `FORMATION_REPORTED_NORMALIZED` | Source-reported formation mapped to a controlled vocabulary. |
| `FORMATION_CALCULATED` | Novi-calculated formation based on wellbore geometry and formation tops (structural depth grids). Used as the standard grouping key for peer comparison. |
| `CURRENT_OPERATOR` | Operator of record for this wellbore's well as of today, resolved to the canonical operator name, which is stored unmodified and may carry padding. Use this for grouping peers; never group on a raw reported name. |
| `WELL_STATUS` | Current coarse lifecycle state of the well (derived from events). Includes 7 milestone-based values and 9 regulatory/operational ones; semantic overlaps (e.g. PERMITTED/`PERMIT_APPROVED`, DRILLING/SPUD, PRODUCING/ACTIVE, `SHUT_IN`/INACTIVE) are deliberately preserved as distinct values so you can tell which source vocabulary a row came from. Details live in well\_event. |
| `WELLBORE_STATUS` | Current lifecycle state for the wellbore (can differ from the well-level status). |
| `WELLBORE_STATUS_REPORTED` | Raw reported wellbore status value from the regulator filing, at wellbore grain (analogous to well.status\_reported but for a specific lateral / sidetrack / re-entry). Independent input from well.status\_reported, wellbore status can differ from well status. |
| `WELLBORE_STATUS_REPORTED_NORMALIZED` | Reported wellbore status mapped to a controlled vocabulary, at wellbore grain (analogous to well.status\_reported\_normalized). Distinct from wellbore.status (Novi-curated lifecycle enum); the reported/normalized pair preserves provenance for audit. |
| `WELLBORE_TYPE_NORMALIZED` | What the wellbore does: its declared operational function, from a controlled vocabulary (PRODUCER, INJECTOR, DISPOSAL, CYCLIC, STORAGE, `OBSERVATION_TEST`, and drainage and thermal-recovery roles). It is the declared function, not current activity: a plugged or shut-in producer stays PRODUCER, so use `WELLBORE_STATUS` for activity. What the wellbore produces or handles is on `PRIMARY_STREAM`. Functions other than PRODUCER come only from a recognised filed code in `WELLBORE_TYPE_REPORTED`; without one (for example, every Texas wellbore) the value is PRODUCER or NULL, so counts of injection, disposal or storage wells are incomplete there. NULL when the source does not establish a function, for example a dry hole (`PRIMARY_STREAM` = DRY) or a service well whose filing does not say which service. |
| `WELLBORE_TYPE_REPORTED` | The well-type code the source supplies for the regulator filing, trimmed and otherwise as filed. Codes, case and spelling vary by jurisdiction; they are not a controlled vocabulary. NULL where the source supplies no code (currently all Texas wellbores and most in Kansas and West Virginia). `WELLBORE_TYPE_NORMALIZED` and `PRIMARY_STREAM` use this code where it is recognised and a coarser classification otherwise, so they can hold a value when this column is NULL. |
| `PRIMARY_STREAM` | What the wellbore produces or handles, as declared, from a controlled vocabulary (OIL, GAS, `OIL_AND_GAS`, WATER, BRINE, WASTE, HELIUM, CO2, STEAM, BITUMEN, LITHIUM, POTASH, CBM, POLYMER, SOLVENT, AIR, `ACID_GAS`, DRY). Pairs with `WELLBORE_TYPE_NORMALIZED`: GAS on a STORAGE or DISPOSAL wellbore is gas stored or disposed of, not produced. For gas producers use `WELLBORE_TYPE_NORMALIZED` = 'PRODUCER' AND `PRIMARY_STREAM` IN ('GAS', '`OIL_AND_GAS`', 'CBM'); `OIL_AND_GAS` is a compound value, and coalbed methane wells currently carry GAS. Declared purpose, not observed production: a well declared for oil stays OIL while it dewaters, and the value asserts nothing about volumes. DRY appears only where a filed code classifies the bore as a dry hole, and then `WELLBORE_TYPE_NORMALIZED` is NULL. NULL when the source does not establish a stream. |
| `DIRECTION` | Novi's resolved well slant: the first of these that applies. `U_TURN_HORIZONTAL` when the calculated slant is a U-turn; HORIZONTAL when a directional survey not marked as planned shows a horizontal path; the normalized reported (filed) slant; the calculated slant. For a well whose survey-based resolution is not available, the survey step is skipped and the filed slant comes first. The filed wording is in `DIRECTION_REPORTED`. |
| `DIRECTION_REPORTED` | Raw reported slant/direction value from the state regulatory agency (e.g., "Horizontal", "Directional"). |
| `DIRECTION_REPORTED_NORMALIZED` | State-reported direction after normalization to a controlled vocabulary. |
| `DIRECTION_CALCULATED` | Slant that Novi infers from evidence other than the filed slant, such as the wellbore trajectory. It is derived, not filed. |
| `MD_TD` | Measured depth at TD in feet. |
| `TVD_TD` | True vertical depth at TD in feet. |
| `KB_ELEVATION` | Kelly bushing elevation in feet above sea level. |
| `SURFACE_LATITUDE` | Surface hole latitude in decimal degrees, from the well's CURRENT surface location, the latest surveyed row per the collapse rule, not an arbitrary one. |
| `SURFACE_LONGITUDE` | Surface hole longitude in decimal degrees, from the well's CURRENT surface location, see the collapse rule. |
| `CRS` | Coordinate reference system for the latitude and longitude columns on this row, as an EPSG code. Every populated row reads 'EPSG:4326' (WGS 84), so coordinates need no reprojection before use; the column is NULL where no coordinate is available. |
| `HEELPOINT_LATITUDE` | Latitude of the lateral heel point in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `HEELPOINT_LONGITUDE` | Longitude of the lateral heel point in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `LANDING_POINT_LATITUDE` | Latitude of the landing point in decimal degrees, WGS84. |
| `LANDING_POINT_LONGITUDE` | Longitude of the landing point in decimal degrees, WGS84. |
| `MIDPOINT_LATITUDE` | Latitude of the approximate lateral midpoint in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `MIDPOINT_LONGITUDE` | Longitude of the approximate lateral midpoint in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `BOTTOM_HOLE_LATITUDE` | Latitude of the bottom hole location in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `BOTTOM_HOLE_LONGITUDE` | Longitude of the bottom hole location in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `SPUD_DATE` | Date drilling began on this wellbore: the earliest SPUD event for the wellbore in `WELL_EVENT` (`EVENT_DT`, else `EFFECTIVE_DT`), truncated to a date in UTC. `WELL_EVENT` is the only source; NULL where it has no SPUD event for the wellbore. |
| `TD_DATE` | Date total depth was reached. Same rule as `SPUD_DATE`. Aggregated with MIN because the ledger permits more than one event of a type per wellbore, and this view is one row per wellbore; event\_dt is optional on the ledger so effective\_dt is the fallback, and the date-time is truncated in UTC. |
| `COMPLETION_DATE` | Date the wellbore was completed. Two sources: pivot from the well\_event ledger (event\_type = COMPLETED), else the first completion's well\_completion.completion\_end\_date. Aggregated with MIN because the ledger permits more than one event of a type per wellbore, and this view is one row per wellbore; event\_dt is optional on the ledger so effective\_dt is the fallback, and the date-time is truncated in UTC. |
| `FIRST_PRODUCTION_DATE` | Date of first reported production (turn-in-line): the earliest TIL event for the wellbore in `WELL_EVENT` (`EVENT_DT`, else `EFFECTIVE_DT`), truncated to a date in UTC. `WELL_EVENT` is the only source; NULL where it has no TIL event for the wellbore. |
| `PA_DATE` | Date the wellbore was plugged and abandoned. Same rule as `SPUD_DATE`. Aggregated with MIN because the ledger permits more than one event of a type per wellbore, and this view is one row per wellbore; event\_dt is optional on the ledger so effective\_dt is the fallback, and the date-time is truncated in UTC. |
| `PROPOSED_TVD` | Proposed true vertical depth as declared in the permit application, in feet. The as-built value is wellbore.tvd\_td once drilled. |
| `CUM_OIL_12_REPORTED` | Reported volumes only; excludes forecast volumes. Oil volume accumulated through the twelfth month on production. It may include condensate. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_OIL_24_REPORTED` | Reported volumes only; excludes forecast volumes. Oil volume accumulated through the twenty-fourth month on production. It may include condensate. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_OIL_LIFE_REPORTED` | Reported volumes only; excludes forecast volumes. Oil volume over the well's full reported history. It may include condensate. Additive across wellbores; not across time within a wellbore; it is already a running total. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `CUM_GAS_12_REPORTED` | Reported volumes only; excludes forecast volumes. Gas volume over the first 12 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_GAS_24_REPORTED` | Reported volumes only; excludes forecast volumes. Gas volume over the first 24 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_GAS_LIFE_REPORTED` | Reported volumes only; excludes forecast volumes. Gas volume over the well's full reported history. Additive across wellbores; not across time within a wellbore; it is already a running total. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `CUM_WATER_12_REPORTED` | Reported volumes only; excludes forecast volumes. Water volume over the first 12 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_WATER_24_REPORTED` | Reported volumes only; excludes forecast volumes. Water volume over the first 24 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_WATER_LIFE_REPORTED` | Reported volumes only; excludes forecast volumes. Water volume over the well's full reported history. Additive across wellbores; not across time within a wellbore; it is already a running total. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `CUM_BOE_12_REPORTED` | Reported volumes only; excludes forecast volumes. Barrel-of-oil-equivalent volume over the first 12 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. BOE comprises oil, condensate and gas at 6 Mcf = 1 BOE, and excludes NGL. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_BOE_24_REPORTED` | Reported volumes only; excludes forecast volumes. Barrel-of-oil-equivalent volume over the first 24 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. BOE comprises oil, condensate and gas at 6 Mcf = 1 BOE, and excludes NGL. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_BOE_LIFE_REPORTED` | Reported volumes only; excludes forecast volumes. Barrel-of-oil-equivalent volume over the well's full reported history. Additive across wellbores; not across time within a wellbore; it is already a running total. BOE comprises oil, condensate and gas at 6 Mcf = 1 BOE, and excludes NGL. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `PEAK_MONTH_OIL_INDEX` | Index on the months-on-production axis of the month in which combined oil and condensate volume peaked. The peak is selected on the combined volume, so on a condensate-rich well this can name a different month than an oil-only peak would. Ties resolve to the earliest such month. Non-additive. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_OIL_AMOUNT` | Combined oil and condensate volume in that peak month. A volume, not a rate. Non-additive across wellbores. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_GAS_INDEX` | Index on the months-on-production axis of the month in which gas volume peaked. Non-additive. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_GAS_AMOUNT` | Gas volume in that peak month. Non-additive across wellbores. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_WATER_INDEX` | Index on the months-on-production axis of the month in which water volume peaked. Non-additive. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_WATER_AMOUNT` | Water volume in that peak month. Non-additive across wellbores. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_BOE_INDEX` | Index on the months-on-production axis of the month in which barrel-of-oil-equivalent volume peaked. The monthly BOE this peak is selected on is oil and gas at 6 Mcf = 1 BOE and EXCLUDES condensate, unlike the cumulative BOE columns, which include it, so on a condensate-rich well the peak month can differ from the one a condensate-inclusive BOE would select. Non-additive. Null when no month carried a positive total: a zero maximum is not a peak. |
| `PEAK_MONTH_BOE_AMOUNT` | Barrel-of-oil-equivalent volume in that peak month, as oil and gas at 6 Mcf = 1 BOE. EXCLUDES condensate and NGL, a narrower basis than the cumulative BOE columns, which include condensate. Non-additive across wellbores. Null when no month carried a positive total: a zero maximum is not a peak. |
| `CUM_LIFE_GOR` | Life-to-date producing gas-oil ratio: life gas over life liquid, where the liquid denominator is the oil that cum\_oil\_life\_reported carries, which may include condensate. Null when that liquid total is zero, so a gas-only well has no value here rather than an infinite one. Rounded to two decimal places. NON-ADDITIVE, never sum or average across wellbores; recompute from the underlying volumes. Recomputing it needs cum\_gas\_life\_reported and cum\_oil\_life\_reported, which are not guaranteed present on the same row. |
| `LAST_REPORTED_MONTHS_ON_PRODUCTION` | Index on the months-on-production axis of the last month with reported production. An index, not a count: it identifies a month, it does not total them. Reported rather than derived from the monthly production fact, and not guaranteed to agree with an index computed from it. Non-additive. |
| `LAST_REPORTED_MONTH` | First day of the last month in which the well reported a positive combined volume of oil, condensate, gas, flared gas and water. A month whose volumes are all zero or unreported does not count, so a well that has gone to zero carries the last month before it did. Reported rather than derived from the monthly production fact, and not guaranteed to equal a month computed from it. Non-additive. Null when no month qualifies. |
| `COMPLETION_SEQUENCE` | Ordinal of the completion within the wellbore, ascending. This view is first-completion grain, so it is 1 on every row; recompletions and re-fracs are not projected here. |
| `COMPLETION_STATE` | Completion lifecycle state (derived from events or operational tracking). |
| `COMPLETION_END_DATE` | Date completion operations ended (if known). |
| `PROPPANT_MASS` | Total proppant mass injected during completion. |
| `FLUID_VOLUME` | Total completion fluid volume injected, in gallons. |
| `STAGE_COUNT` | Number of frac stages completed. Omit the field when the stage count is unknown. Do not store 0 for unknown, 0 is not a valid stage count. |
| `PERFORATION_UPPER` | Shallowest perforation depth (MD) in feet. |
| `PERFORATION_LOWER` | Deepest perforation depth (MD) in feet. |
| `PERFORATION_INTERVAL` | Perforation interval length in feet (perforation\_lower - perforation\_upper). |
| `PROPPANT_LOADING` | Proppant mass per foot of lateral, computed by Novi rather than from columns in this view. Non-additive ratio, never sum across wellbores. Its denominator is the selected lateral length, `LATERAL_LENGTH` in this view, with its method in `LATERAL_LENGTH_SOURCE`; the ratio need not equal `PROPPANT_MASS` / `LATERAL_LENGTH` on every row. A peer-set figure is an average of ratios rather than a ratio of totals. Values above 9,000 lb/ft are nulled as physically impossible rather than clamped, so a NULL can mean no credible ratio exists for the well even when `PROPPANT_MASS` is present. Also NULL when Novi's selected lateral length for the well is unknown or zero. That nulling is the guarantee this column carries: the denominator is chosen per well from perforations, survey points or depth, and falls back to a surface-to-bottom-hole distance, so it is not a single stated method. |
| `PROPPANT_CONCENTRATION` | Proppant mass per gallon of completion fluid, slurry concentration, independent of lateral length, computed by Novi rather than from columns in this view. Non-additive ratio, never sum across wellbores. NULL when proppant mass or fluid volume is unknown or zero, and when the ratio exceeds 8 lb/gal, which Novi treats as not credible; values above 8 are nulled, not clamped. Rounded to 2 decimal places. |
| `STAGE_SPACING` | Average distance between frac stages of the first completion, in feet: the lateral length Novi selected for the well divided by the first completion's stage count. Non-additive ratio, never sum across wellbores. That lateral length is `LATERAL_LENGTH` in this view, with its method in `LATERAL_LENGTH_SOURCE`; the value need not equal `LATERAL_LENGTH` divided by `STAGE_COUNT` on every row. NULL when the stage count is zero or that lateral length is unknown. Whole feet. No bounds are applied, so implausibly large or small values (a few under 20 ft) are possible and are published as computed. |
| `IS_CHILD` | True if this well is classified as a child well (drilled after nearby parent wells were producing). |
| `PARENT_COUNT` | Number of neighboring parent wells meeting spacing criteria. |
| `PARENT_DAYS_ONLINE` | Days the nearest parent well was online relative to this well's start. |
| `CLOSEST_WELL_XY` | XY distance to the closest lateral and staggered neighbor in feet. Non-additive. |
| `CLOSEST_TWO_AVG_XY` | Average XY distance to the two closest neighbors (includes staggered and stacked). Non-additive. |
| `WELLS_IN_RADIUS` | Count of all wells within the neighbor distance radius. |
| `WELLS_IN_RADIUS_AVG_XY` | Total wells in radius converted to a distance = 2 \* MaxNeighborDistance / (1 + WellsInRadius). Non-additive. |
| `LATERAL_CLOSER_XY` | XY distance to the nearest well in the same lateral row. Non-additive. |
| `STAGGER_CLOSER_TANGENT` | Tangent distance to the nearest staggered well. Non-additive. |
| `STACK_CLOSER_Z` | Vertical distance to the nearest well in the same vertical stack. Non-additive. |
| `BOUNDEDNESS_SCORE` | Number of neighbor quadrants occupied by wells (0-8). Non-additive. |
| `LATEST_OIL_GRAVITY` | Most recent oil API gravity reported for the well this wellbore belongs to, in degrees API. Oil and gas gravities are reported independently and may come from different tests. NULL when none is reported. |
| `LATEST_OIL_GRAVITY_TEST_DATE` | Date of the latest well test, on any wellbore of the well, that reports an oil gravity: the test behind `LATEST_OIL_GRAVITY`. NULL together with it. |
| `LATEST_GAS_GRAVITY` | Most recent gas specific gravity reported for the well this wellbore belongs to (air = 1.0). Not necessarily from the same test as `LATEST_OIL_GRAVITY`. NULL when none is reported. |
| `LATEST_GAS_GRAVITY_TEST_DATE` | Date of the latest well test, on any wellbore of the well, that reports a gas specific gravity: the test behind `LATEST_GAS_GRAVITY`. NULL together with it. |
| `SOAK_TIME_DAYS` | Number of days between the end of the first completion and the start of production (the soak period). NULL when the span is zero or negative, longer than 365 days, or shorter than 30 days where the first-production date is not known accurately. Do not sum across wellbores. |
| `EUR_OIL_20YR` | Forecast estimated ultimate recovery of oil through the first 20 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_GAS_20YR` | Forecast estimated ultimate recovery of gas through the first 20 years on production, in Mcf. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole Mcf: 0 where the forecast is under one Mcf or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_WATER_20YR` | Forecast estimated ultimate recovery of water through the first 20 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_BOE_20YR` | Forecast estimated ultimate recovery through the first 20 years on production, in barrels of oil equivalent at 6 Mcf = 1 bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole BOE: 0 where the forecast is under one BOE or states no volume; NULL where no forecast value exists at this horizon. |
| `EUR_OIL_30YR` | Forecast estimated ultimate recovery of oil through the first 30 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_GAS_30YR` | Forecast estimated ultimate recovery of gas through the first 30 years on production, in Mcf. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole Mcf: 0 where the forecast is under one Mcf or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_WATER_30YR` | Forecast estimated ultimate recovery of water through the first 30 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_BOE_30YR` | Forecast estimated ultimate recovery through the first 30 years on production, in barrels of oil equivalent at 6 Mcf = 1 bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole BOE: 0 where the forecast is under one BOE or states no volume; NULL where no forecast value exists at this horizon. |
| `EUR_OIL_50YR` | Forecast estimated ultimate recovery of oil through the first 50 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_GAS_50YR` | Forecast estimated ultimate recovery of gas through the first 50 years on production, in Mcf. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole Mcf: 0 where the forecast is under one Mcf or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_WATER_50YR` | Forecast estimated ultimate recovery of water through the first 50 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_BOE_50YR` | Forecast estimated ultimate recovery through the first 50 years on production, in barrels of oil equivalent at 6 Mcf = 1 bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole BOE: 0 where the forecast is under one BOE or states no volume; NULL where no forecast value exists at this horizon. |
| `OPERATOR_REPORTED` | The well's current operator as reported for the well: a name, not resolved to an OPERATOR row (`OPERATOR_ID` carries the resolved operator). May hold a placeholder where no operator is assigned. A current value, not a history. NULL where no operator is reported. |
| `OPERATOR_ORIGINAL` | The well's operator as of first production: a name, not resolved to an OPERATOR row. It does not change when the well later changes operator. NULL where no original operator is recorded. |
| `LATERAL_LENGTH` | Selected lateral length in feet: a manual override where one exists, otherwise the first populated of `LATERAL_LENGTH_CALCULATED_U_TURN`, `LATERAL_LENGTH_CALCULATED_PERF`, `LATERAL_LENGTH_CALCULATED_LP_TO_BHL`, `LATERAL_LENGTH_CALCULATED_KP_TO_BHL`, `LATERAL_LENGTH_CALCULATED_MD_TVD` and `LATERAL_LENGTH_CALCULATED_SHL_BHL`, in that order. The method varies by row and is named in `LATERAL_LENGTH_SOURCE`, so values are not comparable across rows without it. Non-additive. NULL when no method yields a value, and then `LATERAL_LENGTH_SOURCE` is NULL too. |
| `LATERAL_LENGTH_SOURCE` | Label of the method that produced `LATERAL_LENGTH`, such as 'Manual Override', 'PerforationTop-PerforationBottom' or 'Landing-Bottom'. Distinguishes methods that share a calculated column, such as landing point to bottom hole and landing point to measured depth. NULL when `LATERAL_LENGTH` is NULL. |
| `LAST_REFRAC_DATE` | Date of the most recent refrac (re-stimulation after the original frac) on the wellbore, from the REFRAC event in `WELL_EVENT`: the latest event\_dt, with effective\_dt as the fallback, truncated to a date in UTC. NULL when `WELL_EVENT` carries no REFRAC event for the wellbore, which includes every wellbore whose `REFRAC_COUNT` is 0. |
| `REFRAC_COUNT` | Carried from WELLBORE.`REFRAC_COUNT`. Number of refracs (re-stimulations after the original frac) reported for this wellbore's well; 0 when none is reported. Reported by the source, not counted from `WELL_EVENT`, which carries only the most recent REFRAC event, so a well with a count of 2 or 3 still has one REFRAC event. NULL when no count is reported, which includes every Canadian wellbore. |
| `DIRECTIONAL_SURVEY_AVAILABLE` | True when directional survey stations are reported for the wellbore, false when none are. Reported by the source rather than computed from `DIRECTIONAL_SURVEY_STATION`, so the two can briefly disagree while a new survey loads. NULL when survey coverage is not reported, which includes every Canadian wellbore. |
| `PLANNED_AS_DRILLED_SURVEY` | Whether the wellbore's directional survey is a planned trajectory (PLANNED) or one measured in the drilled hole (`AS_DRILLED`), as the source reports it. NULL when `DIRECTIONAL_SURVEY_AVAILABLE` is false or NULL, which includes every Canadian wellbore. |
| `WELLBORE_TYPE` | The wellbore's declared operational function. It equals `WELLBORE_TYPE_NORMALIZED` and has the same values, meaning and limits; read that column's description. NULL wherever `WELLBORE_TYPE_NORMALIZED` is NULL. |
| `COUNTY_CODE` | Five-digit FIPS code of the county (or parish in Louisiana) where the well is located (e.g., "48389" for Reeves County, Texas). The name is in COUNTY. |
## WELLBORE_HEADER
Identity, jurisdiction, geology, operator, status and lifecycle dates. Grain: One row per wellbore\_key.
| Column | Description |
| --- | --- |
| `WELLBORE_KEY` | Surrogate key for the wellbore row, a stable string composed as {country}:{native\_id\_type}:{native\_id}:{sequence\_number} (e.g. US:API14:42123405670000:0). Consistent with this row's country, native\_id\_type, native\_id, and sequence\_number. |
| `WELL_KEY` | Foreign key to well.well\_key, linking this wellbore to its parent well. |
| `NATIVE_ID` | Wellbore-level identifier. For regulatory schemes (API10/API14/UWI-DLS) this is the external regulatory id, API14 captures the sidetrack/event suffix (positions 11-14) that disambiguates per-wellbore borehole+event; the well-level well.native\_id carries the well-level root (API10 for US, UWI-DLS for Canada). Use the contiguous 14-digit API14 (digits only, no hyphens). For the PLANNED scheme (planned wellbores with no regulatory id yet) this is the Novi-internal id (the planned\_well\_id). The scheme is named by native\_id\_type, which conditionally validates this value's canonical format per scheme; this value is the third component of wellbore\_key. |
| `OPERATOR_ID` | Current operator of record. Historical changes should be captured as events (e.g., `OPERATOR_CHANGE`) or in a dedicated attribute history. |
| `PERMIT_ID` | Regulatory permit identifier as issued by the state/agency. Primary key for the permit record. |
| `NATIVE_ID_TYPE` | Identifier scheme of native\_id (API10, API14, UWI-DLS, or PLANNED). API14 when a borehole/event suffix is available, otherwise API10 (e.g. single-wellbore wells or API10-only sources), UWI-DLS in Canada, or PLANNED for planned wellbores with no regulatory identifier yet. Second component of wellbore\_key. |
| `COUNTRY` | Two-letter ISO 3166-1 alpha-2 country code where the wellbore is located (e.g., US, CA). First component of wellbore\_key; matches the parent well.country. |
| `SEQUENCE_NUMBER` | Ordinal distinguishing wellbores that share a native\_id, part of the conformed identity (native\_id + native\_id\_type + country + sequence\_number). It is 0 on every row in current data, no native\_id yet resolves to more than one wellbore, and is retained because the identity is only unique with it. |
| `WELL_NAME` | Human-friendly well name (operator or regulatory naming). Use for display; not a key. |
| `FIELD_NAME` | Name of the oil/gas field the well is in. |
| `STATE` | US state (USPS two-letter) or Canadian province/territory (Statistics Canada two-letter) code where the well is located. |
| `COUNTY` | Name of the county (or parish in Louisiana) where the well is located, as reported (e.g., "Reeves"); a name, never a code. The FIPS code is in `COUNTY_CODE`. NULL when not reported. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `FORMATION` | Canonical formation name used for analytics grouping. Represents Novi's best estimate of the landing zone formation. |
| `FORMATION_REPORTED` | Formation name as reported by the data source (raw regulatory filing string). |
| `FORMATION_REPORTED_NORMALIZED` | Source-reported formation mapped to a controlled vocabulary. |
| `FORMATION_CALCULATED` | Novi-calculated formation based on wellbore geometry and formation tops (structural depth grids). Used as the standard grouping key for peer comparison. |
| `CURRENT_OPERATOR` | Operator of record for this wellbore's well as of today, resolved to the canonical operator name, which is stored unmodified and may carry padding. Use this for grouping peers; never group on a raw reported name. |
| `WELL_STATUS` | Current coarse lifecycle state of the well (derived from events). Includes 7 milestone-based values and 9 regulatory/operational ones; semantic overlaps (e.g. PERMITTED/`PERMIT_APPROVED`, DRILLING/SPUD, PRODUCING/ACTIVE, `SHUT_IN`/INACTIVE) are deliberately preserved as distinct values so you can tell which source vocabulary a row came from. Details live in well\_event. |
| `WELLBORE_STATUS` | Current lifecycle state for the wellbore (can differ from the well-level status). |
| `WELLBORE_STATUS_REPORTED` | Raw reported wellbore status value from the regulator filing, at wellbore grain (analogous to well.status\_reported but for a specific lateral / sidetrack / re-entry). Independent input from well.status\_reported, wellbore status can differ from well status. |
| `WELLBORE_STATUS_REPORTED_NORMALIZED` | Reported wellbore status mapped to a controlled vocabulary, at wellbore grain (analogous to well.status\_reported\_normalized). Distinct from wellbore.status (Novi-curated lifecycle enum); the reported/normalized pair preserves provenance for audit. |
| `WELLBORE_TYPE_NORMALIZED` | What the wellbore does: its declared operational function, from a controlled vocabulary (PRODUCER, INJECTOR, DISPOSAL, CYCLIC, STORAGE, `OBSERVATION_TEST`, and drainage and thermal-recovery roles). It is the declared function, not current activity: a plugged or shut-in producer stays PRODUCER, so use `WELLBORE_STATUS` for activity. What the wellbore produces or handles is on `PRIMARY_STREAM`. Functions other than PRODUCER come only from a recognised filed code in `WELLBORE_TYPE_REPORTED`; without one (for example, every Texas wellbore) the value is PRODUCER or NULL, so counts of injection, disposal or storage wells are incomplete there. NULL when the source does not establish a function, for example a dry hole (`PRIMARY_STREAM` = DRY) or a service well whose filing does not say which service. |
| `WELLBORE_TYPE_REPORTED` | The well-type code the source supplies for the regulator filing, trimmed and otherwise as filed. Codes, case and spelling vary by jurisdiction; they are not a controlled vocabulary. NULL where the source supplies no code (currently all Texas wellbores and most in Kansas and West Virginia). `WELLBORE_TYPE_NORMALIZED` and `PRIMARY_STREAM` use this code where it is recognised and a coarser classification otherwise, so they can hold a value when this column is NULL. |
| `PRIMARY_STREAM` | What the wellbore produces or handles, as declared, from a controlled vocabulary (OIL, GAS, `OIL_AND_GAS`, WATER, BRINE, WASTE, HELIUM, CO2, STEAM, BITUMEN, LITHIUM, POTASH, CBM, POLYMER, SOLVENT, AIR, `ACID_GAS`, DRY). Pairs with `WELLBORE_TYPE_NORMALIZED`: GAS on a STORAGE or DISPOSAL wellbore is gas stored or disposed of, not produced. For gas producers use `WELLBORE_TYPE_NORMALIZED` = 'PRODUCER' AND `PRIMARY_STREAM` IN ('GAS', '`OIL_AND_GAS`', 'CBM'); `OIL_AND_GAS` is a compound value, and coalbed methane wells currently carry GAS. Declared purpose, not observed production: a well declared for oil stays OIL while it dewaters, and the value asserts nothing about volumes. DRY appears only where a filed code classifies the bore as a dry hole, and then `WELLBORE_TYPE_NORMALIZED` is NULL. NULL when the source does not establish a stream. |
| `DIRECTION` | Novi's resolved well slant: the first of these that applies. `U_TURN_HORIZONTAL` when the calculated slant is a U-turn; HORIZONTAL when a directional survey not marked as planned shows a horizontal path; the normalized reported (filed) slant; the calculated slant. For a well whose survey-based resolution is not available, the survey step is skipped and the filed slant comes first. The filed wording is in `DIRECTION_REPORTED`. |
| `DIRECTION_REPORTED` | Raw reported slant/direction value from the state regulatory agency (e.g., "Horizontal", "Directional"). |
| `DIRECTION_REPORTED_NORMALIZED` | State-reported direction after normalization to a controlled vocabulary. |
| `DIRECTION_CALCULATED` | Slant that Novi infers from evidence other than the filed slant, such as the wellbore trajectory. It is derived, not filed. |
| `MD_TD` | Measured depth at TD in feet. |
| `TVD_TD` | True vertical depth at TD in feet. |
| `KB_ELEVATION` | Kelly bushing elevation in feet above sea level. |
| `SURFACE_LATITUDE` | Surface hole latitude in decimal degrees, from the well's CURRENT surface location, the latest surveyed row per the collapse rule, not an arbitrary one. |
| `SURFACE_LONGITUDE` | Surface hole longitude in decimal degrees, from the well's CURRENT surface location, see the collapse rule. |
| `CRS` | Coordinate reference system for the latitude and longitude columns on this row, as an EPSG code. Every populated row reads 'EPSG:4326' (WGS 84), so coordinates need no reprojection before use; the column is NULL where no coordinate is available. |
| `HEELPOINT_LATITUDE` | Latitude of the lateral heel point in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `HEELPOINT_LONGITUDE` | Longitude of the lateral heel point in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `LANDING_POINT_LATITUDE` | Latitude of the landing point in decimal degrees, WGS84. |
| `LANDING_POINT_LONGITUDE` | Longitude of the landing point in decimal degrees, WGS84. |
| `MIDPOINT_LATITUDE` | Latitude of the approximate lateral midpoint in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `MIDPOINT_LONGITUDE` | Longitude of the approximate lateral midpoint in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `BOTTOM_HOLE_LATITUDE` | Latitude of the bottom hole location in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `BOTTOM_HOLE_LONGITUDE` | Longitude of the bottom hole location in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `SPUD_DATE` | Date drilling began on this wellbore: the earliest SPUD event for the wellbore in `WELL_EVENT` (`EVENT_DT`, else `EFFECTIVE_DT`), truncated to a date in UTC. `WELL_EVENT` is the only source; NULL where it has no SPUD event for the wellbore. |
| `TD_DATE` | Date total depth was reached. Same rule as `SPUD_DATE`. Aggregated with MIN because the ledger permits more than one event of a type per wellbore, and this view is one row per wellbore; event\_dt is optional on the ledger so effective\_dt is the fallback, and the date-time is truncated in UTC. |
| `COMPLETION_DATE` | Date the wellbore was completed. Two sources: pivot from the well\_event ledger (event\_type = COMPLETED), else the first completion's well\_completion.completion\_end\_date. Aggregated with MIN because the ledger permits more than one event of a type per wellbore, and this view is one row per wellbore; event\_dt is optional on the ledger so effective\_dt is the fallback, and the date-time is truncated in UTC. |
| `FIRST_PRODUCTION_DATE` | Date of first reported production (turn-in-line): the earliest TIL event for the wellbore in `WELL_EVENT` (`EVENT_DT`, else `EFFECTIVE_DT`), truncated to a date in UTC. `WELL_EVENT` is the only source; NULL where it has no TIL event for the wellbore. |
| `PA_DATE` | Date the wellbore was plugged and abandoned. Same rule as `SPUD_DATE`. Aggregated with MIN because the ledger permits more than one event of a type per wellbore, and this view is one row per wellbore; event\_dt is optional on the ledger so effective\_dt is the fallback, and the date-time is truncated in UTC. |
| `PROPOSED_TVD` | Proposed true vertical depth as declared in the permit application, in feet. The as-built value is wellbore.tvd\_td once drilled. |
| `OPERATOR_REPORTED` | The well's current operator as reported for the well: a name, not resolved to an OPERATOR row (`OPERATOR_ID` carries the resolved operator). May hold a placeholder where no operator is assigned. A current value, not a history. NULL where no operator is reported. |
| `OPERATOR_ORIGINAL` | The well's operator as of first production: a name, not resolved to an OPERATOR row. It does not change when the well later changes operator. NULL where no original operator is recorded. |
| `LATERAL_LENGTH` | Selected lateral length in feet: a manual override where one exists, otherwise the first populated of `LATERAL_LENGTH_CALCULATED_U_TURN`, `LATERAL_LENGTH_CALCULATED_PERF`, `LATERAL_LENGTH_CALCULATED_LP_TO_BHL`, `LATERAL_LENGTH_CALCULATED_KP_TO_BHL`, `LATERAL_LENGTH_CALCULATED_MD_TVD` and `LATERAL_LENGTH_CALCULATED_SHL_BHL`, in that order. The method varies by row and is named in `LATERAL_LENGTH_SOURCE`, so values are not comparable across rows without it. Non-additive. NULL when no method yields a value, and then `LATERAL_LENGTH_SOURCE` is NULL too. |
| `LATERAL_LENGTH_SOURCE` | Label of the method that produced `LATERAL_LENGTH`, such as 'Manual Override', 'PerforationTop-PerforationBottom' or 'Landing-Bottom'. Distinguishes methods that share a calculated column, such as landing point to bottom hole and landing point to measured depth. NULL when `LATERAL_LENGTH` is NULL. |
| `LAST_REFRAC_DATE` | Date of the most recent refrac (re-stimulation after the original frac) on the wellbore, from the REFRAC event in `WELL_EVENT`: the latest event\_dt, with effective\_dt as the fallback, truncated to a date in UTC. NULL when `WELL_EVENT` carries no REFRAC event for the wellbore, which includes every wellbore whose `REFRAC_COUNT` is 0. |
| `DIRECTIONAL_SURVEY_AVAILABLE` | True when directional survey stations are reported for the wellbore, false when none are. Reported by the source rather than computed from `DIRECTIONAL_SURVEY_STATION`, so the two can briefly disagree while a new survey loads. NULL when survey coverage is not reported, which includes every Canadian wellbore. |
| `PLANNED_AS_DRILLED_SURVEY` | Whether the wellbore's directional survey is a planned trajectory (PLANNED) or one measured in the drilled hole (`AS_DRILLED`), as the source reports it. NULL when `DIRECTIONAL_SURVEY_AVAILABLE` is false or NULL, which includes every Canadian wellbore. |
| `WELLBORE_TYPE` | The wellbore's declared operational function. It equals `WELLBORE_TYPE_NORMALIZED` and has the same values, meaning and limits; read that column's description. NULL wherever `WELLBORE_TYPE_NORMALIZED` is NULL. |
| `COUNTY_CODE` | Five-digit FIPS code of the county (or parish in Louisiana) where the well is located (e.g., "48389" for Reeves County, Texas). The name is in COUNTY. |
| `LATEST_OIL_GRAVITY` | Most recent oil API gravity reported for the well this wellbore belongs to, in degrees API; the same on every wellbore of the well. Oil and gas gravities are reported independently and may come from different tests. NULL when none is reported. |
| `LATEST_OIL_GRAVITY_TEST_DATE` | Date of the latest well test, on any wellbore of the well, that reports an oil gravity: the test behind `LATEST_OIL_GRAVITY`. NULL together with it. |
| `LATEST_GAS_GRAVITY` | Most recent gas specific gravity reported for the well this wellbore belongs to (air = 1.0); the same on every wellbore of the well. Not necessarily from the same test as `LATEST_OIL_GRAVITY`. NULL when none is reported. |
| `LATEST_GAS_GRAVITY_TEST_DATE` | Date of the latest well test, on any wellbore of the well, that reports a gas specific gravity: the test behind `LATEST_GAS_GRAVITY`. NULL together with it. |
## WELLBORE_COMPLETION_DESIGN
First-completion design plus intensity ratios. Grain: One row per wellbore\_key, first completion (completion\_sequence = 1).
| Column | Description |
| --- | --- |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key. |
| `NATIVE_ID` | Regulatory identifier of the wellbore this row belongs to, the same value as `WELLBORE_HEADER`.`NATIVE_ID`, so the row can be joined to data outside `NOVI_WELLS`. Its scheme (API10, API14, UWI-DLS, UWI-NTS or PLANNED) is `NATIVE_ID_TYPE`. Not a unique bore key: an API10 does not distinguish the bores of a multi-lateral, so join rows on `WELLBORE_KEY`. |
| `WELL_COMPLETION_ID` | Surrogate key of the completion event this row collapsed to, the first completion. Carried so a consumer can trace back to the source row and audit the collapse. |
| `NATIVE_ID_TYPE` | Identifier scheme of `NATIVE_ID` (API10, API14, UWI-DLS, UWI-NTS or PLANNED), the same value as `WELLBORE_HEADER`.`NATIVE_ID_TYPE`. |
| `COMPLETION_SEQUENCE` | Ordinal of the completion within the wellbore, ascending. This view is first-completion grain, so it is 1 on every row; recompletions and re-fracs are not projected here. |
| `COMPLETION_STATE` | Completion lifecycle state (derived from events or operational tracking). |
| `COMPLETION_END_DATE` | Date completion operations ended (if known). |
| `PROPPANT_MASS` | Total proppant mass injected during completion. |
| `FLUID_VOLUME` | Total completion fluid volume injected, in gallons. |
| `STAGE_COUNT` | Number of frac stages completed. Omit the field when the stage count is unknown. Do not store 0 for unknown, 0 is not a valid stage count. |
| `PERFORATION_UPPER` | Shallowest perforation depth (MD) in feet. |
| `PERFORATION_LOWER` | Deepest perforation depth (MD) in feet. |
| `PERFORATION_INTERVAL` | Perforation interval length in feet (perforation\_lower - perforation\_upper). |
| `PROPPANT_LOADING` | Proppant mass per foot of lateral, computed by Novi rather than from columns in this view. Non-additive ratio, never sum across wellbores. It cannot be recomputed from this view, which does not carry its denominator, the selected lateral length, published as `LATERAL_LENGTH` on `WELLBORE_HEADER` and `WELL_DETAIL` with its method in `LATERAL_LENGTH_SOURCE`; a peer-set figure is an average of ratios rather than a ratio of totals. Values above 9,000 lb/ft are nulled as physically impossible rather than clamped, so a NULL can mean no credible ratio exists for the well even when `PROPPANT_MASS` is present. Also NULL when Novi's selected lateral length for the well is unknown or zero. That nulling is the guarantee this column carries: the denominator is chosen per well from perforations, survey points or depth, and falls back to a surface-to-bottom-hole distance, so it is not a single stated method. |
| `PROPPANT_CONCENTRATION` | Proppant mass per gallon of completion fluid, slurry concentration, independent of lateral length, computed by Novi rather than from columns in this view. Non-additive ratio, never sum across wellbores. NULL when proppant mass or fluid volume is unknown or zero, and when the ratio exceeds 8 lb/gal, which Novi treats as not credible; values above 8 are nulled, not clamped. Rounded to 2 decimal places. |
| `STAGE_SPACING` | Average distance between frac stages of the first completion, in feet: the lateral length Novi selected for the well divided by the first completion's stage count. Non-additive ratio, never sum across wellbores. It cannot be recomputed from this view, which does not carry that lateral length; `WELLBORE_HEADER` and `WELL_DETAIL` publish it as `LATERAL_LENGTH`, with its method in `LATERAL_LENGTH_SOURCE`. NULL when the stage count is zero or that lateral length is unknown. Whole feet. No bounds are applied, so implausibly large or small values (a few under 20 ft) are possible and are published as computed. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `SOAK_TIME_DAYS` | Number of days between the end of the first completion and the start of production (the soak period). NULL when the span is zero or negative, longer than 365 days, or shorter than 30 days where the first-production date is not known accurately. Do not sum across wellbores. |
## WELLBORE_PRODUCTION_SUMMARY
Production roll-ups as the source of record reports them per well, carried rather than recomputed: cumulative oil, gas, water and BOE at the 12-month, 24-month and life horizons; the peak producing month for each stream; life-to-date gas-oil ratio; and the index of the last month with reported production; and forecast EUR at 20, 30 and 50 years per stream, which is a forecast rather than reported production. Cumulative volume columns end in \_REPORTED: reported volumes only, no forecast. Grain: one row per wellbore\_key, carried on the well's lowest-sequence bore. A value this view does not carry is one the source of record does not report, and NULL means exactly that, not that a window was incomplete. IP rates, the 3- and 6-month windows, the 12-month ratios and the producing-time columns are no longer projected here; compute them from `PRODUCTION_MONTHLY`, which owns those definitions. Oil as reported includes condensate; whether forecast EUR oil does is not defined.
| Column | Description |
| --- | --- |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key. |
| `NATIVE_ID` | Regulatory identifier of the wellbore this row belongs to, the same value as `WELLBORE_HEADER`.`NATIVE_ID`, so the row can be joined to data outside `NOVI_WELLS`. Its scheme (API10, API14, UWI-DLS, UWI-NTS or PLANNED) is `NATIVE_ID_TYPE`. Not a unique bore key: an API10 does not distinguish the bores of a multi-lateral, so join rows on `WELLBORE_KEY`. |
| `NATIVE_ID_TYPE` | Identifier scheme of `NATIVE_ID` (API10, API14, UWI-DLS, UWI-NTS or PLANNED), the same value as `WELLBORE_HEADER`.`NATIVE_ID_TYPE`. |
| `CUM_OIL_12_REPORTED` | Reported volumes only; excludes forecast volumes. Oil volume accumulated through the twelfth month on production. It may include condensate. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_OIL_24_REPORTED` | Reported volumes only; excludes forecast volumes. Oil volume accumulated through the twenty-fourth month on production. It may include condensate. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_OIL_LIFE_REPORTED` | Reported volumes only; excludes forecast volumes. Oil volume over the well's full reported history. It may include condensate. Additive across wellbores; not across time within a wellbore; it is already a running total. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `CUM_GAS_12_REPORTED` | Reported volumes only; excludes forecast volumes. Gas volume over the first 12 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_GAS_24_REPORTED` | Reported volumes only; excludes forecast volumes. Gas volume over the first 24 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_GAS_LIFE_REPORTED` | Reported volumes only; excludes forecast volumes. Gas volume over the well's full reported history. Additive across wellbores; not across time within a wellbore; it is already a running total. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `CUM_WATER_12_REPORTED` | Reported volumes only; excludes forecast volumes. Water volume over the first 12 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_WATER_24_REPORTED` | Reported volumes only; excludes forecast volumes. Water volume over the first 24 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_WATER_LIFE_REPORTED` | Reported volumes only; excludes forecast volumes. Water volume over the well's full reported history. Additive across wellbores; not across time within a wellbore; it is already a running total. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `CUM_BOE_12_REPORTED` | Reported volumes only; excludes forecast volumes. Barrel-of-oil-equivalent volume over the first 12 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. BOE comprises oil, condensate and gas at 6 Mcf = 1 BOE, and excludes NGL. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_BOE_24_REPORTED` | Reported volumes only; excludes forecast volumes. Barrel-of-oil-equivalent volume over the first 24 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. BOE comprises oil, condensate and gas at 6 Mcf = 1 BOE, and excludes NGL. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_BOE_LIFE_REPORTED` | Reported volumes only; excludes forecast volumes. Barrel-of-oil-equivalent volume over the well's full reported history. Additive across wellbores; not across time within a wellbore; it is already a running total. BOE comprises oil, condensate and gas at 6 Mcf = 1 BOE, and excludes NGL. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `PEAK_MONTH_OIL_INDEX` | Index on the months-on-production axis of the month in which combined oil and condensate volume peaked. The peak is selected on the combined volume, so on a condensate-rich well this can name a different month than an oil-only peak would. Ties resolve to the earliest such month. Non-additive. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_OIL_AMOUNT` | Combined oil and condensate volume in that peak month. A volume, not a rate. Non-additive across wellbores. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_GAS_INDEX` | Index on the months-on-production axis of the month in which gas volume peaked. Non-additive. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_GAS_AMOUNT` | Gas volume in that peak month. Non-additive across wellbores. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_WATER_INDEX` | Index on the months-on-production axis of the month in which water volume peaked. Non-additive. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_WATER_AMOUNT` | Water volume in that peak month. Non-additive across wellbores. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_BOE_INDEX` | Index on the months-on-production axis of the month in which barrel-of-oil-equivalent volume peaked. The monthly BOE this peak is selected on is oil and gas at 6 Mcf = 1 BOE and EXCLUDES condensate, unlike the cumulative BOE columns, which include it, so on a condensate-rich well the peak month can differ from the one a condensate-inclusive BOE would select. Non-additive. Null when no month carried a positive total: a zero maximum is not a peak. |
| `PEAK_MONTH_BOE_AMOUNT` | Barrel-of-oil-equivalent volume in that peak month, as oil and gas at 6 Mcf = 1 BOE. EXCLUDES condensate and NGL, a narrower basis than the cumulative BOE columns, which include condensate. Non-additive across wellbores. Null when no month carried a positive total: a zero maximum is not a peak. |
| `CUM_LIFE_GOR` | Life-to-date producing gas-oil ratio: life gas over life liquid, where the liquid denominator is the oil that cum\_oil\_life\_reported carries, which may include condensate. Null when that liquid total is zero, so a gas-only well has no value here rather than an infinite one. Rounded to two decimal places. NON-ADDITIVE, never sum or average across wellbores; recompute from the underlying volumes. Recomputing it needs cum\_gas\_life\_reported and cum\_oil\_life\_reported, which are not guaranteed present on the same row. |
| `LAST_REPORTED_MONTHS_ON_PRODUCTION` | Index on the months-on-production axis of the last month with reported production. An index, not a count: it identifies a month, it does not total them. Reported rather than derived from the monthly production fact, and not guaranteed to agree with an index computed from it. Non-additive. |
| `LAST_REPORTED_MONTH` | First day of the last month in which the well reported a positive combined volume of oil, condensate, gas, flared gas and water. A month whose volumes are all zero or unreported does not count, so a well that has gone to zero carries the last month before it did. Reported rather than derived from the monthly production fact, and not guaranteed to equal a month computed from it. Non-additive. Null when no month qualifies. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `EUR_OIL_20YR` | Forecast estimated ultimate recovery of oil through the first 20 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_GAS_20YR` | Forecast estimated ultimate recovery of gas through the first 20 years on production, in Mcf. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole Mcf: 0 where the forecast is under one Mcf or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_WATER_20YR` | Forecast estimated ultimate recovery of water through the first 20 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_BOE_20YR` | Forecast estimated ultimate recovery through the first 20 years on production, in barrels of oil equivalent at 6 Mcf = 1 bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole BOE: 0 where the forecast is under one BOE or states no volume; NULL where no forecast value exists at this horizon. |
| `EUR_OIL_30YR` | Forecast estimated ultimate recovery of oil through the first 30 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_GAS_30YR` | Forecast estimated ultimate recovery of gas through the first 30 years on production, in Mcf. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole Mcf: 0 where the forecast is under one Mcf or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_WATER_30YR` | Forecast estimated ultimate recovery of water through the first 30 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_BOE_30YR` | Forecast estimated ultimate recovery through the first 30 years on production, in barrels of oil equivalent at 6 Mcf = 1 bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole BOE: 0 where the forecast is under one BOE or states no volume; NULL where no forecast value exists at this horizon. |
| `EUR_OIL_50YR` | Forecast estimated ultimate recovery of oil through the first 50 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_GAS_50YR` | Forecast estimated ultimate recovery of gas through the first 50 years on production, in Mcf. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole Mcf: 0 where the forecast is under one Mcf or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_WATER_50YR` | Forecast estimated ultimate recovery of water through the first 50 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_BOE_50YR` | Forecast estimated ultimate recovery through the first 50 years on production, in barrels of oil equivalent at 6 Mcf = 1 bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole BOE: 0 where the forecast is under one BOE or states no volume; NULL where no forecast value exists at this horizon. |
## WELLBORE_DECLINE_PARAMETERS
Arps parameters per segment per stream, shaped for ARIES export. Grain: One row per (wellbore\_key, production\_forecast\_id, production\_stream, segment\_number).
| Column | Description |
| --- | --- |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key. |
| `NATIVE_ID` | Regulatory identifier of the wellbore this row belongs to, the same value as `WELLBORE_HEADER`.`NATIVE_ID`, so the row can be joined to data outside `NOVI_WELLS`. Its scheme (API10, API14, UWI-DLS, UWI-NTS or PLANNED) is `NATIVE_ID_TYPE`. Not a unique bore key: an API10 does not distinguish the bores of a multi-lateral, so join rows on `WELLBORE_KEY`. |
| `PRODUCTION_FORECAST_ID` | Forecast run to which this segment belongs. Use to group segments and parameters by a single forecast execution. May be NULL when no parent production\_forecast row exists for this segment. |
| `NATIVE_ID_TYPE` | Identifier scheme of `NATIVE_ID` (API10, API14, UWI-DLS, UWI-NTS or PLANNED), the same value as `WELLBORE_HEADER`.`NATIVE_ID_TYPE`. |
| `PRODUCTION_STREAM` | Which stream this segment forecasts (e.g., oil, gas, ngl, water, condensate). |
| `SEGMENT_UID` | Stable, immutable unique identifier for this segment. |
| `SEGMENT_NUMBER` | 1-based index of the segment within the stream for the wellbore\_key. |
| `KIND` | ARPS regime represented by this segment: - buildup: early-time pre-decline behavior, - transition: changeover period between regimes, - terminal: late-time decline segment. |
| `SEGMENT_CURVE_TYPE` | Type of decline curve applied in this segment. 'exponential' assumes constant nominal decline D; 'hyperbolic' uses exponent b (0<b<1 typical; b=1 is harmonic); 'linear' is a buildup-phase ramp where rate increases linearly from segment\_start\_rate to segment\_end\_rate over (day\_stop - day\_start) days (no decline math applies). 'linear' is only valid when kind='buildup'. |
| `DAY_START` | Inclusive day index where this segment begins, in real calendar days since first production (0 = first day of production). This is the axis the segment's Arps parameters were fitted against and is the correct axis for evaluating the curve within this fact. It is NOT comparable to production\_forecast.forecast\_day, which is a nominal 30-day month ordinal rather than a day count; matching the two drifts by a median of 129 days and up to 236, well-specific and uncorrectable by a constant. To align this fact with production\_forecast, use segment\_start\_date / segment\_end\_date against year / month. |
| `DAY_STOP` | Inclusive day index where this segment ends, in real calendar days since first production. Must be >= day\_start for valid datasets (cannot be enforced portably in standard JSON Schema). Same axis and same caveats as day\_start; (day\_stop - day\_start) is the segment duration in days, used by the 'linear' segment\_curve\_type ramp. |
| `SEGMENT_START_DATE` | Calendar date on which this segment begins, inclusive (YYYY-MM-DD). The alignment axis between this fact and production\_forecast: a monthly forecast row belongs to the segments whose \[segment\_start\_date, segment\_end\_date\] range overlaps its year/month. Anchors the fitted curve to real calendar time, which is what evaluating a segment against actual monthly production requires. NULL when the wellbore has no calendar anchor (no first-production date), in which case consumers must fall back to the relative day\_start / day\_stop offsets. |
| `SEGMENT_END_DATE` | Calendar date on which this segment ends, inclusive (YYYY-MM-DD). NULL when the wellbore has no calendar anchor. See segment\_start\_date. |
| `B_FACTOR` | Arps hyperbolic exponent b for this segment. 0 = exponential, 1 = harmonic, 0 < b < 1 = hyperbolic. Non-additive, never average across wellbores. |
| `NOMINAL_DECLINE_RATE` | D\_nom, nominal decline parameter used in ARPS (1/day). Constant for exponential; initial value for hyperbolic at segment start. |
| `EFFECTIVE_DECLINE_RATE_TANGENT` | D\_eff (tangent), effective decline rate using the tangent (instantaneous) approximation over a 1-day interval (dimensionless fraction in \[0,1)). For exponential decline, D\_eff\_tangent = 1 - e^{-D\_nom}. This is the point-in-time derivative of the decline curve; use effective\_decline\_rate\_secant for the average-interval approximation. |
| `EFFECTIVE_DECLINE_RATE_SECANT` | D\_eff (secant), effective decline rate using the secant (average-interval) approximation over a 1-day interval (dimensionless fraction in \[0,1)). For exponential decline, D\_eff\_secant = 1 - (q(t+1)/q(t)). Secant is the discrete-period average decline; needed for ARIES export and reproducibility alongside the tangent approximation. |
| `SEGMENT_START_RATE` | Production rate at the start of this segment. This is qi for the first DECLINE segment, not necessarily segment\_number = 1, which may be a buildup segment. Non-additive. |
| `SEGMENT_END_RATE` | q\_end, production rate at the end of the segment (same units as stream). Should be <= q\_start for decline segments (cannot be enforced portably here). |
| `SEGMENT_PARAMETER_UID` | Stable unique identifier for this parameter row. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
## WELLBORE_SPACING_DETAIL
Parent/child classification and neighbour distances for interference work. Grain: One row per wellbore\_key.
| Column | Description |
| --- | --- |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key. |
| `WELL_SPACING_ID` | Surrogate key. |
| `NATIVE_ID` | Regulatory identifier of the wellbore this row belongs to, the same value as `WELLBORE_HEADER`.`NATIVE_ID`, so the row can be joined to data outside `NOVI_WELLS`. Its scheme (API10, API14, UWI-DLS, UWI-NTS or PLANNED) is `NATIVE_ID_TYPE`. Not a unique bore key: an API10 does not distinguish the bores of a multi-lateral, so join rows on `WELLBORE_KEY`. |
| `NATIVE_ID_TYPE` | Identifier scheme of `NATIVE_ID` (API10, API14, UWI-DLS, UWI-NTS or PLANNED), the same value as `WELLBORE_HEADER`.`NATIVE_ID_TYPE`. |
| `IS_CHILD` | True if this well is classified as a child well (drilled after nearby parent wells were producing). |
| `PARENT_COUNT` | Number of neighboring parent wells meeting spacing criteria. |
| `PARENT_DAYS_ONLINE` | Days the nearest parent well was online relative to this well's start. |
| `CLOSEST_WELL_XY` | XY distance to the closest lateral and staggered neighbor in feet. Non-additive. |
| `CLOSEST_TWO_AVG_XY` | Average XY distance to the two closest neighbors (includes staggered and stacked). Non-additive. |
| `WELLS_IN_RADIUS` | Count of all wells within the neighbor distance radius. |
| `WELLS_IN_RADIUS_AVG_XY` | Total wells in radius converted to a distance = 2 \* MaxNeighborDistance / (1 + WellsInRadius). Non-additive. |
| `LATERAL_CLOSER_XY` | XY distance to the nearest well in the same lateral row. Non-additive. |
| `STAGGER_CLOSER_TANGENT` | Tangent distance to the nearest staggered well. Non-additive. |
| `STACK_CLOSER_Z` | Vertical distance to the nearest well in the same vertical stack. Non-additive. |
| `BOUNDEDNESS_SCORE` | Number of neighbor quadrants occupied by wells (0-8). Non-additive. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
## WELLBORE_SUBSURFACE_PROPERTY
Rock properties and landing-zone geometry at one measurement point. Grain: One row per (wellbore\_key, location\_type, formation).
| Column | Description |
| --- | --- |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key, the canonical anchor for every subsurface\_property row. Populated for all rows; the optional survey\_station\_id provides finer station-grain attachment when available. |
| `SUBSURFACE_PROPERTY_ID` | Surrogate key. |
| `NATIVE_ID` | Regulatory identifier of the wellbore this row belongs to, the same value as `WELLBORE_HEADER`.`NATIVE_ID`, so the row can be joined to data outside `NOVI_WELLS`. Its scheme (API10, API14, UWI-DLS, UWI-NTS or PLANNED) is `NATIVE_ID_TYPE`. Not a unique bore key: an API10 does not distinguish the bores of a multi-lateral, so join rows on `WELLBORE_KEY`. |
| `SURVEY_STATION_ID` | Optional foreign key to directional\_survey\_station.survey\_station\_id. Populated when the wellbore has a matching directional survey station for the row's location type; NULL when the parent wellbore has no directional-survey coverage. Use wellbore\_key as the always-populated anchor. |
| `NATIVE_ID_TYPE` | Identifier scheme of `NATIVE_ID` (API10, API14, UWI-DLS, UWI-NTS or PLANNED), the same value as `WELLBORE_HEADER`.`NATIVE_ID_TYPE`. |
| `LOCATION_TYPE` | Type of measurement point along the wellbore, as an integer code. Part of the natural key: it disambiguates multiple measurements on one wellbore. Measured on current data the values are 7 (94.7% of rows), 1 (5.3%) and 4 (0.008%); the codes are not decoded on this view, so treat it as an opaque discriminator rather than a readable label. |
| `FORMATION` | Novi's best estimate of the actual target formation. |
| `REPORTED_FORMATION` | Target formation as reported by the state. |
| `GRID_FORMATION` | Formation based on subsurface grid studies. |
| `STRUCTURAL_DEPTH` | Depth of the top of the formation (TVDSS). |
| `POROSITY_AVG` | Effective porosity in percentage (porosity units). |
| `PERMEABILITY_AVG` | Average permeability calibrated to core and production matching, in millidarcies. |
| `PERMEABILITY_HEIGHT_AVG` | Average permeability times gross thickness (kh product) in millidarcy-feet. |
| `POROSITY_HEIGHT_AVG` | Average porosity times gross thickness (phi-h product). |
| `THICKNESS_AVG` | Gross isopach (formation thickness) in feet. |
| `SW_AVG` | Average water saturation as a percentage. |
| `TOC_AVG` | Average total organic carbon as a percentage. |
| `VCLAY_AVG` | Average volume of clay as a percentage. |
| `BVI_AVG` | Average bulk volume irreducible water as a percentage. |
| `NTG_AVG` | Net-to-gross ratio (dimensionless). |
| `BRITTLENESS_AVG` | Average brittleness of the formation, as an index whose unit and range are not defined; not a 0-1 fraction or a percentage. Non-additive. |
| `COMPETENCY_AVG` | Average rock competency of the formation, as an index whose unit and range are not defined; not a 0-1 fraction. Non-additive. |
| `STOIIP_AVG` | Stock tank oil initially in place, million barrels per section (sq. mi). |
| `GIIP_AVG` | Gas initially in place, billion cubic feet per section (sq. mi). |
| `POROSITY_OF_NET` | Porosity averaged over net pay cutoffs. |
| `PERMEABILITY_OF_NET` | Permeability averaged over net pay cutoffs, in millidarcies. |
| `PERMEABILITY_HEIGHT_OF_NET` | Permeability-height product over net pay cutoffs, in millidarcy-feet. |
| `POROSITY_HEIGHT_OF_NET` | Porosity-height product over net pay cutoffs. |
| `THICKNESS_OF_NET` | Net pay thickness in feet. |
| `SW_OF_NET` | Water saturation over net pay cutoffs. |
| `TOC_OF_NET` | TOC over net pay cutoffs. |
| `VCLAY_OF_NET` | Volume of clay over net pay cutoffs. |
| `BVI_OF_NET` | Irreducible water over net pay cutoffs. |
| `BRITTLENESS_OF_NET` | Brittleness averaged over net pay cutoffs within the formation, on the same scale as brittleness\_avg. Unit and range are not defined. Non-additive. |
| `COMPETENCY_OF_NET` | Competency averaged over net pay cutoffs, on the same scale as competency\_avg. Unit and range are not defined. Non-additive. |
| `STOIIP_OF_NET` | Oil in place over net pay cutoffs. |
| `GIIP_OF_NET` | Gas in place over net pay cutoffs. |
| `PERCENT_IN_ZONE` | Percentage of lateral in the grid formation. |
| `DISTANCE_FROM_TOP` | Feet from top of formation, based on grids and survey. |
| `DISTANCE_FROM_BASE` | Feet from base of formation, based on grids and survey. |
| `NORMALIZED_DISTANCE_TO_TOP` | Value 0-1 where 0 = drilled at top of zone, 1 = drilled at base of zone. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
## WELLBORE_TEST_HISTORY
Well-test rates and flowing and shut-in pressures. Grain: One row per (wellbore\_key, test\_date).
| Column | Description |
| --- | --- |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key. |
| `WELL_TEST_ID` | Surrogate key for the well test row. |
| `NATIVE_ID` | Regulatory identifier of the wellbore this row belongs to, the same value as `WELLBORE_HEADER`.`NATIVE_ID`, so the row can be joined to data outside `NOVI_WELLS`. Its scheme (API10, API14, UWI-DLS, UWI-NTS or PLANNED) is `NATIVE_ID_TYPE`. Not a unique bore key: an API10 does not distinguish the bores of a multi-lateral, so join rows on `WELLBORE_KEY`. |
| `NATIVE_ID_TYPE` | Identifier scheme of `NATIVE_ID` (API10, API14, UWI-DLS, UWI-NTS or PLANNED), the same value as `WELLBORE_HEADER`.`NATIVE_ID_TYPE`. |
| `TEST_DATE` | Date on which the well test was performed. |
| `REPORT_DATE` | Date when the test was first reported. May differ from test\_date. |
| `OIL_RATE` | 24-hour oil production rate in barrels per day. Semi-additive: do not sum across wellbores. |
| `GAS_RATE` | 24-hour gas production rate in Mcf per day. Semi-additive: do not sum across wellbores. |
| `WATER_RATE` | 24-hour water production rate in barrels per day. Semi-additive: do not sum across wellbores. |
| `FLOWING_WELLHEAD_PRESSURE` | Pressure at the wellhead while flowing during the test. Semi-additive. |
| `SHUT_IN_WELLHEAD_PRESSURE` | Pressure at the wellhead while shut-in during the test. Semi-additive. |
| `BOTTOM_HOLE_PRESSURE` | Bottom hole pressure during the test. Semi-additive. |
| `OIL_GRAVITY` | API gravity of produced oil in degrees, measured at standard conditions (60°F). Conventional buckets: <22.3 = heavy, 22.3–31.1 = medium, >31.1 = light, >50 = condensate. Property of the fluid sample at this test event. |
| `GAS_SPECIFIC_GRAVITY` | Specific gravity of produced gas relative to air, air = 1.0. A property of the fluid sample at this test event, not of the wellbore: a wellbore with several tests has several values, and the most recent one is a derivation rather than this column. Dry pipeline gas is typically 0.55–0.70; richer casinghead and condensate-associated gas runs higher, and values above roughly 1.0 indicate a heavy, NGL-rich stream. Non-additive: never sum, and average only with volume weighting. Sparse by design, NULL means this test reported no gas gravity, which is the common case, while the absence of a row means no test. minimum: 0 is a physical floor, consistent with the other measures on this entity; it is not a range check. Sources that range-guard the value (the primary US source discards readings outside 0.5–1.5) do so before it reaches this column, and a source that does not is not caught here. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
## PRODUCTION_MONTHLY
Monthly volumes by stream across calendar, producing and economic time axes. Grain: One row per (wellbore\_key, year, month), monthly granularity only. Actual and forecast months OVERLAP and are not reconciled: a wellbore can have a row in `PRODUCTION_MONTHLY` and a row in `PRODUCTION_FORECAST_MONTHLY` for the same (wellbore\_key, year, month). Novi does not trim the forecast to begin after the last producing month, and the overlap WIDENS over time: new production records are appended while the forecast's timeframe stays as generated, so the number of overlapping months grows until the forecast is regenerated. Do not hard-code a cutover month. Do not sum the two for a period, pick one, or take actuals where they exist and forecast only beyond them.
| Column | Description |
| --- | --- |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key. |
| `NATIVE_ID` | Regulatory identifier of the wellbore this row belongs to, the same value as `WELLBORE_HEADER`.`NATIVE_ID`, so the row can be joined to data outside `NOVI_WELLS`. Its scheme (API10, API14, UWI-DLS, UWI-NTS or PLANNED) is `NATIVE_ID_TYPE`. Not a unique bore key: an API10 does not distinguish the bores of a multi-lateral, so join rows on `WELLBORE_KEY`. |
| `NATIVE_ID_TYPE` | Identifier scheme of `NATIVE_ID` (API10, API14, UWI-DLS, UWI-NTS or PLANNED), the same value as `WELLBORE_HEADER`.`NATIVE_ID_TYPE`. |
| `PRODUCTION_DATE` | First day of the month for this record. A convenience column equivalent to (year, month), the production fact does not require it, so (year, month) is the grain and this column may be null on an otherwise valid source row. Derive it rather than depend on it. |
| `YEAR` | Calendar year of this production record (UTC). |
| `MONTH` | Calendar month number of this production record (1–12). |
| `PRODUCING_DAYS` | Number of days in this period during which the wellbore was actively producing OR injecting. Bounded by period length (0–31 monthly, 0–7 weekly). 0 days legitimately implies zero produced + zero injected volumes (maintenance, shut-in, plugged). For injection-only wells (SWD, EOR injectors), an active-injection period reports producing\_days >= 1 even though produced volumes are zero. |
| `CALENDAR_DAYS` | Number of calendar days represented for this period (1–31 monthly, exactly 7 weekly). |
| `CUMULATIVE_PRODUCING_DAYS` | Cumulative number of producing days since production start. |
| `MONTHS_ON_PRODUCTION` | Calendar-month index of the row relative to the wellbore's first month on production, 1-based: 1 = the first month on production whether or not it is partial. After the first index every calendar month advances it by one whether or not the month produced, so it is a calendar index, unique and contiguous per wellbore, and never a count of producing months. The elapsed-time axis for type-curve analysis: it aligns wells of different vintages on months since first production rather than on absolute date (year/month). Elapsed, not produced, a shut-in month still advances it. `SUPPLY_PROJECTION` uses the same 1-based convention, so cohort joins line up. |
| `OIL` | Oil volume produced at the wellhead for the period, measured in barrels (bbl). |
| `GAS` | Natural gas volume produced at the wellhead for the period, measured in thousand cubic feet (Mcf). |
| `WATER` | Produced water volume for the period, measured in barrels (bbl). |
| `GAS_FLARED` | Natural gas volume flared in the period, measured in thousand cubic feet (Mcf). Used for emissions and regulatory reporting. |
| `IS_OIL_FROM_PRODUCTION_SHARING` | True if oil production data is from a proprietary source. |
| `IS_GAS_FROM_PRODUCTION_SHARING` | True if gas production data is from a proprietary source. |
| `IS_WATER_FROM_PRODUCTION_SHARING` | True if water production data is from a proprietary source. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
## PRODUCTION_FORECAST_MONTHLY
Monthly forecast rates and cumulatives by stream, per scenario. Grain: One row per (wellbore\_key, scenario, year, month), monthly granularity only. Actual and forecast months OVERLAP and are not reconciled: a wellbore can have a row in `PRODUCTION_MONTHLY` and a row in `PRODUCTION_FORECAST_MONTHLY` for the same (wellbore\_key, year, month). Novi does not trim the forecast to begin after the last producing month, and the overlap WIDENS over time: new production records are appended while the forecast's timeframe stays as generated, so the number of overlapping months grows until the forecast is regenerated. Do not hard-code a cutover month. Do not sum the two for a period, pick one, or take actuals where they exist and forecast only beyond them.
| Column | Description |
| --- | --- |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key. |
| `PRODUCTION_FORECAST_ID` | Identifier that groups the period rows of one forecast. Shared by those rows, so it is not unique per row. |
| `NATIVE_ID` | Regulatory identifier of the wellbore this row belongs to, the same value as `WELLBORE_HEADER`.`NATIVE_ID`, so the row can be joined to data outside `NOVI_WELLS`. Its scheme (API10, API14, UWI-DLS, UWI-NTS or PLANNED) is `NATIVE_ID_TYPE`. Not a unique bore key: an API10 does not distinguish the bores of a multi-lateral, so join rows on `WELLBORE_KEY`. |
| `NATIVE_ID_TYPE` | Identifier scheme of `NATIVE_ID` (API10, API14, UWI-DLS, UWI-NTS or PLANNED), the same value as `WELLBORE_HEADER`.`NATIVE_ID_TYPE`. |
| `SCENARIO` | Forecast scenario percentile. Novi currently produces P50 (most likely) only, so this column holds 'P50' on every row today; it is part of the grain so that other scenarios can be added. |
| `FORECAST_DAY` | Period index relative to initial production (IP), expressed in nominal day units. For monthly records this is the month ordinal times 30, where the ordinal is 1-based (so month 1 encodes as 30); for weekly records, multiples of 7. The lowest value actually present in a given fact depends on which months that fact carries, a forecast-only projection whose historical months are excluded starts at whatever month the forecast begins, not at 30. NOT a count of elapsed days, dividing by 30 recovers the month index exactly, and real elapsed time drifts from it by roughly 0.44 days per month (about 264 days over a 600-month horizon). Note this is a different basis from production.months\_on\_production: a day index, not a month index. Use forecast\_day to order rows within this fact. Do NOT use it as an alignment key against production\_forecast\_arps\_segment.day\_start (real calendar days) or for discounting; align on year / month, or on the segment's segment\_start\_date / segment\_end\_date. |
| `YEAR` | Calendar year of the production month this forecast row represents. Not the revenue month, revenue conventionally lags production by 1–2 months. Together with month, this is the alignment axis against actual production and against production\_forecast\_arps\_segment.segment\_start\_date. On yearly records, the calendar year of forecast\_date, the first month of the 12-month block. |
| `MONTH` | Calendar month number (1–12) of the production month this forecast row represents. Not the revenue month. See year. On yearly records, the calendar month of forecast\_date, the first month of the 12-month block. |
| `OIL_PER_DAY` | Oil rate (bbl/d). May carry oil and condensate as a single combined rate, in which case condensate\_per\_day is null; a populated oil rate beside a null condensate rate therefore does not assert that no condensate is forecast. Semi-additive; do not sum across wells without producing\_days weighting. On yearly records, the 12-month block's volume divided by the calendar days of that block counted from forecast\_date (365 or 366), so a final partial block is still divided by a full block. |
| `CUMULATIVE_OIL` | Cumulative oil volume (bbl), combined with condensate on the same rows as oil\_per\_day (cumulative\_condensate is then null), accumulated over the FORECAST horizon only: the running total of this fact's own per-period forecast volumes, from the first forecast period at this row's period\_granularity. It excludes production that occurred before the forecast starts; historical volumes live in production. Semi-additive: it may be summed across wellbores at a fixed period, but must NEVER be summed across periods; it is already a running total, so summing double-counts. To recover a single period's volume, difference consecutive rows. |
| `GAS_PER_DAY` | Gas rate (Mcf/d). Semi-additive; do not sum across wells without producing\_days weighting. On yearly records, the 12-month block's volume divided by the calendar days of that block counted from forecast\_date (365 or 366), so a final partial block is still divided by a full block. |
| `CUMULATIVE_GAS` | Cumulative gas volume (Mcf), accumulated over the FORECAST horizon only: the running total of this fact's own per-period forecast volumes, from the first forecast period at this row's period\_granularity. It excludes production that occurred before the forecast starts; historical volumes live in production. Semi-additive: it may be summed across wellbores at a fixed period, but must NEVER be summed across periods; it is already a running total, so summing double-counts. To recover a single period's volume, difference consecutive rows. |
| `WATER_PER_DAY` | Water rate (bbl/d). Semi-additive; do not sum across wells without producing\_days weighting. On yearly records, the 12-month block's volume divided by the calendar days of that block counted from forecast\_date (365 or 366), so a final partial block is still divided by a full block. |
| `CUMULATIVE_WATER` | Cumulative water volume (bbl), accumulated over the FORECAST horizon only: the running total of this fact's own per-period forecast volumes, from the first forecast period at this row's period\_granularity. It excludes production that occurred before the forecast starts; historical volumes live in production. Semi-additive: it may be summed across wellbores at a fixed period, but must NEVER be summed across periods; it is already a running total, so summing double-counts. To recover a single period's volume, difference consecutive rows. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `FORECAST_DATE` | First day of the calendar month whose production this row forecasts (e.g. 2034-03-01): the forecast production month, not the revenue month, which typically lags 1–2 months. On yearly records, the first day of the first month of the 12-month block; not 1 January. On monthly records it joins to production.production\_date by value; on yearly records it matches only the block's first month. |
| `FORECAST_MONTH` | 1-based index of the month within the wellbore's monthly series of consecutive months, 1 being the series' earliest month. On monthly records, the month this row forecasts, equal to forecast\_day / 30. On yearly records, the last month present in the 12-month block: the year ordinal times 12, or less for a final partial year. An ordinal index, not a calendar month: see month for the calendar month. |
---
# Wells and wellbores
Source: https://developers.novilabs.com/data/tables/wells/
> Well identity, wellbore geometry, surface locations, trajectories, and directional survey stations.
Views live in `NOVI_DATA_ACCESS.NOVI_WELLS`. Column descriptions are from the Wells data dictionary, release 26.4.3. Type is the data model's logical type, and unit appears where the model declares one. For Snowflake column types, query `NOVI_DATA_ACCESS.INFORMATION_SCHEMA.COLUMNS`.
## WELL
Canonical identity and slowly changing attributes for a well. This record is the stable anchor used by planning, drilling, production, economics, and forecasting. Lifecycle changes are events in `WELL_EVENT`, and geometry is in `SURFACE_LOCATION`.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `WELL_KEY` | string | | Surrogate key for the well row, a stable string composed as {country}:{native\_id\_type}:{native\_id} (e.g. US:API10:4212340567). Consistent with this row's country, native\_id\_type, and native\_id. |
| `COUNTRY` | string | | Two-letter ISO 3166-1 alpha-2 country code where the well is located (e.g., US, CA). |
| `NATIVE_ID_TYPE` | string | | Identifier scheme of native\_id, explicitly restricted to the well-grain schemes API10 or UWI-DLS. API14 is wellbore grain (its borehole/event suffix distinguishes laterals, which would fan one well into multiple well\_keys) and PLANNED is wellbore-only, so neither is valid on a well. Second component of well\_key. |
| `NATIVE_ID` | string | | External regulatory identifier at well grain, the well-level root (API10 for US, UWI-DLS for Canada). Must be the canonical form for its scheme (digits-only for API10, the DLS format for UWI-DLS; no hyphens) so one regulatory well maps to one well\_key. The scheme is named by native\_id\_type, which conditionally validates this value's format; this value is the third component of well\_key. |
| `OPERATOR_ID` | integer | | Current operator of record. Historical changes should be captured as events (e.g., `OPERATOR_CHANGE`) or in a dedicated attribute history. |
| `WELL_NAME` | string | | Human-friendly well name (operator or regulatory naming). Use for display; not a key. |
| `COUNTY` | string | | Name of the county (or parish in Louisiana) where the well is located, as reported (e.g., "Reeves"); a name, never a code. The FIPS code is in `COUNTY_CODE`. NULL when not reported. |
| `STATE` | string | | US state (USPS two-letter) or Canadian province/territory (Statistics Canada two-letter) code where the well is located. |
| `FIELD_NAME` | string | | Name of the oil/gas field the well is in. |
| `STATUS_REPORTED` | string | | Raw reported well status value from the state regulatory agency filing. |
| `STATUS_REPORTED_NORMALIZED` | string | | State-reported well status after normalization to a controlled vocabulary. |
| `STATUS` | string | | Current coarse lifecycle state of the well (derived from events). Includes 7 milestone-based values and 9 regulatory/operational ones; semantic overlaps (e.g. PERMITTED/`PERMIT_APPROVED`, DRILLING/SPUD, PRODUCING/ACTIVE, `SHUT_IN`/INACTIVE) are deliberately preserved as distinct values so you can tell which source vocabulary a row came from. Details live in well\_event. |
| `LEASE_NUMBER` | string | | State-issued lease or production-unit identifier for the well as filed with the regulator, verbatim. Not a key: there is no lease table, and it is an identifier rather than the human-readable lease name. Format is state-specific and values compare only within one state: Texas carries the Railroad Commission of Texas (RRC) district and lease number joined by a semicolon (e.g. 08;39152; the semicolon joins district and lease, it is not a list separator; districts can be alphanumeric such as 7B); Oklahoma carries the 14-digit Oklahoma Tax Commission (OTC) production unit number. Exactly one identifier per well; the current assignment only. NULL where the state record carries no lease identifier, which is the case in every state other than Texas and Oklahoma today. |
| `LATEST_OIL_GRAVITY` | number | deg API | Most recent oil API gravity reported for the well, in degrees API. Oil and gas gravities are reported independently and may come from different tests. NULL when none is reported. |
| `LATEST_GAS_GRAVITY` | number | SG | Most recent gas specific gravity reported for the well (air = 1.0). Not necessarily from the same test as `LATEST_OIL_GRAVITY`. NULL when none is reported. |
| `OPERATOR_REPORTED` | string | | The well's current operator as reported for the well: a name, not resolved to an OPERATOR row (`OPERATOR_ID` carries the resolved operator). May hold a placeholder where no operator is assigned. A current value, not a history. NULL where no operator is reported. |
| `OPERATOR_ORIGINAL` | string | | The well's operator as of first production: a name, not resolved to an OPERATOR row. It does not change when the well later changes operator. NULL where no original operator is recorded. |
| `COUNTY_CODE` | string | | Five-digit FIPS code of the county (or parish in Louisiana) where the well is located (e.g., "48389" for Reeves County, Texas). The name is in COUNTY. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the well record was first created in this system (ingest or authoring time). |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update to this well record. |
## WELLBORE
A specific bore/lateral associated with a well. One well can have multiple wellbores (laterals, sidetracks, re-entries). As-built attributes belong here; time-varying milestones belong in well\_event.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `WELLBORE_KEY` | string | | Surrogate key for the wellbore row, a stable string composed as {country}:{native\_id\_type}:{native\_id}:{sequence\_number} (e.g. US:API10:4212340567:0 for US, CA:UWI-DLS:00/02-13-069-09W5/0:0 for Canada). Consistent with this row's country, native\_id\_type, native\_id, and sequence\_number. |
| `COUNTRY` | string | | Two-letter ISO 3166-1 alpha-2 country code where the wellbore is located (e.g., US, CA). First component of wellbore\_key; matches the parent well.country. |
| `NATIVE_ID_TYPE` | string | | Identifier scheme of native\_id (API10, API14, UWI-DLS, or PLANNED). API14 when a borehole/event suffix is available, otherwise API10 (e.g. single-wellbore wells or API10-only sources), UWI-DLS in Canada, or PLANNED for planned wellbores with no regulatory identifier yet. Second component of wellbore\_key. |
| `NATIVE_ID` | string | | Wellbore-level identifier. For regulatory schemes (API10/API14/UWI-DLS) this is the external regulatory id, API14 captures the sidetrack/event suffix (positions 11-14) that disambiguates per-wellbore borehole+event; the well-level well.native\_id carries the well-level root (API10 for US, UWI-DLS for Canada). Use the contiguous 14-digit API14 (digits only, no hyphens). For the PLANNED scheme (planned wellbores with no regulatory id yet) this is the Novi-internal id (planned\_well.planned\_well\_id). The scheme is named by native\_id\_type, which conditionally validates this value's canonical format per scheme; this value is the third component of wellbore\_key. |
| `WELL_KEY` | string | | Foreign key to well.well\_key, linking this wellbore to its parent well. |
| `WELLBORE_TYPE_NORMALIZED` | string | | What the wellbore does: its declared operational function, from a controlled vocabulary (PRODUCER, INJECTOR, DISPOSAL, CYCLIC, STORAGE, `OBSERVATION_TEST`, and drainage and thermal-recovery roles). It is the declared function, not current activity: a plugged or shut-in producer stays PRODUCER, so use STATUS for activity. What the wellbore produces or handles is on `PRIMARY_STREAM`. Functions other than PRODUCER come only from a recognised filed code in `WELLBORE_TYPE_REPORTED`; without one (for example, every Texas wellbore) the value is PRODUCER or NULL, so counts of injection, disposal or storage wells are incomplete there. NULL when the source does not establish a function, for example a dry hole (`PRIMARY_STREAM` = DRY) or a service well whose filing does not say which service. |
| `WELLBORE_TYPE_REPORTED` | string | | The well-type code the source supplies for the regulator filing, trimmed and otherwise as filed. Codes, case and spelling vary by jurisdiction; they are not a controlled vocabulary. NULL where the source supplies no code (currently all Texas wellbores and most in Kansas and West Virginia). `WELLBORE_TYPE_NORMALIZED` and `PRIMARY_STREAM` use this code where it is recognised and a coarser classification otherwise, so they can hold a value when this column is NULL. |
| `STATUS_REPORTED` | string | | Raw reported wellbore status value from the regulator filing, at wellbore grain (analogous to well.status\_reported but for a specific lateral / sidetrack / re-entry). Independent input from well.status\_reported, wellbore status can differ from well status. |
| `STATUS_REPORTED_NORMALIZED` | string | | Reported wellbore status mapped to a controlled vocabulary, at wellbore grain (analogous to well.status\_reported\_normalized). Distinct from wellbore.status (Novi-curated lifecycle enum); the reported/normalized pair preserves provenance for audit. |
| `STATUS` | string | | Current lifecycle state for the wellbore (can differ from the well-level status). |
| `MD_TD` | number | ft | Measured depth at TD in feet. |
| `TVD_TD` | number | ft | True vertical depth at TD in feet. |
| `LATERAL_LENGTH` | number | ft | Selected lateral length in feet: a manual override where one exists, otherwise the first populated of `LATERAL_LENGTH_CALCULATED_U_TURN`, `LATERAL_LENGTH_CALCULATED_PERF`, `LATERAL_LENGTH_CALCULATED_LP_TO_BHL`, `LATERAL_LENGTH_CALCULATED_KP_TO_BHL`, `LATERAL_LENGTH_CALCULATED_MD_TVD` and `LATERAL_LENGTH_CALCULATED_SHL_BHL`, in that order. The method varies by row and is named in `LATERAL_LENGTH_SOURCE`, so values are not comparable across rows without it. Non-additive. NULL when no method yields a value, and then `LATERAL_LENGTH_SOURCE` is NULL too. |
| `LATERAL_LENGTH_CALCULATED_PERF` | number | ft | Lateral length in feet from the upper to the lower perforation, the completed (stimulated) interval rather than the drilled one. One of six explicitly named derivations; there is no canonical choice between them. NULL on horseshoe (U-turn) wellbores, where direction\_calculated is '`U_TURN_HORIZONTAL`': this method is distorted on a reversing path. Where a horseshoe's lateral length is stated, it is in lateral\_length\_calculated\_u\_turn, unless it was set manually. |
| `LATERAL_LENGTH_CALCULATED_LP_TO_BHL` | number | ft | Lateral length in feet between the landing point and the bottom hole, as the difference in measured depth between the two survey stations, the surveyed path along the borehole, not a straight line. NULL on horseshoe (U-turn) wellbores, where direction\_calculated is '`U_TURN_HORIZONTAL`': this method is distorted on a reversing path. Where a horseshoe's lateral length is stated, it is in lateral\_length\_calculated\_u\_turn, unless it was set manually. |
| `LATERAL_LENGTH_CALCULATED_KP_TO_BHL` | number | ft | Lateral length in feet between the kick-off point and the bottom hole, as the difference in measured depth between the two survey stations. Includes the build section, so it reads longer than lateral\_length\_calculated\_lp\_to\_bhl and adds no wellbore that column does not already cover. NULL on horseshoe (U-turn) wellbores, where direction\_calculated is '`U_TURN_HORIZONTAL`': this method is distorted on a reversing path. Where a horseshoe's lateral length is stated, it is in lateral\_length\_calculated\_u\_turn, unless it was set manually. |
| `LATERAL_LENGTH_CALCULATED_MD_TVD` | number | ft | Lateral length in feet from measured depth minus true vertical depth at total depth, clamped at 24,000 ft. A coarse beyond-vertical proxy rather than a survey-based measurement. NULL on horseshoe (U-turn) wellbores, where direction\_calculated is '`U_TURN_HORIZONTAL`': this method is distorted on a reversing path. Where a horseshoe's lateral length is stated, it is in lateral\_length\_calculated\_u\_turn, unless it was set manually. |
| `LATERAL_LENGTH_CALCULATED_SHL_BHL` | number | ft | Great-circle distance in feet between the surface and bottom hole locations. This is a horizontal DISPLACEMENT, not a lateral length: it includes the vertical and build sections, and on most wellbores where it is the only available derivation the value is under 500 ft. Do not use it as a lateral length without a minimum-length filter. NULL on horseshoe (U-turn) wellbores, where direction\_calculated is '`U_TURN_HORIZONTAL`': this method is distorted on a reversing path. Where a horseshoe's lateral length is stated, it is in lateral\_length\_calculated\_u\_turn, unless it was set manually. |
| `MIDPOINT_LATITUDE` | number | deg | Latitude of the approximate lateral midpoint in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `MIDPOINT_LONGITUDE` | number | deg | Longitude of the approximate lateral midpoint in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `HEELPOINT_LATITUDE` | number | deg | Latitude of the lateral heel point in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `HEELPOINT_LONGITUDE` | number | deg | Longitude of the lateral heel point in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `BOTTOM_HOLE_LATITUDE` | number | deg | Latitude of the bottom hole location in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `BOTTOM_HOLE_LONGITUDE` | number | deg | Longitude of the bottom hole location in decimal degrees, WGS84 unless otherwise specified by the CRS. |
| `KB_ELEVATION` | integer | ft | Kelly bushing elevation in feet above sea level. |
| `LANDING_POINT_LATITUDE` | number | deg | Latitude of the landing point in decimal degrees, WGS84. |
| `LANDING_POINT_LONGITUDE` | number | deg | Longitude of the landing point in decimal degrees, WGS84. |
| `FORMATION_REPORTED` | string | | Formation name as reported by the data source (raw regulatory filing string). |
| `FORMATION_REPORTED_NORMALIZED` | string | | Source-reported formation mapped to a controlled vocabulary. |
| `FORMATION` | string | | Canonical formation name used for analytics grouping. Represents Novi's best estimate of the landing zone formation. |
| `FORMATION_CALCULATED` | string | | Novi-calculated formation based on wellbore geometry and formation tops (structural depth grids). Used as the standard grouping key for peer comparison. |
| `DIRECTION_REPORTED` | string | | Raw reported slant/direction value from the state regulatory agency (e.g., "Horizontal", "Directional"). |
| `DIRECTION_REPORTED_NORMALIZED` | string | | State-reported direction after normalization to a controlled vocabulary. |
| `DIRECTION_CALCULATED` | string | | Slant that Novi infers from evidence other than the filed slant, such as the wellbore trajectory. It is derived, not filed. |
| `DIRECTION` | string | | Novi's resolved well slant: the first of these that applies. `U_TURN_HORIZONTAL` when the calculated slant is a U-turn; HORIZONTAL when a directional survey not marked as planned shows a horizontal path; the normalized reported (filed) slant; the calculated slant. For a well whose survey-based resolution is not available, the survey step is skipped and the filed slant comes first. The filed wording is in `DIRECTION_REPORTED`. |
| `WELLBORE_LATERAL_LENGTH` | integer | ft | Deprecated and no longer maintained: it keeps the value last written before 2026-09-24 and is NULL on wellbores added since, so its coverage shrinks over time. It was a measured-depth difference along the borehole from the landing point (or the kick-off point where no landing point is known) to the bottom hole. Use `LATERAL_LENGTH_CALCULATED_LP_TO_BHL` for that measurement, or `LATERAL_LENGTH` for the selected value. |
| `LATERAL_LENGTH_SOURCE` | string | | Label of the method that produced `LATERAL_LENGTH`, such as 'Manual Override', 'PerforationTop-PerforationBottom' or 'Landing-Bottom'. Distinguishes methods that share a calculated column, such as landing point to bottom hole and landing point to measured depth. NULL when `LATERAL_LENGTH` is NULL. |
| `SEQUENCE_NUMBER` | integer | | Lateral ordinal within the well (0-based; 0 for the first lateral, aligning with API14 borehole/event codes). Required, it is the fourth component of wellbore\_key and guarantees wellbore uniqueness when native\_id alone does not distinguish laterals (e.g. API10-only multi-lateral wells). |
| `PRIMARY_STREAM` | string | | What the wellbore produces or handles, as declared, from a controlled vocabulary (OIL, GAS, `OIL_AND_GAS`, WATER, BRINE, WASTE, HELIUM, CO2, STEAM, BITUMEN, LITHIUM, POTASH, CBM, POLYMER, SOLVENT, AIR, `ACID_GAS`, DRY). Pairs with `WELLBORE_TYPE_NORMALIZED`: GAS on a STORAGE or DISPOSAL wellbore is gas stored or disposed of, not produced. For gas producers use `WELLBORE_TYPE_NORMALIZED` = 'PRODUCER' AND `PRIMARY_STREAM` IN ('GAS', '`OIL_AND_GAS`', 'CBM'); `OIL_AND_GAS` is a compound value, and coalbed methane wells currently carry GAS. Declared purpose, not observed production: a well declared for oil stays OIL while it dewaters, and the value asserts nothing about volumes. DRY appears only where a filed code classifies the bore as a dry hole, and then `WELLBORE_TYPE_NORMALIZED` is NULL. NULL when the source does not establish a stream. |
| `LATERAL_LENGTH_CALCULATED_U_TURN` | number | ft | Lateral length in feet stated for the wellbore as a U-turn (horseshoe) lateral length. Unlike the other lateral\_length\_calculated\_\* columns, its measurement basis (endpoints, along-hole or straight-line) is not defined, and the wellbore is not necessarily classified as U-turn. NULL where not stated. |
| `REFRAC_COUNT` | integer | | Number of refracs (re-stimulations after the original frac) reported for this wellbore's well; 0 when none is reported. Reported by the source, not counted from `WELL_EVENT`, which carries only the most recent REFRAC event, so a well with a count of 2 or 3 still has one REFRAC event. NULL when no count is reported, which includes every Canadian wellbore. |
| `DIRECTIONAL_SURVEY_AVAILABLE` | boolean | | True when directional survey stations are reported for the wellbore, false when none are. Reported by the source rather than computed from `DIRECTIONAL_SURVEY_STATION`, so the two can briefly disagree while a new survey loads. NULL when survey coverage is not reported, which includes every Canadian wellbore. |
| `PLANNED_AS_DRILLED_SURVEY` | string | | Whether the wellbore's directional survey is a planned trajectory (PLANNED) or one measured in the drilled hole (`AS_DRILLED`), as the source reports it. NULL when `DIRECTIONAL_SURVEY_AVAILABLE` is false or NULL, which includes every Canadian wellbore. |
| `WELLBORE_TYPE` | string | | The wellbore's declared operational function. It equals `WELLBORE_TYPE_NORMALIZED` and has the same values, meaning and limits; read that column's description. NULL wherever `WELLBORE_TYPE_NORMALIZED` is NULL. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the wellbore record was created in this system. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update to this wellbore record. |
## SURFACE_LOCATION
Surface location and legal description for a well.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `SURFACE_LOCATION_ID` | integer | | Stable, immutable unique identifier for this surface location record. |
| `WELL_KEY` | string | | Foreign key to well.well\_key that currently references this location. |
| `LATITUDE` | number | | Latitude in decimal degrees, WGS84 unless otherwise specified by crs. |
| `LONGITUDE` | number | | Longitude in decimal degrees, WGS84 unless otherwise specified by crs. |
| `CRS` | string | | Coordinate reference system identifier (e.g., 'EPSG:4326'). |
| `BLOCK_TOWNSHIP` | string | | Township-level land identifier, consolidated across survey systems. PLSS: township, range and principal meridian as filed, separated by single spaces (e.g., "10S 62W Indian"): township is the first token, range the second, and the meridian is everything after the second space, which may itself contain spaces ("Sixth Principal", "New Mexico Principal") or be a California meridian code ("MD" Mount Diablo, "SB" San Bernardino, "H" Humboldt, filed beside the spelled-out "Humboldt"); the meridian vocabulary is not normalized. Township + range alone (e.g., "10S 62W") only when the state record carries no meridian. Texas: block number as filed (e.g., "143"), which may contain spaces. The model also defines an Alberta DLS format ("R15 T2 W4"), never returned here because this product carries US wells only. Token count does not identify the survey system: read the jurisdiction from WELL.STATE via `WELL_KEY` (or `TX_SURVEY`, which only Texas files), not from this value's shape. |
| `SECTION` | string | | Section number within the block/township (~640 acres). Shared across all survey systems (PLSS, Texas, Alberta DLS). |
| `TX_SURVEY` | string | | Texas only. Original land grant survey name (e.g., "T&STL RR CO"). Null for non-Texas wells. |
| `ABSTRACT_LOT` | string | | Sub-section subdivision. Texas: abstract number (e.g., "3559"). PLSS: quarter/government lot (e.g., "NENW"). Alberta DLS: legal subdivision (e.g., "14"). |
| `STATE` | | | US state (USPS two-letter) or Canadian province/territory (Statistics Canada two-letter) code of the well this location belongs to; the same value as WELL.STATE for this `WELL_KEY`. |
| `COUNTY` | | | Name of the county (or parish in Louisiana) of the well this location belongs to (e.g., "Reeves"); a name, never a code. The same value as WELL.COUNTY for this `WELL_KEY`; the FIPS code is in WELL.`COUNTY_CODE`. NULL when not reported. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the location record was created in this system. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update to this location record. |
## WELLBORE_TRAJECTORY
Stores a wellbore trajectory as a polyline for spatial analysis (spacing, overlap, inventory sizing, and map visualization). One row per wellbore, the polyline is updated in place as new survey stations are observed or existing stations are corrected. Geometry is stored as WKT LineString in WGS84 (EPSG:4326) unless otherwise specified by crs.
| Column | Description |
| --- | --- |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key. |
| `TRAJECTORY_ID` | Surrogate key for the trajectory row. |
| `GEOMETRY_WKT` | Wellbore trajectory as WKT LineString in the specified crs. |
| `CRS` | Coordinate reference system identifier (e.g., 'EPSG:4326'). |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | Timestamp the trajectory record was created in this system. |
| `UPDATED_AT` | Timestamp of the most recent update to this trajectory record. |
## DIRECTIONAL_SURVEY_STATION
Station-level directional survey data for a wellbore. One row per survey station along the wellbore path, ordered by measured depth from surface to TD. Stations capture inclination, azimuth, TVD, and spatial offsets at each survey point. Used for wellbore trajectory reconstruction, spacing analysis, and subsurface mapping.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `WELLBORE_KEY` | string | | Foreign key to wellbore.wellbore\_key. |
| `SURVEY_STATION_ID` | integer | | Surrogate key for the survey station row. Deterministic and stable across reloads, and unique per station of a wellbore's combined trajectory: a shared pilot section copied into several wellbores' trajectories yields a distinct key in each. |
| `STATION_SEQUENCE` | integer | | Ordinal of this station within the wellbore's combined trajectory, 1-based (1 = the first, shallowest station) and ascending with measured depth. Because a wellbore has at most one combined trajectory, the per-wellbore and per-survey orderings are the same. |
| `MD` | number | ft | Measured depth of this survey station in feet. |
| `TVD` | number | ft | True vertical depth of this survey station in feet. |
| `SUB_SEA_TVD_CALCULATED` | number | ft | Novi-calculated sub-sea true vertical depth at this survey station, in feet. Negative values are above sea level. |
| `INCLINATION` | number | deg | Inclination angle at this station in degrees (0 = vertical, 90 = horizontal). |
| `AZIMUTH` | number | deg | Azimuth bearing at this station in degrees from north, 0 to 360 inclusive. 0 and 360 both denote due north; treat them as equal when comparing or grouping bearings. Non-additive. |
| `NS_OFFSET` | number | ft | North-South offset from wellhead in feet. Northbound is positive, southbound is negative. |
| `EW_OFFSET` | number | ft | East-West offset from wellhead in feet. Eastbound is positive, westbound is negative. |
| `LOCATION_TYPE` | integer | | Type of survey point: -1=furthest point of a U-turn (horseshoe) lateral, 0=other, 1=wellhead, 2=bottom hole, 3=kickoff point, 4=landing point, 5=perforation top, 6=perforation bottom, 7=midpoint. The same code system is used by subsurface\_property.location\_type, so the two can be compared directly. |
| `LATITUDE` | number | deg | Latitude of this survey station in decimal degrees, WGS84. |
| `LONGITUDE` | number | deg | Longitude of this survey station in decimal degrees, WGS84. |
| `INTERPOLATED` | boolean | | True if any value on this station row was interpolated rather than read from the source survey, a row or page missing from the filed survey, or a section that could not be read by OCR, with the intervening points computed. False when every value on the row came from the source. Row-level and deliberately coarse: it does not identify which value was interpolated, so a consumer needing confidence in the station's position specifically (spacing analysis) cannot separate an interpolated coordinate from an interpolated formation. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the record was created. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update. |
---
# Production and tests
Source: https://developers.novilabs.com/data/tables/production/
> Monthly and weekly production volumes, reported production roll-ups, and well tests.
Views live in `NOVI_DATA_ACCESS.NOVI_WELLS`. Column descriptions are from the Wells data dictionary, release 26.4.3. Type is the data model's logical type, and unit appears where the model declares one. For Snowflake column types, query `NOVI_DATA_ACCESS.INFORMATION_SCHEMA.COLUMNS`.
## PRODUCTION
The production record for a single wellbore at either monthly or weekly granularity, identified by wellbore\_key and a period selector. Captures measured volumes at the wellhead (produced) and, optionally, at the downstream custody-transfer point (sales) for oil (bbl), natural gas (Mcf) and natural gas liquids (bbl), plus injection volumes (water/brine in bbl, gas/CO2/N2 in Mcf) for SWD/EOR/CCUS wells. Each volume is non-negative. When producing\_days is one or more, at least one positive volume must be present, either produced/sales or injection; zero-volume periods are permitted when producing\_days = 0, for example maintenance or shut-in. Also includes producing\_days (bounded by period length) and calendar\_days (days in the period; monthly 28 to 31, weekly 7) to support rate normalization. For monthly periods use year/month; for weekly periods use week\_year/week (ISO week).
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `WELLBORE_KEY` | string | | Foreign key to wellbore.wellbore\_key. |
| `OPERATOR_ID` | integer | | Foreign key to operator.operator\_id. The operator of record for this production period, as the source attributes it: Novi's company name for the filer with mergers applied as of the period, so a month filed before an acquisition names the acquired company and a month filed after it names the acquirer. Not re-resolved to today's owner; join WELL.`OPERATOR_ID` for the current operator and group by `OPERATOR_ID` for operator tenure. In Oklahoma the source sometimes attributes a month to the gas purchaser or gatherer rather than the operator; those months carry that company. NULL where the regulator recorded a placeholder rather than an operator. |
| `PERIOD_GRANULARITY` | string | | Granularity of this record's period. |
| `YEAR` | integer | | Calendar year of this production record (UTC). |
| `MONTH` | integer | | Calendar month number of this production record (1–12). |
| `WEEK_YEAR` | integer | | ISO week-numbering year for weekly records (may differ from calendar year near boundaries). |
| `WEEK` | integer | | ISO week number (1–53) for weekly records. |
| `PRODUCING_DAYS` | integer | | Number of days in this period during which the wellbore was actively producing OR injecting. Bounded by period length (0–31 monthly, 0–7 weekly). 0 days legitimately implies zero produced + zero injected volumes (maintenance, shut-in, plugged). For injection-only wells (SWD, EOR injectors), an active-injection period reports producing\_days >= 1 even though produced volumes are zero. |
| `CALENDAR_DAYS` | integer | | Number of calendar days represented for this period (1–31 monthly, exactly 7 weekly). |
| `OPERATING_STATUS` | string | | Operational status for this period. 'producing' or 'injecting' implies producing\_days >= 1. 'maintenance', 'shut\_in', 'shut\_in\_injector', and 'temporarily\_abandoned' allow zero volumes and require downtime\_reason. 'injecting' applies to active injection periods (SWD, EOR injectors); 'shut\_in\_injector' is the injection-well analog of shut\_in. |
| `DOWNTIME_REASON` | string | | Optional free-text note describing maintenance/shut\_in reason or context. |
| `OIL` | number | bbl | Oil volume produced at the wellhead for the period, measured in barrels (bbl). May carry oil and condensate as a single combined volume, in which case condensate is null. A populated oil beside a null condensate therefore does not assert that no condensate was produced, whether or not the stream was reported separately upstream. |
| `OIL_SALES` | number | bbl | Oil volume measured at the downstream custody-transfer (sales) point for the period, in barrels (bbl). |
| `GAS` | number | Mcf | Natural gas volume produced at the wellhead for the period, measured in thousand cubic feet (Mcf). |
| `GAS_SALES` | number | Mcf | Natural gas volume measured at the downstream custody-transfer (sales) point for the period, in thousand cubic feet (Mcf). |
| `NGL` | number | bbl | Natural gas liquids volume produced at the wellhead for the period, measured in barrels (bbl). |
| `NGL_SALES` | number | bbl | Natural gas liquids volume measured at the downstream custody-transfer (sales) point for the period, in barrels (bbl). |
| `WATER` | number | bbl | Produced water volume for the period, measured in barrels (bbl). |
| `CONDENSATE` | number | bbl | Condensate volume produced at the wellhead for the period, measured in barrels (bbl). Null wherever the volume is not carried separately. A null does not establish that none was produced: the volume may be combined into oil, or may simply not have been reported. |
| `CONDENSATE_SALES` | number | bbl | Condensate volume measured at the downstream custody-transfer (sales) point for the period, in barrels (bbl). |
| `GAS_FLARED` | number | Mcf | Natural gas volume flared in the period, measured in thousand cubic feet (Mcf). Used for emissions and regulatory reporting. |
| `MONTHS_ON_PRODUCTION` | integer | | Calendar-month index of the row relative to the wellbore's first month on production. 1 = the first month on production; a source that distinguishes an incomplete first month marks it 0, in which case 1 is the first full month. After the first index every calendar month advances it by one whether or not the month produced, so indices are unique and contiguous across a wellbore's monthly rows (one monthly row per calendar month; weekly rows of the same month share its index). The elapsed-time axis for type-curve analysis: it aligns wells of different vintages on months since first production rather than on absolute date (year/month). Elapsed, not produced, a shut-in month still advances it. `SUPPLY_PROJECTION` shares the convention for cohort joins. On this surface the index starts at 1: the partial first month is not distinguished. |
| `CUMULATIVE_PRODUCING_DAYS` | integer | day | Cumulative number of producing days since production start. |
| `PRODUCTION_DATE` | date | | First day of the month for this production record (e.g., "2021-12-01"). Convenience field equivalent to year/month. |
| `IS_OIL_FROM_PRODUCTION_SHARING` | boolean | | True if oil production data is from a proprietary source. |
| `IS_GAS_FROM_PRODUCTION_SHARING` | boolean | | True if gas production data is from a proprietary source. |
| `IS_GAS_FLARED_FROM_PRODUCTION_SHARING` | boolean | | True if flared gas data is from a proprietary source. |
| `IS_WATER_FROM_PRODUCTION_SHARING` | boolean | | True if water production data is from a proprietary source. |
| `INJECTION_WATER` | number | bbl | Water or brine injected at the wellbore for the period in barrels (waterflood, saltwater disposal, produced-water disposal). Volumetric, additive across periods for the same wellbore. |
| `INJECTION_GAS` | number | Mcf | Gas injected at the wellbore for the period in thousand cubic feet (gas-injection EOR, CCUS, pressure maintenance, gas storage cycling). Includes hydrocarbon gas, CO2, and N2 reported as one combined gaseous-injectant volume; the individual gases are not reported separately. |
| `OPERATOR_REPORTED` | string | | The operator of this wellbore for this period as reported by the state regulatory agency, verbatim. Not resolved to an operator row; `OPERATOR_ID` carries the resolved operator. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the record was created. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update. |
## WELL_PRODUCTION_SUMMARY
Production roll-ups reported at well level: cumulative volumes at the 12-month, 24-month and life horizons, the peak producing month for oil, gas, water and BOE (NGL and condensate are not carried, and BOE is a converted total rather than a production stream), life-to-date gas-oil ratio, and the index of the last month with reported production. Cumulative volume columns end in \_REPORTED: reported volumes only, no forecast. Beside them it carries forecast EUR at 20, 30 and 50 years per stream, which is a forecast, not reported production. The roll-ups are REPORTED values, not computed from the production fact, a consumer wanting figures derived from monthly rows should compute them from production, which may give a different answer over a different set of months.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `WELL_PRODUCTION_SUMMARY_ID` | integer | | Surrogate key. |
| `WELLBORE_KEY` | string | | Foreign key to wellbore.wellbore\_key. The roll-up is a well-level quantity, carried on the well's lowest-sequence bore (sequence\_number 0); the well's other bores have no row, so a well's cumulative is never repeated across its laterals and the volumes stay additive across wellbores. A consequence for aggregation: filtering wellbores on a wellbore attribute before summing can drop a whole well's roll-up, because the carrying bore is the lowest-sequence one and need not be the production lateral. Rows carrying a value are identifiable by a wellbore\_key ending in:0. |
| `CUM_OIL_12_REPORTED` | number | bbl | Reported volumes only; excludes forecast volumes. Oil volume accumulated through the twelfth month on production. It may include condensate. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_OIL_24_REPORTED` | number | bbl | Reported volumes only; excludes forecast volumes. Oil volume accumulated through the twenty-fourth month on production. It may include condensate. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_OIL_LIFE_REPORTED` | number | bbl | Reported volumes only; excludes forecast volumes. Oil volume over the well's full reported history. It may include condensate. Additive across wellbores; not across time within a wellbore; it is already a running total. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `CUM_GAS_12_REPORTED` | number | Mcf | Reported volumes only; excludes forecast volumes. Gas volume over the first 12 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_GAS_24_REPORTED` | number | Mcf | Reported volumes only; excludes forecast volumes. Gas volume over the first 24 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_GAS_LIFE_REPORTED` | number | Mcf | Reported volumes only; excludes forecast volumes. Gas volume over the well's full reported history. Additive across wellbores; not across time within a wellbore; it is already a running total. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `CUM_WATER_12_REPORTED` | number | bbl | Reported volumes only; excludes forecast volumes. Water volume over the first 12 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_WATER_24_REPORTED` | number | bbl | Reported volumes only; excludes forecast volumes. Water volume over the first 24 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_WATER_LIFE_REPORTED` | number | bbl | Reported volumes only; excludes forecast volumes. Water volume over the well's full reported history. Additive across wellbores; not across time within a wellbore; it is already a running total. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `CUM_BOE_12_REPORTED` | number | BOE | Reported volumes only; excludes forecast volumes. Barrel-of-oil-equivalent volume over the first 12 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. BOE comprises oil, condensate and gas at 6 Mcf = 1 BOE, and excludes NGL. Null when the well has no producing month at index 12 or beyond: a permit-only row, a well whose reported history has not yet reached month 12, or a well that ceased producing before month 12. Never a partial sum. |
| `CUM_BOE_24_REPORTED` | number | BOE | Reported volumes only; excludes forecast volumes. Barrel-of-oil-equivalent volume over the first 24 months on production. Additive across wellbores at this horizon; never across horizons, the 12- and 24-month windows overlap. BOE comprises oil, condensate and gas at 6 Mcf = 1 BOE, and excludes NGL. Null when the well has no producing month at index 24 or beyond: a permit-only row, a well whose reported history has not yet reached month 24, or a well that ceased producing before month 24. Never a partial sum. |
| `CUM_BOE_LIFE_REPORTED` | number | BOE | Reported volumes only; excludes forecast volumes. Barrel-of-oil-equivalent volume over the well's full reported history. Additive across wellbores; not across time within a wellbore; it is already a running total. BOE comprises oil, condensate and gas at 6 Mcf = 1 BOE, and excludes NGL. 0 where the value is reported as nothing, and null where no value is reported at all. A zero and a null are different statements, and neither alone identifies a well that did not produce. |
| `PEAK_MONTH_OIL_INDEX` | integer | | Index on the months-on-production axis of the month in which combined oil and condensate volume peaked. The peak is selected on the combined volume, so on a condensate-rich well this can name a different month than an oil-only peak would. Ties resolve to the earliest such month. Non-additive. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_OIL_AMOUNT` | number | bbl | Combined oil and condensate volume in that peak month. A volume, not a rate. Non-additive across wellbores. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_GAS_INDEX` | integer | | Index on the months-on-production axis of the month in which gas volume peaked. Non-additive. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_GAS_AMOUNT` | number | Mcf | Gas volume in that peak month. Non-additive across wellbores. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_WATER_INDEX` | integer | | Index on the months-on-production axis of the month in which water volume peaked. Non-additive. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_WATER_AMOUNT` | number | bbl | Water volume in that peak month. Non-additive across wellbores. Null when the stream never produced: a zero maximum is not a peak. |
| `PEAK_MONTH_BOE_INDEX` | integer | | Index on the months-on-production axis of the month in which barrel-of-oil-equivalent volume peaked. The monthly BOE this peak is selected on is oil and gas at 6 Mcf = 1 BOE and EXCLUDES condensate, unlike the cumulative BOE columns, which include it, so on a condensate-rich well the peak month can differ from the one a condensate-inclusive BOE would select. Non-additive. Null when no month carried a positive total: a zero maximum is not a peak. |
| `PEAK_MONTH_BOE_AMOUNT` | number | BOE | Barrel-of-oil-equivalent volume in that peak month, as oil and gas at 6 Mcf = 1 BOE. EXCLUDES condensate and NGL, a narrower basis than the cumulative BOE columns, which include condensate. Non-additive across wellbores. Null when no month carried a positive total: a zero maximum is not a peak. |
| `CUM_LIFE_GOR` | number | Mcf/bbl | Life-to-date producing gas-oil ratio: life gas over life liquid, where the liquid denominator is the oil that cum\_oil\_life\_reported carries, which may include condensate. Null when that liquid total is zero, so a gas-only well has no value here rather than an infinite one. Rounded to two decimal places. NON-ADDITIVE, never sum or average across wellbores; recompute from the underlying volumes. Recomputing it needs cum\_gas\_life\_reported and cum\_oil\_life\_reported, which are not guaranteed present on the same row. |
| `LAST_REPORTED_MONTHS_ON_PRODUCTION` | integer | | Index on the months-on-production axis of the last month with reported production. An index, not a count: it identifies a month, it does not total them. Reported rather than derived from the monthly production fact, and not guaranteed to agree with an index computed from it. Non-additive. |
| `LAST_REPORTED_MONTH` | date | | First day of the last month in which the well reported a positive combined volume of oil, condensate, gas, flared gas and water. A month whose volumes are all zero or unreported does not count, so a well that has gone to zero carries the last month before it did. Reported rather than derived from the monthly production fact, and not guaranteed to equal a month computed from it. Non-additive. Null when no month qualifies. |
| `EUR_OIL_20YR` | number | bbl | Forecast estimated ultimate recovery of oil through the first 20 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_GAS_20YR` | number | Mcf | Forecast estimated ultimate recovery of gas through the first 20 years on production, in Mcf. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole Mcf: 0 where the forecast is under one Mcf or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_WATER_20YR` | number | bbl | Forecast estimated ultimate recovery of water through the first 20 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_BOE_20YR` | number | BOE | Forecast estimated ultimate recovery through the first 20 years on production, in barrels of oil equivalent at 6 Mcf = 1 bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole BOE: 0 where the forecast is under one BOE or states no volume; NULL where no forecast value exists at this horizon. |
| `EUR_OIL_30YR` | number | bbl | Forecast estimated ultimate recovery of oil through the first 30 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_GAS_30YR` | number | Mcf | Forecast estimated ultimate recovery of gas through the first 30 years on production, in Mcf. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole Mcf: 0 where the forecast is under one Mcf or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_WATER_30YR` | number | bbl | Forecast estimated ultimate recovery of water through the first 30 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_BOE_30YR` | number | BOE | Forecast estimated ultimate recovery through the first 30 years on production, in barrels of oil equivalent at 6 Mcf = 1 bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole BOE: 0 where the forecast is under one BOE or states no volume; NULL where no forecast value exists at this horizon. |
| `EUR_OIL_50YR` | number | bbl | Forecast estimated ultimate recovery of oil through the first 50 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_GAS_50YR` | number | Mcf | Forecast estimated ultimate recovery of gas through the first 50 years on production, in Mcf. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole Mcf: 0 where the forecast is under one Mcf or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_WATER_50YR` | number | bbl | Forecast estimated ultimate recovery of water through the first 50 years on production, in bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. In whole bbl: 0 where the forecast is under one bbl or states no volume for this stream; NULL where no forecast value exists at this horizon. |
| `EUR_BOE_50YR` | number | BOE | Forecast estimated ultimate recovery through the first 50 years on production, in barrels of oil equivalent at 6 Mcf = 1 bbl. A forecast for the well as currently producing, not a reported production volume. Additive across wellbores at the same horizon; never add horizons together. Whether condensate is included is not defined. In whole BOE: 0 where the forecast is under one BOE or states no volume; NULL where no forecast value exists at this horizon. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the record was created. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update. |
## WELL_TEST
Periodic well test measurement for a single wellbore on a specific test date. Captures 24-hour flow rates for oil, gas, and water, along with pressure readings. Used for lease allocation, production calibration, and artificial lift optimization. One row per wellbore per test date.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `WELL_TEST_ID` | integer | | Surrogate key for the well test row. |
| `WELLBORE_KEY` | string | | Foreign key to wellbore.wellbore\_key. |
| `TEST_DATE` | date | | Date on which the well test was performed. |
| `OIL_RATE` | number | bbl/d | 24-hour oil production rate in barrels per day. Semi-additive: do not sum across wellbores. |
| `GAS_RATE` | number | Mcf/d | 24-hour gas production rate in Mcf per day. Semi-additive: do not sum across wellbores. |
| `WATER_RATE` | number | bbl/d | 24-hour water production rate in barrels per day. Semi-additive: do not sum across wellbores. |
| `FLOWING_WELLHEAD_PRESSURE` | number | psi | Pressure at the wellhead while flowing during the test. Semi-additive. |
| `BOTTOM_HOLE_PRESSURE` | number | psi | Bottom hole pressure during the test. Semi-additive. |
| `SHUT_IN_WELLHEAD_PRESSURE` | number | psi | Pressure at the wellhead while shut-in during the test. Semi-additive. |
| `OIL_GRAVITY` | number | deg API | API gravity of produced oil in degrees, measured at standard conditions (60°F). Conventional buckets: <22.3 = heavy, 22.3–31.1 = medium, >31.1 = light, >50 = condensate. Property of the fluid sample at this test event. |
| `GAS_SPECIFIC_GRAVITY` | number | SG | Specific gravity of produced gas relative to air, air = 1.0. A property of the fluid sample at this test event, not of the wellbore: a wellbore with several tests has several values, and the most recent one is a derivation rather than this column. Dry pipeline gas is typically 0.55–0.70; richer casinghead and condensate-associated gas runs higher, and values above roughly 1.0 indicate a heavy, NGL-rich stream. Non-additive: never sum, and average only with volume weighting. Sparse by design, NULL means this test reported no gas gravity, which is the common case, while the absence of a row means no test. minimum: 0 is a physical floor, consistent with the other measures on this entity; it is not a range check. Sources that range-guard the value (the primary US source discards readings outside 0.5–1.5) do so before it reaches this column, and a source that does not is not caught here. |
| `REPORT_DATE` | date | | Date when the test was first reported. May differ from test\_date. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the record was created. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update. |
---
# Completion and stimulation
Source: https://developers.novilabs.com/data/tables/completions/
> Completion design, intensity ratios, and FracFocus disclosures.
Views live in `NOVI_DATA_ACCESS.NOVI_WELLS`. Column descriptions are from the Wells data dictionary, release 26.4.3. Type is the data model's logical type, and unit appears where the model declares one. For Snowflake column types, query `NOVI_DATA_ACCESS.INFORMATION_SCHEMA.COLUMNS`.
## WELL_COMPLETION
Completion/stimulation state and summary parameters for a wellbore. One row per completion event per wellbore; a recompletion has the next `COMPLETION_SEQUENCE`. Mass/volume values represent total injected amounts (proppant\_mass in lbs, fluid\_volume in gal). `PROPPANT_LOADING`, `PROPPANT_CONCENTRATION` and `STAGE_SPACING` are first-completion ratios computed by Novi; fluid per foot is not published.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `WELL_COMPLETION_ID` | integer | | Surrogate key for the completion row. |
| `WELLBORE_KEY` | string | | Foreign key to wellbore.wellbore\_key. |
| `COMPLETION_SEQUENCE` | integer | | 1 = first completion; increment for recompletions/re-fracs. |
| `COMPLETION_STATE` | string | | Completion lifecycle state (derived from events or operational tracking). |
| `COMPLETION_END_DATE` | date | | Date completion operations ended (if known). |
| `PROPPANT_MASS` | number | lb | Total proppant mass injected during completion. |
| `FLUID_VOLUME` | number | gal | Total completion fluid volume injected, in gallons. |
| `STAGE_COUNT` | integer | | Number of frac stages completed. Omit the field when the stage count is unknown. Do not store 0 for unknown, 0 is not a valid stage count. |
| `PERFORATION_UPPER` | integer | ft | Shallowest perforation depth (MD) in feet. |
| `PERFORATION_LOWER` | integer | ft | Deepest perforation depth (MD) in feet. |
| `PERFORATION_INTERVAL` | integer | ft | Perforation interval length in feet (perforation\_lower - perforation\_upper). |
| `SOAK_TIME_DAYS` | integer | day | Number of days between the end of the first completion and the start of production (the soak period). NULL when the span is zero or negative, longer than 365 days, or shorter than 30 days where the first-production date is not known accurately. Do not sum across wellbores. |
| `PROPPANT_LOADING` | number | lb/ft | Proppant mass per foot of lateral for the first completion, in lb/ft, computed by Novi rather than from `PROPPANT_MASS` and a lateral length here. Non-additive ratio, never sum across wellbores. Its denominator is the lateral length Novi selected for the well, so a peer-set figure is an average of ratios rather than a ratio of totals. WELLBORE carries that length as `LATERAL_LENGTH`, with its method in `LATERAL_LENGTH_SOURCE`; the ratio need not equal `PROPPANT_MASS` / `LATERAL_LENGTH` on every row. Values above 9,000 lb/ft are nulled as physically impossible rather than clamped, so a NULL can mean no credible ratio exists for the well even when `PROPPANT_MASS` is present. Also NULL when Novi's selected lateral length for the well is unknown or zero. Truncated to whole lb/ft. Populated for the first completion only. `WELLBORE_COMPLETION_DESIGN` and `WELL_DETAIL` publish the same number as `PROPPANT_LOADING`. |
| `PROPPANT_CONCENTRATION` | number | lb/gal | Proppant mass, in pounds, per gallon of completion fluid for the first completion, computed by Novi rather than here from `PROPPANT_MASS` and `FLUID_VOLUME`, so it need not equal their quotient on the same row. Non-additive ratio, never sum across wellbores. NULL when proppant mass or fluid volume is unknown or zero, and when the ratio exceeds 8 lb/gal, which Novi treats as not credible; values above 8 are nulled, not clamped. Rounded to 2 decimal places. Populated for the first completion only. `WELLBORE_COMPLETION_DESIGN` and `WELL_DETAIL` publish the same number as `PROPPANT_CONCENTRATION`. |
| `STAGE_SPACING` | number | ft | Average distance between frac stages of the first completion, in feet: the lateral length Novi selected for the well (the denominator of `PROPPANT_LOADING`) divided by the first completion's stage count. Non-additive ratio, never sum across wellbores. WELLBORE carries that length as `LATERAL_LENGTH`, with its method in `LATERAL_LENGTH_SOURCE`. NULL when the stage count is zero or the lateral length is unknown. Whole feet. No bounds are applied, so implausibly large or small values (a few under 20 ft) are possible and are published as computed. Populated for the first completion only. `WELLBORE_COMPLETION_DESIGN` and `WELL_DETAIL` publish the same number as `STAGE_SPACING`. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the completion record was created in this system. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update to this completion record. |
## FRAC_FOCUS_SUMMARY
Summary of a FracFocus chemical disclosure for a hydraulic fracturing event. One row per wellbore per frac sequence number. Contains processed/cleaned summary data from FracFocus along with Novi quality check scores and original ff-prefixed raw fields. Links to wellbore via wellbore\_key; the wellbore's regulatory identifier is available on wellbore.native\_id.
| Column | Description |
| --- | --- |
| `FRAC_FOCUS_SUMMARY_ID` | Surrogate key. |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key. |
| `SEQUENCE_NR` | Sequence number of this frac event for the wellbore (0 = first). |
| `START_DATE` | Start date of the fracturing event. |
| `END_DATE` | End date of the fracturing event. |
| `DURATION_DAYS` | Duration of the fracturing event in days. |
| `FLUID_VOLUME` | Total fluid volume used in gallons. Additive. |
| `PROPPANT_MASS` | Total proppant mass in pounds. Additive. |
| `PROPPANT_MAIN_TYPE` | Main proppant type (e.g., "Sand"). |
| `PROPPANT_MAIN_MESH` | Main proppant mesh size (e.g., "20/40"). |
| `CHECK_DATE` | Quality score for date reliability (0-100; 100 = no inconsistencies). Non-additive. |
| `CHECK_WATER_VOLUME` | Quality score for fluid volume reliability. Non-additive. |
| `CHECK_PROPPANT_MASS` | Quality score for proppant mass reliability. Non-additive. |
| `FF_TOTAL_BASE_WATER_VOLUME` | Original FracFocus total base water volume in gallons. |
| `FF_TOTAL_BASE_NON_WATER_VOLUME` | Original FracFocus total non-water volume in gallons. |
| `FF_TVD` | Original FracFocus TVD in feet. |
| `FF_LATITUDE` | Original FracFocus latitude in decimal degrees, in the geodetic datum stated on the disclosure (NAD27, NAD83 or WGS84); the datum is unknown where the disclosure states none. Coordinates in different datums are not directly comparable. |
| `FF_LONGITUDE` | Original FracFocus longitude in decimal degrees, in the geodetic datum stated on the disclosure (NAD27, NAD83 or WGS84); the datum is unknown where the disclosure states none. Coordinates in different datums are not directly comparable. |
| `FF_OPERATOR` | Original FracFocus operator name. |
| `FF_PKEY` | Original FracFocus primary key. |
| `OFS_COMPANY_ORIGINAL` | Original oil field service company that performed the job. |
| `OFS_COMPANY_CURRENT` | Current identity of OFS company after M&A. |
| `REPORT_DATE` | Date the disclosure was first reported to FracFocus. |
| `FF_PROJECTION` | Geodetic datum of ff\_latitude and ff\_longitude as stated on the FracFocus disclosure. NULL where the disclosure states none. Coordinates in different datums are not directly comparable. |
| `FF_VERSION` | Version of the FracFocus disclosure form the disclosure was filed on (e.g. 1.0-4.0). The fields a disclosure carries differ between form versions. NULL where not stated. A label, not a measure: never aggregate. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | Timestamp the record was created. |
| `UPDATED_AT` | Timestamp of the most recent update. |
## FRAC_FOCUS_INGREDIENT
Detailed chemical ingredient from a FracFocus disclosure. One row per ingredient per disclosure. Contains original FracFocus fields (ff-prefixed) for trade name, supplier, purpose, CAS number, and concentration percentages.
| Column | Description |
| --- | --- |
| `FRAC_FOCUS_INGREDIENT_ID` | Surrogate key. |
| `WELLBORE_KEY` | Foreign key to wellbore.wellbore\_key. |
| `FRAC_FOCUS_SUMMARY_ID` | Foreign key to frac\_focus\_summary.frac\_focus\_summary\_id (parent disclosure). |
| `FF_PKEY` | Original FracFocus primary key for the ingredient row. |
| `SEQUENCE_NR` | Sequence number linking to the parent FracFocusSummary. |
| `FF_PKEY_DISCLOSURE` | Original primary key of the parent FracFocus disclosure. Required for traceability back to FracFocus source data. |
| `FF_TRADE_NAME` | Product trade name as reported by the supplier. |
| `FF_SUPPLIER` | Company that supplied the product for the frac job. |
| `FF_PURPOSE` | Purpose of the ingredient (e.g., Surfactant, Biocide, Proppant). |
| `FF_INGREDIENT_NAME` | Chemical ingredient name from FracFocus. |
| `FF_CAS_NUMBER` | Chemical Abstract Service identification number (CAS RN format: 2-7 digits, hyphen, 2 digits, hyphen, 1 check digit). |
| `FF_PERCENT_HIGH_ADDITIVE` | Percent of the ingredient in the trade name product (top of range from MSDS). |
| `FF_PERCENT_HF_JOB` | Percent of the ingredient in the total hydraulic fracturing volume by mass. |
| `FF_MASS_INGREDIENT` | Mass of this ingredient. |
| `FF_CLAIMANT_COMPANY` | Company claiming trade secret for this ingredient. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | Timestamp the record was created. |
| `UPDATED_AT` | Timestamp of the most recent update. |
---
# Forecasts
Source: https://developers.novilabs.com/data/tables/forecasts/
> Monthly production forecasts, Arps decline segments and parameters, and county supply projections.
Views live in `NOVI_DATA_ACCESS.NOVI_WELLS`. Column descriptions are from the Wells data dictionary, release 26.4.3. Type is the data model's logical type, and unit appears where the model declares one. For Snowflake column types, query `NOVI_DATA_ACCESS.INFORMATION_SCHEMA.COLUMNS`.
## PRODUCTION_FORECAST
Forecasted monthly production for a wellbore. One row per (wellbore\_key, forecast\_day, scenario). This projection currently ships monthly granularity only (period\_granularity='monthly') and the P50 scenario only, the source is monthly and emits a single deterministic forecast. Stream rates (oil/gas/water) come from source; oil carries condensate combined, as the source oil does, and NGL and condensate are NULL. Cumulative columns aggregate over the forecast horizon. The year / month pair carries the PRODUCTION month each row represents, not a revenue month, and is the calendar axis for aligning rows with actual production and with production\_forecast\_arps\_segment.segment\_start\_date. Do not align on forecast\_day, which is a nominal period ordinal rather than elapsed time; see its description.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `PRODUCTION_FORECAST_ID` | integer | | Identifier that groups the period rows of one forecast. Shared by those rows, so it is not unique per row. |
| `WELLBORE_KEY` | string | | Foreign key to wellbore.wellbore\_key. |
| `PERIOD_GRANULARITY` | string | | Granularity of this forecast record. A yearly record is a 12-month block counted from the first month of the wellbore's monthly series, not a calendar year. |
| `FORECAST_DAY` | integer | day | Period index relative to initial production (IP), expressed in nominal day units. For monthly records this is the month ordinal times 30, where the ordinal is 1-based (so month 1 encodes as 30); for weekly records, multiples of 7. The lowest value actually present in a given fact depends on which months that fact carries, a forecast-only projection whose historical months are excluded starts at whatever month the forecast begins, not at 30. NOT a count of elapsed days, dividing by 30 recovers the month index exactly, and real elapsed time drifts from it by roughly 0.44 days per month (about 264 days over a 600-month horizon). Same 1-based month ordinal as `MONTHS_ON_PRODUCTION` (times 30 for monthly records). Use forecast\_day to order rows within this fact. Do NOT use it as an alignment key against production\_forecast\_arps\_segment.day\_start (real calendar days) or for discounting; align on year / month, or on the segment's segment\_start\_date / segment\_end\_date. |
| `YEAR` | integer | | Calendar year of the production month this forecast row represents. Not the revenue month, revenue conventionally lags production by 1–2 months. Together with month, this is the alignment axis against actual production and against production\_forecast\_arps\_segment.segment\_start\_date. On yearly records, the calendar year of forecast\_date, the first month of the 12-month block. |
| `MONTH` | integer | | Calendar month number (1–12) of the production month this forecast row represents. Not the revenue month. See year. On yearly records, the calendar month of forecast\_date, the first month of the 12-month block. |
| `SCENARIO` | string | | Forecast scenario. This release publishes P50, the median forecast, only. |
| `OIL_PER_DAY` | number | bbl/d | Oil rate (bbl/d). May carry oil and condensate as a single combined rate, in which case condensate\_per\_day is null; a populated oil rate beside a null condensate rate therefore does not assert that no condensate is forecast. Semi-additive; do not sum across wells without producing\_days weighting. On yearly records, the 12-month block's volume divided by the calendar days of that block counted from forecast\_date (365 or 366), so a final partial block is still divided by a full block. |
| `CUMULATIVE_OIL` | number | bbl | Cumulative oil volume (bbl), combined with condensate on the same rows as oil\_per\_day (cumulative\_condensate is then null), accumulated over the FORECAST horizon only: the running total of this fact's own per-period forecast volumes, from the first forecast period at this row's period\_granularity. It excludes production that occurred before the forecast starts; historical volumes live in production. Semi-additive: it may be summed across wellbores at a fixed period, but must NEVER be summed across periods; it is already a running total, so summing double-counts. To recover a single period's volume, difference consecutive rows. |
| `GAS_PER_DAY` | number | Mcf/d | Gas rate (Mcf/d). Semi-additive; do not sum across wells without producing\_days weighting. On yearly records, the 12-month block's volume divided by the calendar days of that block counted from forecast\_date (365 or 366), so a final partial block is still divided by a full block. |
| `CUMULATIVE_GAS` | number | Mcf | Cumulative gas volume (Mcf), accumulated over the FORECAST horizon only: the running total of this fact's own per-period forecast volumes, from the first forecast period at this row's period\_granularity. It excludes production that occurred before the forecast starts; historical volumes live in production. Semi-additive: it may be summed across wellbores at a fixed period, but must NEVER be summed across periods; it is already a running total, so summing double-counts. To recover a single period's volume, difference consecutive rows. |
| `NGL_PER_DAY` | number | bbl/d | NGL rate (bbl/d). Semi-additive; do not sum across wells without producing\_days weighting. On yearly records, the 12-month block's volume divided by the calendar days of that block counted from forecast\_date (365 or 366), so a final partial block is still divided by a full block. |
| `CUMULATIVE_NGL` | number | bbl | Cumulative NGL volume (bbl), accumulated over the FORECAST horizon only: the running total of this fact's own per-period forecast volumes, from the first forecast period at this row's period\_granularity. It excludes production that occurred before the forecast starts; historical volumes live in production. Semi-additive: it may be summed across wellbores at a fixed period, but must NEVER be summed across periods; it is already a running total, so summing double-counts. To recover a single period's volume, difference consecutive rows. |
| `WATER_PER_DAY` | number | bbl/d | Water rate (bbl/d). Semi-additive; do not sum across wells without producing\_days weighting. On yearly records, the 12-month block's volume divided by the calendar days of that block counted from forecast\_date (365 or 366), so a final partial block is still divided by a full block. |
| `CUMULATIVE_WATER` | number | bbl | Cumulative water volume (bbl), accumulated over the FORECAST horizon only: the running total of this fact's own per-period forecast volumes, from the first forecast period at this row's period\_granularity. It excludes production that occurred before the forecast starts; historical volumes live in production. Semi-additive: it may be summed across wellbores at a fixed period, but must NEVER be summed across periods; it is already a running total, so summing double-counts. To recover a single period's volume, difference consecutive rows. |
| `CONDENSATE_PER_DAY` | number | bbl/d | Condensate rate (bbl/d). Null wherever condensate is not carried separately; the rate may then be combined into oil\_per\_day, so a null does not establish that none is forecast. Semi-additive; do not sum across wells without producing\_days weighting. On yearly records, the 12-month block's volume divided by the calendar days of that block counted from forecast\_date (365 or 366), so a final partial block is still divided by a full block. |
| `CUMULATIVE_CONDENSATE` | number | bbl | Cumulative condensate volume (bbl), null wherever condensate is not carried separately (it may then be combined into cumulative\_oil), accumulated over the FORECAST horizon only: the running total of this fact's own per-period forecast volumes, from the first forecast period at this row's period\_granularity. It excludes production that occurred before the forecast starts; historical volumes live in production. Semi-additive: it may be summed across wellbores at a fixed period, but must NEVER be summed across periods; it is already a running total, so summing double-counts. To recover a single period's volume, difference consecutive rows. |
| `FORECAST_DATE` | date | | First day of the calendar month whose production this row forecasts (e.g. 2034-03-01): the forecast production month, not the revenue month, which typically lags 1–2 months. On yearly records, the first day of the first month of the 12-month block; not 1 January. On monthly records it joins to production.production\_date by value; on yearly records it matches only the block's first month. |
| `FORECAST_MONTH` | integer | | 1-based index of the month within the wellbore's monthly series of consecutive months, 1 being the series' earliest month. On monthly records, the month this row forecasts, equal to forecast\_day / 30. On yearly records, the last month present in the 12-month block: the year ordinal times 12, or less for a final partial year. An ordinal index, not a calendar month: see month for the calendar month. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Source ingestion timestamp from the production forecast feed. |
## PRODUCTION_FORECAST_ARPS_SEGMENT
An ARPS forecast segment refers to a specific time range for a single production stream of a wellbore. Each segment consists of a continuous number of days that share the same ARPS regime (for example, buildup, transition, or terminal). Segments are numbered starting from one and are ordered sequentially; they must not overlap within a specific combination of wellbore\_key and production\_stream.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `WELLBORE_KEY` | string | | Foreign key to wellbore.wellbore\_key. |
| `PRODUCTION_FORECAST_ID` | integer | | Forecast run to which this segment belongs. Use to group segments and parameters by a single forecast execution. May be NULL when no parent production\_forecast row exists for this segment. |
| `SEGMENT_UID` | integer | | Stable, immutable unique identifier for this segment. |
| `PRODUCTION_STREAM` | string | | Which stream this segment forecasts (e.g., oil, gas, ngl, water, condensate). |
| `SEGMENT_NUMBER` | integer | | 1-based index of the segment within the stream for the wellbore\_key. |
| `KIND` | string | | ARPS regime represented by this segment: - buildup: early-time pre-decline behavior, - transition: changeover period between regimes, - terminal: late-time decline segment. |
| `SEGMENT_CURVE_TYPE` | string | | Type of decline curve applied in this segment. 'exponential' assumes constant nominal decline D; 'hyperbolic' uses exponent b (0<b<1 typical; b=1 is harmonic); 'linear' is a buildup-phase ramp where rate increases linearly from segment\_start\_rate to segment\_end\_rate over (day\_stop - day\_start) days (no decline math applies). 'linear' is only valid when kind='buildup'. |
| `DAY_START` | integer | | Inclusive day index where this segment begins, in real calendar days since first production (0 = first day of production). This is the axis the segment's Arps parameters were fitted against and is the correct axis for evaluating the curve within this fact. It is NOT comparable to production\_forecast.forecast\_day, which is a nominal 30-day month ordinal rather than a day count; matching the two drifts by a median of 129 days and up to 236, well-specific and uncorrectable by a constant. To align this fact with production\_forecast, use segment\_start\_date / segment\_end\_date against year / month. |
| `DAY_STOP` | integer | | Inclusive day index where this segment ends, in real calendar days since first production. Must be >= day\_start for valid datasets (cannot be enforced portably in standard JSON Schema). Same axis and same caveats as day\_start; (day\_stop - day\_start) is the segment duration in days, used by the 'linear' segment\_curve\_type ramp. |
| `SEGMENT_START_DATE` | date | | Calendar date on which this segment begins, inclusive (YYYY-MM-DD). The alignment axis between this fact and production\_forecast: a monthly forecast row belongs to the segments whose \[segment\_start\_date, segment\_end\_date\] range overlaps its year/month. Anchors the fitted curve to real calendar time, which is what evaluating a segment against actual monthly production requires. NULL when the wellbore has no calendar anchor (no first-production date), in which case consumers must fall back to the relative day\_start / day\_stop offsets. |
| `SEGMENT_END_DATE` | date | | Calendar date on which this segment ends, inclusive (YYYY-MM-DD). NULL when the wellbore has no calendar anchor. See segment\_start\_date. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
## PRODUCTION_FORECAST_ARPS_SEGMENT_PARAMETER
Parameter values associated with a single ARPS forecast segment. These parameters describe decline behavior and rates for the segment referenced by forecast\_segment\_id. Units for rates should match the stream's production rate (e.g., bbl/d, mcf/d). Decline rates are per-day fractions unless otherwise noted.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `FORECAST_SEGMENT_ID` | integer | | Foreign key to the ARPS segment this parameter set applies to. Must reference an existing ProductionForecastArpsSegment.segment\_uid. |
| `SEGMENT_PARAMETER_UID` | integer | | Stable unique identifier for this parameter row. |
| `B_FACTOR` | number | | Hyperbolic decline exponent b. >0 for hyperbolic; b=1 is harmonic; values typically in (0, 2\]. Only relevant when the segment curve type is hyperbolic/harmonic. |
| `EFFECTIVE_DECLINE_RATE_TANGENT` | number | | D\_eff (tangent), effective decline rate using the tangent (instantaneous) approximation over a 1-day interval (dimensionless fraction in \[0,1)). For exponential decline, D\_eff\_tangent = 1 - e^{-D\_nom}. This is the point-in-time derivative of the decline curve; use effective\_decline\_rate\_secant for the average-interval approximation. |
| `EFFECTIVE_DECLINE_RATE_SECANT` | number | | D\_eff (secant), effective decline rate using the secant (average-interval) approximation over a 1-day interval (dimensionless fraction in \[0,1)). For exponential decline, D\_eff\_secant = 1 - (q(t+1)/q(t)). Secant is the discrete-period average decline; needed for ARIES export and reproducibility alongside the tangent approximation. |
| `NOMINAL_DECLINE_RATE` | number | | D\_nom, nominal decline parameter used in ARPS (1/day). Constant for exponential; initial value for hyperbolic at segment start. |
| `SEGMENT_START_RATE` | number | | q\_start, production rate at the beginning of the segment (same units as stream, e.g., bbl/d or mcf/d). |
| `SEGMENT_END_RATE` | number | | q\_end, production rate at the end of the segment (same units as stream). Should be <= q\_start for decline segments (cannot be enforced portably here). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the record was created. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update. |
## SUPPLY_PROJECTION
County-level type curve projections for oil and gas supply modeling. One row per county per production-start-month cohort per months-on-production. Provides average forecasted production rates and volumes per well for horizontal wells that started producing since 2010.
| Column | Description |
| --- | --- |
| `SUPPLY_PROJECTION_ID` | Surrogate key. |
| `COUNTY_CODE` | FIPS county code. |
| `MONTH_OF_PRODUCTION_START` | First day of the month in which the cohort started producing. |
| `MONTHS_ON_PRODUCTION` | Month index from first production. Uses the same convention as PRODUCTION.`MONTHS_ON_PRODUCTION`: 1 = the first month on production, or 0 for a distinguished incomplete first month before full month 1. For supply projections the first index represents the cohort's first month on production. |
| `DATE` | Calendar date for this data point. |
| `YEAR_OF_PRODUCTION_START` | Year the cohort started producing. |
| `OIL_PER_MONTH_PROJECTED` | Average forecasted oil production per well for this month. A per-well average, so it is non-additive: summing it across cohorts or months does not give a total volume. |
| `OIL_PER_DAY_PROJECTED` | Average forecasted oil production rate per well per day. Non-additive (rate average). |
| `GAS_PER_MONTH_PROJECTED` | Average forecasted gas production per well for this month. A per-well average, so it is non-additive: summing it across cohorts or months does not give a total volume. |
| `GAS_PER_DAY_PROJECTED` | Average forecasted gas production rate per well per day. Non-additive (rate average). |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
| `UPDATED_AT` | Timestamp of the most recent update. |
---
# Spacing and subsurface
Source: https://developers.novilabs.com/data/tables/spacing-subsurface/
> Well spacing metrics, the settings behind them, and subsurface rock properties.
Views live in `NOVI_DATA_ACCESS.NOVI_WELLS`. Column descriptions are from the Wells data dictionary, release 26.4.3. Type is the data model's logical type, and unit appears where the model declares one. For Snowflake column types, query `NOVI_DATA_ACCESS.INFORMATION_SCHEMA.COLUMNS`.
## WELL_SPACING
Spacing metrics for a single wellbore, including nearest neighbor distances, parent/child classification, and density metrics. One row per wellbore. Used for frac hit analysis, spacing optimization, and parent-child interference studies. All distance fields are non-additive.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `WELL_SPACING_ID` | integer | | Surrogate key. |
| `WELLBORE_KEY` | string | | Foreign key to wellbore.wellbore\_key. |
| `CLOSEST_WELL_XY` | number | ft | XY distance to the closest lateral and staggered neighbor in feet. Non-additive. |
| `WELLS_IN_RADIUS` | integer | | Count of all wells within the neighbor distance radius. |
| `CLOSEST_TWO_AVG_XY` | number | ft | Average XY distance to the two closest neighbors (includes staggered and stacked). Non-additive. |
| `WELLS_IN_RADIUS_AVG_XY` | number | ft | Total wells in radius converted to a distance = 2 \* MaxNeighborDistance / (1 + WellsInRadius). Non-additive. |
| `IS_CHILD` | boolean | | True if this well is classified as a child well (drilled after nearby parent wells were producing). |
| `PARENT_COUNT` | integer | | Number of neighboring parent wells meeting spacing criteria. |
| `PARENT_DAYS_ONLINE` | number | day | Days the nearest parent well was online relative to this well's start. |
| `LATERAL_CLOSER_XY` | number | ft | XY distance to the nearest well in the same lateral row. Non-additive. |
| `STAGGER_CLOSER_TANGENT` | number | ft | Tangent distance to the nearest staggered well. Non-additive. |
| `STACK_CLOSER_Z` | integer | ft | Vertical distance to the nearest well in the same vertical stack. Non-additive. |
| `BOUNDEDNESS_SCORE` | integer | | Number of neighbor quadrants occupied by wells (0-8). Non-additive. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the record was created. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update. |
## WELL_SPACING_CONFIGURATION
Configuration settings used to compute well\_spacing metrics. One row per (basin, subbasin): the source defines parameters per basin, and the same parameters are emitted for every subbasin under that basin, so a wellbore's basin resolves to exactly one config row. Includes search radii, cutoff angles, and threshold parameters.
| Column | Description |
| --- | --- |
| `WELL_SPACING_CONFIG_ID` | Surrogate key. |
| `LENGTH_UNIT` | Length unit for spacing data (e.g., "feet"). |
| `MAX_NEIGHBOR_DISTANCE` | Search radius for neighbor detection. |
| `MAX_VERTICAL_DISTANCE` | Maximum vertical distance to count as a neighbor. |
| `MAX_PARENT_VERTICAL_DISTANCE` | Maximum vertical distance to count as a parent. |
| `HORIZONTAL_CUTOFF_ANGLE` | Angle threshold for lateral neighbor identification. |
| `VERTICAL_CUTOFF_ANGLE` | Angle threshold for stacked neighbor identification. |
| `HORIZONTAL_MAX_OF_STACKED_NEIGHBORS` | Max horizontal distance for stacked neighbor. |
| `VERTICAL_MAX_OF_LATERAL_NEIGHBORS` | Max vertical distance for lateral neighbor. |
| `PARENT_CUTOFF_DAYS` | Parent must be producing at least this many days before child. |
| `MIN_LATERAL_LENGTH_FOR_NEIGHBORS` | Minimum lateral length for a well to count as a neighbor. |
| `DEFAULT_LATERAL_DISTANCE` | Default distance when no neighbor is detected. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
## SUBSURFACE_PROPERTY
Subsurface petrophysical and geomechanical properties at a specific point/depth along a wellbore, optionally mapped to a directional survey station when one exists. Properties include porosity, permeability, brittleness, thickness, water saturation, TOC, and hydrocarbon-in-place estimates, all formation-averaged at the measurement point's depth. Every row anchors to a wellbore via wellbore\_key; rows with directional-survey coverage additionally carry survey\_station\_id for station-grain analytics (along-trajectory and spatial queries).
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `SUBSURFACE_PROPERTY_ID` | integer | | Surrogate key. |
| `WELLBORE_KEY` | string | | Foreign key to wellbore.wellbore\_key, the canonical anchor for every subsurface\_property row. Populated for all rows; the optional survey\_station\_id provides finer station-grain attachment when available. |
| `SURVEY_STATION_ID` | integer | | Optional foreign key to directional\_survey\_station.survey\_station\_id. Populated when the wellbore has a matching directional survey station for the row's location type; NULL when the parent wellbore has no directional-survey coverage. Use wellbore\_key as the always-populated anchor. |
| `LOCATION_TYPE` | integer | | Type of measurement point along the wellbore, shared value enum (not a foreign key) with directional\_survey\_station.location\_type. Part of the natural key: disambiguates multiple measurements at different points along the same wellbore and formation. Required even when survey\_station\_id is NULL so unmatched rows still carry positional context. |
| `STRUCTURAL_DEPTH` | number | ft | Depth of the top of the formation (TVDSS). |
| `BRITTLENESS_AVG` | number | | Average brittleness of the formation, as an index whose unit and range are not defined; not a 0-1 fraction or a percentage. Non-additive. |
| `COMPETENCY_AVG` | number | | Average rock competency of the formation, as an index whose unit and range are not defined; not a 0-1 fraction. Non-additive. |
| `THICKNESS_AVG` | number | ft | Gross isopach (formation thickness) in feet. |
| `PERMEABILITY_AVG` | number | mD | Average permeability calibrated to core and production matching, in millidarcies. |
| `PERMEABILITY_HEIGHT_AVG` | number | mD-ft | Average permeability times gross thickness (kh product) in millidarcy-feet. |
| `POROSITY_AVG` | number | pct | Effective porosity in percentage (porosity units). |
| `POROSITY_HEIGHT_AVG` | number | pct-ft | Average porosity times gross thickness (phi-h product). |
| `STOIIP_AVG` | number | MMbbl/sq\_mi | Stock tank oil initially in place, million barrels per section (sq. mi). |
| `SW_AVG` | number | pct | Average water saturation as a percentage. |
| `TOC_AVG` | number | pct | Average total organic carbon as a percentage. |
| `VCLAY_AVG` | number | pct | Average volume of clay as a percentage. |
| `BVI_AVG` | number | pct | Average bulk volume irreducible water as a percentage. |
| `NTG_AVG` | number | | Net-to-gross ratio (dimensionless). |
| `GIIP_AVG` | number | Bcf/sq\_mi | Gas initially in place, billion cubic feet per section (sq. mi). |
| `BRITTLENESS_OF_NET` | number | | Brittleness averaged over net pay cutoffs within the formation, on the same scale as brittleness\_avg. Unit and range are not defined. Non-additive. |
| `COMPETENCY_OF_NET` | number | | Competency averaged over net pay cutoffs, on the same scale as competency\_avg. Unit and range are not defined. Non-additive. |
| `THICKNESS_OF_NET` | number | ft | Net pay thickness in feet. |
| `PERMEABILITY_OF_NET` | number | mD | Permeability averaged over net pay cutoffs, in millidarcies. |
| `PERMEABILITY_HEIGHT_OF_NET` | number | mD-ft | Permeability-height product over net pay cutoffs, in millidarcy-feet. |
| `POROSITY_OF_NET` | number | pct | Porosity averaged over net pay cutoffs. |
| `POROSITY_HEIGHT_OF_NET` | number | pct-ft | Porosity-height product over net pay cutoffs. |
| `STOIIP_OF_NET` | number | MMbbl/sq\_mi | Oil in place over net pay cutoffs. |
| `SW_OF_NET` | number | pct | Water saturation over net pay cutoffs. |
| `TOC_OF_NET` | number | pct | TOC over net pay cutoffs. |
| `VCLAY_OF_NET` | number | pct | Volume of clay over net pay cutoffs. |
| `BVI_OF_NET` | number | pct | Irreducible water over net pay cutoffs. |
| `GIIP_OF_NET` | number | Bcf/sq\_mi | Gas in place over net pay cutoffs. |
| `FORMATION` | string | | Novi's best estimate of the actual target formation. |
| `REPORTED_FORMATION` | string | | Target formation as reported by the state. |
| `GRID_FORMATION` | string | | Formation based on subsurface grid studies. |
| `PERCENT_IN_ZONE` | integer | pct | Percentage of lateral in the grid formation. |
| `DISTANCE_FROM_TOP` | integer | ft | Feet from top of formation, based on grids and survey. |
| `DISTANCE_FROM_BASE` | integer | ft | Feet from base of formation, based on grids and survey. |
| `NORMALIZED_DISTANCE_TO_TOP` | number | | Value 0-1 where 0 = drilled at top of zone, 1 = drilled at base of zone. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the record was created. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update. |
---
# Permits and well events
Source: https://developers.novilabs.com/data/tables/permits-events/
> Drilling permits, permit filings, and the well lifecycle event timeline.
Views live in `NOVI_DATA_ACCESS.NOVI_WELLS`. Column descriptions are from the Wells data dictionary, release 26.4.3. Type is the data model's logical type, and unit appears where the model declares one. For Snowflake column types, query `NOVI_DATA_ACCESS.INFORMATION_SCHEMA.COLUMNS`.
## PLANNED_WELL
Permitted wells, sourced from state and other public drilling permit filings. One row per permit. This is the public record of what operators have filed, not Novi Labs' own view of drilling inventory. Most rows describe wells that have since been drilled: where that has happened, status is COMPLETED and materialized\_well\_key points at the resulting well row in well / wellbore. Rows with status PROPOSED or PERMITTED are the forward-looking subset.
| Column | Description |
| --- | --- |
| `PLANNED_WELL_ID` | Stable, immutable identifier for this planned well. |
| `MATERIALIZED_WELL_KEY` | Foreign key to well.well\_key once the permitted well has actually been drilled. Non-null on the majority of rows, because most permits on file correspond to wells that already exist. NULL while the permit is still forward-looking or was cancelled. |
| `OPERATOR_ID` | Current operator. |
| `PAD_ID` | Always NULL in this product: no pad entity is published, and pads are not derived from coordinates. There is no published table to join it to. |
| `NAME` | Human-friendly planned well name (e.g., operator naming). Not a key. |
| `COUNTY` | County or parish where the planned well is located. |
| `TARGET_FORMATION` | Intended target formation/bench for the lateral (e.g., 'Wolfcamp A'). |
| `LATERAL_LENGTH` | Planned horizontal lateral length in feet. |
| `STATUS` | Planning lifecycle status. |
| `PLANNED_SPUD_DATE` | Scheduled spud date. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | Timestamp the plan was created. |
| `UPDATED_AT` | Timestamp of the most recent update. |
## WELL_PERMIT
Regulatory drilling permit records associated with a wellbore. One row per permit filing; captures the permitted operator and the proposed wellbore depths as declared in the application. Permit lifecycle milestones (submitted / approved / amended / cancelled) are recorded as `PERMIT_`\* events on well\_event, linked via well\_event.permit\_id.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `WELLBORE_KEY` | string | | Foreign key to wellbore.wellbore\_key that this permit applies to, resolved from the permit's api10. Every emitted well\_permit row links to an existing wellbore; permits whose api10 does not resolve to a wellbore are not represented. |
| `PERMIT_ID` | string | | Regulatory permit identifier as issued by the state/agency. Not unique on its own, a regulator id recurs across states/datasets/permit revisions; the per-row grain is (permit\_id, wellbore\_key). |
| `OPERATOR_ID` | integer | | Operator that filed for or holds the permit (foreign key to operator.operator\_id). Optional, omit (do not send null) when the filing operator cannot be resolved. |
| `PROPOSED_TVD` | number | ft | Proposed true vertical depth as declared in the permit application, in feet. The as-built value is wellbore.tvd\_td once drilled. |
| `EXPIRATION_DATE` | date | | The expiry date filed with the permit. It does not mean the permit expired. If the well was spudded, or a later permit was approved, the date is moot. A permit lapsed unused when this date has passed and `WELL_EVENT` has no SPUD and no later `PERMIT_APPROVED` event. The `PERMIT_CANCELLED` event in `WELL_EVENT` (emitted when the regulator's permit status is Cancelled or Expired, joined on `PERMIT_ID`; a permit merely past this date under another status has no event) carries this date as `EVENT_DT`. NULL when no expiry date was filed. |
| `BASIN` | | | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | | | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the permit record was created. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update. |
## WELL_EVENT
Ledger of lifecycle milestones and state changes for wells and wellbores (planning -> drilling -> completion -> production -> workovers -> P&A). New events are appended in normal operation, except event types documented as one row per well, which are updated in place when a newer occurrence is reported; physical retractions are allowed only to handle source-side corrections (e.g., when an event's underlying source field is cleared). Use event\_dt for when something happened, effective\_dt for when it should count for status/economics. Payload captures event-specific fields without changing the schema.
| Column | Description |
| --- | --- |
| `WELL_EVENT_ID` | Surrogate key for the event row. |
| `WELL_KEY` | Well-level scope for the event. Provide either well\_key or wellbore\_key (or both) depending on applicability. |
| `WELLBORE_KEY` | Wellbore-level scope for the event (e.g., SPUD, `TD_REACHED`, COMPLETED for a specific lateral). |
| `PERMIT_ID` | Foreign key to `WELL_PERMIT`.`PERMIT_ID`, the regulator-issued permit associated with this event (primarily permit-class events: `PERMIT_SUBMITTED`, `PERMIT_APPROVED`, `PERMIT_REJECTED`, `PERMIT_AMENDED`, `PERMIT_CANCELLED`, `PERMIT_ISSUED`). NULL when the event has no associated permit. `PERMIT_ID` alone is not unique in `WELL_PERMIT`, whose grain is (`PERMIT_ID`, `WELLBORE_KEY`): join on both columns. |
| `EVENT_TYPE` | Event code indicating the lifecycle milestone or change. |
| `EVENT_DT` | Timestamp when the event actually occurred (if known). May be null for planned events. |
| `EFFECTIVE_DT` | Business-effective timestamp for determining status transitions and economics (e.g., when production eligibility starts). Often equals event\_dt but may differ due to backfills or corrections. |
| `PAYLOAD` | Event-specific attributes, keyed by event\_type, captures details that vary by event without adding sparse top-level columns. The keys expected for each event type are documented on that event\_type value (see the event\_type enum). Payload keys are validated/typed via conditional schemas for `OPERATOR_CHANGE`, `WELLBORE_TYPE_CHANGE`, `PERMIT_SUBMITTED`, and the completion events (`COMPLETION_STARTED` / COMPLETED / `DRILL_OUT`); for other event types the payload keys are documented but not statically typed, so their value domains (e.g., operator\_calculated is an operator.operator\_id; wellbore\_type\_normalized is a `WELLBORE_TYPE_NORMALIZED` value; wellbore\_type\_reported is the type as the source reported it, at whatever granularity the source supplies) apply by convention. On permit events wellbore\_type\_reported carries a coarse classification (Oil, Gas, Service or Unknown), because permits have no filed code. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | Timestamp when this event record was created. |
| `UPDATED_AT` | Timestamp of the most recent update to this event record. |
---
# Acreage, activity, and prices
Source: https://developers.novilabs.com/data/tables/activity-land/
> Company acreage parcels, rig and frac activity, and weekly benchmark prices.
Views live in `NOVI_DATA_ACCESS.NOVI_WELLS`. Column descriptions are from the Wells data dictionary, release 26.4.3.
## Acreage
### COMPANY_ACREAGE
Land-parcel acreage positions held by an operator or mineral rights company. One row per individual leasehold parcel, a company can hold many parcels in the same (state, county, basin), each with its own polygon, acres, and per-parcel NRI/WI. Consumers needing company-area totals or area-weighted averages should aggregate in their own queries (SUM acres; area-weighted NRI/WI). Use geometry\_wkt as the parcel discriminator.
| Column | Description |
| --- | --- |
| `COMPANY_ACREAGE_ID` | Surrogate key. Per-parcel, distinguished by geometry within a company × state × county × basin × subbasin cell. |
| `OPERATOR_ID` | Foreign key to operator.operator\_id: the company holding the acreage position, the current holder after mergers as the source states it. Resolves to the same company that COMPANY names. |
| `COMPANY` | Name of the company holding the acreage position, as the source states it: the current holder after mergers. `OPERATOR_ID` resolves to the same company. |
| `STATE` | State name. |
| `COUNTY` | County name. |
| `SUBBASIN` | Sub-basin name. Optional, provides a finer geographic grouping than basin alone. |
| `NRI` | Net revenue interest (fraction) for this parcel. Non-additive across parcels (use area-weighted average in the analytics layer if rolling up). |
| `NRI_TYPE` | Whether the per-parcel NRI is exactly known or an area average from the source. |
| `WI` | Working interest (fraction) for this parcel. Non-additive across parcels (use area-weighted average in the analytics layer if rolling up). |
| `WI_TYPE` | Whether the per-parcel WI is exactly known or an area average from the source. |
| `ACRES` | Parcel area in acres. Additive across parcels within the same company. |
| `UPDATE_DATE` | Date the acreage data was last updated. |
| `GEOMETRY_WKT` | Well-known text representation of the parcel boundary. Required, acts as the parcel discriminator within a (company, state, county, basin, subbasin) cell. Large WKT polygons may be up to ~1MB. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
| `UPDATED_AT` | Timestamp of the most recent update. |
## Market and activity
### RIG_ACTIVITY_WEEKLY
Weekly horizontal rig count by county and basin, sourced from Baker Hughes North American Rotary Rig Count. One row per state/county/basin/subbasin per ISO week. Used for drilling activity monitoring and supply forecasting. Rig counts are semi-additive across geography but not across time.
| Column | Description |
| --- | --- |
| `RIG_ACTIVITY_WEEKLY_ID` | Surrogate key. |
| `STATE` | US state code (USPS two-letter). |
| `COUNTY` | County name. |
| `COUNTY_CODE` | FIPS county code. |
| `YEAR` | ISO week-numbering year. |
| `WEEK` | ISO week number. |
| `MONTH` | Calendar month of the Friday that falls within this ISO week. When an ISO week spans two months, the month is determined by the Friday date. Provided as a convenience for monthly aggregation. |
| `OIL_RIGS` | Number of horizontal rigs drilling for oil. Semi-additive across geography. |
| `GAS_RIGS` | Number of horizontal rigs drilling for gas. Semi-additive. |
| `OTHER_RIGS` | Number of horizontal rigs drilling for other purposes. Semi-additive. |
| `TOTAL_RIGS` | Total horizontal rigs in this county/basin for the week. Semi-additive. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | Timestamp the record was created. |
| `UPDATED_AT` | Timestamp of the most recent update. |
### RIG_FRAC_ACTIVITY
Combined rig and frac fleet activity details. One row per observation record per activity date. A record may represent a single unit or an aggregated count for a location/operator. Tracks active drilling rigs and fracturing fleets across basins with location, operator, and service company information.
| Column | Description |
| --- | --- |
| `RIG_FRAC_ACTIVITY_ID` | Surrogate key. |
| `EXTERNAL_ID` | External source identifier for this record. |
| `OPERATOR_ID` | Foreign key to operator.operator\_id. The company operating the rig or frac fleet, as the activity source names it and without further normalization: a name variant (legal suffix, spelling) can resolve to its own operator row. |
| `SERVICE_COMPANY` | Service company providing the equipment. |
| `RIG_NUMBER` | Specific rig number or identifier. |
| `COUNTRY` | Country where equipment is located. |
| `STATE_PROVINCE` | State or province. |
| `COUNTY` | County name. |
| `LATITUDE` | Latitude of the equipment location. |
| `LONGITUDE` | Longitude of the equipment location. |
| `EQUIPMENT_TYPE` | Type of equipment: Rig or Frac fleet. |
| `LOCATION_TYPE` | Deprecated: superseded by `LOCATION_METHOD`, which carries the same values on every row. Whether the location is estimated or precisely known. It will be removed in a later release, announced in that release's notes. |
| `DATA_SOURCE` | The rig/frac data provider. |
| `COUNT` | Number of units of this equipment type that the row represents. A row can aggregate several units at one location, operator and activity date; for a rig row that reports a trajectory, the count is of rigs drilling that trajectory, so rows split by trajectory are summed to get the total for their location, operator and date. |
| `ACTIVITY_DATE` | Date of the activity observation. |
| `RIG_TRAJECTORY` | Trajectory of the well the rig is drilling. Applies to rig rows only and is NULL on frac fleet rows. HORIZONTAL is also carried where the provider reports no trajectory for a rig, so it is not always a reported value; OTHER is a reported value, not a missing one. |
| `LOCATION_METHOD` | Method by which the rig or frac fleet location was determined: ESTIMATED or PRECISE. Replaces `LOCATION_TYPE`, with the same values. |
| `BASIN` | Basin name (e.g., Permian, Eagle Ford). |
| `SUBBASIN` | Subbasin name (e.g., Delaware, Midland). |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | Timestamp the record was created. |
| `UPDATED_AT` | Timestamp of the most recent update. |
### PRICE_WEEKLY
Weekly benchmark commodity prices. One row per week (Friday date). Provides WTI oil and Henry Hub gas prices. Used for economics, benchmarking, and price history analysis. Prices are non-additive point-in-time observations.
| Column | Description |
| --- | --- |
| `PRICE_WEEKLY_ID` | Surrogate key. |
| `DATE` | Friday date for this weekly price observation. |
| `OIL_PRICE` | WTI oil price in USD per barrel. Non-additive. |
| `GAS_PRICE` | Henry Hub gas price in USD per MMBtu. Non-additive. |
| `CURRENCY` | Currency for prices (defaults to USD). |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
| `UPDATED_AT` | Timestamp of the most recent update. |
---
# Operators and reference lists
Source: https://developers.novilabs.com/data/tables/reference/
> Operators, operator contacts, the basin list, and data lineage.
Views live in `NOVI_DATA_ACCESS.NOVI_WELLS`. Column descriptions are from the Wells data dictionary, release 26.4.3. Type is the data model's logical type, and unit appears where the model declares one. For Snowflake column types, query `NOVI_DATA_ACCESS.INFORMATION_SCHEMA.COLUMNS`.
## OPERATOR
A company that operates wells. One row per company. Its registrations, and the contact details filed with them, are operator\_contact rows keyed by operator\_id.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `OPERATOR_ID` | integer | | Surrogate key for the company, derived from name. |
| `WEBSITE` | string | | Operator website URL. |
| `TICKER` | string | | Stock ticker symbol. NULL when the company is not publicly traded or the ticker is unknown. |
| `IS_PUBLIC` | boolean | | Whether the organization is a publicly traded company. |
| `NAME` | string | | The company's name, verbatim as the source gave it. May contain trailing whitespace. Unique, and the value operator\_id is derived from. |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | timestamp | | Timestamp the operator record was created. |
| `UPDATED_AT` | timestamp | | Timestamp of the most recent update. |
## OPERATOR_CONTACT
How to reach an operator about a particular jurisdiction, and the registration that jurisdiction issued. A row is either a registration a regulator issued, or an operator's presence in a jurisdiction with no registration behind it; is\_registered says which, and external\_operator\_id is empty on the second kind. Because the unregistered case is a row rather than an absence, a lookup from an operator to a jurisdiction distinguishes 'no registration exists' from 'not present here'.
| Column | Description |
| --- | --- |
| `OPERATOR_CONTACT_ID` | Surrogate key for this registration or presence. |
| `OPERATOR_ID` | Foreign key to operator.operator\_id: the company this row belongs to. Part of the natural key. |
| `EXTERNAL_OPERATOR_ID` | The registration identifier the regulator issued. Absent where no registration exists; required where is\_registered is true. Part of the natural key. |
| `COUNTRY` | ISO 3166-1 alpha-2 country of the jurisdiction in jurisdiction\_reported. Not the mailing country, which is not modelled. Part of the natural key. |
| `JURISDICTION_REPORTED` | The state or province that issued the registration, or in which the operator is evidenced. Part of the natural key. |
| `IS_REGISTERED` | TRUE where a regulator issued this registration, FALSE where only activity in the jurisdiction attests to the operator's presence. The two row kinds are different claims, 'this regulator issued this registration' versus 'this operator is evidenced here and no registration exists', and this column is what tells them apart; external\_operator\_id is empty on the second kind. |
| `OPERATOR_REPORTED` | The operator's name as this registration recorded it, or as the activity source reported it. Filed spellings differ between a company's registrations, so this is the name on THIS row rather than the company's canonical name, which is operator.name. |
| `ADDRESS` | Mailing address, first line. |
| `ADDRESS2` | Mailing address, second line, suite, floor or unit. |
| `CITY` | Mailing address city. |
| `ADDRESS_STATE` | Mailing state or province. Where post is sent, which may differ from jurisdiction\_reported, the jurisdiction that licensed the operator. |
| `POSTAL_CODE` | Mailing postal code, a US ZIP or ZIP+4, or a Canadian postal code. The mailing country is not modelled, so both forms are accepted and neither is tied to country, which is the licensing jurisdiction's country rather than the address's. |
| `PHONE` | Contact telephone number as reported. |
| `EMERGENCY_PHONE` | Emergency contact telephone number as reported. |
| `SOURCE_ID` | Foreign key to source.source\_id for data lineage. |
| `CREATED_AT` | Timestamp the record was created. |
| `UPDATED_AT` | Timestamp of the most recent update. |
## BASIN
Reference list of basins and subbasins.
| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| `BASIN` | string | | Name of the basin, e.g. "Permian" |
| `SUBBASIN` | string | | Name of the subbasin, e.g. "Midland" |
| `SOURCE_ID` | | | Foreign key to source.source\_id for data lineage. |
## SOURCE
Data lineage dimension. One row per (system, collection, source\_file, source\_path) lineage tuple, where source\_file carries the upstream dataset name (e.g. 'US\_Horizontals', 'US\_Onshore', 'Canada'). Every base fact and dimension row carries a source\_id resolving to exactly one row here, and rows from different datasets of the same upstream table receive distinct source\_ids. ingested\_at carries the date and time of the bulk export that last loaded this lineage tuple, so it moves with each export.
| Column | Description |
| --- | --- |
| `SYSTEM` | Originating system name (e.g., 'regulator', 'internal\_ops'). |
| `INGESTED_AT` | When the data was ingested into the platform. |
| `COLLECTION` | Source collection or dataset name within the originating system. |
| `SOURCE_FILE` | Upstream dataset name carrying the bulk-export provenance for this row (e.g. 'US\_Horizontals', 'US\_Onshore', 'Canada'). Names the dataset rather than a single file, because this schema's lineage is tracked per dataset. |
| `SOURCE_PATH` | Path or URI to the source data file or object. |
| `SOURCE_ID` | Deterministic integer hash of the canonical lineage payload. Serves as both primary key and dedup key. |
| `CREATED_AT` | Timestamp the source record was created in this system. |
| `UPDATED_AT` | Timestamp of the most recent update to this source record. |
---
# Bulk download views
Source: https://developers.novilabs.com/data/tables/downloads/
> The two views that list the full and diff zip files your account can download.
Load a full zip once from `DOWNLOADS_FULL`, then apply the diff zips from `DOWNLOADS_DIFF` in `RUN_ID` order. Each row has a download URL that stops working 2 hours after you query it. See [Delivery options](https://developers.novilabs.com/data/delivery/#bulk-files) for the full procedure.
Views live in `NOVI_DATA_ACCESS.NOVI_WELLS`. Column descriptions are from the Wells data dictionary, release 26.4.3.
## DOWNLOADS_FULL
Full zip files you can download: the latest complete extract of each basin, one row per basin. Load a full zip once, then apply the diff zips of later runs from `DOWNLOADS_DIFF` to keep it current. Lists only the zips your account is entitled to; the USA zip needs every US basin.
| Column | Description |
| --- | --- |
| `RUN_ID` | Run that produced the zip, as `YYYYMMDD_HHMISS` in UTC. After you load the zip, your data matches this run. |
| `BASIN` | Basin the zip covers, or USA for the country zip that holds every US basin. |
| `ZIP_NAME` | Name of the zip, the same as BASIN. The downloaded file has a different name, which contains `RUN_ID`. |
| `RUN_AT_UTC` | `RUN_ID` as a UTC timestamp. |
| `ZIP_SIZE_MB` | Size of the zip file in megabytes. |
| `URL` | Download link for the zip. The link is created when you query the view and stops working 2 hours later; query the view again for a new link. A download that has started continues after the link expires. |
## DOWNLOADS_DIFF
Diff zip files you can download, one row per basin per run. Each diff holds the changes from `BASE_RUN_ID` to `RUN_ID`, so it applies only on top of the data from `BASE_RUN_ID`. Apply diffs in `RUN_ID` order; if a `BASE_RUN_ID` is not the run you hold, download the full zip from `DOWNLOADS_FULL` instead. Lists only the zips your account is entitled to; the USA zip needs every US basin.
| Column | Description |
| --- | --- |
| `BASE_RUN_ID` | Run the diff starts from, as `YYYYMMDD_HHMISS` in UTC. Apply the diff only to data from this run. |
| `RUN_ID` | Run that produced the zip, as `YYYYMMDD_HHMISS` in UTC. After you apply the diff, your data matches this run. |
| `BASIN` | Basin the zip covers, or USA for the country zip that holds every US basin. Joins to `DOWNLOADS_FULL`.BASIN. |
| `ZIP_NAME` | Name of the zip: the basin name followed by --DIFF. The downloaded file has a different name, which contains `RUN_ID`. |
| `DAYS_PRIOR` | Position of this run among the diff runs: 1 for the newest, 2 for the run before it. It counts runs, not calendar days; runs happen on weekdays only. The same value names the same run in every basin. |
| `BASE_RUN_AT_UTC` | `BASE_RUN_ID` as a UTC timestamp. |
| `RUN_AT_UTC` | `RUN_ID` as a UTC timestamp. |
| `ZIP_SIZE_MB` | Size of the zip file in megabytes. |
| `URL` | Download link for the zip. The link is created when you query the view and stops working 2 hours later; query the view again for a new link. A download that has started continues after the link expires. |
---
# Releases and versioning
Source: https://developers.novilabs.com/data/releases/
> How Novi UDM Data releases are numbered, what is in the current release, coverage, and how API versions are supported.
## Current release
| | |
| --- | --- |
| Release | 26.4.3 |
| Released | 2026-10-29 |
| Data model version | 1.6.80 |
| Schema | `NOVI_DATA_ACCESS.NOVI_WELLS` |
| Contents | 41 views: 10 presentation views, 29 base views, 2 bulk download views |
| Coverage | United States |
26.4.3 is the first release of Novi Wells in Snowflake. It covers well, wellbore, completion, production, forecast, spacing, subsurface, well-test, permit, activity, acreage, and operator data for the United States.
Every view and column in it is new.
## Release numbers
Releases use Novi's published release numbers, such as 26.2.4 and 26.4.3, the same numbers as in Novi's release notes.
Each release also records the version of the unified data model it was built from.
- The data dictionary's release history lists the columns each release introduced.
- Columns that are documented but not yet in a release are marked as staged. They are not queryable, and they may change before a release number is assigned.
- Novi Intelligence first became available in Snowflake with release 26.2.4.
## Changes inside a release line
Data refreshes on a regular schedule between releases. Each query returns the latest load.
Existing columns can change through bug fixes, improved logic, or deprecation. A deprecated column stays in its view, and its description says what to use instead.
## API versions
Novi supports up to three API versions at a time: Primary, Deprecated and Future. What each status means: [Versioning](https://developers.novilabs.com/platform/versioning/#novis-version-policy).
| Version | What it is | Status |
| --- | --- | --- |
| v4 | Novi UDM Data in Snowflake, documented in this section | New datasets and enhancements land here |
| v3 | The REST API at `/api/v3` and its bulk export | Supported. Novi has not announced when v3 becomes Deprecated |
> **Note:**
> v3 and v4 run side by side. Turning on v4 does not switch off v3. See [Moving from v3](https://developers.novilabs.com/data/migrate-from-v3/).
## Coverage
| Area | Status |
| --- | --- |
| United States, onshore | [Available] |
| Canada | [Planned] |
| US wellbores keyed on API14 | [Planned] |
Rows in views keyed by a well or wellbore are limited to the basins in your subscription.
Reference lists such as operators, basins, and weekly prices are complete.
Canadian data is planned for `NOVI_WELLS`, keyed on Canadian UWIs. Until then, use v3 for Canadian data.
---
# 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.
---
# Novi Forecasts API
Source: https://developers.novilabs.com/forecasts/
> Forecast oil, gas and water for planned horizontal wells, run development plans and export the results over REST.
Forecast oil, gas and water for horizontal wells before they are drilled, from a script, notebook or pipeline. Describe
a well by its surface hole, toe, landing zone and completion design; get cumulative volumes by day on production, with
EUR and Low and High bands on request.
- [Novi forecasting on novilabs.com](https://novilabs.com/energy-analytics/forecast-engine/): Machine-learning-driven per-well forecasts for drill schedules, PDP forecasts and asset evaluations.
## What you can do
- Look up existing wells: headers, production, spacing neighbors and the model's inputs.
- Forecast up to 50 drawn wells in one request, each with several completion designs.
- Run development plans of thousands of wells as background jobs.
- Read every well's cumulative curves to EUR, a page at a time.
- Export a plan as CSV and Parquet, or as ARIES, ComboCurve and Val Nav import files.
- Keep another tool in step with your saved plans and Legacy Forecasts[^legacy], pulling only what changed.
- Price scenarios with simulated half-cycle economics (IRR, payback, NPV).
## Start here
- [Quickstart](https://developers.novilabs.com/forecasts/quickstart/): Make a token, call the API and read a plan's curves.
- [Authentication](https://developers.novilabs.com/forecasts/authentication/): API tokens, access and sign-in for MCP clients.
- [Partner sync](https://developers.novilabs.com/forecasts/guides/partner-sync/): Pull only the plans that changed into another tool.
- [MCP server and Claude skill](https://developers.novilabs.com/forecasts/mcp/): Ask questions of your plans from Claude.
## Core objects
| Object | What it is | Read it with |
| --- | --- | --- |
| Model set | A basin dataset with its oil, gas and water models. Every dataset call takes `model_set`; without it the default set answers | `GET /model-sets` |
| Existing well | A well in the dataset, keyed by its wellbore key, with production and spacing | `GET /wells`, `GET /wells/{key}` |
| Drawn well | A well you plan: `shl` and `bhl` as `[lng, lat]`, a target `formation`, and optional landing, TIL date, pad and name | Request bodies of `POST /forecasts` and `POST /plans` |
| Design | Fluid in bbl and proppant in lb per lateral ft. Each well is forecast once per design | `designs` in a request; `GET /completions/defaults` |
| Scenario | A named alternative in one request. Its wells never space against another scenario's | `scenario` on each well |
| Plan | A background job that forecasts many drawn wells and stores the result | `POST /plans`, `GET /plans/{id}` |
| Legacy Forecast | One of your company's earlier predrill forecast runs, served read only as a plan | `GET /plans?origin=all` |
| Curve | One well's cumulative volume per stream, every 30 days to EUR | `GET /plans/{id}/curves` |
| Export | A zip of a done plan's tables | `POST /exports`, `GET /exports/{id}` |
| Forecast source | A booked forecast file (Val Nav, ComboCurve, Mosaic, ARIES or Novi) to compare with plans | `GET /forecast-sources`, `POST /comparisons` |
Send drawn wells and designs to `POST /forecasts` for an answer in the request, or to `POST /plans` for a background
job you then read, export or sync.
## Base URL
```text
https://.novilabs.io/forecasts/api/v1
```
Use the host you sign in to Novi at. Every path in these docs is relative to this base. `GET /openapi.json` returns
the OpenAPI 3.1 document your host runs.
## Conventions
- JSON in and out, snake_case names. Some reads also take a file upload (`multipart/form-data`).
- Oil and water in bbl, gas in mcf, lengths and depths in ft; field names carry the unit.
- Points are `[lng, lat]` in bodies and `"lng,lat"` in query strings, WGS 84 degrees.
- Volumes are cumulative by `ip_day`, days since first production. BOE is oil plus gas at 6 mcf per bbl.
- `GET /conventions` has the full rules, including the [P-level convention](https://developers.novilabs.com/forecasts/guides/forecasts-and-curves/#low-mid-and-high).
## Versioning
`/api/v1` only grows; additions are opt-in. Some releases tighten validation, so a loosely accepted request can become
an invalid-input error. `GET /health` returns your host's API `version`. See [Versioning](https://developers.novilabs.com/platform/versioning/#novi-forecasts-api).
## Status
| Surface | Status |
| --- | --- |
| REST API at `/forecasts/api/v1` with API tokens | [Available] |
| Claude skill | [Available] |
| Hosted MCP server and the Claude Desktop extension | [Preview] |
| Python and TypeScript SDKs | [Planned] |
> **SDKs:**
> Until the SDKs ship, call the API with any HTTP client. Examples use `curl` and Python `requests`; the quickstart also
> shows TypeScript `fetch`.
[^legacy]: Legacy Forecasts are dynamic imports from Forecast Engine v1.
---
# Quickstart
Source: https://developers.novilabs.com/forecasts/quickstart/
> Create an API token, make your first call and read a done plan's oil and gas curves.
This page takes you from no token to a done plan's cumulative curves in three calls. You need a Novi login with access
to Forecasts.
1. **Create a token.** In the Forecasts app, open **Settings**, then **API tokens**. Name the token, pick how long it
lasts (7, 30 or 90 days, 1 year, or a custom 1 to 365 days; 90 is the default) and create it. Copy it now: Novi
shows it only once.
If **API tokens** is missing from Settings, ask your company's Novi administrator for the Access MCP permission.
2. **Set your base URL and token.** Use the host you sign in to Novi at.
```sh
export NOVI_API_BASE="https://.novilabs.io/forecasts/api/v1"
# Paste the token at the prompt so it stays out of your shell history.
read -rs NOVI_API_TOKEN && export NOVI_API_TOKEN
```
3. **Check who you are.** `GET /me` answers with the account the token acts as.
```sh
curl -sS --fail-with-body \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
"$NOVI_API_BASE/me"
```
```json
{ "tenant": "example", "user": { "id": "7", "email": "user@example.com" }, "role": "customer" }
```
4. **List your done plans.** `origin=all` includes your Legacy Forecasts[^legacy] beside the plans made in Forecasts.
Each row's `origin.engine` says which: `v2` or `fe`.
```sh
curl -sS --fail-with-body \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
"$NOVI_API_BASE/plans?origin=all&status=done&limit=5"
```
5. **Read a plan's curves.** `GET /plans/{id}/curves` returns each well's cumulative volume every 30 days, to its EUR on a plan made with `eur: true`:
`cum[m-1]` is the cumulative at day 30·m, so `cum[11]` is the volume to day 360.
```sh
PLAN_ID=""
curl -sS --fail-with-body --compressed \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
"$NOVI_API_BASE/plans/$PLAN_ID/curves?limit=10"
```
## The same calls in code
**Python**
```python
import os
import requests
BASE = os.environ["NOVI_API_BASE"]
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NOVI_API_TOKEN']}"
def get(path, **params):
r = session.get(f"{BASE}{path}", params=params, timeout=60)
r.raise_for_status()
return r.json()
print(get("/me"))
plans = get("/plans", origin="all", status="done", limit=5)["plans"]
for plan in plans:
print(plan["id"], plan["name"], plan["origin"]["engine"])
if not plans:
raise SystemExit("No done plans yet: run one in the Forecasts app or with POST /plans.")
plan_id = plans[0]["id"]
params = {"limit": 100}
while True:
page = get(f"/plans/{plan_id}/curves", **params)
for well in page["wells"]:
oil = well.get("curves", {}).get("oil", {}).get("P50", {})
cum = oil.get("cum", [])
if len(cum) > 11 and cum[11] is not None:
print(well["label"], "oil to day 360:", cum[11], "bbl")
if page["next_cursor"] is None:
break
params["cursor"] = page["next_cursor"]
```
**TypeScript**
```ts
const BASE = process.env.NOVI_API_BASE ?? '';
const headers = { Authorization: `Bearer ${process.env.NOVI_API_TOKEN ?? ''}` };
async function get(path: string, params: Record = {}): Promise {
const url = new URL(BASE + path);
for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
const res = await fetch(url, { headers });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
return (await res.json()) as T;
}
type PlanList = {
plans: { id: string; name: string | null; origin?: { engine: string } }[];
next_cursor: string | null;
};
type Curve = { cum?: (number | null)[]; error?: string };
type CurvesPage = {
wells: { label: string; curves?: { oil?: { P50?: Curve } } }[];
next_cursor: string | null;
};
async function main() {
console.log(await get('/me'));
const { plans } = await get('/plans', { origin: 'all', status: 'done', limit: '5' });
for (const plan of plans) console.log(plan.id, plan.name, plan.origin?.engine);
if (plans.length === 0) throw new Error('No done plans yet: run one in the Forecasts app or with POST /plans.');
const params: Record = { limit: '100' };
for (;;) {
const page = await get(`/plans/${plans[0].id}/curves`, params);
for (const well of page.wells) {
const cum = well.curves?.oil?.P50?.cum ?? [];
const day360 = cum[11];
if (day360 != null) console.log(well.label, 'oil to day 360:', day360, 'bbl');
}
if (page.next_cursor === null) break;
params.cursor = page.next_cursor;
}
}
main().catch(err => {
console.error(err);
process.exit(1);
});
```
The TypeScript runs on Node 18 or later, which has `fetch` built in.
> **Ask for less:**
> Lists page with `limit` and an opaque `cursor`: pass `next_cursor` back until it is `null`. Send
> `Accept-Encoding: gzip` (curl's `--compressed`) and responses over 1 KB come back compressed.
## Next
- Learn what each curve point means, and how Novi labels Low and High, in
[Forecasts and curves](https://developers.novilabs.com/forecasts/guides/forecasts-and-curves/).
- Run your own plan in [Plans and wells](https://developers.novilabs.com/forecasts/guides/plans-and-wells/).
- Keep another tool in step with [Partner sync](https://developers.novilabs.com/forecasts/guides/partner-sync/).
[^legacy]: Legacy Forecasts are dynamic imports from Forecast Engine v1.
---
# Forecasts API authentication
Source: https://developers.novilabs.com/forecasts/authentication/
> Create and revoke API tokens, what a token can see, and how MCP clients sign in.
Send a Novi API token as a bearer token on every request. The token acts as you: it sees your company's plans and
data and nothing else.
```http
GET /forecasts/api/v1/me HTTP/1.1
Host: .novilabs.io
Authorization: Bearer
```
## API tokens
- **Create** a token in the Forecasts app under **Settings**, then **API tokens**.
- **Who can create one:** a user with the Access MCP permission, which your company's Novi administrator grants
through a role. Without it, **API tokens** doesn't appear in Settings.
- **Revoke** a token from the same page. Anything using it stops working within two minutes.
Lifetimes and safe storage: [Compare credentials](https://developers.novilabs.com/start/authentication/#compare-credentials). Format and one-time display: [Novi API token](https://developers.novilabs.com/start/authentication/#novi-api-token).
## Access
| You need | What happens without it |
| --- | --- |
| A token that is current, not revoked, for an active user | The request is not authorized. Create a new token |
| The **Access Forecasts** permission | The API denies access. Ask your Novi administrator |
- Every company's plans, forecast jobs, exports, shares and saved documents are its own. Another company's record
looks the same as one that doesn't exist, and nothing you send can select another company.
- What each error looks like: [Errors and limits](https://developers.novilabs.com/forecasts/guides/errors-and-limits/#status-codes).
> **Call from servers, scripts and notebooks:**
> Browser code on web pages outside Novi can't call the API. Call it from a server, a script, a notebook or a pipeline,
> and keep the token there.
## MCP clients and Novi sign-in [Preview]
MCP clients such as claude.ai and Claude Desktop can sign you in with your Novi login instead of a pasted token, at
`https://.novilabs.io/forecasts/api/mcp`.
- To approve a connection, you need the Access MCP permission and access to Forecasts.
- The sign-in works only on that MCP server, at your company. It does not work on the REST API.
- No token, however it was made, can create or manage other tokens.
Steps: [Novi sign-in for assistants](https://developers.novilabs.com/start/authentication/#novi-sign-in-for-assistants). Setup: [MCP server and Claude skill](https://developers.novilabs.com/forecasts/mcp/).
## Service tokens [Planned]
Every token today acts as one person, with that person's full access. Read-only tokens for partners and pipelines, not
tied to a person, are planned.
---
# Plans and wells
Source: https://developers.novilabs.com/forecasts/guides/plans-and-wells/
> Find existing wells, describe drawn wells, and run, read, save and delete development plans.
A plan forecasts many drawn
wells as one background job and stores the result.
## Model sets and the dataset
A model set is one basin's dataset with its oil, gas and water models.
- `GET /model-sets` lists your company's sets, the default first. Send `model_set=` on any dataset call; without it,
the default set answers.
- A plan or export stays in its set, so later calls on it need no `model_set`.
- `GET /dataset` gives the set's `as_of` date, `ip_days`, whether EUR and bands are available, and `limits` such as
`limits.forecast_wells` and `limits.plan_wells`.
- `GET /formations` lists the formations. `include=target` marks the target zones, where you can plan a well.
## Existing wells
| Call | Returns |
| --- | --- |
| `GET /wells` | Wells for a map. `format=geojson` with `bbox`, `formation`, `q` (name or key), `operator` or `near` and a small `limit` returns a page of points |
| `GET /wells/{key}` | One well's header, by wellbore key |
| `GET /wells/{key}/production` | Its production history |
| `GET /wells/{key}/spacing` | Its spacing neighbors |
| `GET /wells/{key}/features` | The spacing features the models read for it |
| `GET /wells/{key}/predictions` | The model's stored prediction beside its actuals |
| `POST /wells/search` | Wells inside a unit's outline, with an optional buffer |
| `GET /wells/facets` | Counts by operator, formation or county, and a numeric field's spread |
| `POST /wells/typecurve` | A type curve of existing wells' production: counts, mean and quantiles by day |
Ask for the least data that answers the question.
## Drawn wells
A drawn well is a well you plan, in the same shape for `POST /forecasts`, `POST /plans` and exports.
| Field | Required | Meaning |
| --- | --- | --- |
| `shl` | yes | Surface hole location, `[lng, lat]` |
| `bhl` | yes | Bottom hole (toe), `[lng, lat]`. The lateral runs from `heel`, else `shl`, to `bhl`: 100 to 50,000 ft |
| `heel` | no | Where the lateral starts, when not at `shl` |
| `formation` | to forecast | Target formation, from `GET /formations` |
| `tvd_ft`, `landing_below_top_ft` or `landing_fraction` | no | Landing. Blank estimates TVD from the structure grid and nearby wells |
| `til_date` | no | First production date, `YYYY-MM-DD`. Orders parents and children in spacing |
| `fluid_bbl_per_ft`, `proppant_lb_per_ft` | no | This well's completion, over the design's |
| `pad`, `scenario` | no | Groups wells by pad. A scenario's wells never space against another scenario's |
| `name` | no | 1 to 60 characters |
These calls lay wells out for you, ready for a plan:
| Call | Does |
| --- | --- |
| `POST /layouts/fill` | Fills a polygon at a spacing and azimuth |
| `POST /areas` | Reads unit outlines from a zipped shapefile, GeoJSON, KML or KMZ |
| `POST /areas/fill` | Fills a whole file of areas |
| `POST /inventories/read` | Reads a well inventory file |
## Run a plan
`POST /plans` returns the plan and its id at once. Read it with `GET /plans/{id}?wait=25`: each call returns as soon as
the status changes from `running` to `done` or `error`, or after 25 seconds.
**curl**
```sh
curl -sS --fail-with-body -X POST \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Hawk unit infill",
"wells": [
{"name": "Hawk 14-1H", "shl": [-101.93, 31.93], "bhl": [-101.93, 31.957], "formation": "WOLFCAMP A", "til_date": "2027-03-01"},
{"name": "Hawk 14-2H", "shl": [-101.928, 31.93], "bhl": [-101.928, 31.957], "formation": "WOLFCAMP A", "til_date": "2027-04-01"}
],
"designs": [
{"name": "Recent median"},
{"name": "Upsized", "fluid_bbl_per_ft": 60, "proppant_lb_per_ft": 3000}
],
"eur": true
}' \
"$NOVI_API_BASE/plans"
# The answer has the plan's id. Each GET with wait=25 returns when the status changes, or after 25 s.
PLAN_ID=""
curl -sS --fail-with-body \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
"$NOVI_API_BASE/plans/$PLAN_ID?wait=25"
```
**Python**
```python
import os
import uuid
import requests
BASE = os.environ["NOVI_API_BASE"]
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NOVI_API_TOKEN']}"
body = {
"name": "Hawk unit infill",
"wells": [
{"name": "Hawk 14-1H", "shl": [-101.93, 31.93], "bhl": [-101.93, 31.957],
"formation": "WOLFCAMP A", "til_date": "2027-03-01"},
{"name": "Hawk 14-2H", "shl": [-101.928, 31.93], "bhl": [-101.928, 31.957],
"formation": "WOLFCAMP A", "til_date": "2027-04-01"},
],
"designs": [
{"name": "Recent median"},
{"name": "Upsized", "fluid_bbl_per_ft": 60, "proppant_lb_per_ft": 3000},
],
"eur": True,
}
r = session.post(f"{BASE}/plans", json=body,
headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=60)
r.raise_for_status()
plan = r.json()
while plan["status"] == "running":
r = session.get(f"{BASE}/plans/{plan['id']}", params={"wait": 25}, timeout=60)
r.raise_for_status()
plan = r.json()
if plan["status"] == "error":
raise SystemExit(plan["error"])
for total in plan["totals"]:
design = plan["designs"][total["design"]]["name"]
oil_eur = total.get("eur", {}).get("oil", {}).get("value")
print(design, "wells:", total["wells_with_forecast"], "oil EUR (bbl):", oil_eur)
session.patch(f"{BASE}/plans/{plan['id']}", json={"saved": True}, timeout=60).raise_for_status()
```
The example is in the Midland basin. Take formations and coordinates from your own model set.
The request also takes:
- `designs`: each well is forecast once per design. An empty design takes the recent completions median.
- `eur: true` extends oil and gas forecasts to an EUR. `bands: true` adds Low (P10) and High (P90) curves, and
`band_eur: true` an EUR for each, where `GET /dataset` says your set has them.
- `til_date` on the request dates every well that no narrower setting dates. In a dated plan, each planned well's
forecast production is passed to the later wells it is a parent of, where the set's models read neighbors'
production. `depletion_chain: false` turns that off.
- `scenarios`, `pads` and `formations` set values per scenario, pad and formation.
- `dry_run: true` checks and counts the plan without starting it.
- `from_plan: ` reruns a done plan's request on the set's current models.
A plan takes up to `limits.plan_wells` forecasts (wells × designs), up to 50,000. Your queued and running plans share a
cap, `limits.plan_unfinished_forecasts`: past it, wait for a plan to finish before you start another. See
[Errors and limits](https://developers.novilabs.com/forecasts/guides/errors-and-limits/#limits).
## Read a done plan
| Call | Returns |
| --- | --- |
| `GET /plans/{id}` | Status, designs, and totals per design (and per scenario) |
| `GET /plans/{id}?include=wells` | Each well's inputs, TVD, forecasts per design and spacing, paged with `limit` and `cursor`. Filter with `formation`, `pad`, `scenario`, `q` or `wells`; rank with `sort` (`eur_boe`, `cum_oil` and more) |
| `GET /plans/{id}/stats` | Histogram and quantiles of a metric across the wells |
| `GET /plans/{id}/rollup` | Oil, gas and water by pad and by landing zone |
| `GET /plans/{id}/checks` | Wells with inputs outside the models' training data, by input |
| `GET /plans/{id}/curves` | Every well's cumulative curves to EUR. See [Forecasts and curves](https://developers.novilabs.com/forecasts/guides/forecasts-and-curves/) |
| `GET /plans/{id}/wells/{index}/explanations/{design}` | A well's drivers per day and the training wells it leans on |
| `GET /plans/{id}/typecurve/{design}` | A type curve from the plan's own forecasts |
## Keep, share or delete
- **Unsaved plans are deleted 90 days after they are made.** `PATCH /plans/{id}` with `{"saved": true}` keeps one
until someone deletes it; `{"saved": false}` starts a new 90 days. `name` renames it.
- `GET /plans` lists your company's plans in a model set, newest first, 20 a page by default, up to 100. Filter with
`q`, `status`, `saved` and `created_by=me`.
- `POST /plans/{id}/shares` makes a link to a done plan; `DELETE /plans/{id}/shares/{share_id}` revokes it.
- `DELETE /plans/{id}` stops a running plan or deletes a done one and its shares, leaving no record. `unless=saved`
deletes it only if it isn't saved or shared.
> **Legacy Forecasts:**
> `GET /plans?origin=all` adds your company's Legacy Forecasts[^legacy] as read-only plans, whose `origin.engine` is
> `fe`. They support `GET /plans/{id}` (with `include=wells`), `GET /plans/{id}/wells/{index}`, `GET /plans/{id}/curves`
> and exports. Other plan reads and any change, such as a rename or a delete, are not supported.
[^legacy]: Legacy Forecasts are dynamic imports from Forecast Engine v1.
---
# Forecasts and curves
Source: https://developers.novilabs.com/forecasts/guides/forecasts-and-curves/
> Forecast drawn wells in one request, read what a forecast and its curve points mean, and how Novi labels Low and High.
A forecast is
cumulative oil, gas and water by day on production, for one well and one completion design.
## Low, Mid and High
> **Novi's P-level convention:**
> Novi labels P-levels by percentile: **P10 is the Low curve and P90 the High curve**, the reverse of SPE PRMS, where
> P90 is the low, proved case. Field names keep Novi's labels: `p10`, `P10`, `p90`, `P90`. See [P-levels](https://developers.novilabs.com/concepts/p-levels/).
- Mid (P50) is the point forecast. Without bands, a forecast is Mid alone.
- Low (P10) and High (P90) are split conformal prediction bands around one well's forecast. Ask with `bands: true`;
`GET /dataset` says which streams have them.
- A plan's Low total is the sum of its wells' Low curves, not the plan's own Low. The same goes for High.
- The spread across a plan's wells is well quantiles (q10, q50, q90), not P-levels.
## Forecast drawn wells
`POST /forecasts` runs up to 50 drawn wells (`limits.forecast_wells`) together, spaced against each other and existing
wells, once per design, up to 25 designs.
**curl**
```sh
curl -sS --fail-with-body -X POST \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"wells": [
{"name": "Hawk 14-2H", "shl": [-101.93, 31.93], "bhl": [-101.93, 31.957], "formation": "WOLFCAMP A"}
],
"designs": [
{"name": "Recent median"},
{"name": "Upsized", "fluid_bbl_per_ft": 60, "proppant_lb_per_ft": 3000}
],
"summary": true,
"eur": true,
"ip_days": [360, 720, 1080]
}' \
"$NOVI_API_BASE/forecasts"
```
**Python**
```python
import os
import requests
BASE = os.environ["NOVI_API_BASE"]
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NOVI_API_TOKEN']}"
body = {
"wells": [{"name": "Hawk 14-2H", "shl": [-101.93, 31.93], "bhl": [-101.93, 31.957],
"formation": "WOLFCAMP A"}],
"designs": [{"name": "Recent median"},
{"name": "Upsized", "fluid_bbl_per_ft": 60, "proppant_lb_per_ft": 3000}],
"summary": True,
"eur": True,
"ip_days": [360, 720, 1080],
}
r = session.post(f"{BASE}/forecasts", json=body, timeout=120)
r.raise_for_status()
result = r.json()
for well in result["wells"]:
for forecast in well.get("forecasts", []):
oil = forecast.get("oil") or {"error": forecast.get("error", "no oil stream")}
if "error" in oil:
print(well["label"], "design", forecast["design"], "oil failed:", oil["error"])
continue
print(well["label"], "design", forecast["design"],
dict(zip(oil["ip_days"], oil["values"])), "EUR:", oil.get("eur", {}).get("value"))
```
Each well returns one `forecasts` entry per design. Each stream (`oil`, `gas`, `water`) holds:
| Field | Meaning |
| --- | --- |
| `unit` | `bbl` for oil and water, `mcf` for gas. |
| `ip_days`, `values` | Cumulative volume at each day on production. |
| `eur` | With `eur: true`: `value`, the day it is reached (`days`) and the decline fit (`arps`). |
| `bands` | With `bands: true`: `p10` (Low) and `p90` (High), each with its `values`, and an `eur` with `band_eur: true`. |
| `error` | In place of the above, why this stream has no forecast. |
| Option | Effect |
| --- | --- |
| `summary: true` | Each well as a compact summary |
| `ip_days` | Only the days you list |
| `boe: true` | BOE (oil plus gas at 6 mcf per bbl) beside the streams |
| `totals: true` | Totals per design |
| `explain: true` | Each forecast's drivers and the training wells it leans on. Up to 10 wells × designs |
| `async: true` | Runs as a [job](https://developers.novilabs.com/forecasts/guides/jobs-and-retries/): read it with `GET /forecasts/{id}?wait=25` |
Every forecast carries `checks`. Show the flag beside any number from a flagged well.
| Check | Meaning |
| --- | --- |
| `out_of_range` | Inputs outside what the models saw in training |
| `missing` | Blank inputs the training rarely had blank |
| `flagged` | Any check applies |
## What a curve means
- A curve is cumulative volume at each `ip_day`, from 0 on day 0, straight from point to point. A period's volume is
the cumulative at its end minus the cumulative at its start.
- EUR is opt-in: a decline-curve fit that extends the forecast to the EUR day (settings in `GET /dataset`
`eur.defaults`). It is not a model output.
- With an EUR, a curve follows the extension to the EUR day, then stays flat. Without one, it ends at its last point.
## Read a plan's curves
`GET /plans/{id}/curves` pages through a done plan's wells: cumulative volume per stream every 30 days to EUR, the same
numbers the monthly export writes.
| Parameter | Default | Meaning |
| --- | --- | --- |
| `design` | `0` | The design, by its index in the plan's `designs`. |
| `streams` | every stream the plan serves | Comma-separated, as `oil,gas`. |
| `p_levels` | `P50` | Comma-separated from `P50`, `P10`, `P90`. Low and High need a plan made with bands. |
| `limit` | `100` | Wells per page, 1 to 200. |
| `cursor` | | `next_cursor` from the previous page. |
| `start_date` | | `til`, or a date as `YYYY-MM-DD`, to add volumes by calendar month. |
```json
{
"plan_id": "e287ce51-430c-4871-87c2-e9c4191fb412",
"design": 0,
"step_days": 30,
"streams": ["oil", "gas"],
"p_levels": ["P50"],
"wells": [
{
"index": 0,
"key": "DRAWN-0",
"well_uid": "54a872630fdca9a2660d598fe5467269",
"label": "Plan well 1",
"name": "Hawk 14-2H",
"til_date": "2027-03-01",
"shl": [-101.93, 31.93],
"bhl": [-101.93, 31.957],
"curves": {
"oil": { "unit": "bbl", "P50": { "cum": [18412.35, 33021.8, 45210.06], "model_months": 36, "extension": "arps", "note": null } },
"gas": { "error": "The forecast worker failed: gas model timed out" }
}
}
],
"next_cursor": null
}
```
The `cum` array is cut short here. To read a well:
- `cum[m-1]` is the cumulative at day 30·m, to 0.01, or `null`. IP30 is `cum[0]`, IP540 `cum[17]`; divide by 30·m for
the average daily rate.
- The first `model_months` points are the model's, the rest the decline extension. `extension` is `arps`, `flat` or
`table`, or `null` with a `note` saying why the curve stops.
- An unplaced well, a failed stream or a missing band comes back as `{"error": "..."}` in place of its curves.
- `well_uid` (32 characters) is the same on every read of the plan. `key` is unique within one plan only.
- Only a done plan has curves. Send a page's `ETag` back as `If-None-Match` to learn that nothing changed.
### Calendar months
With `start_date`, each curve adds `calendar`: volume per calendar month from `first_month` (`YYYY-MM`).
- `start_date=til` starts each well at its TIL date, else the plan's day; `start_date_source` says which (`til`,
`plan_day` or `request`). `start_date=YYYY-MM-DD` starts every well that day.
- The first month is partial unless the start is a 1st. The months add up to the last cumulative, within rounding.
## Curves you already have
`POST /declines` fits the same EUR decline to cumulative curves you send.
## Explanations
`GET /plans/{id}/wells/{index}/explanations/{design}` explains one plan well: each input's contribution per day
(SHAP), the training wells it leans on, and, on request, analog wells with their production. An analog spread is a
peer range, not Low and High.
---
# Exports
Source: https://developers.novilabs.com/forecasts/guides/exports/
> Write a done plan's tables to a zip as CSV and Parquet, or as ARIES, ComboCurve and Val Nav import files.
Exports run as queued jobs. To read curves
straight into code, see [Forecasts and curves](https://developers.novilabs.com/forecasts/guides/forecasts-and-curves/).
## Presets
`GET /export-formats?plan=` lists every table, column, option and preset, and which the plan can take, with the
reason when it can't.
| Preset | What the zip holds |
| --- | --- |
| `engineer` (default) | Monthly volumes to EUR, EUR per well, wells and designs |
| `monthly` | Monthly volumes to EUR, EUR per well and wells |
| `plan_tables` | Wells, designs, neighbors, model inputs, subsurface values and cumulative volumes by day |
| `arps` | Arps segments per well, design and stream, with EUR per well |
| `eur` | EUR per well and design |
| `drivers` | Each model input's contribution to each forecast (SHAP values) |
| `economics` | NPV, capex, IRR and payback per well, pad and plan |
| `aries` | One ARIES import file: 12 monthly volumes per well and design, then declines. No Parquet |
| `combocurve` | Well header and forecast parameters CSVs, plus `eur_check.csv` |
| `valnav` | A decline CSV by well, reserves category and product, in imperial units, plus `eur_check.csv` |
Send `preset` or `tables` (with each table's options), not both. `wells`, `designs` and `streams` narrow every table.
## Run an export
**curl**
```sh
curl -sS --fail-with-body -X POST \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"source\": {\"plan\": \"$PLAN_ID\"}, \"preset\": \"combocurve\", \"identity\": {\"well_id\": \"uid\"}}" \
"$NOVI_API_BASE/exports"
# The answer has the export's id.
EXPORT_ID=""
# Wait for it: each call returns when the status changes, or after 25 s.
curl -sS --fail-with-body \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
"$NOVI_API_BASE/exports/$EXPORT_ID?wait=25"
# Download, resuming a partial file with -C -. -L follows a redirect to the signed copy.
curl -sS --fail-with-body -L -C - -o export.zip \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
"$NOVI_API_BASE/exports/$EXPORT_ID/file"
```
**Python**
```python
import os
from urllib.parse import urljoin
import requests
BASE = os.environ["NOVI_API_BASE"]
PLAN_ID = os.environ["PLAN_ID"]
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NOVI_API_TOKEN']}"
r = session.post(f"{BASE}/exports", json={
"source": {"plan": PLAN_ID},
"preset": "combocurve",
"identity": {"well_id": "uid"},
}, timeout=60)
r.raise_for_status()
export = r.json()
while export["status"] in ("queued", "running"):
r = session.get(f"{BASE}/exports/{export['id']}", params={"wait": 25}, timeout=60)
r.raise_for_status()
export = r.json()
if export["status"] != "done":
raise SystemExit(f"Export {export['status']}: {export['error']}")
# file.url is a path on your host; requests drops the token if it redirects to another host.
url = urljoin(BASE, export["file"]["url"])
with session.get(url, stream=True, timeout=600) as download:
download.raise_for_status()
with open(f"{export['id']}.zip", "wb") as f:
for chunk in download.iter_content(chunk_size=1 << 20):
f.write(chunk)
print("saved", f"{export['id']}.zip", export["file"]["bytes"], "bytes")
```
- `POST /exports` returns the export and its `Location` at once. The same request for the same plan returns the
existing export, with `reused: true`.
- `status`: `queued`, `running`, then `done`, `error` or `cancelled`; `expired` once the file is removed. `progress`
gives the step, share done, rows and bytes.
- When done, `file` has `name`, `bytes`, `sha256`, `url` (a path on your host) and `expires_at`.
- Downloads resume with `Range` and `If-Range`. One may redirect to a signed copy that works for 15 minutes: follow
it without your token, as curl 7.58 and later and Python `requests` do.
- Files are kept for `limits.ttl_hours` ([Limits](#limits)); then run the export again.
- `DELETE /exports/{id}` cancels a queued or running export, or removes a finished one.
## What's in the zip
- One CSV per table. By default, fixed-schema tables also come as Parquet under `parquet/`, with Snowflake and
Databricks load scripts. `GET /export-formats` says which; `parquet: false` leaves it out.
- `manifest.json` (the request and settings) and `README.txt` (every table and column).
- On a plan made with bands, `p_levels: ["P50", "P10", "P90"]` adds Low (P10) and High (P90) rows after each Mid
(P50) row. Otherwise the export is Mid only.
## Files for other tools
**ComboCurve**
**ARIES**
- **ComboCurve:** `eur_check.csv` gives each curve's EUR as ComboCurve will sum it, beside Novi's. ComboCurve names
P-series by exceedance, so Low (P10) is written as series `P90` and High (P90) as `P10`.
- **Val Nav:** `reserves_categories` sets the reserves category each P-level writes.
- **ARIES:** don't send `parquet: true`.
- `identity` sets each well's Well ID and start date. `identity.well_id: "uid"` writes the `well_uid` that
`GET /plans/{id}/curves` gives, so plans with the same well names don't collide.
- These files carry no scenario: a plan with two or more needs `scenario` to pick one.
## Other sources
- `source.wells` forecasts and exports wells you send in one job, up to `limits.max_source_wells` forecasts (500 by
default).
- `source.comparison` exports a comparison of two plans, or of a plan and a booked forecast source.
- A Legacy Forecast[^legacy] exports like a plan, without neighbors, model inputs, subsurface, SHAP, economics, the
presets that need them, or ARIES. `GET /export-formats?plan=` gives each reason.
## Limits
| Limit | Default | Past it |
| --- | --- | --- |
| Exports queued or running, per model set | 20 | Start more once one finishes |
| Exports queued or running, per plan | 3 | Start more once one finishes |
| How long a file is kept (`limits.ttl_hours`) | 24 hours, less when export storage (`limits.max_bytes`) fills; the oldest go first | Run the export again |
| Request body | 10 MB | Send less |
`GET /export-formats` `limits` reports your host's values. Error codes: [Errors and limits](https://developers.novilabs.com/forecasts/guides/errors-and-limits/#limits).
## Callbacks [Planned]
Notices to your own https receiver when an export or plan finishes are not available yet: `GET /export-formats`
`callbacks.enabled` is `false` and `callback_url` is not accepted. Use `wait=25`.
[^legacy]: Legacy Forecasts are dynamic imports from Forecast Engine v1.
---
# Partner sync
Source: https://developers.novilabs.com/forecasts/guides/partner-sync/
> Keep another tool in step with your saved plans and Legacy Forecasts, pulling only what changed.
Keep another tool in step with your saved plans and Legacy Forecasts[^legacy]. Each scheduled run lists the plans
changed since the last run and reads their curves. You turn the cumulative points into whatever the tool loads.
## What stays and what changes
| Item | What can change |
| --- | --- |
| A done plan made with `POST /plans` | Only its name and whether it is saved. Its forecasts don't change |
| Curve points past `model_months` | A later release can move them. [Catch moved points](#catch-moved-points) with `ETag` |
| An unsaved plan | Deleted 90 days after it is made. Saved plans stay until someone deletes them |
| A Legacy Forecast | Its numbers, keeping its id. It can't be changed or deleted through the API |
| A deleted plan | Drops out of the lists and can no longer be read. No record is left |
## One sync run
1. **Note the run's start time** for the next run's `updated_from`.
2. **List what changed in each model set** from `GET /model-sets`:
```text
GET /plans?origin=all&kept=true&status=done&updated_from=&include=storage&limit=100&model_set=
```
- `kept=true`: saved plans and every Legacy Forecast. `status=done` leaves out running plans.
- `updated_from`: every plan made, finished, renamed, saved, unsaved or shared since then. The 15 minutes catch
changes your last run's list missed.
- Every set's list holds every Legacy Forecast, so send `origin=v2` for each set after the first.
- Page by `next_cursor` until it is `null`, with the same parameters.
- `include=storage` adds `storage.updated_at`, the last stored change that `updated_from` reads.
3. **Decide what to read.** A renamed plan you hold has the same forecasts. Re-read a Legacy Forecast
(`origin.engine` `fe`) when its `origin.indexed_at` is newer than your copy.
4. **Read the curves.** For each plan and design, page through `GET /plans/{id}/curves` (up to 200 wells a page). Key
wells by `well_uid`. `start_date=til` adds volumes by calendar month.
5. **Save the start time.**
```python
import os
from datetime import datetime, timedelta, timezone
import requests
BASE = os.environ["NOVI_API_BASE"]
STATE = "last_sync_start.txt"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NOVI_API_TOKEN']}"
def get(path, **params):
r = session.get(f"{BASE}{path}", params=params, timeout=120)
r.raise_for_status()
return r.json()
def pages(path, params):
while True:
page = get(path, **params)
yield page
if page["next_cursor"] is None:
return
params = {**params, "cursor": page["next_cursor"]}
def changed_plans(since):
for i, model_set in enumerate(get("/model-sets")["model_sets"]):
params = {
"origin": "all" if i == 0 else "v2",
"kept": "true",
"status": "done",
"include": "storage",
"limit": 100,
"model_set": model_set["id"],
}
if since is not None:
params["updated_from"] = (since - timedelta(minutes=15)).strftime("%Y-%m-%dT%H:%M:%SZ")
for page in pages("/plans", params):
if page.get("warnings"):
print("warnings:", page["warnings"])
yield from page["plans"]
def store(plan, design, well):
print(plan["id"], design, well["well_uid"], sorted(well.get("curves", {})))
try:
with open(STATE) as f:
last_sync_start = datetime.fromisoformat(f.read().strip())
except FileNotFoundError:
last_sync_start = None
sync_start = datetime.now(timezone.utc)
seen = set()
for plan in changed_plans(last_sync_start):
if plan["id"] in seen:
continue
seen.add(plan["id"])
for design in range(len(plan["designs"])):
params = {"design": design, "limit": 200, "start_date": "til"}
for page in pages(f"/plans/{plan['id']}/curves", params):
for well in page["wells"]:
store(plan, design, well)
with open(STATE, "w") as f:
f.write(sync_start.isoformat())
```
Replace `store` with your load step. The first run lists every kept plan.
## Catch moved points
Keep each curve page's `ETag`. To check a plan, read its pages again with the `ETag` as `If-None-Match`: a Not
Modified answer, with no body, means nothing moved.
## Removals
Lists leave out unsaved, deleted and expired plans without saying so. Now and then, send the lists without
`updated_from` and `status`, and drop the ids you hold that they don't list.
> **Pending Legacy Forecasts:**
> A `fe_runs_pending` warning counts Legacy Forecasts not ready to list yet; a later run lists them. A
> `fe_runs_unavailable` warning means Legacy Forecasts could not be listed at all. After a list with either warning,
> drop no Legacy Forecast: the list may leave out one that still exists.
## Files instead of curves
When the tool loads files, [export](https://developers.novilabs.com/forecasts/guides/exports/) with the `combocurve` or `valnav` preset and
`identity.well_id: "uid"`, so Well IDs match the `well_uid` you key on.
## Coming later
| Primitive | Status |
| --- | --- |
| Deletion records, so a sync learns what was removed without a full list | [Planned] |
| Arps segments as JSON, outside an export zip | [Planned] |
| Read-only service tokens for partners, not tied to one person | [Planned] |
| Callbacks to your receiver when a plan finishes | [Planned] |
[^legacy]: Legacy Forecasts are dynamic imports from Forecast Engine v1.
---
# Jobs, waiting and retries
Source: https://developers.novilabs.com/forecasts/guides/jobs-and-retries/
> How long-running work runs as jobs, how to wait without polling, and how to retry safely with idempotency keys and ETags.
A `POST` returns the job and
its `Location` at once; a waiting `GET` reads it.
## The four jobs
| Job | Start, then read | Statuses | Running at once | Kept |
| --- | --- | --- | --- | --- |
| Plan | `POST /plans`, `GET /plans/{id}` | `running` (queued too), `done`, `error` | Your unfinished forecasts, up to `limits.plan_unfinished_forecasts` | Unsaved 90 days; saved until deleted |
| Export | `POST /exports`, `GET /exports/{id}` | `queued`, `running`, `done`, `error`, `cancelled`, `expired` | 20 per model set and 3 per plan by default | Its file for `limits.ttl_hours` |
| Async forecast | `POST /forecasts` with `async: true`, `GET /forecasts/{id}` | `running`, `done`, `error` | 50 per company | An hour after it finishes |
| Plan economics | `POST /plans/{id}/economics`, `GET /plans/{id}/economics/{job_id}` | `running`, `done`, `error` | 4 per company | An hour after it finishes |
Past a cap, retry after one finishes, or after `Retry-After` when given ([codes](https://developers.novilabs.com/forecasts/guides/errors-and-limits/#limits)).
Every job carries `seconds`, its run time. Plans report `progress` as a share done; exports the step, share, rows and
bytes.
## Wait instead of polling
Add `wait` (1 to 25 seconds) to the job's `GET`. It answers when the status changes or the time passes; a finished
job answers at once.
```sh
curl -sS --fail-with-body \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
"$NOVI_API_BASE/plans/$PLAN_ID?wait=25"
```
Set your client's timeout above the wait, for example 60 seconds.
## Links and Location
`Location`, `links.self` and an export's `file.url` are paths, such as `/forecasts/api/v1/exports//file`. Resolve
them against `https://.novilabs.io`.
## Retry safely with Idempotency-Key
These calls take an `Idempotency-Key` header: `POST /plans`, `POST /exports`, `POST /plans/{id}/economics`,
`POST /forecast-sources`, `POST /area-sets`, `POST /saved/{collection}`, and `POST /forecasts` with `async: true`
(otherwise the key is ignored).
- Send your own key, 1 to 128 letters, digits and `.`, `_`, `:` or `-`, such as a UUID, on every retry of that
request.
- The same key with the same body within 24 hours (for an async forecast or plan economics job, while the job is
kept) returns what the first request made, with `Idempotent-Replayed: true`, and starts nothing.
- The same key with a different body is a conflict error with `details.field` `Idempotency-Key`.
- Only a request that succeeds records its key, so retry a server error or a lost response with the same key.
- Keys are per operation.
> **Tip:**
> An identical `POST /exports` for the same plan also returns the existing export, with `reused: true`, key or not.
## ETags and compression
Send a read's `ETag` back as `If-None-Match`: when nothing changed, the answer is Not Modified, with no body.
| Read | Behavior |
| --- | --- |
| Dataset reads, economics decks, `GET /changelog` | `ETag` |
| A done or failed plan, `GET /plans/{id}` | `ETag` |
| A curve page, `GET /plans/{id}/curves` | `ETag` on each page |
| An export file | Strong `ETag`, `Accept-Ranges: bytes`; `Range` resumes and `If-Range` guards the resume |
Responses over 1 KB are gzipped when you send `Accept-Encoding: gzip`.
## Paging
Lists page with `limit` and an opaque `cursor`. Pass `next_cursor` back until it is `null`, with the same filters
and sort each time. On `GET /plans`, plans created or deleted between pages are neither skipped nor repeated.
## Request ids
Every response carries `X-Request-Id`. Send your own to match your logs, and quote it when you ask Novi about a call.
---
# Errors and limits
Source: https://developers.novilabs.com/forecasts/guides/errors-and-limits/
> The error envelope, what each status means, the size and concurrency limits, and how to back off.
Every error from the API has one shape, and the status tells you
what to do next.
## The error envelope
```json
{
"error": {
"code": "invalid_argument",
"message": "wells[0].tvd isn't a known field; did you mean tvd_ft?",
"details": { "field": "wells[0].tvd" }
},
"request_id": "3c9d1e7a-2b4f-4a6c-9d8e-7f1a2b3c4d5e"
}
```
- `code` is one of `invalid_argument`, `not_found`, `conflict`, `unavailable` and `internal`.
- `details.field` names the input at fault. Some errors add more, such as `details.allowed` with the values a
parameter takes.
- `request_id` is the call's `X-Request-Id`. Quote it when you ask Novi about a call.
## Status codes
| Status | `code` | Means | Do |
| --- | --- | --- | --- |
| `400` | `invalid_argument` | An input is invalid. | Fix the field `details.field` names. |
| `401` | | No valid token. | See below. |
| `403` | `invalid_argument` | The user lacks access to Forecasts. | Ask your Novi administrator. |
| `404` | `not_found` | No such well, plan, export or path, or it belongs to another company. | Check the id. |
| `405` | `invalid_argument` | The path has no operation for that method. | Use a method from the `Allow` header. |
| `409` | `conflict` | The request conflicts with the state of what it names: a plan still running or failed, a read or change a Legacy Forecast doesn't support, a reused `Idempotency-Key` with another body, a full export queue. | Read `message`; wait or change the request. |
| `410` | `not_found` | An export's file expired. | Run the export again. |
| `413` | `invalid_argument` | The request body is too large. | Send less, or split it. |
| `416` | `invalid_argument` | A download range starts past the end of the file. | Restart the download. |
| `429` | `conflict` | Your queued and running plans would pass your cap. | Wait for `Retry-After`, or for a plan to finish. |
| `500` | `internal` | An unexpected error. | Retry once; then quote `request_id`. |
| `502` | `internal` | A model step failed. | Retry with the same `Idempotency-Key`. |
| `503` | `unavailable` | A model step or the grids aren't ready. | Retry shortly with the same `Idempotency-Key`. |
A missing, expired or revoked token gets `401` with the body `{"code": 401, "message": "Unauthorized"}` and no
`request_id`. A sign-in made for an MCP client gets `403` on the REST API. See
[Authentication](https://developers.novilabs.com/forecasts/authentication/).
Other statuses you will see: `202` when a job starts, `304` when an `If-None-Match` read finds nothing changed, and
`307` when an export download redirects to its signed copy.
## Limits
`GET /dataset` `limits` and `GET /export-formats` `limits` report most limits. Read them rather than hard-coding these
defaults.
| Limit | Value | Past it |
| --- | --- | --- |
| Drawn wells per `POST /forecasts` | 50 (`limits.forecast_wells`) | `400` |
| Designs per `POST /forecasts` | 25 | `400` |
| Wells × designs with `explain: true` | 10 | `400` |
| Forecasts (wells × designs) per plan | `limits.plan_wells`, up to 50,000 | `400` |
| One caller's unfinished plan forecasts | `limits.plan_unfinished_forecasts` | `429` with `Retry-After` |
| Async forecasts running, per company | 50 | `409` with `Retry-After: 1` |
| Plan economics jobs running, per company | 4 | `409` with `Retry-After: 1` |
| Exports queued or running | 20 per model set, 3 per plan | `409` |
| Request body, `POST /plans` | 64 MB | `413` |
| Request body, `POST /exports` | 10 MB | `413` |
| A file of areas (shapefile, GeoJSON, KML) | 10 MB, 5,000 areas | `413` or `400` |
| Plans per `GET /plans` page | 1 to 100, default 20 | `400` |
| Wells per curves page | 1 to 200, default 100 | `400` |
| `wait` on a job | 1 to 25 seconds | `400` |
## Backing off
- Honor `Retry-After` on `429` and `409`.
- Retry `502`, `503` and `504`, and a lost response, with the same `Idempotency-Key` so a retry never starts a second
job. See [Jobs, waiting and retries](https://developers.novilabs.com/forecasts/guides/jobs-and-retries/).
- Prefer `wait=25` on a job's `GET` to a polling loop.
## Rate limit headers [Planned]
The API sends no request-rate headers today. Standard `RateLimit` and `RateLimit-Policy` headers, so a client can pace
itself, are planned.
---
# MCP server and Claude skill
Source: https://developers.novilabs.com/forecasts/mcp/
> Ask questions of Novi Forecasts from Claude, through the MCP server's 25 tools or the Claude skill.
Ask Claude about your forecasts in plain words and get the numbers and a chart, with where they came from. Use the MCP
server's 25 tools, or the Claude skill, which teaches Claude when to use each tool and how to chart the result.
| Surface | Status |
| --- | --- |
| Claude skill, for Claude Code | [Available] |
| Hosted MCP server at `/forecasts/api/mcp` | [Preview] |
| Claude Desktop extension | [Preview] |
> **Preview:**
> The hosted MCP server is in preview and not yet available on company hosts. The Forecasts app's API page lists the
> skill and extension downloads.
## How it works
- Tools act as you. They read, or start a plan or an export; `save_forecast_source` saves a forecast file once you agree. No tool deletes.
- Each answer carries its provenance: dataset, as-of date, models, request id and API version.
- The transport is Streamable HTTP.
## Tools
| Tool | What it answers |
| --- | --- |
| `describe_dataset` | The dataset: basin, formations, as-of date, models and what they can do. Call it first |
| `find_wells` | Existing wells by name, operator, formation, area or unit, filtered by ranges and sorted by any field |
| `well_facets` | Counts of wells by operator, formation, county and other values, with each numeric field's range and histogram |
| `get_well` | One well's header, production, spacing and the model's stored prediction against its actuals |
| `type_curve` | A type curve from existing wells' actual production: counts, mean and quantiles by day |
| `completion_defaults` | Default completion designs (fluid and proppant per ft) by formation |
| `forecast_wells` | Forecasts for drawn wells, for one or more completion designs, with EUR |
| `explain_forecast` | The top drivers behind a forecast, per stream, against a typical well and its analogs' production |
| `model_card` | What each model saw in training and how accurate it is on wells it never saw |
| `fill_layout` | Parallel wells across a polygon at a given spacing and azimuth |
| `read_areas` | Unit or lease boundaries from GeoJSON, a zipped shapefile or KML, each with a polygon to fill |
| `fill_areas` | Wells of one lateral length over a file's areas, areas that share an edge laid as one piece of land |
| `summarize_unit` | What a unit holds: acres, existing wells by formation and operator, grid ranges and completions |
| `read_inventory` | Planned wells from a CSV or GeoJSON lines, ready to forecast, with why any rows were left out |
| `gun_barrel` | A cross-section of drawn and existing wells: spacing across, TVD and each formation's top |
| `start_plan` | Starts a plan that forecasts many wells; returns its id |
| `get_plan` | A plan's status, totals per design and per pad and zone, ranked wells, failed wells and nearby PDP wells |
| `list_plans` | Your recent plans, or your team's, newest first |
| `export_plan` | Exports a done plan as files and returns a download link |
| `price_scenarios` | Simulated half-cycle economics for well scenarios on a price deck |
| `compare_forecasts` | Two plans, scenarios or designs, or a saved forecast source against a plan |
| `read_forecast_sources` | Reads a booked forecast file without storing it, or lists and opens saved forecast sources |
| `save_forecast_source` | Saves a read forecast file as a forecast source, after asking you |
| `list_model_sets` | The model sets the server serves |
| `get_conventions` | Units, the BOE ratio, the P-level convention and how to present results |
Two resources come with them: `novi://conventions` (the conventions as Markdown) and `novi://dataset` (the dataset
card `describe_dataset` returns).
## Connect [Preview]
The endpoint is `https://.novilabs.io/forecasts/api/mcp`. Signing in with your Novi login needs the Access
MCP permission, which your company's Novi administrator grants.
**claude.ai and Claude Desktop**
1. In Claude, open **Settings**, then **Connectors**, and add a custom connector with the endpoint URL. On a Team or
Enterprise plan, an owner adds it first.
2. Connect, and sign in with your Novi login.
**Claude Code**
Add the server, then run `/mcp` to sign in with your Novi login.
```sh
claude mcp add --transport http --scope user novi-forecasts https://.novilabs.io/forecasts/api/mcp
```
Or send an API token instead:
```sh
claude mcp add --transport http --scope user novi-forecasts https://.novilabs.io/forecasts/api/mcp \
--header "Authorization: Bearer "
```
**Claude Desktop extension**
1. Download `novi-forecasts.mcpb` from the Forecasts app's API page and open it in Claude Desktop to install it.
2. Set its **Forecasts API base URL** to `https://.novilabs.io/forecasts` and its **Novi API token** to a token
from Settings, API tokens.
The extension runs the same tools on your computer with your token, and says when a newer version is out.
## The Claude skill [Available]
The skill (`novi-forecasts`) is for Claude Code. It holds when to use each tool, the conventions, the field
dictionary, every export column and chart templates: type curve, cumulative, gun barrel, stick map, ranked table, plan
histogram and design delta.
1. Download `novi-forecasts-skill.zip` from the Forecasts app's API page.
2. Unzip it so `SKILL.md` sits at `~/.claude/skills/novi-forecasts/SKILL.md`.
3. Start a new Claude Code session.
Without the MCP server, the skill answers from an attached export zip (the default export's monthly volumes, EUR, wells
and designs), or calls the REST API with your token: reads and documented `POST` calls, never `DELETE`.
## Your first question
Ask: **What data is behind Novi Forecasts?** Claude names the dataset and its as-of date, and whether forecasts carry
Low and High bands. Then try a type curve, a spacing question or a plan.
---
# API reference
Source: https://developers.novilabs.com/forecasts/reference/
> Where to find every Forecasts API operation, its parameters, schemas and code samples.
Every operation of the Forecasts API under `/forecasts/api/v1` is in the [Novi Forecasts API reference](https://developers.novilabs.com/reference/forecasts/), grouped by area. Each page has its parameters, request and response schemas, samples in cURL, Python and JavaScript, and a Try it button.
The OpenAPI 3.1 document is [forecasts.json](https://developers.novilabs.com/openapi/forecasts.json). Your host also serves it at `GET /openapi.json`. The API page in the Forecasts app has its own Try it panel.
---
# Novi EVA
Source: https://developers.novilabs.com/eva/
> Read Novi EVA well data, production and forecasts from code or an AI assistant, and load your own columns and shapefiles into EVA.
Work with Novi EVA, Novi's well analytics and forecasting application, from scripts or an AI assistant. EVA brings well-level data, forecasts and research together with your organization's own data, across US and Canadian basins.
- [Novi EVA on novilabs.com](https://novilabs.com/energy-analytics/novi-eva/): The EVA application: its data, research and workflows.
## What you can build
| You want | Use | Status |
| --- | --- | --- |
| Field values for up to 50,000 wells per call, in the order you sent them, for dataframes, load jobs and BI tools | [REST API](https://developers.novilabs.com/eva/api/) | [Preview] |
| Production history and forecast for up to 1,000 wells per call, for reserves and economics tools | [REST API](https://developers.novilabs.com/eva/api/) | [Preview] |
| Your own columns per well, and shapefile uploads, in EVA | [REST API](https://developers.novilabs.com/eva/api/) | [Preview] |
| Plain-language answers: benchmark basins or operators, build a type curve with High (P10), Mid (P50) and Low (P90) cases, map a cohort | [MCP server](https://developers.novilabs.com/eva/mcp/), 13 read-only tools | [Preview] |
| Area screens: count and rank wells within a radius of a reference set, by operator or vintage | [MCP server](https://developers.novilabs.com/eva/mcp/) | [Preview] |
EVA charts use the exceedance convention, where P10 is the High case. See [P-levels](https://developers.novilabs.com/concepts/p-levels/).
The MCP server is in preview and not yet available on company hosts.
## Which one to use
**Pipelines and scripts**
Use the REST API. Send a well list; get values back in your order, ready for a dataframe or a load job.
**Questions in plain language**
Use the MCP server. An assistant finds the right columns, applies your filters, and returns rankings, charts and maps with the basis and units stated.
## Access
- **REST API:** create a Developer API Token on the Organization Settings page in EVA and send it in the `x-api-key` header. The key acts for your EVA organization.
- **MCP server:** sign in from a supported assistant. You need the Access EVA and Access MCP permissions on your company's Novi account. API keys and personal tokens don't work on the MCP server.
## Next steps
- [REST API](https://developers.novilabs.com/eva/api/): Base URL, authentication, endpoints and examples.
- [MCP server](https://developers.novilabs.com/eva/mcp/): Tools, filters, pagination, conventions and limits.
- [Connect Claude](https://developers.novilabs.com/eva/connect-claude/): Add EVA to Claude, Claude Code or Codex.
---
# EVA MCP server
Source: https://developers.novilabs.com/eva/mcp/
> Ask an AI assistant to benchmark, chart and map wells in Novi EVA, with 13 read-only tools.
Ask an assistant such as Claude to rank basins or operators, build type curves, chart production and map a cohort in Novi EVA. Every tool is read-only and sees only the data your account can see in EVA. See [Good prompts](#good-prompts).
The server is in preview and not yet available on company hosts. Until it is, use the [REST API](https://developers.novilabs.com/eva/api/).
## Server URL
```text
https://.novilabs.io/eva/api/mcp
```
Use the host you use for Novi apps in the browser. The transport is Streamable HTTP.
## Sign-in
Sign in with your Novi login from Claude (claude.ai and Claude Desktop), Claude Code or OpenAI Codex; API keys and personal tokens don't work. You need **Access EVA**, **Access MCP** and membership in the company whose host you use. Steps: [Connect Claude](https://developers.novilabs.com/eva/connect-claude/).
The sign-in works only for EVA on your company host. When it expires, your assistant asks you to sign in again. If an administrator removes either permission, access stops within about two minutes.
## Tools
### Data
| Tool | Purpose | Key inputs |
|---|---|---|
| `get_data_guide` | How to read the data, before a custom query | `topic`: `querying`, `units`, `percentiles`, `production`, `forecasts`, `benchmarking` |
| `search_columns` | Exact column references by name, path, category or note. Every query word must match | `query` (empty browses), `category`, `operation`, `limit` (default 20, max 50), `cursor` |
| `describe_columns` | Units, definitions and the operations each column supports | `references` (up to 25) |
| `resolve_values` | Exact stored text values with well counts: `Reeves` finds `Reeves, TX`. Never picks an ambiguous match for you | `column`, `query`, `filter`, `limit` (default 10, max 25) |
| `group_by` | Well counts per value of a text or integer column, with optional `sum`, `avg`, `min`, `max` or `median` measures. Omit `column` for cohort totals | `filter`, `column`, `measures` (up to 4), `normalize_by`, `sort`, `limit` (default 100, max 500), `min_wells_counted`, `benchmark`, `options` |
| `fetch_data` | Individual well rows, sorted by well identifier | `filter`, `columns` (1 to 50), `entity_keys` (up to 500), `normalize_by`, `limit` (default 100, max 500), `cursor`, `options` |
| `create_radius_filter` | A polygon filter of a given radius around the center of a reference set of wells | `reference_filter`, `radius_miles` (above 0, up to 100) |
### Charts
| Tool | Purpose | Key inputs |
|---|---|---|
| `get_chart` | Production charts: one chart, up to 8 charts over one filter (`charts[]`), or up to 8 named cohorts with one chart spec (`cohorts[]`) | `filter`, `chart_type` or `preset`, `product`, `group_by`, `statistics`, `chart_setting`, `volume_years`, `include_png`, `include_series`, `limit` |
| `get_chart_guide` | What each chart type plots, P-levels, averaging, survivor bias, units and settings | none |
| Setting | Values |
|---|---|
| `chart_type` | `MonthlyRateTime`, `MonthlyRateCum`, `CumTime`, `RateDate`, `TotalRateDate` |
| `product` | `oil`, `gas`, `water`, `boe`, `fluid`, `gor`, `cgr`, `wgr` |
| `preset` | `type_curve` (P10 High, P50 Mid and P90 Low on, survivor bias on, cutoff 50) or `stacked_area` (`TotalRateDate`) |
| `chart_setting` | `survivorBias`, `cutoff`, `shutInMonths`, `showForecast`, `forecastMode`, `normalizeBy`, `useWeightedRatioAverage`, `movingAverageDays` |
| `user_forecast_settings` | Forecast sources you are licensed for |
| `volume_years` | `{from, to}`, inclusive, up to 20 years, on `RateDate` or `TotalRateDate`. Each group then carries `volume_by_year` in `volume_unit` |
### Maps
| Tool | Purpose | Key inputs |
|---|---|---|
| `get_map` | A well map from a full filter, colored by group | `filter`, `group_by`, `palette`, `reverse_color`, `format` (`tiles`, `png`, `geojson`, `auto`), `geometry` (`points`, `trajectories`), `delivery` |
| `get_map_tile` | One map tile, for clients without the map viewer | `map_id`, `z`, `x`, `y`, `representation` |
| `get_map_legend` | Group titles, counts and colors, a page at a time | `map_id`, `cursor`, `limit` (up to 200) |
| `get_map_guide` | Map filtering, radius, palette, geometry and expiry rules | none |
In clients that support MCP Apps, such as Claude, `get_chart` and `get_map` draw inline. Other clients get a PNG (`include_png`, default true, for charts; `format: png` for maps) and the data.
## Filters
Every data, chart and map tool takes the complete filter inline; saved EVA filters are not used.
```json
{
"filter": {
"query": {
"operator": "and",
"predicates": [
{ "id": "basin", "type": "Property", "property": "Header.Basin", "operator": "in", "value": ["Permian"] },
{ "id": "vintage", "type": "Property", "property": "Dates.Vintage_Year", "operator": "between", "value": [2022, 2025] }
],
"children_nodes": []
}
},
"columns": ["Header.ResourcePlay", "Header.Operator_Short", "Well_Design.HzLength_m"],
"options": { "units": "hybrid", "app_default_filters": true },
"limit": 100
}
```
- `query.operator` is `and` or `or`; nest groups in `children_nodes`. Up to 100 predicates, each with a unique `id`.
- Text: `in` and `nin` with 1 to 100 strings. Numbers and dates (`YYYY-MM-DD`): `between` (lower bound included, upper excluded), `lt`, `gte`.
- `Polygon`: one closed WGS84 ring of 4 to 1,024 points, 2,048 across the query.
- `options.app_default_filters: true` adds producing (`HasProduction=Y`) horizontal wells (`HORIZONTAL`, `U_TURN_HORIZONTAL`) and says so. Maps never add these.
Common references you can use without a search: `Header.FieldCounty` (values like `Lea, NM`), `Header.StateProvince`, `Header.Country` (`US`), `Header.Basin` (`Permian`), `Header.ResourcePlay` (`Delaware`, `Midland`), `Header.Operator_Short`, `Header.Direction`, `Dates.Vintage_Year`, `Well_Design.HzLength_m`, `Production_Summary.Cumulative12MonthsOil`.
## Pagination
`fetch_data` returns `next_cursor` when more rows match. Send the same inputs again with `cursor` set to that value.
- A cursor works only with the inputs it came from, for 10 minutes. Otherwise you get `INVALID_CURSOR`: start again without a cursor.
- Pages are not a snapshot. Data can change between pages.
`search_columns` and `get_map_legend` also take a `cursor` from their previous page.
## Results
Data tools return `schema_version`, `data`, `returned_count`, `matched_count`, `applied_options`, `warnings`, `truncated`, `next_cursor`, `coverage` and `freshness`. Check `truncated` and `warnings` before you rely on a result.
## Conventions
| Topic | Convention |
|---|---|
| Units | `options.units`: `hybrid` (default), `si` or `imperial`. Hybrid: lateral length in metres, oil and BOE in Mbbl, gas in MMcf. Results label their units |
| Cohort years | A bare year means production vintage (`Dates.Vintage_Year`), not completion year |
| Well identifiers | `Header.EntityName`: the API10 for US wells, the UWI or local identifier elsewhere |
| Production windows | `Cumulative12Months*` and `Cumulative24Months*` use the first 12 or 24 producing months; shorter histories return null |
| Oil | Stored cumulative oil is reported oil only. Chart oil includes condensate |
| P-levels in charts | `p10` is High, `p50` Mid (the median), `p90` Low: the exceedance convention, the reverse of Novi Forecasts |
## Good prompts
Ask for one result, name the cohort, and say which basis you want.
- "Rank US basins by median first-12-month oil per 1,000 ft for wells online 2022 through 2024."
- "Show oil production for horizontal Permian wells online 2020 through 2026, by operator and by first-production year."
- "How much gas did Delaware wells produce in 2025, by operator? Give exact yearly volumes, not estimates."
- "Build a type curve with High (P10), Mid (P50) and Low (P90) for horizontal Midland wells online in 2023."
- "Map horizontal wells in Reeves County, TX, colored by first-production year."
- "Count wells within 10 miles of the center of horizontal wells in Loving County, TX, by operator."
The first prompt uses `group_by` with `benchmark`: public production, hybrid units, the first 12 producing months of reported oil, horizontal producing wells with laterals of at least 1,000 m, per 1,000 ft, sorted by median.
**Benchmark call**
```json
{
"filter": {
"query": {
"operator": "and",
"predicates": [
{ "id": "country", "type": "Property", "property": "Header.Country", "operator": "in", "value": ["US"] },
{ "id": "vintage", "type": "Property", "property": "Dates.Vintage_Year", "operator": "between", "value": [2022, 2025] }
],
"children_nodes": []
}
},
"column": "Header.Basin",
"benchmark": {}
}
```
**Two charts, one filter**
```json
{
"filter": {
"query": {
"operator": "and",
"predicates": [
{ "id": "basin", "type": "Property", "property": "Header.Basin", "operator": "in", "value": ["Permian"] },
{ "id": "vintage", "type": "Property", "property": "Dates.Vintage_Year", "operator": "between", "value": [2020, 2027] },
{ "id": "direction", "type": "Property", "property": "Header.Direction", "operator": "in", "value": ["HORIZONTAL", "U_TURN_HORIZONTAL"] }
],
"children_nodes": []
}
},
"charts": [
{ "chart_type": "TotalRateDate", "product": "oil", "group_by": { "column": "Header.Operator_Short", "bin": { "MaxBins": 20, "MaxBinsSortOrder": "WellCount" } }, "include_png": false, "include_series": false, "limit": { "max_series": 50 } },
{ "chart_type": "TotalRateDate", "product": "oil", "group_by": { "column": "Dates.Vintage_Year" }, "include_png": false, "include_series": false, "limit": { "max_series": 50 } }
]
}
```
## Limits
| Limit | Value |
|---|---|
| Request body | 1 MiB |
| `fetch_data` rows per page | 500 (default 100) |
| `group_by` groups | 500 (default 100) |
| Charts or cohorts per `get_chart` call | 8 |
| Series per chart (`limit.max_series`) | 50 |
| `volume_years` span | 20 years |
| Radius filter | 100 miles |
| Mappable wells in GeoJSON | 100,000 |
| Data tool deadline | 30 seconds |
| `fetch_data` cursor lifetime | 10 minutes |
| `map_id` lifetime | 5 minutes, or your token's expiry if sooner |
A few of your data tool calls run at once; more wait briefly. Too many calls, or too large a result, returns `LIMIT_EXCEEDED`.
## Errors
A tool error is JSON: `{"code", "message", "retryable", "field"}`.
| Code | Meaning | What to do |
|---|---|---|
| `LIMIT_EXCEEDED` | Too many calls in flight, or a result too large | Retry later if `retryable` is true; otherwise narrow the request |
| `DEADLINE_EXCEEDED` | The call ran past its deadline | Retry, or narrow the filter |
| `DEPENDENCY_ERROR` | Novi could not read the data just then | Retry later. A failed read is never reported as zero |
| `INVALID_CURSOR` | The cursor expired or the inputs changed | Start again without a cursor |
| `VALIDATION_ERROR` | An input is invalid; `field` names it | Fix the input |
| `UNSUPPORTED_OPERATION` | The column does not support that filter, grouping or measure | Check the operations `describe_columns` lists |
| `ACCESS_DENIED` | A column, value or part of the cohort is outside your subscription | Do not retry with guessed columns; ask your Novi admin about access |
> **Note:**
> Not on the MCP server today: shapefile filters, your organization's columns, saved filters, raw monthly series and bulk exports. Use the [REST API](https://developers.novilabs.com/eva/api/) for organization columns and production arrays.
---
# Connect Claude to EVA
Source: https://developers.novilabs.com/eva/connect-claude/
> Add Novi EVA to Claude, Claude Code or Codex with one URL, sign in through Novi, and ask about wells in plain language.
Add Novi EVA to Claude, Claude Code or Codex, then ask for well rankings, production charts, type curves and maps in plain language. The assistant works in EVA as you.
> **Preview:**
> The EVA MCP server is in preview and not yet available on company hosts. These steps work once it is.
## Before you start
- **URL:** `https://.novilabs.io/eva/api/mcp`, with the company name you use for Novi apps in the browser.
- **Permissions:** **Access EVA** and **Access MCP**, granted by your company's Novi administrator.
- **Client:** Claude (claude.ai and Claude Desktop), Claude Code or OpenAI Codex. API keys and personal tokens don't work.
## Add the connector
**Claude**
1. In Claude, open **Customize > Connectors**, select **+ Add**, then **Add custom connector**.
2. Enter a name, for example `Novi EVA`, and the URL `https://.novilabs.io/eva/api/mcp`. Select **Continue**, review the authentication Claude detects, select **Continue** again, then **Add**.
3. Select **Connect** and sign in to Novi in the browser.
4. Approve Novi's consent page, which shows the client, the application (EVA), your company, your email and how long the sign-in lasts.
5. In a chat, select **+**, then **Connectors**, and turn on the EVA connector.
**Claude Team or Enterprise**
1. An owner opens **Organization settings > Connectors**, selects **Add**, hovers over **Custom** and selects **Web**.
2. The owner enters a name, for example `Novi EVA`, and the URL `https://.novilabs.io/eva/api/mcp`, selects **Continue** twice, then **Add**.
3. Each member opens **Customize > Connectors**, selects **Connect** on the connector, signs in and approves the Novi consent page.
4. In a chat, select **+**, then **Connectors**, and turn on the EVA connector.
The connector also shows up in Claude's mobile apps. If it does not, open Claude on the web or desktop first.
**Claude Code**
1. Add the server:
```bash
claude mcp add --transport http novi-eva https://.novilabs.io/eva/api/mcp
```
2. Run `/mcp`, select `novi-eva` and authenticate. Sign in to Novi in the browser, or open the URL Claude Code prints.
3. Approve the Novi consent page.
**Codex**
Add `https://.novilabs.io/eva/api/mcp` as a remote MCP server in Codex and complete the Novi sign-in. Novi shows the same consent page.
## After you connect
Try: "Rank US basins by median first-12-month oil per 1,000 ft for wells online 2022 through 2024." More prompts and the tool list: [EVA MCP server](https://developers.novilabs.com/eva/mcp/).
When a sign-in expires, the assistant asks you to sign in again. If an administrator removes Access EVA or Access MCP, access stops within about two minutes.
## Troubleshooting
| What you see | Meaning | Fix |
|---|---|---|
| "Novi doesn't recognise the app that sent you here, so it can't connect to your account." | The client is not supported | Use Claude, Claude Code or Codex |
| `403` on every call | Missing Access EVA or Access MCP, a host for another company, or an API key instead of a sign-in | Ask your administrator for both permissions; use your own company host; remove any API key header and connect again |
| `401` after signing in | The sign-in expired or was revoked | Reconnect and sign in again |
| `503` | Novi could not check your sign-in just then | Retry in a moment. You do not need to sign in again |
| Sign-in fails, or calls return `404`, on a `novilabs.io` host | The EVA MCP server is not yet available on company hosts | Use the [REST API](https://developers.novilabs.com/eva/api/) until it is |
| `LIMIT_EXCEEDED` in a tool result | Too many calls at once, or a result too large | Wait and retry, or narrow the question |
> **Note:**
> A custom agent cannot sign in yet. For scripts, use the [REST API](https://developers.novilabs.com/eva/api/).
---
# EVA REST API
Source: https://developers.novilabs.com/eva/api/
> Pull Novi EVA field values, production and forecasts for a list of wells, and write your organization's columns and shapefiles into EVA.
Pull field values, production and forecasts for a list of wells into scripts, dataframes and load jobs, in the order you ask for them. You can also write your organization's own columns and upload shapefiles.
## Base URL
```text
https://api.novilabs.com
```
> **Preview:**
> The EVA REST API is in preview. `api.novilabs.com` is not live yet; access details come with its release.
All endpoints are under `/v1`. OpenAPI 3.1 document: [eva.json](https://developers.novilabs.com/openapi/eva.json).
## Authentication
Create a Developer API Token on EVA's **Organization Settings** page and send it in the `x-api-key` header. It acts for your EVA organization: keep it out of source code and load it from the environment.
```bash
export NOVI_EVA_API_KEY=""
```
It is not a Novi API token, and the [EVA MCP server](https://developers.novilabs.com/eva/mcp/) does not take it.
## Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | `/v1/data/fields` | List the fields you can request, optionally for one `group` |
| POST | `/v1/data` | Field values for up to 50,000 wells |
| POST | `/v1/production` | Production history and forecast for up to 1,000 wells |
| GET | `/v1/columns/org-defined-columns` | List your organization's columns |
| POST | `/v1/columns/org-defined-columns` | Create an organization column |
| GET | `/v1/columns/org-defined-columns/{id}` | Get one column with its values |
| PUT | `/v1/columns/org-defined-columns/{id}` | Update a column and its values |
| POST | `/v1/shapefile/upload` | Upload a shapefile to your organization |
## Quickstart
### 1. Find field keys
Groups: Header, Dates, Geology, Well Design, Frac Data, Performance and Forecast. Leave out `group` for every field.
```bash
curl -s "https://api.novilabs.com/v1/data/fields?group=Header" \
-H "x-api-key: $NOVI_EVA_API_KEY"
```
Each entry has `field`, the key you request (such as `Header.ResourcePlay`), and `fieldName`, its display name.
### 2. Get values for your wells
**curl**
```bash
curl -s https://api.novilabs.com/v1/data \
-H "x-api-key: $NOVI_EVA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"wellList": ["100091802103W500", "100111403204W500"],
"fields": ["Header.ResourcePlay", "Header.Status", "Dates.Vintage_Year"]
}'
```
**Python**
```python
import os
import requests
response = requests.post(
"https://api.novilabs.com/v1/data",
headers={"x-api-key": os.environ["NOVI_EVA_API_KEY"]},
json={
"wellList": ["100091802103W500", "100111403204W500"],
"fields": ["Header.ResourcePlay", "Header.Status", "Dates.Vintage_Year"],
},
timeout=120,
)
response.raise_for_status()
for well in response.json():
print(well["uwid"], well["data"])
```
One entry per well comes back, in request order, with your identifiers as sent and `data` in the order of `fields`:
```json
[
{ "uwid": "100091802103W500", "data": ["", "", ""] },
{ "uwid": "100111403204W500", "data": ["", "", ""] }
]
```
- `"n/a"`: not available for that well. A well not found returns `"data": ["n/a"]`.
- `"Subscription Required"`: your subscription does not include that value.
Optional `productionSource` picks the production source; `publicDataTrumpingOrder` sets which public source wins per category (`Header`, `Survey`, `Frac`, `Production`) when sources disagree. Values: [OpenAPI document](https://developers.novilabs.com/openapi/eva.json).
### 3. Get production
```bash
curl -s https://api.novilabs.com/v1/production \
-H "x-api-key: $NOVI_EVA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"wellList": ["100091807811W600"],
"productionSource": "GDC",
"forecastSource": "GDC",
"includeForecast": false
}'
```
Each well returns `id`, `history` and `forecast` arrays. `forecast` is empty with `includeForecast: false`; both are empty for a well not found.
## Organization columns
Store your organization's own values per well in EVA, keyed by well identifier.
```bash
curl -s https://api.novilabs.com/v1/columns/org-defined-columns \
-H "x-api-key: $NOVI_EVA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Test Field",
"subgroup": "Tests",
"dataType": "Number",
"defaultUnit": "bbl",
"data": { "100091802103W500": 100.1, "100111403204W500": 150.3 }
}'
```
`dataType` is `Number`, `Text` or `Date`. Other fields: `published`, `canBin`, `canNormalize`, `normalizeByDefault`, `propertyName`, `withinSubgroupOrder`. Update with `PUT /v1/columns/org-defined-columns/{id}`; `GET` on that path returns it with its values.
## Shapefile upload
Send the shapefile's files as `multipart/form-data` parts, each with its file name:
```bash
curl -s https://api.novilabs.com/v1/shapefile/upload \
-H "x-api-key: $NOVI_EVA_API_KEY" \
-F "file=@acreage.shp" \
-F "file=@acreage.shx" \
-F "file=@acreage.dbf" \
-F "file=@acreage.prj"
```
## Limits
| Limit | Value |
|---|---|
| Wells per `POST /v1/data` | 50,000 |
| Wells per `POST /v1/production` | 1,000 |
| Request rate | 10 per second on average, bursts up to 30 |
| Requests in flight | 5 |
## Troubleshooting
Errors return JSON with one field, `error`.
| What you see | Meaning | Fix |
|---|---|---|
| `401` `{"error": "Missing x-api-key header"}` | No key was sent | Send the key in the `x-api-key` header |
| `401` `{"error": "Invalid API key"}` | The key is not valid | Check the key, or create a new one on **Organization Settings** |
| `400` `{"error": "Too many wells requested. Limited to 50,000 at a time."}` | Over the well limit on `POST /v1/data` | Split the well list |
| `400` with `Limited to 1000 at a time.` | Over the well limit on `POST /v1/production` | Split the well list |
> **Note:**
> The REST API takes no filters. To ask about a whole basin or play without a well list, use the [EVA MCP server](https://developers.novilabs.com/eva/mcp/) (in preview).
---
# Novi M&A Intelligence
Source: https://developers.novilabs.com/ma/
> Query Novi's upstream oil and gas M&A deal records with SQL in Snowflake, or ask an AI assistant about them through the MCP server.
Query Novi's record of upstream oil and gas mergers and acquisitions with SQL, or ask an AI assistant about it. Each deal carries its dates and status, the buyers, sellers, sponsors and advisors, the basins it touches, the price and how it was paid, the production and acreage that changed hands, and Novi's valuation.
There is no public REST API for M&A Intelligence. For scripts, use [SQL over HTTPS](https://developers.novilabs.com/data/delivery/#sql-over-https).
- [Novi Intelligence on novilabs.com](https://novilabs.com/energy-analytics/intelligence/): Novi's research product line, which includes Novi M&A Intelligence.
## What you can build
| You want | Use |
| --- | --- |
| Comp sets in your valuation model: price per flowing BOE/d, price per net acre, PDP PV10 and the split between producing wells and undeveloped locations, one row per deal | Snowflake |
| Deal flow by basin, year and buyer in a BI tool, with totals summed on `MA_DEAL` so each deal counts once | Snowflake |
| Company histories across name changes: one key per company, with every name a deal recorded it under | Snowflake |
| Plain-language answers, such as "chart the top 10 buyers in the Permian since 2020 by total value", as a chart with a table of the same numbers | MCP server |
## What is available
| Surface | What you can do | Status |
| --- | --- | --- |
| Snowflake views in `NOVI_MA_INTEL` | Nine views: deals, parties and their roles, basins, Novi's valuation, analyst comments, and Novi's written deal analysis with a download link | [Available] |
| SQL over HTTPS | The same views from scripts and pipelines, with a Snowflake programmatic access token | [Available] |
| MCP server on your company host | 10 tools to search, filter, summarize, chart and tabulate deals and keep a comps basket. Charts and tables are not yet on company hosts | [Preview] |
| Wells that changed hands in each deal | Join a deal to the wells it transferred | [Planned] |
## Get access
| You want | You need | Who sets it up |
| --- | --- | --- |
| Snowflake | An M&A Intelligence subscription. It is separate from Novi UDM Data | Novi. Start with your Customer Success Advisor or support@novilabs.com |
| MCP server | A Novi login at your company's host with **Access Intelligence M&A**. **Access MCP** to sign in from an assistant | Your company's Novi administrator |
- A subscription includes every deal. There is no basin filter on this data.
- The Snowflake welcome email includes the M&A Intelligence guide (PDF) and an example cookbook. The **API Documentation** item in the M&A app's help menu opens the same guide.
- The data refreshes on a regular schedule. Each query returns the latest load.
## Next steps
- [M&A data in Snowflake](https://developers.novilabs.com/ma/data/): Views, keys, joins, key columns and starter SQL.
- [M&A Intelligence MCP server](https://developers.novilabs.com/ma/mcp/): Tools, filters, units and how to connect.
- [Delivery options](https://developers.novilabs.com/data/delivery/): Reader account, share into your account, and SQL over HTTPS.
- [Connect an assistant](https://developers.novilabs.com/ai/connect/): Add a Novi MCP server to Claude, Claude Code or Codex.
---
# M&A data in Snowflake
Source: https://developers.novilabs.com/ma/data/
> The nine views in NOVI_MA_INTEL, how they join, the columns most analyses need, and SQL that counts each deal once.
Query M&A deals in Snowflake database `NOVI_DATA_ACCESS`, schema `NOVI_MA_INTEL`. The current release is 1.6.72, the first release.
## Connect
Connect the same ways as Novi UDM Data: a Novi-hosted reader account, a share into your own Snowflake account, or SQL over HTTPS. Setup: [Delivery options](https://developers.novilabs.com/data/delivery/).
- **Its own subscription.** M&A Intelligence is licensed separately. On your own Snowflake account it arrives in the same Novi share and database as any other Novi data you subscribe to.
- **Every deal.** There is no basin filter on this schema.
- **Its own guide.** The welcome email includes the M&A Intelligence guide (PDF) and an example cookbook with 10 recipes.
Set the database and schema at the start of a session, and the SQL on this page runs as printed.
```sql title="Set your session"
USE DATABASE NOVI_DATA_ACCESS;
USE SCHEMA NOVI_MA_INTEL;
```
From a script, send the same SQL over HTTPS with a Snowflake programmatic access token ([Authentication](https://developers.novilabs.com/start/authentication/#snowflake-login-and-token)).
```bash title="Count deals over HTTPS"
curl -X POST "$NOVI_SNOWFLAKE_URL/api/v2/statements" \
-H "Authorization: Bearer $NOVI_SNOWFLAKE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"statement": "SELECT COUNT(*) FROM NOVI_MA_INTEL.MA_DEAL", "warehouse": "NOVI_WH", "database": "NOVI_DATA_ACCESS"}'
```
## Views
Start with `MA_DEAL`, one row per deal. Every other deal view joins to it on `MA_DEAL_KEY`.
| View | One row per | A row is |
| --- | --- | --- |
| `MA_DEAL` | `MA_DEAL_KEY` | A deal |
| `MA_DEAL_SCOPE` | `MA_DEAL_KEY`, `BASIN`, `SUBBASIN` | A basin and subbasin that a deal touches |
| `MA_DEAL_VALUATION` | `MA_DEAL_KEY` | Novi's valuation of a deal |
| `MA_DEAL_COMMENT` | `MA_DEAL_KEY`, `WORKSHEET_COLUMN` | The analyst's comment on one field of a deal |
| `MA_DEAL_PARTY` | `MA_DEAL_KEY`, `PARTY_KEY`, `ROLE`, `DEAL_SIDE` | A party in one role on one side of a deal |
| `PARTY` | `PARTY_KEY` | A company |
| `PARTY_ALIAS` | `PARTY_KEY`, `ALIAS` | A name a company was recorded under |
| `MA_DEAL_DOCUMENT` | `MA_DEAL_KEY`, `MA_DOCUMENT_KEY` | A document that covers a deal |
| `MA_DOCUMENT` | `MA_DOCUMENT_KEY` | A document written by Novi |
## How the views join
| From | To | On |
| --- | --- | --- |
| `MA_DEAL_SCOPE`, `MA_DEAL_VALUATION`, `MA_DEAL_COMMENT`, `MA_DEAL_PARTY`, `MA_DEAL_DOCUMENT` | `MA_DEAL` | `MA_DEAL_KEY` |
| `MA_DEAL_PARTY` | `PARTY` | `PARTY_KEY` |
| `PARTY_ALIAS` | `PARTY` | `PARTY_KEY` |
| `MA_DEAL_DOCUMENT` | `MA_DOCUMENT` | `MA_DOCUMENT_KEY` |
`MA_DEAL_PARTY` and `MA_DEAL_DOCUMENT` are link views: go through them to get from a deal to its parties or documents. `MA_DEAL_KEY` is a 64-bit integer, `NUMBER(19,0)`.
## Key columns
The columns most analyses start from. The guide describes every column.
### MA_DEAL
| Column | Meaning |
| --- | --- |
| `ANNOUNCE_DT`, `CLOSE_DT` | Announcement and closing dates. `CLOSE_DT` is empty until the deal closes |
| `DEAL_STATUS` | `ANNOUNCED`, `CLOSED` or `TERMINATED`. Ownership has not moved until `CLOSED` |
| `DEAL_TYPE`, `ASSET_OR_CORPORATE` | Merger or acquisition, and whether assets or the corporate entity changed hands |
| `DEAL_DESCRIPTION` | A one-line summary of the deal |
| `COMMODITY` | Primary commodity character of the deal's assets |
| `TOTAL_CONSIDERATION_USD_MM` | Headline consideration, USD millions. On all but a few deals it equals `CASH_USD_MM` + `ISSUED_EQUITY_USD_MM` + `DEBT_ASSUMED_USD_MM` + `OTHER_CONSIDERATION_USD_MM`, empty parts as 0 |
| `TOTAL_PRODUCTION_MBOE_D` | Production at deal time, thousand boe per day |
| `NET_MINERAL_ACRES`, `WORKING_INTEREST` | Net acres conveyed, and working interest as a fraction from 0 to 1 |
| `LIQUIDS` | Liquids share of production as the analyst reports it, a fraction from 0 to 1 |
| `CONSIDERATION_PER_FLOWING_BOE_D_USD`, `CONSIDERATION_PER_NET_ACRE_USD` | Price per flowing boe/d and per net acre, in US dollars |
| `STATES`, `CONSIDERATION_TYPE`, `DEAL_ASSET_TAGS` | Lists, stored as VARIANT arrays |
| `DEAL_GROUP_KEY` | Shared by deals recorded as parts of one package. Empty for most deals |
### MA_DEAL_SCOPE
| Column | Meaning |
| --- | --- |
| `BASIN` | From Novi's controlled list; Novi Wells basin names where Novi Wells has coverage |
| `SUBBASIN` | Sub-basin or play as reported. Part of the grain, so a deal in the Delaware and the Midland is two rows |
| `REGION` | `US_LOWER_48`, `GULF_OF_MEXICO`, `CANADA`, `ALASKA`, `INTERNATIONAL` or `UNDISCLOSED` |
| `STATE` | State or province for this basin, when the source gives it |
### MA_DEAL_VALUATION
Novi's deal-level comparables valuation, not per-well economics. Money is USD millions unless the column name says otherwise.
| Column | Meaning |
| --- | --- |
| `PDP_PV10_USD_MM` | Present value of proved developed producing reserves at 10% |
| `ALLOCATED_VALUE_PDP_USD_MM`, `ALLOCATED_VALUE_PUD_USD_MM`, `ALLOCATED_VALUE_OTHER_USD_MM` | How the price divides between producing wells, undeveloped locations and other assets |
| `IMPLIED_VALUE_PER_LOCATION_USD_MM` | Implied value per undeveloped location |
| `RQ_TIER1_LOCATIONS` to `RQ_TIER4_LOCATIONS` | Locations by Novi rock-quality tier |
| `PDP_PV10_PER_FLOWING_BOE_D_USD` | PDP PV10 per flowing boe/d, in US dollars |
| `BENCHMARK_WTI_PROMPT`, `BENCHMARK_HH_PROMPT`, `STRIP_DATE` | Prompt-month WTI (USD/bbl) and Henry Hub (USD/MMBtu) at deal time, and the as-of date of the forward strip the valuation used |
### MA_DEAL_PARTY, PARTY and PARTY_ALIAS
| Column | Meaning |
| --- | --- |
| `MA_DEAL_PARTY.ROLE` | `PRINCIPAL` for a buyer or seller. `SPONSOR`, `ADVISOR_FINANCIAL`, `ADVISOR_LEGAL`, `RECEIVER` or `TRUSTEE` for a party attached to one side |
| `MA_DEAL_PARTY.DEAL_SIDE` | `BUYER` or `SELLER`. For a sponsor or advisor, the side it backs or advises |
| `MA_DEAL_PARTY.PARTY_NAME_REPORTED` | The name as this deal recorded it |
| `MA_DEAL_PARTY.TICKER`, `IS_PUBLIC`, `MARKET_CAP_USD_MM`, `ENTERPRISE_VALUE_USD_MM` | A principal's ticker, listing, market cap and enterprise value at the time of the deal |
| `PARTY.PARTY_NAME` | One display name per company, for grouping |
| `PARTY_ALIAS.ALIAS`, `ALIAS_TYPE` | Every name a company was recorded under, such as a former name before a rebrand |
### MA_DEAL_COMMENT, MA_DEAL_DOCUMENT and MA_DOCUMENT
| Column | Meaning |
| --- | --- |
| `MA_DEAL_COMMENT.WORKSHEET_COLUMN_LABEL`, `COMMENT_TEXT` | The field the analyst commented on, and the comment |
| `MA_DEAL_DOCUMENT.PAGE_NUMBER` | Page where the deal appears in a document that covers several deals |
| `MA_DOCUMENT.TITLE`, `PUBLISHED_DATE`, `PAGE_COUNT` | Novi's written analysis of a deal |
| `MA_DOCUMENT.DOWNLOAD_URL` | A download link, good for 24 hours after your query runs. Empty while a new file is not ready |
The documents are Novi's own analysis, not press releases, investor presentations or other third-party material.
## Get the numbers right
- **Sum deal values on `MA_DEAL` only.** A join to `MA_DEAL_PARTY`, `MA_DEAL_SCOPE`, `MA_DEAL_COMMENT` or `MA_DEAL_DOCUMENT` repeats a deal's values on each of its rows. Filter with `EXISTS` instead.
- **A deal's value is not split between basins.** Count deals by basin; a sum by basin gives each basin the whole deal.
- **Buyers and sellers need `ROLE` and `DEAL_SIDE`.** A buyer is `ROLE = 'PRINCIPAL'` and `DEAL_SIDE = 'BUYER'`. `DEAL_SIDE` alone also returns sponsors and advisors.
- **Group companies on `PARTY_KEY`.** Search `PARTY_ALIAS.ALIAS` to find one by a former name.
- **Units are in the column name.** `_USD_MM` is millions of US dollars, `_MBOE_D` thousand boe per day. Percentages are fractions (0.18 is 18%). Ratios and per-unit prices do not add up across deals.
- **Empty is not zero.** It means not reported or not applicable.
- **Lists are arrays.** Test one value with `ARRAY_CONTAINS('TX'::VARIANT, STATES)`. Use `LATERAL FLATTEN` for one row per value, then count distinct `MA_DEAL_KEY`.
## Starter SQL
```sql title="The 50 most recently announced deals, with buyers and sellers"
SELECT d.ANNOUNCE_DT,
d.DEAL_DESCRIPTION,
d.DEAL_TYPE,
d.DEAL_STATUS,
d.COMMODITY,
d.TOTAL_CONSIDERATION_USD_MM,
LISTAGG(DISTINCT CASE WHEN dp.DEAL_SIDE = 'BUYER' THEN p.PARTY_NAME END, '; ') AS buyers,
LISTAGG(DISTINCT CASE WHEN dp.DEAL_SIDE = 'SELLER' THEN p.PARTY_NAME END, '; ') AS sellers
FROM NOVI_MA_INTEL.MA_DEAL d
LEFT JOIN NOVI_MA_INTEL.MA_DEAL_PARTY dp
ON dp.MA_DEAL_KEY = d.MA_DEAL_KEY AND dp.ROLE = 'PRINCIPAL'
LEFT JOIN NOVI_MA_INTEL.PARTY p ON p.PARTY_KEY = dp.PARTY_KEY
GROUP BY d.MA_DEAL_KEY, d.ANNOUNCE_DT, d.DEAL_DESCRIPTION, d.DEAL_TYPE, d.DEAL_STATUS,
d.COMMODITY, d.TOTAL_CONSIDERATION_USD_MM
ORDER BY d.ANNOUNCE_DT DESC NULLS LAST
LIMIT 50;
```
```sql title="Number of deals that touch each basin"
SELECT s.BASIN, COUNT(DISTINCT s.MA_DEAL_KEY) AS deal_count
FROM NOVI_MA_INTEL.MA_DEAL_SCOPE s
GROUP BY s.BASIN
ORDER BY deal_count DESC;
```
```sql title="Total consideration of deals that touch the Permian, each deal once"
SELECT SUM(d.TOTAL_CONSIDERATION_USD_MM) AS total_consideration_usd_mm
FROM NOVI_MA_INTEL.MA_DEAL d
WHERE EXISTS (
SELECT 1
FROM NOVI_MA_INTEL.MA_DEAL_SCOPE s
WHERE s.MA_DEAL_KEY = d.MA_DEAL_KEY
AND s.BASIN = 'Permian'
);
```
That total includes the whole value of any deal that also touches another basin.
```sql title="Download links for Novi's deal analysis"
SELECT doc.TITLE, doc.PUBLISHED_DATE, doc.PAGE_COUNT, doc.SIZE_BYTES, doc.DOWNLOAD_URL
FROM NOVI_MA_INTEL.MA_DOCUMENT doc
WHERE doc.DOWNLOAD_URL IS NOT NULL
ORDER BY doc.PUBLISHED_DATE DESC NULLS LAST, doc.TITLE;
```
More recipes, from the cookbook in your welcome email, are in the [M&A Intelligence cookbook](https://developers.novilabs.com/cookbook/ma-intelligence/): deal value and price per unit, Novi's valuation, sponsors and advisors, public company deals and premiums, states and tags, and linked deals with analyst comments.
## Look up columns yourself
View and column descriptions in Snowflake's catalog match the guide.
```sql title="Every view in NOVI_MA_INTEL"
SELECT table_name, table_type, row_count, comment
FROM NOVI_DATA_ACCESS.INFORMATION_SCHEMA.TABLES
WHERE table_schema = 'NOVI_MA_INTEL'
ORDER BY table_type, table_name;
```
```sql title="Columns of MA_DEAL"
SELECT column_name, data_type, is_nullable, comment
FROM NOVI_DATA_ACCESS.INFORMATION_SCHEMA.COLUMNS
WHERE table_schema = 'NOVI_MA_INTEL'
AND table_name = 'MA_DEAL'
ORDER BY ordinal_position;
```
> **Tip:**
> No rows in any view means your M&A Intelligence subscription is not active on that account. A total larger than you expect means a join to a view with several rows per deal counted a deal more than once.
---
# M&A Intelligence MCP server
Source: https://developers.novilabs.com/ma/mcp/
> Let an AI assistant search, summarize, chart and tabulate upstream M&A deals, with 10 tools that act as you.
Ask an assistant such as Claude to find, total, chart and tabulate upstream M&A deals, and keep a comps basket, as you.
## Connect
| | |
| --- | --- |
| URL | `https://.novilabs.io/intelligence-ma/api/mcp`, on the host you use for Novi apps in the browser |
| Transport | Streamable HTTP |
| Sign-in | Novi sign-in from a supported client, or a Novi API token as `Authorization: Bearer` |
| Permissions | **Access Intelligence M&A**. Signing in from an assistant also needs **Access MCP** |
| Status | [Preview] Charts and tables (`ma_chart_deals`, `ma_table_deals`) are not yet on company hosts |
**Novi sign-in**
Add the URL as a custom connector or remote MCP server and sign in with your Novi login. Supported clients and steps: [Connect an assistant](https://developers.novilabs.com/ai/connect/).
**Novi API token**
Any client that takes a URL and a header works, with a [token](https://developers.novilabs.com/start/authentication/#novi-api-token) for a user with Access Intelligence M&A.
```bash title="Claude Code"
claude mcp add --transport http novi-ma https://.novilabs.io/intelligence-ma/api/mcp \
--header "Authorization: Bearer $NOVI_API_TOKEN"
```
If the token expires or is revoked, create a new one and update the client.
## Tools
| Tool | What it does | Key inputs |
| --- | --- | --- |
| `ma_search_deals` | Turns a sentence into filters and runs them. Returns the filters, its `interpretation`, and `unsupported` and `unknown_companies` for the parts of the question the data can't express | `query`, `limit`, `offset` |
| `ma_filter_deals` | Lists deals that match explicit filters. Returns `total`, `limit`, `offset` and `transactions` | [Filters](#filters), `sort`, `dir`, `limit`, `offset` |
| `ma_summarize_deals` | Totals, averages and medians over the matching deals in one call, with breakdowns by deal type, scope, commodity, consideration type and ownership direction | [Filters](#filters) |
| `ma_filter_values` | Valid filter values as spelled in the data, basin to sub-basin pairings and sort keys. No company names | None |
| `ma_get_deal` | Full detail for one deal: every column plus basins, states, tags, advisors and the analyst's comments | `deal_id` |
| `ma_basket_add` | Adds deals to your comps basket. Returns the basket's deal ids, how many were added and `unknown_ids` | `deal_ids` |
| `ma_basket_remove` | Removes deals from your basket. Returns the basket's deal ids, how many were removed and `not_in_basket` | `deal_ids` |
| `ma_basket_list` | Your basket in full, oldest first, with the detail `ma_get_deal` returns. Returns `count` and `transactions` | None |
| `ma_chart_deals` | Charts deals: one bar or point per value of `dim`, measuring `metric` | `dim`, `metric`, `type`, `color_by`, `secondary_metric`, `top`, [filters](#filters) |
| `ma_table_deals` | Shows matching deals as a table: announced, buyer, seller, type, basins, value, production and price per flowing BOE/d | `sort`, `dir`, `limit`, `offset`, [filters](#filters) |
Use `ma_search_deals` in conversation, `ma_filter_deals` when the filters are decided, and `ma_summarize_deals` for "how much".
## Filters
`ma_filter_deals`, `ma_summarize_deals`, `ma_chart_deals` and `ma_table_deals` take these filters. Values in one list are ORed; different filters are ANDed.
| Filter | Takes |
| --- | --- |
| `search` | Full text over the deal |
| `basin`, `subbasin` | Lists of names |
| `state`, `buyer`, `seller`, `deal_type`, `deal_scope`, `commodity`, `deal_tag`, `other_asset_tag`, `consideration_type`, `ownership_dir` | Lists of values as `ma_filter_values` spells them. Buyer and seller names are used as given |
| `year_min`, `year_max` | Announcement years |
| `announce_from`, `announce_to`, `close_from`, `close_to` | Dates as `YYYY-MM-DD`, inclusive. A closing range matches only deals that have closed |
| `size_min`, `size_max` | Total consideration in $MM |
| `production_min`, `production_max` | Net production in Mboe/d, so 500 boe/d is 0.5. Matches only deals that disclose production |
| `liquids_min`, `liquids_max` | Liquids share of production in percent, 0 to 100 |
- Midland, Delaware, Marcellus and Utica are sub-basins. Given as a basin, they match as sub-basins and the result says so. An unknown name is an error that lists the valid names.
- The deal tag `Novi Research` selects deals Novi has published research on.
- Liquids filters take a percent; the `LIQUIDS` column in [Snowflake](https://developers.novilabs.com/ma/data/) is a fraction from 0 to 1.
## Totals and coverage
Each total says how many deals it covers, since not every deal discloses every figure.
| Figure | Covers |
| --- | --- |
| `total_count` | Every matching deal |
| `total_value`, `avg_value`, `median_value` ($MM) | `valued_count`, the deals that disclose a price |
| `total_production` (Mboe/d) | `production_count` |
| `median_consideration_per_boe` ($ per BOE/d) | `consideration_per_boe_count` |
Quote the count with the figure, for example "$4,800MM across 12 of 15 deals".
## Charts and tables
In clients that support MCP Apps, such as Claude, `ma_chart_deals` draws a chart with a table tab and `ma_table_deals` a sortable table. Every client gets the rows as JSON.
| Setting | Values |
| --- | --- |
| `dim` (the axis) | `year`, `close_year`, `deal_size`, `deal_type`, `deal_scope`, `commodity`, `ownership`, `consideration`, `buyer`, `seller`, `pe`, `basin`, `subbasin`, `geography`, `deal_tags`, `pe_firm`, `sponsor_type` |
| `metric` | `count` (default), `value`, `avg`, `production`, `acres`, `pv10`, `per_boe`, `consideration_per_boe` |
| `type` | `bar` (default), `line` for a trend over years, `table` to open on the table |
| `top` | How many of the largest to show on an unordered axis such as buyer or basin: 1 to 50, default 20. Years and deal-size bands show in full |
| `color_by` | Splits each bar into stacked bands by a second dimension. Not with an averaged metric (`avg`, `per_boe`, `consideration_per_boe`) |
| `secondary_metric` | A second measure drawn as a labelled line on a right-hand axis |
On `basin`, `subbasin`, `geography`, `deal_tags`, `pe_firm` and `sponsor_type`, a deal counts under each of its values, so bars can add up to more than the matching deals. The result's `notes` say so, and when a figure covers only the deals that disclose it.
## Paging, basket and errors
- **Paging.** `limit` is 1 to 100 rows, default 25. Page with `offset`.
- **Comps basket.** One per person, kept across sessions, up to 50 deals. Separate from the comps list in the M&A app.
- **Deal ids.** `deal_id` is not the `MA_DEAL_KEY` in Snowflake.
- **Errors.** An unknown deal id or filter value comes back as a tool result that names the cause.
- **Search limits.** `ma_search_deals` is rate limited per person; the error says how many seconds to wait. `ma_filter_deals` is not affected.
## What Novi records
For each tool call, Novi records the tool name, how long it took, whether it failed, how many deals it returned, which filters had a value, and the assistant app you signed in from. Filter values and the text of your search are not recorded.
## Good prompts
- Chart deal count by year since 2015, split by deal size, with total value as a line.
- Show the 15 largest Permian deals since 2020 as a table.
- Chart the top 10 buyers in the Permian since 2020 by total value.
- How much was paid for oil-weighted Williston deals closed since 2023, and how many of them disclosed a price?
> **Note:**
> Ask follow-ups in the same chat. Add deals to your basket as you go, then list the basket to compare them.
---
# Cookbook
Source: https://developers.novilabs.com/cookbook/
> Ready-to-run Snowflake SQL recipes for Novi Wells, Novi Intelligence and Novi M&A Intelligence, one collection per dataset.
Paste a recipe into a Snowflake worksheet to answer one engineering question. Each collection matches the release your
account reads today. Your welcome email points to the full cookbook.
- [Novi Wells](https://developers.novilabs.com/cookbook/wells/): Find wells, production and cumulatives, type wells, forecasts and decline, gunbarrels, rigs.
- [Novi Intelligence](https://developers.novilabs.com/cookbook/intelligence/): Basin research: inventory, rock quality, completion design, economics and breakevens, Arps curves.
- [Novi M&A Intelligence](https://developers.novilabs.com/cookbook/ma-intelligence/): Upstream deals: recent deals, deals by basin, deal value and metrics, valuation, advisors.
## Before you run a recipe
1. Connect to the `NOVI_DATA_ACCESS` database, as [Delivery](https://developers.novilabs.com/data/delivery/) describes.
2. Run `USE DATABASE NOVI_DATA_ACCESS;` once per session.
3. Change the filters in the recipe (basin, subbasin, formation, dates) to your own and run it.
Column meanings are in [Tables](https://developers.novilabs.com/data/tables/). Recipes that name a company or a specific well are in the full cookbook
only: see "In the notebook only" or "More recipes" on each page.
---
# Novi Wells recipes
Source: https://developers.novilabs.com/cookbook/wells/
> Ready-to-run Snowflake SQL recipes for well, production, forecast and activity questions on Novi UDM Data (v4).
Each recipe answers one engineering question. Copy it into a Snowflake worksheet, swap in your own basin, subbasin and
direction filters, and run it.
Run this once per session first:
```sql title="Set your session"
USE DATABASE NOVI_DATA_ACCESS;
USE SCHEMA NOVI_WELLS;
```
Recipes for one wellbore read a session variable, set here to an example Permian horizontal. Use your own `WELLBORE_KEY` if you have one.
```sql title="Pick an example wellbore"
SET wellbore_key = (
SELECT MIN(WELLBORE_KEY)
FROM NOVI_WELLS.WELLBORE
WHERE BASIN = 'Permian'
AND DIRECTION = 'HORIZONTAL'
AND MIDPOINT_LATITUDE IS NOT NULL
AND HEELPOINT_LATITUDE IS NOT NULL
AND BOTTOM_HOLE_LATITUDE IS NOT NULL
);
SET well_key = (SELECT WELL_KEY FROM NOVI_WELLS.WELLBORE WHERE WELLBORE_KEY = $wellbore_key);
```
## 1. Find wells from a list of API numbers
**Job:** turn a pasted list of API numbers in any format into Novi wells.
`WELL.NATIVE_ID` holds the API10, so the recipe keeps each value's first 10 digits. Replace the sample list with your own.
```sql title="Look up wells by API number"
SELECT w.WELL_KEY, w.WELL_NAME, w.NATIVE_ID, w.STATE, w.COUNTY, w.STATUS
FROM NOVI_WELLS.WELL w
WHERE w.NATIVE_ID IN (
SELECT LEFT(REGEXP_REPLACE(value, '[^0-9]', ''), 10)
FROM TABLE(SPLIT_TO_TABLE('42-000-00001, 4200000002, 42000000030000', ','))
)
ORDER BY w.WELL_KEY;
```
## 2. Screen wellbores with no joins
**Job:** shortlist horizontal wellbores by early productivity and completion design.
`WELL_DETAIL` already joins header, completion, spacing, and production roll-ups, one row per wellbore.
```sql title="Screen with WELL_DETAIL"
SELECT wd.WELLBORE_KEY, wd.WELL_NAME, wd.CURRENT_OPERATOR, wd.SUBBASIN, wd.FORMATION,
wd.FIRST_PRODUCTION_DATE, wd.LATERAL_LENGTH, wd.PROPPANT_LOADING, wd.STAGE_COUNT,
wd.CUM_OIL_12_REPORTED, wd.CUM_BOE_12_REPORTED
FROM NOVI_WELLS.WELL_DETAIL wd
WHERE wd.BASIN = 'Permian'
AND wd.DIRECTION = 'HORIZONTAL'
AND wd.LAST_REPORTED_MONTHS_ON_PRODUCTION IS NOT NULL
ORDER BY wd.CUM_BOE_12_REPORTED DESC NULLS LAST, wd.WELLBORE_KEY
LIMIT 100;
```
> **Note:**
> Reported production totals default to 0 for a wellbore that never produced, so `IS NOT NULL` on a cumulative does not exclude non-producers.
> `LAST_REPORTED_MONTHS_ON_PRODUCTION` is NULL exactly when there is no reported producing history. Filter on it instead.
## 3. Wells inside a drawn polygon
**Job:** select wells inside an area of interest drawn on a map.
Coordinates are WGS 84. Keep the cheap bounding-box filter first so `ST_WITHIN` only checks the candidates.
```sql title="Wells in a polygon"
SELECT sl.WELL_KEY, sl.LATITUDE, sl.LONGITUDE
FROM NOVI_WELLS.SURFACE_LOCATION sl
WHERE sl.LATITUDE BETWEEN 31.0 AND 32.5
AND sl.LONGITUDE BETWEEN -103.0 AND -101.5
AND ST_WITHIN(
ST_MAKEPOINT(sl.LONGITUDE, sl.LATITUDE),
TO_GEOGRAPHY('POLYGON((-103 31, -101.5 31, -101.5 32.5, -103 32.5, -103 31))'))
ORDER BY sl.WELL_KEY
LIMIT 200;
```
## 4. Type-well profile
**Job:** build an average-well curve for a cohort, aligned on months since first production, with oil per 1,000 ft of lateral.
Normalize each well-month, then average by month on production.
```sql title="Average type well, months 1 to 60"
WITH scope AS (
SELECT wb.WELLBORE_KEY, wb.LATERAL_LENGTH
FROM NOVI_WELLS.WELLBORE wb
WHERE wb.BASIN = 'Permian'
AND wb.SUBBASIN = 'Midland'
AND wb.DIRECTION = 'HORIZONTAL'
),
monthly AS (
SELECT p.WELLBORE_KEY, p.YEAR, p.MONTH,
MAX(p.MONTHS_ON_PRODUCTION) AS mop,
SUM(p.OIL) AS oil,
SUM(p.GAS) AS gas
FROM NOVI_WELLS.PRODUCTION p
JOIN scope s ON p.WELLBORE_KEY = s.WELLBORE_KEY
WHERE p.PERIOD_GRANULARITY = 'monthly'
GROUP BY p.WELLBORE_KEY, p.YEAR, p.MONTH
)
SELECT m.mop AS months_on_production,
COUNT(*) AS well_months,
ROUND(AVG(m.oil), 1) AS avg_oil_bbl,
ROUND(AVG(m.gas), 1) AS avg_gas_mcf,
ROUND(AVG(COALESCE(m.oil, 0) + COALESCE(m.gas, 0) / 6), 1) AS avg_boe,
ROUND(AVG(m.oil / NULLIF(s.LATERAL_LENGTH / 1000, 0)), 2) AS avg_oil_bbl_per_1000ft
FROM monthly m
JOIN scope s ON m.WELLBORE_KEY = s.WELLBORE_KEY
WHERE m.mop BETWEEN 1 AND 60
GROUP BY m.mop
ORDER BY m.mop;
```
`MONTHS_ON_PRODUCTION` starts at 1 and counts every calendar month after first production, shut-in months included.
`PRODUCTION` can hold more than one row for a wellbore and month, so the recipe collapses to one row per wellbore-month first.
## 5. 12-month cumulative oil and gas per wellbore
**Job:** compute first-12-month cumulatives yourself from monthly production, and keep only wellbores whose history supports it.
The `HAVING` checks matter: a unique, gap-free month index in step with the calendar, months 1 to 12 all present, and production through month 12.
```sql title="Cumulative oil and gas, months 1 to 12"
WITH scope AS (
SELECT wb.WELLBORE_KEY
FROM NOVI_WELLS.WELLBORE wb
WHERE wb.BASIN = 'Permian'
AND wb.SUBBASIN = 'Midland'
AND wb.DIRECTION = 'HORIZONTAL'
),
monthly AS (
SELECT p.WELLBORE_KEY, p.YEAR, p.MONTH,
MAX(p.MONTHS_ON_PRODUCTION) AS mop,
SUM(p.OIL) AS oil, SUM(p.GAS) AS gas, SUM(p.WATER) AS water,
SUM(p.CONDENSATE) AS condensate, SUM(p.GAS_FLARED) AS gas_flared
FROM NOVI_WELLS.PRODUCTION p
JOIN scope s ON p.WELLBORE_KEY = s.WELLBORE_KEY
WHERE p.PERIOD_GRANULARITY = 'monthly'
GROUP BY p.WELLBORE_KEY, p.YEAR, p.MONTH
)
SELECT WELLBORE_KEY,
SUM(CASE WHEN mop BETWEEN 1 AND 12 THEN COALESCE(oil, 0) END) AS cum12_oil_bbl,
SUM(CASE WHEN mop BETWEEN 1 AND 12 THEN COALESCE(gas, 0) END) AS cum12_gas_mcf
FROM monthly
GROUP BY WELLBORE_KEY
HAVING COUNT(DISTINCT CASE WHEN mop BETWEEN 1 AND 12 THEN mop END) = 12
AND MAX(mop) - MIN(mop) + 1 = COUNT(*)
AND COUNT(DISTINCT mop) = COUNT(*)
AND MIN(mop) >= 0
AND MIN(mop - (YEAR * 12 + MONTH)) = MAX(mop - (YEAR * 12 + MONTH))
AND MAX(CASE WHEN COALESCE(oil, 0) > 0 OR COALESCE(gas, 0) > 0 OR COALESCE(water, 0) > 0
OR COALESCE(condensate, 0) > 0 OR COALESCE(gas_flared, 0) > 0
THEN mop END) >= 12
AND SUM(CASE WHEN mop BETWEEN 1 AND 12 THEN oil END) > 0
ORDER BY cum12_oil_bbl DESC, WELLBORE_KEY
LIMIT 100;
```
`WELLBORE_PRODUCTION_SUMMARY` also publishes 12-month cumulatives, as reported by the source rather than computed from the monthly rows. The two are not guaranteed to agree.
## 6. Benchmark operators
**Job:** rank operators in a cohort by average 12-month cumulative oil per well.
Compare per-well averages, not totals. The window checks are the same as recipe 5.
```sql title="Operator ranking, cohorts of 25 wells or more"
WITH cohort AS (
SELECT wb.WELLBORE_KEY, o.NAME AS operator
FROM NOVI_WELLS.WELLBORE wb
JOIN NOVI_WELLS.WELL w ON wb.WELL_KEY = w.WELL_KEY
JOIN NOVI_WELLS.OPERATOR o ON w.OPERATOR_ID = o.OPERATOR_ID
WHERE wb.BASIN = 'Permian'
AND wb.SUBBASIN = 'Midland'
AND wb.DIRECTION = 'HORIZONTAL'
),
monthly AS (
SELECT c.operator, p.WELLBORE_KEY, p.YEAR, p.MONTH,
MAX(p.MONTHS_ON_PRODUCTION) AS mop,
SUM(p.OIL) AS oil, SUM(p.GAS) AS gas, SUM(p.WATER) AS water,
SUM(p.CONDENSATE) AS condensate, SUM(p.GAS_FLARED) AS gas_flared
FROM NOVI_WELLS.PRODUCTION p
JOIN cohort c ON p.WELLBORE_KEY = c.WELLBORE_KEY
WHERE p.PERIOD_GRANULARITY = 'monthly'
GROUP BY c.operator, p.WELLBORE_KEY, p.YEAR, p.MONTH
),
well_cum AS (
SELECT operator, WELLBORE_KEY,
SUM(CASE WHEN mop BETWEEN 1 AND 12 THEN COALESCE(oil, 0) END) AS cum12_oil_bbl
FROM monthly
GROUP BY operator, WELLBORE_KEY
HAVING COUNT(DISTINCT CASE WHEN mop BETWEEN 1 AND 12 THEN mop END) = 12
AND MAX(mop) - MIN(mop) + 1 = COUNT(*)
AND COUNT(DISTINCT mop) = COUNT(*)
AND MIN(mop) >= 0
AND MIN(mop - (YEAR * 12 + MONTH)) = MAX(mop - (YEAR * 12 + MONTH))
AND MAX(CASE WHEN COALESCE(oil, 0) > 0 OR COALESCE(gas, 0) > 0 OR COALESCE(water, 0) > 0
OR COALESCE(condensate, 0) > 0 OR COALESCE(gas_flared, 0) > 0
THEN mop END) >= 12
AND SUM(CASE WHEN mop BETWEEN 1 AND 12 THEN oil END) > 0
)
SELECT operator,
COUNT(*) AS wells,
ROUND(AVG(cum12_oil_bbl)) AS avg_cum12_oil_bbl,
ROUND(MEDIAN(cum12_oil_bbl)) AS median_cum12_oil_bbl
FROM well_cum
GROUP BY operator
HAVING COUNT(*) >= 25
ORDER BY avg_cum12_oil_bbl DESC, operator
LIMIT 25;
```
## 7. Forecast and decline parameters for one wellbore
**Job:** read the monthly P50 forecast and the Arps segments behind it.
Order forecast rows by `FORECAST_DAY`. Align them with actual production on `YEAR` and `MONTH`, not on `FORECAST_DAY`.
```sql title="Monthly P50 forecast"
SELECT FORECAST_DATE, FORECAST_MONTH, OIL_PER_DAY, GAS_PER_DAY, CUMULATIVE_OIL, CUMULATIVE_GAS
FROM NOVI_WELLS.PRODUCTION_FORECAST
WHERE WELLBORE_KEY = $wellbore_key
AND SCENARIO = 'P50'
AND PERIOD_GRANULARITY = 'monthly'
ORDER BY FORECAST_DAY;
```
```sql title="Arps segments and parameters"
SELECT seg.PRODUCTION_STREAM, seg.SEGMENT_NUMBER, seg.KIND, seg.SEGMENT_CURVE_TYPE,
seg.SEGMENT_START_DATE, seg.SEGMENT_END_DATE,
prm.B_FACTOR, prm.NOMINAL_DECLINE_RATE, prm.SEGMENT_START_RATE
FROM NOVI_WELLS.PRODUCTION_FORECAST_ARPS_SEGMENT seg
JOIN NOVI_WELLS.PRODUCTION_FORECAST_ARPS_SEGMENT_PARAMETER prm
ON prm.FORECAST_SEGMENT_ID = seg.SEGMENT_UID
WHERE seg.WELLBORE_KEY = $wellbore_key
ORDER BY seg.PRODUCTION_STREAM, seg.SEGMENT_NUMBER;
```
Forecast cumulatives start at the first forecast period and exclude earlier production. Decline rates are per-day fractions unless noted.
`b = 0` is exponential, `b = 1` is harmonic, and values between are hyperbolic.
## 8. EUR by subbasin
**Job:** compare 30-year forecast EUR per well across subbasins.
EUR columns are additive across wells at one horizon, never across horizons. Wells with no forecast are NULL and drop out.
```sql title="Average 30-year EUR per well"
SELECT wb.SUBBASIN,
COUNT(wps.EUR_BOE_30YR) AS wells_with_forecast,
ROUND(AVG(wps.EUR_OIL_30YR)) AS avg_eur_oil_30yr_bbl,
ROUND(AVG(wps.EUR_GAS_30YR)) AS avg_eur_gas_30yr_mcf,
ROUND(AVG(wps.EUR_BOE_30YR)) AS avg_eur_boe_30yr
FROM NOVI_WELLS.WELL_PRODUCTION_SUMMARY wps
JOIN NOVI_WELLS.WELLBORE wb ON wb.WELLBORE_KEY = wps.WELLBORE_KEY
WHERE wb.BASIN = 'Permian'
AND wb.DIRECTION = 'HORIZONTAL'
GROUP BY wb.SUBBASIN
ORDER BY avg_eur_boe_30yr DESC NULLS LAST;
```
## 9. Lifecycle timeline for one well
**Job:** list permit, spud, total depth, completion, and first production events in order.
Keep this wellbore's events plus well-level events, which have no `WELLBORE_KEY`. Per-event details live in the `PAYLOAD` map.
```sql title="Well events in date order"
SELECT EVENT_TYPE, EVENT_DT, EFFECTIVE_DT, WELLBORE_KEY,
PAYLOAD['operator_reported']::string AS operator_reported
FROM NOVI_WELLS.WELL_EVENT
WHERE WELL_KEY = $well_key
AND (WELLBORE_KEY = $wellbore_key OR WELLBORE_KEY IS NULL)
ORDER BY EVENT_DT;
```
`EVENT_DT` is when something happened. `EFFECTIVE_DT` is when it counts for status.
## 10. Gunbarrel: offsets around a wellbore
**Job:** find neighbors within about 1,000 m of a target lateral's midpoint, with lateral spacing and vertical offset, for a cross-section plot.
`lateral_spacing_ft` is the distance from each neighbor's midpoint to the target's heel-to-bottom-hole line, on either side.
```sql title="Gunbarrel neighbors"
WITH target AS (
SELECT wb.WELLBORE_KEY, wb.TVD_TD,
wb.MIDPOINT_LATITUDE AS lat,
wb.MIDPOINT_LONGITUDE AS lon,
ST_MAKEPOINT(wb.MIDPOINT_LONGITUDE, wb.MIDPOINT_LATITUDE) AS mid,
TO_GEOGRAPHY('LINESTRING('
|| wb.HEELPOINT_LONGITUDE || ' ' || wb.HEELPOINT_LATITUDE || ', '
|| wb.BOTTOM_HOLE_LONGITUDE || ' ' || wb.BOTTOM_HOLE_LATITUDE || ')'
) AS lateral_line
FROM NOVI_WELLS.WELLBORE wb
WHERE wb.WELLBORE_KEY = $wellbore_key
)
SELECT n.WELLBORE_KEY AS neighbor,
n.FORMATION,
ROUND(n.TVD_TD) AS tvd_ft,
ROUND(ST_DISTANCE(ST_MAKEPOINT(n.MIDPOINT_LONGITUDE, n.MIDPOINT_LATITUDE),
t.lateral_line) * 3.28084) AS lateral_spacing_ft,
ROUND(n.TVD_TD - t.TVD_TD) AS tvd_offset_ft
FROM target t
JOIN NOVI_WELLS.WELLBORE n
ON n.WELLBORE_KEY <> t.WELLBORE_KEY
AND n.MIDPOINT_LATITUDE BETWEEN t.lat - 0.02 AND t.lat + 0.02
AND n.MIDPOINT_LONGITUDE BETWEEN t.lon - 0.02 AND t.lon + 0.02
AND ST_DWITHIN(ST_MAKEPOINT(n.MIDPOINT_LONGITUDE, n.MIDPOINT_LATITUDE), t.mid, 1000)
ORDER BY lateral_spacing_ft, neighbor
LIMIT 30;
```
`WELL_SPACING` has precomputed distances, neighbor counts, and parent and child flags for each wellbore, but not the neighbor list.
## 11. Rig counts by basin and week
**Job:** track drilling activity.
Counts add up across geography but not across time.
```sql title="Weekly rig counts"
SELECT r.BASIN, r.YEAR, r.WEEK,
SUM(r.OIL_RIGS) AS oil_rigs,
SUM(r.GAS_RIGS) AS gas_rigs,
SUM(r.TOTAL_RIGS) AS total_rigs
FROM NOVI_WELLS.RIG_ACTIVITY_WEEKLY r
GROUP BY r.BASIN, r.YEAR, r.WEEK
ORDER BY r.YEAR DESC, r.WEEK DESC, total_rigs DESC, r.BASIN
LIMIT 100;
```
## 12. Gas producers by state
**Job:** count gas-producing wellbores using the declared function and stream.
For gas producers, read `GAS`, `OIL_AND_GAS`, and `CBM`, not `GAS` alone. States that file no well-type code report only `PRODUCER` or NULL.
```sql title="Gas producers by state"
SELECT w.STATE,
wb.PRIMARY_STREAM,
COUNT(*) AS wellbores
FROM NOVI_WELLS.WELLBORE wb
JOIN NOVI_WELLS.WELL w ON w.WELL_KEY = wb.WELL_KEY
WHERE wb.WELLBORE_TYPE_NORMALIZED = 'PRODUCER'
AND wb.PRIMARY_STREAM IN ('GAS', 'OIL_AND_GAS', 'CBM')
GROUP BY w.STATE, wb.PRIMARY_STREAM
ORDER BY wellbores DESC;
```
## More recipes
The notebook also covers well status mixes, slant and survey checks, well tests and gas gravity, permit expiry, lease numbers, legal land lookups, completion ratios and soak time.
Reader accounts get it as notebooks in a shared workspace or as a link to the online cookbook; the welcome email says which.
The full cookbook holds 18 recipes for this release (26.4.3):
- Cookbook recipe 1: Well lookup and filters
- Cookbook recipe 2: Spatial map
- Cookbook recipe 3: Production timeseries
- Cookbook recipe 4: Cumulative and IP
- Cookbook recipe 5: Forecast and decline
- Cookbook recipe 6: Well card detail
- Cookbook recipe 7: Benchmarking rankings
- Cookbook recipe 8: Activity and rigs
- Cookbook recipe 9: Well status
- Cookbook recipe 10: Bulk export
- Cookbook recipe 11: Gunbarrel
- Cookbook recipe 12: Wellbore slant and surveys
- Cookbook recipe 13: Well tests permits and land
- Cookbook recipe 14: Lease numbers permit expiry and primary stream
- Cookbook recipe 15: Presentation views
- Cookbook recipe 16: Completion ratios soak and EUR
- Cookbook recipe 17: Wellbore type and primary stream
- Cookbook recipe 18: Bulk downloads
---
# Novi Intelligence recipes
Source: https://developers.novilabs.com/cookbook/intelligence/
> Ready-to-run Snowflake SQL recipes for Novi Intelligence, from the cookbook your welcome email points to.
These recipes query the `NOVI_INTEL` schema. They match Novi Intelligence release 26.2.4, the release your account reads, and the full cookbook your welcome email points to holds the same SQL.
Run this once per session first:
```sql
USE DATABASE NOVI_DATA_ACCESS;
```
## 1. Basin overview
Basin-level summary: well counts by development class (PDP vs planned inventory: Base Case + Emerging).
It reproduces Basin Report cover page well counts.
Tables: `WELL`, `PLANNED_WELL`, `BASIN`.
**PDP wells by basin and subbasin**
```sql
SELECT
w.BASIN,
w.SUBBASIN,
w.REPORT_NAME,
COUNT(*) AS pdp_well_count
FROM NOVI_INTEL.WELL w
GROUP BY w.BASIN, w.SUBBASIN, w.REPORT_NAME
ORDER BY w.BASIN, w.SUBBASIN
```
**Base Case / Emerging inventory by basin**
```sql
SELECT
pw.BASIN,
pw.SUBBASIN,
pw.REPORT_NAME,
COUNT(*) AS planned_well_count,
COUNT(CASE WHEN pw.INVENTORY_CLASS = 'BASE_CASE' THEN 1 END) AS base_case_count,
COUNT(CASE WHEN pw.INVENTORY_CLASS = 'EMERGING' THEN 1 END) AS emerging_count
FROM NOVI_INTEL.PLANNED_WELL pw
GROUP BY pw.BASIN, pw.SUBBASIN, pw.REPORT_NAME
ORDER BY pw.BASIN, pw.SUBBASIN
```
**Combined PDP + planned inventory by basin (planned covers BASE_CASE + EMERGING)**
```sql
SELECT
BASIN,
SUM(CASE WHEN dev_class = 'PDP' THEN cnt ELSE 0 END) AS pdp,
SUM(CASE WHEN dev_class = 'PLANNED' THEN cnt ELSE 0 END) AS planned,
SUM(cnt) AS total
FROM (
SELECT BASIN, 'PDP' AS dev_class, COUNT(*) AS cnt FROM NOVI_INTEL.WELL GROUP BY BASIN
UNION ALL
SELECT BASIN, 'PLANNED' AS dev_class, COUNT(*) AS cnt FROM NOVI_INTEL.PLANNED_WELL GROUP BY BASIN
) x
GROUP BY BASIN
ORDER BY total DESC
```
## 2. Well header by operator
Well header with operator, formation, and wellbore geometry.
It reproduces Report Figures 11-14 (well counts by operator, formation, county).
Tables: `WELL`, `WELLBORE`, `OPERATOR`.
**Well count by operator (top 10)**
```sql
SELECT
o.NAME_NORMALIZED AS operator,
COUNT(*) AS well_count
FROM NOVI_INTEL.WELL w
JOIN NOVI_INTEL.OPERATOR o ON w.OPERATOR_ID = o.OPERATOR_ID
GROUP BY o.NAME_NORMALIZED
ORDER BY well_count DESC
LIMIT 10
```
**Well count by formation (from wellbore, since formation moved from well to wellbore)**
```sql
SELECT
wb.FORMATION AS formation,
COUNT(DISTINCT w.WELL_ID) AS well_count
FROM NOVI_INTEL.WELL w
JOIN NOVI_INTEL.WELLBORE wb ON wb.WELL_ID = w.WELL_ID
WHERE w.BASIN = 'Haynesville'
GROUP BY wb.FORMATION
ORDER BY well_count DESC
```
**Well header detail: well + wellbore + operator joined**
```sql
SELECT
w.UWI_API,
o.NAME_NORMALIZED AS operator,
w.BASIN,
w.SUBBASIN,
w.STATUS,
w.FIRST_PRODUCTION_DATE,
wb.FORMATION,
wb.LATERAL_LENGTH,
wb.TVD_TD,
wb.MD_TD
FROM NOVI_INTEL.WELL w
JOIN NOVI_INTEL.WELLBORE wb ON wb.WELL_ID = w.WELL_ID
JOIN NOVI_INTEL.OPERATOR o ON w.OPERATOR_ID = o.OPERATOR_ID
WHERE w.BASIN = 'Haynesville'
ORDER BY w.FIRST_PRODUCTION_DATE DESC NULLS LAST
LIMIT 20
```
## 3. Production forecast EUR
Production forecast EUR and type curve analysis.
It reproduces Executive Summary EUR estimates and forecast volumes.
Tables: `WELL_ECONOMICS_SUMMARY`, `WELL`, `OPERATOR`.
For what P10 and P90 mean in each Novi product, see [P-levels](https://developers.novilabs.com/concepts/p-levels/).
**EUR by operator (gas-focused, Haynesville)**
```sql
SELECT
o.NAME_NORMALIZED AS operator,
COUNT(*) AS well_count,
ROUND(AVG(es.EUR_GAS_30YR), 0) AS avg_eur_gas_mcf,
ROUND(AVG(es.EUR_DRY_GAS_30YR), 0) AS avg_eur_dry_gas_mcf,
ROUND(AVG(es.EUR_NGL_30YR), 0) AS avg_eur_ngl_bbl,
ROUND(AVG(es.IP_GAS), 1) AS avg_ip_gas_mcfd
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY es
JOIN NOVI_INTEL.WELL w ON es.WELL_ID = w.WELL_ID
JOIN NOVI_INTEL.OPERATOR o ON w.OPERATOR_ID = o.OPERATOR_ID
WHERE w.BASIN = 'Haynesville'
AND es.WELL_ID IS NOT NULL -- PDP wells only
GROUP BY o.NAME_NORMALIZED
HAVING COUNT(*) >= 10
ORDER BY avg_eur_gas_mcf DESC
```
**EUR distribution by formation**
```sql
SELECT
wb.FORMATION,
COUNT(*) AS well_count,
ROUND(PERCENTILE_CONT(0.10) WITHIN GROUP (ORDER BY es.EUR_GAS_30YR), 0) AS p10_eur_gas,
ROUND(PERCENTILE_CONT(0.50) WITHIN GROUP (ORDER BY es.EUR_GAS_30YR), 0) AS p50_eur_gas,
ROUND(PERCENTILE_CONT(0.90) WITHIN GROUP (ORDER BY es.EUR_GAS_30YR), 0) AS p90_eur_gas
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY es
JOIN NOVI_INTEL.WELL w ON es.WELL_ID = w.WELL_ID
JOIN NOVI_INTEL.WELLBORE wb ON wb.WELL_ID = w.WELL_ID
WHERE w.BASIN = 'Haynesville'
GROUP BY wb.FORMATION
ORDER BY p50_eur_gas DESC
```
**Daily forecast for a sample well (first 365 days)**
Note: PRODUCTION_FORECAST only has PLANNED_WELL_ID (WELL_ID is NULL), so query via PLANNED_WELL_ID directly.
```sql
SELECT
pf.PLANNED_WELL_ID,
pf.FORECAST_DAY,
pf.GAS_PER_DAY,
pf.CUMULATIVE_GAS,
pf.WATER_PER_DAY,
pf.CUMULATIVE_WATER
FROM NOVI_INTEL.PRODUCTION_FORECAST pf
WHERE pf.PLANNED_WELL_ID IS NOT NULL
AND pf.BASIN = 'Haynesville'
AND pf.FORECAST_DAY <= 365
ORDER BY pf.PLANNED_WELL_ID, pf.FORECAST_DAY
LIMIT 50
```
## 4. Economics breakeven
Well economics: NPV, IRR, breakeven analysis.
It reproduces Report Figure 1 (Remaining vs Drilled by NPV25 Breakeven Tranche) and Executive Summary average NPV25 breakeven of $3.06/Mcf.
Tables: `WELL_ECONOMICS_SUMMARY`, `WELL`, `PLANNED_WELL`, `ECON_PRICE_ASSUMPTION`.
**Average breakeven and NPV by basin (all planned inventory: Base Case + Emerging)**
For Base Case only, add: AND pw.INVENTORY_CLASS = 'BASE_CASE' to the WHERE clause.
```sql
SELECT
pw.BASIN,
COUNT(*) AS planned_well_count,
ROUND(AVG(es.BREAKEVEN_1YR), 2) AS avg_breakeven_1yr,
ROUND(AVG(es.NPV25_BREAKEVEN), 2) AS avg_npv25_breakeven,
ROUND(AVG(es.IRR * 100), 1) AS avg_irr_pct,
ROUND(AVG(es.PAYBACK_MONTHS), 0) AS avg_payback_months
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY es
JOIN NOVI_INTEL.PLANNED_WELL pw ON es.PLANNED_WELL_ID = pw.PLANNED_WELL_ID
WHERE pw.BASIN = 'Haynesville'
GROUP BY pw.BASIN
```
**NPV25 breakeven tranche distribution (all planned inventory)**
Matches Report Figure 1: % drilled vs undrilled by breakeven bracket.
```sql
SELECT
CASE
WHEN es.NPV25_BREAKEVEN <= 1.5 THEN '<= $1.50/Mcf'
WHEN es.NPV25_BREAKEVEN <= 2.0 THEN '<= $2.00/Mcf'
WHEN es.NPV25_BREAKEVEN <= 2.5 THEN '<= $2.50/Mcf'
WHEN es.NPV25_BREAKEVEN <= 3.0 THEN '<= $3.00/Mcf'
WHEN es.NPV25_BREAKEVEN <= 3.5 THEN '<= $3.50/Mcf'
ELSE '> $3.50/Mcf'
END AS breakeven_tranche,
COUNT(*) AS location_count,
ROUND(AVG(es.NPV10), 0) AS avg_npv10_usd,
ROUND(AVG(es.IRR * 100), 1) AS avg_irr_pct
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY es
JOIN NOVI_INTEL.PLANNED_WELL pw ON es.PLANNED_WELL_ID = pw.PLANNED_WELL_ID
WHERE pw.BASIN = 'Haynesville'
GROUP BY breakeven_tranche
ORDER BY breakeven_tranche
```
**Remaining planned-inventory value by discount rate (Base Case + Emerging)**
```sql
SELECT
pw.BASIN,
ROUND(SUM(es.NPV5), 0) AS total_npv5_usd,
ROUND(SUM(es.NPV10), 0) AS total_npv10_usd,
ROUND(SUM(es.NPV25), 0) AS total_npv25_usd
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY es
JOIN NOVI_INTEL.PLANNED_WELL pw ON es.PLANNED_WELL_ID = pw.PLANNED_WELL_ID
WHERE pw.BASIN = 'Haynesville'
GROUP BY pw.BASIN
```
**Price deck assumptions**
```sql
SELECT
epa.NAME,
epa.OIL_PRICE AS wti_price,
epa.GAS_PRICE AS hh_price,
epa.NGL_PRICE,
epa.OIL_PRICE_DIFFERENTIAL AS wti_diff,
epa.GAS_PRICE_DIFFERENTIAL AS hh_diff
FROM NOVI_INTEL.ECON_PRICE_ASSUMPTION epa
```
## 5. Rock quality tiers
Rock quality tier analysis by operator and formation.
It reproduces Executive Summary Figures 1-2 (PDP / Base Case by tier), Report Figure 2 ~5.2k tier-1, ~5.4k tier-2, ~6.1k tier-3, ~5.9k tier-4.
Tables: `WELL_ROCK_QUALITY`, `WELL`, `PLANNED_WELL`, `OPERATOR`.
**Tier distribution for PDP wells (drilled)**
```sql
SELECT
rq.ROCK_QUALITY_TIER,
COUNT(*) AS well_count
FROM NOVI_INTEL.WELL_ROCK_QUALITY rq
WHERE rq.WELL_CLASS = 'PDP'
AND rq.BASIN = 'Haynesville'
AND rq.STREAM = 'gas'
GROUP BY rq.ROCK_QUALITY_TIER
ORDER BY rq.ROCK_QUALITY_TIER
```
**Tier distribution for Base Case wells (remaining inventory)**
```sql
SELECT
rq.ROCK_QUALITY_TIER,
COUNT(*) AS location_count
FROM NOVI_INTEL.WELL_ROCK_QUALITY rq
WHERE rq.WELL_CLASS = 'BASE_CASE'
AND rq.BASIN = 'Haynesville'
AND rq.STREAM = 'gas'
GROUP BY rq.ROCK_QUALITY_TIER
ORDER BY rq.ROCK_QUALITY_TIER
```
**Operator benchmarking: remaining inventory weighting by tier**
Reproduces: Report Figure 2 (Estimated Operated Remaining Location Weighting).
```sql
SELECT
o.NAME_NORMALIZED AS operator,
COUNT(*) AS total_locations,
COUNT(CASE WHEN rq.ROCK_QUALITY_TIER = 'Tier-1' THEN 1 END) AS tier_1,
COUNT(CASE WHEN rq.ROCK_QUALITY_TIER = 'Tier-2' THEN 1 END) AS tier_2,
COUNT(CASE WHEN rq.ROCK_QUALITY_TIER = 'Tier-3' THEN 1 END) AS tier_3,
COUNT(CASE WHEN rq.ROCK_QUALITY_TIER = 'Tier-4' THEN 1 END) AS tier_4,
ROUND(100.0 * COUNT(CASE WHEN rq.ROCK_QUALITY_TIER IN ('Tier-1', 'Tier-2') THEN 1 END)
/ NULLIF(COUNT(*), 0), 1) AS pct_top_tier
FROM NOVI_INTEL.WELL_ROCK_QUALITY rq
JOIN NOVI_INTEL.OPERATOR o ON rq.OPERATOR_ID = o.OPERATOR_ID
WHERE rq.WELL_CLASS = 'BASE_CASE'
AND rq.BASIN = 'Haynesville'
AND rq.STREAM = 'gas'
GROUP BY o.NAME_NORMALIZED
HAVING COUNT(*) >= 50
ORDER BY pct_top_tier DESC
```
**Rock quality by formation**
```sql
SELECT
rq.FORMATION,
rq.ROCK_QUALITY_TIER,
COUNT(*) AS cnt
FROM NOVI_INTEL.WELL_ROCK_QUALITY rq
WHERE rq.BASIN = 'Haynesville'
AND rq.STREAM = 'gas'
GROUP BY rq.FORMATION, rq.ROCK_QUALITY_TIER
ORDER BY rq.FORMATION, rq.ROCK_QUALITY_TIER
```
## 6. Completion design
Completion design analysis: proppant, fluid, lateral length trends.
It reproduces Report Figures 18-21 (lateral length over time, proppant/rig efficiency).
Tables: `WELL_COMPLETION`, `WELLBORE`, `WELL`, `OPERATOR`.
**Average completion design metrics (all wells by basin)**
Note: WELL_COMPLETION only has PLANNED_WELL_ID (WELL_ID is NULL).
```sql
SELECT
wc.BASIN,
COUNT(*) AS well_count,
ROUND(AVG(wc.LATERAL_LENGTH_FT), 0) AS avg_lateral_ft,
ROUND(AVG(wc.PROPPANT_MASS), 0) AS avg_proppant_lbs,
ROUND(AVG(wc.FLUID_VOLUME), 0) AS avg_fluid_gal,
ROUND(AVG(wc.PROPPANT_LOADING), 0) AS avg_proppant_lbs_per_ft
FROM NOVI_INTEL.WELL_COMPLETION wc
WHERE wc.BASIN = 'Haynesville'
GROUP BY wc.BASIN
```
**Long lateral trend (>12,500 ft)**
Reproduces: Report Figure 19.
```sql
SELECT
YEAR(w.FIRST_PRODUCTION_DATE) AS fpy,
COUNT(*) AS total_wells,
COUNT(CASE WHEN wb.LATERAL_LENGTH > 12500 THEN 1 END) AS long_laterals,
ROUND(100.0 * COUNT(CASE WHEN wb.LATERAL_LENGTH > 12500 THEN 1 END)
/ NULLIF(COUNT(*), 0), 1) AS pct_long_lateral
FROM NOVI_INTEL.WELL w
JOIN NOVI_INTEL.WELLBORE wb ON wb.WELL_ID = w.WELL_ID
WHERE w.BASIN = 'Haynesville'
AND w.FIRST_PRODUCTION_DATE IS NOT NULL
GROUP BY fpy
ORDER BY fpy
```
**Completion design by operator (top 10)**
Join to OPERATOR via WELLBORE -> WELL or PLANNED_WELL for operator name.
```sql
SELECT
o.NAME_NORMALIZED AS operator,
COUNT(*) AS well_count,
ROUND(AVG(wc.LATERAL_LENGTH_FT), 0) AS avg_lateral_ft,
ROUND(AVG(wc.PROPPANT_LOADING), 0) AS avg_proppant_lbs_per_ft,
ROUND(AVG(wc.FLUID_LOADING), 0) AS avg_fluid_gal_per_ft
FROM NOVI_INTEL.WELL_COMPLETION wc
JOIN NOVI_INTEL.PLANNED_WELL pw ON pw.PLANNED_WELL_ID = wc.PLANNED_WELL_ID
JOIN NOVI_INTEL.OPERATOR o ON o.OPERATOR_ID = pw.OPERATOR_ID
WHERE wc.BASIN = 'Haynesville'
GROUP BY o.NAME_NORMALIZED
HAVING COUNT(*) >= 20
ORDER BY well_count DESC
LIMIT 10
```
## 7. Arps decline curve
Arps decline curve parameters per well per stream. ARPS_FORECAST pre-joins the segment structure with the Arps parameters (qi, Di, b), so reconstructing the decline model is a single SELECT.
View: `ARPS_FORECAST`.
**Arps segments for wells in the Williston basin**
Note: Arps segments are keyed by WELL_REF (UWI_API for completed wells, 'PW-``' for planned wells).
```sql
SELECT
WELL_REF,
STREAM,
SEGMENT_NUMBER,
SEGMENT_CURVE_TYPE,
DAY_START,
DAY_STOP,
B_FACTOR,
NOMINAL_DECLINE_RATE AS di,
SEGMENT_START_RATE AS qi,
SEGMENT_END_RATE
FROM NOVI_INTEL.ARPS_FORECAST
WHERE BASIN = 'Williston'
ORDER BY WELL_REF, STREAM, SEGMENT_NUMBER
LIMIT 50
```
**Average Arps parameters by basin (oil stream, segment 1 only)**
Note: Haynesville has no arps data; Williston, Permian, Appalachia do.
```sql
SELECT
BASIN,
COUNT(*) AS segment_count,
ROUND(AVG(B_FACTOR), 3) AS avg_b_factor,
ROUND(AVG(NOMINAL_DECLINE_RATE), 4) AS avg_di,
ROUND(AVG(SEGMENT_START_RATE), 1) AS avg_qi
FROM NOVI_INTEL.ARPS_FORECAST
WHERE STREAM = 'oil'
AND SEGMENT_NUMBER = 1
GROUP BY BASIN
ORDER BY avg_qi DESC
```
## 8. Cost summary
D&C and DCET cost analysis by operator and basin.
It reproduces Inventory sheet cost columns.
Tables: `WELL_COST_SUMMARY`, `WELL`, `PLANNED_WELL`, `OPERATOR`.
**Average D&C costs by operator (PDP wells)**
```sql
SELECT
o.NAME_NORMALIZED AS operator,
COUNT(*) AS well_count,
ROUND(AVG(cs.TOTAL_DC_COST), 0) AS avg_dc_cost_usd,
ROUND(AVG(cs.TOTAL_DCET_COST), 0) AS avg_dcet_cost_usd,
ROUND(AVG(cs.NORMALIZED_DC_COST_PER_FT), 0) AS avg_dc_per_ft_usd,
ROUND(AVG(cs.NORMALIZED_DCET_COST_PER_FT), 0) AS avg_dcet_per_ft_usd
FROM NOVI_INTEL.WELL_COST_SUMMARY cs
JOIN NOVI_INTEL.WELL w ON cs.WELL_ID = w.WELL_ID
JOIN NOVI_INTEL.OPERATOR o ON w.OPERATOR_ID = o.OPERATOR_ID
WHERE w.BASIN = 'Haynesville'
GROUP BY o.NAME_NORMALIZED
HAVING COUNT(*) >= 10
ORDER BY avg_dc_cost_usd
```
**Cost breakdown: D&C vs equip + tie-in by basin**
Note: the intelligence inventory source carries only total D&C and DCET costs, not a discrete drilling / completion / facilities / other split (those columns are always NULL for rows from basin research), so the equip + tie-in portion is derived as DCET - D&C.
```sql
SELECT
w.BASIN,
COUNT(*) AS well_count,
ROUND(AVG(cs.TOTAL_DC_COST), 0) AS avg_dc_cost_usd,
ROUND(AVG(cs.TOTAL_DCET_COST), 0) AS avg_dcet_cost_usd,
ROUND(AVG(cs.TOTAL_DCET_COST - cs.TOTAL_DC_COST), 0) AS avg_equip_tiein_usd
FROM NOVI_INTEL.WELL_COST_SUMMARY cs
JOIN NOVI_INTEL.WELL w ON cs.WELL_ID = w.WELL_ID
WHERE w.BASIN = 'Haynesville'
GROUP BY w.BASIN
```
## 9. Inventory by operator
Remaining inventory analysis by operator.
It reproduces Report "Total Remaining by Operator" sheet and Figure 2.
Tables: `PLANNED_WELL`, `WELLBORE`, `OPERATOR`, `WELL_ECONOMICS_SUMMARY`.
**Remaining Base Case locations by operator with economics**
```sql
SELECT
o.NAME_NORMALIZED AS operator,
COUNT(*) AS remaining_locations,
ROUND(AVG(pw.LATERAL_LENGTH), 0) AS avg_lateral_ft,
ROUND(SUM(pw.LATERAL_LENGTH), 0) AS total_lateral_ft,
ROUND(AVG(es.NPV25_BREAKEVEN), 2) AS avg_npv25_breakeven,
ROUND(AVG(es.IRR * 100), 1) AS avg_irr_pct
FROM NOVI_INTEL.PLANNED_WELL pw
JOIN NOVI_INTEL.OPERATOR o ON pw.OPERATOR_ID = o.OPERATOR_ID
LEFT JOIN NOVI_INTEL.WELL_ECONOMICS_SUMMARY es ON es.PLANNED_WELL_ID = pw.PLANNED_WELL_ID
WHERE pw.BASIN = 'Haynesville'
AND pw.INVENTORY_CLASS = 'BASE_CASE'
GROUP BY o.NAME_NORMALIZED
HAVING COUNT(*) >= 20
ORDER BY remaining_locations DESC
```
**Implied inventory life at current drilling cadence**
Assumes ~500 wells/year (~4.9 MM ft/year) based on 2023-2024 cadence.
```sql
SELECT
o.NAME_NORMALIZED AS operator,
COUNT(*) AS remaining_locations,
ROUND(SUM(pw.LATERAL_LENGTH), 0) AS total_remaining_ft,
ROUND(SUM(pw.LATERAL_LENGTH) / 4900000.0, 1) AS implied_years_at_basin_cadence
FROM NOVI_INTEL.PLANNED_WELL pw
JOIN NOVI_INTEL.OPERATOR o ON pw.OPERATOR_ID = o.OPERATOR_ID
WHERE pw.BASIN = 'Haynesville'
AND pw.INVENTORY_CLASS = 'BASE_CASE'
GROUP BY o.NAME_NORMALIZED
HAVING COUNT(*) >= 50
ORDER BY implied_years_at_basin_cadence DESC
```
**Inventory by pad (planned wells grouped by pad)**
```sql
SELECT
p.NAME AS pad_name,
p.OPERATOR_NAME,
p.BASIN,
COUNT(pw.PLANNED_WELL_ID) AS wells_on_pad
FROM NOVI_INTEL.PAD p
JOIN NOVI_INTEL.PLANNED_WELL pw ON pw.PAD_ID = p.PAD_ID
WHERE p.BASIN = 'Haynesville'
GROUP BY p.NAME, p.OPERATOR_NAME, p.BASIN
ORDER BY wells_on_pad DESC
LIMIT 20
```
## 11. Data freshness
Check which basin reports are loaded and when they were last refreshed. Useful for verifying data currency before analysis.
Tables: `SOURCE`, `WELL`, `BASIN`.
**Available basin reports**
```sql
SELECT
s.COLLECTION AS report_name,
s.SYSTEM,
MIN(s.CREATED_AT) AS first_loaded,
COUNT(DISTINCT w.WELL_ID) AS well_count
FROM NOVI_INTEL.SOURCE s
LEFT JOIN NOVI_INTEL.WELL w ON w.SOURCE_ID = s.SOURCE_ID
GROUP BY s.COLLECTION, s.SYSTEM
ORDER BY s.COLLECTION
```
**Basin dimension: all available basins and subbasins**
```sql
SELECT
b.BASIN,
b.SUBBASIN
FROM NOVI_INTEL.BASIN b
ORDER BY b.BASIN, b.SUBBASIN
```
**Row counts per entity (data completeness check)**
```sql
SELECT 'WELL' AS entity, COUNT(*) AS row_count FROM NOVI_INTEL.WELL
UNION ALL SELECT 'WELLBORE', COUNT(*) FROM NOVI_INTEL.WELLBORE
UNION ALL SELECT 'PLANNED_WELL', COUNT(*) FROM NOVI_INTEL.PLANNED_WELL
UNION ALL SELECT 'WELL_COMPLETION', COUNT(*) FROM NOVI_INTEL.WELL_COMPLETION
UNION ALL SELECT 'PRODUCTION_FORECAST', COUNT(*) FROM NOVI_INTEL.PRODUCTION_FORECAST
UNION ALL SELECT 'WELL_ECONOMICS_SUMMARY', COUNT(*) FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY
UNION ALL SELECT 'WELL_ROCK_QUALITY', COUNT(*) FROM NOVI_INTEL.WELL_ROCK_QUALITY
UNION ALL SELECT 'WELL_COST_SUMMARY', COUNT(*) FROM NOVI_INTEL.WELL_COST_SUMMARY
ORDER BY entity
```
## 12. Oil basin economics
Oil-focused economics for basins like Williston (Bakken/Three Forks). Haynesville uses $/Mcf (gas) breakevens, Williston uses $/bbl (oil) breakevens.
It reproduces Williston Exec Summary avg NPV25 breakeven ~$89/bbl (WTI).
Tables: `WELL_ECONOMICS_SUMMARY`, `PLANNED_WELL`, `OPERATOR`.
**NPV25 breakeven tranche distribution ($/bbl for oil basins)**
```sql
SELECT
CASE
WHEN es.NPV25_BREAKEVEN <= 40 THEN '<= $40/bbl'
WHEN es.NPV25_BREAKEVEN <= 50 THEN '<= $50/bbl'
WHEN es.NPV25_BREAKEVEN <= 60 THEN '<= $60/bbl'
WHEN es.NPV25_BREAKEVEN <= 70 THEN '<= $70/bbl'
WHEN es.NPV25_BREAKEVEN <= 80 THEN '<= $80/bbl'
WHEN es.NPV25_BREAKEVEN <= 90 THEN '<= $90/bbl'
ELSE '> $90/bbl'
END AS breakeven_tranche,
COUNT(*) AS location_count,
ROUND(AVG(es.IRR * 100), 1) AS avg_irr_pct,
ROUND(AVG(es.PAYBACK_MONTHS), 0) AS avg_payback_months
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY es
JOIN NOVI_INTEL.PLANNED_WELL pw ON es.PLANNED_WELL_ID = pw.PLANNED_WELL_ID
WHERE pw.BASIN = 'Williston'
GROUP BY breakeven_tranche
ORDER BY breakeven_tranche
```
**Oil EUR by operator (Williston is oil-primary)**
```sql
SELECT
o.NAME_NORMALIZED AS operator,
COUNT(*) AS well_count,
ROUND(AVG(es.EUR_OIL_30YR), 0) AS avg_eur_oil_bbl,
ROUND(AVG(es.EUR_GAS_30YR), 0) AS avg_eur_gas_mcf,
ROUND(AVG(es.IP_OIL), 1) AS avg_ip_oil_bpd,
ROUND(AVG(es.NGL_YIELD), 1) AS avg_ngl_yield
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY es
JOIN NOVI_INTEL.WELL w ON es.WELL_ID = w.WELL_ID
JOIN NOVI_INTEL.OPERATOR o ON w.OPERATOR_ID = o.OPERATOR_ID
WHERE w.BASIN = 'Williston'
GROUP BY o.NAME_NORMALIZED
HAVING COUNT(*) >= 20
ORDER BY avg_eur_oil_bbl DESC
```
**Two-year payout breakeven by first production year**
Williston report: wells drilled now to 2030 can generate sub-$70/bbl payout.
```sql
SELECT
YEAR(w.FIRST_PRODUCTION_DATE) AS fpy,
COUNT(*) AS well_count,
ROUND(AVG(es.BREAKEVEN_2YR), 2) AS avg_2yr_breakeven,
ROUND(AVG(es.PAYBACK_MONTHS), 0) AS avg_payback_months
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY es
JOIN NOVI_INTEL.WELL w ON es.WELL_ID = w.WELL_ID
WHERE w.BASIN = 'Williston'
AND w.FIRST_PRODUCTION_DATE IS NOT NULL
GROUP BY fpy
ORDER BY fpy
```
## 13. Base case vs emerging inventory
Base Case vs Emerging inventory split. Williston: ~37.8k Base Case + ~5.2k Emerging locations.
It reproduces Exec Summary "37,801 Base Case locations and 5,184 Emerging locations".
Tables: `PLANNED_WELL`, `WELL_ROCK_QUALITY`, `OPERATOR`.
**Base Case vs Emerging counts by basin**
```sql
SELECT
pw.BASIN,
pw.INVENTORY_CLASS,
COUNT(*) AS location_count,
ROUND(AVG(pw.LATERAL_LENGTH), 0) AS avg_lateral_ft
FROM NOVI_INTEL.PLANNED_WELL pw
GROUP BY pw.BASIN, pw.INVENTORY_CLASS
ORDER BY pw.BASIN, pw.INVENTORY_CLASS
```
**Rock quality tier distribution by well class (Base Case vs Emerging)**
```sql
SELECT
rq.WELL_CLASS,
rq.ROCK_QUALITY_TIER,
COUNT(*) AS location_count
FROM NOVI_INTEL.WELL_ROCK_QUALITY rq
WHERE rq.BASIN = 'Williston'
AND rq.WELL_CLASS IN ('BASE_CASE', 'EMERGING')
AND rq.STREAM = 'oil'
GROUP BY rq.WELL_CLASS, rq.ROCK_QUALITY_TIER
ORDER BY rq.WELL_CLASS, rq.ROCK_QUALITY_TIER
```
**Top operators by Base Case + Emerging inventory**
```sql
SELECT
o.NAME_NORMALIZED AS operator,
COUNT(CASE WHEN pw.INVENTORY_CLASS = 'BASE_CASE' THEN 1 END) AS base_case_count,
COUNT(CASE WHEN pw.INVENTORY_CLASS = 'EMERGING' THEN 1 END) AS emerging_count,
COUNT(*) AS total
FROM NOVI_INTEL.PLANNED_WELL pw
JOIN NOVI_INTEL.OPERATOR o ON pw.OPERATOR_ID = o.OPERATOR_ID
WHERE pw.BASIN = 'Williston'
GROUP BY o.NAME_NORMALIZED
ORDER BY total DESC
LIMIT 15
```
## 14. Multi formation comparison
Compare performance across formations within a basin. Williston: Middle Bakken vs Three Forks (primary targets). Haynesville: Haynesville Shale vs Bossier Shale.
It reproduces Report Figures 13-14 (production by formation).
Tables: `WELLBORE`, `WELL`, `WELL_ECONOMICS_SUMMARY`, `WELL_ROCK_QUALITY`.
**Well count and EUR by formation (Williston)**
```sql
SELECT
wb.FORMATION,
COUNT(DISTINCT w.WELL_ID) AS pdp_well_count,
ROUND(AVG(es.EUR_OIL_30YR), 0) AS avg_eur_oil_bbl,
ROUND(AVG(es.EUR_GAS_30YR), 0) AS avg_eur_gas_mcf,
ROUND(AVG(es.IP_OIL), 1) AS avg_ip_oil_bpd,
ROUND(AVG(wb.LATERAL_LENGTH), 0) AS avg_lateral_ft
FROM NOVI_INTEL.WELL w
JOIN NOVI_INTEL.WELLBORE wb ON wb.WELL_ID = w.WELL_ID
LEFT JOIN NOVI_INTEL.WELL_ECONOMICS_SUMMARY es ON es.WELL_ID = w.WELL_ID
WHERE w.BASIN = 'Williston'
GROUP BY wb.FORMATION
HAVING COUNT(DISTINCT w.WELL_ID) >= 10
ORDER BY pdp_well_count DESC
```
**Rock quality tier distribution by formation**
```sql
SELECT
rq.FORMATION,
rq.ROCK_QUALITY_TIER,
COUNT(*) AS cnt,
ROUND(100.0 * COUNT(*) / SUM(COUNT(*)) OVER (PARTITION BY rq.FORMATION), 1) AS pct
FROM NOVI_INTEL.WELL_ROCK_QUALITY rq
WHERE rq.BASIN = 'Williston'
AND rq.STREAM = 'oil'
AND rq.WELL_CLASS = 'BASE_CASE'
GROUP BY rq.FORMATION, rq.ROCK_QUALITY_TIER
ORDER BY rq.FORMATION, rq.ROCK_QUALITY_TIER
```
**Average breakeven by formation (all planned inventory: Base Case + Emerging)**
For Base Case only, add: AND pw.INVENTORY_CLASS = 'BASE_CASE' to the WHERE clause.
```sql
SELECT
wb.FORMATION,
COUNT(*) AS planned_well_count,
ROUND(AVG(es.NPV25_BREAKEVEN), 2) AS avg_npv25_breakeven,
ROUND(AVG(es.BREAKEVEN_2YR), 2) AS avg_2yr_breakeven
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY es
JOIN NOVI_INTEL.PLANNED_WELL pw ON es.PLANNED_WELL_ID = pw.PLANNED_WELL_ID
JOIN NOVI_INTEL.WELLBORE wb ON wb.PLANNED_WELL_ID = pw.PLANNED_WELL_ID
WHERE pw.BASIN = 'Williston'
GROUP BY wb.FORMATION
HAVING COUNT(*) >= 50
ORDER BY avg_npv25_breakeven
```
## 15. Cross basin comparison
Compare key metrics across all loaded basins. Useful when your subscription covers several basins.
Tables: `WELL`, `PLANNED_WELL`, `WELL_ECONOMICS_SUMMARY`, `WELL_ROCK_QUALITY`.
**Basin-level summary card**
```sql
SELECT
BASIN,
COUNT(*) AS pdp_wells
FROM NOVI_INTEL.WELL
GROUP BY BASIN
ORDER BY pdp_wells DESC
```
**Base Case inventory and economics by basin**
```sql
SELECT
pw.BASIN,
COUNT(*) AS base_case_locations,
ROUND(AVG(es.NPV25_BREAKEVEN), 2) AS avg_npv25_breakeven,
ROUND(AVG(es.IRR * 100), 1) AS avg_irr_pct,
ROUND(AVG(es.PAYBACK_MONTHS), 0) AS avg_payback_months,
ROUND(AVG(es.EUR_OIL_30YR), 0) AS avg_eur_oil_bbl,
ROUND(AVG(es.EUR_GAS_30YR), 0) AS avg_eur_gas_mcf
FROM NOVI_INTEL.PLANNED_WELL pw
LEFT JOIN NOVI_INTEL.WELL_ECONOMICS_SUMMARY es ON es.PLANNED_WELL_ID = pw.PLANNED_WELL_ID
WHERE pw.INVENTORY_CLASS = 'BASE_CASE'
GROUP BY pw.BASIN
ORDER BY base_case_locations DESC
```
**Rock quality distribution comparison across basins**
```sql
SELECT
rq.BASIN,
rq.ROCK_QUALITY_TIER,
COUNT(*) AS cnt
FROM NOVI_INTEL.WELL_ROCK_QUALITY rq
WHERE rq.WELL_CLASS = 'BASE_CASE'
GROUP BY rq.BASIN, rq.ROCK_QUALITY_TIER
ORDER BY rq.BASIN, rq.ROCK_QUALITY_TIER
```
**Top operators across all basins (counts all planned inventory: Base Case + Emerging)**
For Base Case only, add: AND pw.INVENTORY_CLASS = 'BASE_CASE' to the LEFT JOIN ON clause.
```sql
SELECT
o.NAME_NORMALIZED AS operator,
COUNT(DISTINCT w.BASIN) AS basins_active,
COUNT(DISTINCT w.WELL_ID) AS total_pdp_wells,
COUNT(DISTINCT pw.PLANNED_WELL_ID) AS total_planned_locations
FROM NOVI_INTEL.OPERATOR o
LEFT JOIN NOVI_INTEL.WELL w ON w.OPERATOR_ID = o.OPERATOR_ID
LEFT JOIN NOVI_INTEL.PLANNED_WELL pw ON pw.OPERATOR_ID = o.OPERATOR_ID
GROUP BY o.NAME_NORMALIZED
HAVING COUNT(DISTINCT w.WELL_ID) > 0 OR COUNT(DISTINCT pw.PLANNED_WELL_ID) > 0
ORDER BY total_pdp_wells + total_planned_locations DESC
LIMIT 20
```
**Completion design evolution comparison across basins**
Average completion design by basin (all wells). Note: WELL_COMPLETION only has PLANNED_WELL_ID (WELL_ID is NULL).
```sql
SELECT
wc.BASIN,
COUNT(*) AS well_count,
ROUND(AVG(wc.LATERAL_LENGTH_FT), 0) AS avg_lateral_ft,
ROUND(AVG(wc.PROPPANT_LOADING), 0) AS avg_proppant_lbs_per_ft
FROM NOVI_INTEL.WELL_COMPLETION wc
GROUP BY wc.BASIN
ORDER BY wc.BASIN
```
## 16. Breakeven by stream
Breakeven analysis faceted by commodity stream. The STREAM column on WELL_ECONOMICS_SUMMARY lets you separate breakevens by commodity unit basis. Without this faceting, gas wells (avg ~$3/MMBtu HH) and oil wells (avg ~$57/bbl WTI) get co-mingled on the same color scale, which makes gas basins dominate the lower end. Important: STREAM is a well-classification tag, NOT a unit discriminator. Wet Gas wells are tagged 'ngl' (consistent with WELL_ROCK_QUALITY.STREAM) but their breakeven values are still in gas $/MMBtu units. For unit-aware faceting: STREAM IN ('gas', 'ngl') -> gas-unit breakevens ($/MMBtu HH). STREAM = 'oil' -> oil-unit breakevens ($/bbl WTI).
Tables: `WELL_ECONOMICS_SUMMARY`, `WELL`, `PLANNED_WELL`, `BASIN`.
**Average breakeven by basin and stream (UNION across drilled + planned for full coverage)**
```sql
WITH well_basin_econ AS (
SELECT e.STREAM, e.NPV10_BREAKEVEN, b.BASIN AS basin_name
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY e
JOIN NOVI_INTEL.WELL w ON w.WELL_ID = e.WELL_ID
JOIN NOVI_INTEL.BASIN b ON b.BASIN_ID = w.BASIN_ID
WHERE e.WELL_ID IS NOT NULL
UNION ALL
SELECT e.STREAM, e.NPV10_BREAKEVEN, b.BASIN AS basin_name
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY e
JOIN NOVI_INTEL.PLANNED_WELL pw ON pw.PLANNED_WELL_ID = e.PLANNED_WELL_ID
JOIN NOVI_INTEL.BASIN b ON b.BASIN_ID = pw.BASIN_ID
WHERE e.PLANNED_WELL_ID IS NOT NULL
)
SELECT
basin_name,
STREAM,
ROUND(AVG(NPV10_BREAKEVEN), 2) AS avg_npv10_breakeven,
ROUND(MIN(NPV10_BREAKEVEN), 2) AS min_breakeven,
ROUND(MAX(NPV10_BREAKEVEN), 2) AS max_breakeven,
COUNT(*) AS wells
FROM well_basin_econ
WHERE STREAM IN ('oil', 'gas', 'ngl')
GROUP BY 1, 2
ORDER BY 1, 2
```
**Gas-unit breakeven only (STREAM IN ('gas', 'ngl')): color-by-breakeven on a single map**
```sql
WITH well_basin_econ AS (
SELECT e.STREAM, e.NPV10_BREAKEVEN, b.BASIN AS basin_name
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY e
JOIN NOVI_INTEL.WELL w ON w.WELL_ID = e.WELL_ID
JOIN NOVI_INTEL.BASIN b ON b.BASIN_ID = w.BASIN_ID
WHERE e.WELL_ID IS NOT NULL
UNION ALL
SELECT e.STREAM, e.NPV10_BREAKEVEN, b.BASIN AS basin_name
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY e
JOIN NOVI_INTEL.PLANNED_WELL pw ON pw.PLANNED_WELL_ID = e.PLANNED_WELL_ID
JOIN NOVI_INTEL.BASIN b ON b.BASIN_ID = pw.BASIN_ID
WHERE e.PLANNED_WELL_ID IS NOT NULL
)
SELECT
basin_name,
ROUND(AVG(NPV10_BREAKEVEN), 2) AS avg_be_per_mmbtu,
COUNT(*) AS wells
FROM well_basin_econ
WHERE STREAM IN ('gas', 'ngl')
GROUP BY 1
ORDER BY 2
```
**Oil-unit breakeven only (STREAM = 'oil')**
```sql
WITH well_basin_econ AS (
SELECT e.STREAM, e.NPV10_BREAKEVEN, b.BASIN AS basin_name
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY e
JOIN NOVI_INTEL.WELL w ON w.WELL_ID = e.WELL_ID
JOIN NOVI_INTEL.BASIN b ON b.BASIN_ID = w.BASIN_ID
WHERE e.WELL_ID IS NOT NULL
UNION ALL
SELECT e.STREAM, e.NPV10_BREAKEVEN, b.BASIN AS basin_name
FROM NOVI_INTEL.WELL_ECONOMICS_SUMMARY e
JOIN NOVI_INTEL.PLANNED_WELL pw ON pw.PLANNED_WELL_ID = e.PLANNED_WELL_ID
JOIN NOVI_INTEL.BASIN b ON b.BASIN_ID = pw.BASIN_ID
WHERE e.PLANNED_WELL_ID IS NOT NULL
)
SELECT
basin_name,
ROUND(AVG(NPV10_BREAKEVEN), 2) AS avg_be_per_bbl,
COUNT(*) AS wells
FROM well_basin_econ
WHERE STREAM = 'oil'
GROUP BY 1
ORDER BY 2
```
## 17. Well master overview
Unified well inventory: PDP + Base Case + Emerging in one view. REPORT_NAME identifies the basin report quarter (e.g., 'basin_research__Midland_Basin__2025Q3').
**Basin summary: count by inventory class (single report)**
```sql
SELECT
BASIN, INVENTORY_CLASS, COUNT(*) AS well_count
FROM NOVI_INTEL.WELL_MASTER
WHERE REPORT_NAME = 'basin_research__Midland_Basin__2025Q3'
GROUP BY 1, 2 ORDER BY 1, 2
```
**Top 10 operators by total inventory**
```sql
SELECT
OPERATOR_NAME, COUNT(*) AS total_wells,
COUNT(CASE WHEN INVENTORY_CLASS = 'PDP' THEN 1 END) AS pdp,
COUNT(CASE WHEN INVENTORY_CLASS = 'BASE_CASE' THEN 1 END) AS base_case,
COUNT(CASE WHEN INVENTORY_CLASS = 'EMERGING' THEN 1 END) AS emerging
FROM NOVI_INTEL.WELL_MASTER
GROUP BY 1 ORDER BY total_wells DESC LIMIT 10
```
**Available reports**
```sql
SELECT REPORT_NAME, INVENTORY_CLASS, COUNT(*) AS well_count
FROM NOVI_INTEL.WELL_MASTER
GROUP BY 1, 2 ORDER BY 1, 2
```
**Wells with geometry for a specific report (for GIS mapping)**
```sql
SELECT WELL_REF, INVENTORY_CLASS, LATITUDE, LONGITUDE, GEOMETRY_GEO, OPERATOR_NAME, FORMATION
FROM NOVI_INTEL.WELL_MASTER
WHERE GEOMETRY_GEO IS NOT NULL AND REPORT_NAME = 'basin_research__Midland_Basin__2025Q3'
LIMIT 100
```
## 18. Economics scorecard
Economics scorecard: breakevens faceted by stream (oil vs gas vs ngl). Note: STREAM is a well-classification tag, NOT a unit discriminator. Wet Gas wells are tagged 'ngl' but breakeven values are in gas $/MMBtu. For unit-aware faceting: STREAM IN ('gas','ngl') = gas-unit, STREAM = 'oil' = oil-unit.
**Average breakeven by stream for a specific report**
```sql
SELECT
REPORT_NAME, STREAM, COUNT(*) AS wells,
ROUND(AVG(NPV10_BREAKEVEN), 2) AS avg_npv10_be,
ROUND(AVG(IRR * 100), 1) AS avg_irr_pct,
ROUND(AVG(PAYBACK_MONTHS), 0) AS avg_payback
FROM NOVI_INTEL.WELL_ECONOMICS
WHERE STREAM IN ('oil', 'gas', 'ngl')
AND REPORT_NAME = 'basin_research__Midland_Basin__2025Q3'
GROUP BY 1, 2 ORDER BY 1, 2
```
**Oil-only: top basins by NPV10 (cross-report comparison)**
```sql
SELECT
BASIN, REPORT_NAME, COUNT(*) AS wells,
ROUND(SUM(NPV10), 0) AS total_npv10_usd,
ROUND(AVG(NPV10_BREAKEVEN), 2) AS avg_be_per_bbl
FROM NOVI_INTEL.WELL_ECONOMICS
WHERE STREAM = 'oil'
GROUP BY 1, 2 ORDER BY total_npv10_usd DESC
```
**Cross-view join: economics + well master for operator benchmarking (single report)**
```sql
SELECT
wm.OPERATOR_NAME, wm.BASIN,
COUNT(*) AS wells,
ROUND(AVG(we.NPV10_BREAKEVEN), 2) AS avg_be,
ROUND(AVG(we.IRR * 100), 1) AS avg_irr_pct,
ROUND(AVG(wm.LATERAL_LENGTH), 0) AS avg_lateral_ft
FROM NOVI_INTEL.WELL_ECONOMICS we
JOIN NOVI_INTEL.WELL_MASTER wm USING (WELL_REF)
WHERE we.STREAM = 'oil' AND we.REPORT_NAME = 'basin_research__Midland_Basin__2025Q3'
GROUP BY 1, 2 HAVING COUNT(*) >= 20
ORDER BY avg_be
```
## 19. ML score analysis
Rock quality scores by stream and tier.
**Tier distribution by basin (gas stream)**
```sql
SELECT
BASIN, ROCK_QUALITY_TIER, COUNT(*) AS well_count
FROM NOVI_INTEL.ML_SCORE
WHERE STREAM = 'gas'
GROUP BY 1, 2 ORDER BY 1, 2
```
**Average score by operator (oil, Base Case only)**
```sql
SELECT
OPERATOR_NAME, COUNT(*) AS locations,
ROUND(AVG(ROCK_QUALITY_SCORE), 3) AS avg_score,
COUNT(CASE WHEN ROCK_QUALITY_TIER IN ('Tier-1','Tier-2') THEN 1 END) AS top_tier_count,
ROUND(100.0 * COUNT(CASE WHEN ROCK_QUALITY_TIER IN ('Tier-1','Tier-2') THEN 1 END)
/ NULLIF(COUNT(*), 0), 1) AS pct_top_tier
FROM NOVI_INTEL.ML_SCORE
WHERE STREAM = 'oil' AND INVENTORY_CLASS = 'BASE_CASE'
GROUP BY 1 HAVING COUNT(*) >= 50
ORDER BY pct_top_tier DESC
```
**Cross-view: economics + rock quality for tier-weighted breakeven**
```sql
SELECT
ms.ROCK_QUALITY_TIER,
COUNT(*) AS wells,
ROUND(AVG(we.NPV10_BREAKEVEN), 2) AS avg_be,
ROUND(AVG(we.IRR * 100), 1) AS avg_irr_pct
FROM NOVI_INTEL.ML_SCORE ms
JOIN NOVI_INTEL.WELL_ECONOMICS we USING (WELL_REF)
WHERE ms.STREAM = 'oil' AND ms.BASIN = 'Permian'
GROUP BY 1 ORDER BY 1
```
## 20. Inventory forecast
Time-series production forecast for Base Case / Emerging inventory.
**First 5 years of monthly oil forecast for a report**
```sql
SELECT
WELL_REF, OPERATOR_NAME, YEAR, MONTH,
OIL_PER_DAY, CUMULATIVE_OIL
FROM NOVI_INTEL.INVENTORY_FORECAST
WHERE REPORT_NAME = 'basin_research__Midland_Basin__2025Q3'
AND FORECAST_DAY <= 1825
ORDER BY WELL_REF, FORECAST_DAY
LIMIT 100
```
**Basin-level aggregate forecast by year (derived from FORECAST_DAY)**
YEAR/MONTH columns are NULL in intelligence data; use FORECAST_DAY instead.
```sql
SELECT
BASIN,
FLOOR(FORECAST_DAY / 365) + 1 AS forecast_year,
COUNT(DISTINCT WELL_REF) AS wells,
ROUND(AVG(OIL_PER_DAY), 0) AS avg_oil_bpd,
ROUND(AVG(GAS_PER_DAY), 0) AS avg_gas_mcfd
FROM NOVI_INTEL.INVENTORY_FORECAST
WHERE FORECAST_DAY <= 1825
GROUP BY 1, 2 ORDER BY 1, 2
```
## 21. Arps decline parameters
Arps decline curve parameters by basin and stream.
**Average decline parameters by basin (oil, segment 1)**
```sql
SELECT
BASIN, COUNT(*) AS segment_count,
ROUND(AVG(B_FACTOR), 3) AS avg_b,
ROUND(AVG(NOMINAL_DECLINE_RATE), 4) AS avg_di,
ROUND(AVG(SEGMENT_START_RATE), 1) AS avg_qi
FROM NOVI_INTEL.ARPS_FORECAST
WHERE STREAM = 'oil' AND SEGMENT_NUMBER = 1
GROUP BY 1 ORDER BY avg_qi DESC
```
**Full decline model for a specific report**
```sql
SELECT
WELL_REF, STREAM, SEGMENT_NUMBER,
SEGMENT_CURVE_TYPE, B_FACTOR,
NOMINAL_DECLINE_RATE AS di,
SEGMENT_START_RATE AS qi, SEGMENT_END_RATE,
DAY_START, DAY_STOP
FROM NOVI_INTEL.ARPS_FORECAST
WHERE REPORT_NAME = 'basin_research__Williston_Basin__2025Q4'
ORDER BY WELL_REF, STREAM, SEGMENT_NUMBER
LIMIT 50
```
## 22. Report deep dive
Single-report deep dive using all 5 presentation views. Replace the REPORT_NAME value with any loaded report (e.g., 'basin_research__Midland_Basin__2025Q3', 'basin_research__Haynesville_Basin__2025Q4', 'basin_research__Delaware_Basin__2025Q3').
**1. Well Master: full inventory for the report**
```sql
SELECT
WELL_REF, INVENTORY_CLASS, OPERATOR_NAME, FORMATION,
LATERAL_LENGTH, LATITUDE, LONGITUDE, STATUS
FROM NOVI_INTEL.WELL_MASTER
WHERE REPORT_NAME = 'basin_research__Midland_Basin__2025Q3'
ORDER BY INVENTORY_CLASS, OPERATOR_NAME
```
**2. Well Economics: breakeven + returns for the report**
```sql
SELECT
WELL_REF, INVENTORY_CLASS, STREAM, OPERATOR_NAME,
NPV10_BREAKEVEN, IRR, PAYBACK_MONTHS,
EUR_OIL_30YR, EUR_GAS_30YR, TOTAL_DCET_COST
FROM NOVI_INTEL.WELL_ECONOMICS
WHERE REPORT_NAME = 'basin_research__Midland_Basin__2025Q3'
ORDER BY NPV10_BREAKEVEN
```
**3. ML Score: rock quality distribution for the report**
```sql
SELECT
WELL_REF, INVENTORY_CLASS, STREAM,
ROCK_QUALITY_SCORE, ROCK_QUALITY_TIER, OPERATOR_NAME
FROM NOVI_INTEL.ML_SCORE
WHERE REPORT_NAME = 'basin_research__Midland_Basin__2025Q3'
ORDER BY ROCK_QUALITY_SCORE DESC
```
**4. Inventory Forecast: first-year rates for the report (YEAR is NULL; use FORECAST_DAY)**
```sql
SELECT
WELL_REF, NAME, OPERATOR_NAME, SCENARIO,
FORECAST_DAY, OIL_PER_DAY, GAS_PER_DAY,
CUMULATIVE_OIL, CUMULATIVE_GAS
FROM NOVI_INTEL.INVENTORY_FORECAST
WHERE REPORT_NAME = 'basin_research__Midland_Basin__2025Q3'
AND FORECAST_DAY <= 365
ORDER BY WELL_REF, FORECAST_DAY
LIMIT 100
```
**5. Arps Forecast: decline parameters for the report**
```sql
SELECT
WELL_REF, STREAM, SEGMENT_NUMBER,
B_FACTOR, NOMINAL_DECLINE_RATE AS di,
SEGMENT_START_RATE AS qi, SEGMENT_END_RATE,
DAY_START, DAY_STOP
FROM NOVI_INTEL.ARPS_FORECAST
WHERE REPORT_NAME = 'basin_research__Midland_Basin__2025Q3'
ORDER BY WELL_REF, STREAM, SEGMENT_NUMBER
```
**6. Cross-view: report summary dashboard**
```sql
SELECT
wm.INVENTORY_CLASS,
COUNT(DISTINCT wm.WELL_REF) AS total_wells,
ROUND(AVG(we.NPV10_BREAKEVEN), 2) AS avg_breakeven,
ROUND(AVG(we.IRR * 100), 1) AS avg_irr_pct,
ROUND(AVG(wm.LATERAL_LENGTH), 0) AS avg_lateral_ft,
ROUND(AVG(ms.ROCK_QUALITY_SCORE), 2) AS avg_rq_score
FROM NOVI_INTEL.WELL_MASTER wm
LEFT JOIN NOVI_INTEL.WELL_ECONOMICS we ON we.WELL_REF = wm.WELL_REF AND we.REPORT_NAME = wm.REPORT_NAME
LEFT JOIN NOVI_INTEL.ML_SCORE ms ON ms.WELL_REF = wm.WELL_REF AND ms.REPORT_NAME = wm.REPORT_NAME AND ms.STREAM = 'oil'
WHERE wm.REPORT_NAME = 'basin_research__Midland_Basin__2025Q3'
GROUP BY 1 ORDER BY 1
```
## Join patterns
Most queries join through the `WELL` or `PLANNED_WELL` tables as the central dimension:
```
WELL → WELLBORE (geometry, formation)
WELL → OPERATOR (name, contact)
WELL → WELL_COMPLETION (proppant, fluid)
WELL → WELL_ECONOMICS_SUMMARY (NPV, IRR, EUR)
WELL → WELL_COST_SUMMARY (D&C costs)
WELL → WELL_ROCK_QUALITY (ML tier scores)
WELL → PRODUCTION_FORECAST (daily rates)
WELL → ARPS_FORECAST (presentation view: pre-joined Arps qi, Di, b)
```
## Notes
- Monetary values (NPV, PV, costs) are stored as exact decimals (`NUMBER(28,7)`) in whole currency units: query them directly, no scaling.
- IRR is stored as a decimal fraction (0.15 = 15%). Multiply by 100 for percentage.
- Formation is on `WELLBORE`, not `WELL`.
- `BASIN` and `SUBBASIN` columns are available on all entity views for filtering.
- `REPORT_NAME` identifies which basin research report the data came from.
- A report can carry more than one price deck; `PRICE_DECK_ID` is scoped to its report, and a forward-curve deck has NULL headline prices.
---
# Novi M&A Intelligence recipes
Source: https://developers.novilabs.com/cookbook/ma-intelligence/
> Ready-to-run Snowflake SQL recipes for Novi M&A Intelligence, from the cookbook your welcome email points to.
These recipes query the `NOVI_MA_INTEL` schema. They match Novi M&A Intelligence release 1.6.72, the release your account reads, and the full cookbook your welcome email points to holds the same SQL.
Run this once per session first:
```sql
USE DATABASE NOVI_DATA_ACCESS;
```
## 1. Recent deals
The newest deals, with the buyer and the seller of each. A deal can have several buyers or several sellers, so the names are collected into one list per side and each deal stays one row.
Tables: `MA_DEAL`, `MA_DEAL_PARTY`, `PARTY`.
**The 50 most recently announced deals**
```sql
SELECT d.ANNOUNCE_DT,
d.DEAL_DESCRIPTION,
d.DEAL_TYPE,
d.DEAL_STATUS,
d.COMMODITY,
d.TOTAL_CONSIDERATION_USD_MM,
LISTAGG(DISTINCT CASE WHEN dp.DEAL_SIDE = 'BUYER' THEN p.PARTY_NAME END, '; ') AS buyers,
LISTAGG(DISTINCT CASE WHEN dp.DEAL_SIDE = 'SELLER' THEN p.PARTY_NAME END, '; ') AS sellers
FROM NOVI_MA_INTEL.MA_DEAL d
LEFT JOIN NOVI_MA_INTEL.MA_DEAL_PARTY dp
ON dp.MA_DEAL_KEY = d.MA_DEAL_KEY AND dp.ROLE = 'PRINCIPAL'
LEFT JOIN NOVI_MA_INTEL.PARTY p ON p.PARTY_KEY = dp.PARTY_KEY
GROUP BY d.MA_DEAL_KEY, d.ANNOUNCE_DT, d.DEAL_DESCRIPTION, d.DEAL_TYPE, d.DEAL_STATUS,
d.COMMODITY, d.TOTAL_CONSIDERATION_USD_MM
ORDER BY d.ANNOUNCE_DT DESC NULLS LAST
LIMIT 50
```
**Deals announced but not closed. Ownership has not moved until DEAL_STATUS is CLOSED**
```sql
SELECT d.ANNOUNCE_DT, d.DEAL_DESCRIPTION, d.TOTAL_CONSIDERATION_USD_MM
FROM NOVI_MA_INTEL.MA_DEAL d
WHERE d.DEAL_STATUS = 'ANNOUNCED'
ORDER BY d.ANNOUNCE_DT DESC
```
## 2. Deals by basin
Deals by basin. MA_DEAL_SCOPE has one row per deal, basin and subbasin, and holds no values. A deal in three basins is three rows there, and its value is stored once on MA_DEAL. Count deals by basin, but do not add up a deal's value by basin: each basin would get the whole deal.
Tables: `MA_DEAL`, `MA_DEAL_SCOPE`.
**Number of deals that touch each basin**
```sql
SELECT s.BASIN, COUNT(DISTINCT s.MA_DEAL_KEY) AS deal_count
FROM NOVI_MA_INTEL.MA_DEAL_SCOPE s
GROUP BY s.BASIN
ORDER BY deal_count DESC
```
**Deals in one basin, newest first**
```sql
SELECT d.ANNOUNCE_DT, d.DEAL_DESCRIPTION, d.DEAL_STATUS, d.TOTAL_CONSIDERATION_USD_MM
FROM NOVI_MA_INTEL.MA_DEAL d
WHERE EXISTS (
SELECT 1
FROM NOVI_MA_INTEL.MA_DEAL_SCOPE s
WHERE s.MA_DEAL_KEY = d.MA_DEAL_KEY
AND s.BASIN = 'Permian'
)
ORDER BY d.ANNOUNCE_DT DESC
```
**Total consideration of the deals in exactly one basin, by basin and year**
Multi-basin deals are left out, so no value is counted twice.
```sql
WITH single_basin AS (
SELECT s.MA_DEAL_KEY, MIN(s.BASIN) AS BASIN
FROM NOVI_MA_INTEL.MA_DEAL_SCOPE s
GROUP BY s.MA_DEAL_KEY
HAVING COUNT(DISTINCT s.BASIN) = 1
)
SELECT sb.BASIN,
YEAR(d.ANNOUNCE_DT) AS announce_year,
COUNT(*) AS deal_count,
SUM(d.TOTAL_CONSIDERATION_USD_MM) AS total_consideration_usd_mm
FROM NOVI_MA_INTEL.MA_DEAL d
JOIN single_basin sb ON sb.MA_DEAL_KEY = d.MA_DEAL_KEY
GROUP BY sb.BASIN, announce_year
ORDER BY sb.BASIN, announce_year
```
## 4. Deal value and metrics
Deal value over time and price paid per unit. Values are in USD millions. The per-unit columns are ratios, so average them and do not add them up.
Tables: `MA_DEAL`.
**Deal count and total consideration by announcement year**
```sql
SELECT YEAR(d.ANNOUNCE_DT) AS announce_year,
COUNT(*) AS deal_count,
SUM(d.TOTAL_CONSIDERATION_USD_MM) AS total_consideration_usd_mm,
MEDIAN(d.TOTAL_CONSIDERATION_USD_MM) AS median_consideration_usd_mm
FROM NOVI_MA_INTEL.MA_DEAL d
WHERE d.ANNOUNCE_DT IS NOT NULL
GROUP BY announce_year
ORDER BY announce_year
```
**Median price per flowing barrel and per net acre, by year and commodity**
```sql
SELECT YEAR(d.ANNOUNCE_DT) AS announce_year,
d.COMMODITY,
COUNT(d.CONSIDERATION_PER_FLOWING_BOE_D_USD) AS deals_with_flowing_metric,
MEDIAN(d.CONSIDERATION_PER_FLOWING_BOE_D_USD) AS median_usd_per_boe_d,
MEDIAN(d.CONSIDERATION_PER_NET_ACRE_USD) AS median_usd_per_net_acre
FROM NOVI_MA_INTEL.MA_DEAL d
WHERE d.ANNOUNCE_DT IS NOT NULL
GROUP BY announce_year, d.COMMODITY
ORDER BY announce_year, d.COMMODITY
```
**How the consideration was paid. The four parts add up to the total; NULL means the deal had no such part**
```sql
SELECT d.ANNOUNCE_DT, d.DEAL_DESCRIPTION,
d.TOTAL_CONSIDERATION_USD_MM,
d.CASH_USD_MM, d.ISSUED_EQUITY_USD_MM, d.DEBT_ASSUMED_USD_MM, d.OTHER_CONSIDERATION_USD_MM
FROM NOVI_MA_INTEL.MA_DEAL d
WHERE d.TOTAL_CONSIDERATION_USD_MM >= 1000
ORDER BY d.TOTAL_CONSIDERATION_USD_MM DESC
```
## 5. Valuation
Novi's valuation of a deal: how the price divides between producing wells (PDP), undeveloped locations (PUD) and other assets, and the assumptions behind it. A column is empty where Novi has no figure for the deal.
Tables: `MA_DEAL`, `MA_DEAL_VALUATION`.
**Price allocation and implied value per location for the largest valued deals**
```sql
SELECT d.ANNOUNCE_DT, d.DEAL_DESCRIPTION,
d.TOTAL_CONSIDERATION_USD_MM,
v.PDP_PV10_USD_MM,
v.ALLOCATED_VALUE_PDP_USD_MM,
v.ALLOCATED_VALUE_PUD_USD_MM,
v.ALLOCATED_VALUE_OTHER_USD_MM,
v.REMAINING_LOCATIONS_NET,
v.IMPLIED_VALUE_PER_LOCATION_USD_MM
FROM NOVI_MA_INTEL.MA_DEAL d
JOIN NOVI_MA_INTEL.MA_DEAL_VALUATION v ON v.MA_DEAL_KEY = d.MA_DEAL_KEY
WHERE v.PDP_PV10_USD_MM IS NOT NULL
ORDER BY d.TOTAL_CONSIDERATION_USD_MM DESC NULLS LAST
LIMIT 50
```
**The price and cost assumptions of each valuation. Read LEASE_OPERATING_EXPENSE and GPTM together with OPEX_UNITS**
```sql
SELECT d.ANNOUNCE_DT, d.DEAL_DESCRIPTION,
v.PRICING_BASIS, v.STRIP_DATE,
v.ASSUMED_OIL_PRICE_USD_BBL, v.ASSUMED_GAS_PRICE_USD_MCF,
v.OPEX_UNITS, v.LEASE_OPERATING_EXPENSE, v.GPTM,
v.IMPLIED_PDP_DISCOUNT_RATE,
v.PDP_VALUE_SOURCE
FROM NOVI_MA_INTEL.MA_DEAL d
JOIN NOVI_MA_INTEL.MA_DEAL_VALUATION v ON v.MA_DEAL_KEY = d.MA_DEAL_KEY
WHERE v.PRICING_BASIS IS NOT NULL
ORDER BY d.ANNOUNCE_DT DESC
```
## 6. Sponsors and advisors
The parties behind the principals. A SPONSOR row is the owner or backer of one side, and an ADVISOR row is a firm that side engaged. DEAL_SIDE on these rows is the side they stand behind.
Tables: `MA_DEAL`, `MA_DEAL_PARTY`, `PARTY`.
**Sponsors by number of deals, split by the side they backed**
```sql
SELECT p.PARTY_NAME AS sponsor,
COUNT(DISTINCT CASE WHEN dp.DEAL_SIDE = 'BUYER' THEN dp.MA_DEAL_KEY END) AS deals_backing_buyer,
COUNT(DISTINCT CASE WHEN dp.DEAL_SIDE = 'SELLER' THEN dp.MA_DEAL_KEY END) AS deals_backing_seller
FROM NOVI_MA_INTEL.MA_DEAL_PARTY dp
JOIN NOVI_MA_INTEL.PARTY p ON p.PARTY_KEY = dp.PARTY_KEY
WHERE dp.ROLE = 'SPONSOR'
GROUP BY p.PARTY_NAME
ORDER BY deals_backing_buyer + deals_backing_seller DESC
LIMIT 25
```
**Sales by sellers that private equity owned, by year**
```sql
SELECT YEAR(d.ANNOUNCE_DT) AS announce_year,
COUNT(DISTINCT d.MA_DEAL_KEY) AS deal_count
FROM NOVI_MA_INTEL.MA_DEAL d
JOIN NOVI_MA_INTEL.MA_DEAL_PARTY dp ON dp.MA_DEAL_KEY = d.MA_DEAL_KEY
WHERE dp.ROLE = 'PRINCIPAL'
AND dp.DEAL_SIDE = 'SELLER'
AND dp.PRIVATE_TYPE = 'PRIVATE_EQUITY'
GROUP BY announce_year
ORDER BY announce_year
```
**Financial and legal advisors by number of deals**
```sql
SELECT dp.ROLE, p.PARTY_NAME AS advisor, COUNT(DISTINCT dp.MA_DEAL_KEY) AS deal_count
FROM NOVI_MA_INTEL.MA_DEAL_PARTY dp
JOIN NOVI_MA_INTEL.PARTY p ON p.PARTY_KEY = dp.PARTY_KEY
WHERE dp.ROLE IN ('ADVISOR_FINANCIAL', 'ADVISOR_LEGAL')
GROUP BY dp.ROLE, p.PARTY_NAME
ORDER BY deal_count DESC
LIMIT 25
```
## 7. Public company deals
Public buyers and sellers. The ticker, share price, market capitalization and enterprise value are on the principal's MA_DEAL_PARTY row, as they were before the deal was announced.
Tables: `MA_DEAL`, `MA_DEAL_PARTY`.
**Public buyers: deal size against the buyer's own size**
```sql
SELECT d.ANNOUNCE_DT, dp.PARTY_NAME_REPORTED AS buyer, dp.TICKER,
d.TOTAL_CONSIDERATION_USD_MM,
dp.MARKET_CAP_USD_MM, dp.ENTERPRISE_VALUE_USD_MM,
d.DEAL_PRICE_TO_BUYER_EV
FROM NOVI_MA_INTEL.MA_DEAL d
JOIN NOVI_MA_INTEL.MA_DEAL_PARTY dp ON dp.MA_DEAL_KEY = d.MA_DEAL_KEY
WHERE dp.ROLE = 'PRINCIPAL'
AND dp.DEAL_SIDE = 'BUYER'
AND dp.IS_PUBLIC
ORDER BY d.ANNOUNCE_DT DESC
```
**Take-outs of public companies, with the premium paid. Premiums are fractions: 0.15 means 15%**
```sql
SELECT d.ANNOUNCE_DT, dp.PARTY_NAME_REPORTED AS seller, dp.TICKER,
d.TOTAL_CONSIDERATION_USD_MM, d.EQUITY_PREMIUM, d.EV_PREMIUM
FROM NOVI_MA_INTEL.MA_DEAL d
JOIN NOVI_MA_INTEL.MA_DEAL_PARTY dp ON dp.MA_DEAL_KEY = d.MA_DEAL_KEY
WHERE dp.ROLE = 'PRINCIPAL'
AND dp.DEAL_SIDE = 'SELLER'
AND d.ASSET_OR_CORPORATE = 'CORPORATE'
AND d.EQUITY_PREMIUM IS NOT NULL
ORDER BY d.ANNOUNCE_DT DESC
```
## 8. States types and tags
Filter by deal structure, and read the list columns. STATES, CONSIDERATION_TYPE and DEAL_ASSET_TAGS hold a list of values per deal. Use. ARRAY_CONTAINS to test for one value and LATERAL FLATTEN to get one row per value.
Tables: `MA_DEAL`.
**Deals by type, scope and structure**
```sql
SELECT d.DEAL_TYPE, d.ASSET_OR_CORPORATE, d.DEAL_STRUCTURE_TAG, COUNT(*) AS deal_count
FROM NOVI_MA_INTEL.MA_DEAL d
GROUP BY d.DEAL_TYPE, d.ASSET_OR_CORPORATE, d.DEAL_STRUCTURE_TAG
ORDER BY deal_count DESC
```
**Deals that list Texas**
```sql
SELECT d.ANNOUNCE_DT, d.DEAL_DESCRIPTION, d.STATES
FROM NOVI_MA_INTEL.MA_DEAL d
WHERE ARRAY_CONTAINS('TX'::VARIANT, d.STATES)
ORDER BY d.ANNOUNCE_DT DESC
```
**Number of deals per state. A deal that lists two states counts once in each**
```sql
SELECT s.VALUE::STRING AS state, COUNT(DISTINCT d.MA_DEAL_KEY) AS deal_count
FROM NOVI_MA_INTEL.MA_DEAL d,
LATERAL FLATTEN(INPUT => d.STATES) s
GROUP BY state
ORDER BY deal_count DESC
```
**Mineral and royalty deals that include stock in the consideration**
```sql
SELECT d.ANNOUNCE_DT, d.DEAL_DESCRIPTION, d.CONSIDERATION_TYPE, d.NET_ROYALTY_ACRES
FROM NOVI_MA_INTEL.MA_DEAL d
WHERE ARRAY_CONTAINS('MINERAL_ROYALTY'::VARIANT, d.DEAL_ASSET_TAGS)
AND ARRAY_CONTAINS('STOCK'::VARIANT, d.CONSIDERATION_TYPE)
ORDER BY d.ANNOUNCE_DT DESC
```
## 9. Linked deals and comments
Deals recorded as parts of one package, and the analyst's comments on a deal. DEAL_GROUP_KEY is the same on every deal of a package and NULL on a deal that stands alone. A comment belongs to one field of a deal, and. WORKSHEET_COLUMN_LABEL names that field.
Tables: `MA_DEAL`, `MA_DEAL_COMMENT`.
**Packages of linked deals, with the number of deals in each**
```sql
SELECT d.DEAL_GROUP_KEY,
COUNT(*) AS deals_in_package,
MIN(d.ANNOUNCE_DT) AS first_announced,
SUM(d.TOTAL_CONSIDERATION_USD_MM) AS package_consideration_usd_mm
FROM NOVI_MA_INTEL.MA_DEAL d
WHERE d.DEAL_GROUP_KEY IS NOT NULL
GROUP BY d.DEAL_GROUP_KEY
ORDER BY first_announced DESC
```
**Comments on the most recent deals**
```sql
SELECT d.ANNOUNCE_DT, d.DEAL_DESCRIPTION, c.WORKSHEET_COLUMN_LABEL, c.COMMENT_TEXT
FROM NOVI_MA_INTEL.MA_DEAL_COMMENT c
JOIN NOVI_MA_INTEL.MA_DEAL d ON d.MA_DEAL_KEY = c.MA_DEAL_KEY
ORDER BY d.ANNOUNCE_DT DESC, c.WORKSHEET_COLUMN_LABEL
LIMIT 100
```
## 10. Novi deal documents
Novi's own written analysis of a deal. MA_DOCUMENT has one row per document, and MA_DEAL_DOCUMENT links a document to each deal it covers. One document can cover several deals. DOWNLOAD_URL is a link that downloads the file of a document. At this time, only Novi research has a file: the views do not hold press releases or other documents from third parties.
Tables: `MA_DEAL`, `MA_DEAL_DOCUMENT`, `MA_DOCUMENT`.
**Deals that have a Novi document, newest first**
```sql
SELECT d.ANNOUNCE_DT, d.DEAL_DESCRIPTION,
doc.DOCUMENT_TYPE, doc.TITLE, doc.PUBLISHED_DATE, doc.PAGE_COUNT,
dd.PAGE_NUMBER
FROM NOVI_MA_INTEL.MA_DEAL d
JOIN NOVI_MA_INTEL.MA_DEAL_DOCUMENT dd ON dd.MA_DEAL_KEY = d.MA_DEAL_KEY
JOIN NOVI_MA_INTEL.MA_DOCUMENT doc ON doc.MA_DOCUMENT_KEY = dd.MA_DOCUMENT_KEY
ORDER BY d.ANNOUNCE_DT DESC
```
**Download links for Novi research. Snowflake makes each link when the query**
runs, and the link stops working 24 hours later; run the query again for a new link. DOWNLOAD_URL is NULL while a new document's file is not ready.
```sql
SELECT doc.TITLE, doc.PUBLISHED_DATE, doc.PAGE_COUNT, doc.SIZE_BYTES, doc.DOWNLOAD_URL
FROM NOVI_MA_INTEL.MA_DOCUMENT doc
WHERE doc.DOWNLOAD_URL IS NOT NULL
ORDER BY doc.PUBLISHED_DATE DESC NULLS LAST, doc.TITLE
```
## In the notebook only
These recipes are in the full cookbook your welcome email points to, not on this page:
- Cookbook recipe 3: Buyers and sellers
---
# Agents and MCP
Source: https://developers.novilabs.com/ai/
> Every Novi MCP server, the Claude skill, and how this site serves its docs to agents.
Connect Claude or another assistant to Novi Forecasts, EVA and M&A Intelligence. Each MCP server acts as you, with your permissions, and sees only what your account can see.
## MCP servers
| Server | URL | Sign-in | Permissions | Tools | Status |
| --- | --- | --- | --- | --- | --- |
| [Novi Forecasts](https://developers.novilabs.com/forecasts/mcp/) | `https://.novilabs.io/forecasts/api/mcp` | Novi sign-in, or a Novi API token | Access Forecasts. Access MCP to sign in | 25 tools and 2 resources | [Preview] |
| [Novi EVA](https://developers.novilabs.com/eva/mcp/) | `https://.novilabs.io/eva/api/mcp` | Novi sign-in only | Access EVA and Access MCP | 13 read-only tools | [Preview] |
| [Novi M&A Intelligence](https://developers.novilabs.com/ma/mcp/) | `https://.novilabs.io/intelligence-ma/api/mcp` | Novi sign-in, or a Novi API token | Access Intelligence M&A. Access MCP to sign in | 10 tools; 8 on your company host today | [Preview] |
`.novilabs.io` is the host you use for Novi apps in the browser. The Forecasts and EVA servers are in preview and not yet available on company hosts. See [Connect an assistant](https://developers.novilabs.com/ai/connect/).
### What each server does
| Server | Tools cover | Writes |
| --- | --- | --- |
| Novi Forecasts | Dataset and model cards, existing wells and type curves, forecasts for drawn wells, layouts over units and leases, plans, exports, economics and forecast comparisons | Starts plans and exports. Saves a forecast source only after asking you. Never deletes |
| Novi EVA | Column search and definitions, value lookup, grouping and benchmarks, well rows, radius filters, production charts, well maps | None. Every tool is read-only |
| Novi M&A Intelligence | Search, filter and summarize upstream M&A deals, look up filter values, read one deal, chart and tabulate deals | Keeps your own comps basket of up to 50 deals |
In clients that support MCP Apps, such as Claude, EVA charts and maps and M&A Intelligence charts and tables draw inline. Other clients get the data as JSON text, and EVA adds a PNG of each chart.
## Claude skill
[Available]
The `novi-forecasts` skill teaches Claude Code when to use each Forecasts tool, the conventions every answer follows and how to chart results. Without the MCP server it answers from an export zip, or calls the REST API with your token. Download and install: [MCP server and Claude skill](https://developers.novilabs.com/forecasts/mcp/).
## Docs for agents
| Feature | What it does |
| --- | --- |
| Markdown copy of every page | Add `.md` to a page path, for example `/start/authentication.md` |
| [`/llms.txt`](https://developers.novilabs.com/llms.txt) | An index of every page with its one-line summary, plus links to the OpenAPI documents |
| [`/llms-full.txt`](https://developers.novilabs.com/llms-full.txt) | Every page in one file |
| **Copy as Markdown** | Copies the page's Markdown to your clipboard |
| **View Markdown** | Opens the page's Markdown copy |
| **Open in Claude** | Opens a Claude chat that starts from the page's Markdown address |
| OpenAPI documents | [Forecasts](https://developers.novilabs.com/openapi/forecasts.json) and [EVA](https://developers.novilabs.com/openapi/eva.json), for code generators and agents |
The buttons sit under every page title. A docs MCP server is [Planned].
## Next
- [Connect an assistant](https://developers.novilabs.com/ai/connect/): Which clients each server supports, and how to add one.
- [Agent patterns](https://developers.novilabs.com/ai/patterns/): Search, describe, fetch; page with cursors; keep bulk data out of the model.
---
# Connect an assistant
Source: https://developers.novilabs.com/ai/connect/
> Which assistants each Novi MCP server supports today, and how to add one in Claude, Claude Code or Codex.
Add a Novi MCP server to your assistant with one URL. The assistant then signs you in through Novi, or sends a Novi API token where the server takes one.
## Which clients each server supports
| Client | Novi Forecasts | Novi EVA | Novi M&A Intelligence |
| --- | --- | --- | --- |
| Claude (claude.ai and Claude Desktop), custom connector with Novi sign-in | Supported | Supported | Supported |
| Claude Code, Novi sign-in | Supported | Supported | Supported |
| OpenAI Codex, Novi sign-in | Supported | Supported | Supported |
| Any client that sends a Novi API token in an `Authorization` header | Supported | Not supported | Supported |
| Claude Desktop extension `novi-forecasts.mcpb` | Supported | Not supported | Not supported |
| Any other client signing in | Not available yet | Not available yet | Not available yet |
An unsupported client sees: "Novi doesn't recognise the app that sent you here, so it can't connect to your account."
## Before you start
- **Your company host.** Use the host you use for Novi apps in the browser, in the server URL below.
- **Permissions.** Signing in needs **Access MCP** plus the product's own permission: Access Forecasts, Access EVA or Access Intelligence M&A. Your company's Novi administrator grants them.
- **A token, if you skip sign-in.** Forecasts and M&A Intelligence also take a Novi API token. See [Authentication](https://developers.novilabs.com/start/authentication/#novi-api-token).
## Add a server
| Server | URL |
| --- | --- |
| Novi Forecasts | `https://.novilabs.io/forecasts/api/mcp` |
| Novi EVA | `https://.novilabs.io/eva/api/mcp` |
| Novi M&A Intelligence | `https://.novilabs.io/intelligence-ma/api/mcp` |
The Forecasts and EVA servers are in preview and not yet available on company hosts. Tools and permissions per server: [Agents and MCP](https://developers.novilabs.com/ai/#mcp-servers).
**Claude**
Add a custom connector with the server URL, connect, sign in with your Novi login and approve Novi's [consent page](https://developers.novilabs.com/start/authentication/#novi-sign-in-for-assistants). On a Claude Team or Enterprise plan, an owner adds the connector first.
Step-by-step screens: [Connect Claude to EVA](https://developers.novilabs.com/eva/connect-claude/) and [Forecasts MCP server](https://developers.novilabs.com/forecasts/mcp/).
**Claude Code**
Add the servers you use, then run `/mcp` in Claude Code and sign in. If no browser opens, copy the URL Claude Code prints.
```bash
claude mcp add --transport http novi-forecasts https://.novilabs.io/forecasts/api/mcp
claude mcp add --transport http novi-eva https://.novilabs.io/eva/api/mcp
claude mcp add --transport http novi-ma https://.novilabs.io/intelligence-ma/api/mcp
```
To send a Novi API token instead of signing in (Forecasts and M&A Intelligence only):
```bash
claude mcp add --transport http novi-forecasts https://.novilabs.io/forecasts/api/mcp \
--header "Authorization: Bearer "
```
**Codex**
Add the server URL as a remote MCP server in Codex and complete the Novi sign-in. Novi shows the same consent page.
## After you connect
| What happens | What to do |
| --- | --- |
| The sign-in ends after 30 days | Sign in again when the assistant asks |
| Your administrator removes Access MCP or the product permission | Access stops. Ask your administrator |
| The sign-in expired or was revoked | The assistant asks you to sign in again |
| A call fails because Novi could not check your sign-in just then | Retry. You stay signed in |
A sign-in works only for that product, at your company, through its MCP server. It does not work on Novi's REST APIs.
> **Note:**
> Only the clients above can sign in today, so your own agent cannot sign in yet. Use a Novi API token on Forecasts or M&A Intelligence, or the [EVA REST API](https://developers.novilabs.com/eva/api/) for scripts. Sign-in for other clients is [Planned].
---
# Agent patterns
Source: https://developers.novilabs.com/ai/patterns/
> Habits that get correct, cheap answers from Novi's MCP servers, grounded in the tools they offer.
## Start from the guide
Read the server's description of its data before the first query.
| Server | First call |
| --- | --- |
| Novi Forecasts | `describe_dataset`: basin, formations, as-of date, models and what they can do. `get_conventions` for units, BOE and P-levels |
| Novi EVA | `get_data_guide` for a topic (`querying`, `units`, `percentiles`, `production`, `forecasts`, `benchmarking`). `get_chart_guide` and `get_map_guide` before charts and maps |
| Novi M&A Intelligence | `ma_filter_values` before guessing a filter value |
## Search, then describe, then fetch
Find exact names before you filter on them. A guessed name fails or matches the wrong thing.
| Step | Novi EVA | Novi Forecasts | Novi M&A Intelligence |
| --- | --- | --- | --- |
| Search | `search_columns` for column references. `resolve_values` for exact stored values, such as `Reeves` to `Reeves, TX` | `find_wells`, `well_facets` | `ma_search_deals` from a sentence |
| Describe | `describe_columns`: units, definitions, supported operations | `model_card` | `ma_filter_values` |
| Fetch | `group_by` for counts and measures, `fetch_data` for well rows | `get_well`, `forecast_wells`, `get_plan` | `ma_filter_deals`, `ma_get_deal` |
When `resolve_values` returns several matches, ask the person.
## Let the server aggregate
Ask for the number, not the rows. Server totals cover the whole cohort; a page of rows does not.
- EVA `group_by` computes counts, sums, averages and medians over every matching well. Do not compute statistics from a truncated `fetch_data` page.
- EVA `group_by` with `benchmark: {}` ranks per-foot productivity in one call.
- M&A Intelligence `ma_summarize_deals` answers "how much" over a filter in one call, with the count of deals each figure covers.
- Forecasts `get_plan` returns a plan's totals per design, pad and zone.
## Page with cursors
EVA `fetch_data` and Forecasts lists page by cursor; M&A Intelligence pages with `limit` and `offset`. Page sizes and
cursor rules: [Pagination](https://developers.novilabs.com/platform/pagination/).
## Keep bulk data out of the model
- Forecasts `export_plan` writes a done plan to files and returns a download link. The Claude skill can then answer from the export zip.
- EVA caps a data tool result at 64 KiB and returns `LIMIT_EXCEEDED` past it. Narrow the filter or ask for fewer columns.
- EVA `get_chart` takes `include_series: false` and `include_png: false` when only the summary is needed.
- For a whole basin's rows, use [Novi UDM Data](https://developers.novilabs.com/data/delivery/) or [EVA REST](https://developers.novilabs.com/eva/api/), not an agent.
## Read-only by default
| Server | What tools can change |
| --- | --- |
| Novi EVA | Nothing. Every tool is read-only |
| Novi Forecasts | Tools read, or start a plan or an export. `save_forecast_source` saves only after asking you. No tool deletes |
| Novi M&A Intelligence | Only your own comps basket, up to 50 deals |
The Claude skill may call the Forecasts REST API directly, with reads and the documented `POST` calls, never `DELETE`.
## Check what came back
- EVA data results carry `truncated`, `warnings`, `coverage` and `freshness`. Check `truncated` and `warnings` before you rely on a result.
- An EVA `DEPENDENCY_ERROR` is a failed read, never zero production. Report it as an error.
- Do not retry an EVA `ACCESS_DENIED` with guessed columns. Tell the person what is outside their subscription.
- An unknown basin in M&A Intelligence is an error that lists the valid names, not an empty result.
## State the basis
Say which units, window and convention a number uses. In EVA, a bare year means production vintage, and hybrid units are the default. P10 means Low in Forecasts and High in EVA charts: name the case. See [Units and conventions](https://developers.novilabs.com/concepts/units-and-conventions/) and [P-levels](https://developers.novilabs.com/concepts/p-levels/).
---
# Platform
Source: https://developers.novilabs.com/platform/
> Versioning, errors, pagination, limits, support and security across Novi products.
Each page here compares Novi UDM Data (v4), the Novi Forecasts API, the Novi EVA API and the MCP servers in one table. Where a product publishes nothing yet, the table says so.
- [Versioning](https://developers.novilabs.com/platform/versioning/): Novi's version policy and how each product versions today.
- [Errors](https://developers.novilabs.com/platform/errors/): Error shapes and status codes per product.
- [Pagination](https://developers.novilabs.com/platform/pagination/): Cursors, partitions and batch sizes per product.
- [Rate limits](https://developers.novilabs.com/platform/rate-limits/): Request rates, concurrency and size limits per product.
- [Status and support](https://developers.novilabs.com/platform/status-and-support/): How to reach Novi and what to send.
- [Security](https://developers.novilabs.com/platform/security/): Token handling, least privilege and data scope.
---
# Versioning
Source: https://developers.novilabs.com/platform/versioning/
> Novi's API version policy, and how Novi UDM Data, the Forecasts API, the EVA API and the MCP servers version today.
## Novi's version policy
Novi supports up to three API versions at a time.
| Status | Meaning |
| --- | --- |
| Primary | The actively maintained, fully supported version, including the API and the bulk export. It gets ongoing updates and enhancements. Existing attributes may change through bug fixes, improved logic or deprecation, but are not removed |
| Deprecated | The previous version once a newer one is published. Available for one year and still receives updated data. Bug fixes are not guaranteed and no enhancements are made |
| Future | A beta version that customers may use early |
Today only Novi's well data has more than one API version, v3 and v4: see [Releases and versioning](https://developers.novilabs.com/data/releases/#api-versions).
## How each product versions
| Product | Versions | How changes ship | How to see your version |
| --- | --- | --- | --- |
| Novi UDM Data (v4) | v4, in Snowflake. v3, the REST API at `/api/v3` and its bulk export | Novi release numbers, such as 26.4.3. Columns change through fixes, improved logic or deprecation. A deprecated column stays in its view and says what to use instead | The data dictionary and [Releases and versioning](https://developers.novilabs.com/data/releases/) |
| Novi Forecasts API | `/api/v1` | Semver API version. Changes are additive and opt-in; some releases tighten validation. A breaking change would be a new major version under a new path; none is planned | `GET /health`: `version` and `app_version` |
| Novi EVA API | `/v1` | Not published yet | Not published yet |
| MCP servers [Preview] | One version per server | Hosted tools update for you. The Forecasts Desktop extension says when a newer version is out | EVA data results carry `schema_version` |
## Novi Forecasts API
- `/api/v1` only grows: additions are opt-in. Fixes that tighten validation can turn a loosely accepted request into an invalid-input error.
- The API version is semver: a minor step when the OpenAPI document changes, at least a patch step for any other contract change. One API version can span several platform releases.
- A breaking change would be a new major version under a new path; none is planned.
- Your host serves the OpenAPI 3.1 document it runs at `GET /openapi.json`.
## Deprecation signals
| Item | Status |
| --- | --- |
| `Deprecation` and `Sunset` response headers on deprecated versions and endpoints | [Planned] |
---
# Errors
Source: https://developers.novilabs.com/platform/errors/
> The error shape, status codes and request ids of each Novi product, and what to do about common errors.
Each product returns errors in its own shape today.
## At a glance
| Product | Error shape | Request id |
| --- | --- | --- |
| Novi UDM Data over HTTPS | Snowflake's SQL API responses | Snowflake's `statementHandle` |
| Novi Forecasts API | `{"error": {"code", "message", "details"}, "request_id"}` | `X-Request-Id` header and `request_id` |
| Novi EVA REST API | `{"error": ""}` | Not published yet |
| Novi EVA MCP server | Tool error `{"code", "message", "retryable", "field"}` | Not published yet |
| Novi M&A Intelligence MCP server | A tool result whose message names the cause | Not published yet |
| Novi sign-in on company hosts | `401` or `403`. On the Forecasts API the `401` body is `{"code": 401, "message": "Unauthorized"}` | None |
## Novi UDM Data (v4)
Over HTTPS, Novi UDM Data answers through Snowflake's SQL API. A statement still running answers `202`; check it with `GET /api/v2/statements/`. A failed statement answers `422`. Snowflake documents both at docs.snowflake.com/en/developer-guide/sql-api/handling-responses.
| What you see | Cause | Do |
| --- | --- | --- |
| A permission error on a view, on your own Snowflake account | The role lacks Novi's database role | Your administrator grants `DR_WELLS_STANDARD` or `DR_WELLS_FULL` to that role |
| `CREATE DATABASE` fails in the setup script | Outside AWS us-east-2, the listing can take a few hours to appear the first time | Wait and run the script again |
| The first query waits 10 to 30 seconds | The reader-account warehouse was idle | Nothing. Later queries run at once |
| A statement stops after 2 hours | The time limit on a BI or lakehouse connection | Narrow the query |
## Novi Forecasts API
```json
{
"error": {
"code": "invalid_argument",
"message": "wells[0].tvd isn't a known field; did you mean tvd_ft?",
"details": { "field": "wells[0].tvd" }
},
"request_id": "3c9d1e7a-2b4f-4a6c-9d8e-7f1a2b3c4d5e"
}
```
| Status | `code` |
| --- | --- |
| `400`, `401`, `403`, `405`, `413`, `416` | `invalid_argument` |
| `404`, `410` | `not_found` |
| `409`, `429` | `conflict` |
| `500`, `502` | `internal` |
| `503` | `unavailable` |
`details.field` names the input at fault. A sign-in made for an MCP client gets `403` on the REST API. Full table and what to do: [Errors and limits](https://developers.novilabs.com/forecasts/guides/errors-and-limits/).
## Novi EVA REST API
| Status | Body |
| --- | --- |
| `401`, no key | `{"error": "Missing x-api-key header"}` |
| `401`, invalid key | `{"error": "Invalid API key"}` |
| `400`, too many wells | `{"error": "Too many wells requested. Limited to 50,000 at a time."}` on `POST /v1/data` |
In a result, `"n/a"` means a value is not available and `"Subscription Required"` means your subscription does not include it. Neither is an error.
## Novi EVA MCP server
| Code | Retry |
| --- | --- |
| `LIMIT_EXCEEDED` | When `retryable` is true; otherwise narrow the request |
| `DEADLINE_EXCEEDED` | Yes, or narrow the filter |
| `DEPENDENCY_ERROR` | Later. A failed read is never reported as zero |
| `INVALID_CURSOR` | Start again without a cursor |
| `VALIDATION_ERROR` | No. Fix the input `field` names |
| `UNSUPPORTED_OPERATION` | No. Check what `describe_columns` lists |
| `ACCESS_DENIED` | No. Do not retry with guessed columns |
Details: [EVA MCP server, errors](https://developers.novilabs.com/eva/mcp/).
## Novi sign-in
These apply to every product on a Novi company host.
| Status | Means | Do |
| --- | --- | --- |
| `401` | No token, or one that expired or was revoked | Create a new token, or sign in again |
| `403` | The token is not valid for this path: wrong product, wrong company, a sign-in token on a REST API, or a missing permission | Use the right credential; ask your administrator for the permission |
| `503` | Novi could not check your token or sign-in just then | Retry |
## Planned
| Item | Status |
| --- | --- |
| One error format across APIs, RFC 9457 problem details | [Planned] |
---
# Pagination
Source: https://developers.novilabs.com/platform/pagination/
> How each Novi product splits large results, page sizes, and how to pull only what changed.
## At a glance
| Product | How it pages | Page size | End of results |
| --- | --- | --- | --- |
| Novi UDM Data over HTTPS | Snowflake returns results in partitions. The first comes with the response; fetch the rest with `GET /api/v2/statements/?partition=` | Set by Snowflake. `resultSetMetaData.partitionInfo` lists each partition's rows and size | The last partition listed in `partitionInfo` |
| Novi Forecasts API | `limit` and an opaque `cursor`. Pass `next_cursor` back with the same filters and sort | `GET /plans`: 1 to 100, default 20. `GET /plans/{id}/curves`: 1 to 200 wells, default 100 | `next_cursor` is `null` |
| Novi EVA REST API | No paging. Send wells in batches | `POST /v1/data`: up to 50,000 wells. `POST /v1/production`: up to 1,000 wells | One call. On `POST /v1/data`, wells come back in request order |
| Novi EVA MCP server | `fetch_data` returns `next_cursor`. Send every original input again with `cursor` set | `fetch_data`: default 100 rows, up to 500. `search_columns`: default 20, up to 50. `get_map_legend`: up to 200 | No `next_cursor` |
| Novi M&A Intelligence MCP server | `limit` and `offset` on `ma_search_deals` and `ma_table_deals` | Up to 100 rows | Not published yet |
## Novi UDM Data (v4)
In SQL you choose the rows: filter, aggregate and name only the columns you need. Over HTTPS, read the partitions as the table above shows. Snowflake documents them at docs.snowflake.com/en/developer-guide/sql-api/handling-responses.
For a full copy, use [bulk files](https://developers.novilabs.com/data/delivery/#bulk-files) instead of paging through queries.
## Novi Forecasts API
- On `GET /plans`, plans created or deleted between pages are neither skipped nor repeated.
- Curve pages carry an `ETag`. Send it back as `If-None-Match`: a Not Modified answer means nothing moved.
Details: [Jobs, waiting and retries](https://developers.novilabs.com/forecasts/guides/jobs-and-retries/).
## Novi EVA MCP server
- A cursor works only with the inputs it came from, for 10 minutes. Otherwise you get `INVALID_CURSOR`: start again without one.
- Pages are not a snapshot. Data can change between pages.
## Pull only what changed
| Product | How |
| --- | --- |
| Novi UDM Data (v4) | Bulk diff zips: apply each diff in `RUN_ID` order. `DOWNLOADS_DIFF` keeps the last 7 runs. In SQL, 22 of the 29 base views carry `UPDATED_AT` |
| Novi Forecasts API | `GET /plans` with `kept=true`, `status=done` and `updated_from`. See [Partner sync](https://developers.novilabs.com/forecasts/guides/partner-sync/) |
| Novi EVA API | Not published yet |
Forecasts lists never report removals: run a full list now and then to catch them. Novi UDM Data diff zips do carry deletes.
---
# Rate limits
Source: https://developers.novilabs.com/platform/rate-limits/
> Request rates, concurrency, size limits and back-off rules for each Novi product, as published today.
Only the EVA REST API publishes a request rate today; the others limit work by size, jobs in flight or warehouse.
## At a glance
| Product | Request rate | Work in flight | Size limits | Rate headers |
| --- | --- | --- | --- | --- |
| Novi UDM Data (v4) | Not published yet | Not published yet | Not published yet | Not published yet |
| Novi Forecasts API | Not published yet | Async forecasts: 50 per company. Plan economics: 4 per company. Exports: 20 per model set, 3 per plan. Your unfinished plan forecasts: `limits.plan_unfinished_forecasts` | 50 drawn wells per `POST /forecasts`. Bodies: 64 MB on `POST /plans`, 10 MB on `POST /exports` | `Retry-After` only, when a job cap is reached |
| Novi EVA REST API | 10 requests per second on average, bursts up to 30 | 5 requests | 50,000 wells per `POST /v1/data`, 1,000 per `POST /v1/production` | Not published yet |
| Novi EVA MCP server | Not published yet | A few data tool calls at a time per person; more wait briefly | Request body 1 MiB. Data tool result 64 KiB. Chart result 256 KiB. 30-second deadline per data tool call | Not published yet |
| Novi M&A Intelligence MCP server | `ma_search_deals` is rate limited per person; the value is not published yet | Not published yet | 100 rows per page; 50 deals in your basket | Not published yet |
## Novi UDM Data (v4)
Your queries run on a Snowflake warehouse, so compute, not a request count, sets the pace.
- In a reader account, the first query after about a minute idle takes 10 to 30 seconds to start. The same SQL run again within 24 hours returns at once.
- On your own Snowflake account, your warehouse runs the queries and you pay for it.
- On a BI or lakehouse connection, statements stop after 2 hours.
## Novi Forecasts API
`GET /dataset` `limits` and `GET /export-formats` `limits` report most limits: read them rather than hard-coding values. Every limit and how to back off: [Errors and limits](https://developers.novilabs.com/forecasts/guides/errors-and-limits/).
## Novi EVA
- **REST:** stay under 10 requests per second and 5 in flight. Batch wells into one call instead of many small ones.
- **MCP:** `LIMIT_EXCEEDED` and `DEADLINE_EXCEEDED` are retryable. Wait, then retry, or narrow the request.
## Planned
| Item | Status |
| --- | --- |
| `RateLimit` and `RateLimit-Policy` headers, so a client can pace itself | [Planned] |
| Published request rates and concurrency for Novi UDM Data over HTTPS | [Planned] |
---
# Status and support
Source: https://developers.novilabs.com/platform/status-and-support/
> How to reach Novi about any product, what to put in a support request, and what never to send.
Email **support@novilabs.com** about any Novi product. For Novi UDM Data setup, you can also ask your Customer Success Advisor.
## What to include
| Include | Why | Where to find it |
| --- | --- | --- |
| Product and surface | Narrows where to look | For example: Novi UDM Data over HTTPS, Forecasts REST, EVA MCP |
| Your company host or Snowflake account | Identifies your company | The host in your browser, or `current_account()` in Snowflake |
| Request id | Finds the exact call | Forecasts: `X-Request-Id` or `request_id`. Novi UDM Data over HTTPS: Snowflake's `statementHandle` |
| Time, with time zone | Narrows the logs | Your client's log. UTC is best |
| The call | Shows what you sent | Method and path, or the SQL. Remove credentials first |
| What came back | Shows what went wrong | The status code and error body |
| Which credential type | Rules out the wrong credential | For example: Novi API token, Novi sign-in, EVA Developer API Token, Snowflake token |
> **Never send a secret:**
> Never send a token, key, password or private key, in email or anywhere else. Novi never needs one. To say which token, give its name.
If a credential leaks, revoke it first, then tell support.
## Self-check before you write
| What you see | Check |
| --- | --- |
| `401` on a Novi company host | Is the token expired or revoked? |
| `403` on the Forecasts API | Does your user have Access Forecasts? Is it a sign-in token used on the REST API? |
| `403` on an MCP server | Do you have Access MCP and the product's permission? Is the host your company's? |
| Permission error on a Novi UDM Data view | Has your administrator granted `DR_WELLS_STANDARD` or `DR_WELLS_FULL`? |
| `LIMIT_EXCEEDED` from EVA | Narrow the request, or wait and retry |
More: [Errors](https://developers.novilabs.com/platform/errors/).
## Status page
[Planned]
Novi does not publish a status page yet. Until it does, ask support@novilabs.com.
---
# Security
Source: https://developers.novilabs.com/platform/security/
> How to handle Novi credentials, keep access narrow, rotate, and what each product lets a token or agent see and change.
## Handle credentials
- Keep tokens and keys in an environment variable or a secret manager. Never in code, a URL, a shared notebook or a support email.
- Copy a credential when it is shown. Novi API tokens and Snowflake programmatic access tokens are shown once. A Novi UDM Data private key comes as a link that works for 72 hours, and Novi keeps no copy.
- Novi API tokens start with `novi_pat_`, so secret scanners can find one committed by mistake.
- Call the APIs from a server, script or notebook. Browser code on your own web pages can't call the Novi Forecasts API.
## Treat links as secrets too
| Link | Lifetime | Who can use it |
| --- | --- | --- |
| Novi UDM Data bulk file link | 2 hours. A download that has started continues | Anyone with the link |
| Forecasts export file, signed copy | 15 minutes | It works without credentials, so anyone with it can download |
| Novi UDM Data private key link | 72 hours | Not published yet. Treat it as a secret |
## Keep access narrow
| Product | What a credential can do |
| --- | --- |
| Novi UDM Data (v4) | A Snowflake role. Restrict a programmatic access token to one role with `ROLE_RESTRICTION` |
| Novi Forecasts API | A Novi API token acts as one person with that person's full access. No token can create or manage tokens |
| MCP sign-in | One product at your company, through its MCP server only. It does not work on other hosts, products or the REST APIs |
| Novi EVA REST API | The key acts for your EVA organization |
- **Access MCP** is its own permission. Your company's Novi administrator grants it through a role, and removing it cuts off every assistant sign-in.
- Read-only service tokens not tied to a person are [Planned].
## Rotate
| Credential | How |
| --- | --- |
| Novi API token | Pick a lifetime from 1 to 365 days. Create a new token, switch to it, then revoke the old one on the API tokens page. A revoked token stops working within two minutes |
| Snowflake programmatic access token | `ALTER USER REMOVE PROGRAMMATIC ACCESS TOKEN`, then `ADD` a new one with `DAYS_TO_EXPIRY` |
| MCP sign-in | Sign in again when the assistant asks |
| Key pair, EVA Developer API Token | Not published yet. Ask support@novilabs.com |
Details: [Authentication](https://developers.novilabs.com/start/authentication/).
## What agents can change
| MCP server | Tools that change anything |
| --- | --- |
| Novi EVA | None. Every tool is read-only |
| Novi Forecasts | Tools read, or start a plan or an export. `save_forecast_source` saves only after asking you. No tool deletes |
| Novi M&A Intelligence | Only your own comps basket |
## Your subscription applies on every channel
An API or an agent sees what your subscription covers, and no more.
- **Novi UDM Data:** every delivery path shows only the basins in your subscription. Views keyed by a well or wellbore filter rows for you.
- **Novi EVA REST:** a value outside your subscription comes back as `"Subscription Required"`.
- **Novi EVA MCP:** column search covers only columns you are licensed for. A request outside your subscription returns `ACCESS_DENIED`.
- **Novi Forecasts API:** each company's plans, exports and saved records are its own. Nothing you send can reach another company's records.
## Compliance
Novi Labs lists SOC 2 Type 2 on novilabs.com.
---
# Roadmap
Source: https://developers.novilabs.com/roadmap/
> Everything planned for the Novi developer platform, by product, with the reason each item belongs.
Nothing on this page is available yet.
## Novi UDM Data (v4)
| Item | What it gives you | Status |
| --- | --- | --- |
| Canadian wells in Novi UDM Data, keyed on `UWI-DLS` | North American coverage in one data model. Canada is on v3 today | [Planned] |
| US wellbores keyed on API14 | Per-lateral joins with operators' own data | [Planned] |
| A v3 to v4 field mapping guide | A column-by-column path from v3 | [Planned] |
| A "data as of" time and refresh cadence for every view | Know how fresh each table is | [Planned] |
| Published request rates and concurrency for Novi UDM Data over HTTPS | Published limits to plan against | [Planned] |
| GIS delivery as standard map layers (OGC or Esri) | GIS layers in your mapping tools | [Planned] |
| OpenSharing (formerly Delta Sharing) for recipients outside Snowflake | The same share for Databricks, pandas, Spark and Power BI users | [Planned] |
| An MCP server beside the Snowflake share | Agents query Novi UDM Data inside your own Snowflake account | [Planned] |
## Novi Forecasts API
| Item | What it gives you | Status |
| --- | --- | --- |
| Python and TypeScript SDKs | Typed clients in Python and TypeScript | [Planned] |
| Read-only service tokens not tied to a person | Least privilege for partners, pipelines and agents | [Planned] |
| Callbacks to your own receiver when a plan or an export finishes | Push instead of polling | [Planned] |
| Deletion records for sync | Partner tools catch removals without a periodic full list | [Planned] |
| Arps segments as JSON | Partner tools that import decline parameters, not volumes | [Planned] |
| `RateLimit` and `RateLimit-Policy` headers | Clients pace themselves | [Planned] |
| Arazzo workflow files for common jobs: find wells, run a forecast, export | Agents and code generators follow the documented sequence | [Planned] |
## Novi EVA API
| Item | What it gives you | Status |
| --- | --- | --- |
| The EVA MCP server on company hosts | Ask EVA questions from an assistant on your company host | [Planned] |
## All products
| Item | What it gives you | Status |
| --- | --- | --- |
| One export job method for every product: send a filter or an area, get a short-lived download link, with MCP as another caller | Large extracts without SQL, for agents and people who do not write SQL | [Planned] |
| Assistant sign-in for clients beyond Claude, Claude Code and Codex, including your own agents | Any MCP client, including your own agent, can connect | [Planned] |
| One error format, RFC 9457 problem details | One error parser for every Novi API | [Planned] |
| `Deprecation` and `Sunset` headers on deprecated versions and endpoints | Clients learn of retirements from the response itself | [Planned] |
| One sign-in and API token for every Novi API, including Novi UDM Data and the EVA REST API | One credential to manage across products | [Planned] |
| Shared conventions for P-levels, units, BOE and first-12-month measures across products | The same number means the same thing in every product. See [P-levels](https://developers.novilabs.com/concepts/p-levels/) and [Units and conventions](https://developers.novilabs.com/concepts/units-and-conventions/) | [Planned] |
| Forecasts data in the v4 data model | Forecasts in the same schema as Novi UDM Data | [Planned] |
| Alerts when new permits, spuds and completions land in an area you watch | Watch an area without polling | [Planned] |
| A status page | Live service status in one place | [Planned] |
| A sandbox with synthetic sample wells and a test token | Try the APIs before you sign | [Planned] |
| A try-it console against the sandbox | Run a call from the docs page | [Planned] |
| An API catalog at `/.well-known/api-catalog` (RFC 9727) | Agents and tools discover every Novi API and spec in one request | [Planned] |
| An MCP server card for each Novi MCP server | Clients read a server's address and protocol versions before they connect | [Planned] |
| An agent plugin that bundles the MCP servers and the Claude skill | One install for every Novi tool | [Planned] |
| A docs MCP server for this site | Agents search these docs directly | [Planned] |
Dates are not published. To ask about an item, email support@novilabs.com.