Queries & Relationships

Errors from the queries: block’s runtime contract, and from relationships: definitions.

6 error codes in this section.

Query Runtime-Contract

`VERR_QUERY_WINDOW_ALLOWED_INVALID`

window.allowed value has invalid format or misaligned bucket. A window.allowed value is not a recognised interval format, or is not a whole multiple of the projection’s bucket interval.

Impact: Queries for that window return empty or stale results.

✗ Won't compile

# projection bucket.interval: 1h
window:
  allowed: [5m, 1h]   # 5m not a multiple of 1h

✓ Fixed

window:
  allowed: [1h, 2h, 24h]   # all multiples of 1h

`VERR_QUERY_WINDOW_VALUE_INVALID`

window.allowed contains unsupported runtime value. A window.allowed value is not in the set the query-service runtime actually supports: 1h, 24h, 7d. Unsupported values are silently ignored, returning empty results for those windows.

Impact: Frontend receives no data for the unsupported window; silent user-facing failure.

✗ Won't compile

window:
  allowed: [30m, 1h, 24h, 7d]   # 30m not supported by runtime

✓ Fixed

window:
  allowed: [1h, 24h, 7d]   # supported runtime values only

`VERR_QUERY_INPUT_PARAM_UNDECLARED`

Query references undeclared input parameter. A WHERE clause or limit_input references input.X but X is not declared in the query’s input: block. Runtime silently passes null, returning no rows or performing a full table scan.

Impact: Query silently returns empty results or scans the full table.

✗ Won't compile

where:
  venue_id:
    eq: "input.venue_id"   # venue_id not in input:
input:
  limit: { type: integer }

✓ Fixed

where:
  venue_id:
    eq: "input.venue_id"
input:
  venue_id: { type: string, required: true }
  limit: { type: integer }

`VERR_QUERY_OPERATOR_TYPE_MISMATCH`

Query WHERE operator incompatible with column type. A WHERE operator is incompatible with the column’s declared type. Geo operators (within_radius, within_box, distance_lte) require GEOGRAPHY_POINT; text operators (contains, starts_with, ilike, like) require TEXT or STRING.

Impact: Query fails at runtime with a Postgres type error.

✗ Won't compile

# venue_id is TEXT
where:
  venue_id:
    within_radius:    # geo op on TEXT field
      center: "input.point"
      radius_m: 1000

✓ Fixed

# Use a GEOGRAPHY_POINT field for geo operators:
# fields.location: GEOGRAPHY_POINT
where:
  location:
    within_radius:
      center: "input.point"
      radius_m: 1000

Relationships

`VERR_RELATIONSHIP_STREAM_NOT_FOUND`

Relationship from/to state not found. A relationship’s from: or to: value does not match any state defined in the spec. The generated relationship stream references an entity that does not exist.

Impact: Relationship stream cannot be generated; emit events are dead.

✗ Won't compile

relationships:
  user_follows_venue:
    from: user    # not in state:
    to: venue     # not in state:
    cardinality: many_to_many

✓ Fixed

state:
  user: { ... }
  venue: { ... }
relationships:
  user_follows_venue:
    from: user
    to: venue
    cardinality: many_to_many

`VERR_RELATIONSHIP_EMIT_EVENT_DUPLICATE`

Duplicate emit_events name across relationships. Two or more relationships declare the same event name in their emit_events block. Duplicate names cause the projection worker to route events to multiple relationship streams simultaneously, producing phantom rows.

Impact: Both relationships receive every instance of the event; rows are duplicated.

✗ Won't compile

relationships:
  user_follows_venue:
    emit_events:
      created: UserFollowedVenue
  user_bookmarks_venue:
    emit_events:
      created: UserFollowedVenue   # duplicate!

✓ Fixed

relationships:
  user_follows_venue:
    emit_events:
      created: UserFollowedVenue
  user_bookmarks_venue:
    emit_events:
      created: UserBookmarkedVenue   # unique name

Projections Listeners