# observe

Schedules one keyed READ at both the pre and terminal execution checkpoints.

Canonical HTML: <https://determica.com/docs/functions/observe>

- Kind: scalar function
- Category: [Simulation](/docs/category/simulation.md)
- Tags: Program Compiler, Simulate

Schedules one keyed READ at both the pre and terminal execution checkpoints.

## Overload 1: observe(VARCHAR, READ)

```sql
observe(VARCHAR, READ)
```

Schedules one keyed READ at both the pre and terminal execution checkpoints.

- Kind: scalar
- Execution context: Offline
- Behavior: Transform
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `observation_key` (VARCHAR; required; positional) — Non-NULL valid UTF-8 key; the consumed request requires 1-256 bytes and no NUL byte.
- `read` (READ; required; positional) — Non-NULL READ evaluated once before step zero and once at terminal state.

### Returns

Pre-and-terminal OBSERVATION

Returns one OBSERVATION that expands to two points, pre and terminal, when execution requests are compiled.

- `observation` (OBSERVATION)

Pre-and-terminal OBSERVATION. Returns one OBSERVATION that expands to two points, pre and terminal, when execution requests are compiled.

### Examples

_Local SQL · Local_

```sql
WITH actors AS (
  SELECT
    '0x1000000000000000000000000000000000000001'::ADDRESS AS sender,
    '0x2000000000000000000000000000000000000002'::ADDRESS AS writer
),
runnable_candidate AS (
  SELECT
    'pass'::VARCHAR AS candidate_key,
    program([execute_call(
      sender,
      writer,
      '0x000000000000000000000000000000000000000000000000000000000000002a'::BYTES,
      1::UINT256,
      100000::UBIGINT
    )]) AS program,
    [observe('writer.slot.checkpoint'::VARCHAR, storage_at(writer, '0x0000000000000000000000000000000000000000000000000000000000000000'::BYTES32))] AS observations
  FROM actors
)
SELECT
  candidate_key,
  len(observations)::INTEGER AS scheduled_observations,
  observations[1] IS NOT NULL AS scheduled
FROM runnable_candidate;
-- => [{"candidate_key":"pass","scheduled_observations":1,"scheduled":"true"}]
```

## Overload 2: observe(VARCHAR, READ, VARCHAR)

```sql
observe(VARCHAR, READ, VARCHAR)
```

Schedules one keyed READ at exactly the pre or terminal execution checkpoint.

- Kind: scalar
- Execution context: Offline
- Behavior: Transform
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `observation_key` (VARCHAR; required; positional) — Non-NULL valid UTF-8 key; the consumed request requires 1-256 bytes and no NUL byte.
- `read` (READ; required; positional) — Non-NULL READ evaluated at the selected checkpoint.
- `checkpoint` (VARCHAR; required; positional) — Case-insensitive selector; only pre or terminal is accepted.

### Returns

Single-checkpoint OBSERVATION

Returns one OBSERVATION that expands to the selected pre or terminal point.

- `observation` (OBSERVATION)

Single-checkpoint OBSERVATION. Returns one OBSERVATION that expands to the selected pre or terminal point.

### Examples

_Local SQL · Local_

```sql
WITH actors AS (
  SELECT
    '0x1000000000000000000000000000000000000001'::ADDRESS AS sender,
    '0x2000000000000000000000000000000000000002'::ADDRESS AS writer
),
runnable_candidate AS (
  SELECT
    'pass'::VARCHAR AS candidate_key,
    program([execute_call(
      sender,
      writer,
      '0x000000000000000000000000000000000000000000000000000000000000002a'::BYTES,
      1::UINT256,
      100000::UBIGINT
    )]) AS program,
    [observe('writer.slot.checkpoint'::VARCHAR, storage_at(writer, '0x0000000000000000000000000000000000000000000000000000000000000000'::BYTES32), 'pre'::VARCHAR)] AS observations
  FROM actors
)
SELECT
  candidate_key,
  len(observations)::INTEGER AS scheduled_observations,
  observations[1] IS NOT NULL AS scheduled
FROM runnable_candidate;
-- => [{"candidate_key":"pass","scheduled_observations":1,"scheduled":"true"}]
```

## Guidance

### Request validation

Key length, NUL bytes, and duplicate points are validated when the observation list is consumed. A request may contain at most 256 expanded points across all OBSERVATION values.

## Related functions

- [assume_native_balance](/docs/functions/assume_native_balance.md) — See Also
- [call_context](/docs/functions/call_context.md) — See Also
- [execute_call](/docs/functions/execute_call.md) — See Also
- [program](/docs/functions/program.md) — See Also
- [run](/docs/functions/run.md) — See Also