Source rows and project wells
Your project can hold wells, and it can read sources — for example a SQL table of wells your organisation keeps upstream. They are different things:
- A source row is a row of the upstream table at one exact revision. Reading a source (Read a connected source in Python) returns the table’s own fields and creates nothing in the project.
- A project well is something the project knows and shares under its own rules. A well can be located by a source row; it then carries a reference to that row, not a copy of the table.
The fields each view gives you
Section titled “The fields each view gives you”| View | Call | Fields |
|---|---|---|
| Source rows, mapped | client.source(id).read().to_frame() | well_id, name, operator (when mapped), x, y, depth (when mapped); frame.attrs: crs, revision, sha256, profile, source_id |
| Source rows, original | read().to_frame(original=True) or records(original=True) | Every column of the table, with its values exactly as returned (large integers, decimal and date text kept as given) |
| Source shape | client.source(id).describe() | Columns and their types, the mapping, the CRS, the row count, nulls per mapped field — no rows |
| Project wells | client.wells().to_frame() | name, entity_id, x, y, crs, and the origin reference: source_asset_id, source_revision, source_row |
| Project wells with their rows | client.wells().with_source(columns=[...]) | The project-wells fields, source_state, source_reason, and source.<column> for each original column asked for (all when columns is left out) |
So a well tells you which source row located it; a source read gives you that row’s fields.
From a well to its source row
Section titled “From a well to its source row”A well imported from a table (Import wells from a table) is located by a row of the
copy the import kept. wells.with_source(columns=[...]) reads those copies — once each, under the copy’s own
permission check, not your source selections — and returns one row per well, in the order wells() listed them:
source_state | Meaning |
|---|---|
joined | The source.<column> values are that row’s, from the kept copy (a later change to the table does not change them) |
no origin | No source row you may read locates this well: none was recorded, or the copy is not one you may read. The server shows neither, so the two look the same |
no origin (location item) | The position comes from a location item, such as a corrected position or an uploaded position file, not from a row of a source table; source_reason says so |
not readable | The well names a copy that cannot be read now: it was withdrawn, it is under review, or it is no longer yours to read. source_reason says which |
The row is the one that supplies the location wells() returned: when several copies locate a well, the newest
one you may read. A copy whose bytes do not match the revision the well names raises source-checksum-mismatch, and
nothing is returned. On the command line, ophiolite wells list --with-source --column NAME --json gives each well a
source object with state, reason and row.
Whose sources you see
Section titled “Whose sources you see”You list and read the source selections you made. A selection another member of the project made is not listed and cannot be read with your key, even in the same project. An access key with read scope is enough.
What a read costs
Section titled “What a read costs”read() and describe() each read the whole table once from the upstream system and verify it; describe()
keeps only its shape. A table is read up to the server’s bounds (100,000 rows, 64 MiB); the SDK also stops at its
own response bound (48 MiB, about 36 MiB of table data once encoded).
When the SDK refuses
Section titled “When the SDK refuses”Each refusal names a code. Codes in capitals come from the server, with its own message and remedy; the others are raised by the SDK after it received an answer, or before it sent anything.
source-not-found
Section titled “source-not-found”No selection with this id is yours in this project. List yours with client.sources(); a selection another member
made is not listed.
source-not-supported
Section titled “source-not-supported”This release reads SQL well tables (sql-wells/1) only; other kinds are listed but refused before any request is
sent. Nothing was read.
source-checksum-mismatch
Section titled “source-checksum-mismatch”The payload did not match its manifest checksum, or the revision did not name the payload. Read it again; if it repeats, report the request id. The check guards transport and decoding; the server computed both values.
source-revision-differs
Section titled “source-revision-differs”You passed expect_revision and the server returned another revision. No rows were given. The error carries the
expected and actual revisions: decide whether the new revision is the one you want, then read again.
source-detached
Section titled “source-detached”The server answered SOURCE_DETACHED: the selection was removed from the project. It is not retried. Selecting
the same source again does not bring it back; a project administrator can resume it.
capacity-exceeded
Section titled “capacity-exceeded”The answer was larger than the SDK’s response bound; the message states the bound in bytes. Ask for an approved view of the table with fewer rows or columns.
Server refusals
Section titled “Server refusals”SOURCE_NEEDS_REVIEW (the mapping needs review, the table changed at an exact revision, or the table is over the
server’s bound — the message says which), SOURCE_REVISION_UNAVAILABLE (the upstream table changed and the
revision held can no longer be read), SOURCE_ACCESS_DENIED (the upstream system refused the owner’s sign-in),
SOURCE_OFFLINE and SOURCE_PENDING (retried, then reported as busy), SOURCE_MISSING and SOURCE_DELETED.
Their remedies are on the errors reference.
