Skip to content

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.
ViewCallFields
Source rows, mappedclient.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, originalread().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 shapeclient.source(id).describe()Columns and their types, the mapping, the CRS, the row count, nulls per mapped field — no rows
Project wellsclient.wells().to_frame()name, entity_id, x, y, crs, and the origin reference: source_asset_id, source_revision, source_row
Project wells with their rowsclient.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.

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_stateMeaning
joinedThe source.<column> values are that row’s, from the kept copy (a later change to the table does not change them)
no originNo 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 readableThe 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.

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.

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).

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.

No selection with this id is yours in this project. List yours with client.sources(); a selection another member made is not listed.

This release reads SQL well tables (sql-wells/1) only; other kinds are listed but refused before any request is sent. Nothing was read.

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.

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.

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.

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.

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.