Defining Queries

Queries are declared under the queries: key in .queries.causet files.

Basic structure

queries:
  shows_for_followed_artists:
    from: artist_show_directory
    input:
      user_id: { type: string, required: true }
    fields:
      - artist_show_directory.*
    where:
      user_following.user_id: { eq: input.user_id }
    order_by:
      date: asc
    limit: 50

Top-level fields

Field	Required	Description
`from`	Yes	Primary projection table name
`input`	No	Named parameters from the caller
`fields`	No	Column selection; defaults to `*`
`where`	No	Filter conditions
`joins`	No	Join other projection tables
`order_by`	No	Sort order
`limit`	No	Max rows (always set one in production)
`distinct`	No	`true` for `SELECT DISTINCT`
`group_by`	No	Required with `aggregate`
`aggregate`	No	Aggregate functions
`cache_ttl_seconds`	No	Redis result cache TTL

`from`

Must match a target.table from a declared projection:

from: artist_leaderboard

The query service runs against this table in the fork’s PostgreSQL schema.

`input`

Typed parameters the caller provides in the request body:

input:
  user_id:    { type: string,  required: true  }
  artist_id:  { type: string,  required: false }
  limit:      { type: int,     required: false }

Reference inputs in where as input.user_id. Missing required parameters return 400 before SQL executes.

Supported types: string, int, integer, boolean, and types matching projection column types.

`fields`

Column selection for the response:

fields:
  - artist_show_directory.show_id
  - artist_show_directory.title
  - artist_show_directory.venue

Use table.* to select all columns from a table. Omit internal columns you don’t want exposed to callers.

Execution endpoint

POST /v1/platforms/{platform}/applications/{app}/forks/{fork}/queries/{query_name}

Request body:

{
  "params": {
    "user_id": "user-123"
  }
}

Response: JSON array of row objects.

See Defining Queries for auth patterns and control-plane integration.

Next steps

Filters & Joins — where, joins, order_by, limit
Aggregates — counts, sums, coalesce_zero
Caching — Redis result cache

Concept Filters & Joins