---
title: Wellbore Formation
slug: wellbore-formation
docTags:
createdAt: 2023-03-22T19:16:54.000Z
---
The Wellbore Formation table represents the rock and fluid properties of the subsurface reservoir (formation) from which fluids are produced. In most cases a wellbore produces from a single formation, but a wellbore can produce from two or more formations.
The unique constraint on wellbore formation entries is **sourceWellboreId + sourceId + startDate**.
:::hint{type="warning"}
The **Is Nullable?** column below reflects whether the API will accept or reject a record, to facilitate a streamlined data ingest process and subsequent validation / cleanup. Refer to the **Data Requirements for Modeling** section for a more precise summary of the data requirements for well modeling.
:::
:::hint{type="danger"}
Variables in red below will be deprecated in a future release and are no longer required
:::
| **Variable** | **Data Type** | **Unit of Measure** | **Is Nullable?** | **Default Value** | **Description** |
| ----------------------------- | --------------- | ------------------- | ---------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| sourceId | String | - | No | - | Unique source ID for the formation, to enable upserts. Commonly this matches the name. |
| sourceWellId | String | - | No | - | Must match the sourceId of a record in the [Well](docId\:P-xHbe4jqKJQemay7aOL5) table |
| sourceWellboreId | String | - | No | - | Must match the sourceId of a record in the [Wellbore](docId\:XPqwCAS8aWDaWyssmVjY6) table |
| startDate | Datetime Offset | - | Yes | 1900-01-01T00:00:00+0000 | Datetime the formation properties become applicable. Datetime offset (with timezone) in ISO 8601 format. Example: 2022-09-27T16:28:37+0000 |
| name | String | - | No | - | Name of the wellbore formation |
| allocationFactor | Double | decimal percent | Yes | 1.0 | Allocation of production assigned to this formation (0.0 - 1.0) |
| compressibilityRock | Double | 1/psi | Yes | 3E-6 | Formation rock compressibility |
| pressureFormationInitialDatum | Double | psia | No | - | Initial reservoir pressure |
| temperatureFormationDatum | Double | degF | No | - | Reservoir temperature |
| depth | Double | ft | No | - | Measured depth of the formation top |
| thicknessFormation | Double | ft | Yes | - | Thickness of the formation |
| porosity | Double | decimal percent | Yes | - | Porosity of the formation |
| saturationWaterInitial | Double | decimal percent | Yes | - | Initial water saturation |
| saturationGasInitial | Double | decimal percent | Yes | 0.0 | Initial gas saturation |
| saturationOilInitial | Double | decimal percent | Yes | - | Initial oil saturation |
| primaryFluidType | String | - | No | OIL | OIL
GAS
WATER |
| rsi | Double | scf/STB | No | - | Initial solution gas oil ratio |
| condensateGasRatio | Double | STB/scf | Yes | - | Condensate gas ratio |
| waterGasRatio | Double | STB/scf | Yes | - | Water gas ratio |
| originalGasInPlace | Double | scf | Yes | - | Estimated original gas in place |
| originalOilInPlace | Double | STB | Yes | - | Estimated original oil in place |
| volumeAcquiferInitial | Double | STB | Yes | - | Initial aquifer volume |
| fluidGravityApi | Double | API degrees | No | - | Oil API gravity |
| fluidGravityGas | Double | specific gravity | No | - | Gas specific gravity |
| fluidSalinityWater | Double | ppm | No | - | Water salinity |
| fluidComingledGOR | Double | scf/STB | Yes | - | Gas oil ratio of the co-mingled fluid in multi-wellbore wells |
| fluidMolarFracN2 | Double | decimal percent | Yes | 0.0 | Molar fraction N2 |
| fluidMolarFracCO2 | Double | decimal percent | Yes | 0.0 | Molar fraction CO2 |
| fluidMolarFracH2S | Double | decimal percent | Yes | 0.0 | Molar fraction H2S |
| langmuirPressure | Double | psig | Yes | - | Langmuir pressure (for coal seam gas reservoirs) |
| langmuirVolume | Double | scf/ft | Yes | - | Langmuir volume (for coal seam gas reservoirs) |
| initialGasContent | Double | scf/ft | Yes | - | Initial gas content (for coal seam gas reservoirs) |
| bulkDensity | Double | lb/ft3 | Yes | - | Bulk density (for coal seam gas reservoirs) |
:::hint{type="info"}
**Start Date Notes**
For wells with constant fluid and rock properties over time, startDate can be NULL and the properties apply for the entire life of the well.
For wells with changing fluid and rock properties over time, NULL is treated as 1900-01-01T00:00:00+0000 (although non-NULL startDate values are preferred), and subsequent valid datetimes trigger the change in properties in the modeling process.
For formations which change over time, the **name / sourceId** must be consistent for every entry of that formation — otherwise it is assumed the well has multiple formations/producing zones that vary over time.
:::
:::hint{type="info"}
**Name Notes**
It is critical to keep the formation name consistent when adding multiple entries for a formation over time. As allocation factors and fluid properties vary over time, the name is the common link between the records.
:::
:::hint{type="info"}
**Allocation Factor Notes**
If the allocation factor is NULL, it is assumed to be 1 (100%) when the wellbore has a single formation. When the wellbore has multiple formations, a normalization reconciles the sum of allocation factors to 1 using the best data available.
:::
:::hint{type="info"}
**Initial Oil Saturation Notes**
If saturationOilInitial is NULL, it defaults to (1 - saturationWaterInitial).
:::
:::hint{type="info"}
**Initial Gas Saturation Notes**
If saturationGasInitial is NULL, it defaults to 0.0.
:::
***
# Data Integrity Checks
| **Condition** | **Response** |
| -------------------------------------------------------------------- | --------------- |
| Any non-nullable field is NULL or empty | Record Rejected |
| (sourceWellId, sourceWellboreId) does not match an existing wellbore | Row Skipped |
:::hint{type="info"}
**Partial success on bulk ingest**
Rows referencing an unknown wellbore are skipped while the remaining rows are written. The error response names each skipped row, e.g. "Formation with sourceId 'xxx' was skipped: wellbore with sourceWellId 'xxx' and sourceWellboreId 'xxx' was not found". An error response therefore does not mean nothing was written.
:::
***
# Common Error Messages
| **API** | **Scenario** | **Error Response** |
| ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| Add / Upsert formation | Unknown wellbore | Formation with sourceId 'xxx' was skipped: wellbore with sourceWellId 'xxx' and sourceWellboreId 'xxx' was not found |
***
# Data Requirements for Modeling
| **Variable** | **Required for Unconventional Wells?** | **Unconventional Models** | **Required for Conventional Wells?** | **Conventional Models** |
| ----------------------------- | -------------------------------------- | -------------------------------------------------- | ------------------------------------ | ------------------------------------- |
| sourceId | ✅ | | ✅ | |
| sourceWellId | ✅ | | ✅ | |
| sourceWellboreId | ✅ | | ✅ | |
| startDate | ⬜ | Only if properties change | ⬜ | Only if properties change |
| name | ✅ | | ✅ | |
| allocationFactor | ✅ | Composite fluid properties for the well | ✅ | Material Balance |
| compressibilityRock | ✅ | Dynamic drainage volume, PIBF | ✅ | Shut-in radial flow, Material Balance |
| pressureFormationInitialDatum | ✅ | Dynamic drainage volume | ✅ | Material balance |
| temperatureFormationDatum | ✅ | Dynamic drainage volume, Bottomhole pressure, PIBF | ✅ | Shut-in radial flow, Material Balance |
| depth | ✅ | Bottomhole pressure | ✅ | Bottomhole pressure |
| thicknessFormation | ⬜ | | ✅ | Shut-in radial flow |
| porosity | ⬜ | | ✅ | Shut-in radial flow, Material Balance |
| saturationWaterInitial | ⬜ | | ✅ | Shut-in radial flow, Material Balance |
| saturationGasInitial | ⬜ | | ✅ | Material balance |
| saturationOilInitial | ⬜ | | ⬜ | |
| primaryFluidType | ✅ | | ✅ | |
| rsi | ✅ | PVT | ✅ | PVT |
| condensateGasRatio | | | | |
| waterGasRatio | | | | |
| originalGasInPlace | ⬜ | | ✅ | Gas well material balance |
| originalOilInPlace | ⬜ | | ✅ | Oil well material balance |
| volumeAquiferInitial | ⬜ | | ✅ | Aquifer modeling (material balance) |
| fluidGravityApi | ✅ | PVT | ✅ | PVT |
| fluidGravityGas | ✅ | PVT | ✅ | PVT |
| fluidSalinityWater | ✅ | PVT | ✅ | PVT |
| fluidComingledGOR | | | | |
| fluidMolarFracN2 | ✅ | PVT | ✅ | PVT |
| fluidMolarFracCO2 | ✅ | PVT | ✅ | PVT |
| fluidMolarFracH2S | ✅ | PVT | ✅ | PVT |