The __admin Dataset
The __admin dataset is a special, read-only dataset that reflects the state of current deployed environment.
It is currently considered "internal" to the Island team, and used by features such as the Command Line tool.
The __admin dataset can only be reached via IAM authentication; it is forbidden on the public (Cognito-authenticated) endpoint.
The easiest way to reach out to the __admin dataset is to use the Gateway Lambda, but it is also
reachable using GraphQL or REST on the iam endpoint.
The following schemas are available in the __admin dataset:
| Schema | Description | Notes |
|---|---|---|
Environment | The current environment | Only one Environment is present per deployed Depot environment, so "listing environments" will return the one available environment. |
Dataset | The datasets available in the environment | |
SchemaNamingMapping | A mapping between logical "depot" names and the deployed "sql" names for each schema | only on Snowflake and Postgres locations |
Store | The stores available in the environment | deprecated? obsolete? |
Transaction | The transactions currently active in the environment | deprecated? obsolete? |
Location | The Locations currently used in the environment | |
Executors | The Executors currently available in the environment |
The Depot schema describing the contents of these schemas is available in the stage-depot-platform repository,
under the name Admin.yml. It broadly matches the input descriptions used by a Service in Depot CDK.
The regular Depot "expand" semantics are available; it is possible to expand location on a Dataset to get the
characteristics of the underlying location; or to expand executor on a Location to get the corresponding Executor
characteristics. Or to expand dataset, dataset.location and dataset.location.executor from a Deployed Schema to
get, for a given schema, the SQL names, the JDBC endpoint and location of credentials in a single round-trip.
SchemaNamingMapping.members
Each SchemaNamingMapping row's members map has one entry per Depot member — a declared or inherited
property, or a metadata pseudo-member such as id or version — keyed by member name. Every entry states,
for that member: its Depot type (the composite type descriptor); kind (object, struct, scalar,
map, array, ref, ... — an open set); nature (property for a declared or inherited property,
metadata for a pseudo-member; also open); resolved required (never the configuration's sparse form —
an unset default is resolved and emitted, not left for the consumer to re-apply); description; effective
layout; decimal precision / scale; temporal resolution; and versioned for a ref. A member that
occupies exactly one physical column carries a name; one that is physically flattened carries a nested
members map of the same shape instead. Flattening that nesting with dot-joined keys reproduces
properties exactly.
members supersedes properties — it covers the same ground and adds the type facts. properties is
retained because existing consumers depend on it; prefer members for anything new.
Enum-valued entries (kind, nature, layout, resolution) render lowercase. type is the one
exception: for a named schema it is that schema's qualified name, in its own casing — this repo already
uses the word for exactly this concept, in Object schema:
"Objects may contain properties, transients and links, these member types share the same namespace."
The metadata entries (id, schema, version, created, updated, and — where deployed — hash and
__transactionId) are not io.basestar.schema.Member instances; basestar keeps them outside that
hierarchy. nature: metadata marks them explicitly rather than leaving that to be inferred from the name.
Dataset.namespace
namespace on a Dataset is projectable, and carries the full schema descriptors for every schema
deployed in that dataset.
It can reach several megabytes on a large dataset — one measured at 3.45 MB across 560 schemas — against
Lambda's 6 MB synchronous response cap, which applies on every hop a request crosses. Projecting
namespace on a large dataset is a real risk of exceeding that cap, not merely a slow path. namespace
cannot be projected into a single schema's descriptor, so there is no way to ask for less once one is
needed; SchemaNamingMapping, scoped to one (dataset, schema) pair, is
the way to get type facts for a single schema without pulling the whole dataset's descriptors.