Wellbore Formation

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.

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.

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 WellWell table
sourceWellboreId	String	-	No	-	Must match the sourceId of a record in the WellboreWellbore 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)

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.

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.

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.

Initial Oil Saturation Notes

If saturationOilInitial is NULL, it defaults to (1 - saturationWaterInitial).

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

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