Skip to main content

Well Header ingestion reference

Well Header ingestion reference​

Use this document when you ingest the WELL_HEADERS share view from a client Snowflake data share into ComboCurve.

1. Purpose​

WELL_HEADERS defines the well master record. It carries the identifiers and attributes that ComboCurve uses to establish the well, scope it correctly, and attach downstream production records.

For this integration pattern, the scheduled job reads the client-provided share view, validates record identity and audit fields, and upserts the current state of each well into ComboCurve.

2. Source object​

Read from the client share view that exposes WELL_HEADERS.

Expected behavior:

  1. Read the full current-state row for each well.
  2. Use the business key to identify the ComboCurve target record.
  3. Use audit fields to detect changes and soft deletes.
  4. Upsert the record into ComboCurve.

3. Business key​

Treat the following fields as the business key for WELL_HEADERS:

  • CHOSEN_ID
  • DATASOURCE
  • PROJECT_NAME

Uniqueness rule:

  • Only one well header record can exist for each (CHOSEN_ID, DATASOURCE, PROJECT_NAME) combination.

4. Project scoping rule​

PROJECT_NAME controls whether the record is project-scoped or company-scoped.

  • For project wells, PROJECT_NAME must be populated.
  • For company-level wells, PROJECT_NAME must be NULL.

Do not normalize a NULL project name into an empty string. Preserve the source convention so record identity remains stable.

5. Required audit fields​

Every inbound record must include the following audit fields:

  • __RECORD_SOURCE
  • __UPDATED_AT
  • __SOFT_DELETE

__CREATED_AT is recommended and should be passed through when available.

5.1 Audit field behavior​

__RECORD_SOURCE​

Use this field for lineage and source tracking. It should identify the client system or organization that produced the record.

__UPDATED_AT​

Use this field as the integration watermark.

Requirements:

  • It must be present on every row.
  • It must change whenever any value in the record changes.
  • When two versions of the same record are encountered, the newest record wins based on __UPDATED_AT.

__SOFT_DELETE​

Use this field to mark a record as deleted.

  • FALSE means the well is active for ingestion.
  • TRUE means ComboCurve should treat the well as deleted.

For delete events, the source should still provide:

  • the business key fields
  • the audit fields

Other non-key attributes can be omitted on delete rows.

6. Minimum required fields for ingestion​

At minimum, the ingestion job should require the following fields to process a WELL_HEADERS row:

6.1 Identity and scope​

  • CHOSEN_ID
  • DATASOURCE
  • PROJECT_NAME

6.2 Audit​

  • __RECORD_SOURCE
  • __UPDATED_AT
  • __SOFT_DELETE
  • __CREATED_AT

All other well attributes are optional from the integration contract perspective, but they can still be ingested when present.

The full example DDL contains a large number of optional well attributes. In practice, it helps to think about them in groups.

7.1 Core identifiers​

Common examples include:

  • WELL_NAME
  • WELL_NUMBER
  • API10
  • API12
  • API14
  • IHS_ID
  • DRILLINGINFO_ID
  • INPT_ID

7.2 Geographic and organizational attributes​

Common examples include:

  • BASIN
  • PLAY
  • SUBPLAY
  • FIELD
  • STATE
  • COUNTY
  • COUNTRY
  • CURRENT_OPERATOR
  • PAD_NAME

7.3 Status and lifecycle dates​

Common examples include:

  • STATUS
  • SPUD_DATE
  • DRILL_START_DATE
  • DRILL_END_DATE
  • COMPLETION_START_DATE
  • COMPLETION_END_DATE
  • FIRST_PROD_DATE
  • TIL

7.4 Well geometry and completion attributes​

Common examples include:

  • LATERAL_LENGTH
  • PERF_LATERAL_LENGTH
  • UPPER_PERFORATION
  • LOWER_PERFORATION
  • TRUE_VERTICAL_DEPTH
  • LANDING_ZONE
  • TARGET_FORMATION

7.5 Custom client-defined attributes​

The schema also supports client-defined extensions such as:

  • CUSTOM_BOOL_*
  • CUSTOM_DATE_*
  • CUSTOM_NUMBER_*
  • CUSTOM_STRING_*

Use these fields when the client needs to pass data that does not map to one of the standard header columns.

8. Validation rules​

Apply these checks before loading into ComboCurve:

8.1 Required-field validation​

Reject the row if any of these are missing:

  • CHOSEN_ID
  • DATASOURCE
  • __RECORD_SOURCE
  • __UPDATED_AT
  • __SOFT_DELETE

For PROJECT_NAME:

  • accept NULL only for company-level wells
  • require a value for project wells

8.2 Key stability validation​

Treat the business key as immutable identity. If a source system changes one of the business key values for an existing well, handle that as a new logical record unless an explicit remapping rule exists.

8.3 Timestamp validation​

Require __UPDATED_AT to be parseable as a timestamp. Use the source value as the authoritative change timestamp.

8.4 Delete validation​

If __SOFT_DELETE = TRUE, the record must still contain enough data to identify the row to remove:

  • CHOSEN_ID
  • DATASOURCE
  • PROJECT_NAME
  • __UPDATED_AT
  • __RECORD_SOURCE
  • __SOFT_DELETE

9. Operational notes​

  • Prefer idempotent loads. Re-reading the same row should not create duplicates.
  • Prefer full-row delivery for updates. Partial updates should only be accepted if the mapping contract explicitly supports them.
  • Preserve the client business key exactly as delivered.
  • Keep raw-source lineage available for troubleshooting.