Your First Query

Continuing the concert app: queries are named, parameterized reads over projection tables — no hand-written SQL. The query service runs them with per-fork tenant isolation.

Project: Concert app from causet init. Open queries/follow.queries.causet.

Prerequisite: Your First Projection — user_following and artist_show_directory.

The query we need

Users follow artists. Artists announce shows. The app should answer: “What upcoming shows are on for artists I follow?”

That requires joining user_following to artist_show_directory on artist_id.

# queries/follow.queries.causet
queries:
  shows_for_followed_artists:
    from: artist_show_directory
    input:
      user_id: { type: string, required: true }
    joins:
      user_following:
        on:
          artist_show_directory.artist_id: user_following.artist_id
        fields:
          - user_following.user_id
    fields:
      - artist_show_directory.*
    where:
      user_following.user_id: { eq: input.user_id }
    order_by:
      date: asc
    limit: 50

Field	Purpose
`from`	Primary projection table
`input`	Caller parameters
`joins`	Join to `user_following` on `artist_id`
`where`	Filter to the requesting user
`order_by` / `limit`	Sort by show date, cap results

Recompile and deploy after adding queries.

Execute via CLI

After following Pearl Jam and announcing the Brooklyn show:

causet query shows_for_followed_artists \
  --fork main \
  --param user_id=user-1

Example response:

{
  "rows": [
    {
      "show_id": "show-pj-brooklyn-2026",
      "artist_id": "artist-pearl-jam",
      "title": "Pearl Jam - Dark Matter Tour",
      "venue": "Barclays Center",
      "date": "2026-09-15"
    }
  ]
}

Queries vs entity inspect

Tool	Use when
`causet query`	Lists, joins, aggregates over projections
`causet inspect entity`	Current snapshot of one entity on the write side

“Shows for followed artists” lives in projections — not entity snapshots.

Concert app so far

concert-app/
  app.causet
  states/       user.state.causet, artist.state.causet
  events/       follow.events.causet, show.events.causet
  actions/      follow.actions.causet, show.actions.causet
  projections/  follow.projections.causet
  queries/      follow.queries.causet

Next steps

Your First Relationship — graph edge for follows
Queries — filters, aggregates, best practices

Your First Projection Your First Relationship