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

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

So a well tells you which source row located it; a source read gives you that row’s fields.

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

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

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

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

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

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

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

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

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

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.