inspect
Need entity details? Retrieve one entity, a batch, or an entire collection by type and reference, with compact or full output.
Instructions
Inspect EXACTLY one entity by reference and kind, a homogeneous
BATCH when reference is a list — or the whole COLLECTION at a kind
when reference is omitted / None.
A clean point-lookup: no fusion / ranking / cypher, and no bundled
memories. Use search instead when you want an entity surfaced in
context (with related memories and ranked neighbours).
Collection (DEV-1667): omit reference (or pass None / [])
to list a whole kind. entity_type="model" lists all models grouped
by datasource (compact=True: one terse line per model; compact=False:
the full per-model tables). entity_type="datasource" lists all
datasources. Only model / datasource support the collection
view; other kinds raise. This subsumes models_summary /
list_datasources.
Batch (DEV-1612): pass a list of references that all share the one
entity_type. Returns one rendered block per id, in input order,
each echoing its resolved canonical id (a ## <canonical> header in
markdown; a JSON array under format="json"). Per-id resolution
errors are isolated — one bad id does not sink the batch (in JSON it
becomes a {"reference": ..., "error": ...} element). A single
str keeps its byte-for-byte single output; a one-element list is
still batch-framed.
Args:
reference: The entity reference, or a list of references (batch).
Accepts canonical forms (mydb, mydb.orders,
mydb.orders.amount), bare names, join paths
(orders.customers.region → resolved to the owning model),
and memory:<id> for memories. Normalised via the shared
resolver; the normalised canonical id is echoed in the JSON
shape.
entity_type: REQUIRED. One of datasource, model,
column, measure, aggregation, memory.
Disambiguates the 3-part canonical collision (a name
shared by, e.g., a column and an aggregation) and asserts
the resolved kind — a mismatch returns a detailed error.
compact: When true (default): description-only for
column/measure/aggregation/datasource/memory; for
entity_type="model" a cheap schema skeleton (column /
measure / aggregation names + join targets, zero DB calls).
False returns the full render (and, for the datasource kind,
a per-model skeleton for each visible model).
format: "markdown" (default) or "json".
num_rows: Sample-data rows for entity_type="model". Ignored
(with a warning) for other kinds.
show_sql: Include generated SQL for entity_type="model".
Ignored (with a warning) for datasource/memory; a silent
no-op for column/measure/aggregation.
sections: Section subset for entity_type="model". Ignored
(with a warning) for other kinds.
descriptions_max_chars: Truncate description fields to this many
characters. Applies to every kind.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | markdown | |
| compact | No | ||
| num_rows | No | ||
| sections | No | ||
| show_sql | No | ||
| reference | No | ||
| entity_type | Yes | ||
| descriptions_max_chars | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |