---
title: Well
slug: well
docTags:
createdAt: 2023-03-22T19:14:15.000Z
---
The Well table defines the well header — the well's identity, classification, and location. Every other dataset in the schema hangs off a well record. The well's **sourceId** must be globally unique, and its **uwi** must match the identifier used by your production allocation system.
| **Variable** | **Data Type** | **Unit of Measure** | **Is Nullable?** | **Default Value** | **Description** |
| ------------------- | ------------- | -------------------------- | ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| sourceId | String | - | No | - | Source ID for the well
**From WellView:** wvwellheader table, idwell column
**From OpenWells:** cd\_well table, well\_id column |
| uwi | String | - | No | - | Unique Well Identifier. This key links the well to daily production from your allocation system. |
| name | String | - | No | - | Well name |
| group1 | String | - | Yes | - | Well Group 1 (often field or asset) |
| group2 | String | - | Yes | - | Well Group 2 (often route or facility) |
| group3 | String | - | Yes | - | Well Group 3 (often pad or cluster) |
| type | String | - | No | PRODUCER | Well type:
PRODUCER
INJECTOR |
| fluid | String | - | No | OIL | Fluid type:
OIL
GAS
WATER
CONDENSATE |
| liftType | String | - | No | NATURAL\_FLOW | Artificial lift type:
NATURAL\_FLOW
ANNULAR\_NATURAL\_FLOW
DUAL\_NATURAL\_FLOW
GAS\_LIFT
ANNULAR\_GAS\_LIFT
PLUNGER\_LIFT
PLUNGER\_ASSISTED\_GAS\_LIFT
GAS\_ASSISTED\_PLUNGER\_LIFT
ROD\_PUMP
ESP
PCP |
| lat | Double | decimal degrees, WGS84 CRS | No | - | Surface latitude. Used for maps and to resolve the well's time zone. |
| lon | Double | decimal degrees, WGS84 CRS | No | - | Surface longitude. Used for maps and to resolve the well's time zone. |
| middleLat | Double | decimal degrees, WGS84 CRS | Yes | - | Optional middle latitude (for maps). Frequently the lateral heel coordinate. |
| middleLon | Double | decimal degrees, WGS84 CRS | Yes | - | Optional middle longitude (for maps). Frequently the lateral heel coordinate. |
| bottomholeLat | Double | decimal degrees, WGS84 CRS | Yes | - | Optional bottomhole latitude (for maps). Frequently the lateral toe coordinate. |
| bottomholeLon | Double | decimal degrees, WGS84 CRS | Yes | - | Optional bottomhole longitude (for maps). Frequently the lateral toe coordinate. |
| mudLine | Double | ft | Yes | - | Depth of the mud line for offshore wells. Null for onshore wells. |
| status | String | - | Yes | ACTIVE | Well status, used to exclude inactive wells from modeling and network optimization:
ACTIVE
INACTIVE
ABANDONED |
| area | String | - | Yes | - | Sub-area of the field/asset defined by group1 |
| centralFacility | String | - | Yes | - | Central facility into which the well flows |
| tankBattery | String | - | Yes | - | Tank battery into which the well flows |
| route | String | - | Yes | - | Route on which the well is located |
| pad | String | - | Yes | - | Pad (if applicable) on which the well is located |
| platform | String | - | Yes | - | Platform (if applicable) to which the well flows |
| responsibleEngineer | String | - | Yes | - | Engineer responsible for the well |
| heritage | String | - | Yes | - | Previous company that owned the well |
:::hint{type="info"}
**Grouping Fields: group1, group2, group3**
The group fields drive navigation and reporting. A well can be grouped at three levels, typically:
**Unconventional**
- group1 = Field
- group2 = Route
- group3 = Pad
**Conventional**
- group1 = Asset
- group2 = Facility
- group3 = Cluster
You decide which field from your source system maps to each level, and any level can be left empty. Whatever convention you choose, apply it consistently across all wells. The explicit metadata fields (area, centralFacility, tankBattery, route, pad, platform) can be used alongside the group fields for richer filtering.
:::
***
# Data Integrity Checks
| **Condition** | **Response** |
| ------------------------- | ------------------------------- |
| uwi is NULL or empty | Record Rejected |
| type is NULL or empty | Value defaults to PRODUCER |
| fluid is NULL or empty | Value defaults to OIL |
| liftType is NULL or empty | Value defaults to NATURAL\_FLOW |
***
# Common Error Messages
| **API** | **Scenario** | **Error Response** |
| ------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Add / Upsert a Well | UWI missing, too short/long, or has leading/trailing spaces | UWI length must be between 2 and 16 chars and cannot contain leading or trailing spaces |
| Fetch a Well | sourceId not found | Well with sourceId xxx does not exist |
| Fetch a Well | UWI not found | Well with uwi: xxx was not found |
| Delete a Well | sourceId not found | Well with sourceId: xxx was not found |