Wellbore Plunger
The Wellbore Plunger table describes plungers installed in the well, used for plunger lift modeling. A plunger belongs to a tubing string — sourceTubingId must match an existing Wellbore TubingWellbore Tubing record.
The unique constraint on plunger entries is sourceTubingId + sourceId.
The tubing string referenced by sourceTubingId must be loaded before adding a plunger to it.
Variable | Data Type | Unit of Measure | Is Nullable? | Default Value | Description |
|---|---|---|---|---|---|
sourceId | String | - | No | - | Unique identifier of the plunger, to enable upserts |
sourceWellId | String | - | No | - | Source ID for the well. Must match the sourceId of a record in the WellWell table. |
sourceWellboreId | String | - | No | - | Source ID for the wellbore. Must match the sourceId of a record in the WellboreWellbore table. |
sourceTubingId | String | - | No | - | Source ID of the tubing string in which the plunger is installed. Must match the sourceId of a Wellbore TubingWellbore Tubing record. |
runDate | Datetime Offset | - | No | - | Date the plunger was installed. Datetime offset (with timezone) in ISO 8601 format. Example: 2022-09-27T16:28:37+0000 |
pullDate | Datetime Offset | - | Yes | - | Date the plunger was removed from the well. Datetime offset (with timezone) in ISO 8601 format. |
make | String | - | No | - | Manufacturer of the plunger installed |
model | String | - | No | - | Manufacturer-assigned model of the plunger |
type | String | - | No | - | Source-provided plunger classification in the well (e.g., conventional, bypass, pad, free cycle, etc.) |
bumperSpringDepth | Double | ft | No | - | Measured depth of the bumper spring installation — the landing depth where the plunger comes to rest at the bottom of the well |
Data Integrity Checks
Condition | Response |
|---|---|
Any non-nullable field is NULL or empty | Record Rejected |
(sourceWellId, sourceWellboreId, sourceTubingId) does not match an existing tubing | Row Skipped |
Partial success on bulk ingest
Rows referencing an unknown tubing string are skipped while the remaining rows are written. The error response names each skipped row. An error response therefore does not mean nothing was written.
Common Error Messages
API | Scenario | Error Response |
|---|---|---|
Add / Upsert plunger | Unknown tubing | WellborePlunger with sourceId 'xxx' was skipped: tubing with sourceWellId 'xxx' and sourceWellboreId 'xxx' and sourceTubingId 'xxx' was not found |