Newcomers to Texas oil and gas data usually arrive with a mental model that goes: a company drills a well, the well produces oil, therefore there is a row somewhere that says how much oil that well produced. That row does not exist. Understanding why is the single highest-leverage thing you can learn about this data.
Three different things with three different keys
A wellbore is a hole in the ground. It is identified by an API number. The Full Wellbore Database has one root record per wellbore, and it is the only place where "hole in the ground" is the unit of the row.
A field is a named accumulation of hydrocarbons that the RRC has formally designated, with rules attached — spacing, allowables, density. It is identified by an eight-digit field number and looked up in the Oil & Gas Field Names and Numbers file. Field names are wonderfully idiosyncratic ("SPRABERRY (TREND AREA)", "WILDCAT") and the number, not the name, is the key. A field is a regulatory object, not a geological one: two fields can be the same rock, and the same field can span counties and districts.
A lease is the RRC's unit of production accounting. It is identified by a district number plus a five-digit lease number, and it is where an operator's production report lands. A lease can have one well or two hundred. It is not the same thing as the mineral lease a landman negotiated, though it usually descends from one.
Three objects, three keys, and no single column that ties a production number to a hole in the ground.
Oil is counted by lease; gas is counted by well
This is the rule that surprises everyone.
For oil, the reporting unit is the lease. An operator files one production report for the lease, covering all the oil wells on it, and the RRC records lease-level volumes. If a lease has forty producing oil wells, there is one production row per month, not forty. There is no official monthly per-well oil volume in this data. Anything claiming to have one is allocating — dividing lease volumes across wells by some model — and you should know whose model it is.
For gas, the reporting unit is the well. Each gas well gets its own identifier (a district plus a gas well number, often called the RRC ID or gas ID), and production is recorded against it. So gas is effectively per-well, using a key that is not the API number.
Every production row in the PDQ dataset therefore carries an oil_gas_code, O
or G, and a lease_no whose meaning depends on it. In the oil case, lease_no
is an oil lease. In the gas case, the same column holds the gas well's identifier
and there is a separate gas_well_no column. Two different grains sharing a
column name in one table is exactly the kind of thing that produces confidently
wrong analysis.
The practical consequence:
-- WRONG: mixes lease-grain oil rows with well-grain gas rows
SELECT lease_no, sum(lease_oil_prod_vol)
FROM texas.pdq_og_lease_cycle
GROUP BY lease_no;
-- RIGHT: the key includes the oil/gas code and the district
SELECT oil_gas_code, district_no, lease_no, sum(lease_oil_prod_vol)
FROM texas.pdq_og_lease_cycle
WHERE oil_gas_code = 'O'
GROUP BY oil_gas_code, district_no, lease_no;
Lease numbers are only unique within a district and within the oil/gas schedule.
Grouping on lease_no alone silently merges unrelated leases across the state.
The wellbore file remembers both identities
The Full Wellbore Database's completion record (record type 02) carries both
sides of this at once. For each completion on a wellbore it stores an oil schedule
identity — an oil code, oil district, five-digit oil lease number, and oil well
number — and a gas schedule identity — a gas district and gas well number. A
single wellbore can have completions on both schedules, because it can be
completed in more than one interval.
That record is the bridge. It is how you get from "this hole in the ground" to "these production reporting units", and it is why the wellbore file is worth the effort of parsing a 28-record-type fixed-width format.
The PDQ dataset ships the same bridge in a friendlier shape. Its well completion
table carries oil_gas_code, district_no, lease_no, well_no alongside
api_county_code and api_unique_no — production keys and API keys in one row.
If you only ever learn one join in Texas data, learn that one.
One well, several completions, several leases
A wellbore is not permanently attached to one lease. Over a forty-year life it can be recompleted into a different formation, reassigned to a different field, transferred to a different operator, and moved onto a different lease number. Every one of those events leaves a trace in a different dataset, and none of them change the API number.
Conversely, a lease's well count changes constantly as wells are added, plugged, or moved off. "Production per well" computed by dividing this month's lease volume by today's well count is a ratio of two numbers measured at different times.
Fields: the third axis
Field assignment is where regulatory and geological reality diverge most visibly.
A well is permitted to a field, completed into a field, and produces on a field.
Those three field numbers can all differ. The permit records the operator's
intent; the completion records what they found; the production schedule records
what the RRC subsequently agreed to. Field transfers are common enough that the
permit application type list includes a dedicated FIELD-TRANSFER code.
WILDCAT deserves a special note. It is the field name used when a well is
drilled outside any established field. It is not one place — wildcat wells are
scattered across the entire state — and a naive "top fields by well count" query
will put WILDCAT at the top and tell you nothing. Filter it out or treat it as a
category, never as a location.
The annual field tables (oil and gas) give you field-level aggregates directly: report year, district, field name and number, county, discovery date, well counts, and annual volumes. When your question is about fields rather than wells, they are far cheaper than aggregating the monthly lease data yourself.
A worked mental model
Picture a section of West Texas.
- The rock is the Spraberry. The RRC calls the regulatory unit
SPRABERRY (TREND AREA)and gives it a field number. - An operator holds acreage and the RRC assigns it oil lease 12345 in district 08. Fourteen wells sit on it.
- One of those wells is API 42-329-31234. It has a wellbore record, a permit, a completion report and a stack of casing and perforation child records.
- Every month the operator files one production report for lease 08-12345. That is the only oil volume in the public record. Nothing in it is attributable to 42-329-31234 by the RRC.
- Two of the fourteen wells also make enough gas to be carried on the gas schedule. Those two have their own gas well identifiers and their own monthly gas rows.
Every question you can ask about this section has to be phrased in one of those grains. "How much oil did that well make?" has no answer in the public data. "How much oil did that lease make, and how many wells were on it?" has an exact one.
What to take away
- Wellbore, lease and field are three distinct objects with three distinct keys.
- Oil volumes are lease-grain. Gas volumes are gas-well-grain. Neither is API-grain.
- Lease numbers need district and oil/gas code to be unique.
- The wellbore completion record and the PDQ well completion table are the two bridges between production keys and API numbers.
- Field assignment can differ between permit, completion and production, and WILDCAT is a status, not a place.
Next: the API number itself — how it is built, why the same well appears under several of them, and how to join on it without losing rows.