Subscriptions

Subscriptions deliver real-time updates when records are created, updated, or deleted. The server pushes events over WebSocket instead of requiring polling.

Connect to /graphql using the graphql-ws protocol.

#Basic Subscription

subscription {
  xyzStatusphereStatusCreated {
    uri
    status
    createdAt
  }
}

#Field Selection

Request only the fields you need:

subscription {
  xyzStatusphereStatusCreated {
    status
  }
}

Response:

{
  "data": {
    "xyzStatusphereStatusCreated": {
      "status": "🚀"
    }
  }
}

#Named Subscription

subscription OnNewStatus {
  xyzStatusphereStatusCreated {
    uri
    status
    actorHandle
  }
}

#Subscription Types

Each collection has three subscription fields:

• {collection}Created - Fires when a new record is created
• {collection}Updated - Fires when a record is updated
• {collection}Deleted - Fires when a record is deleted

#Examples

# New status created
subscription {
  xyzStatusphereStatusCreated {
    uri
    status
  }
}

# Status updated
subscription {
  xyzStatusphereStatusUpdated {
    uri
    status
  }
}

# Status deleted
subscription {
  xyzStatusphereStatusDeleted {
    uri
  }
}

#With Joins

Subscriptions support joins like queries:

subscription {
  xyzStatusphereStatusCreated {
    uri
    status
    appBskyActorProfileByDid {
      displayName
      avatar {
        url
      }
    }
  }
}

Response:

{
  "data": {
    "xyzStatusphereStatusCreated": {
      "uri": "at://did:plc:abc123/xyz.statusphere.status/3m4vk4wi",
      "status": "🎉 Just shipped!",
      "appBskyActorProfileByDid": {
        "displayName": "Alice",
        "avatar": {
          "url": "https://cdn.bsky.app/img/avatar/plain/did:plc:abc123/bafyrei..."
        }
      }
    }
  }
}

#WebSocket Protocol

#1. Connect

ws://localhost:8080/graphql          # Local development
wss://quickslice.example.com/graphql  # Production

#2. Initialize

{
  "type": "connection_init"
}

#3. Subscribe

{
  "id": "1",
  "type": "subscribe",
  "payload": {
    "query": "subscription { xyzStatusphereStatusCreated { uri status } }"
  }
}

#4. Receive Events

{
  "id": "1",
  "type": "next",
  "payload": {
    "data": {
      "xyzStatusphereStatusCreated": {
        "uri": "at://...",
        "status": "Hello!"
      }
    }
  }
}

#5. Unsubscribe

{
  "id": "1",
  "type": "complete"
}